Ýöüŕ ƒîŕšţ þŕöĵéçţ

Àţ ţĥé éñđ öƒ ţĥîš þàĝé, öñé ŵöŕđ îš šþéļļéđ öñé ŵàý àçŕöšš à ƒöļđéŕ öƒ đöçüḿéñţš, àñđ éṽéŕý éđîţ îš çĥéçķéđ àĝàîñšţ ţĥàţ ŕüļé. Ţĥé ŕüļé îš ķéþţ öñçé, àñđ Ķàþî Đéšķţöþ, ýöüŕ àššîšţàñţ àñđ ţĥé ÇĻÎ àļļ éñƒöŕçé îţ.

À þŕöĵéçţ îš à çöḿḿîţţéđ ŕéçîþé (kapi.yaml) ţĥàţ šàýš ŵĥîçĥ ƒîļéš çöüñţ àš çöñţéñţ, þļüš ţĥé ŵîŕîñĝ ţĥàţ ļéţš ţĥé çöđîñĝ àĝéñţš îñ ýöüŕ ŕéþöšîţöŕý ŕéàçĥ ķàþî. Ýöüŕ ƒîŕšţ þŕöĵéçţ ĥàš öñé ļàñĝüàĝé. Ýöü öþéñ ţĥé ƒöļđéŕ, šéé ŵĥàţ ķàþî ƒîñđš, đéçîđé ŵĥàţ ƃéçöḿéš à ŕüļé, çĥéçķ àñđ ƒîẋ ţĥé ƒîļéš, þüţ àñ àššîšţàñţ öñ ţĥé þŕöĵéçţ àñđ šĥàŕé ţĥé ŕüļéš. Ļàñĝüàĝéš àŕé à ļàţéŕ šţéþ.

Ţĥé éẋàḿþļéš çöḿé ƒŕöḿ acme-docs, à ĝîţ ŕéþöšîţöŕý ŵîţĥ à README.md àñđ ƒîṽé Ḿàŕķđöŵñ ƒîļéš üñđéŕ docs/. Ţŵö öƒ îţš ƃļöçķš üšé é-ḿàîļ ŵĥéŕé ţĥé öţĥéŕš üšé éḿàîļ.

1. Öþéñ ţĥé ƒöļđéŕ

Đéšķţöþ
Àĝéñţ (Çļàüđé)
ÇĻÎ

Îñšţàļļ Ķàþî Đéšķţöþ àñđ öþéñ îţ. Çļîçķ Çĥööšé à ƒöļđéŕ, öŕ đŕöþ ţĥé ƒöļđéŕ öñ ţĥé ŵîñđöŵ. Ţö ļööķ àŕöüñđ ƒîŕšţ, Ţŕý ŵîţĥ ĶàþîḾàŕţ öþéñš à šàḿþļé þŕöĵéçţ ŵîţĥ ŕüļéš, ţéŕḿš àñđ àñ àššîšţàñţ'š ñöţéš ţö đéçîđé àƃöüţ.

Ţĥé Öþéñ šçŕééñ ŵîţĥ Çĥööšé à ƒöļđéŕ àñđ Ţŕý ŵîţĥ ĶàþîḾàŕţ

Ķàþî Đéšķţöþ ŕéàđš ţĥé ƒîļéš àñđ çĥàñĝéš ñöţĥîñĝ üñţîļ ýöü àšķ. Ţĥé þŕöĵéçţ öþéñš öñ îţš Öṽéŕṽîéŵ, ţĥé đéšķţöþ ƒöŕḿ öƒ kapi look. Ƒŕöḿ ţĥéŕé:

Ŵĥàţ ýöüŕ ƒîļéš đö ļîšţš ţĥé šüĝĝéšţîöñš, àñđ Đéçîđé àšķš àƃöüţ éàçĥ öñé ŵîţĥ Ķééþ, Ñöţ à ŕüļé öŕ Ļàţéŕ.
À ŕöŵ üñđéŕ Ƒîļéš öþéñš ţĥé ƒîļé îñ ţĥé Ŕéàđéŕ, ŵîţĥ éàçĥ ƒîñđîñĝ îñ þļàçé, ţĥé ŕüļéš îñ ţĥé ḿàŕĝîñ àñđ Ƒîẋ ŵĥéŕé ķàþî çàñ ƒîẋ à ƒîñđîñĝ.
Ţĥé þŕöĵéçţ'š Þŕöĵéçţ Šéţţîñĝš ĥöļđ ţĥé Àššîšţàñţš ţàƃ, ŵĥîçĥ çöññéçţš àñ àššîšţàñţ, àñđ ţĥé Šĥàŕé ţàƃ.

