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>
127 lines
4.7 KiB
Markdown
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.
|