kapi context note

$ kapi note [what you noticed]

Record one thing this project's files do every time: a product, feature or plan name as they write it, the spelling variety they keep to, a word they use where writers often use another, who the text addresses. Record it whether or not your own text uses it. Leave alone a word the files write more than one way (record nothing about it, not even a note), an interface label, and wording taken from your task.

For a name or word, pass --term with the form the files use and --instead-of with the form they avoid: the split form of a one-word name, the other spelling, or the other word. kapi derives the other forms to avoid: the spaced, hyphenated and closed spellings of a compound, each part capitalised. "--term Quickcast --instead-of 'Quick cast'" avoids Quick cast, Quick-cast and QuickCast. Without --term a note is a fact in prose.

When a person changes wording, record it with --from (what was there), --to (what replaced it) and --seen-in. A change is evidence about how this project writes. A person's change toward a rule somebody already suggested is that person's backing for it, so the rule is established, and fails a check, unless something recorded argues against it. With --suggest it also records the rule the change implies, so the next use of the old wording is reported. A person's change that reverses a rule in force contests the rule, so their own edit never fails their build.

Every note is a suggestion. Checks report it, no check fails on it, and a person decides about it with "kapi context review". Say where you saw it with --seen-in and --quote. A note holds where its evidence sits; --point narrows that one axis at a time to a value inside it, such as --point market=no, and --valid-from and --valid-to bound how long it holds. Take back a note of your own that was wrong with --withdraw <id>, in the session that recorded it.

Commandcontext note

Groupcontext-assistant

Try it

Runs in your browser against a small sample file. Edit the command before running, or press Run to execute it as shown.

$ kapi context note "the docs address the reader as you"

Flags

Flag	Type	Default	Description
--advisory	bool	false	with --suggest: make that rule report without failing a check once kept
--from	string		for a change a person made: the wording that was there
--instead-of	stringArray		a form the project avoids for --term (repeatable)
--point	stringArray		narrow where it holds, as axis=value within where the evidence sits, such as market=no (repeatable)
--project, -p	string		path to a kapi.yaml project recipe or its directory (auto-discovered from cwd if omitted)
--quote	string		the wording you saw
--seen-in	stringSlice		a file you saw it in, or the change was made in (repeatable)
--suggest	bool	false	with --from and --to: also record the rule the change implies
--term	string		the form the project uses for a name or word
--to	string		for a change a person made: the wording that replaced it
--valid-from	string		it holds from this date (2006-01-02) or instant on
--valid-to	string		it holds until this date (2006-01-02) or instant, not including it
--why	string		what the person said about the change, or what was wrong with the note withdrawn
--withdraw	string		take back a note of your own by its id

More examples

$ kapi context note --term Quickcast --instead-of "Quick cast" \

--seen-in README.md --quote "Quickcast forecasts the next hour."

$ kapi context note --from "sign in" --to "log in" --seen-in web/src/auth.tsx --suggest

$ kapi context note --term "Summer sale" --instead-of "Spring sale" --seen-in promo/no.md \

--point market=no --valid-to 2026-09-01

$ kapi context note --withdraw 0n794e2gk7 --why "recorded the wrong way round"

← Back to the Command Reference