Storage
Type: kb/types/note.md · Status: current
Commonplace stores data in three layers: authored markdown files under kb/, derived indexes rebuilt from those files, and a local SQLite database scoped to the review subsystem.
Authored markdown
All authored content lives as markdown with YAML frontmatter under kb/, tracked in git. Every file is readable and editable without tooling beyond an editor and grep.
| Directory | Contents |
|---|---|
kb/notes/ |
Transferable claims and theory |
kb/reference/ |
Shipped-system reference docs and ADRs |
kb/sources/ |
Ingested external sources |
kb/tasks/ |
Task lifecycle documents |
kb/work/ |
Workshop artifacts |
kb/instructions/ |
Skills and procedural guidance |
kb/types/, kb/*/types/ |
Global and collection-scoped type definitions |
Document type is declared by type: in frontmatter and validated against the matching schema, resolved from the owning collection's types/ directory with fallback to global kb/types/. See available-types.md and type-loading.md.
Derived indexes
Each surface below is derived from the authored markdown; none of it is committed. Complete generated listings exist only in the built site (ADR 025).
| Surface | What it covers | Where it is produced |
|---|---|---|
Directory listing pages (per-collection dir-index.md) |
Title, description, and type of every note in the directory | mkdocs hook, build time only |
| Per-tag generated listings (below each curated tag index) | Notes grouped by tag, minus already-curated entries | mkdocs hook, build time only |
| MkDocs static site | Entire kb/ tree, configured by mkdocs.yml |
mkdocs build |
Agents enumerate the same information on demand with the scoped rg recipes in navigation.md.
The redirect_maps block in mkdocs.yml preserves external URLs across note renames.
Generated reports
Generated reports record operational work products rather than curated library knowledge. Connect reports under kb/reports/connect/ are discovery artifacts produced by /cp-skill-connect and consumed by downstream workflows such as ingestion. They are intentionally gitignored because they are regenerable from the source artifact and current KB state; their absence from git status is expected.
Review state (SQLite)
Review state is the one subsystem that is not file-backed. The review database stores:
| Table | Contents |
|---|---|
review_jobs |
One row per review invocation/prompt, with freshness model_partition, nullable finalization-time runner provenance, queued/completed/failed status, created/completed timing, and packing |
review_pairs |
One row per requested (note_path, gate_path) pair inside a job, with nullable completed decision and reviewed snapshot IDs; model partition is derived through the parent job |
acceptance |
Current accepted baseline per (note_path, gate_path, model_partition) |
Prompt, bundle-output, manifest, and per-pair result paths are derived from the review job id, packing, and pair set. Acceptance is keyed by (note_path, gate_path, model_partition) and stored as one current row per key. current_gate_acceptances exposes only rows whose parent job is completed and whose review pair has a non-null decision. Selector logic reads current note and gate content from files and compares their hashes against accepted DB-owned snapshots. Successful supersede prunes obsolete review rows, unreferenced snapshots, and whole obsolete job artifact directories inline; there is no separate prune command.
Notes, gates, instructions, and source material remain file-backed. See ADR-010, ADR-032, ADR-033, ADR-034, ADR-035, and ADR-036 for the rationale.
See also
- documentation-site.md — how the MkDocs site renders these files, the README-vs-index rule, and the reader landing-page inventory
- architecture.md — installed project layout and surface-by-role
- ADR-010 — decision: SQLite for review state
- ADR-007 — decision:
kb/reports/for generated operational artifacts