ckb/docs/MANUAL.md
Michał Kopeć 6427567a0b Template 2.0.1: 3.8 compatibility, routines --mark, exporter containment
Fixes F1-F5 from the 2.0.0 script review:
- removeprefix/removesuffix (3.9+) replaced; lint, retrieve and
  consolidate crashed on Python 3.8 with any graph edges
- routines.py --mark wrote `last_run:DATE` (invalid YAML) and swallowed
  trailing comments into the value
- export_okf.py --out must be inside outputs/ (it is rmtree'd);
  export_starlight.py image copies confined to wiki/assets/
- script counts in AGENTS.md, READMEs and manuals

New tests/unit/ (stdlib unittest, run from smoke.sh): 3.8 API guard,
routines round-trips, exporter containment, AGENTS.md consistency.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 14:26:10 +01:00

69 KiB

User Manual

Read this in: English | Polski

First time here? The one-page Quickstart gets you from an empty folder to your first answer.

This is the human-facing manual for working with a Cascade Knowledge Base (this repo). It's written for the person using the wiki, not the agent. For the agent's own operating rules, see AGENTS.md / CLAUDE.md. For a feature-by-feature technical overview, see README.md. For the page schema in full and the version histories behind it, see CHANGELOG.md. This document is task-oriented: "I want to do X - what do I say, and what happens?"

Everywhere below, "say" means typing it to whatever AI coding agent you're using against this repo (Claude Code, or another agent that reads AGENTS.md). You don't need exact wording - the trigger phrases shown are examples, not magic words; the agent matches intent.


Contents

  1. Creating or initialising a wiki
  2. Adding knowledge
  3. Keeping it tidy
  4. Syncing - with yourself, and with other people
  5. Upgrading the template
  6. Use cases
  7. What's agent-generated vs. what you can edit
  8. Quick reference

1. Creating or initialising a wiki

Prerequisites

The agent does almost everything by reading and writing Markdown. Eight skills additionally run a small Python 3.8+ script (standard library only, nothing to pip install): lint (including the check the agent runs at every session start), retrieval ranking, inbox duplicate detection, routines, consolidation reports, saving conversations, and the two exporters. Python is recommended, not strictly required:

Without Python What happens
Session-start health check A bash fallback runs instead (on Windows, under Git Bash, which comes with Git for Windows). It covers malformed pages, stale pages, changed sources and the commonest secret shapes, and says that crux quotes and the context budget were not checked.
"Ingest" duplicate check The agent compares sha256sum digests of inbox and archive files by hand and skips the URL comparison.
"Lint" The agent works a manual checklist with grep. It's slower and scoped, and it says what it skipped.
Questions The agent ranks candidates by hand from the indexes and grep instead of the fusion script.
OKF / Starlight export Not available until Python is installed.

The agent tells you once per session when it cannot find an interpreter, then continues on the fallback paths. To install Python:

  • Windows: winget install Python.Python.3.12 in a terminal, or the Microsoft Store "Python 3.12" app, or the installer from python.org (tick Add python.exe to PATH). Afterwards python --version or py -3 --version should print Python 3.x. If python opens the Store instead, turn off the App execution aliases for python.exe in Windows Settings, or use py -3.
  • macOS: brew install python with Homebrew, or xcode-select --install for the Apple-shipped python3.
  • Linux: sudo apt install python3 (Debian/Ubuntu), sudo dnf install python3 (Fedora), sudo pacman -S python (Arch). Most distributions already have it.

Any of python3, python or py -3 is fine; the agent tries them in that order.

If you're reading this inside an existing Cascade KB

Nothing to do - the structure already exists (wiki/, raw/, outputs/, etc.). Skip to §2.

Starting a brand-new one elsewhere

Say:

"Set up a new wiki like this one in ~/projects/my-notes."

This clones the schema only - the directory structure, the AGENTS.md/CLAUDE.md behaviour file, and an empty wiki/ scaffold - into the target folder. It never copies this project's actual content (no entities, no graph data, no notes). You get a fresh, empty KB, ready for its first raw/inbox/ drop. See .agents/skills/ckb-init/SKILL.md.

The template can come from two places: this repo's own files, or a fresh shallow clone of the canonical template repo (or any fork/mirror URL you name) pulled into a scratch folder. Say "pull the latest template and set up a KB in <folder>" - or run it from outside any KB at all - and the agent clones first, then builds the scaffold from that. The clone is scratch only: the new KB gets its own git history (the agent asks before running git init), not the template's.

If the target folder already looks like a KB (it has a wiki/ or AGENTS.md already), the agent stops and asks before touching anything. It won't silently overwrite an existing knowledge base.

Building on top of someone else's wiki

A Cascade KB can sit on top of one or more upstream knowledge bases, which stay read-only. There are three ways to mount one:

  • Symlink (another KB on your own machine, or one you maintain elsewhere and want live-linked):

    ln -s /path/to/other-kb ./linked/other-team
    
  • Git clone (an external KB you want a frozen, version-controlled copy of):

    git clone https://github.com/org/external-kb ./libs/external-kb
    

    Don't want to use git? Most git hosts also offer a "Download ZIP" option on the repo's page - download it and unpack the contents straight into ./libs/external-kb instead. You end up with the same frozen, read-only copy either way. The only difference is that you can't git pull it later to refresh it; to update it, re-download the ZIP and unpack it over the old contents.

  • Connector (a live external source you don't want a full local copy of - a SharePoint folder, a Google Drive folder, or another connected source): create libs/<name>/source.yaml yourself:

    connector: sharepoint
    location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
    description: "Finance team's shared reports folder"
    

    then say "index external sources." The agent reads the config, connects to whatever's available that session (a connected Microsoft 365/Google Drive tool, or a plain URL fetch), and builds a short index of what it finds - one entry per document - inside that same libs/<name>/ folder. See §6 for a worked example and what the result looks like.

    Before you rely on a connector source:

    • You don't have to build the index yourself. source.yaml can add an index: block pointing at an already-built index - a git repo, or a shared resource - so you fetch what someone else already indexed instead of scanning the live source yourself. Every run checks that location first: if there's already an index there, you get it. If there isn't one yet (the normal state before anyone has run this with write access), that's not an error: the next run by whoever has write access creates it and publishes it there for the first time.
    • Building and refreshing are opt-in, per person, per source. By default, everyone is read-only for a connector source - nobody's agent will scan the live connector on their behalf unless they've explicitly said so. Say "make me the admin for <source>" to opt yourself in (this writes a local, personal libs/<name>/source.local.yaml - never committed, never seen by anyone else). One or two people maintain a source for the whole team; nobody else re-scans it.
    • You can set how often it should be refreshed. Add an optional refresh_interval_days: 7 to source.yaml (it defaults to 30). A folder that churns daily wants a shorter window than a quarterly archive nobody touches. Both "index external sources" and "Lint" then tell you when a source is overdue and by how much. That matters most if you're read-only for it: once you know which source has gone stale, you can ask the person who maintains it.

Either way, once it's mounted, ask questions normally. The agent checks your local wiki/ first, then walks linked/, then libs/, and uses whichever has the answer. You never edit files inside linked/ or a git-copy libs/<name>/ directly; if something there is wrong or outdated, you fix it by writing the corrected version into your own local wiki/, which always wins. (A connector-backed libs/<name>/ is the one place the agent does write on your behalf - see §6 - but only its generated index, and only the build/refresh part if you're that source's admin; source.yaml itself always stays yours to edit, never the agent's.)


2. Adding knowledge

This is the main way the wiki grows. There are five ways in:

A. Drop material, then say "Ingest"

Put anything unprocessed into raw/inbox/ - pasted notes, a .txt transcript, a links.txt of URLs, a PDF, a messy scratch file. No need to organise it first. Then say:

"Ingest." (or "Update the wiki" - same thing; never a phrase with "sync" in it, that is git)

Example:

You drop meeting-2026-07-10.txt (rough notes from a client call) into raw/inbox/, then say "Ingest."

The agent reads the file, extracts the people, decisions, and open questions mentioned, creates or updates entity pages under wiki/entities/, records relationships in wiki/graph/edges.json, adds the new pages to wiki/index.md, logs the change in wiki/log.md, and moves the original file to raw/archive/2026-07-10/. It finishes by reminding you to review the result and say "sync changes" once you're happy with it.

For a long transcript, the agent does more than write one summary page. It pulls out the searchable question, the summary, the resolution, the systems and people involved - and promotes individual passages to their own findable sections when they'd otherwise be lost inside a summary. That last part has a deliberate bar: a passage has to contain a specific term (a flag, an error string, a clause, a version), run to a couple of sentences at least, and be corroborated by something later in the material. Otherwise it stays folded into the summary. Without that bar every paragraph looks quotable and the wiki page ends up being the transcript again, which defeats the point of ingesting it.

If raw/inbox/ is empty, the agent scans raw/ directly instead (still skipping raw/archive/, which is already-processed history).

Three things happen before anything is written:

  • Duplicates are caught. A script compares every inbox file with raw/archive/ and with the sources wiki pages already cite. A file you already ingested (byte for byte, or the same text saved again with different line endings), a link to a page the wiki already cites, or two copies of the same file in the inbox are reported as "already ingested on → ". The agent asks before skipping any of them.
  • The agent checks in. For each source it tells you in three or four lines what it read it as saying, which pages it will create or change, and what it contradicts. Then it waits. Correct it here; it is far cheaper than fixing pages afterwards. Say "ingest in batch" (or "no check-in") to skip this, for example for a large pile you trust. An ingest run by a routine with confirm: false skips it too.
  • Private passages stay out. Anything you wrap in <private> … </private> in a source is never written into the wiki, quoted, or summarised.

Pages the agent creates start as review: draft, meaning no person has checked them yet. When new material disagrees with a page and it isn't clear which is right, the agent doesn't pick a winner. It writes a marker into the page and tells you:

> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02

The marker stays until you settle it (see "Review, contradictions and tags" under Keeping it tidy).

Skill: .agents/skills/ckb-ingest/SKILL.md.

B. Just tell the agent something in conversation

You don't always need a file. If you tell the agent a fact with lasting value, such as "actually, the deadline moved to September", the agent can file it straight into wiki/ as a new page or an update to an existing one, the same as it would from an ingested file.

C. Let the agent tell you what's missing (Demand-Driven Context)

If you ask something the wiki can't answer, the agent doesn't fail silently. It identifies the gap and proposes a minimal page to fill it.

Example:

You: "What's our policy on X?" Agent: "The wiki doesn't cover that yet. Want me to add a stub page for it, or can you paste/describe the policy and I'll write it up?"

You approve, paste the source, or drop it in raw/inbox/ - the next ingest incorporates it. This keeps the wiki demand-driven: it grows around what you actually ask, not everything that could theoretically be written down.

Durable misses can also be tracked in wiki/query-gaps.md. A good gap entry is tiny: the question, where the agent looked, and the smallest source or page that would make the answer available next time.

D. Record a decision

When a call gets made - a technology choice, a process change, a policy - say:

"Record a decision: we're moving billing to Postgres. Alice and Bob decided it today, because the reporting queries were killing MySQL."

The agent writes a numbered record under wiki/decisions/ with the decision, who decided, when, the rationale, the alternatives, and what it affects. If it replaces an earlier decision, it links the two in both directions and marks the old one superseded - without touching the old page's reasoning. Anything you leave out, it asks for in one round; if you're mid-flow, say so and it records what you gave it and tells you which fields it left open.

Then ask about them however you like:

"What did we decide about the billing database?" "Why do we use Postgres?" "Who decided that, and when?" "Which decisions are still just proposed?" "What superseded decision 3?"

The answer always comes with who and when attached, and says plainly when a decision is proposed rather than accepted, or has since been superseded - so you don't act on something that isn't in force. Skill: ckb-decide.

Two rules:

  • Decisions are append-only. "Actually, we changed our mind" creates a new decision that supersedes the old one; it never edits the old one's reasoning. The history is the point. Plain transcription errors ("I said Alice, it was Anna") do get fixed in place.
  • A proposal is not a decision. If it wasn't actually settled, it's recorded as proposed with no decision date, and shows up when you ask what's still open.

E. Create a local project scope

When a topic, client, system, or initiative comes up often, ask:

"Create a project scope for payments integration."

The agent creates or updates a plain Markdown page under wiki/projects/ listing the pages, entities, raw/archive files, connector indexes, and graph areas that should be searched first for that scope. You still keep one local wiki; this just gives repeated questions a better starting area.

A scope page can also carry your team's rules for that project, in a ## Rules section you write yourself: "name environments prod/stage, never production", "decisions here need the client's sign-off". The agent follows them whenever it works inside that scope, and no skill ever rewrites them. Only AGENTS.md overrides them.


3. Keeping it tidy

Say, whenever you like - after a big ingest, or just periodically (or let a routine do it for you):

"Lint."

This runs a health check across the whole wiki:

  • pages missing required frontmatter (type) get flagged
  • pages that haven't been touched in a while get flagged as stale
  • confidence scores decay if nothing has reinforced them recently
  • old, low-priority pages get archived to wiki/archived/ (never deleted)
  • contradicting pages get linked old→new (supersession)
  • orphaned pages (nothing links to them) get backlinked or archived
  • broken graph edges get fixed or removed
  • missing/duplicate index and log entries get corrected
  • connector-backed sources whose index is overdue for a refresh get flagged, with how overdue they are - useful even if you're read-only for that source, since it tells you who to chase
  • pages whose source has actually changed get flagged - see below
  • quotes that no longer appear in the source they cite get flagged
  • recurring systemic issues get written into wiki/error-book.md
  • credentials committed by accident (keys, tokens, private keys, a password in a URL) anywhere in wiki/, outputs/, workload/ or raw/, and any <private> passage that leaked into a wiki page, get flagged - never auto-fixed, see below
  • kept answers in outputs/answers/ whose sources have changed get flagged
  • the always-loaded layer (AGENTS.md plus every skill description) gets flagged when it grows past the budget in ckb.yaml

The two source checks (changed fingerprints and quotes that no longer match) are the difference between "this page is old" and "this page is wrong".

Every page records a fingerprint of the material it was built from. Staleness by date is a guess: a page written a year ago may still be perfectly accurate. A fingerprint is not a guess - the agent recomputes it and either the source is byte-for-byte what the page was written against, or somebody edited it. When a source changes, the page built on it goes to the top of the list, ahead of anything that has merely aged.

Pages also quote their sources directly, in a ## Crux section - a few verbatim lines carrying the actual claim, underneath the agent's summary of it. Two things follow from that. When you ask a question, the agent can often answer from the quote instead of re-reading the whole source, and show you the words rather than its paraphrase of them. And when a quote stops matching its source, that's a page asserting, in quotation marks, something its evidence no longer says - the strongest finding lint produces, and the agent will never "fix" it by quietly editing the quote to match.

The detection half runs as a read-only Python script (scripts/lint_report.py; without Python, see Prerequisites for what still runs), so the same wiki always produces the same findings list. The agent reads that report and then does the parts that need judgment (supersession, ambiguous orphans, error-book entries, and deciding what to fix versus what to hand back to you). It fixes what it safely can on its own and reports the rest for you to decide. Like Ingest, it finishes by reminding you to review and sync. Skill: .agents/skills/ckb-lint/SKILL.md.

Secrets. A key found in the repo is reported with only its first four characters, never in full. The fix is yours: remove it, and rotate it - once a secret is committed it stays in git history even after the line is gone. A harmless match, such as an example key in documentation, can be allowlisted: the finding prints a <path> <hash> line to add to .secrets-allow at the repo root. The hash covers that one line, so editing the line brings the finding back. The same check runs before every "sync changes" commit.

Review, contradictions and tags

Review. A page can say whether a person has checked it: review: draft (the agent wrote it, nobody checked), reviewed (with reviewed_by and reviewed_on), or needs_update (it was reviewed, then changed or was contradicted). Ask "what needs review?" for the queue, needs_update first. Say "mark X as reviewed" once you have read a page; the agent records your name and today's date and never marks a page you did not name. If a reviewed page later changes, lint notices. Answers built on draft pages say so.

Contradictions. Lint lists every open > CONTRADICTION: marker. Settle one by saying which side is right. The agent then either supersedes the wrong page, records a decision ("record a decision: we retry five times"), or edits the claim, and removes the marker.

Tags. A page may carry tags: retries, billing, but only tags listed in wiki/tags.md. Add a row there before using a new tag; lint flags any tag that isn't listed. Questions can then be narrowed by tag.

Cold pages. The agent notes which pages it actually reads, in tmp/access.log on your machine (never committed). "Which pages has nobody read lately?" runs lint --cold and proposes moving those pages to an ## Archive section of their index, so they're consulted last. It only proposes; nothing is moved, renamed or deleted, and pages marked retention: high are never proposed.

Context budget. Every session starts by loading AGENTS.md and the one-line description of every skill. That costs tokens before you have said anything. Lint estimates the cost (characters ÷ 4) and flags it when it passes budget: always_loaded_tokens in ckb.yaml (9000 by default). Ask "show the context budget" for the breakdown.

Starting a session: the brief, open threads and the hook

At the start of every session the agent runs one script and gets a short brief: who you are (your git identity), the git state, the one-line health check, due routines, and the last note from workload/. It acts only on the lines that need it.

Open threads. When a session ends with something unfinished, the agent writes it in that day's workload note under ### Open threads as - [ ] item. The brief counts open threads across all notes and lists the oldest few, marking any older than 30 days. To close one, tick it where it was opened (- [x]), or write - [x] dropped: <why>. Nothing is ever deleted, so the notes stay a record. This is the KB's "what's in flight now" view: there is no separate status file to keep in sync.

The session-start hook (Claude Code only). By default the agent runs the brief itself as its first action. With the hook, Claude Code runs it before your first message and runs it again after the conversation is compacted, so the brief never falls out of context in a long session. To turn it on, say "turn on the session-start hook". The agent sets session: start_hook: true in ckb.yaml and, after asking, installs the hook in .claude/settings.local.json. That file is per machine and never committed, because a hook committed to git would run code on every clone. Teammates on other machines see a start hook: line in their brief and are asked once. Other agents ignore the setting and keep running the brief themselves.

Consolidation and topic summaries

Ingest adds knowledge one source at a time; nobody steps back to see the whole. Say:

"Consolidate."

The agent writes a report to outputs/reports/<date>_consolidation.md and changes nothing in the wiki. It lists:

  • topics: groups of related pages (a project's members, pages sharing a tag, linked groups), each marked missing, current or outdated;
  • merge candidates: two pages that seem to say the same thing;
  • missing links: pages citing the same sources that don't link to each other;
  • stale or changed pages;
  • old log entries, counted by month. The log itself is never rewritten.

You pick what to act on. "Build the topic summaries" writes wiki/topics/<name>.md: one page that says what the KB holds overall about that subject, listing its member pages with fingerprints. When a member changes, lint flags the topic as outdated. Questions like "what do we know about payments overall?" start from these pages, and the agent still checks the member pages before answering. A fortnightly routine that asks first suits this well: "consolidate every two weeks, ask me first". Skill: .agents/skills/ckb-consolidate/SKILL.md.

Routines: do it for me every N days

Anything you would say to the agent can be made a routine:

"Lint every week." "Index external sources every 30 days, but ask me first."

The agent records it in ckb.yaml under routines: (name, the phrase to run, the period, whether to ask first, and the date it last ran). A routine is time-since-last, not a calendar: at the start of every session the agent checks which routines' periods have elapsed, answers whatever you asked first, and then runs the due ones in the same turn, reporting each in one line. One marked "ask me first" is offered at the end of the reply instead and runs only on a yes. A routine that fails or is declined is not marked done, so it comes back next session. Doing the action by hand counts too - saying "Lint" yourself resets the weekly lint's clock.

Because the last-run date is committed with the repo, a routine fires once per period for everyone sharing the KB, not once per machine. Two actions cannot be made routines: resetting the wiki and syncing with git. "List routines", "which routines are due", "run the routines now" and "remove the weekly lint" do what they say. This is not Claude Code's cloud scheduler: nothing runs while nobody has the KB open. Skill: .agents/skills/ckb-routine/SKILL.md.

Starting over: resetting to a clean template

Sometimes you want the shape of a knowledge base without its contents - typically because this repo doubles as the template you hand to other people, and it has accumulated decisions, workload summaries and entity pages that shouldn't ship with it.

"Reset the wiki." / "Make this a clean template."

This is the one command in this repo that deletes knowledge on purpose, so it is built to be hard to trigger by accident:

  1. It looks for a restore point first. If your working tree is dirty it stops and offers to commit, because after a reset anything committed is a git checkout away and anything uncommitted is simply gone. It can also tag the commit (pre-reset-<date>) so you don't have to keep a hash in your head.
  2. It asks how far to go. Six tiers, chosen individually: wiki knowledge, workload history, raw/ source material, outputs/, external sources, and installed modules. Only the first is on by default. libs/, linked/ and modules default to no - linked/ holds symlinks into other people's knowledge bases, and it will remove a link but never follow one.
  3. It counts before it asks. You get an inventory - how many pages, how many decision records (listed by number and title), how many graph edges, plus anything marked retention: high - and one line on what survives.
  4. It wants a typed phrase, not a "yes". And if you change the scope in your reply, it re-counts and asks again, because you agreed to a number and the number moved.
  5. It verifies afterwards, running lint before telling you it worked.

What it restores is exactly what ckb-init would create: same directories, same scaffold files, same kb_schema_version. Emptying the content doesn't roll back the schema.

What it never touches, with or without confirmation: the template layer (AGENTS.md, .agents/, LICENSE, VERSION, the docs) and src/, which holds independent code repositories this command has no business deleting.

One deliberate quirk: unlike every other skill, this one does not write a workload/ session note - that entry would be the first thing in a directory it has just emptied. It tells you so in its report.

Skill: .agents/skills/ckb-reset/SKILL.md.


4. Syncing — with yourself, and with other people

There are two different kinds of "sync" here. Don't confuse them:

Ingest / Lint Sync changes
Layer Content (what the wiki knows) Git (whose disk has which files)
What it touches wiki/, raw/ The repo's commit history and origin remote
Say "Ingest" / "Lint" "Sync changes"

Reconciling with origin (git-level sync)

Say:

"Sync changes."

This commits whatever local changes you have (e.g. from a recent Ingest or Lint pass), pulls down anything new from origin, merges the two, and - if there's a conflict - walks you through it file by file, asking you to keep your version, keep the remote version, or supply merged text for each conflicting block. Once everything's resolved, it pushes.

If this repo has never been connected to a remote, the agent will ask you to paste the URL first:

Agent: "This repo has no origin remote configured. Paste the URL of the remote repository and I'll add it as origin."

You: https://git.wierzbowa.cloud/michal/ckb

For this Cascade KB, the canonical, always-up-to-date copy is the source repo at git.wierzbowa.cloud/michal/ckb. If you're not sure whether your local checkout is current, check against it.

You don't have to git clone it to get a working copy, either. If you'd rather not use git at all, download it as a ZIP from that page and unpack it locally: you get the exact same files and can point your agent at the unpacked folder right away. What you won't have is a configured origin, so "sync changes" and "upgrade the wiki" have nothing to push to or compare against yet. When you're ready for those, run git init in the unpacked folder and add the URL above as origin (git remote add origin https://git.wierzbowa.cloud/michal/ckb).

From then on, "sync changes" reconciles against that remote. This is how multiple people share one wiki: everyone ingests/edits locally, and "sync changes" is how each person's changes reach everyone else - and how theirs reach you. Before it commits, it checks what is about to be committed for secrets (see Keeping it tidy). If it finds one, it stops and asks, and commits anyway only if you say so explicitly. Skill: .agents/skills/ckb-sync-changes/SKILL.md.

The agent also nudges you about this automatically: at the start and end of a working session it does a quick, read-only check for anything uncommitted or unpushed, and tells you if "sync changes" is worth running. It never pushes unless you ask. At the end of a session that did real work, it also asks once whether you want the conversation saved (see "Save a conversation" under Use cases) - and saves only if you say yes.

Building a shared cascade (KB-level sync)

If instead of one shared wiki you want your own wiki that builds on someone else's - e.g. your team's KB overlaying the company-wide KB - that isn't git sync at all; that's the linked//libs/ mounting described in §1. Each person/team keeps their own local wiki/ (which always wins), and upstream KBs update on their own schedule, independently.


5. Upgrading the template

This is a different kind of "keeping current" from anything in §4: that section is about your own KB's own remote - sharing your content with your collaborators. This section is about catching your KB's tooling up with improvements made to the canonical Cascade KB template itself, wherever your KB originally came from (ckb-init, a clone, a fork, or a KB that's been around long enough to predate some of these conventions).

Say:

"Upgrade the wiki." / "Check for a newer template version."

Which channel you're pulling from

The template repo keeps four branches, and by default you get the stable one:

Branch What it is Who should be on it
main Stable - the released template You, unless you have a reason not to be
test Release candidate - validated before it reaches main You're helping validate a release, or you need a fix that's landed but not shipped
experimental Development - active work, may be broken or reverted You're developing the template itself
1.x Maintenance - the 1.x line after 2.0: fixes only; the last line with PowerShell support You need PowerShell, or can't move to 2.0 yet

To use a different one, say which:

"Upgrade from the test branch." / "Check experimental for updates." / "Switch this KB back to the stable channel."

Whichever you pick sticks - it's recorded in ckb.yaml, so the next upgrade stays on the same channel rather than quietly pulling you back to main. The same goes at creation time: "initialize from the experimental branch".

One thing to watch. If you're tracking test or experimental, your KB can sit on a version main hasn't released yet. Checking against main then finds nothing newer - the agent will tell you you're ahead, not that you're up to date, because those are different situations. Going back to main from there is a downgrade: it can remove skills and roll the schema back below what your pages are written against. You'll be asked to confirm explicitly, and it's refused outright if your content would stop conforming to its own declared schema.

A new major version (1.x → 2.0) removes something a KB may rely on, so the agent never crosses one quietly, not even from a routine. It names what the new major removes, from the changelog, and asks: take it, or move this KB to the 1.x maintenance branch ("switch this KB to the 1.x branch"), which keeps getting fixes but no new features.

What gets checked

Two separate things get checked, and either, both, or neither might turn something up:

  • The template/tooling layer - AGENTS.md/CLAUDE.md, every skill under .agents/skills/, LICENSE, VERSION, and the README/MANUAL docs. Compared against the canonical repo's own VERSION file.
  • Your wiki content's own schema version - the kb_schema_version field in wiki/index.md, compared against what the template currently expects. A KB can be fully current on tooling but still carry wiki/ content built years ago under an older (or entirely missing) kb_schema_version - or the reverse.

If nothing's behind on either front, you get "already up to date - template vX, wiki schema vY," and nothing changes.

If the template layer is behind, you'll see a breakdown of what's new (nothing local to lose) versus what's changed (a template file whose local copy differs - either a template improvement or a customization you made on purpose, e.g. to AGENTS.md). You get asked, file by file or all at once, to take the template version, keep yours, or see the full diff first - nothing gets silently overwritten.

If your wiki content's schema is behind (including the common case of an older KB with no kb_schema_version at all - an "unversioned" wiki), you'll get a distinct, explicit question:

Agent: "Your wiki/ content was built without a kb_schema_version (or an older one). Would you like me to also upgrade all wiki-related folders and data to the new standard?"

If you say yes, the agent:

  • adds any missing scaffold pieces (e.g. a wiki/graph/index.md that never existed if your KB predates the graph feature),
  • backfills missing frontmatter on existing pages - tldr, confidence, quality, retention, and so on - without rewriting anything you've actually written; only structure and metadata get added, never the substance of a page,
  • confirms with you before assigning a type to any page where it isn't obvious,
  • logs every touched page in wiki/log.md as a migration entry so it's clear the change was structural, not new knowledge,
  • and bumps kb_schema_version once done.

If you say no, nothing under wiki/ is touched at all - not even kb_schema_version - so the next time you run this, it's still correctly flagged as behind rather than silently considered handled. These two decisions (template layer, wiki content) are independent: you can accept one and decline the other.

Like Ingest and Lint, this finishes by reminding you to review the result and run "sync changes" against your own origin - the template repo it just checked against is a separate remote for any KB other than the template project's own working copy. Skill: .agents/skills/ckb-upgrade/SKILL.md.


6. Use cases

Ask questions

Ask in plain language:

"What do we know about the Q3 migration risk?"

The agent reads wiki/index.md first to find relevant pages. If a matching project scope exists under wiki/projects/, it searches that scope first. Then it runs retrieve_candidates.py, which gathers exact-match, tldr, project-scope, graph and trust signals into one fused ranking, expands context around matching sections, walks the knowledge graph for connected facts, and falls back to linked//libs/ if the local wiki has nothing. You get an answer grounded in what's actually written down, not a guess.

Two details matter as a user:

  • It searches raw/inbox/ too. Something you dropped in this morning and haven't ingested yet can still answer your question. The agent will tell you when an answer came from un-ingested material, which doubles as a nudge that "Ingest" is overdue.
  • Answers carry their own caveats. If the page behind an answer is past its freshness window, scored low on confidence, or was read from a cached connector index instead of a live check, the answer says so next to the claim. If two pages disagree and neither has been marked superseded yet, you'll hear about that too. You never have to read the frontmatter yourself to know how much to trust what you just got.
  • It finds the section, not just the page. A search index of every page section (kept in tmp/, rebuilt automatically) lets the agent read just the section that answers you, and it knows what a full page would cost to read. When an answer is really a table, a chart, a deck or a web page, the agent offers that once.

When an answer took real work (several pages pieced together, a source re-read), the agent offers once to keep it. Say yes and it goes to outputs/answers/<date>_<question>.md, with the sources it rests on (fingerprinted, so lint tells you when they change) and a ## Gaps section listing what the KB could not answer. Ask the same question again later and the agent offers to update the kept answer instead of writing a second one. If the answer holds something the wiki itself should know, the agent offers to file it back. That means a normal ingest, with the same check-in, so a kept answer never edits the wiki on its own. Private passages (<private>) are never quoted in an answer.

Ask who knows something

"Who knows about the checkpoint restore path?" / "Who owns the billing service?"

These are answered from the knowledge graph directly rather than by keyword-searching for names. Ingest records an expertise or ownership edge when the source material actually shows someone answering questions on a topic or holding declared responsibility for it - not from having attended a meeting or from a job title. If nobody has a recorded edge yet, the agent falls back to who the archived sources show answering that kind of question and tells you it's inferring rather than reporting.

When there is still no answer, the agent should tell you what is missing and either add/propose a short entry in wiki/query-gaps.md or suggest the smallest source to drop into raw/inbox/.

Learn from the wiki

Quick test of what you know - say:

"Quiz me on the onboarding process."

You'll be asked how many questions and what format (open / multiple choice), then run through them one at a time with immediate feedback and a running score. Nothing is saved afterward - it's a one-off check. .agents/skills/ckb-quiz/SKILL.md.

A proper course, spread over time - say:

"Teach me the wiki." / "Teach me about the supplier onboarding process."

The first call plans a curriculum: it asks whether you want one session or a series, how long each session should be and how often, and whether you'd like a calendar .ics file with reminders. It then chunks the material into session-sized portions (erring toward one more short session rather than cramming) and shows you the plan before saving anything. Later, saying "next lesson" (or similar) picks up where you left off, teaching using a different technique each time - Socratic questions, analogies, worked examples, teach-back, mnemonics - and briefly checking what stuck before moving on, re-teaching anything shaky. Plans and progress live under outputs/teaching/<topic>/. .agents/skills/ckb-teach-me/SKILL.md.

A guided reading order without a full course - say:

"Onboard me on the payments integration." / "Where do I start with X?"

You get a short overview plus an ordered reading list - foundations first, then the topic, then what builds on it - built by walking the knowledge graph outward. Read-only; nothing is saved. .agents/skills/ckb-onboard-me/SKILL.md.

Find out what you, or the wiki, are hand-waving about - say:

"Feynman me on the Atlas retry policy." / "What am I fuzzy on?"

The agent reads the page and its sources, explains it in plain words with one concrete example, and links each block to the section it came from. Then it lists every place the explanation went thin: the page is vague (fix it with Lint or Ingest), the sources never covered it (a new source is needed), or the agent itself could not make it simple. It does not fill gaps from its own knowledge. Last, it asks you to explain one part back, so your own gaps show too, and ends with numbered next moves. With no topic, it suggests draft, single-source or stale pages. Sessions are saved to outputs/teaching/feynman/; nothing in wiki/ changes unless you agree to record a gap in wiki/query-gaps.md. .agents/skills/ckb-feynman/SKILL.md.

Generate documents / share knowledge outside the wiki

A quick top-level snapshot - say:

"Give me a project summary." / "Where do things stand?"

Regenerates PROJECT-OVERVIEW.md at the repo root: a one-to-two-page overview, current state, open actions with status, risks, and assumptions, all synthesised from the current wiki. It's fully overwritten each time, so it always reflects what the wiki says right now. .agents/skills/ckb-project-summary/SKILL.md.

A machine-readable export for other tools - say:

"Export the wiki as OKF."

Produces an Open Knowledge Format bundle at outputs/okf/, consumable by generic OKF tooling (e.g. a graph visualiser) without needing to understand this wiki's own richer schema. .agents/skills/ckb-export-okf/SKILL.md.

A human-readable documentation website - say:

"Export the wiki to Starlight." / "Build a docs site from the wiki."

Produces an Astro + Starlight-ready site at outputs/starlight/ - real pages, real navigation, something you could host and hand to someone who's never seen the wiki. .agents/skills/ckb-export-starlight/SKILL.md.

A document you write often, from a template - say:

"Prepare a new document using template status-report." / "New status report from the template, for Atlas, last two weeks."

Templates live in templates/, one Markdown file each. The headings give the document its shape; an HTML comment under each heading tells the agent what goes there - "ask the user", "take this from the project's wiki page", "three sentences, no bullets". The agent reads the template, asks you its questions in one go, pulls the rest from the wiki, and writes the finished document to outputs/documents/. Anything it could not find becomes a TODO: line in the file, never a guess. One example ships with the template, templates/status-report.md, and templates/README.md explains the format in a page. Say "make a template for a handover note" and the agent drafts one for you to edit. .agents/skills/ckb-document/SKILL.md.

A Word doc, slide deck, or PDF from what's in the wiki - no dedicated skill for this, but it's a normal ask:

"Turn the wiki page on our pricing model into a one-page Word doc I can send to legal."

The agent reads the relevant wiki page(s) and uses its general document skills (docx, pptx, pdf) to produce the file - the wiki is the source of truth, the document is a one-off derived artifact.

Add information

Covered in full in §2 - the short version: drop it in raw/inbox/ and say "Ingest," or tell the agent in chat if it's small enough to state directly.

Your profile and lessons

Say "set up my profile" and the agent asks up to three questions: your role, how you want it to work with you, and anything to always or never do. Your answers go into workload/profiles/<your-name>.md. From then on, every session you start prints your profile into the agent's brief. Other people's profiles are not loaded for you. The file is committed, so keep it to working preferences you'd share with the team.

Your preferences never override the KB's rules. AGENTS.md comes first, a project's ## Rules next, and your profile fills in the rest.

When the agent gets something wrong, you can make the correction stick: "remember this: always cite the runbook for retry numbers", or "lesson: …". It asks whether the lesson is yours or for everyone:

  • Yours goes into your profile.
  • Everyone's goes into wiki/lessons.md and waits for a second person to review it. Everyone else's next session lists it as new.

Nothing becomes a lesson unless you ask. A lesson that should bind everyone always belongs in AGENTS.md; the agent will suggest that rather than edit it. Skill: .agents/skills/ckb-profile/SKILL.md.

Save a conversation

Every new session gets a title the agent picks from your first message (or the one you put there: "title: …"). You are not asked; the first reply opens with one line naming it and reminding you that "rename this conversation to X" changes it. The title names the saved transcript and the session's block in workload/. If the reminder line bothers you, say "stop telling me the title" - the agent flips announce_title: false under conversations: in ckb.yaml; the title is still set, just not announced.

Say "save this conversation" and the agent copies the session's transcript into raw/saved-conversations/<YYYY-MM-DD>/ - the original JSONL that Claude Code keeps, byte for byte, plus a readable .md rendering of the same exchange (your messages and the agent's verbatim, tool calls as one-line notes, tool results truncated, the agent's private reasoning left out). raw/saved-conversations/index.md lists everything saved. Earlier sessions of the same project can be saved too: ask, and the agent lists them for you to pick from.

Saved conversations are deliberately outside the wiki. Questions are still answered from wiki/, linked/ and libs/ only - a transcript never becomes evidence on its own. What you can do is ask about the conversations themselves: "did we discuss the billing cut-over", "what did I tell you about naming last week", "what did I ask you to do about the export". The agent searches the saved .md files and quotes the exact exchange, with the date.

If you would rather not be asked, say "save conversations automatically": the agent flips autosave: true under conversations: in ckb.yaml, and from then on every session is saved at its end without a question. "Turn off autosave" flips it back. The switch is committed with the repo, so it applies to everyone working in that KB. Because it is a rule the agent follows at session end, a session that is killed mid-turn would be missed - so the feature has a per-machine half: a Claude Code Stop hook in .claude/settings.local.json (gitignored) that re-saves the transcript after every turn. The agent never installs it on its own. When autosave is on, the session-start check notices a machine where the hook is missing (or one where autosave was turned off but the hook is still there) and asks once whether to change that machine's configuration; it applies the change only if you say yes. Each machine that opens the repo gets asked once.

If a conversation holds knowledge that belongs in the wiki, copy its .md into raw/inbox/ and say "Ingest" - the copy is yours to make, so nothing enters the wiki without you choosing it. Note that a transcript is verbatim: it contains whatever file contents or command output the agent printed during the session, and it becomes a tracked file in the repo. Skill: .agents/skills/ckb-add-conversation/SKILL.md.

Index an external source

Say:

"Index external sources." (or "index libs," "refresh the external index")

This walks every libs/<name>/ that has a source.yaml (see §1) and builds a short index of what it finds - one entry per document, plus an overview page - all inside that same libs/<name>/ folder. Nothing under wiki/ is touched.

Example:

You create libs/finance-reports/source.yaml:

connector: sharepoint
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
description: "Finance team's shared reports folder"
refresh_interval_days: 7

then say "Index external sources."

The agent connects using whatever's available that session (a connected Microsoft 365 tool, in this case), lists the documents in that folder, reads enough of each to write a short summary, and creates libs/finance-reports/index.md (an overview of the source) plus one page per document under libs/finance-reports/entities/, cross-linked via libs/finance-reports/graph/edges.json. It logs everything in libs/finance-reports/log.md, a log separate from wiki/log.md, since this index is scoped to that one connector rather than blended into your main wiki. It finishes by reminding you to review the result and say "sync changes" once you're happy with it.

If a connector needs authorizing (e.g. a SharePoint or Google Drive connection that isn't set up yet), the agent tells you which one and where to authorize it, then continues with any other configured sources rather than stopping the whole run. Run "index external sources" again any time the source has changed - it refreshes existing entries in place rather than duplicating them, and never deletes a page for a document that's disappeared from the source (it flags it instead, so a later "Lint" pass archives it naturally). Skill: .agents/skills/ckb-index-external/SKILL.md.

Who's allowed to build it, and where it's shared. By default, nobody has write access to a connector source until they say so - this keeps a team of, say, ten people from all redundantly scanning the same SharePoint folder. Say:

"Make me the admin for finance-reports."

This writes a personal libs/finance-reports/source.local.yaml with access: write - never committed, never seen by your teammates. Anyone without that file is read-only for that source: if they say "index external sources," the agent won't touch the live connector on their behalf at all. It reports what's already indexed (or tells them plainly that nothing has been indexed yet and who to ask).

If the finance team wants everyone reading the same index rather than each maintaining their own local copy of it inside their own KB, the admin adds an index: block to the shared source.yaml:

index:
  store: git
  location: "https://github.com/finance-team/index-cache.git"
  # ref: main   — optional: pin a branch, tag, or subpath within that store

The very first time anyone runs "index external sources" after that block is added, https://github.com/finance-team/index-cache.git is empty. That's expected, not an error. Every run checks it first: read-only users see "nothing published yet, ask the admin", and the admin's run creates it, because a write-access run always rebuilds from the live connector and pushes the result to that location, whether or not anything was there before. From then on, whenever anyone says "index external sources," the agent first fetches whatever's already published there. Read-only users stop at that point; the admin also rebuilds from the live connector and pushes the refreshed index back to the same location, so the next person's fetch picks it up. Leave the index: block out (the simplest setup, and the right default for a single small team) and the index lives directly inside libs/finance-reports/ in this KB's own repo, shared the normal way via "sync changes", exactly like the plain example above.

Add an optional module

Some capabilities only make sense for some knowledge bases, so they ship as modules in .agents/modules/: present in every copy, inactive until you install one. Say:

  • "What modules are available": lists each module, and whether it's installed.
  • "Install the <name> module": checks what the module needs, tells you before writing anything, then adds its skills, folders and settings. It's recorded in ckb.yaml.
  • "Uninstall the <name> module": removes its skills and settings. Your content stays: wiki pages it created, src/ clones, specs.
Module What it's for Guide
software The KB documents software you're building: source repos as gitignored clones in src/, code mapped into wiki entities, and specs with OpenSpec OPENSPEC.md · module README
capture Save links, articles, PDFs and video transcripts into raw/inbox/ as dated snapshots, with a Wayback fallback and duplicate check module README
share Send a document to another KB through a shared git repo (one append-only mailbox per KB), and take what other KBs sent into raw/inbox/, with versions, retractions and a sender check module README
mcp Use the KB from Claude's web/desktop/mobile apps, Claude Code or another agent through an MCP server: search, read, add material, undo a misfiled submission. Several KBs can be connected at once MCP.md · module README

Skill: .agents/skills/ckb-module/SKILL.md.

Using an agent other than Claude Code

The KB is plain files plus AGENTS.md, so any agent that reads AGENTS.md can work in it. None of the setups below has been tested yet; each says what its tool documents. If you confirm or correct one, change "untested" to the date and the tool version.

Agent Setup (untested)
Codex CLI Reads AGENTS.md at the repo root by itself; start it in the KB folder. It doesn't load .agents/skills/ as skills, so it follows the routing table and opens each SKILL.md as AGENTS.md tells it to.
Cursor Reads AGENTS.md at the repo root as a project rule. If your version doesn't, add a .cursor/rules/ckb.mdc that tells it to read AGENTS.md first.
OpenCode Reads AGENTS.md at the repo root. Skills work as for Codex.
Gemini CLI Looks for GEMINI.md by default. Point it at AGENTS.md with {"contextFileName": "AGENTS.md"} in .gemini/settings.json, or make GEMINI.md a symlink to AGENTS.md, as CLAUDE.md is.

What only Claude Code does today:

Feature Elsewhere
Skills discovered automatically (.claude/skills → .agents/skills) The agent reads SKILL.md files when AGENTS.md routes it there
Session-start hook (start_hook.py) Rule E runs by hand, as it always has
Conversation autosave hook, and saving conversations at all (ckb-add-conversation reads Claude Code's transcripts) Not available; save notes in workload/ instead
Session titles stored for transcripts Not available

Everything else (the Python scripts, lint, retrieval, the MCP server, the modules) works the same with any agent.

Per-folder rules. Some agents read a nested AGENTS.md, where the one closest to the file being edited wins. This template ships none. For rules that apply to one project, use the ## Rules section of its scope page, which every agent reads, because it is part of the wiki.


7. What's agent-generated vs. what you can edit

The short version: the local wiki/ always wins in the cascade, which means it's your wiki - you're never locked out of editing it directly. "Agent-managed" below means the agent treats itself as responsible for keeping that content structurally correct (frontmatter, index, log, graph) - not that you're forbidden from touching it. If you hand-edit a wiki page, it's good practice to run "Lint" afterward so the index/log/ graph stay in sync with what you changed.

There is one exception that runs the other way. On any page the agent regenerates - a connector index, a code map - everything you write is normally lost on the next rebuild. So every such page ends with a ## Notes section that no skill will ever touch:

## Notes

<!-- Yours. Never rewritten by any skill. -->

Write whatever you want there - that this document is obsolete, that the person named in it has left, who to actually ask. It is carried across rebuilds byte-for-byte. Anything you write above that heading on a generated page will be overwritten.

Location Who normally writes it Notes
raw/inbox/, loose files in raw/ You, only The agent only reads, archives, and moves things here - it never originates content in raw/ itself.
raw/archive/<date>/ Agent Auto-filed copy of what you dropped in raw/inbox/, organised by ingestion date. Don't hand-file here - let Ingest do it, so the date and pairing with the log entry stay accurate.
linked/<name>/ You (you create the symlink) Points at another KB's real files, which live and get edited in that other repo - never here. The agent must never write inside linked/.
libs/<name>/ (git-copy, no source.yaml) You (you git clone) A frozen copy of an external KB. Update it by re-pulling that repo yourself, not by hand-editing files here. The agent must never write inside it.
libs/<name>/source.yaml (connector) You, only Declares the connector, location, optionally how often it should be refreshed (refresh_interval_days:), and optionally where a shared/pre-built index lives (index:). The agent reads it but never writes it - same as anything else upstream.
libs/<name>/source.local.yaml (connector) You (or the agent, only when you explicitly ask to become/stop being that source's admin) Per-person, per-machine access: write/read setting - never committed, never seen by anyone else. Absent = read-only, the default.
libs/<name>/{index.md,entities/,graph/,log.md} (connector) Agent-generated, you can freely edit The agent's own index of that one connector's source, built/refreshed by "Index external sources" - but only if you have access: write locally; read-only users get a fetched copy. Structurally the same deal as the main wiki/ row below - feel free to correct an entry by hand, then run "Lint" (it now also checks connector-backed indexes, respecting the same read/write split). Scoped entirely to that connector; never blended into wiki/. Only ## Notes survives a rebuild - put anything you want to keep there.
wiki/decisions/ Agent-generated, edit with care Same as the rest of wiki/ mechanically, but these are append-only by convention: correct a typo or a misattributed name freely, and don't rewrite a decision's context or rationale to match a later view - record a superseding decision instead, so the history survives.
wiki/ (pages, index.md, overview.md, log.md, error-book.md, entities/, graph/) Agent-generated, you can freely edit This is the one place the agent both writes and expects you might too. Feel free to correct a page by hand - just keep the frontmatter fields intact (or update last_updated), and run Lint afterward if you touched something the index/graph/log reference.
outputs/okf/, outputs/starlight/ Agent, fully regenerated Don't hand-edit - these are gitignored build artifacts, silently overwritten the next time you export. If something's wrong, fix the wiki page it came from and re-export.
outputs/teaching/<topic>/ Agent, semi-persistent state plan.md/progress.md the teaching skill reads and writes across sessions. You can look at them any time; hand-editing is possible but may confuse "what's next" tracking - safer to tell the agent what you want changed and let it update the files.
outputs/teaching/feynman/ Agent (one file per session), you can edit Feynman sessions: the explanation, the gaps found, what you said back, and fingerprints of the pages read. Gitignored with the rest of outputs/teaching/; never overwritten by a later session.
PROJECT-OVERVIEW.md (repo root) Agent, fully regenerated Overwritten in full each time you ask for a project summary. Don't hand-edit it - edit the wiki pages it's synthesised from instead, then regenerate.
ABOUT.md, ABOUT.pl.md You The same file in English and Polish: fill in the one in your KB's language and delete the other if you like (if both are filled in, ABOUT.md wins on a conflict). What this KB is for: purpose, audience, scope, owners, sensitivity, the language pages are written in. The README links to it. The agent reads it, checks new material against its scope at ingest, and never edits it unless you ask; upgrades and resets leave it alone. wiki/overview.md is the agent's summary of what the KB actually holds.
templates/ You Document templates: headings, plus a comment per section saying what goes there and where it comes from. The agent reads them, and writes a new one only when you ask. Nothing regenerates or resets this folder. Start from templates/status-report.md.
outputs/documents/ Agent (one file per request), you can edit Documents prepared from a template. Tracked in git and never overwritten by a later run (a repeated name gets -2, -3). Edit them freely; the frontmatter records which template and which wiki pages they came from.
workload/YYYY-MM-DD_<author>_summary.md Agent (appended each session) A running journal of what happened each day, one file per person so a shared repo records who did what and never conflicts here. The author is the git identity of the session. You can read, edit, or trim it freely - it's a log for continuity, not a machine-critical file.
workload/ingest-reports/ Agent (one file per ingest) What each ingest changed: raw files taken in and where they were archived, decisions recorded, entities and other pages created or updated, graph edges, and what the new material confirmed, extended or contradicted. Written once and never rewritten - read it to review an ingest without reconstructing it from the log and the diff.
AGENTS.md / CLAUDE.md You (rarely) This is the system prompt that defines how the agent behaves in this repo. Edit it if you want to change a global rule - e.g. the frontmatter schema, the logging format, or the directory contract. Changes apply from the next session onward.
.agents/skills/*/SKILL.md You (advanced/optional) Each file defines one on-demand capability. You can create new ones or edit existing ones by following the pattern of the ones already here - this isn't required for normal use, but nothing stops you.
LICENSE, VERSION, README*, docs/, ckb.yaml Agent, you can edit Part of the same template layer as AGENTS.md - kept in sync by ckb-upgrade when you accept a template update. ckb-upgrade will always ask before touching LICENSE's copyright line or any of these if your local copy differs from the template's, since customization here (e.g. your own project name or license holder) is expected, not a mistake.

Where the template's own decisions live

docs/decisions/ holds the template's design records (D-0001, D-0002…) in the same format as wiki/decisions/, but as part of the template layer: skills and docs cite them, so they must survive a ckb-reset and travel with ckb-upgrade. Your KB's own decisions still go to wiki/decisions/ via "record a decision" - never here.

Checking a template release

tests/smoke.sh runs the deterministic scripts (lint_report.py, retrieve_candidates.py, save_conversation.py) against the fixtures in tests/fixtures/ and diffs the result with tests/expected/. Run it before merging anything to test or main; run it with --update after an intended change to the scripts' output. The tests/ folder exists only in the template repo: ckb-init does not copy it and ckb-upgrade does not ship it, so a knowledge base never carries it.

tests/bench_retrieval.py measures retrieval (hit@1 and hit@3 on 20 questions). tests/run_evals.py checks what an agent run left behind for each case in tests/evals/: prepare a scratch KB, run the agent there with the case's prompt, then check. The smoke test validates the cases but runs no agent; run the cases by hand before a release.

8. Quick reference

Say... What happens Skill
"Set up a new wiki like this one in <folder>" Bootstraps a fresh, empty KB with this schema ckb-init
"Pull the ckb repo into <folder> and set up the wiki" Clones the template repo to a scratch dir, then bootstraps an empty KB from it ckb-init
"Ingest" / "Update the wiki" Processes raw/inbox/ into structured wiki/ pages ckb-ingest
"Retract X" / "Undo the ingest of X" / "This went to the wrong KB" Shows what the source built (pages, claims, edges), then removes exactly that after your yes; processes requests in raw/retractions/ ckb-retract
"Record a decision: ..." / "we decided ..." Writes a numbered decision record under wiki/decisions/ ckb-decide
"What did we decide about X" / "who decided X" / "what's still open" Answers from the decision records, with who/when/status attached ckb-decide
"Lint" Health-checks the wiki, auto-fixes what it safely can ckb-lint
"Reset the wiki" / "Make this a clean template" Destructive. Deletes accumulated knowledge and restores the empty scaffold, after an inventory and a typed confirmation ckb-reset
"Sync changes" / "Sync with git" Commits, pulls, resolves conflicts, pushes to origin ckb-sync-changes
"Save this conversation" Copies the session transcript (JSONL + readable .md) into raw/saved-conversations/<date>/; outside retrieval ckb-add-conversation
"Save conversations automatically" / "Turn off autosave" Flips conversations.autosave in ckb.yaml; on, every session is saved at its end without asking ckb-add-conversation
"Rename this conversation to X" / "Stop telling me the title" Sets the session's title (used by the saved transcript and the workload note) / flips conversations.announce_title ckb-add-conversation
"Consolidate" / "Build the topic summaries" Writes a proposals-only report / builds the approved wiki/topics/ pages ckb-consolidate
"Set up my profile" / "Remember this: …" / "Lesson: …" Writes your profile, or records a personal or KB-wide lesson ckb-profile
"What needs review?" / "Mark X as reviewed" Lists draft and needs_update pages / records your review on the pages you name ckb-lint
"Keep this answer" Saves the last answer to outputs/answers/ with its sources and gaps ckb-retrieve
"Ingest in batch" / "Ingest, no check-in" Ingests without stopping to show its reading of each source first ckb-ingest
"Turn on the session-start hook" / "Show the context budget" Sets session.start_hook in ckb.yaml and installs the per-machine hook / prints the always-loaded token estimate ckb-lint
"Lint every week" / "Index external sources every 30 days, ask me first" Adds a routine to ckb.yaml; due routines run at session start, after your request ckb-routine
"List routines" / "Which routines are due" / "Remove the weekly lint" Shows, checks or removes routines ckb-routine
"Did we discuss X" / "What did I tell you about X" Searches saved conversations and quotes the exchange ckb-add-conversation
"What modules are available" / "Install the mcp module" Lists or installs an optional module; nothing in it is active until installed ckb-module
"Deploy the MCP server" / "Connect the KB to Claude web" Walks through hosting the KB behind an MCP server and adding it as a connector (mcp module) ckb-mcp
"Quiz me on X" One-off scored knowledge test ckb-quiz
"Teach me the wiki" / "Teach me about X" Plans and runs a spaced-out course with progress tracking ckb-teach-me
"Onboard me on X" / "Where do I start with X" Short guided reading order through the graph ckb-onboard-me
"Feynman me on X" / "What am I fuzzy on?" Plain-words explanation of one page, the gaps it exposed, and an explain-back ckb-feynman
"Give me a project summary" Regenerates PROJECT-OVERVIEW.md ckb-project-summary
"Prepare a new document using template X" / "List templates" / "Make a template for X" Fills a template from templates/ with your answers and the wiki, writes it to outputs/documents/; lists or drafts templates ckb-document
"Export the wiki as OKF" Machine-readable export at outputs/okf/ ckb-export-okf
"Export the wiki to Starlight" Human-readable docs site at outputs/starlight/ ckb-export-starlight
"Upgrade the wiki" / "Check for a newer template version" Checks template + wiki schema versions against the canonical repo, upgrades what you accept ckb-upgrade
"Index external sources" / "Index libs" Builds/refreshes a self-contained index for each connector-backed libs/<name>/ ckb-index-external
Just ask a question Answers from the wiki, using the index/TLDR/graph cascade, with caveats when a source is stale or contested ckb-retrieve
"Who knows about X" / "Who owns X" Answers from expertise/ownership edges in the graph ckb-retrieve