ckb/README.md
Michał Kopeć 8415004031 Template 1.28.1: 1.x maintenance channel, major-version guard (D-0019)
Adds the `1.x` release channel (fixes only, last line with PowerShell
support) to every channel table, and makes ckb-upgrade stop and ask before
crossing a major version, offering the maintenance branch instead.
D-0019 records the 2.0 plan: drop PowerShell, scripts stay in Python.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 13:47:37 +01:00

743 lines
40 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Cascade Knowledge Base
*Read this in: **English** | [Polski](README.pl.md)*
**Source repo (always the most up-to-date version):**
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb)
**What this knowledge base holds:** see [ABOUT.md](ABOUT.md) - its purpose,
audience, scope, owners and sensitivity, written by whoever runs this KB. The
rest of this README describes the Cascade KB tooling, which is the same in
every KB.
A layered, agent-managed wiki where local content overlays read-only upstream
sources. Built on Karpathy's LLM Wiki pattern with extensions for scaling,
lifecycle management, and multi-agent support.
This document is a technical feature overview. For a task-oriented guide -
how to create a wiki, add knowledge, keep it tidy, sync with others, and
worked examples for every use case - see [docs/MANUAL.md](docs/MANUAL.md)
([Polski](docs/MANUAL.pl.md)). New to it? Start with the one-page
[docs/QUICKSTART.md](docs/QUICKSTART.md) ([Polski](docs/QUICKSTART.pl.md)).
If this KB documents software you're building, the optional `software` module
adds `src/` repositories and spec-driven development - see
[docs/OPENSPEC.md](docs/OPENSPEC.md) ([Polski](docs/OPENSPEC.pl.md)).
To use the KB from Claude's web app or any other MCP client, the optional `mcp`
module serves it over MCP: search and read, submissions to `raw/inbox/`, and
undoing a misfiled one, with several KBs connected at once - see
[docs/MCP.md](docs/MCP.md) ([Polski](docs/MCP.pl.md)). To clip web pages,
PDFs and video transcripts into `raw/inbox/`, the optional `capture` module
saves each as a dated, untrusted-marked snapshot. To send a document to
another KB, the optional `share` module uses a shared git repo with one
mailbox per KB; the receiver takes it into `raw/inbox/` and ingests it as
usual. Every module has its
own README in both languages under `.agents/modules/<name>/`.
For the page schema in full, and for how both version numbers got where they
are, see [docs/CHANGELOG.md](docs/CHANGELOG.md) ([Polski](docs/CHANGELOG.pl.md)).
Why the template is shaped the way it is - its own design decisions - is in
[docs/decisions/](docs/decisions/README.md).
### Release channels
The template repo keeps four branches. They are not interchangeable:
| Branch | What it is | Who should track it |
|---|---|---|
| `main` | **Stable** - the released template | Everyone, by default |
| `test` | **Release candidate** - validated before merging to `main` | Anyone helping validate a release, or needing a landed-but-unshipped fix |
| `experimental` | **Development** - active work, may be broken or reverted | People developing the template itself |
| `1.x` | **Maintenance** - the 1.x line after 2.0: fixes only; the last line with PowerShell support | KBs that need PowerShell, or can't move to 2.0 yet |
Both `ckb-init` and `ckb-upgrade` default to `main`. To use another channel,
say which: *"initialize from the test branch"*, *"check experimental for
updates"*, *"switch this KB back to the stable channel"*. The branch a KB
tracks is recorded in `ckb.yaml`:
```yaml
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main
```
A KB with no `ckb.yaml` (or no `template:` block) is treated as tracking
`main`, as every KB predating this convention already did.
---
## Directory Structure
```
├── ABOUT.md # What this KB holds: purpose, audience, scope, owners - yours to write
├── ABOUT.pl.md # The same in Polish - fill in the one in your KB's language
├── ckb.yaml # Repo manifest: template branch tracked, installed modules, conversation settings, routines
├── docs/ # Manual, changelog, OpenSpec guide, and decisions/ — the template's own ADRs
├── tests/ # Template repo only: fixture KB + smoke test (tests/smoke.sh); not copied into KBs
├── libs/ # Read-only external sources — git-copy clones (gitignored) OR
│ # connector configs (source.yaml) with a self-contained generated index
├── linked/ # Read-only upstream KBs mounted as symlinks
├── outputs/ # Generated artifacts, exports, compiled files
│ └── documents/ # Documents prepared from templates/
├── raw/ # User-provided source material
│ └── inbox/ # Drop zone: unprocessed material
├── templates/ # Your document templates: headings plus a comment per section as the brief
├── tmp/ # Temporary files, caches (gitignored)
├── wiki/ # Local structured markdown wiki (agent-managed)
│ ├── index.md # Routing table with "Use when" triggers + kb_schema_version
│ ├── overview.md # What this KB covers — content, not schema
│ ├── log.md # Root rollup change log
│ ├── error-book.md # Compilation errors & derived constraints
│ ├── query-gaps.md # Failed or missing-answer questions for future ingest
│ ├── projects/ # Optional local query scopes
│ ├── decisions/ # Numbered, append-only decision records + own index.md & log.md
│ ├── entities/ # Typed entity pages (people, projects, concepts) + own index.md
│ └── graph/ # Edge lists and relationship data + own index.md
└── workload/ # Session summaries & decisions
└── YYYY-MM-DD_<author>_summary.md
```
---
## Cascade Priority
When searching, layers are checked in order - first match wins:
```
wiki/ (highest) ← agent writes here, always wins
linked/A/ (medium) ← symlinked upstream KBs
linked/B/ (low) ← symlinked upstream KBs
libs/A/ (lowest) ← git-managed external KB copies, or a connector's own generated index
```
The agent never writes to `linked/` or a git-copy `libs/<name>/`. To correct
upstream content, write the right version in `wiki/` - it takes precedence
automatically. The one exception is a connector-backed `libs/<name>/` (see
"External Source Connectors & Indexing" below): the agent owns and
maintains its generated index the same way it does `wiki/`.
---
## Features
Every feature below is a skill under `.agents/skills/`. A skill loads into
context only when invoked; `AGENTS.md` carries the routing and the
non-negotiable rules, nothing more.
### Inbox-Driven Workflow
Drop any raw material (notes, articles, links) into `raw/inbox/` without
organizing. On "Ingest" (or "Update the wiki"), the agent
processes the inbox - extracts knowledge, files it into `wiki/`, and
archives processed items to `raw/` - then reminds you to review the result
and run "sync changes" to push it to `origin` once you're happy with it.
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
Before writing, a script (`dedup_inbox.py`) reports inbox files already
ingested: byte-identical or same-text copies of archived files, files whose
digest a page already cites, links to URLs a page already cites, and
duplicates within the inbox. The agent then **checks in**: per source, its
reading, the pages it will touch and what it contradicts. Nothing is written
until you answer. "Ingest in batch" skips the check-in. Text wrapped in
`<private>…</private>` is never ingested.
For long conversations, meeting notes, transcripts, or chat exports, ingest
uses a structured distillation rather than treating the whole file as one
undifferentiated blob: searchable question, short summary, resolution or
decision, systems/code references, people involved, and high-signal excerpts
that deserve to stay findable on their own.
"High-signal" is an explicit test, not a judgment call, or every excerpt
looks worth keeping and the page becomes a second copy of the transcript.
An excerpt earns its own retrievable section only if it carries a term rare
across the wiki (checked with `rg -c` - a distinguishing search handle, not
a word already on twenty pages), runs to roughly 200 characters or more, and
is corroborated by something later in the material agreeing with, acting on,
or correcting it. Fail any one and the content still lands in the page, just
inside the summary rather than as its own unit. Promoted excerpts carry
their parent heading or thread question with them, so they read
unambiguously alone.
### Lazy-Loading Index with "Use When" Triggers
`wiki/index.md` is a routing table. Each entry has a **Use when** column
listing trigger keywords. The agent reads the index first (stays in context),
matches keywords against the task, and only loads matching pages. The
index stays small; the pages it points at don't have to.
### TLDR-First Query Layer
Every page carries a one-sentence `tldr` in frontmatter. When querying, the
agent reads TLDRs first. If the TLDR already answers the question, the agent
never loads the full body. Fallback chain: TLDR → body → raw source.
### Local Project Scopes
For recurring teams, clients, systems, or initiatives, the wiki can keep
plain Markdown scope pages under `wiki/projects/`. A scope page lists the
wiki pages, entities, raw/archive sources, connector-backed libs, outputs,
and graph areas to search first for that project. You get what a project
workspace gives you in a larger retrieval system, but the scope stays local,
transparent, and editable in any text editor.
Scopes only narrow the first pass. If the scoped search does not answer the
question, the agent falls back to the full cascade.
### Local Hybrid Retrieval
When index/TLDR routing is not enough, the agent can combine several local
signals before answering:
- exact text search with `rg` for error strings, commands, flags, filenames,
hostnames, ticket IDs, and other literal tokens - including across
`raw/inbox/`, so material dropped an hour ago and not yet ingested can
still answer a question (and flags that an ingest is overdue)
- semantic/entity matches from page titles, TLDRs, project scopes, and graph
relationships
- freshness and confidence metadata, so stale or weak pages are treated with
care
- context expansion around a matched section, so answers are grounded in the
neighboring headings and paragraphs rather than a lone snippet
- BM25 section search through SQLite FTS5 (standard library), each section
indexed with its page title, heading path and `tldr` as context, so a
candidate names the sections that matched and its token cost
Gathering and fusing those signals is mechanical, so it runs as a script -
`.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py` - the same way
lint's detection does; the agent reads its ranked output and does the
judgment (dedupe by claim, rerank against the literal question, source
verification). Each signal produces its own ranked list, and the lists are
then fused rather than resolved by picking a favourite: every candidate scores
`weight / (k + rank)` summed across the lists it appears in, so a page
ranked third by three signals beats one ranked first by a single signal.
`k` is 10, deliberately smaller than the 60 rank fusion is usually quoted
with - 60 is tuned for retrievers returning hundreds of candidates and
flattens all scores into near-identical values against the dozen a local
wiki produces. Literal-token queries up-weight the exact-match list, since
no amount of title similarity should outrank a match on the exact string
someone pasted.
Fused candidates are then deduplicated by claim - a wiki page, the
`raw/archive/` file it cites, and a connector page pointing back at it are
three hits for one fact, not three sources - and reranked 0–10 on how well
each answers the literal question rather than how well it matches the
question's wording. Same agent, deliberate second pass, no separate model.
The result is normalized internally as an evidence packet: source path,
matched claim, date/freshness, confidence/quality, relationship or scope
hints, and which signals each candidate was fused from. No server, vector
database, or dedicated client is required.
### Answer Caveats
Metadata the wiki already tracks is stated in the answer itself, not just
consulted while building it. When a page grounding an answer is past its
`freshness_window_days`, carries low `confidence`/`quality`, rests on
un-ingested `raw/inbox/` material, or was checked against a cached
connector index rather than a live re-fetch, the answer says so next to
the claim it qualifies. Conflicts between two live pages are surfaced the
same way even when neither carries `superseded_by` yet. The failure mode
this closes is answering confidently *from* a stale page without passing
that on.
### Consolidation and Topic Summaries (on demand)
"Consolidate" writes a proposals-only report to `outputs/reports/`: topic
clusters (and whether each `wiki/topics/` page is missing or outdated), merge
candidates, missing links, stale pages and old log entries. Nothing in the
wiki changes until you approve an item. Approved topic pages summarise what
the KB holds about one subject and list their member pages with digests, so
lint flags a topic when a member changes. Skill:
`.agents/skills/ckb-consolidate/SKILL.md`.
### Profiles and Lessons
Each person can keep a profile in `workload/profiles/` (role, how to work
with them), printed into their own session-start brief and nobody else's.
"Remember this" or "lesson: …" records a lesson: a personal one in the
profile, a KB-wide one in `wiki/lessons.md`, which waits for a second
person's review. Precedence is `AGENTS.md`, then a project's `## Rules`, then
the profile. Skill: `.agents/skills/ckb-profile/SKILL.md`.
### Kept Answers
An answer that took real work can be kept on request in
`outputs/answers/`, with fingerprinted `## Sources` and a `## Gaps`
section. Lint flags a kept answer whose sources have changed, and asking
the same question again updates the kept answer rather than duplicating it.
Filing an answer back into the wiki goes through a normal ingest, never a
direct write. Private (`<private>`) passages are never quoted.
### Expertise & Ownership Lookups
"Who knows about X" and "who owns X" are direct graph lookups rather than
full-text guesses. Ingest records `has_expertise_in` edges when someone
demonstrably answers questions or explains decisions on a topic, and
`owns` edges for declared responsibility over a system, area, or decision - both from demonstrated evidence only, never inferred from meeting
attendance or job title. Where no edge exists yet, retrieval falls back to
authorship evidence and says which of the two grounded the answer, since
an inferred expert is a weaker claim than a recorded one.
### Decision Records
`wiki/decisions/` holds one numbered page per decision (`NNNN-slug.md`):
what was decided, `decided_by` whom, `decided_on` what date, why, the
alternatives that lost, and what it `affects`. A `status` field
(`proposed`/`accepted`/`rejected`/`superseded`/`reversed`) says whether it is
actually in force, and an optional `review_on` date marks it for revisiting.
Decision pages are **append-only**. When the choice changes, a *new* decision
supersedes the old one - `supersedes`/`superseded_by` are set on both sides,
the old page's status becomes `superseded` or `reversed`, and its original
context and rationale stay untouched. That is what makes "why is it like
this?" answerable years later, and what turns "we use Postgres" into "we use
Postgres, and before that MySQL, changed in September because of reporting".
`decided_by` and `affects` also become graph edges, so "who decided X" and
"what decisions touch Y" are direct lookups. The `ckb-decide` skill records
decisions and answers questions about them; `ckb-lint` checks their structure
(status vocabulary, required dates, two-sided supersession, unique numbers,
overdue reviews).
### Query Gaps
If the cascade cannot answer a question, the agent records or proposes a
short entry in `wiki/query-gaps.md`: what was asked, where it looked, and the
smallest source or page that would close the gap. Failed searches then become
demand signals for the next ingest instead of disappearing into chat history.
### Page Frontmatter Schema
Every wiki page uses YAML frontmatter. `type` is required; the rest are optional:
```yaml
---
type: concept # REQUIRED. Open string: person, project, concept, library, decision, playbook, ...
resource: https://... # Canonical URI to the authoritative external source this page describes
tldr: One-sentence summary optimised for LLM reading
confidence: 0.0–1.0 # Source corroboration score
quality: 0.0–1.0 # Self-evaluation (below 0.7 → flagged)
supersedes: path/to/old.md
superseded_by: path/to/new.md
last_updated: YYYY-MM-DD
freshness_window_days: 90 # Days before considered stale
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e # digest of the source this page was built from
source_checked: YYYY-MM-DD # when that digest was last verified
review: draft|reviewed|needs_update # with reviewed_by / reviewed_on (1.6)
tags: retries, billing # only tags listed in wiki/tags.md (1.6)
---
```
- **type** - required; unregistered string, new values always valid, readers tolerate unrecognized ones
- **resource** - optional pointer to the live/authoritative source, kept separate from the wiki's own commentary
- **confidence** - set on write, decays with time, reinforced by new sources
- **quality** - self-scored on write, pages below 0.7 flagged for review
- **supersedes / superseded_by** - when new info replaces old, link them
- **freshness_window_days** - pages older than this get flagged during lint
- **retention** - low pages are archived after 2× freshness window
- **source_fingerprint / source_checked** - a digest of the material the page
was synthesized from, plus when it was last confirmed. A freshness window is
a guess that a source *might* have moved; a fingerprint is a fact about
whether it *did*, and lint checks it mechanically.
- **review / reviewed_by / reviewed_on** - whether a person has checked the
page: ingest writes `draft`, a person's "mark X as reviewed" sets
`reviewed`, and a later change to what the page claims sets `needs_update`
- **tags** - a flat list checked against the KB's own vocabulary in
`wiki/tags.md`; retrieval can filter on it
#### Reserved body sections
Three `##` headings mean something specific everywhere in the KB:
| Section | What it holds |
|---|---|
| `## Sources` | one bullet per source, each with a fingerprint |
| `## Crux` | verbatim quotes from those sources - evidence, never paraphrase |
| `## Notes` | human-authored and **protected**: no skill rewrites it, ever |
| `## Rules` | on project scope pages only: the team's rules for that project, protected like `## Notes` |
Where two sources disagree and nobody has decided which is right, ingest
writes a `> CONTRADICTION: …` marker into the page instead of picking a
winner; lint lists it until a person settles it.
`## Crux` is what lets a question be answered from the page instead of from
the archive: a summary can drift silently, a quote either still matches its
source or it doesn't. `## Notes` is the inverse guarantee - on pages the agent
regenerates (connector indexes, code maps), it is the one place an annotation
survives the next rebuild.
`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.7"`), declaring
which revision of this schema the wiki was authored against - bump minor for
additive optional fields, major for breaking changes.
### Entity Extraction & Knowledge Graph
During ingest, the agent extracts typed entities (people, projects, libraries,
concepts, systems) and stores them as pages in `wiki/entities/`. Typed
relationships are recorded in `wiki/graph/edges.json`, using a closed
vocabulary where each verb is defined by the question it answers (see
`wiki/graph/index.md`) - structural ones (`part_of`, `uses`, `depends_on`,
`produces`, `configures`, `validates`, `implements`, `caused`, `contradicts`,
`supersedes`) plus people-to-topic ones (`has_expertise_in`, `owns`). Queries can walk the
graph to discover connected pages (e.g. "what depends on Redis?") or to
answer "who knows about X" directly.
### Recursive Index & Log Convention
Any `wiki/` subdirectory that groups multiple pages (`entities/`, `graph/`,
future topic folders) keeps its own `index.md` - a plain link list, no
frontmatter - so subdirectory navigation stays lazy instead of requiring a
full scan. A subdirectory can also keep its own `log.md` once it has enough
independent history; `wiki/log.md` stays the root-level rollup and never
duplicates a change a subdirectory log already recorded - it carries a
one-line `POINTER` entry instead. `wiki/decisions/log.md` is the one
subdirectory log the base scaffold ships with, and Rule B in `AGENTS.md`
names it as the exception.
### External Source Connectors & Indexing (on demand)
A `libs/<name>/` folder supports a second population mode alongside the
existing git-copy one: a small user-authored `libs/<name>/source.yaml`
declaring a *live* external source - a SharePoint folder, a Google Drive
folder, a plain URL, or another connector - that you don't want to fully
mirror locally:
```yaml
connector: sharepoint
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
description: "Finance team's shared reports folder"
refresh_interval_days: 7 # optional, defaults to 30
```
`refresh_interval_days` tunes cadence per source - a folder that churns
daily deserves a shorter window than a quarterly archive that barely moves - and sets the `freshness_window_days` stamped on that source's generated
pages. Both "index external sources" and "Lint" report a source that's
overdue against it, and say by how much, so a read-only user knows which
admin to chase rather than quietly trusting a copy three weeks past due.
Say "index external sources" and the agent walks it, resolving `connector`
to whatever live tool is available that session (a connected Microsoft
365/Google Drive MCP tool, or `WebFetch` for a plain URL), and builds a
self-contained generated index inside that same `libs/<name>/` -
`index.md`/`entities/`/`graph/`/`log.md`, mirroring `wiki/`'s own shape via
the Recursive Index & Log Convention above, but scoped entirely to that one
connector. The index is **not** blended
into the main `wiki/entities/`/`wiki/graph/edges.json` - it stays separated
at the `libs/` cascade layer, the same way a git-cloned KB's own files
already are. `source.yaml` itself stays user-only, never written by the
agent.
Two refinements on top of that:
- Shared, pre-built indexes. `source.yaml` can add an optional `index:`
block declaring *where the already-built index lives* - a git repo, or a
shared resource such as a network path or another connector-reachable
location:
```yaml
index:
store: git # git | shared
location: "https://github.com/org/finance-index-cache.git"
ref: main # optional — branch, tag, or subpath hint within that store
```
Every run checks that location: if it already has an index, fetch it.
Most people read what's already there instead of building it
themselves. If it doesn't yet, that's the normal first-time state, not an
error: the next run by a user with write access creates and publishes
it there, with no separate "initialize" step.
- Read vs. write, per user, per source. Whether *this* user can
rebuild an index (versus only read a fetched/published one) is a
separate, local, gitignored `libs/<name>/source.local.yaml` - read-only
by default. Setting `access: write` there opts a given machine/user in as
that source's admin, so a team can designate one or two people to
maintain a source while everyone else reads the result - no
redundant rebuilding, no need for every user to have their own connector
authorization.
Skill: `.agents/skills/ckb-index-external/SKILL.md`.
### Dual-Linking (Wikilinks + Markdown)
Every cross-reference uses both `[[Wikilinks]]` (Obsidian-compatible) and
standard `[markdown](path.md)` links. Works in Obsidian graph view, GitHub
rendering, and CLI tools. Upstream references use full relative paths:
`linked/<name>/...` or `libs/<name>/...`. Intra-wiki references prefer
project-root-absolute paths (`/wiki/entities/foo.md`) over relative ones,
so links survive later file moves.
### Self-Healing Lint
Periodically (or on demand), the agent health-checks the wiki:
- **Conformance** - flags any page missing parseable frontmatter or a `type` field
- **Freshness** - flags pages past their `freshness_window_days`
- **Confidence decay** - reduces confidence on unreinforced pages
- **Retention sweep** - archives `retention: low` pages past 2× window
- **Supersession detection** - finds contradictions, links old→new
- **Orphan detection** - finds pages with no inbound links
- **Graph consistency** - verifies all edges point to existing entities
- **Index/log consistency** - verifies every subdirectory has an index.md and no change is double-logged
- **Source fingerprints** - recomputes each cited source's digest and flags pages whose evidence has actually changed, not merely aged
- **Crux verbatimness** - flags a quoted excerpt that no longer appears in the source it cites
- **Connector cadence** - flags a connector-backed source whose generated index is overdue against its `refresh_interval_days`, and by how much
- **Secrets and private spans** - flags credential shapes in committed text and `<private>` passages that reached `wiki/`, masked, never auto-fixed; harmless matches go in a line-hash `.secrets-allow`
- **Kept answers** - flags answers in `outputs/answers/` whose sources changed
- **Context budget** - estimates the always-loaded layer (`AGENTS.md` plus skill descriptions) and flags it above `budget.always_loaded_tokens` in `ckb.yaml`
- **Error Book** - records systemic issues with root cause and fix
Auto-fixes what it can (broken links, missing backlinks, stale flags), and
reminds you to review the result and run "sync changes" to push it to
`origin` once you're happy with it. Skill: `.agents/skills/ckb-lint/SKILL.md`.
### Conflict Resolution (Supersession)
When new information contradicts an existing page, the agent adds
`supersedes` / `superseded_by` links. The old page stays, marked stale.
Version control for knowledge as well as files.
### Quality Scoring
Every page gets a quality score (0.0–1.0) on write, based on structure,
source citations, and consistency with the rest of the wiki. Pages below
0.7 are flagged for review or rewritten in the next lint pass.
### Error Book
Systematic errors (orphan links, formatting issues, cross-page contradictions)
are recorded in `wiki/error-book.md` with root cause, applied fix, and a
reusable constraint to prevent recurrence. Two-layer repair:
- **Layer 1** - deterministic auto-fix for structural issues
- **Layer 2** - agent reasoning pass for semantic/cross-page issues
### Session Conventions
These are rules the agent follows from `AGENTS.md`, not hooks wired into the
harness - nothing in `.claude/` runs on its own. If you want any of them
enforced mechanically, that is a Claude Code hook or a scheduled agent you
add yourself.
- **Session start** → pick a title for the conversation from the first
message and state it in one line (unless `conversations.announce_title:
false`); one call to `session_start.py` stores it and prints the git
status, the one-line `lint_report.py --quick` result, due routines and
the last block of the latest workload summary; suggest
`ckb-sync-changes` or `ckb-lint` only when either reports something; run
due routines after the first request; when conversation autosave is on,
also check this machine has the gitignored Stop hook in
`.claude/settings.local.json` and ask before installing it. The brief also
lists open threads: unticked `- [ ]` items under `### Open threads` in
workload notes
- **Session-start hook (opt-in, Claude Code)** → with `session.start_hook:
true`, a per-machine `SessionStart` hook injects the same brief before the
first message and again after every compaction; the agent asks before
installing it
- **Session end** → append to `workload/`; repeat the unsynchronized-change
check; after a session that did real work, ask once whether to save the
conversation (`ckb-add-conversation`) - saved only on a yes, or without
asking when `conversations.autosave: true` is set in `ckb.yaml`
- **Every turn that touches the KB** → a note in `workload/` (Rule D)
- **Wrong or misfiled source** → `ckb-retract` removes it and exactly what
it contributed (pages, claims, edges), after showing the plan; requests
queued in `raw/retractions/` (e.g. from the MCP server) are flagged at
ingest
- **Unanswerable question** → a `wiki/query-gaps.md` entry, the one write
`ckb-retrieve` owns; answers are never filed back as pages automatically
- **Lint on demand or by routine** → "Lint" runs the full check; "lint
every week" makes it a routine in `ckb.yaml` that fires at the first
session start after the period has elapsed (`ckb-routine`)
### Demand-Driven Context (DDC)
The wiki grows from real agent failures, not upfront curation:
1. Agent can't answer → identifies missing knowledge
2. Proposes minimal entity/page to fill the gap
3. User approves or provides source material
4. Next ingest incorporates it
### Session Summaries
After every conversational action, the agent appends to
`workload/YYYY-MM-DD_<author>_summary.md`, one file per person per day,
named and stamped with the git identity the session runs under. That gives
continuity between sessions, a browsable history of how the KB evolved and,
in a shared repo, a record of who did what without merge conflicts in
`workload/`. The same identity goes on every `wiki/log.md`
entry's `**Author:**` line. The agent reads the latest summary on session
start, whoever wrote it, to pick up where things were left.
### Change Log
Every wiki modification is immediately logged in exactly one log, in reverse
chronological order: `wiki/decisions/log.md` for anything under
`wiki/decisions/`, `wiki/log.md` for everything else, with a one-line
`POINTER` in the root log when the decisions log absorbs a change. Lint
flags a change recorded in both.
### OKF Export (on demand)
The wiki can be exported as an [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
v0.1-conformant bundle at `outputs/okf/`, consumable by any generic OKF tool
(e.g. Google's reference graph visualizer) without disturbing the richer
internal schema (`confidence`/`quality`/`retention`/`supersedes`/dual-linking)
that OKF doesn't natively understand. A deterministic Python script
(`scripts/export_okf.py`) does the whole transform - frontmatter remapping,
link rewriting, index and log regeneration, and an OKF conformance pass over
its own output - so the export is reproducible rather than re-reasoned page
by page; the agent runs it and relays the report. `outputs/okf/` is
gitignored - it's a fully-regenerated build artifact, so each machine/tool
regenerates it on demand rather than carrying it in git history. Skill:
`.agents/skills/ckb-export-okf/SKILL.md`.
### Starlight Export (on demand)
The wiki can also be exported into an Astro + Starlight-consumable form at
`outputs/starlight/`, producing a human-readable documentation website -
unlike the OKF export, which targets machine/tool consumption. A
deterministic Python script (`scripts/export_starlight.py`) handles
frontmatter remapping, dual-link collapsing, wikilink resolution, asset
copying, and sidebar generation; the agent only asks the two setup
questions (export scope: full runnable scaffold vs. content-only; whether
to include the log/error-book meta pages) and relays the script's report. Skill: `.agents/skills/ckb-export-starlight/SKILL.md`. Like `outputs/okf/`,
`outputs/starlight/` is gitignored as a regenerated build artifact.
### Decision Log (on demand)
Say "record a decision: ..." (or just "we decided ...") to file a numbered
decision record; ask "what did we decide about X", "who decided that",
"which decisions are still proposed", or "what superseded decision 3" to get
it back with the who, when, and status attached. Recording gathers the
missing fields in a single round rather than an interview, wires the
supersession links in both directions, adds `decided_by`/`affects` graph
edges, and logs to `wiki/decisions/log.md`. See
`.agents/skills/ckb-decide/SKILL.md`.
### Guided Onboarding Tours (on demand)
Ask "onboard me on X" (or "where do I start with X", "mini tour of X") to get
a short, read-only guided reading order: an overview paragraph plus an
ordered list of wiki pages to read, built by walking the knowledge graph
outward from the best-matching page (foundations first, then the topic
itself, then what builds on it). Never writes to `wiki/`. See
`.agents/skills/ckb-onboard-me/SKILL.md`.
### Project Summary (on demand)
Ask for "a project summary" (or "where do things stand", "catch me up on the
project") to regenerate `PROJECT-OVERVIEW.md` at the repo root - a
one-to-two-page snapshot (overview, project state, actions & status, risks,
assumptions) synthesized entirely from the current `wiki/` contents and its
knowledge graph. Always overwritten in full on re-run, never hand-appended
to. See `.agents/skills/ckb-project-summary/SKILL.md`.
### Documents from Templates (on demand)
Keep the documents you write often as templates in `templates/`: a Markdown
file whose headings set the shape and whose HTML comments brief the agent on
each section - ask the user, read this wiki page, keep it to three sentences.
"Prepare a new document using template status-report" reads the template,
asks its questions in one go, pulls the rest from the wiki and writes the
result to `outputs/documents/`, with frontmatter naming the template and the
pages used. Gaps become `TODO:` lines, not guesses. One example ships,
`templates/status-report.md`; `templates/README.md` has the format. See
`.agents/skills/ckb-document/SKILL.md`.
### Git Sync (on demand)
On demand, the agent reconciles this repo's git history with its `origin`
remote: it commits local changes, pulls and merges remote ones, shows you
any conflicts file by file to resolve, then pushes the result automatically.
Before staging, it scans what is about to be committed for secrets and stops
on a hit. Say "sync changes" to trigger it. It has
nothing to do with "Ingest", which turns `raw/inbox/` into `wiki/` pages and
never touches git. "Sync" on its own always means git. Skill:
`.agents/skills/ckb-sync-changes/SKILL.md`.
### Saved Conversations (on demand)
Say "save this conversation" and the session's transcript is copied into
`raw/saved-conversations/<YYYY-MM-DD>/` - the JSONL Claude Code keeps, plus
a readable `.md` rendering - and listed in that folder's `index.md`. Saved
conversations stay outside retrieval: questions are still answered from the
wiki alone. You can ask about the conversations themselves ("did we discuss
X", "what did I tell you about Y") and get the exact exchange quoted back.
To bring one into the wiki, copy its `.md` into `raw/inbox/` and say
"Ingest". Say "save conversations automatically" to flip
`conversations.autosave` in `ckb.yaml`, after which every session is saved
at its end without a question. Every session is titled by the agent from
its first message; the first reply states the title, which names the saved
transcript, and "stop telling me the title" silences that line.
Skill: `.agents/skills/ckb-add-conversation/SKILL.md`.
### Quiz Mode (on demand)
Ask to be quizzed on the wiki ("quiz me on X", "test my knowledge") for a
one-off, scored knowledge check: the agent reads the relevant pages,
generates open or multiple-choice questions grounded in specific wiki
facts, runs them one at a time with immediate feedback and a running
score, and closes with a verdict. Stateless - nothing is saved between
runs. See `.agents/skills/ckb-quiz/SKILL.md`.
### Guided Teaching Curriculum (on demand)
Ask to be taught the wiki ("teach me the wiki", "teach me about X", "run a
teaching session") for a stateful course rather than a one-off quiz. First
call plans it: scopes the material (optionally supplementing thin spots
from the web, clearly marked as non-authoritative), asks whether it should
be one session or a spaced series (duration, frequency, optional calendar
`.ics` reminders), chunks the content into session-sized portions -
preferring an extra session over cramming - and saves the accepted plan
and a progress tracker to `outputs/teaching/<topic>/`. Later calls compare
plan against progress, teach the next portion using a different technique
each time (Socratic questioning, analogies, worked examples, teach-back,
mnemonics, ...), spot-check retention, and re-teach weak spots before
advancing. Never writes to `wiki/`. See
`.agents/skills/ckb-teach-me/SKILL.md`.
### Feynman Explanations (on demand)
Ask "Feynman me on X" (or "explain X to me properly", "what am I fuzzy
on?") to have one wiki page explained in words a twelve-year-old owns, each
block linked to the section it came from, and then every place the
explanation went thin named and sorted: a gap in the page, a gap in its
sources, or a gap in the explainer. The agent never fills a gap from its own
knowledge. It then asks you to explain one piece back and goes one level
deeper. With no concept named, it offers draft, single-source or stale
pages. The session is saved to `outputs/teaching/feynman/`; a source gap
goes into `wiki/query-gaps.md` only on your yes. See
`.agents/skills/ckb-feynman/SKILL.md`.
---
## Quick Start
0. **Optional: install Python 3.8+.** Five skills run a stdlib-only Python
script; without it the session-start check falls back to a bash/PowerShell
script, lint and retrieval run in a slower manual mode, and the exporters
are unavailable. Per-OS steps: [docs/MANUAL.md → Prerequisites](docs/MANUAL.md#prerequisites).
1. **Mount upstream KBs:**
```bash
ln -s /path/to/other-kb ./linked/my-upstream
git clone https://github.com/org/external-kb ./libs/external-kb
```
Or, for a live source you don't want to fully mirror, drop a
`libs/<name>/source.yaml` instead (see "External Source Connectors &
Indexing" above) and say "index external sources."
2. **Drop raw material** into `raw/inbox/` (notes, links, articles).
3. **Tell an agent to "Ingest"** - it processes the inbox, consults the
cascade, extracts entities, and writes structured markdown into `wiki/`.
4. **Ask questions** - the agent uses the index for routing, TLDRs for
quick answers, and the graph for relationship discovery.
5. **Periodically ask to "Lint"** - the agent health-checks everything,
auto-fixes what it can, and reports issues.
---
## Agent Instruction Files
| File | Purpose |
|------|---------|
| `AGENTS.md` | Full instruction for any AI coding agent |
| `CLAUDE.md` | Symlink to `AGENTS.md`, auto-detected by Claude Code |
Skills live in one shared location, `.agents/skills/`, so any agent tooling
that reads that convention picks them up. `.claude/skills` is a symlink to
`.agents/skills` - Claude Code sees the same skill set without a second
copy to keep in sync.
---
## Tips
- Upstream KBs (`linked/` and git-copy `libs/`) are **never modified** by
agents. A connector-backed `libs/<name>/` (one with a `source.yaml`) is
the one exception - the agent owns and maintains its generated index,
but only for a user who's opted themselves into `access: write` locally
(see the next point); everyone else's copy stays read-only.
- To correct upstream content, write the correct version in `wiki/` - it wins.
- Use `raw/inbox/` for anything unprocessed; the agent clears it on ingest.
- The `wiki/index.md` routing table is the most important file - keep it current.
- Confidence, quality, and freshness let you trust the right content and
flag the rest for review.
- `tmp/` is gitignored. So is most of `libs/`, with one split: a git-copy
`libs/<name>/` stays gitignored, while a connector-backed one has its
`source.yaml` and generated `index.md`/`entities/`/`graph/`/`log.md`
tracked. That index is synthesized knowledge worth sharing via "sync
changes", not a build artifact. `libs/<name>/source.local.yaml` is the
exception inside the exception: personal machine state, never synced.
- `outputs/` is tracked, but `outputs/okf/` and `outputs/starlight/` are
not. Each is reproducible from `wiki/` on demand, so there is nothing to
reconcile by carrying it in history. Commit hand-maintained artifacts
under `outputs/` as normal.
- `outputs/teaching/` is gitignored too. Learning plans, session progress and
Feynman sessions are personal, not shared KB content.
---
## Version & License
Current template version: [VERSION](VERSION). Licensed under the
[Apache License 2.0](LICENSE).