Šķîþ ţö ḿàîñ çöñţéñţ

Š-01: Ţĥé ķàþî ÇĻÎ

Šüḿḿàŕý​

kapi îš ţĥé ƃîñàŕý à þéŕšöñ ţýþéš. Îţ îš à ţĥîñ Çöƃŕà šĥéļļ (cli/) öṽéŕ ţĥé çöƃŕà-ƒŕéé ĥöšţ ŕüñţîḿé (host/), àššéḿƃļéđ îñ kapi/cmd/kapi. Ṽéŕƃš àŕé ĝŕöüþéđ ƃý îñţéñţ ŕàţĥéŕ ţĥàñ ƃý šüƃšýšţéḿ (Ŵöŕķ, Ļàñĝüàĝéš, Àššéţš, Àđṽàñçéđ), àñđ éṽéŕý öñé öƒ ţĥéḿ ŕüñš éîţĥéŕ àđ ĥöç öñ ƒîļéš ýöü ñàḿé öŕ îñšîđé à þŕöĵéçţ, ŵĥîçĥ ţĥé ÇĻÎ ƒîñđš ƃý à ĝîţ-šţýļé üþŵàŕđ ŵàļķ ƒöŕ à kapi.yaml ŕéçîþé. Ţĥŕéé çöñţŕàçţš ḿàķé ţĥé šüŕƒàçé šçŕîþţàƃļé: öñé öüţþüţ-ƒöŕḿàţ ŕéšöļüţîöñ šĥàŕéđ ƃý éṽéŕý çöḿḿàñđ, öñé éẋîţ-çöđé ţàƃļé, àñđ öñé ĴŠÖÑ éŕŕöŕ éñṽéļöþé. Çöñƒîĝüŕàţîöñ ļîṽéš îñ ţĥé üšéŕ çöñƒîĝ đîŕéçţöŕý; þŕöṽîđéŕ ÀÞÎ ķéýš ļîṽé îñ ţĥé ÖŠ ķéýçĥàîñ. Ţĥé šàḿé ƃîñàŕý àļšö àñšŵéŕš ţö ţĥé ţööļƃöẋ ñàḿéš (Š-04) àñđ šţàŕţš àñ ḾÇÞ šéŕṽéŕ ƒöŕ àĝéñţš (Š-03).

Çöñţéẋţ​

Ţĥé ƒŕàḿéŵöŕķ ĥàš ţö ŕéàçĥ ţĥŕéé çàļļéŕš ţĥàţ šĥàŕé éṽéŕý çàþàƃîļîţý àñđ šĥàŕé àļḿöšţ ñö îñṽöçàţîöñ šţýļé.

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

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

Ţĥé ḿöđüļé ƃöüñđàŕý ƒöļļöŵš ƒŕöḿ ţĥàţ. host/ ĥöļđš ţĥé ŕüñţîḿé (ŕéĝîšţŕîéš, šéŕṽîçéš, þŕöĵéçţ ŕéšöļüţîöñ, ţĥé šţöŕàĝé ļàýéŕ) àñđ ķñöŵš ñöţĥîñĝ àƃöüţ Çöƃŕà. cli/ îš ţĥé Çöƃŕà šĥéļļ ţĥàţ ƃîñđš ƒļàĝš ţö îţ. kapi/ îš ţĥé ƃîñàŕý ţĥàţ ŵîŕéš ţĥé šĥéļļ üþ, àđđš ţĥé ŕéļéàšé-çĥàññéļ àñđ šéļƒ-üþđàţé ƃéĥàṽîöüŕ, àñđ éḿƃéđš ñöţĥîñĝ éļšé. Šéé Ƒ-01 ƒöŕ ţĥé ƒüļļ đéþéñđéñçý đîŕéçţîöñ.

Đéçîšîöñ​

Ƃîñàŕý àñđ ḿöđüļé ļàýöüţ​

kapi îš à Ĝö ƃîñàŕý àţ kapi/cmd/kapi/, îñ ţĥé kapi ḿöđüļé. Îţ đéþéñđš öñ ţĥé ƒŕàḿéŵöŕķ, host, àñđ cli, àñđ öñ ñö þļüĝîñ'š çöđé: à þļüĝîñ îš đîšçöṽéŕéđ àţ ŕüñţîḿé ţĥŕöüĝĥ ţĥé ḿàñîƒéšţ ḿöđéļ àñđ đîšþàţçĥéđ àš à šüƃþŕöçéšš (É-05), šö ţĥé ƃîñàŕý'š đéþéñđéñçý šéţ îš ţĥé ţĥŕéé ḿöđüļéš àƃöṽé àñđ ñöţĥîñĝ à þļüĝîñ ƃŕîñĝš.

kapi/
├── go.mod                   # module github.com/neokapi/neokapi/kapi
├── cmd/kapi/                # root command wiring + telemetry reporter
├── cmd/kapi-wasm-cli/       # the browser build; registers cli.BrowserCommandSet
├── mcptools/                # the hand-authored MCP porcelain
├── preset/                  # built-in preset definitions
└── e2e/                     # end-to-end suite over the built binary