À þŕöĵéçţ'š Öṽéŕṽîéŵ: ţĥé ƒîļéš, ƃļöçķš, ŕüļéš àñđ ƒîñđîñĝš çöüñţš, Ŵĥàţ ýöüŕ ƒîļéš đö ŵîţĥ ţĥé šüĝĝéšţîöñš, àñđ ţĥé Ƒîļéš ļîšţ

Ŕéṽîéŵ ŵĥàţ ýöüŕ àššîšţàñţ ñöţîçéđ ŵàļķš ţĥŕöüĝĥ Đéçîđé öñ ţĥé šàḿþļé.

Walkthrough videoPending recording

Çŕéàţîñĝ à þŕöĵéçţ ƒŕöḿ ţĥé Ñéŵ Þŕöĵéçţ đîàļöĝ, öþéñîñĝ ţĥé ĶàþîḾàŕţ šàḿþļé, àđđîñĝ à çöñţéñţ çöļļéçţîöñ, àñđ ŕéàđîñĝ ţĥé ţŵö-àẋîš šţàñđîñĝ àñđ ŵĥéŕé çöñţéñţ šîţš.

View scene script ↗

Ŵîţĥ ţĥé Ķàþî šķîļļ öŕ ḾÇÞ šéŕṽéŕ çöññéçţéđ, àšķ ƒöŕ ţĥé þŕöĵéçţ:

Šéţ ķàþî üþ ƒöŕ ţĥîš þŕöĵéçţ.

Çļàüđé ŕüñš kapi init àñđ þŕéšéñţš ţĥé þŕöþöšéđ çöñţéñţ çöļļéçţîöñš ƒöŕ ýöüŕ ŕéṽîéŵ. Çöḿḿîţ ţĥé ĝéñéŕàţéđ ŕéçîþé àñđ àĝéñţ çöñƒîĝüŕàţîöñ. Šţéþ 3, đéçîđîñĝ ŵĥàţ ƃéçöḿéš à ŕüļé, îš ýöüŕš, îñ à ţéŕḿîñàļ öŕ îñ Ķàþî Đéšķţöþ.

Îñšţàļļ ţĥé ÇĻÎ, ţĥéñ ƒŕöḿ ţĥé ƒöļđéŕ:

$ kapi init
Initialized kapi project "acme-docs"
  recipe: /path/to/acme-docs/kapi.yaml
  collections (proposed from the files here; edit the recipe to change them):
    README.md     markdown, 1 file
    docs/**/*.md  markdown, 5 files
  mcp:    .mcp.json (created: kapi mcp --project kapi.yaml)
  skill:  .claude/skills/kapi (created: 1 file)
  rules:  AGENTS.md (created)
  rules:  CLAUDE.md (created)

kapi init ŕéàđš ţĥé ƒîļéš îñ ţĥé ƒöļđéŕ, ĥöñöüŕîñĝ .gitignore àñđ šķîþþîñĝ đéþéñđéñçý àñđ ƃüîļđ đîŕéçţöŕîéš. Ţĥé çöļļéçţîöñš àŕé ţĥé ƒîļéš ķàþî ŕéàđš àš çöñţéñţ: đöçüḿéñţš ĝŕöüþéđ ƃý đîŕéçţöŕý, à ƒîļé àţ ţĥé ŕööţ öñ îţš öŵñ, àñđ î18ñ çàţàļöĝš ŵĥéŕé à ķñöŵñ ƒŕàḿéŵöŕķ ļàýöüţ öŕ à ƒîļé ñàḿéđ ƒöŕ ţĥé šöüŕçé ļàñĝüàĝé ḿàŕķš ţĥéḿ. kapi add "<pattern>" àđđš àñöţĥéŕ. Ŕüññîñĝ kapi init àĝàîñ ļéàṽéš ţĥéḿ àš ţĥéý àŕé àñđ þŕîñţš àñý çöñţéñţ ñö çöļļéçţîöñ ŕéàđš ýéţ. Ƒöŕ à ķñöŵñ šţàçķ, kapi init --preset react-i18next (öŕ nextjs, vue-i18n, …) ŵŕîţéš îţš çàţàļöĝ ļàýöüţ ƃéƒöŕé ţĥé ƒîļéš éẋîšţ; kapi init --list-presets ļîšţš ţĥéḿ.

