ckb/MANUAL.md

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. 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

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.

If the target folder already looks like a KB (it has a wiki/ or AGENTS.md already), the agent will stop and ask 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 entirely read-only. There are two 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
  

Either way, once it's mounted, just 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 libs/ directly; if something there is wrong or outdated, you fix it by writing the corrected version into your own local wiki/, which always wins.

---

2. Adding knowledge

This is the main way the wiki grows. There are two on-ramps:

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 "Sync the wiki" / "Update the wiki" — same thing)

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.

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

This is implemented by the ckb-ingest 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 worth keeping — "actually, the deadline moved to September" — and it has lasting value, 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 just 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.

---

3. Keeping it tidy

Say, whenever you like (there's no fixed schedule — do it after a big ingest, or just periodically):

"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
• recurring systemic issues get written into wiki/error-book.md

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. Implemented by the ckb-lint skill — .agents/skills/ckb-lint/SKILL.md.

---

4. Syncing — with yourself, and with other people

There are two entirely 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, that source repo — git.wierzbowa.cloud/michal/ckb — is the canonical, always-up-to-date copy. If you're not sure whether your local checkout is current, that's the place to check against.

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. Implemented by the ckb-sync-changes 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 on its own without you asking.

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."

Two entirely 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'll just 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 — which could be a genuine template improvement, or could be 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. Implemented by the ckb-upgrade skill — .agents/skills/ckb-upgrade/SKILL.md.

---

6. Use cases

Ask questions

Just ask, in plain language:

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

The agent reads wiki/index.md first to find relevant pages, checks their one-line tldr before loading the full page, 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.

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/cbk-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 — entirely 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 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 just tell the agent in chat if it's small enough to state directly.

---

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.

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>/	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 libs/.
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.
workload/YYYY-MM-DD_summary.md	Agent (appended each session)	A running journal of what happened each day. You can read, edit, or trim it freely — it's a log for continuity, not a machine-critical file.
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*, MANUAL*	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.

---

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
"Ingest" / "Sync the wiki" / "Update the wiki"	Processes raw/inbox/ into structured wiki/ pages	ckb-ingest
"Lint"	Health-checks the wiki, auto-fixes what it safely can	ckb-lint
"Sync changes" / "Sync with git"	Commits, pulls, resolves conflicts, pushes to origin	ckb-sync-changes
"Quiz me on X"	One-off scored knowledge test	cbk-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
"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
Just ask a question	Answers from the wiki, using the index/TLDR/graph cascade	— (core query workflow)