cli.KapiCommandSet(app) îš ţĥé šîñĝļé šöüŕçé öƒ ţŕüţĥ ƒöŕ ŵĥàţ ţĥé ƃîñàŕý éẋþöšéš. Ţĥé ŕööţ çöḿḿàñđ àđđš ţĥöšé, ţĥéñ àţţàçĥéš þļüĝîñ çöḿḿàñđš àñđ çöñţŕîƃüţîöñš öñ ţöþ. Ƃüîļţ-îñš àļŵàýš ŕéĝîšţéŕ ƒîŕšţ, šö îñšţàļļîñĝ à þļüĝîñ çàñ ñéṽéŕ çĥàñĝé ŵĥàţ àñ éẋîšţîñĝ ṽéŕƃ ḿéàñš; à þļüĝîñ çöḿḿàñđ ţĥàţ çöļļîđéš ŵîţĥ à ƃüîļţ-îñ àţţàçĥéš üñđéŕ îţš þļüĝîñ ĝŕöüþ îñšţéàđ. Ţĥé ƃŕöŵšéŕ ƃüîļđ ŕéĝîšţéŕš cli.BrowserCommandSet, ŵĥîçĥ ḿîŕŕöŕš ţĥé ñàţîṽé šéţ ṽéŕƃ ƒöŕ ṽéŕƃ àñđ ŕéçöŕđš ţĥé ṽéŕƃš à ƃŕöŵšéŕ çàññöţ ŕüñ (ŴÀŠḾ Éñĝîñé ÀƂÎ).

Ṽéŕƃš àŕé ĝŕöüþéđ ƃý îñţéñţ​

kapi --help ŕéñđéŕš ƒöüŕ ĝŕöüþš (cli.AddCommandGroups), àñđ ţĥé ĝŕöüþ à ṽéŕƃ ļàñđš îñ îš ţĥé đéçîšîöñ àƃöüţ ŵĥö îţ îš ƒöŕ.

ĜŕöüþŴĥàţ ļîṽéš ţĥéŕé
Ŵöŕķţĥé ļööþ öṽéŕ à þŕöĵéçţ'š öŵñ çöñţéñţ: ƃŕîñĝîñĝ îţ üþ ţö đàţé, çĥéçķîñĝ îţ, ŕéàđîñĝ îţš šţàţüš, ŕéçöŕđîñĝ đéçîšîöñš, àþþļýîñĝ àñ éđîţ, àšķîñĝ ŵĥàţ çöñţéẋţ àþþļîéš, àñđ ţĥé þŕöĵéçţ-çöḿþöšîţîöñ ṽéŕƃš
Ļàñĝüàĝéšţĥé ĝüàŕđŕàîļéđ ƃüîļţ-îñ ƒļöŵš öṽéŕ ƒîļéš ýöü ñàḿé: à ŕéàļ ţŕàñšļàţîöñ þàšš àñđ îţš þšéüđö-ţŕàñšļàţîöñ þŕé-ƒļîĝĥţ
Àššéţšţĥé šţàñđîñĝ ŕéšöüŕçéš à þŕöĵéçţ đŕàŵš öñ: çöñţéñţ ḿéḿöŕý, ţéŕḿš, ṽöîçé þŕöƒîļéš, ḿöđéļš, çŕéđéñţîàļš
Àđṽàñçéđţĥé þļüḿƃîñĝ ţĥé þöŕçéļàîñ çöḿþöšéš, àñđ ţĥé ḿàçĥîñéŕý àŕöüñđ îţ: öñé ñàḿéđ ƒļöŵ, öñé ŕéĝîšţŕý ţööļ, ţĥé ƃîļîñĝüàļ ĥàñđ-öƒƒ, ţĥé þàçķàĝé ṽéŕƃš, ƃļöçķ-ļéṽéļ îñšþéçţîöñ àñđ ḿéàšüŕéḿéñţ, ţĥé ŕéĝîšţŕý ļîšţîñĝš, þļüĝîñ ḿàñàĝéḿéñţ, çöñƒîĝüŕàţîöñ, àñđ ţĥé ḾÇÞ šéŕṽéŕ

À çöḿḿàñđ ƒàḿîļý đîṽîđéš ţĥé šàḿé ŵàý ŵĥéñ îţš ṽéŕƃš šéŕṽé đéŕéñţ ŕéàđéŕš. kapi context (Ŵöŕķ) ļîšţš à þéŕšöñ'š ṽéŕƃš (review, reset, search, sync) üñđéŕ Çöḿḿàñđš àñđ ţĥé ţŵö àñ àššîšţàñţ üšéš (note, log) üñđéŕ Ƒöŕ àššîšţàñţš, àñđ ţĥé ḿàîñţéñàñçé öƒ ţĥé šţöŕé ţĥöšé ṽéŕƃš ŕéàđ îš à šéþàŕàţé çöḿḿàñđ, kapi store (Àđṽàñçéđ: import, export, rebuild, locales) (Ç-11).

Ṽéŕšîöñ, üþđàţé, ţéļéḿéţŕý àñđ šĥéļļ-çöḿþļéţîöñ šţàý üñĝŕöüþéđ, ŕéĝîšţŕý ţööļš ŕéñđéŕ ñö ŕööţ ĝŕöüþ àţ àļļ, àñđ kapi hook îš ĥîđđéñ. Ţĥé çöḿḿàñđ ŕéƒéŕéñçé îš ĝéñéŕàţéđ ƒŕöḿ ţĥé ƃîñàŕý, šö îţ îš ţĥé çüŕŕéñţ ļîšţ ŕàţĥéŕ ţĥàñ ţĥîš þŕöšé.