Ţĥé ļàšţ ƒöüŕ ļîñéš çöññéçţ Çļàüđé Çöđé; šţéþ 6 šàýš ŵĥàţ ţĥéý àŕé.

Ţĥé ŕéçîþé îš þļàîñ ÝÀḾĻ:

kapi.yaml
version: v1
# This project's stable identity. It survives a rename, a move and a clone,
# and everything kapi records about the project is keyed on it. Keep it.
id: prj_fyvo35str3o4bv3aty766bj6w4
name: acme-docs
defaults:
  source_language: en

# Collections are the files kapi reads as content. kapi init proposed these
# from the files it found. Edit them freely; 'kapi add <pattern>' adds more.
collections:
  # README.md: Markdown, at the root
  - path: README.md
    format: markdown
  # docs/: 5 Markdown files
  - path: "docs/**/*.md"
    format: markdown

id: ĵöîñš éṽéŕý çĥéçķöüţ, ŵöŕķţŕéé àñđ çļöñé öƒ ţĥé ŕéþöšîţöŕý ţö öñé çöñţéẋţ, šö ķééþ îţ. Çöḿḿîţ ţĥé ŕéçîþé àñđ ţĥé àĝéñţ çöñƒîĝüŕàţîöñ. kapi init éẋçļüđéš .kapi/ ƒŕöḿ ṽéŕšîöñ çöñţŕöļ: îţ ĥöļđš đéŕîṽéđ šţöŕéš àñđ çàçĥéš, þéŕšöñàļ ŕéàđéŕ ƒîļţéŕš, àñđ àñý ŕéđàçţîöñ ṽàüļţ, ŵĥöšé ŵîţĥĥéļđ öŕîĝîñàļš àŕé ļöšţ îƒ ýöü đéļéţé îţ. Šéé Ţĥé þŕöĵéçţ šţöŕé àñđ ţĥé þŕöĵéçţ ƒîļé ŕéƒéŕéñçé.

Éṽéŕý ķàþî çöḿḿàñđ ŕüñ àñýŵĥéŕé îñ ţĥé ţŕéé ƒîñđš ţĥé þŕöĵéçţ ƃý ŵàļķîñĝ üþ, ļîķé ĝîţ.

2. Šéé ŵĥàţ àþþļîéš

kapi look, öŕ kapi öñ îţš öŵñ, þŕîñţš ţĥé þŕöĵéçţ àš ķàþî ŕéàđš îţ:

$ kapi look
acme-docs · read 6 files just now

  6 files · 18 blocks · 0 rules · 2 findings · kapi suggests 1

What your files do
  Name  email, not e-mail, e mail  5 of 7 uses

Files
  docs/guide.md          5 blocks · 2 findings
  docs/faq.md            3 blocks
  docs/installation.md   3 blocks
  docs/reference/api.md  3 blocks
  docs/release-notes.md  2 blocks
  README.md              2 blocks

Decide with `kapi rules`. See a file with `kapi look <path>`.

À ñéŵ þŕöĵéçţ ĥàš ñö ŕüļéš, šö ţĥé ƒîŕšţ ļööķ ŕéçöŕđš ŵĥàţ ķàþî šééš îñ ţĥé ƒîļéš àš šüĝĝéšţîöñš. Îţ üšéš ñö ḿöđéļ ƒöŕ ţĥîš. Ĥéŕé ţĥé ƒîļéš ŵŕîţé éḿàîļ ƒîṽé ţîḿéš àñđ é-ḿàîļ ţŵîçé. Ţĥé ţŵö ƒîñđîñĝš àŕé ţĥé üšéš öƒ é-ḿàîļ, ŕéþöŕţéđ àĝàîñšţ ţĥé šüĝĝéšţîöñ àñđ ƒàîļîñĝ ñöţĥîñĝ. kapi look docs/guide.md þŕîñţš ţĥàţ ƒîļé'š ƃļöçķš ŵîţĥ éàçĥ ƒîñđîñĝ ḿàŕķéđ üñđéŕ ţĥé ŵöŕđš îţ îš àƃöüţ. Îñ Ķàþî Đéšķţöþ, ţĥé þŕöĵéçţ'š Öṽéŕṽîéŵ šĥöŵš ţĥé šàḿé ṽîéŵ.

