chore: restore product scaffold to rollback baseline

docs/architecture/desktop-ptt-architecture.md

@@ -0,0 +1,43 @@
+# Chanora Desktop Push-to-Talk Architecture
+
+**Document status:** DV meeting baseline candidate  
+**Date:** 2026-05-29  
+**Related documents:** `docs/architecture/sad.md`, `docs/architecture/sdd.md`, `docs/release/dv-waiver-register.md`
+
+## 1. Purpose
+
+This document records the desktop push-to-talk architecture advertised by the README and connects it to the SWE.2/SWE.3 baselines.
+
+## 2. Architecture Summary
+
+Desktop PTT is implemented as a platform-capability feature. The application must detect the active backend, expose the resulting `PttCapabilityLevel`, and avoid claiming global PTT support when the runtime falls back to focused-input behavior.
+
+## 3. Platform Backends
+
+| Platform | Backend strategy | Release claim rule |
+|---|---|---|
+| Windows | Raw Input first, low-level keyboard hook fallback, focused fallback if unavailable | Claim only the detected runtime capability |
+| macOS | Event Tap where permission and OS policy allow; focused fallback otherwise | Claim Global PTT only with permission/backend evidence |
+| Linux | Freedesktop GlobalShortcuts portal where available; focused fallback otherwise | State portal/fallback behavior clearly |
+
+## 4. Safety Rules
+
+| Rule | Purpose |
+|---|---|
+| Missed-key-up watchdog clears transmit after timeout | Prevents stuck transmit when an OS suppresses key-up |
+| Capability is surfaced to UI and release record | Prevents over-claiming platform support |
+| Mouse side-button support is platform-dependent | Avoids blocking release on Linux portal limitations |
+| Focused fallback remains available | Preserves usable PTT when global backends are unavailable |
+
+## 5. Verification Handoff
+
+| Evidence | Required result |
+|---|---|
+| Per-platform smoke | Active backend and fallback behavior recorded |
+| UI inspection | PTT capability badge matches runtime backend |
+| Release readiness | Release notes mirror actual capability per platform |
+| Safety test | Watchdog prevents stuck transmit after missed key-up |
+
+## 6. DV Conclusion
+
+The desktop PTT architecture is documented for DV navigation. Public release claims still require per-platform PTT evidence attached to the release-readiness record.

docs/architecture/sad.md

