Edit content in any format, faithfully

Goal: edit the text inside a file without touching its structure (a Word document, a JSON catalog, a Markdown guide, or any other format kapi reads). The result is the same file (same keys, same styles, same inline codes) with only the prose changed. You (or your assistant) do the rewriting; kapi parses the format, enforces a faithful round-trip, and writes the result back. kapi never sends content to a model to rewrite it, and no project, provider, or credential is needed.

▶

Walkthrough videoPending recording

A short walkthrough inspecting a file's blocks, previewing an edit as a diff, applying it in place, and verifying the result with a check, showing how only the leaf text changes while the format round-trips.

View scene script ↗

Desktop

The desktop shows the blocks and verifies the result; the write itself is the CLI's or an assistant's apply.

1. Read the blocks. Open the file in your project: Blocks lists each text block as the engine reads it; Preview shows the rendered document with the source ↔ target toggle.
2. Edit translated text in Review. For target-language units the edit surface is the Review queue: edit, then approve; the write lands through the same faithful round-trip.
3. Run source rewrites through apply. Drive the inspect → apply loop from the CLI tab or a connected assistant; then reopen Preview to see that headings, styles, and inline codes survived, and re-run the Checks view to confirm the gate.

Agent (Claude)

With kapi wired as an MCP server or through the Agent Skill, ask:

Simplify the setup section of guide.md: shorter sentences, same meaning, keep every link.

The assistant drives the loop through structured calls: extract_content to read blocks, apply_edits to write the change-set back, check_file to confirm the gate. The assistant is the writer; kapi enforces the round-trip, drift-checks each edit by content_hash, and rejects an edit that would corrupt inline markup. No model is called for the write itself.

CLI

Read the blocks. kapi inspect returns one record per content block: the text, the block's structural role, a stable id, and a content_hash:

kapi inspect guide.md --jsonl        # one JSON object per line

Two fields anchor an edit: text renders inline codes as <x id="…"/> tokens; keep every token in your edited text (a placeholder is <x id="1/"/>, a paired span opens with <x id="1"/> and closes with <x id="/1"/>). content_hash is the block's identity; send it back so kapi can tell the block is still the one you read.

Edit, then apply. Produce one content entry per changed block; kapi apply is the one write verb:

{
  "kind": "content",
  "file": "guide.md",
  "id": "p3",
  "content_hash": "a1b2c3…",
  "text": "See the <x id=\"1/\"/> dashboard."
}

kapi inspect guide.md --jsonl > blocks.jsonl
# rewrite the "text" of the blocks you want changed (keeping every <x id="…"/>
# token) and save them as content entries to edits.jsonl (you do this; no command)
kapi apply edits.jsonl --diff             # preview as a unified diff, write nothing
kapi apply edits.jsonl                    # apply in place
kapi apply edits.jsonl --in-place=.bak    # apply, keeping a .bak

Verify. kapi check confirms the result meets your content rules: deterministic, read-only, exit 0 pass and 3 on gate failure:

kapi check guide.md --max-chars 500 --forbid "utilize"

The two guards

apply writes a block only when both guards pass; a blocked edit leaves that block untouched and is reported, so nothing is silently corrupted:

• Drift guard. A block whose current content_hash no longer matches your entry changed since you inspected it; the edit is marked stale and skipped.
• Inline-code guard. An edited text that drops, invents, duplicates, or unbalances an <x id="…"/> token is rejected rather than written back with broken markup.

Either outcome exits on the gate code (3), distinct from an operational error; re-inspect the affected blocks and retry with fresh hashes. apply is idempotent, and the same change-set can carry asset edits (an approved term, a voice rule; see Create content) or a kind:"review" entry (The kapi loop): one write verb, different kinds.

What "faithfully" means

Only the extracted prose changes; everything outside it (.docx character styles and table borders, JSON keys and non-string values, Markdown headings and fences) is reproduced byte for byte. This is what makes editing binary office formats (.docx, .pptx) safe; kapi formats marks such formats faithful in its Edit column.

In a project

In a kapi project, kapi inspect and kapi check run against the recipe's declared content with no file argument, and kapi apply lands edits against the named files.

Next

• Checks: rule families, profiles, scoring, and the gate exit codes.
• Create content: the author → parse → check loop and the mixed change-set.
• Feed content to your AI: the same anchored blocks as an ingestion stream.