This is the canonical map for understanding and changing Cacheboard. Start with the shortest path for your task, then follow links to the detailed contract rather than relying on a dated plan or handoff.
| Need | Read first | Then verify |
|---|---|---|
| Join the project or resume after context loss | Agent operating contract, current state, then architecture | Current source, git status, and development gates |
| Operate or troubleshoot startup/auth | Root quick start, server runtime contract | Operator runbook and current health output |
| Change Metrics Dashboard | Server runtime/API contract | Server tests and full provider-free gate |
| Change Cacheboard Orchestrator | Orchestrator document map, ADR 0002 | Nearest Orchestrator tests and verification ledger |
| Change Cacheboard Tasks or Quick Notes | Work Items and Quick Notes contract, ADR 0006, and ADR 0007 | Nearest Work Items/Quick Notes focused gate, browser fixture, then full gate |
| Make a capability or release claim | Capability matrix | Dated verification ledger and any required manual gate |
Cacheboard deliberately presents three owner-facing areas while reusing two runtime trust boundaries:
| Area | Purpose | Canonical detail |
|---|---|---|
| Metrics Dashboard | Exact-account metrics and owner-configured cards | server/README.md |
| Cacheboard Orchestrator | Exact-session control, queues, Rooms, automations, hosts, connectors, and attention | docs/orchestrator/README.md |
| Cacheboard Tasks | Compact Kanban workspace plus human-owned Quick Notes over the shared Orchestrator schema-11 store | work-items.md and ADR 0007 |
The implemented-surface snapshot and open gates are in CURRENT-STATE.md. The system-level relationship, state owners, and source hotspots are in ARCHITECTURE.md. The local workflow and exact commands are in DEVELOPMENT.md.
When material conflicts, use this order:
- Security and identity decisions in ADR 0001, ADR 0002, and applicable later ADRs, including ADR 0007 for Quick Notes.
- Current detailed contracts and exact-version provider capability probes.
- Persisted schema, validators, source behavior, and regression tests.
- Operator procedures and setup guides.
- Roadmaps, notes, plans, handoffs, and dated receipts.
Source presence proves implementation exists; a passing deterministic test proves only its stated fixture/local scope. Neither proves a live provider or external environment.
| Label | Meaning |
|---|---|
| Contract | Required behavior; not evidence that it passed. |
| Fixture-verified | A deterministic fake/isolated gate passed without consuming provider capacity. |
| Locally verified | A machine/runtime check passed on the named local environment. |
| Live-verified | The exact account/provider/device flow passed and has a dated receipt. |
| Experimental | A version-pinned vendor surface exists with a probe and fallback boundary. |
| Observed-only | Cacheboard may show or link the activity but does not own its controls. |
| Blocked | A named external or owner-only gate prevents verification. |
| Not verified | No acceptable evidence is recorded. |
Every verification record should include the date, tree/commit, command, environment, result, skips, and what it does not prove. Treat all receipts as point-in-time history; refresh cheap, drift-prone checks before relying on them.
- Architecture decisions:
docs/adr/ - Universal controller and Work Items contracts: Orchestrator document map
- Runtime operation and recovery: Operator runbook and runtime artifact identity
- Security and persisted-data boundaries: Data and security model
- Identity enrollment and reauthentication: multi-account operations
- Current versus historical proof: Verification ledger
- Owner-facing setup handout source: Cacheboard Setup and Tasks
ROADMAP.md, NOTES.md, NOTES-multi-account.md, dated HANDOFF-*.md files, Cacheboard-Setup-and-Tasks.md and its generated PDF, and docs/superpowers/plans/ can contain useful rationale or procedures. They are not automatically current. A handoff or plan should carry a historical/superseded notice once implemented; a PDF is current only when regenerated from its source and visually checked.
When a change moves a source owner, alters a command, adds a product area, changes schema/auth/authority, or supersedes a contract:
- Update the canonical detailed document and its tests.
- Update this map or ARCHITECTURE.md only if navigation or system boundaries changed.
- Add a dated verification-ledger entry for newly executed evidence; never rewrite an old receipt into a current claim.
- Link instead of duplicating endpoint tables, DTOs, enums, and recovery steps.