Scaffold a code-side knowledge layer into a project: the build-documentation system that gives a repo memory across sessions. It's a convention refined across several real codebases — a vault of notes, a platform backend, a desktop app — that all needed the same thing: a way to stop losing the why between build sessions. This skill makes any new project match that convention.

Build sessions surface rationale — why an architecture was chosen, why an approach was abandoned, what's still open — that gets parked verbally and then lost. For a solo or small/contracted team, that loss is the real risk: strong documentation is the survival strategy, the way a small operation keeps a system alive. A knowledge layer captures the why next to the source, append-only, so the next session (or the same person months later) reconstructs intent instead of re-litigating it.

knowledge/
  CLAUDE.md              orientation: the three rules, code-map protocol, formats
  wiki/                  curated reference — one article per subsystem/topic, append-only context logs
  wiki/_codemap.md       auto-generated structural index (symbols + imports, tree-sitter)
  _codemap.json          machine copy of the structural index (modules, edges)
  journal/               per-session ADR-flavored entries, written continuously
  decisions/             atomic decision records (ADR format)
  wiki/roadmap.md        the parking lot
.claude/
  hooks/journal-breadcrumb.sh   auto-journals each git commit + nudges the agent
  hooks/codemap-refresh.sh      regenerates _codemap.md on source-file commits (background)
  settings.json                 wires both hooks (PostToolUse, gated to git commit)
.gitattributes                  union merge-driver on _codemap.md + _codemap.json

wiki/ is the curated layer. journal/ + decisions/ are the firehose. The split is the whole point: write hot and often to the firehose, compile cold and deliberately to the wiki. _codemap.md is the structural WHAT/HOW — auto-maintained, never hand-edited.

1. Journal continuously, wiki at the end. The journal is append-only firehose — write to it as you go: after a larger move, a longer code run, right after each git commit, or before a risky operation. Batching journal writes to session-end loses information (you forget, you compress, or the session crashes). The commit-breadcrumb hook automates the cadence. The wiki only changes via an explicit end-of-session compile pass — that keeps it intentional and the prompt cache stable.
2. Wiki updates need a real trigger — only three: a new subsystem/capability was added; a documented decision is now contradicted; or the user explicitly said "document this." No "just in case" rewrites.
3. Append-only, [[wikilinks]] everywhere. Never edit prior entries — if something's wrong, append a correction linking the contradicting source. Cross-reference with [[wikilinks]] so the graph is navigable for humans (Obsidian/file nav) and agents.

The full journal / decision / wiki frontmatter formats live in references/formats.md — read it when writing entries or when you need the exact templates to put in the project's knowledge/CLAUDE.md.

Run the init script from the target repo (or pass the repo path). It's idempotent and merge-aware — safe to re-run, won't clobber an existing knowledge/ or overwrite an existing .claude/settings.json (it merges the hook in).

bash ~/.claude/skills/knowledge-layer/scripts/init.sh [repo-path]

It creates the directories, installs the breadcrumb hook, merges the PostToolUse hook into .claude/settings.json, adds the hook's state file to .gitignore, and drops a template knowledge/CLAUDE.md with {{PLACEHOLDER}} fields if one doesn't exist already.

The template is generic; a knowledge layer is only useful if its orientation file reflects the actual project. Open knowledge/CLAUDE.md and:

• Replace every {{PLACEHOLDER}} — project name, a one-line description of what the project is, the language/stack.
• Fill in the "doc surfaces" section honestly for this repo. Most projects have more than one place docs live; spell out how they differ so they don't get confused. Common surfaces: this knowledge/ (build history), a docs/ or README (the plan / how-to), and any external source of truth. If the project reads an external knowledge store at runtime (like Amber reading a vault), note that it's unrelated to this build layer.
• Keep the three rules and the format templates verbatim (pull them from references/formats.md) — consistency across projects is the value; don't invent a per-project variant.

An empty knowledge layer has no gravity. Give it a starting mass:

• Decision records for the real decisions already baked into the project. Look at the architecture, the README, recent commits, and any "we chose X because Y" rationale. Write each as an ADR in decisions/ (format in references/formats.md), including the Dissent / Alternatives Considered section so rejected paths aren't re-litigated.
• A first journal entry in journal/YYYY-MM-DD-<slug>.md capturing where the project stands right now and what's next — a backfill of recent history if the project already exists.
• A few wiki articles only for subsystems that genuinely exist and have content worth curating. Don't create empty shells — speculative [[wikilinks]] to not-yet-written articles are fine (they mark gaps), but don't manufacture filler.
• Add a pointer from the repo-root CLAUDE.md (or README) to knowledge/CLAUDE.md so fresh sessions discover it.

Get the date right — convert "today" to an absolute YYYY-MM-DD for filenames and frontmatter.

The breadcrumb hook won't fire until Claude Code re-reads settings. If .claude/ was just created this session, the config watcher isn't watching it yet — tell the user to open /hooks once (reloads config) or restart the session. After that it's silent-automatic.

Then confirm it works: after the next git commit, a breadcrumb (### HH:MM — hash / subject / files) should appear in today's journal. If it doesn't, the watcher still hasn't picked up the config — /hooks or restart.

Two hooks fire on every git commit that advances HEAD:

journal-breadcrumb.sh appends a crash-proof breadcrumb (time, short hash, subject, changed files) to today's journal entry and nudges the agent to add the why while it's fresh. A HEAD-comparison guard means a blocked/failed commit never breadcrumbs, and reruns never double-write.

codemap-refresh.sh checks whether any source files changed in the commit; if so, it regenerates knowledge/wiki/_codemap.md + knowledge/_codemap.json in the background (time-boxed at 30 seconds, swallows all errors). Doc-only commits are skipped. This hook emits no agent note — breadcrumb already handled the commit notification.

Both hooks are not blocking gates: any error is swallowed and the commit succeeds. A broken codemap or missed breadcrumb never interrupts the build.

The skill generates and maintains a structural map of the codebase alongside the curated knowledge layer. The map is auto-generated by tree-sitter (deterministic, no LLM), never hand-edited, and refreshed automatically on source-file commits.

uv run --with tree-sitter --with tree-sitter-language-pack \
    python3 ~/.claude/skills/knowledge-layer/scripts/codemap.py [repo-root]

• Run this once after init to create the initial map.
• After that, codemap-refresh.sh runs it automatically in the background on every commit that touches source files.
• Languages supported: rust, typescript, tsx, javascript, php, python. Unknown extensions are skipped. If uv isn't in PATH the hook silently skips.

Per file: top-level symbols (functions, classes, structs/impls, exported consts, enums, traits, types) and import edges. Output is grouped by directory, sorted deterministically, and emits:

• knowledge/wiki/_codemap.md — agent-readable (consult before grepping)
• knowledge/_codemap.json — machine-readable (modules, symbols, import edges)

Symbols carry visibility (pub fn, export class) and, for Rust impl blocks, a compact list of public methods in []. Confidence tag: EXTRACTED.

Before asking "where does X live" or "what does Y import," read _codemap.md. It maps the structure in one pass; grep only to confirm or when the map is stale. The curated wiki and ADRs hold the why; the codemap holds the what/how.

init.sh registers git's built-in union merge-driver on both generated files via .gitattributes — merges never conflict, and the next commit's hook regenerates a clean file anyway.

Planned evolution and decisions-in-waiting for this skill live in references/. Current:

• references/roadmap-codemap.md — the design rationale for the code-map feature (items 1–5 are now built; the scoped-out list is unchanged).