ckb/MANUAL.md

# User Manual

*Read this in: **English** | [Polski](MANUAL.pl.md)*

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](AGENTS.md) /
[CLAUDE.md](CLAUDE.md). For a feature-by-feature technical overview, see
[README.md](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](#1-creating-or-initialising-a-wiki)
2. [Adding knowledge](#2-adding-knowledge)
3. [Keeping it tidy](#3-keeping-it-tidy)
4. [Syncing — with yourself, and with other people](#4-syncing--with-yourself-and-with-other-people)
5. [Upgrading the template](#5-upgrading-the-template)
6. [Use cases](#6-use-cases)
7. [What's agent-generated vs. what you can edit](#7-whats-agent-generated-vs-what-you-can-edit)
8. [Quick reference](#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](#2-adding-knowledge).

### 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):
  ```bash
  ln -s /path/to/other-kb ./linked/other-team
  ```
- **Git clone** (an external KB you want a frozen, version-controlled copy
  of):
  ```bash
  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.

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](https://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](#building-on-top-of-someone-elses-wiki). 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](#4-syncing--with-yourself-and-with-other-people): 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](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
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](#2-adding-knowledge) — 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) |