3. Đéçîđé ŵĥàţ ƃéçöḿéš à ŕüļé

kapi rules àšķš àƃöüţ éàçĥ šüĝĝéšţîöñ, ŵîţĥ ţĥé éṽîđéñçé àñđ ŵĥàţ ķééþîñĝ îţ đöéš. Îñ Ķàþî Đéšķţöþ, Đéçîđé àšķš ţĥé šàḿé ǫüéšţîöñš:

$ kapi rules
[1/1] Which one do your files use?  #0rbnyk4bjm
  * 1) email  5 blocks in 4 files
    2) e-mail  2 blocks in 1 file
    3) e mail  0 blocks in 0 files
    4) Other…
  If you keep "email": the other 2 forms become findings in 2 blocks. Applies to the whole project.
  Seen "Create a workspace, then invite your team by e-mail address." in docs/guide.md

Decide with: kapi rules --keep <id>, --drop <id> or --later <id>

Îñ à ţéŕḿîñàļ îţ ŵàîţš ƒöŕ ýöüŕ àñšŵéŕ: k ķééþš ţĥé ḿàŕķéđ ƒöŕḿ, à ñüḿƃéŕ þîçķš àñöţĥéŕ, n šàýš îţ îš ñöţ à ŕüļé, àñđ l ļéàṽéš îţ ƒöŕ ļàţéŕ. À šüĝĝéšţîöñ ļéƒţ ƒöŕ ļàţéŕ ķééþš àđṽîšîñĝ. Öüţšîđé à ţéŕḿîñàļ îţ ļîšţš ţĥé ǫüéšţîöñš, àñđ ýöü đéçîđé ƃý îđ ŵîţĥ kapi rules --keep 0rbnyk4bjm.

À ķéþţ šüĝĝéšţîöñ ƃéçöḿéš à ŕüļé îñ ţĥé þŕöĵéçţ'š ţéŕḿš šţöŕé, ƃéšîđé ţĥé éṽîđéñçé îţ ŕéšţéđ öñ. ķàþî ŕéŵŕîţéš îţš šéçţîöñ öƒ CLAUDE.md àñđ AGENTS.md, šö ţĥé ñéẋţ àĝéñţ šéššîöñ ŕéàđš ţĥé ŕüļé ţĥéŕé:

Say this, not that:
- email, not "e mail" or "e-mail"

--advisory ķééþš à ŕüļé ţĥàţ ŕéþöŕţš àñđ ñéṽéŕ ƒàîļš. kapi rules list ļîšţš ŵĥàţ ţĥé þŕöĵéçţ ķééþš, àñđ kapi rules drop <id> šéţš à ŕüļé àšîđé. Öñļý à þéŕšöñ ķééþš öŕ đŕöþš à šüĝĝéšţîöñ; šéé Ĝŕöŵîñĝ çöñţéẋţ.

4. Çĥéçķ

Ƃéƒöŕé ýöü ķéþţ îţ, ţĥé šüĝĝéšţîöñ öñļý ŕéþöŕţéđ àñđ kapi check þàššéđ. Ñöŵ îţ ƒàîļš öñ éàçĥ üšé öƒ é-ḿàîļ:

$ kapi check docs/guide.md
  outcome  rule              location                                      message
  FAILS    terms.vocabulary  docs/guide.md:getting-started/next-steps/p#2  Forbidden term "e-mail" found
                                                                           ↳ Use "email" instead
  FAILS    terms.vocabulary  docs/guide.md:getting-started/p               Forbidden term "e-mail" found
                                                                           ↳ Use "email" instead

FAIL configured checks: 2 failing, 0 reported · score 50/100
  Coverage: 2 analyzer runs completed.
  Context: docs/guide.md; voice none (project); terms loaded
Error: quality gate failed

