Your first project

A project is a committed recipe (kapi.yaml) plus a store that remembers your work: approvals, content memory, terminology. Set it up once and every surface works the same project: the desktop app, your AI assistant, and the CLI. A new project starts source-only (checks, voice, terminology); add languages when you want them.

Desktop

Install Kapi Desktop and open it. On first open, the Connect your AI card offers whatever it detects (a Claude Code sign-in that uses your Claude subscription with no key, a local Ollama model, or a stored API key) in one click; or skip and use the demo engine.

1. Create the project. On the home screen, click New Project, name it, and pick a source language. Or click KapiMart under sample projects to explore a realistic, pre-seeded project first: content collections, a bound voice profile and terms, five target languages, and a stocked content memory.
2. Add content. In the Project view, add a pattern that matches your source files (for example docs/**/*.md). Kapi lists the matched files and the detected format, grouped into a collection.
3. Read where it stands. The project home says where the project is on two axes: Content (what has been read in, what changed on disk, what is missing) and Governance (the voice profile in force, the terms bound, when it last converged). Below, the point map gives one row per point the recipe declares. Bind a voice profile and set the default point under Project Settings; the Context hub then shows what applies at any file.
4. Bring it up to date. Bring up to date runs the project's default flow until every gated scope is shippable or parked for a person, the desktop form of kapi up. For a source-only project that means the checks; once you add languages, per-language coverage appears on the collections it applies to.
5. Review what parked. Anything a machine can't decide lands in the Review queue. See Review & approve.

▶

Walkthrough videoPending recording

Creating a project from the New Project dialog, opening the KapiMart sample, adding a content collection, and reading the two-axis standing and the point map.

View scene script ↗

Agent (Claude)

With the Kapi skill or MCP server connected, ask for the project:

Set kapi up for this project.

Claude detects the stack, runs kapi init (with --preset <stack> for a known i18n layout), adds the content patterns it finds, drafts a voice profile from your existing copy, and proposes terms for you to approve. The result is committed: a recipe, a voice profile, a terms source, and a section in CLAUDE.md saying the voice is held by kapi, so the next session asks for it before writing. From there your prompts stay short; "check this is on brand" needs no flags, because the recipe carries them.

CLI

Install the CLI, then from your content directory:

kapi init                      # scaffold kapi.yaml + the .kapi/ store (source-only)
kapi add "docs/**/*.md"        # declare the content; format auto-detected
kapi stats                     # blocks, words, characters for what's tracked
kapi check                     # check the project's content; exit 3 on gate fail

For a known stack, kapi init --preset react-i18next (or nextjs, vue-i18n, …) pre-fills the content mapping; kapi init --list-presets lists them.

A scaffolded project binds a starter voice, so kapi init also writes a short section into the project's assistant file: an existing CLAUDE.md or AGENTS.md at the root, or a new CLAUDE.md. The section says the voice is held by kapi and that kapi voice guide retrieves it, so an assistant working in the tree asks before it writes. It sits between <!-- kapi:voice --> markers and is replaced in place on every run; the rest of the file is yours. A section that landed in AGENTS.md reaches an assistant limited to CLAUDE.md through an import line, @AGENTS.md. kapi init --no-pointer skips it, and kapi voice pointer writes or refreshes it on an existing project.

The recipe is plain YAML, and the governance a source-only project checks against is bound under defaults::

kapi.yaml

version: v1
name: my-app
defaults:
  source_language: en
  voice: .kapi/voice.yaml            # the voice profile: kapi voice new --pack <pack> -o .kapi/voice.yaml
  terms_source: .kapi/terms.json     # the committed terms record: kapi terms import / kapi apply write it
  coordinates:
    brand: my-app                    # a declared axis every collection inherits
collections:
  - path: "docs/**/*.md"

Commit the recipe and .kapi/: that directory is your project's context (terms, content memory, voice profile, and the record of where each unit stands in review), and it belongs in review like the rest of your source. kapi init writes a two-line ignore rule for the one part that is not: .kapi/work/, where the project store and its caches are derived, plus .kapi/filters.local.json for your personal reader settings. Every kapi command run anywhere in the tree finds the project by walking up, like git. See the project file reference for the full schema. When you're ready for AI-backed steps, kapi models setup detects what you already have (a Claude Code sign-in, Ollama, or an API key) and confirms it as the default (Use with Claude).

Next

• Add languages: target locales, kapi up, review, gates.
• Projects: the concept; ad-hoc vs project, bindings, the store.
• Set up your brand guide in 10 minutes: the source-quality half.