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

127 lines
4.7 KiB
Markdown

# Quickstart
*Read this in: **English** | [Polski](QUICKSTART.pl.md)*
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](MANUAL.md) 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](MANUAL.md#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:
```bash
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:
```bash
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](MANUAL.md) 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](CHANGELOG.md) lists every page field and what changed in
each release.