Ţĥé Context: ļîñé ñàḿéš ţĥé ṽöîçé þŕöƒîļé ţĥàţ àþþļîéš àñđ ŵĥéţĥéŕ ţéŕḿš ŵéŕé ļöàđéđ. kapi check ŵîţĥ ñö þàţĥ çĥéçķš ţĥé ŵĥöļé þŕöĵéçţ, àñđ kapi check --ship éñƒöŕçéš ţĥé ŕéļéàšé þöļîçý. Ƃöţĥ éẋîţ 3 ŵĥéñ à ƒîñđîñĝ ƒàîļš, šö ýöü çàñ ŕüñ ţĥé çĥéçķ àš à ÇÎ šţéþ: šéé Šĥîþ ĝàţéš & ÇÎ.

5. Ƒîẋ

kapi fix àþþļîéš ţĥé ŕéþļàçéḿéñţ éàçĥ ƒàîļîñĝ ŵöŕđ-ŕüļé ƒîñđîñĝ ñàḿéš, ţĥéñ çĥéçķš ţĥé ƒîļéš îţ ŵŕöţé àĝàîñ:

$ kapi fix
2 fixed in 1 file
  docs/guide.md  2 fixed: e-mail → email, e-mail → email
kapi check: no failing findings

Éṽéŕý ƃýţé öüţšîđé ţĥé ŕéþļàçéđ ŵöŕđš šţàýš àš îţ ŵàš. Îñ Ķàþî Đéšķţöþ, Ƒîẋ öñ à ƒîñđîñĝ îñ ţĥé Ŕéàđéŕ àþþļîéš ţĥé šàḿé ŕéþļàçéḿéñţ. kapi fix --dry-run þŕîñţš ţĥé çĥàñĝé éàçĥ ƒîļé ŵöüļđ ĝéţ àñđ ŵŕîţéš ñöţĥîñĝ. À ƒîñđîñĝ àƃöüţ ţöñé öŕ šţýļé, öŕ öñé öṽéŕ ŵöŕđš ţĥàţ ĥöļđ à ļîñķ öŕ à þļàçéĥöļđéŕ, ĥàš ñö àüţöḿàţîç ƒîẋ, àñđ kapi fix ļîšţš îţ àš ñééđîñĝ à ŕéŵŕîţé.

6. Þüţ àñ àššîšţàñţ öñ îţ

kapi connect ŵŕîţéš ŵĥàţ àñ àššîšţàñţ ñééđš ţö ƒöļļöŵ ţĥé ŕüļéš: ţĥé ŕüļéš šéçţîöñ îñ AGENTS.md àñđ CLAUDE.md, àñ ḾÇÞ šéŕṽéŕ éñţŕý ţĥàţ šţàŕţš kapi mcp ƒöŕ ţĥîš þŕöĵéçţ, àñđ ţĥé ķàþî šķîļļ. kapi init àļŕéàđý đîđ ţĥîš ƒöŕ Çļàüđé Çöđé, šö ĥéŕé éṽéŕý ƒîļé îš ķéþţ:

$ kapi connect
Claude Code   connected · rules, MCP server, skill
  .mcp.json            kept
  .claude/skills/kapi  kept
  Edit hook            pending: in Claude Code, /plugin marketplace add neokapi/claude-plugins, then /plugin install kapi@neokapi-plugins
  Stop hook            pending: in Claude Code, /plugin marketplace add neokapi/claude-plugins, then /plugin install kapi@neokapi-plugins
Cursor        not connected: no .cursor/ folder here (kapi connect cursor adds it)
VS Code       not connected: no .vscode/ folder here (kapi connect vscode adds it)
Codex         not connected: no .codex/ folder here (kapi connect codex adds it)

Project
  kapi.yaml            kept
  AGENTS.md            kept
  CLAUDE.md            kept

See what an assistant reads for a file: kapi context <path> --explain

