# DAMM Documentation Index

The doc set has grown. This file is the canonical map: which doc owns which concern, what status each is in, when it was last verified against reality. **Updating a doc without updating this index is how the doc set goes to seed.**

Last verified: 2026-04-29 (against deployed v0.3.2).

## How to read this index

Status legend:
- **canonical** — the one we steer by. A demand or a behavior that disagrees with this doc is a bug in the system or in the doc; pick one and reconcile.
- **supplementary** — a deeper read on a topic the canonical docs touch on. Useful, not authoritative.
- **superseded** — kept for git history but no longer steering anything; pointers in newer docs replace it.
- **draft** — not yet load-bearing.

When you write code that contradicts a `canonical` doc, *fix one of the two before merging*. When two `canonical` docs contradict each other, that's a flag to file an issue, not to silently pick one.

## The canonical set

| Doc | Owns | Last verified |
|---|---|---|
| `field-manual.md` | What's deployed, postmortem, demands per concern, storyboards, what to ship next | 2026-04-29 |
| `roadmap-next.md` | Concrete release-by-release plan to v0.4.0 with exit criteria each | 2026-04-29 |
| `issue-triage.md` | Compact register of every open concern, categorized | 2026-04-29 |
| `transport-tiers.md` | T0-T4 obfuscation tier spec: what each defeats, costs, server runtime, client app | 2026-04-29 |
| `tech-debt.md` | Running register of debt accrued in tracer-bullet work | 2026-04-29 |
| `bring-up-notebook.md` | Reproducible cell-by-cell setup of a fresh hub2 to a working `/get/` wizard | 2026-04-28 |
| `operational-runbook.md` | Halt / freeze / wedged-state recovery, 26 sections, ~120 specific runnable steps | 2026-04-28 |
| `architecture-map.md` | The resilience-by-statistics posture: threat-blind score loop, signed catalogs, polymorphic transport, ingress/egress separation | 2026-04-27 |
| `coordination-layer.md` | Provider-polyglot architecture: Capability interface, adapter pattern, per-provider competitive analysis, Phase 3.0–3.6 trajectory | 2026-04-27 |
| `system-spec.md` | Implementation contract: required invariants, component specs, state model, validation contract, success criteria | 2026-04-21 |
| `scripts/verify/` | Runnable verification suite — celebrated-path, units, public-surfaces, state-integrity, admission, wizard-flow + verify-all driver | 2026-04-29 |

## Supplementary (useful, not authoritative)

| Doc | Adds | Last verified |
|---|---|---|
| `architecture-premortem.md` | Peer-architect critique of Phase-0 trajectory + competing stateless-tickets alternative | 2026-04-27 |
| `sanity-check-2026-04-28.md` | Component-by-component critique with sharp API boundaries and the v0.3 done-when checklist | 2026-04-28 |
| `design-brief.md` | Visual + interaction designer hand-off for the wizard | 2026-04-27 |
| `engineering-decisions.md` | Why we chose what we chose | 2026-04-21 |
| `client-boundaries.md` | The boundary between native VPN clients, the companion PWA, and CP logic | 2026-04 |
| `onboarding-flow.md` | The honest current onboarding path; predates the `/get/` wizard | 2026-04-21 |
| `validation-harness.md` | What each validation harness proves and where evidence lands | 2026-04 |
| `network-permeability.md` | Schema for permeability scores and placement recommendations | 2026-04 |
| `runbook.md` | Original bring-up runbook (predates `bring-up-notebook.md` and `operational-runbook.md`) | 2026-04 |
| `roadmap.md` | Milestones ordered by architectural dependency | 2026-04 |
| `architecture-decision-records.md` | ADRs for key choices | 2026-04 |
| `payment-credentials.md` | Provider billing model | 2026-04 |
| `observatory-integration.md` | How DAMM hooks into the broader observatory | 2026-04 |
| `site-deployment.md` | How `damm.raindesk.dev` (the marketing site) is deployed | 2026-04 |
| `platform-clients.md` | Platform-specific client guidance | 2026-04 |
| `profiling.md` | Profiling approach | 2026-04 |
| `agent-orientation.md` | Agent-onboarding for AI assistants picking up the repo cold | 2026-04 |
| `repo.md` | Repo conventions | 2026-04 |
| `status-template.md` | Template for status reports | 2026-04 |
| `achievements.md` | Cumulative milestones | 2026-04-21 |
| `iphone-apps.html` | Generated portfolio (not core to DAMM) | 2026-04 |
| `ghost-drones.md` | Imaginative thread; not load-bearing | 2026-04 |

## Drift markers (things to reconcile next)

These are the places where the doc set is currently inconsistent with the deployed system or with itself. Fix in the next ship.

- **`runbook.md` vs `bring-up-notebook.md` vs `operational-runbook.md`** — three docs for closely related concerns. The new pair (notebook + operational-runbook) supersedes `runbook.md` for both bring-up and recovery. Action: mark `runbook.md` as superseded with a one-line redirect to the two new docs.
- **`onboarding-flow.md` predates the `/get/` wizard** — it describes the honest pre-wizard path. The wizard fundamentally changes that path. Action: either rewrite `onboarding-flow.md` against the wizard, or mark it superseded by `field-manual.md` §3.1 and §4.
- **`architecture.md` (original) vs `architecture-map.md` (resilience-by-statistics)** — both are canonical-shaped, both describe "the architecture." The map is the newer posture; the original holds the system thesis. Action: declare `architecture.md` the system thesis (what we are), `architecture-map.md` the resilience model (how we stay alive). Cross-link explicitly so future readers don't pick one and miss the other.
- **`engineering-decisions.md` vs `architecture-decision-records.md`** — both record decisions. Pick one as canonical; merge or retire the other.
- **`coordination-layer.md` Phase 3.x trajectory vs `roadmap.md`** — coordination-layer.md is the sharper, more recent statement of Phase 3+. Action: roadmap.md should reference coordination-layer.md for Phase 3+ rather than restating it.

## Doc-hygiene rules

These are the rules we follow so the doc set stays useful:

1. **Every canonical doc has a "Last verified" date.** When you change behavior the doc describes, update the date. When the date is more than 30 days old, re-read the doc against reality and either update or re-stamp.
2. **Drift goes in this index, not in commit messages.** When you notice a contradiction between a doc and the system, add it to `Drift markers` above — it'll be picked up in the next doc-hygiene pass.
3. **Every new doc is registered here on the same commit it lands.** A doc that doesn't earn a row in this index doesn't ship.
4. **Status changes are visible.** When a doc moves from canonical to superseded (or vice versa), it's a one-line edit here.
5. **The field manual is the lookup-first doc.** Operators triaging an incident, designers planning a screen, future engineers picking up cold — all start at `field-manual.md`. Any doc that wants to be load-bearing earns it by being referenced from there.

## Steering: how this index actually drives work

A practical loop:

- **Before designing a new feature**: search for the relevant `canonical` doc. If the demand isn't there, add it as `OPEN` first, then design.
- **Before merging a PR**: confirm that any doc the PR contradicts has been updated, or that the PR explicitly notes the contradiction here as a `Drift marker`.
- **Once a quarter (or after a major version)**: walk this index. Re-stamp dates. Reconcile drift markers. Retire docs that aren't earning their keep.

The doc set is a tool, not a museum. If a doc isn't being read by someone making a decision, it's dead weight. Either bring it to the canonical layer or supersede it.