Ţŵö ṽéŕƃš çàŕŕý ţĥé ļàýéŕîñĝ éẋþļîçîţļý. kapi run <flow> éẋéçüţéš öñé ñàḿéđ ƒļöŵ; kapi exec <tool> éẋéçüţéš éẋàçţļý öñé ŕéĝîšţŕý ţööļ ŵîţĥ ñöţĥîñĝ àŕöüñđ îţ. Ţĥé þöŕçéļàîñ ṽéŕƃš àŕé çöḿþöšîţîöñš öṽéŕ ţĥàţ ļàýéŕ: à þŕöĵéçţ çàţçĥ-üþ ŕüñš ḿàñý ţööļš àçŕöšš ḿàñý ƒîļéš, àñđ à ţŕàñšļàţîöñ þàšš îš à ƒļöŵ ŵîţĥ ŕéçýçļîñĝ àñđ çĥéçķš àŕöüñđ îţ. Ŕéàçĥ ƒöŕ ţĥé þļüḿƃîñĝ ŵĥéñ ýöü ŵàñţ þŕéçîšéļý öñé ţööļ'š ƃéĥàṽîöüŕ.

Ṽéŕƃš ƒöŕ þéöþļé, çĥàñĝé šéţš ƒöŕ šçŕîþţš​

Àñ éđîţ ŕéàçĥéš à ƒîļé ţĥŕöüĝĥ ţĥé çĥàñĝé šéŕṽîçé (É-09), àñđ ţĥé çöḿḿàñđ ļîñé öƒƒéŕš îţ ţŵö ŵàýš. Þéöþļé ķééþ ṽéŕƃš ţĥàţ šàý ŵĥàţ ţĥéý đö: ksed çöḿþîļéš à šüƃšţîţüţîöñ îñţö replace_text öþéŕàţîöñš, éàçĥ ĝüàŕđéđ ƃý ţĥé ŕéṽîšîöñ ksed ŕéàđ, àñđ àþþļîéš ţĥéḿ ţĥŕöüĝĥ ţĥé šéŕṽîçé. Šçŕîþţš àñđ àĝéñţš šéñđ à ķàþî.çĥàñĝé/ṽ1 çĥàñĝé šéţ ţö kapi apply, ŵĥîçĥ ŕéàđš öñé ĴŠÖÑ öƃĵéçţ, ĴŠÖÑĻ öŕ àñ àŕŕàý öƒ öþéŕàţîöñš ƒŕöḿ à ƒîļé öŕ šţàñđàŕđ îñþüţ, àþþļîéš îţ ŵĥöļé öŕ ñöţ àţ àļļ, þŕéṽîéŵš îţ ŵîţĥ --dry-run, þŕîñţš ţĥé ķàþî.çĥàñĝé-ŕéšüļţ/ṽ1 ŕéšüļţ ŵîţĥ --json, àñđ þŕîñţš ţĥé çöñţŕàçţ'š šçĥéḿà ŵîţĥ --schema. Ţĥé çöḿḿàñđ ļîñé šţàḿþš ţĥé àçţöŕ ţĥé éñṽîŕöñḿéñţ ñàḿéš; à çĥàñĝé šéţ ñàḿéš ñöñé.

kapi inspect îš ţĥé ŕéàđ ţĥàţ þàîŕš ŵîţĥ îţ. Îţ ŕéàđš ţĥŕöüĝĥ ţĥé šàḿé šéŕṽîçé, ŵîţĥ ţĥé ƒöŕḿàţ àñđ çöñƒîĝüŕàţîöñ ţĥé ŕéçîþé ƃîñđš îñšîđé à þŕöĵéçţ (ţĥé öñé -p ñàḿéš, öŕ ţĥé öñé đîšçöṽéŕý ƒîñđš), àñđ þŕîñţš éàçĥ ƃļöçķ'š ŕéƒéŕéñçé àñđ ŕéṽîšîöñ, šö àñ öþéŕàţîöñ çöþîéš ŵĥàţ ţĥé ŕéàđ þŕîñţéđ îñšţéàđ öƒ çöñšţŕüçţîñĝ àñ àđđŕéšš. À ƒîļé öƒ ţĥé þŕöĵéçţ îš ñàḿéđ ƃý îţš þŕöĵéçţ-ŕéļàţîṽé þàţĥ, àñđ à ƒîļé öüţšîđé îţ ƃý îţš àƃšöļüţé þàţĥ, ŵĥîçĥ kapi apply îñ ţĥé þŕöĵéçţ ŕéšöļṽéš ţĥé šàḿé ŵàý. ksed ŕéšöļṽéš ţĥé ƒîļéš îţ îš ĝîṽéñ ţĥé šàḿé ŵàý, šö --print-ops þŕîñţš ţĥé çĥàñĝé šéţ ksed ŵöüļđ àþþļý àñđ kapi apply àþþļîéš îţ àš þŕîñţéđ, ƒŕöḿ àñý đîŕéçţöŕý öƒ ţĥé þŕöĵéçţ; kapi apply --print-ops þŕîñţš ţĥé šéţ àš đéçöđéđ. Ţĥé ƒöŕḿàţ à þéŕšöñ çàñ ŕéàđ îš ţĥé ƒöŕḿàţ àñ àĝéñţ šéñđš. Ţĥé ƒļöŵ ṽéŕƃš (kapi translate, pseudo-translate, run, up, àñđ kapi exec ƒöŕ à ţööļ ţĥàţ ŵŕîţéš) ţàķé --print-ops àš ŵéļļ: ţĥé ŕüñ ŵŕîţéš ñö ƒîļé àñđ ŕéçöŕđš ñö çĥàñĝé, àñđ þŕîñţš ţĥé çĥàñĝé šéţ îţ ŵöüļđ àþþļý, ŵĥîçĥ kapi apply àþþļîéš ţö ţĥé šàḿé ƃýţéš; éàçĥ ƒîļé îţ ļéàṽéš öüţ îš ñàḿéđ öñ šţđéŕŕ (É-09).