Ţĥéñ ĝîṽé ţĥé àššîšţàñţ àñ öŕđîñàŕý ŵŕîţîñĝ ţàšķ. Îţ ŕéàđš ţĥé ŕüļéš àš îţ šţàŕţš, àšķš kapi context <path> ƃéƒöŕé îţ ŵŕîţéš à ƒîļé ţĥé ŕüļéš šéçţîöñ đöéš ñöţ çöṽéŕ, àñđ ŕüñš kapi check öñ éàçĥ ƒîļé îţ çĥàñĝéđ. Çļàüđé Çöđé àšķš ýöü ţö àþþŕöṽé ţĥé þŕöĵéçţ ḾÇÞ šéŕṽéŕ ţĥé ƒîŕšţ ţîḿé, šö ŕéṽîéŵ .mcp.json ţĥé ŵàý ýöü ŵöüļđ àñý ƒîļé à ŕéþöšîţöŕý šĥîþš.

Ŵĥîļé îţ ŵöŕķš, ţĥé àššîšţàñţ ñöţéš ŵĥàţ ţĥé ƒîļéš ķééþ ţö àñđ ţĥé ŵöŕđîñĝ ýöü çĥàñĝé îñ îţš đŕàƒţš. Éàçĥ ñöţé àŕŕîṽéš àš à šüĝĝéšţîöñ îñ kapi rules, àñđ šţéþ 3 đéçîđéš îţ. Šéé Üšé ŵîţĥ Çļàüđé.

7. Šĥàŕé ţĥé ŕüļéš

Ţĥé ŕüļéš ļîṽé îñ ýöüŕ ŵöŕķšþàçé öñ ţĥîš ḿàçĥîñé, ķéýéđ öñ ţĥé þŕöĵéçţ'š id:, šö éṽéŕý çĥéçķöüţ ĥéŕé ŕéàđš ţĥé šàḿé öñéš. kapi share šĥàŕéš ţĥéḿ ŵîţĥ ţĥé þéöþļé ŵĥö ŵöŕķ öñ ţĥé þŕöĵéçţ. Îñ à ŕéþöšîţöŕý ŵîţĥ à ŕéḿöţé, --via git ķééþš ţĥéḿ îñ à ŕéƒ öüţšîđé éṽéŕý ƃŕàñçĥ:

$ kapi share --via git
kapi.yaml  updated
With your team · through git (origin refs/kapi/context)
  pushed 6 changes · pulled none · last sync just now

Çöḿḿîţ ţĥé çĥàñĝé ţö kapi.yaml šö éṽéŕý çĥéçķöüţ šĥàŕéš ţĥŕöüĝĥ ţĥé šàḿé þļàçé. Àƒţéŕ ţĥàţ, kapi share öñ îţš öŵñ ŕéàđš ŵĥàţ ţĥé öţĥéŕš šĥàŕéđ àñđ šĥàŕéš ŵĥàţ ŵàš ķéþţ ĥéŕé. Šéé Šĥàŕîñĝ çöñţéẋţ.

Ļàţéŕ: àđđ ļàñĝüàĝéš

Ŵĥéñ ţĥé þŕöĵéçţ ñééđš à ţàŕĝéţ ļàñĝüàĝé, àđđ îţ ţö ţĥé ŕéçîþé àñđ ŕüñ kapi up. Šéé Àđđ ļàñĝüàĝéš.

Ñéẋţ

Ĝŕöŵîñĝ çöñţéẋţ: ñöţîñĝ, đéçîđîñĝ, àñđ ĝöîñĝ ƃàçķ ţö ƃéƒöŕé àñ àĝéñţ'š šéššîöñ.
Þŕöĵéçţš: ţĥé çöñçéþţ; àđ-ĥöç ṽš þŕöĵéçţ, ţĥé ŕéçîþé, ţĥé šţöŕé.
Šéţ üþ ýöüŕ ƃŕàñđ ĝüîđé îñ 10 ḿîñüţéš: ŵŕîţîñĝ à ṽöîçé þŕöƒîļé ƃý ĥàñđ, ŵĥéñ ýöü ŵàñţ öñé.

1. Öþéñ ţĥé ƒöļđéŕ​

2. Šéé ŵĥàţ àþþļîéš​

3. Đéçîđé ŵĥàţ ƃéçöḿéš à ŕüļé​

4. Çĥéçķ​

5. Ƒîẋ​

6. Þüţ àñ àššîšţàñţ öñ îţ​

7. Šĥàŕé ţĥé ŕüļéš​

Ļàţéŕ: àđđ ļàñĝüàĝéš​

Ñéẋţ​