Knowledge: small, linked, tagged files

Project knowledge lives in docs/ as small, dense, linked, tagged markdown files. Markdown is the only source of truth.

Why

Small files

• One concept per file, ~<150 lines. Split rather than grow.
• Link related files relatively. A file nothing links to is a smell.
• If a section needs a heading to be findable, it probably wants its own file.

Frontmatter on every doc

---
title: Invoice computation               # str, required
tags: [billing, domain]                  # list[str], only from docs/tags.md
code: [src/pkg/billing.py::compute_invoice, src/pkg/io/]   # path or path::Symbol
---

code: is covered by freshness. ADRs and papercuts add status (ADRs, papercuts).

Controlled tag vocabulary

docs/tags.md: one tag per line with a one-line meaning.

• Tags only from docs/tags.md.
• If none fits, add one there in the same change.
• When adding a tag, look at the existing ones first.

Seed vocabulary: scaffold/docs/tags.md: meta, domain, architecture, ops, dev, qa. The catch-up prompt derives 10–20 tags from what the docs actually cover.

Layout

QA.md                  operational, at the project root (see QA)
docs/
  README.md            index
  style.md             writing rules
  tags.md              vocabulary
  architecture.md      current state
  adr/NNNN-slug.md     decisions
  papercuts/slug.md    friction
  <concept>.md         everything else, one concept each

Scaffold index: scaffold/docs/README.md. Writing rules: scaffold/docs/style.md: read before writing any doc.

Search

None built. Agents use ripgrep over frontmatter and text. No stored index either: files are edited directly, so an index would go stale.

Interplay

Tooling

raw markdown