ckb/wiki/overview.md

type	tldr	last_updated
overview	High-level map of the cascade knowledge base's directory structure, frontmatter schema, and layering rules.	2026-07-13

Knowledge Base Overview

This is the local (mutable) layer of a cascade knowledge base. It sits above read-only upstream KBs in ../linked/ and ../libs/.

Cascade Priority

1. wiki/ (local) — highest priority, agent-managed
2. linked/<name>/ (symlinked) — read-only upstream source of truth
3. libs/<name>/ (git-managed) — read-only external KBs

When the same entity exists in multiple layers, the local version wins.

Directory Structure

.
├── libs/         # Git-managed external KBs (read-only, gitignored)
├── linked/       # Symlinks to upstream KBs (read-only)
├── outputs/      # Generated artifacts from the wiki
├── raw/          # User-provided source material
│   └── inbox/    # Drop zone for unprocessed material
├── tmp/          # Temporary files, caches (gitignored)
├── wiki/         # Local structured wiki (agent-managed)
│   ├── query-gaps.md # Failed or missing-answer questions for demand-driven ingest
│   ├── projects/ # Optional local query scopes
│   ├── entities/ # Typed entity pages
│   └── graph/    # Edge lists and relationship data
└── workload/     # Summaries of discussions and decisions

Page Frontmatter

Every wiki page carries YAML frontmatter with a required type field, plus optional resource, tldr, confidence, quality, supersedes, freshness_window_days, and retention. wiki/index.md additionally declares kb_schema_version for the bundle as a whole. See AGENTS.md for the full schema.

Recursive Indexes

entities/, graph/, and optional topic folders such as projects/ each carry their own index.md so navigation stays lazy — read wiki/index.md first, then only descend into a subdirectory index if its contents are relevant to the current task.

Local-First Retrieval Aids

Project scope pages in wiki/projects/ can group related sources so a query starts narrow before falling back to the full cascade. wiki/query-gaps.md records questions the wiki could not answer yet, turning failed searches into small ingest targets.