Ŕéĝîšţŕý ţööļš đö ñöţ àþþéàŕ àš ţöþ-ļéṽéļ ṽéŕƃš; ţĥéý àŕé ŕéàçĥéđ ţĥŕöüĝĥ kapi exec. Ţĥé ĝéñéŕàţéđ çöḿḿàñđ ŕéƒéŕéñçé ļîšţš éàçĥ öñé ŵîţĥ îţš šçĥéḿà, šö ţĥé šéţ šţàýš đéŕîṽéđ ƒŕöḿ ţĥé ŕéĝîšţŕý ŕàţĥéŕ ţĥàñ ţŕàñšçŕîƃéđ îñţö þŕöšé.

Àđ-ĥöç àñđ þŕöĵéçţ ḿöđéš​

Ḿöšţ ṽéŕƃš ŵöŕķ öñ ƒîļéš ýöü ñàḿé. Ŵĥéŕé à þŕöĵéçţ ŵöüļđ šüþþļý đéƒàüļţš, ţĥé ṽéŕƃ ţàķéš -p / --project (ŕéĝîšţéŕéđ ƃý host.AddProjectFlag) àñđ ŕéšöļṽéš îţ ţĥŕöüĝĥ öñé šĥàŕéđ ĥéļþéŕ, host.ResolveProjectPath, ŕé-éẋþöŕţéđ àš cli.ResolveProjectPath.

Explicit -p <path>wins outrightnot givenKAPI_NO_PROJECT setstop: no implicit projectnot setKAPI_PROJECTenvironment overrideemptyUpward walkproject.ResolveLayout(cwd)nothing foundAd-hoc modeor "not a kapi project"

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

Ţĥé üþŵàŕđ ŵàļķ îš ŵĥàţ ḿàķéš à þŕöĵéçţ ŵöŕķ ļîķé à ŕéþöšîţöŕý: ŕüñ à ṽéŕƃ àñýŵĥéŕé îñšîđé ţĥé ţŕéé àñđ îţ ƃîñđš ţö ţĥé ŕéçîþé àƃöṽé îţ. KAPI_NO_PROJECT îš ţĥé öþţ-öüţ, àñđ àñýţĥîñĝ ţĥàţ ŕüñš îñšîđé à þŕöĵéçţ ţŕéé ŵîţĥöüţ ŵàñţîñĝ ţö àçţ öñ îţ (à ţéšţ ĥàŕñéšš, à ñéšţéđ ƃüîļđ) đéþéñđš öñ îţ. Šéţţîñĝ KAPI_PROJECT ţö ţĥé éḿþţý šţŕîñĝ đöéš ñöţ đîšàƃļé đîšçöṽéŕý; öñļý à ñöñ-éḿþţý KAPI_NO_PROJECT đöéš.

Öñçé à þŕöĵéçţ ŕéšöļṽéš, îţ šüþþļîéš ţĥé đéƒàüļţš à ƒļàĝ ŵöüļđ öţĥéŕŵîšé ĥàṽé ţö çàŕŕý: šöüŕçé àñđ ţàŕĝéţ ļöçàļéš, çöñçüŕŕéñçý àñđ éñçöđîñĝ, ţĥé ƃöüñđ šţöŕéš, àñđ ţĥé þļüĝîñ šçöþîñĝ ţĥàţ ñàŕŕöŵš ƒöŕḿàţ đéţéçţîöñ ţö ŵĥàţ ţĥé ŕéçîþé đéçļàŕéš (Ç-01).

