Schema 1.6, all fields optional (D-0014): - F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`, `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews - F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred - F21 `tags` against the new `wiki/tags.md`, lint check 19, retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags - F9 profiles in workload/profiles/, protected `## Rules` on project scope pages, precedence AGENTS.md > Rules > profile - F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the bash/PowerShell fallbacks); open threads no longer print twice. ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
62 KiB
User Manual
Read this in: English | Polski
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
- Creating or initialising a wiki
- Adding knowledge
- Keeping it tidy
- Syncing - with yourself, and with other people
- Upgrading the template
- Use cases
- What's agent-generated vs. what you can edit
- Quick reference
1. Creating or initialising a wiki
Prerequisites
The agent does almost everything by reading and writing Markdown. Five
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, and the two exporters.
Python is recommended, not strictly required:
| Without Python | What happens |
|---|---|
| Session-start health check | A bash/PowerShell fallback runs instead. 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.12in a terminal, or the Microsoft Store "Python 3.12" app, or the installer from python.org (tick Add python.exe to PATH). Afterwardspython --versionorpy -3 --versionshould printPython 3.x. Ifpythonopens the Store instead, turn off the App execution aliases forpython.exein Windows Settings, or usepy -3. - macOS:
brew install pythonwith Homebrew, orxcode-select --installfor the Apple-shippedpython3. - 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-kbDon'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-kbinstead. You end up with the same frozen, read-only copy either way. The only difference is that you can'tgit pullit 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.yamlyourself: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.yamlcan add anindex: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, personallibs/<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: 7tosource.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.
- You don't have to build the index yourself.
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) intoraw/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 inwiki/graph/edges.json, adds the new pages towiki/index.md, logs the change inwiki/log.md, and moves the original file toraw/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: falseskips 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
proposedwith 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/orraw/, 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.mdplus every skill description) gets flagged when it grows past the budget inckb.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.
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.
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:
- 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 checkoutaway 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. - 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. - 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. - 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.
- 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
originremote configured. Paste the URL of the remote repository and I'll add it asorigin."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 three 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 |
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.
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 theREADME/MANUALdocs. Compared against the canonical repo's ownVERSIONfile. - Your wiki content's own schema version - the
kb_schema_versionfield inwiki/index.md, compared against what the template currently expects. A KB can be fully current on tooling but still carrywiki/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 akb_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.mdthat 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
typeto any page where it isn't obvious, - logs every touched page in
wiki/log.mdas a migration entry so it's clear the change was structural, not new knowledge, - and bumps
kb_schema_versiononce 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.
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.
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.mdand 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: 7then 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 underlibs/finance-reports/entities/, cross-linked vialibs/finance-reports/graph/edges.json. It logs everything inlibs/finance-reports/log.md, a log separate fromwiki/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 |
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.
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. |
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 |
You | 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.
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 |
| "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 |
| "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 |