@@ -0,0 +1,186 @@
+# Chanora Software Architecture Description
+
+**Lifecycle:** SWE.2 Software Architectural Design  
+**Document status:** DV meeting baseline candidate  
+**Date:** 2026-05-29  
+**Direct upstream source:** `docs/srs.md`  
+**Related system allocation:** `docs/sysdes.md`
+
+## 1. Purpose
+
+This Software Architecture Description defines Chanora's software architecture for DV review. It bridges SRS software requirements to SWE.3 detailed design and to SWE.5/SWE.6 verification planning.
+
+This baseline captures the architecture visible in the current repository. It is sufficient for DV traceability review, while deeper per-module algorithms remain in `docs/architecture/sdd.md` and source-level design.
+
+## 2. Architectural Scope
+
+Chanora is a Flutter application with a Rust core. Flutter owns the user-facing shell, Material 3 widgets, localization, permission UX, and platform service presentation. Rust owns connection orchestration, protocol isolation, audio processing, storage coordination, diagnostics, server resolution, prefetch policy, and bridge DTOs.
+
+## 3. Upstream SRS Allocation
+
+| SRS group | Architectural allocation |
+|---|---|
+| SRS-003, SRS-008 through SRS-016 | Cross-platform app shell, Flutter UI, Rust core, platform adapters |
+| SRS-017 through SRS-030 | Flutter UI, state presentation, connection and voice controls |
+| SRS-031 through SRS-035 | Bridge layer and typed DTO boundary |
+| SRS-036 through SRS-043 | Rust core connection lifecycle and state behavior |
+| SRS-044 through SRS-053 | Protocol adapter and TeamSpeak-compatible server boundary |
+| SRS-054 through SRS-061 | State synchronization and replay/reducer verification hooks |
+| SRS-062 through SRS-083 | Audio subsystem, DSP, codec, PTT, mute/deaf, metering |
+| SRS-084 through SRS-095 | Storage, secure storage, identity, diagnostics-sensitive data |
+| SRS-096 through SRS-102 | Diagnostics, export, redaction, troubleshooting hooks |
+| SRS-103 through SRS-123 | Platform adapters, packaging, release behavior |
+| SRS-124 through SRS-143 | Verification support, analysis requirements, traceability rules |
+| SRS-144 through SRS-184 | Material 3, adaptive UI, accessibility, localization, Unicode, app initialization |
+| SRS-185 through SRS-218 | Platform baselines, PTT capability, transmit mode, no automatic telemetry, benchmark advisory |
+
+## 4. Component Architecture
+
+| Component | Repository location | Responsibility | Direct architectural dependencies |
+|---|---|---|---|
+| Flutter app shell | `apps/chanora_flutter/lib/main.dart`, services, widgets | App startup, screen composition, user actions, localization, Material 3 UI | Generated Rust bridge, platform plugins, Flutter services |
+| Flutter service layer | `apps/chanora_flutter/lib/services/` | Permission flows, lifecycle policy, host prefetch debounce, link trust, state mapping, platform back intent | Flutter app shell, generated bridge APIs, platform plugins |
+| Flutter widget layer | `apps/chanora_flutter/lib/widgets/` | Connect UI, channel tree, chat, voice controls, settings, diagnostics surfaces | Flutter services, generated DTOs, design tokens |
+| Bridge layer | `crates/chanora_bridge`, `apps/chanora_flutter/lib/src/rust/` | Typed Flutter/Rust boundary and generated bindings | Rust core, Flutter generated code |
+| Rust core | `core/chanora_core` | Connection lifecycle, orchestration, reconnect behavior, storage coordination, voice state | Protocol, audio, storage, diagnostics, state, resolver/prefetch |
+| Protocol adapter | `crates/chanora_protocol` | Isolate `tsclientlib`, expose typed protocol DTOs/errors | Rust core, external compatible server |
+| State sync | `crates/chanora_state` | Snapshot/delta model, channel join helpers, reducer behavior | Rust core, protocol DTOs |
+| Audio subsystem | `crates/chanora_audio` | Capture/playback, Opus, DSP, PTT, voice activity reservation, platform units | Rust core, platform APIs, protocol audio path |
+| Storage | `crates/chanora_storage` | Bookmarks, identities, encrypted local data, platform keyring integration | Rust core, platform secure storage |
+| Diagnostics | `crates/chanora_diagnostics` | Redaction, log sink, export bundle, known-secret registry | Rust core, Flutter diagnostics UI |
+| Server resolver | `crates/chanora_resolver` | SRV/TSDNS/DNS fallback resolution | Rust core, prefetch crate |
+| Server prefetch | `crates/chanora_server_prefetch`, Flutter `prefetch_debouncer.dart` | Invisible host-field resolution warming, TTL cache, generation safety | Resolver, Flutter connect UI, Rust core |
+
+## 5. Static Architecture View
+
+```text
+Flutter UI/widgets/services
+  -> generated Dart bridge API
+  -> chanora_bridge
+  -> chanora_core
+      -> chanora_protocol -> tsclientlib -> external compatible server
+      -> chanora_state
+      -> chanora_audio -> platform audio APIs / Opus / DSP
+      -> chanora_storage -> platform secure storage / SQLite
+      -> chanora_diagnostics
+      -> chanora_server_prefetch -> chanora_resolver -> network DNS/TSDNS
+```
+
+The bridge is the trust and type boundary between Flutter and Rust. Flutter must not directly depend on protocol-library internals. Rust core must not expose platform-specific storage or audio details to UI code except through stable DTOs and capability fields.
+
+## 6. Runtime Flow Architecture
+
+### 6.1 Connect Flow
+
+```text
+User enters host/bookmark
+  -> Flutter connect widgets
+  -> optional prefetch debounce
+  -> bridge connect command
+  -> Rust core supervisor
+  -> resolver / prefetch cache
+  -> protocol adapter
+  -> external compatible server
+  -> state snapshot/events
+  -> bridge event stream
+  -> Flutter state mapper and widgets
+```
+
+### 6.2 Voice Flow
+
+```text
+Microphone / platform input
+  -> audio capture unit
+  -> DSP chain: HPF, NS, AEC, AGC where active
+  -> PTT/mute/transmit gate
+  -> Opus encode
+  -> protocol adapter
+  -> external compatible server
+
+External server voice
+  -> protocol adapter
+  -> jitter/decode path
+  -> mixer / per-user controls
+  -> platform output
+```
+
+### 6.3 Diagnostics Flow
+
+```text
+Runtime event or error
+  -> diagnostic log sink / known-secret registry
+  -> redactor
+  -> user-initiated export bundle
+  -> Flutter share/export surface
+```
+
+## 7. Interface Catalogue
+
+| Interface | Producer | Consumer | Architectural rule |
+|---|---|---|---|
+| Bridge command DTOs | Flutter generated API | `chanora_bridge`, Rust core | Stable typed DTOs; no raw protocol-library types cross to Flutter |
+| Bridge event DTOs | Rust core / bridge | Flutter services/widgets | User-safe errors and capability fields are explicit |
+| Protocol DTOs | `chanora_protocol` | Rust core, state sync | Protocol adapter isolates `tsclientlib` |
+| Audio configuration | Flutter settings / Rust core | `chanora_audio` | Voice modes and processing flags are explicit; VAD remains disabled/deferred |
+| Storage records | Storage crate | Rust core / Flutter UI via bridge | Secrets stay behind secure-storage abstraction |
+| Diagnostic bundles | Diagnostics crate | Flutter diagnostics UI | Redaction runs before export or display |
+| Platform capability records | Platform adapters/audio/PTT backends | UI and release record | UI/release wording must not over-claim capability |
+
+## 8. Dependency Rules
+
+| Rule | Rationale |
+|---|---|
+| Flutter UI depends on generated bridge APIs, not Rust internals | Keeps UI stable across Rust implementation changes |
+| Rust core orchestrates crates but protocol/audio/storage crates remain separately testable | Supports SWE.4 unit verification and bounded responsibilities |
+| Protocol adapter is the only component that owns `tsclientlib` coupling | Protects the app from protocol-library leakage |
+| Diagnostics redaction must be reusable by runtime logging and export | Prevents split redaction behavior |
+| Platform-specific behavior stays in platform adapters or audio platform units | Keeps cross-platform logic testable and reduces conditional sprawl |
+| Release claims consume capability records and release evidence | Prevents over-claiming PTT, signing, packaging, or secure-storage behavior |
+
+## 9. Non-Functional Allocation
+
+| Concern | Architectural mechanism | Verification owner |
+|---|---|---|
+| Real-time audio responsiveness | Rust audio subsystem, benchmark advisory, bounded callback behavior | Audio / Platform QA |
+| Privacy and no automatic telemetry | User-initiated diagnostics, no automatic upload policy | Security / Privacy QA |
+| Secure secret handling | Platform secure-storage abstraction and encrypted local storage | Security / QA |
+| Cross-platform UI | Flutter Material 3, design tokens, responsive widgets | Software QA / UX |
+| Protocol compatibility | `tsclientlib` adapter isolation and compatible-server matrix | Protocol / Integration QA |
+| Release reproducibility | CI, build scripts, artifact hashes, release-readiness record | Release / Operations QA |
+
+## 10. Architectural Decisions Captured by This Baseline
+
+| Decision | Architectural outcome |
+|---|---|
+| Flutter + Rust split | Flutter owns presentation; Rust owns protocol/audio/storage/diagnostics core behavior |
+| `tsclientlib` isolation | Protocol compatibility is behind `chanora_protocol` |
+| Secure storage abstraction | Platform storage details do not leak into UI or unrelated crates |
+| Advisory audio benchmarks | Performance regressions are surfaced without making CI a hard release gate at this stage |
+| PTT capability levels | Platform PTT support is represented as capability data and must match release wording |
+| VoiceActivity deferral | `VoiceActivity` remains reserved/disabled until a later baseline allocates implementation |
+| No automatic diagnostic upload in MVP | Diagnostics are local and user-initiated unless future approved requirements change policy |
+
+## 11. Verification Handoff
+
+| Verification plan | SAD handoff |
+|---|---|
+| SWE.4 | Component boundaries define unit-test ownership for Flutter services/widgets and Rust crates |
+| SWE.5 | Interface catalogue and runtime flows define integration paths |
+| SWE.6 | SRS allocation and acceptance flows define software acceptance evidence |
+| SYS.4 | Platform capability and external-server boundaries define system integration evidence |
+
+## 12. Traceability to SRS
+
+This SAD derives only from `docs/srs.md`. The broad SRS group-to-component allocation in section 3 is the controlling SWE.2 trace for DV. Detailed item-level trace is represented by the SRS coverage matrix and `docs/governance/traceability-matrix.md`.
+
+## 13. Open Architecture Risks
+
+| Risk | Impact | Control |
+|---|---|---|
+| SAD item numbering from historical status references is not reconstructed in this baseline | Existing references such as `SAD-043` and `SAD-046` are not itemized here | Treat this as a DV baseline SAD; add itemized SAD IDs in a follow-up if process requires strict ID-level review |
+| Some architecture views are textual rather than C4 diagrams | Reviewers may request visual C4 views | Record as documentation hardening, not a blocker for DV baseline if textual views are accepted |
+| Release/platform architecture evidence is incomplete | Public release remains blocked | Controlled by release-readiness and waiver records |
+
+## 14. DV Conclusion
+
+This SWE.2 baseline is sufficient to remove the missing-SAD traceability gap for DV review. It does not replace candidate test evidence or final release approval.

