ckb/docs/QUICKSTART.md
Michał Kopeć cf9e08157b Template 1.26.1: one-page quickstart in English and Polish
docs/QUICKSTART.md and docs/QUICKSTART.pl.md take a new user from an
empty folder to the first ingest, answer, lint and sync. Linked from
both READMEs and both manuals; ckb-init copies them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 21:00:53 +01:00

4.7 KiB

Quickstart

Read this in: English | Polski

This page takes you from an empty folder to a knowledge base that answers questions from your own material. It covers the first session only. The manual has everything else.

You talk to an AI agent in plain language; it does the filing. The phrases in quotes below are examples. The agent matches what you mean, so you don't need the exact words.

What you need

  • An AI agent that reads AGENTS.md. Claude Code supports every feature. Codex CLI, Cursor, OpenCode and Gemini CLI should work too; see "Using an agent other than Claude Code" in the manual.
  • Git.
  • Python 3.8 or newer. It's optional but worth having: lint, search and a few other checks are scripts, and without Python the agent does them by hand, more slowly. The manual's Prerequisites section has install steps for Windows, macOS and Linux.

1. Create your knowledge base

Get a copy of the template and open your agent in it:

git clone https://git.wierzbowa.cloud/michal/ckb.git ckb-template
cd ckb-template

Then ask for a new, empty KB in a folder of your choice:

"Set up a new wiki like this one in ~/kbs/team-notes."

The agent copies the structure, the rules and the skills, but none of the template's content. It asks before it runs git init. From now on, work in the new folder. You can delete ckb-template once you're done.

2. Start a session

Open your agent in ~/kbs/team-notes and say anything. Before it answers, the agent runs a short check: who you are (from your git identity), whether anything is uncommitted, and whether the wiki has problems. Its first reply starts with a one-line title for the conversation. Rename it if you like: "rename this conversation to onboarding notes".

If your git identity isn't set, the agent says so. Set it once, because it goes into every log entry:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

3. Say what the KB is for

Open ABOUT.md and replace the comments with a few lines of your own: what the KB is for, who reads it, what belongs in it and what doesn't, and anything sensitive. A paragraph per section is plenty.

This is the one file the agent reads and never rewrites. Ingest checks new material against it, so a stray file from the wrong project gets flagged instead of filed.

4. Add material

Drop files into raw/inbox/: meeting notes, a PDF, an exported chat, a .txt of links. No need to tidy them. Then say:

"Ingest."

The agent first tells you, in a few lines per file, how it read each one, which pages it plans to create or change, and what it disagrees with. Then it waits. Correct it here; it's much cheaper than fixing pages later. Once you say go, it writes pages under wiki/, records each source's fingerprint, moves the files to raw/archive/<date>/, and leaves a report in workload/ingest-reports/.

Got a link rather than a file? Install the capture module once ("install the capture module"), then say "capture this link: https://…". The page lands in the inbox as a dated snapshot, ready for the next ingest.

5. Ask questions

Ask the way you'd ask a colleague:

"What did we agree about access requests for new starters?"

The agent finds the pages, checks them against the files they came from, and answers with its sources. It also says when a page is old, unreviewed or contradicted. If the KB doesn't know, it says so and records the gap in wiki/query-gaps.md, so you know what to add next.

An answer worth keeping? Say "keep this answer" and it's saved to outputs/answers/, with its sources.

6. Keep it healthy

Every so often, say "Lint". The agent checks the whole wiki: broken links, stale pages, sources that changed under a page, quotes that no longer match, secrets committed by accident. It fixes what it safely can and asks about the rest.

Pages the agent wrote start as drafts. "What needs review?" lists them, and "mark the access-requests page as reviewed" records that you've read one.

To stop remembering, make it a routine: "lint every week". It then runs at the first session after seven days.

7. Share it

Say "sync changes". The agent checks for secrets, commits, pulls anything new, and pushes. On the first sync it asks for the URL of your remote repository. After that, everyone who works on the KB uses the same phrase to send their changes and receive everyone else's.

It never pushes unless you ask.

Where next

  • The manual covers each task in detail, from recording decisions to linking other people's KBs.
  • ABOUT.md is yours to keep current as the KB grows.
  • The changelog lists every page field and what changed in each release.