Knowledge-Base Conventions

Scratchpad for kb writing patterns that haven’t been codified yet. The canonical schema — frontmatter fields, claim-typing callouts, page types, contribution-type taxonomy, decisions split, operating principles, hot cache, folder layout — lives in knowledge-base/CLAUDE.md. Don’t restate CLAUDE.md here. Use this page to surface co-evolved patterns before they migrate into the schema doc; once a pattern is firm, lift it into CLAUDE.md and delete the entry here.

Open conventions

Diagrams use Mermaid

Embed inline as a mermaid code fence (Quartz renders it). For C4-style architecture views, use C4Context / C4Container blocks. Mermaid lives next to the prose, is diffable, and doesn’t require an external rendering pipeline. Lift to CLAUDE.md once the team has shipped a few real diagrams and the convention has stuck.

Filename collisions

The schema requires globally-unique filenames across all pages directories. The bootstrap hit this with architecture/overview.md ↔ product/overview.md — resolved by renaming architecture’s to architecture-overview.md. If a general rule emerges (e.g., “always prefix folder-named pages with the folder”), promote it to CLAUDE.md.

Known schema deviations

source_platform enum vs. bootstrap doc

The bootstrap structure doc prescribed source_platform: note (Source) for its own contribution frontmatter, but the kb schema enum is confluence | jira | tldv | loom | slack | email | call | figma | github | qase | shopify | web | none — note is not a valid value (it’s a type:, not a source_platform:). Filed with source_platform: none as the closest schema-valid value. Either the schema should add note (signaling “self-authored note, no external platform”) or self-authored sources should consistently use none. Decide and update.