docs/architecture/sdd.md

@@ -0,0 +1,154 @@
+# Chanora Software Detailed Design
+
+**Lifecycle:** SWE.3 Software Detailed Design and Unit Construction Handoff  
+**Document status:** DV meeting baseline candidate  
+**Date:** 2026-05-29  
+**Direct upstream source:** `docs/architecture/sad.md`  
+**Related software requirements:** `docs/srs.md`
+
+## 1. Purpose
+
+This Software Detailed Design defines the module-level design details needed for SWE.4 unit verification and SWE.5 integration verification. It is based on the current repository layout and the SWE.2 architecture baseline.
+
+## 2. Module Catalogue
+
+| SDD module | Source location | Primary responsibility | Upstream SAD component |
+|---|---|---|---|
+| SDD-MOD-001 Flutter app bootstrap | `apps/chanora_flutter/lib/services/app_bootstrap.dart`, `main.dart` | Initialize Rust bridge, localization, app services, theme/design baseline | Flutter app shell |
+| SDD-MOD-002 Connect UI | `apps/chanora_flutter/lib/widgets/connect_widgets.dart` | Host/bookmark inputs, connect actions, pre-request UX | Flutter widget layer |
+| SDD-MOD-003 Snapshot and channel UI | `snapshot_view.dart`, `snapshot_state_mapper.dart`, `channel_spacer.dart` | Present channel tree, clients, and mapped state | Flutter widget/service layer |
+| SDD-MOD-004 Chat UI | `chat_views.dart`, `bbcode_text.dart` | Channel text rendering and BBCode-safe display | Flutter widget layer |
+| SDD-MOD-005 Voice UI | `voice_bar.dart`, `voice_compact.dart`, `voice_settings*.dart`, `voice_level_meter.dart`, `ptt_capability_badge.dart` | Voice controls, processing settings, metering, PTT capability | Flutter widget layer |
+| SDD-MOD-006 Platform services | `android_permissions_service.dart`, `ios_permissions_service.dart`, `audio_lifecycle_service.dart`, `back_intent_*`, `link_trust_service.dart` | Permission, lifecycle, navigation, route/link trust behavior | Flutter service layer |
+| SDD-MOD-007 Bridge API | `crates/chanora_bridge/src/api.rs`, generated Dart/Rust bridge files | Typed command/event boundary | Bridge layer |
+| SDD-MOD-008 Rust core supervisor | `core/chanora_core/src/lib.rs`, `ptt.rs` | Connection orchestration, reconnect, PTT state, storage coordination | Rust core |
+| SDD-MOD-009 Protocol adapter | `crates/chanora_protocol/src/` | `tsclientlib` isolation, DTO/error mapping | Protocol adapter |
+| SDD-MOD-010 State sync | `crates/chanora_state/src/lib.rs`, `channel_join.rs` | Snapshot/delta model, reducer, channel join support | State sync |
+| SDD-MOD-011 Audio subsystem | `crates/chanora_audio/src/` | Audio capture/playback, DSP, Opus, PTT, mode stack, platform units | Audio subsystem |
+| SDD-MOD-012 Storage | `crates/chanora_storage/src/lib.rs` | Bookmarks, identity storage, encrypted local records, keyring abstraction | Storage |
+| SDD-MOD-013 Diagnostics | `crates/chanora_diagnostics/src/lib.rs` | Redaction, log sink, known-secret registry, export bundle | Diagnostics |
+| SDD-MOD-014 Resolution and prefetch | `crates/chanora_resolver/src/lib.rs`, `crates/chanora_server_prefetch/src/lib.rs`, `prefetch_debouncer.dart` | SRV/TSDNS/DNS fallback and generation-safe resolution warming | Server resolver / prefetch |
+| SDD-MOD-015 Build and release hooks | `.github/workflows/`, `tools/`, platform project files | CI, unsigned iOS build, benchmark advisory, platform smoke procedures | Release / platform architecture |
+
+## 3. Bridge Boundary Design
+
+The bridge boundary is the only supported Flutter-to-Rust command path. Dart code uses generated APIs under `apps/chanora_flutter/lib/src/rust/`; Rust exposes bridge functions through `crates/chanora_bridge/src/api.rs`.
+
+Design rules:
+
+| Rule | Detail |
+|---|---|
+| DTO stability | DTO fields must be explicit and serializable through Flutter Rust Bridge generation |
+| Error safety | Rust errors exposed to Flutter must be user-safe or mapped before display |
+| Secret handling | Secrets may cross only as command inputs or protected DTO fields and must be registered for diagnostic redaction where relevant |
+| Capability reporting | Platform and PTT capability fields must reflect actual active backend state |
+| Regeneration control | Generated bridge files are implementation artifacts and must be regenerated when bridge API signatures change |
+
+## 4. Connection and State Design
+
+| Detail | Design |
+|---|---|
+| Connection lifecycle | Rust core owns connect/disconnect/reconnect decisions and suppresses reconnect after user disconnect |
+| Backoff | Reconnect uses exponential backoff as described in implementation status, capped at 60 seconds |
+| Server resolution | Resolver performs SRV/TSDNS/DNS fallback; prefetch cache may warm but must not be required for connect success |
+| Snapshot mapping | Rust state and bridge DTOs are mapped into Flutter view models by `snapshot_state_mapper.dart` |
+| Channel join | Channel join logic and errors are represented through Rust state/protocol handling and Flutter error mapper service |
+| Reducers | `chanora_state` owns snapshot/delta reducer design with unit coverage for snapshot, delta, reconnect, duplicate normalization, disconnected/lost suppression, unknown-client voice activity, deterministic ordering, and channel-delete/client cleanup. Current runtime UI refresh still flows through `chanora_core` snapshot/probe paths; full live-event folding through `chanora_state::reduce` is an integration follow-up. |
+
+## 5. Audio Detailed Design
+
+| Audio element | Design detail |
+|---|---|
+| Capture/playback | Platform-specific units handle Android, iOS, desktop/fallback paths behind Rust audio abstractions |
+| Codec | Opus encode/decode lives in `opus_voice.rs` and associated audio modules |
+| DSP chain | High-pass filter, noise suppression, echo cancellation, and AGC are represented by audio processing modules/backends |
+| Transmit control | `TransmitMode` supports `Ptt`, `Continuous`, and reserved `VoiceActivity`; `VoiceActivity` has no active MVP implementation |
+| PTT | Desktop/mobile backends expose capability level and active backend; missed-key-up watchdog prevents stuck transmit |
+| Release tail | Tail handling prevents abrupt cutoffs after PTT release where configured |
+| Benchmarks | Realtime capture, Opus, and resampler benchmarks provide advisory baseline evidence |
+
+## 6. Storage and Secret Design
+
+| Storage item | Design detail |
+|---|---|
+| Bookmarks | Stored locally through the storage crate and surfaced in Flutter connect UI |
+| Identity references | Stored through `IdentityFileStore` and platform secure storage where available |
+| Passwords/secrets | Encrypted at rest using the current storage design; Android Keystore-backed DEK is deferred and must be disclosed |
+| CI keyring behavior | CI disables real keyring access with `CHANORA_DISABLE_KEYRING=1` to avoid headless blocking |
+| Fallback behavior | Platform fallback modes must be represented as limitations in release/security evidence |
+
+## 7. Diagnostics Detailed Design
+
+| Diagnostic element | Design detail |
+|---|---|
+| Log sink | Runtime logs can be captured by diagnostic sinks for export |
+| Known-secret registry | Runtime secrets are registered for redaction where applicable |
+| Redactor | Redacts configured sensitive patterns before export |
+| Export bundle | Diagnostic export is JSON-based and user-initiated |
+| Upload policy | MVP has no automatic diagnostic, telemetry, or crash upload |
+
+## 8. Flutter UI Detailed Design
+
+| UI area | Design detail |
+|---|---|
+| Design tokens | `chanora_tokens.dart` centralizes product styling over Material 3 |
+| Platform capability display | `platform_capabilities.dart` and PTT capability widgets expose platform-specific support honestly |
+| Localization | Generated localization files provide English and Simplified Chinese resources |
+| Responsive behavior | Current widgets support compact/mobile-oriented layouts; expanded side-pane hardening remains P1/P2 as recorded |
+| Accessibility | Critical status should use text/icons/semantics and not color alone; verification remains through UI tests/audit |
+| UI settings persistence | `UiPreferencesService` persists host, nickname, permission explanation state, and theme mode through `shared_preferences`; invalid stored theme values fall back to system theme |
+
+## 9. Build and Release Detailed Design
+
+| Build/release item | Design detail |
+|---|---|
+| Rust CI | `.github/workflows/ci.yml` runs cargo check/test and advisory clippy |
+| Flutter CI | `.github/workflows/ci.yml` runs Flutter pub get, analyze, and tests |
+| Supply chain | CI runs cargo-deny and license inventory checks |
+| iOS unsigned build | CI runs `flutter build ios --release --no-codesign` |
+| Audio benchmarks | `bench-advisory.yml` runs audio benchmarks and posts advisory evidence |
+| Platform packages | Public binary packaging/signing/notarization remains release-gated |
+
+## 10. Verification Hook Design
+
+| Module | SWE.4 unit hooks | SWE.5/SWE.6 integration hooks |
+|---|---|---|
+| Flutter services/widgets | Dart unit/widget tests under `apps/chanora_flutter/test/` | Widget/system demos and candidate device smoke |
+| Bridge | API compile/generation checks | Flutter-to-Rust command/event smoke |
+| Rust core | Cargo tests | Compatible-server lifecycle demo |
+| Protocol | DTO/error mapping tests | Protocol compatibility matrix and server demo |
+| State sync | Reducer tests | Snapshot/delta/reconnect integration evidence |
+| Audio | DSP/codec/PTT tests and benchmarks | Platform audio loopback/device demo |
+| Storage | Repository/encryption/keyring-disabled tests | Platform secure-storage audit |
+| Diagnostics | Redaction/export tests | User-initiated export inspection |
+| Release hooks | CI workflow validation | Release readiness record and artifact evidence |
+
+## 11. Traceability to SAD
+
+| SAD component | SDD modules |
+|---|---|
+| Flutter app shell | SDD-MOD-001 |
+| Flutter service layer | SDD-MOD-006, SDD-MOD-014 |
+| Flutter widget layer | SDD-MOD-002 through SDD-MOD-005 |
+| Bridge layer | SDD-MOD-007 |
+| Rust core | SDD-MOD-008 |
+| Protocol adapter | SDD-MOD-009 |
+| State sync | SDD-MOD-010 |
+| Audio subsystem | SDD-MOD-011 |
+| Storage | SDD-MOD-012 |
+| Diagnostics | SDD-MOD-013 |
+| Server resolver/prefetch | SDD-MOD-014 |
+| Release/platform architecture | SDD-MOD-015 |
+
+## 12. Open Detailed-Design Risks
+
+| Risk | Impact | Control |
+|---|---|---|
+| Detailed item IDs from historical SDD references are not reconstructed | Existing references such as `SDD-109` are not itemized in this baseline | Treat this as a DV baseline SDD and add strict item numbering later if required |
+| Some module designs are summarized rather than API-by-API | May be insufficient for final process audit | Use this as DV baseline; deepen high-risk modules before final release gate |
+| Android Keystore-backed DEK is not implemented | Limits storage/security design claims | Controlled by waiver and release-readiness records |
+| Full event replay tooling and live reducer integration evidence are absent | Limits state verification design beyond reducer unit behavior | Controlled as P1 gap and runtime-integration follow-up |
+
+## 13. DV Conclusion
+
+This SWE.3 baseline is sufficient to remove the missing-SDD traceability gap for DV review and to feed SWE.4/SWE.5 verification plans. It does not close release evidence gaps or replace source-level tests.

docs/architecture/sysdes.md

@@ -0,0 +1,21 @@
+# System Design Specification
+
+**Document status:** DV entry-point record  
+**Canonical document:** `../sysdes.md`
+
+The canonical Chanora System Design Specification currently lives at `docs/sysdes.md`. This file preserves the README-advertised path `docs/architecture/sysdes.md` for DV navigation.
+
+Reviewers shall use `docs/sysdes.md` as the authoritative SysDes baseline until the repository migration moves the canonical file into this directory.
+
+## DV Review Summary
+
+| Topic | Canonical source |
+|---|---|
+| System element allocation | `docs/sysdes.md` sections 4 through 8 |
+| Verification handoff | `docs/sysdes.md` section 12, SysDes-102 through SysDes-107 |
+| SysRS-to-SysDes allocation matrix | `docs/sysdes.md` Appendix A |
+| Change-control and traceability rules | `docs/sysdes.md` SysDes-108 through SysDes-110 |
+
+## DV Position
+
+The SysDes baseline is reviewable for DV. SRS, SAD, SDD, and verification documents derive from or consume this allocation layer.