Set up your brand guide in 10 minutes

Goal: a working voice profile (tone, style, do/don't patterns) and the words it uses and avoids, held by your project and enforced by every check, starting from a template rather than a blank page. You author it as YAML and kapi keeps it in the project's voice store; the profile format documents every field. Start with the rules you can define precisely and refine the profile as you review findings.

Choose a built-in starter pack and adapt it to your requirements: professional-b2b, friendly-dtc, technical-docs, marketing-blog, customer-support.

Desktop

1. Start from your assistant or the CLI to produce brand/voice.yaml (the tabs to the right); the profile is authored as a file either way.
2. Bind it in Project Settings, so the project enforces it.
3. See it work. The findings count on the project's Map now carries voice findings over everything the project tracks, and the voice gate joins each locale's ship-gate cell.

Agent (Claude)

The assistant drafts the profile from copy you already have:

Draft a voice profile for us. Base the tone on our README and landing page, forbid the usual filler ("leverage", "seamless", "cutting-edge"), and use "sign in" not "log in". Bind it in the recipe.

The assistant scaffolds from kapi voice new, fills tone and terms from your existing copy, writes brand/voice.yaml, binds it under defaults.voice, and runs kapi context sync --files-only so AGENTS.md and CLAUDE.md state the voice for the next session. You review the YAML (it's short) and correct the judgment calls. Then ask for the proof:

Now check the README against it.

CLI

Create, validate and import the profile, then run a check:

kapi voice new --pack technical-docs -o brand/voice.yaml   # 1. scaffold from a pack
$EDITOR brand/voice.yaml                                   # 2. your terms, your tone
kapi voice validate brand/voice.yaml                       # 3. structure, enums, regex
kapi voice import brand/voice.yaml                         # 4. voice into the store, terms: into the project's terms
kapi check README.md                                       # 5. first enforced check

The import prints the id it filed the profile under. Name that id in the recipe and every surface picks the profile up without flags:

kapi.yaml

defaults:
  voice:
    profile: acme-docs

From then on kapi voice edit is how you change it: the profile opens in $VISUAL or $EDITOR as the same YAML, what you save is validated the way kapi voice validate validates a file, and the result goes into the store as one recorded change that kapi context log shows. After importing, you can delete the temporary file under brand/.

kapi context sync --files-only writes the voice and the rules into the project's AGENTS.md and CLAUDE.md, which an assistant in the tree loads before it writes, so drafts start on-voice. kapi context <path> prints the full answer for one file as a short markdown guide.

Growing it

Treat the profile like a test suite: every real off-voice finding that reaches review becomes a rule. The keep-source-on-brand loop shows the change-set shape that fixes a draft and adds the rule in one apply; Content governance for AI is the standing model the profile slots into.

Two additions help once you have real rules:

• Forms. The check matches a term exactly, so a rule about utilize misses utilizes until the term lists the other shapes the word takes. kapi terms expand --locale nb asks a model once for the inflections in that language and writes them onto each term as forms, for you to review; --dry-run shows the additions first, and terms that already carry forms are left alone unless you pass --overwrite.
• Rates and scopes. A prohibited pattern under style.prohibited_patterns can carry a rate (max matches per per_words, default 1,000) so a house rule such as "one em dash per thousand words" is a ceiling rather than a ban, and a scope (prose, code, heading) so a ban on implementation words stays out of the code samples that need them. The fields are in the voice profile reference.

Next

• Keep your source content on brand: the day-to-day enforcement loop.
• Voice profile: profile format, scoring, packs.