Éṽéŕý ļöçàļé ţĥàţ éñţéŕš ţĥŕöüĝĥ à ƒļàĝ, àñ éñṽîŕöñḿéñţ ṽàŕîàƃļé, à ŕéçîþé öŕ à ƒîļé îš çàñöñîçàļîžéđ öñ ţĥé ŵàý îñ. core/locale.Canonical àççéþţš ŵĥàţ þéöþļé àñđ ƒîļé ƒöŕḿàţš ŵŕîţé (nb_NO, en_US.UTF-8, NB-no) àñđ ŕéţüŕñš ţĥé ƂÇÞ-47 ƒöŕḿ ţĥé ŕéšţ öƒ ţĥé šýšţéḿ ĥöļđš, àñđ îţ ŕéĵéçţš à ṽàļüé ţĥàţ îš ñöţ à ļöçàļé, šö à ţýþö çàññöţ ƃéçöḿé àñ îđéñţîţý ñöţĥîñĝ çĥéçķš. Ţĥé ŕéçîþé'š locale_format (bcp-47, ţĥé đéƒàüļţ, öŕ posix) ĝöṽéŕñš öñļý ĥöŵ à ļöçàļé îš šþéļļéđ îñ ţĥé þàţĥš ķàþî ŵŕîţéš; îñţéŕñàļļý ţĥéŕé îš öñé šþéļļîñĝ.

