# Documentation map

Start with [current architecture and vocabulary](architecture.md). It describes
the implemented ownership boundaries and points to the code that owns them.
[AGENTS.md](../AGENTS.md) describes how to work here.

## Where to look

| Question | Source |
| --- | --- |
| What is the application and what owns its state? | [Architecture](architecture.md) |
| What is the product's design direction? | [Product](../PRODUCT.md); currently focused on Types & Records interaction |
| What should ATProto startup/login/onboarding/logout do? | [Local-first lifecycle](plans/atproto-local-first-lifecycle.md); user-aligned correction in progress |
| What is the current transport implementation and what was tested? | [Sustainable inline sync plan](plans/2026-10-11-sustainable-inline-sync.md) and [implementation evidence](verification/2026-10-11-sustainable-inline-sync.md); feature branch, not deployed |
| What is proposed for worker-owned editing, adoption and large backup import? | [Worker-owned documents plan](plans/2026-10-07-worker-owned-documents.md); draft, not yet implemented |
| How do external plugins work? | `src/plugin/obsidian-compat/` and `src/plugin/reams/`; `npm run obsidian:contract` checks upstream API shape. The [plugin author guide](PLUGIN-AUTHOR-GUIDE.md) provides examples, with some historical implementation descriptions. |
| How do I deploy or operate a release? | `playbooks/`; use the playbook for the selected edition/deployment |
| What does a particular test gate measure? | `testing/`, `perf/`, package scripts and their Vitest configs |
| What work is scheduled or complete? | Chainlink (`chainlink tree`, `chainlink show <id>`) |
| Where should cleanup start? | [2026-10-05 maintainability audit](audits/2026-10-05-maintainability.md) |
| Where can I note friction encountered during a change? | [problems.md](../problems.md); add a short note during commit reflection when useful. |

## Keeping guidance trustworthy

- Put a live contract in one short maintained document or its owning code;
  link to it from plans and agent instructions instead of copying it.
- Date decisions and plans so their original context is clear. Remove contradictory
  prescriptive guidance when the user replaces a contract, and link to its current
  authority. Retain dated verification evidence as evidence of that candidate,
  not instructions to reproduce superseded product behavior.
- Verification reports describe their dated candidate and executed scope. A
  passing checkpoint is not a permanent claim about the current release.
- Keep temporary ports, worktree permissions, and resume instructions scoped to
  their session/candidate. Deployment assumptions from before release need review
  before reuse for migration or compatibility work.
- When guidance and implementation disagree, investigate and reconcile them;
  an architecture summary does not silently authorize changing product behavior.

## Historical context (when needed)

`decisions/`, `research/`, `plans/`, and `verification/` retain the reasoning,
experiments, and evidence from earlier checkpoints. Read them to investigate a
specific change, using their dates and candidate scope. Older Chainlink issues,
including #1, likewise describe their original implementation context.

The editor originally used Lexical and migrated to CodeMirror 6 in Chainlink #203.
`~/usr/reams` is an older OverType prototype, useful for design inspiration.
The [September 2026 text-first worktree instructions](plans/2026-09-text-first-worktree-guidance.md)
are retained as a historical session record, not a prerequisite for current work.