Keeping content caught up

Source content changed. Its other languages, its vocabulary, its brand conformance are now behind — and that is normal, not an error. Bowrain treats catching up as the everyday state of a live project: reuse what the workspace already remembers, draft the rest, check everything produced, and park what a machine cannot decide for a person.

A run is one pass of that work. Runs execute on the server, on the organization's AI keys and the workspace's shared memory, vocabulary, and brand checks — so what a run parks lands in the team's review queue rather than a solo worklist. Content that never touches a checkout is treated identically: a connector fetches it server-side, and a run catches it up where it lives.

This page covers what happens on the server. The model itself — the lifecycle ladders, coverage gates, and approver classes — is documented once, on the kapi site, where it is called the kapi loop: The kapi loop.

Three roles, three surfaces

Producing, promoting, and releasing stay separate. Each role has a home:

A server run produces; review in the app promotes what a machine can't decide; the ship gate releases.

• A run produces. A server-side flow over connector content, a push under the server.converge policy, or a developer's kapi up — each drives every unit as far up its lifecycle as a flow can take it unaided.
• Review promotes. What a run parks appears in the project's Review surface, where a person (or several — decisions are shared) advances a unit past what a machine can decide.
• The gate releases. kapi check --ship answers one question — is this scope shippable? — and is the explicit, opt-in enforcement point for a release in a pipeline. Language drift never fails an ordinary build.

The formal name

The model behind this — derived state, lifecycle ladders, coverage gates — is formally called convergence; the server-side runs are convergence as a service (AD-022). The REST API, the run event stream, and --json output use that vocabulary. On the kapi site the same model is named the kapi loop.

Source first: settle before the fan-out

A run settles the source first, holds at a source ship-gate until the source is ready, and only then produces the approved source per language. Source content is shared across every language, so a term left unresolved or a sentence left off-brand is paid for once per language — and paid for again when the source is fixed and everything is regenerated. Settling once, in front of the fan-out, is the seam between the automatic pass and governed review: the source-readiness gate is where a person signs off before the per-language cost is incurred.

A server run settles the source, holds at the source ship-gate until it clears, then translates the approved source per locale — each gate routes work it can't ship to a person rather than shipping it.

• Settle the source. A server run's first pass runs the source stage over the source locale only — source checks, do-not-translate terms marked and protected so translation can never touch them, source QA — and stamps each unit's source status up the authoring ladder (authored → checked → approved).
• Hold at the source ship-gate. The project's source_gate (defaults.source_gate, default checked) is the source-side counterpart of the ship gate. Source that has not cleared its bar holds: the run parks with the reason source_not_ready, opens a source-review task in the team's queue (see Review), and reports how many blocks are blocked on source — it never burns AI translating content you are about to change. A project that genuinely wants raw fan-out sets source_gate: none to opt out.
• Translate only the approved source. Settled source fans out per locale, Memory-first — recycle what the shared memory already has, AI-translate the remainder, check what was produced. Protected terms stay protected through the model.
• Hold at the target ship-gate. A locale that clears its ship_gate is shippable; whatever a machine cannot decide parks for review rather than shipping under-reviewed.

Gating on source readiness before the fan-out is what keeps the per-language cost proportionate to settled source. Editing a source unit re-opens the source gate for only the changed segments, so a fix re-settles and regenerates just those, never the whole corpus. The model itself — the ladders and gate thresholds — is documented once on the kapi site: Source first.

Who starts a run

Three starters, one server-side run — each suits a different way of working:

The same server-side run, started by a connector, a push policy, or a developer's command.

• From a connector, with no checkout. Content connected server-side — a content platform, a design tool — catches up where it lives when a server-side flow or automation rule runs over it, and publishes back to where it came from. A repository connector turns a push webhook into a run and delivers the results as a pull request, with no pipeline in the repository at all.
• From a push policy. With server.converge: on-push on the recipe's server: block, every push triggers a server-side run — the project stays continuously current without anyone running a command. The policy is explicit and per-project, the way git push triggering CI is a repository policy. See Automation.
• From a developer's terminal or CI. kapi up on a connected project prints its resolved venue first (server), pushes the drift, streams the run's progress live into the same terminal view, and pulls the results down. kapi up --local overrides the venue for one run — the work executes on that machine and those keys, and the results are pushed so the server is never left stale. kapi up --server requires the server venue, failing rather than falling back (for CI that must never spend local keys). See the kapi connector and the loop in CI.

Seeing it

Every surface reads the same derived state:

• In the web and desktop app, a project's Runs view lists the server-side runs — Running, Up to date, Parked, with the trigger (Manual, kapi up, On push), the pass count, and a per-language summary such as "3 shippable · 1 parked". A Run now button starts a run from the app, and an in-flight run can be canceled.
• In the terminal, kapi status shows the per-language coverage grid, the server standing, and the effective venue and server.converge policy.
• In the review queue, parked units are the worklist: a run reports them as awaiting a person and still exits zero. Parked work is pending review, not an error.

A run started from the app and a run started from a terminal emit the same event stream, so progress rendered in the Runs view, the CLI, and --json for agents never disagree.

See it run

The developer route end to end — connect a repository, push, and bring it up to date on the server:

Outdated wording

The narration uses terminology that has since been retired. The interface and the behaviour shown are unchanged.

What's next

• Connectors — every route into a workspace
• Quick start — get content in, from your systems or from a codebase
• Review — where parked work gets promoted
• The loop in CI — pipelines and the ship gate
• The full model on the kapi site — ladders, gates, approver classes