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

# 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
│   ├── decisions/ # Numbered, append-only decision records
│   ├── 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`. Pages with `type: decision` add
`status`, `decided_on`, `decided_by`, `affects`, and `review_on`. `wiki/index.md` additionally
declares `kb_schema_version` for the bundle as a whole.
See AGENTS.md for the full schema.

## Decision Records
`wiki/decisions/` holds one numbered page per decision (`NNNN-slug.md`),
recording what was decided, by whom, on what date, why, and which earlier
decision it supersedes or reverses. Decision pages are **append-only**: the
substance is never rewritten to match a later change of mind — a new decision
supersedes the old one and both stay on the record, so "why is it like this?"
keeps its original answer. Decision-specific frontmatter is `status`,
`decided_on`, `decided_by`, and optionally `affects` and `review_on`; the
existing `supersedes`/`superseded_by` pair carries the history. The
`ckb-decide` skill records them and answers questions about them.

## Recursive Indexes
`entities/`, `graph/`, `decisions/`, 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.