Skip to content

Context Map — ownership, authority, budgets

The contract that keeps this repo's agent-facing documentation accurate and small. Enforcement is mechanical: scripts/docs-guard.sh (CI: docs-guard workflow) checks budgets, links, indexes, ADR parity, version claims, and duplication tripwires. When editing documentation, follow this file.

Ownership (one home per meaning)

Meaning Owner Everyone else
Universal conventions AGENTS.md §Conventions nowhere else
Doc router AGENTS.md §Documentation map subtree indexes list only their own files
Upkeep triggers AGENTS.md §Upkeep rules domain.md points here
Fine-grained topic routing per-subtree index.md index lines are triggers, never summaries
System map, layering, ADR table docs/architecture/overview.md CONTEXT.md carries one-line ADR entries
Capture flow & routing docs/architecture/ingestion-pipeline.md overview links; never re-derives it
NotificationKey formula parser.md §NotificationKey others link
Term definitions CONTEXT.md glossary (≤2 lines each) topic docs own how-it-works
Package/file layout the filesystem itself prose keeps only non-obvious orientation
Published-site navigation (nav) root zensical.toml mirrors subtree indexes; updated whenever a page under docs/ is added, renamed, moved, or deleted

Authority (who wins on conflict)

  1. Executable code, android-app/app/schemas/*.json, tests (incl. the ParseGoldenTest ≥90% HIGH gate)
  2. Machine-readable config: android-app/gradle/libs.versions.toml, CI workflows
  3. Current architecture docs (docs/architecture/*)
  4. Topic-doc scope lines
  5. Root AGENTS.md conventions
  6. CONTEXT.md glossary + decision index
  7. CHANGELOG / superseded ADRs

Always-loaded ≠ authoritative: a convention describes an intended invariant. If code contradicts it, surface the contradiction in the change — never silently rewrite either side.

Where new things go

  • New domain term → glossary entry ≤2 lines (definition + pointer).
  • New/changed decision → numbered ADR in docs/adr/ + one-line entries in CONTEXT.md and the overview table. Nothing else to update.
  • New convention → AGENTS.md §Conventions only.
  • New architecture topic → new docs/architecture/*.md with a scope line, plus its trigger line in docs/architecture/index.md (same PR).
  • New subsystem doc set → give the directory an index.md before it has three topic files.
  • New / renamed / moved / deleted doc page → update its subtree index and the curated nav in root zensical.toml (same PR); Cloudflare Pages republishes on push automatically.
  • Screenshot changes → images under docs/assets/screens/ are generated artifacts of scripts/generate_screenshots.sh; never hand-edit them — change the app or seeder, rerun the script, commit the refreshed PNGs.
  • Copy-pasting meaning between docs is a bug: add or sharpen a pointer.

Editing rules

  • Change behavior facts in the owner file; pointers name topics and survive content edits untouched.
  • Index/router lines are triggers ("when you're doing X"), not summaries.
  • Every topic doc opens with a one-line scope statement.
  • Docs describe shipped behavior only; plans belong in issues or ADRs marked Proposed.

Curated-rule bar (what earns always-loaded or glossary space)

A rule qualifies only with reason + source + scope + verification, e.g.: "money is Long minor units — ADR-0009 — visible in MoneyFormatter types, guarded by review." If you can't state the verifying mechanism, it doesn't go in; it can be rediscovered from code.

Provenance & freshness

Cite sources inline ("per ADR-0009"); no "last verified" timestamps — they go stale themselves. Freshness is mechanical: docs-guard detects dead pointers, phantom paths, stale versions and duplication regressions; humans re-skim the glossary at each release (see releasing checklist).

Budgets (CI-enforced; prune before growing)

  • AGENTS.md ≤ 65 lines
  • CONTEXT.md ≤ 140 lines

Raising a budget is a deliberate act in the same PR as the need for it.