A guided tour
In Kapi Desktop you read the rules your projects keep and decide about what your assistants noticed. The sections below follow the order of the app's surfaces: the context first, the files after. For what the app is and how to install it, see the overview.
The Map and Decide
The app opens on Your context: counts for the projects, the rules in force, the terms, the suggestions advising and what needs you, then What's new, with a row for each project where an assistant noticed something since you last looked. A row carries the assistant's mark and a chip for each kind of thing it noticed. Review on a row opens the project on Decide.
A project otherwise opens on its Map: when kapi last read the files, four counts (files, blocks, rules and findings), What your files do with one row for each suggestion waiting for you, and Files with one row for each content file, the files with the most findings first. Run on everything checks every file and refreshes the counts, and the findings count opens what the checks found. Decide on a suggestion's row, or at the top of the Map, opens Decide.
Open on a file shows it in the Reader: its blocks in file order, each
finding marked on its words with a row under the block, and Fix beside a
finding whose rule names a replacement and has no formatting among its words.
The rules that hold at the file run down the margin, as kapi context <path>
prints them.
In Decide, a list holds one row per suggestion, and the pane beside it asks one
question about the row you select, the same question kapi rules asks. For a
name, the question is "Which one do your files use?", and the options are its
forms, the most used first, each with the blocks and files that write it, and
Other… for a form of your own. For a word or a note, it is "Keep this as a
rule?". Two suggestions that disagree are one question, with a side per option.
Above the actions, a line says what keeping the picked option does, such as
"If you keep "KapiMart": no block uses the other 2 forms. Applies to Website."
Below them, Seen in quotes the sentence and names the file and the
assistant that recorded it. Keep (k), Not a rule (n) and Later
(l) answer, the option numbers pick another option, and the next question is
selected. Sessions, under Assistants, widens a kept rule across the project or the workspace.
Review what your assistant noticed is the same walk, step by step, on the sample.
Ask
Ask asks by file or by word. Give it a file and it shows what applies there. Search a word and it returns the terms that cover it, the prior wording that used it, and where.
Assistants
Assistants has a row for Claude Code, Cursor, VS Code, Codex, Agent skills
and Claude Desktop. A connected assistant reads Connected and what it gets:
the rules, and the check on every edit once Claude Code has the kapi plugin.
Connect on any other row writes the files kapi connect writes for that
assistant. Show what it reads, beside the title, opens two tabs. Rules files shows the
section kapi writes into AGENTS.md and CLAUDE.md, which an assistant reads
as it starts. The brief for a file is the full answer an assistant gets for
the file you choose, the same text kapi context <path> prints. Below the
assistants, Sessions lists what you and the assistants recorded in the
project, one row per session. See Connect an
assistant.
Voice, terms and content memory
Voice shows the voice profile that applies, as it applies: tone, style rules, pattern rules, examples, and the language, channel and persona adjustments. When dated guidance has lapsed, the page says which and why. Editing writes the YAML in your working tree, the same file a reviewer reads in a pull request.
Terms lists the words the project decided on, one concept per row: the term, its status, and how many languages it has terms in. The search at the top of the list narrows it as you type. Select a concept and the pane beside the list shows its definition, the forms it retires with what to write instead, its terms language by language, where it came from, and the concepts it relates to. Relate links it to another concept.
Content Memory lists the approved wording one pair per row: the source
sentence, and the language it was translated into. The filter bar at the top of
the list searches on Enter, and Filters narrows the list by language, target
language, project, the kinds of name an entry holds, the import it came from,
or whether it carries inline codes; each choice shows as a token you can also
type, such as target:fr-FR. Find similar looks up wording like a sentence
you type instead, with the names in it marked, and lists the matches best first
with their scores. Select a pair to read both sides in full, with inline
formatting kept as tags, the file the entry came from and the unit it was
approved for. Pair and All languages above it switch between the pair
and every language the entry holds, beside Edit, Mark entities and
Delete. The box at the start of a row marks its entry, and with entries
marked, Delete and Mark entities act on all of them. Add entry sits
at the top of the page.
Sessions
Sessions opens from a session on the Assistants page, or from All sessions under them. It lists what was recorded in the project, one session per row, newest first: who worked, when, and how many operations the session holds. Select a session to see its operations beside the list. A suggestion still waiting for a decision keeps Keep, Edit and Not a rule on its row, with the sentence it was seen in behind a click. Reset to before this session, above the operations, goes back to how the context stood before the session started. The reset is recorded too, and Take this reset back on it brings back what it set aside.
Share
Share is titled with the project's name, such as Fernwell · Share, and
lists how far your rules reach as three rungs. Each rung says what reaching it
changes for you, and the one the project stands on carries a Current
badge. On this Mac is where every project starts: your rules and your
assistants, read by every clone and worktree on this machine. While it is
current, it shows your workspace folder and Change, which opens the dialog
that names a place. With your team is a git ref, a folder or an S3 bucket
that every machine syncs. Once kapi.yaml names one, the rung reads the rules
in force and the last sync, such as "12 rules · synced 10:03". Under it are
the place, the changes waiting to push and to pull, Sync now and
Change. In a folder you opened without a kapi.yaml, Change writes
the recipe first. See Share context with your
team.
The third rung is Managed on Bowrain: a team queue, who kept what, the
same screens in a browser. Preview opens the project as a Bowrain project
page draws it. When the recipe names a server and this Mac is signed in to it,
Preview reads the server and is labelled As Bowrain shows it; otherwise it
reads this Mac and is labelled As this Mac shows it. When the recipe names
a server this Mac is not signed in to, the sheet also shows Not signed in
to that server with the kapi auth login command. A read the server
refuses shows its message with Sign in and the kapi auth login command,
or Open Bowrain. Preview reads and never writes, so it has no Keep,
Fix or Run on everything. It has two tabs:
- Map: the page the project opens on. A file on it opens in the Reader, and Back returns to the Map.
- Rules: the questions waiting for a person, each with who noticed it, and Kept by: each rule in force, who kept it, the day, and where it holds.
Until the project is connected, the rung also shows About Bowrain, which
opens How Bowrain and kapi fit
together, and the
command that connects it, kapi share --via bowrain <server-url>, which needs
the kapi-bowrain plugin (brew install neokapi/tap/bowrain-cli). A
project whose recipe declares a bowrain: block stands on the third rung,
which then names the server and the workspace, for example
app.bowrain.cloud and acme, and offers Open the project beside
Preview.
Where the project stands
The Project section answers "where is this" on two axes before it offers to do anything.
Content is the blocks the project's files hold, and what is missing. Governance is the voice profile in force, the terms that apply, when the project last converged, and whether it is in sync with the venue it declares.
Beneath, Where content sits gives one row for each part of the project the recipe declares, with the collections there and the voice that applies to them. A project with one voice for everything is one row.
On a project with a target language, Bring up to date runs the project's default flow until every gated locale ships or waits for review. Plan… beside it is the pre-flight: the pending work, the leverage available from content memory, and a token estimate, before anything runs.
Three counts above the button separate the run's work from a person's. Blocks to translate are what the run drafts. Waiting for review opens Review. Languages held back lists each collection language that does not ship yet and what holds it back: a ship gate not yet met, a failing check, or a source that changed after approval. The app reads the project's files when the project opens and again when they change, so no step reads them in by hand.
The interface has changed since this was recorded. The workflow it demonstrates still applies, but some screens and labels differ from the current release. The clip shows an earlier layout of the project home. The app opens on the two-axis standing and where content sits, above the convergence hero.
Collections and formats
A project's content is grouped into named collections: documentation, store copy, contracts, templates. Each is a set of patterns, and the home shows one card per collection with the real files matched beside the format kapi detected.
Opening a file previews it the way the engine reads it. A Preview of the rendered document, a Blocks list, and, where the format carries them, a Structure view of roles and reading order and a Layout view of page-scaled bounding boxes. Media renders as itself: an image with its recognized text boxed, or an audio or video player with the recognized cues as a synced subtitle track. Opening a file whose format needs an engine plugin offers to install it there and then. The format reference lists what kapi reads.
Click a block in the Preview and choose Edit to change it in place: its source, or a translation the project carries for it. Formatting and placeholders stay as chips you type around, and saving writes the file through its format, leaving every other byte as it was.
Checks
Checks are tests for prose. Run on everything on the Map runs them, and the Map's findings count opens the findings, which read like a test report. A finding names the rule that fired and where it applies, and clicking it opens Context there with the rule in view.
From the finding you see the rule that found it, and you change either the wording or the rule. A finding whose rule names the wording to use instead offers Apply fix, which puts that wording in place of the flagged words in the file. When the flagged words have formatting among them, such as a link or bold text, there is no Apply fix, because plain wording in their place would drop the formatting; edit them by hand in the file. When the text changed after the run, the panel shows it as it is now and asks before applying the fix. Collections can be re-run individually as you work.
Flows and the toolbox
The Toolbox holds the flows a project runs over its content: a plain AI translation, a translation followed by quality checks, a pseudo-translation for testing. Each is a named sequence of steps saved beside the project and shared through version control. Open one to edit its pipeline, and run it through the runner with live per-file progress.
The tool browser beside it is a reference. It says what each tool does, what it consumes and produces, and the command line that runs it.
The interface has changed since this was recorded. The workflow it demonstrates still applies, but some screens and labels differ from the current release. The clip shows an earlier Toolbox. In the app, flows run through the runner, and the tool browser is a reference.
Settings, providers, and plugins
Settings has four tabs: General for appearance, AI Models for the providers and models kapi runs with (keys stay in your OS keychain, never in the project file), Plugins for the formats and tools that extend it, and Locales. Project Settings carries the recipe itself: the languages, the voice and terms each part of the project uses, and the default flow.
Plugins install from the registry in one click, and the formats and tools they add appear in the project immediately. The manage plugins recipe walks it step by step.
The interface has changed since this was recorded. The workflow it demonstrates still applies, but some screens and labels differ from the current release. The clip shows an earlier settings layout. In the app, Terms and Content Memory sit under Context, and Project Settings carries the governance bindings.
And in every language
A project that declares target languages gets the multilingual half. Per-language coverage appears on the collections it applies to, and the Review queue takes whatever the loop could not carry to its ship gate. Inspection puts source and target side by side with their findings, to edit, approve, or reject, keyboard-first, with an optional AI pre-review to triage a long queue. See Review & approve.
A project that declares no target languages is complete without this. Its sidebar shows Languages + instead of Review, and the Project page shows no coverage and no Bring up to date. Languages + opens the source language and the languages to translate into. Once the saved recipe declares the first target, the entry reads Languages and opens the Project page at Bring up to date, and Review, Content Memory and the coverage appear.
Next
- Overview: what the app is and how to install it.
- Your first project: the step-by-step path through these surfaces.
- Kapi CLI guides: each task guide notes how it maps to Kapi Desktop.