Pause & resume a big run

Goal: a big run that doesn't have to finish in one sitting. A .kpz is a single file holding an entire run in progress — pull sources into it, work as far as you get, set it down, and resume exactly where you left off, later or on another machine. Its configuration (languages, output layout) rides inside the file: no project, no server. The parcel model sits inside the Projects concept; the package format is in the KBF reference.

Desktop

The .kpz workspace lifecycle is a CLI capability today — Kapi Desktop does not drive a parcel directly. Where Desktop meets it: a project you work on visually can be snapshotted from the CLI (kapi pack) for a colleague, and the translated files a merge emits open and preview in Desktop like any others. For pausing and resuming project work visually, the project store already persists between sessions — just reopen the project.

Agent (Claude)

Hand the parcel over like you would to a person:

Here's work.kpz from the vendor — finish the French pass, run the checks, and merge the files out.

The assistant inspects it (kapi info), resumes the work in place, and merges when done. Because progress is derived from the content itself — the overlays present — resuming is idempotent: the assistant can't double-translate what's already done.

CLI

The lifecycle is four verbs over one file:

kapi extract src/**/*.json -o work.kpz \
  --target-lang fr,qps --out 'l10n/{lang}/{name}.{ext}'   # ingest + record config
kapi translate work.kpz --target-lang fr                  # transform in place
kapi pseudo-translate work.kpz --target-lang qps          # …work accumulates
kapi info work.kpz                                        # documents, locales, dirty?
kapi pack work.kpz                                        # eject the cache → the shareable file
kapi merge work.kpz -o l10n/                              # emit the finished files

What's happening underneath:

• Extract records a small recipe (target locales, output layout) so later steps need no flags. By default the .kpz carries identity + a round-trip skeleton, not raw bytes; --with-source embeds the originals for offline re-extraction.
• Transforms run against a working cache keyed to the .kpz — the file itself changes only when you pack (or pass --pack on a transform). info reports dirty when the cache holds unpacked work. Re-running a transform reuses work already done, so AI steps never run twice.
• Merge replays the stored translations onto the source and writes one file per source × locale — it never re-runs a tool or calls a provider. With no -o it uses the recipe's layout.
• Another machine just receives the packed file: the first command rebuilds the cache from the .kpz alone.

One thing to avoid: running a .kpz workspace and a .kapi project over the same content — use the parcel when there is no project.

Try it

Walk the lifecycle as narrated commands, live in your browser:

Loading the walkthrough…

Then do it yourself — work, pack, reopen on a fresh path (a stand-in for another machine), and watch kapi rebuild the workspace from the file alone:

Loading the interactive .kpz workspace lab…

Next

• The Kapi format family & .kpz package — the package format and its working-state members.
• Hand off to translators — the bilingual interchange profile of the same round-trip.