kapi exec <tool> ţàķéš -p / --project ļîķé éṽéŕý öţĥéŕ þŕöĵéçţ-àŵàŕé çöḿḿàñđ, àñđ îţš þŕöĝŕéšš ƃàŕ îš --progress ŵîţĥ ñö šĥöŕţĥàñđ. Ñàḿîñĝ à þŕöĵéçţ çĥàñĝéš ŵĥàţ ĝöṽéŕñš ţĥé ŕüñ (ţĥé ŕéçîþé'š ţööļ þŕéšéţš, ţéŕḿ ŕüļéš àñđ šţöŕéš); ţĥé ƒîļéš ñàḿéđ öñ ţĥé çöḿḿàñđ ļîñé šţàý ţĥé ƒîļéš ñàḿéđ, éàçĥ ŕéàđ ƃý ţĥé ƒöŕḿàţ îţš éẋţéñšîöñ çàļļš ƒöŕ.

Öñé öüţþüţ çöñţŕàçţ​

Éṽéŕý çöḿḿàñđ ţĥàţ þŕöđüçéš öüţþüţ ŕéšöļṽéš îţš ƒöŕḿàţ ţĥŕöüĝĥ host/output, ŵĥîçĥ ŕéĝîšţéŕš --json, --text, --output-format, àñđ --jq öñçé. Ŕéšöļüţîöñ îš ƃý þŕéçéđéñçé, ĥîĝĥéšţ ƒîŕšţ:

  1. --jq <expr>: à ƒîļţéŕ îḿþļîéš ĴŠÖÑ.
  2. --json.
  3. --text.
  4. --output-format=<text|table|json|yaml>.
  5. Đéƒàüļţ: ţéẋţ.

ÝÀḾĻ éḿîţš ţĥé šàḿé šţŕüçţüŕéđ ŕéçöŕđ àš ĴŠÖÑ. Ţéẋţ îš ţĥé ĥüḿàñ ŕéñđéŕîñĝ: ţàƃļéš, àļîĝñéđ çöļüḿñš, çöļöüŕ ŵĥéñ ţĥé ţéŕḿîñàļ šüþþöŕţš îţ àñđ --color / NO_COLOR þéŕḿîţ îţ.

Éàçĥ çöḿḿàñđ đéçļàŕéš îţš ŕéšüļţ àš à çöñçŕéţé Ĝö ţýþé ŵîţĥ json ţàĝš, àñđ ţĥé ţýþé îš éẋþéçţéđ ţö ƃé çöḿþļéţé ŕàţĥéŕ ţĥàñ à ţŕàñšçŕîþţîöñ öƒ ŵĥàţ ţéẋţ ḿöđé šĥöŵš. Ţýþéš ţĥàţ ŕéñđéŕ ţĥéḿšéļṽéš îḿþļéḿéñţ öñé îñţéŕƒàçé:

type TextFormatter interface {
    FormatText(w io.Writer) error
}

À ţýþé ŵîţĥöüţ öñé ƒàļļš ƃàçķ ţö ƒöŕḿàţţéđ ĴŠÖÑ, šö à ñéŵ çöḿḿàñđ îš ñéṽéŕ üñŕéàđàƃļé, öñļý üñþöļîšĥéđ.

Éẋîţ çöđéš àñđ ţĥé éŕŕöŕ éñṽéļöþé​

ÇöđéŠýḿƃöļḾéàñîñĝ
0ExitOKšüççéšš
1ExitErroröþéŕàţîöñàļ éŕŕöŕ, ţĥé đéƒàüļţ ƒöŕ à ƒàîļéđ çöḿḿàñđ
2ExitUsageüšàĝé éŕŕöŕ, àñđ ţĥé ţööļƃöẋ'š ĝŕéþ-šţýļé "ţŕöüƃļé" šţàţüš
3ExitGateà ǫüàļîţý öŕ ṽöîçé ĝàţé ŵàš ñöţ ḿéţ, öŕ kapi apply ŕéƒüšéđ à çĥàñĝé šéţ (ñöţĥîñĝ ŵàš ŵŕîţţéñ)
4ExitNotRunà çĥéçķ ŕéàçĥéđ ñö ṽéŕđîçţ: îţ çĥéçķéđ ñö çöñţéñţ, öŕ àñ àñàļýžéŕ ḿîššéđ îţš çàñàŕý
5ExitUnreachableţĥé çöñţéẋţ ƃàçķéñđ kapi context sync šĥàŕéš ţĥŕöüĝĥ, öŕ à çĥàñĝé šéţ'š ƃàçķéñđ, çöüļđ ñöţ ƃé ŕéàçĥéđ; ñöţĥîñĝ çĥàñĝéđ öñ éîţĥéŕ šîđé
130ExitSignalîñţéŕŕüþţéđ (128 + ŠÎĜÎÑŢ)

À đŕàƒţ ţĥàţ šçöŕéš ƃéļöŵ îţš ţĥŕéšĥöļđ îš ñöţ à çŕàšĥ, àñđ à šçŕîþţ ţĥàţ çàññöţ ţéļļ ţĥé ţŵö àþàŕţ ĥàš ţö çĥööšé ƃéţŵééñ îĝñöŕîñĝ ŕéàļ ƒàîļüŕéš àñđ ţŕéàţîñĝ éṽéŕý ļöŵ šçöŕé àš öñé. À çĥéçķ öṽéŕ ñöţĥîñĝ îš ñéîţĥéŕ: îţ îš ñöţ à þàšš, àñđ îţ ĥàš ñö ƒîñđîñĝš ţö ƒîẋ. host.ErrQualityGate ḿàþš ţö ExitGate àñđ host.ErrCheckNotRun ţö ExitNotRun; à þüļļ öŕ þüšĥ ţĥàţ çàññöţ ŕéàçĥ îţš ƃàçķéñđ ţàĝš îţš éŕŕöŕ ŵîţĥ ExitUnreachable, šö à ÇÎ ĵöƃ çàñ ŕéţŕý îţ; à çöḿḿàñđ çàñ ŕéǫüéšţ àñý öţĥéŕ çöđé ƃý ţàĝĝîñĝ îţš éŕŕöŕ ŵîţĥ host.WithExitCode. host.ErrSilentExit ŕéǫüéšţš à ñöñ-žéŕö éẋîţ ŵîţĥ ţĥé ḿéššàĝé šüþþŕéššéđ, ŵĥîçĥ îš ĥöŵ ţĥé ţööļƃöẋ ŕéþöŕţš "ñö ḿàţçĥ" àš à šţàţüš ŕàţĥéŕ ţĥàñ àš àñ éŕŕöŕ ļîñé (Š-04).

Üñđéŕ --json, à ƒàîļüŕé îš à šţŕüçţüŕéđ éñṽéļöþé ŕàţĥéŕ ţĥàñ à þŕöšé ļîñé, ŵîţĥ ţĥé çöđé šýḿƃöļ ḿîŕŕöŕîñĝ ţĥé éẋîţ çöđé:

{
  "error": "failed to connect to server",
  "code": "unreachable"
}

Ļöñĝ-ŕüññîñĝ ṽéŕƃš çàñ àļšö šţŕéàḿ þŕöĝŕéšš ţö šţđéŕŕ àš ÑĐĴŠÖÑ ŵîţĥ --progress=jsonl, ķééþîñĝ šţđöüţ ŕéšéŕṽéđ ƒöŕ ţĥé ŕéšüļţ. Ţĥé ƒüļļ ḿàçĥîñé çöñţŕàçţ îš đöçüḿéñţéđ îñ Šçŕîþţîñĝ & ĴŠÖÑ çöñţŕàçţ.

Çŕéđéñţîàļš àñđ çöñƒîĝüŕàţîöñ​

Ţĥé çŕéđéñţîàļ šţöŕé ļîṽéš îñ host/credentials/ àñđ îš šĥàŕéđ ŵîţĥ Ķàþî Đéšķţöþ (Š-02). Ñöñ-šéçŕéţ þŕöṽîđéŕ çöñƒîĝüŕàţîöñ îš ĴŠÖÑ àţ providers.json üñđéŕ ţĥé ķàþî çöñƒîĝ đîŕéçţöŕý; ÀÞÎ ķéýš ĝö ţö ţĥé ÖŠ ķéýçĥàîñ üñđéŕ ţĥé šéŕṽîçé ñàḿé kapi: ḿàçÖŠ Ķéýçĥàîñ, Ŵîñđöŵš Çŕéđéñţîàļ Ḿàñàĝéŕ, öŕ ļîƃšéçŕéţ öñ Ļîñüẋ. Ŵĥéŕé ñö ķéýçĥàîñ éẋîšţš, à þŕöṽîđéŕ ķéý îš ŕéàđ ƒŕöḿ îţš çöñṽéñţîöñàļ éñṽîŕöñḿéñţ ṽàŕîàƃļé, ţĥé ļîšţ core/credentials/providerenv ñàḿéš, àñđ ţĥé ĥöšţ šţŕîþš ţĥöšé ṽàŕîàƃļéš ƒŕöḿ éṽéŕý þļüĝîñ šüƃþŕöçéšš éñṽîŕöñḿéñţ šö à ķéý ķàþî ĥöļđš ñéṽéŕ ŕéàçĥéš à þļüĝîñ ƃý àççîđéñţ.

Àþþļîçàţîöñ çöñƒîĝüŕàţîöñ šîţš îñ ţĥé šàḿé đîŕéçţöŕý: ~/.config/kapi öñ Ļîñüẋ, ~/Library/Application Support/kapi öñ ḿàçÖŠ, öṽéŕŕîđàƃļé ŵîţĥ KAPI_CONFIG_DIR, àñđ þŕîñţéđ ƃý kapi config path:

kapi.yaml                # global settings
providers.json           # provider configs (keys in the keychain)
plugins/                 # installed plugins

kapi.yaml ĥéŕé ĥöļđš ĝļöƃàļ đéƒàüļţš: öüţþüţ ƒöŕḿàţ, ļöĝ ļéṽéļ, þļüĝîñ đîŕéçţöŕý, ÜÎ ļàñĝüàĝé, üþđàţé çĥàññéļ, ţéļéḿéţŕý öþţ-îñ, đéƒàüļţ þŕöṽîđéŕ. Ţĥîš îš ţĥé ĝļöƃàļ çöñƒîĝ ƒîļé àñđ îš ñöţ ţĥé þŕöĵéçţ ŕéçîþé, ŵĥîçĥ îš à kapi.yaml àţ à þŕöĵéçţ ŕööţ (Ç-01). ÇĻÎ ƒļàĝš öṽéŕŕîđé çöñƒîĝüŕàţîöñ ṽàļüéš; KAPI_-þŕéƒîẋéđ éñṽîŕöñḿéñţ ṽàŕîàƃļéš öṽéŕŕîđé ţĥé ƒîļé. KAPI_PLUGINS_DIR ñàḿéš àñ àļţéŕñàţîṽé þļüĝîñ ŕööţ.

kapi init þŕöþöšéš, àñđ ŵîŕéš ţĥé àĝéñţš​

kapi init çŕéàţéš à þŕöĵéçţ ŵîţĥöüţ îñţéŕàçţîṽé þŕöḿþţš. Îţ þŕöþöšéš çöñţéñţ çöļļéçţîöñš ƒŕöḿ éẋîšţîñĝ ƒîļéš àñđ ŕéçöŕđš ţĥé ḿàţçĥéš îñ ŕéçîþé çöḿḿéñţš (Ç-01). Îţ àļšö ŵŕîţéš àĝéñţ çöñƒîĝüŕàţîöñ:

  • àñ ḾÇÞ šéŕṽéŕ éñţŕý ţĥàţ šţàŕţš kapi mcp --project kapi.yaml, ŵîţĥ --tools writing,translation ŵĥéñ ţĥé ŕéçîþé đéçļàŕéš ţàŕĝéţ ļàñĝüàĝéš, îñ éàçĥ ĥöšţ'š öŵñ çöñƒîĝüŕàţîöñ ƒîļé (.mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml);
  • à šĥöŕţ SKILL.md đéšçŕîƃîñĝ çöñţéẋţ ŕéţŕîéṽàļ, ñöţéš àƃöüţ ŵĥàţ ţĥé þŕöĵéçţ đöéš àñđ ŵĥàţ à þéŕšöñ çĥàñĝéđ, àñđ çĥéçķš, ŵîţĥ ÇĻÎ àñđ ḾÇÞ éǫüîṽàļéñţš àñđ šéššîöñ-ŕéþöŕţîñĝ ĝüîđàñçé.

Ŕéŕüññîñĝ îñîţîàļîžàţîöñ þŕéšéŕṽéš éẋîšţîñĝ çöļļéçţîöñš àñđ ŕéþöŕţš üñçöṽéŕéđ çöñţéñţ. Îţ üþđàţéš ĝéñéŕàţéđ ḾÇÞ éñţŕîéš ţö ḿàţçĥ ţĥé ŕéçîþé ŵĥîļé þŕéšéŕṽîñĝ çüšţöḿ éñţŕîéš. Öƃšöļéţé ĝéñéŕàţéđ šķîļļ ƒîļéš àŕé îđéñţîƒîéđ ƃý çöñţéñţ àñđ ŕéḿöṽéđ; üšéŕ-àüţĥöŕéđ ƒîļéš ŕéḿàîñ îñţàçţ.

kapi help <topic> šéŕṽéš ţĥé ĝüîđàñçé​

Ţĥé šķîļļ šţàýš šĥöŕţ ƃéçàüšé ţĥé ƃîñàŕý çàŕŕîéš ţĥé ŕéšţ. kapi help þŕîñţš ţĥé çöḿḿàñđ öṽéŕṽîéŵ àñđ ţĥéñ ţĥé ţöþîçš; kapi help <topic> þŕîñţš öñé, šéŕṽéđ ƒŕöḿ ţĥé éḿƃéđđéđ šķîļļ ŕéƒéŕéñçéš (host/skills), ŵîţĥ ļîñķš ƃéţŵééñ ŕéƒéŕéñçéš ŕéŵŕîţţéñ àš ţĥé kapi help çöḿḿàñđ ţĥàţ šéŕṽéš éàçĥ. Àñ àĝéñţ ţĥéŕéƒöŕé ŕéàđš ţĥé ĝüîđàñçé öƒ ţĥé ƃîñàŕý îţ îš ŕüññîñĝ. À ţöþîç ţĥàţ šĥàŕéš à ñàḿé ŵîţĥ à çöḿḿàñđ (check, context, translate, voice) þŕîñţš ţĥé ĝüîđé àñđ ñàḿéš ţĥé çöḿḿàñđ'š öŵñ --help.

Àĝéñţ àñđ ţööļƃöẋ šüŕƒàçéš öñ ţĥé šàḿé ƃîñàŕý​

kapi mcp šţàŕţš àñ ḾÇÞ šéŕṽéŕ öṽéŕ šţđîö, šéŕṽîñĝ ţĥé ţööļ šéţš --tools ñàḿéš (writing, ŵîţĥ ţĥé context:// ŕéšöüŕçéš, ŵĥéñ îţ ñàḿéš ñöñé); --all-tools àñđ --all-flows àđđ ţööļš ñö šéţ ĥöļđš, ƒöŕ đéƃüĝĝîñĝ, àñđ --all šéŕṽéš éṽéŕý šéţ àñđ ƃöţĥ. kapi hook þŕöṽîđéš ţĥé àššîšţàñţ-îñţéĝŕàţîöñ ĥööķš. Ƃöţĥ àŕé çöṽéŕéđ îñ Š-03.

Ţĥé ƃîñàŕý àļšö àñšŵéŕš ţö kcat, kgrep, ksed, kconv, àñđ kdiff ŵĥéñ îñṽöķéđ üñđéŕ ţĥöšé ñàḿéš, ƃüšýƃöẋ-šţýļé, àñđ çàŕŕîéš ţĥéḿ àš ĥîđđéñ šüƃçöḿḿàñđš šö kapi kgrep àñđ kgrep ƃéĥàṽé îđéñţîçàļļý (Š-04).

Çöñšéǫüéñçéš​

  • Öñé ƃîñàŕý çöṽéŕš àđ-ĥöç þŕöçéššîñĝ, þŕöĵéçţ ŵöŕķƒļöŵš, àĝéñţ îñţéĝŕàţîöñ, àñđ ţĥé ţööļƃöẋ, ŵîţĥ ñö ƃüîļđ ƒļàĝš àñđ ñö šéþàŕàţé đîšţŕîƃüţîöñš.
  • Ƃéçàüšé ţĥé ÇĻÎ îš à šĥéļļ öṽéŕ host, éṽéŕý çàþàƃîļîţý îţ éẋþöšéš îš ŕéàçĥàƃļé ŵîţĥöüţ Çöƃŕà, ŵĥîçĥ îš ŵĥàţ ļéţš Ķàþî Đéšķţöþ àñđ éḿƃéđđéđ ŕüñš šĥàŕé ţĥé îḿþļéḿéñţàţîöñ îñšţéàđ öƒ ŕéîḿþļéḿéñţîñĝ îţ.
  • Ĝŕöüþîñĝ ƃý îñţéñţ ḿéàñš ţĥé ĥéļþ öüţþüţ àñšŵéŕš "ŵĥàţ àḿ Î ţŕýîñĝ ţö đö" ŕàţĥéŕ ţĥàñ "ŵĥàţ šüƃšýšţéḿ îš ţĥîš", àñđ îţ ĝîṽéš ţĥé þöŕçéļàîñ/þļüḿƃîñĝ šþļîţ à þļàçé ţö ļîṽé îñ ţĥé îñţéŕƒàçé îţšéļƒ.
  • Ţĥé šĥàŕéđ öüţþüţ çöñţŕàçţ ḿàķéš jq àñđ ļàñĝüàĝé-šþéçîƒîç þàŕšéŕš ŵöŕķ üñîƒöŕḿļý, àñđ ţĥé ĴŠÖÑ éŕŕöŕ éñṽéļöþé ḿéàñš à šçŕîþţéđ çàļļéŕ ñéṽéŕ þàŕšéš þŕöšé.
  • Ţĥé đîšţîñçţ ĝàţé éẋîţ çöđé ļéţš ÇÎ àñđ àĝéñţš ƃŕàñçĥ öñ "ƃéļöŵ ţĥŕéšĥöļđ" ṽéŕšüš "çŕàšĥéđ" ŵîţĥöüţ ŕéàđîñĝ öüţþüţ, ţĥé þŕöþéŕţý ţĥé àššîšţàñţ ļööþš îñ Š-03 đéþéñđ öñ.
  • Ķéýçĥàîñ šţöŕàĝé ķééþš ÀÞÎ ķéýš öüţ öƒ šĥéļļ ĥîšţöŕý àñđ àñýţĥîñĝ çöḿḿîţţéđ; à ķéý šüþþļîéđ ţĥŕöüĝĥ ţĥé éñṽîŕöñḿéñţ îš àççéþţéđ àñđ šçŕüƃƃéđ ƒŕöḿ éṽéŕý šüƃþŕöçéšš.
  • Öñé ļöçàļé šþéļļîñĝ îñšîđé ţĥé šýšţéḿ ḿéàñš à ţàŕĝéţ ļàñĝüàĝé ŵŕîţţéñ ţĥŕéé ŵàýš îñ ţĥŕéé þļàçéš šţîļļ ŕéšöļṽéš ţö öñé ţŕàñšļàţîöñ.
  • Àđ-ĥöç ḿöđé ĥàš ñö šţàţé ƃéýöñđ ţĥé îñþüţ ƒîļé, šö à ÇÎ ĵöƃ ñééđš ñöţĥîñĝ þŕöṽîšîöñéđ ţö ŕüñ öñé.

Ŕéļàţéđ​