# AGENTS · Documentation Working Directory

## Scope & Roles
- Working directory: `docs/` (includes `docs/assets/**` fixtures and `docs/api/console/samples/**`).
- Roles: Documentation author (primary), QA/fixtures reviewer, module SMEs (Console/UI, Advisory AI, Policy/Airgap) for accuracy checks.
- Only documentation and fixture assets live here; code changes belong to module repos and must be coordinated via the owning sprint.

## Required Reading (treat as read before DOING)
- `docs/README.md` and `docs/07_HIGH_LEVEL_ARCHITECTURE.md`.
- Module dossiers relevant to the document being edited (e.g., `docs/modules/advisory-ai/architecture.md`, `docs/modules/ui/architecture.md`, `docs/modules/airgap/architecture.md`, `docs/modules/platform/architecture-overview.md`).
- Active sprint file: `docs/implplan/SPRINT_0301_0001_0001_docs_md_i.md` (Docs Tasks Md.I).

## Working Agreements
- Determinism: Keep fixtures and captures reproducible. Store payload JSON alongside SVG/PNG captures; record sha256 hashes in the doc and verify with `sha256sum` before publishing.
- Offline posture: Use sealed/fixture data only; no external fonts/CDNs or live calls in regeneration scripts. Capture timestamps in UTC.
- Status discipline: Update task status in the sprint Delivery Tracker (`TODO → DOING → DONE/BLOCKED`) and log changes in the sprint Execution Log.
- Cross-links: When documentation applies a design/advisory change, update the relevant module doc and link it from the sprint’s **Decisions & Risks**.
- Testing: For regeneration scripts, keep them self-contained (stdlib-only) and record expected hashes so QA can diff outputs deterministically.

## Boundaries
- Do not edit source code outside `docs/` without an explicit sprint note.
- Asset placement: use `docs/assets/<area>/` for captures and `docs/api/<area>/samples/` for JSON fixtures. Name captures `yyyyMMdd-HHmmss-<view>-<build>.<ext>` in UTC.

## Escalation / Blockers
- Missing fixtures or conflicting contracts → mark the task `BLOCKED` in the sprint file, describe the needed artifact or contract in **Decisions & Risks**, then continue with other unblocked work.
- If new advisories land, run the advisory-sync workflow: update high-level docs, deep area docs, add sprint tasks, and carry code samples into fixtures/tests immediately.