# AGENTS.md — Chanora Project Conventions

## Project Overview

Chanora is a cross-platform voice client (Flutter + Rust) targeting TeamSpeak-compatible servers. The project follows ASPICE engineering processes with full traceability from system requirements through verification.

## Repository Structure

```
chanora/                          ← Code repo (this one)
├── docs/ → chanoraapp/docs       ← Git submodule: ASPICE docs, Docusaurus doc site
├── dev-docs/                     ← Local-only development docs
│   ├── superpowers/              ← AI agent specs and plans
│   │   ├── specs/                ← Feature/design specs (active)
│   │   └── plans/                ← Implementation plans (active)
│   │       └── _archived/        ← Completed plans
│   ├── offline-knowledge/        ← Doc maintenance tools, link coverage
│   ├── implementation-status-*   ← Code state snapshots
│   └── release/ios-build.md      ← Operational build instructions
├── apps/chanora_flutter/         ← Flutter application
├── core/chanora_core/            ← Rust core API + orchestration
├── crates/                       ← Rust crates (protocol, audio, state, etc.)
└── dev-docs/impl-mapping.md      ← SAD component → source file mapping
```

## Documentation Two-Repo Model

**`docs/` is a git submodule** pointing to the `chanoraapp/docs` repository. It serves a Docusaurus doc site with ASPICE traceability. It is NOT a local directory you can freely create files in.

### What lives where

| Content | Location | Reason |
|---|---|---|
| SysRS, SysDes, SRS, SAD, SDD | `docs/` (submodule) | ASPICE baselines, served on doc site |
| Verification plans (SWE.4/5/6, SYS.4) | `docs/` (submodule) | ASPICE verification evidence |
| Governance, traceability, decision register | `docs/` (submodule) | ASPICE governance |
| Security, privacy, legal | `docs/` (submodule) | Stakeholder-facing |
| UI/UX guidelines, i18n architecture | `docs/` (submodule) | Design references |
| Feature specs and implementation plans | `dev-docs/superpowers/` | Code-coupled, agent working files |
| Link coverage, doc quality analysis | `dev-docs/offline-knowledge/` | Maintenance tools |
| Implementation status snapshots | `dev-docs/` | Code state tracking |
| Source file path references | `dev-docs/impl-mapping.md` | Developer convenience, not ASPICE |

### Rules for agents

1. **Never create or edit files in `docs/`** without understanding it's a submodule. Changes there require committing in the `chanoraapp/docs` repo first, then updating the submodule pointer in this repo.

2. **ASPICE documents do not contain code file paths.** ASPICE traces requirement IDs (e.g., `SysRS-233`, `SRS-045`, `SDD-MOD-009`), not source file paths. If you need to map a component to its source, use or update `dev-docs/impl-mapping.md`.

3. **Specs and plans go in `dev-docs/superpowers/`.** Follow the naming convention: `YYYY-MM-DD-<topic>-design.md` for specs, `YYYY-MM-DD-<topic>.md` for plans.

4. **Completed plans move to `_archived/`.** Once a plan is fully implemented and verified, move it to `dev-docs/superpowers/plans/_archived/`.

5. **Doc site uses Docusaurus.** The `chanoraapp/docs` repo uses Docusaurus 3.10 (Meta-maintained). Do not add MkDocs, mdBook, or other doc site generators.

## ASPICE Traceability Chain

```text
SysRS → SysDes → SRS → SAD (SWE.2) → SDD (SWE.3) → Verification
                                           ↓              ↓
                                       SWE.4 (unit)   SWE.4/5/6/SYS.4
```

- Requirement IDs are the traceability mechanism, not file paths.
- Every downstream document must reference upstream IDs it traces from.
- Verification plans map to their upstream design/requirements level:
  - SYS.4 ← SysDes, SysRS
  - SWE.5 ← SAD (SWE.2)
  - SWE.4 ← SDD (SWE.3)
  - SWE.6 ← SRS
- Requirement IDs should be added to doc front matter `tags:` for traceability browsing.

## Code Architecture

| Component | Location | Responsibility |
|---|---|---|
| Flutter app shell | `apps/chanora_flutter/` | UI, Material 3, navigation, localization |
| Rust core | `core/chanora_core/` | Session orchestration, bridge events |
| Protocol adapter | `crates/chanora_protocol/` | TeamSpeak protocol via tsclientlib |
| State sync | `crates/chanora_state/` | Snapshots, deltas, reducers |
| Audio subsystem | `crates/chanora_audio/` | Capture, DSP, Opus, PTT |
| Storage | `crates/chanora_storage/` | Bookmarks, identity, encryption |
| Diagnostics | `crates/chanora_diagnostics/` | Redaction, logs, export |
| Resolver | `crates/chanora_resolver/` | SRV/TSDNS/DNS resolution |
| Prefetch | `crates/chanora_prefetch/` | Resolution warming, TTL cache |
| Bridge | `crates/chanora_bridge/` | Flutter/Rust typed DTO boundary |
| Cache | `crates/chanora_cache/` | Avatar/icon blob cache |

## Coding Conventions

- **Rust:** Follow workspace `Cargo.toml` structure. Run `cargo check`, `cargo clippy`, `cargo test` before committing.
- **Flutter:** Run `flutter analyze`, `flutter test` before committing.
- **No code comments** unless explicitly requested.
- **Git commits:** Follow convention in `docs/governance/git-commit-message-convention.md` (accessible via submodule).
- **Bridge boundary:** Flutter must not directly depend on protocol-library internals. All cross-boundary communication goes through `chanora_bridge` typed DTOs.

## Verification Commands

```bash
cargo check && cargo clippy && cargo test
cd apps/chanora_flutter && flutter analyze && flutter test
```

## Important References

- Traceability matrix: `docs/governance/traceability-matrix.md`
- Decision register: `docs/governance/product-decision-register.md`
- Security guidelines: `docs/security/security-privacy-legal-guideline.md`
- Release readiness: `docs/release/release-readiness-go-nogo-record.md`
- Doc site repo: `chanoraapp/docs` (Docusaurus)
- Doc site local preview: `cd docs && npm run start`