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 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 you won't be able to git pull it later to refresh — to update it, just 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.

  Two things worth knowing up front about 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 just 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 yet (the normal state before anyone's run this with write access), that's not an error — whoever has write access is the one whose next run creates and publishes it there for the first time.
  • Building/refreshing is 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). This is deliberate: it lets one or two people maintain a source for the whole team instead of everyone redundantly re-scanning it.

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

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'll have the exact same files and can point your agent at the unpacked folder right away. The one thing you'll be missing is a configured origin, so "sync changes" and "upgrade the wiki" won't have anything to push to or compare against yet — run git init in the unpacked folder and add the URL above as origin (git remote add origin https://git.wierzbowa.cloud/michal/ckb) whenever you're ready for those.

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.

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 — entirely 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"

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 that's entirely 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). Implemented by the ckb-index-external 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 just 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 just see "nothing published yet, ask the admin"; the admin's run is what actually creates it there, since 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 right there; the admin also rebuilds from the live connector and pushes the refreshed index back to that same location, so the next person's fetch picks it up. Leave the index: block out entirely (the simplest setup, and the right default for a single small team) and the index just 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.

---

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>/ (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, 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 just 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/.
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
"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	— (core query workflow)