Agent workflow

1. Choose the access mode

booktx status .
booktx profile list .

booktx series prepare BOOK ... --write
# or, for an existing prepared book:
booktx series review BOOK --profile PROFILE --write
booktx source interview-report BOOK --profile PROFILE --write
# Review/edit the generated decision manifest, then:
booktx source interview-apply BOOK --profile PROFILE --file DECISIONS.json --write
booktx series finalize BOOK --profile PROFILE --write

booktx source analyze BOOK --write --sync-profiles
booktx source interview-plan BOOK --profile PROFILE --write
booktx source interview-next BOOK --profile PROFILE --format markdown
booktx source interview-status BOOK --profile PROFILE --fail-if-open

booktx mode .
booktx doctor isolation .
booktx source status .
booktx context status .

2. Read the profile-local context

context.md

Do not start translating when context.json is missing or not ready.

3. Request a task

booktx translate next . --unit batch --max-words 800 --format block

This writes:

• tasks/TASK.agent.md

• tasks/TASK.source.block.txt

• ingest/TASK.block.txt

• ingest/TASK.json

• tasks/TASK.concordance.md

• tasks/TASK.concordance.json

The task JSON also records the dotted baseline version plus the immutable context-view snapshot used for that task.

4. Fill the durable ingest file

Read all three generated task files before writing: tasks/TASK.agent.md, tasks/TASK.source.block.txt, and ingest/TASK.block.txt. Translate only the record bodies in ingest/TASK.block.txt. Keep record ids and placeholders unchanged. Treat # glossary:, # style:, and # termbase: as source-only directives; never copy them into target text.

5. Lint, then submit the result

booktx translate lint-block . \
  --task-id TASK \
  --file ingest/TASK.block.txt \
  --format block

booktx translate insert . \
  --task-id TASK \
  --file ingest/TASK.block.txt \
  --format block

Lint is read-only. If lint fails, repair the same ingest file and rerun lint once. If the same failure class remains, stop and report it.

For historical consistency, use booktx-mediated lookup. Binding context, glossary, termbase, and protected-name rules win over observed usage. Use one batched lookup per batch when possible:

booktx translate search . \
  --source-regex 'Beetle girl|the Wasps|Avaris the Spider|Salmae cavalry' \
  --jsonl

Do not Grep/Search canonical stores, context history, or generated editor indexes in isolated agent mode. The concordance report is advisory evidence, not approval or policy.

6. Validate and build

booktx validate . --fail-on-warnings
booktx build . --require-complete
booktx check . --epub-output --fail-on-warnings

The todo submission workflow performs the active task chapter’s scoped check before continuation. Use booktx validate for the final pre-build check and check --epub-output for the final artifact verification.

6b. Refresh editor QA indexes

After translation/review changes, refresh the three editor-friendly indexes for source-only search, target-only search, and side-by-side review:

booktx translate export-index .

This writes source-index.json, target-index.json, and source-target-index.json into the profile directory. Use rg to search translated terms without English source false positives (rg "Wespen" target-index.json) or source terms without target matches (rg "Wasp" source-index.json). Use nvim source-target-index.json for side-by-side scanning.

The three files are generated artifacts. Do not edit them manually and do not use them as build input. They are optional human/editor exploration artifacts, not the agent consistency protocol; use translate search or translate concordance instead.

6c. Resume an existing bounded todo

Discover open todos without an expected-error probe:

booktx translate todo-list . --state open --json

Select the exact todo_id and pass it to todo-status and todo-resume.

7. Longer bounded runs

When the user asks to continue for multiple chapters, do not request one huge chapter task. Create a todo instead:

booktx translate todo-next . --profile PROFILE_A --chapters 3 \
  --batch-words 800 --write --resume --format block

Read the generated todo markdown and follow its loop. After each completed chapter, fill the booktx context chapter-note template printed by booktx translate insert; do not hand-edit context.md for chapter notes.

If validation flags an old accepted record during a bounded run, use booktx translate revise-record . RECORD_ID --target "..." to fix it. Never edit canonical translation store shards directly. That chapter-note append affects the next task’s context view, but it does not mint a new dotted version by itself. Stop when the todo goal is complete, when todo-status says it is complete, or when a stop condition occurs. Report partial progress if conversation or tool budget runs low. --max-run-words is advisory only.

An incomplete successful insert is not a stop condition. Query the exact todo status, inspect its must_continue and next_safe_command state, and resume the same todo in the same assistant turn. Do not ask the user to say continue unless an explicit stop condition or harness limit has occurred.

Guardrails

• Never mix files between profiles.

• Cross-profile reference work is allowed only from project-root collaborative mode.

• Use booktx context sync for same-book sibling policy propagation instead of copying context files or hand-repeating glossary decisions.

• Never edit .booktx/chunks/*.json directly during normal translation work.

• Never edit translations/<profile>/translation-store/ directly. If validation flags an old accepted record, use booktx translate revise-record to fix it.

• Never edit translations/<profile>/translated/*.json directly; use booktx translate export.

• Use booktx profile compare for cross-profile review instead of mixing store files manually.

• Use project-root mode to create or refresh a judge source snapshot. After booktx judge sync-sources or booktx judge prepare-isolation, a selection profile may run booktx judge status/next/record/insert from its profile root without sibling profile access.

• If a todo-status, todo-resume, or todo-next command fails with an internal booktx error, stop and report the tool failure. Do not silently switch to a large unbounded translate next --unit chapter task. Bounded todos exist to keep agent runs within budget; bypassing them defeats that purpose. Only use translate next --unit chapter for small chapters or when the user explicitly requests a whole-chapter task.

Finish a single large chapter

If the user asks to finish a chapter and that chapter has more than the safe task budget, booktx automatically creates a single-chapter todo and returns bounded batch tasks. Do not create a giant chapter task:

booktx translate next . --chapter 0005 --unit chapter --max-words 800 --format block
# booktx auto-creates a single-chapter todo and returns a bounded batch
booktx translate insert . --task-id TASK --file ingest/TASK.block.txt --format block
booktx check . --chapter 0005 --fail-on-warnings
booktx translate todo-resume . --latest --format block
# repeat until chapter complete

Only use --force-chapter for small chapters or when explicitly requested.

After each chapter, the todo submission scoped gate must pass before adding the chapter note:

booktx context chapter-note . 0005 --title "ONE" ...

Context approval hard stop

Stop and ask the user whenever context questions are open or only recommended. Do not translate from a context that you generated yourself. Prepare a user review form, then wait for explicit approval or edited answers before running booktx context approve and booktx context mark-ready.

EPUB inline XHTML translation rule

For EPUB records, preserve inline XHTML tags and attributes in the target. Translate text nodes only. Do not convert <em> or other inline tags to Markdown markers.

7b. Quality review pass workflow

After validation passes, optional quality review improves the accepted target:

1. booktx review status . – check which records still need review per pass

2. booktx review next . --pass 1 – create a review task for un-reviewed records

3. Edit the prefilled ingest block under translations/<profile>/reviews/

4. booktx review insert . --review-task-id TASK --file reviews/TASK.block.txt

5. Repeat for pass 2: booktx review next . --pass 2, review, insert

6. Validate and build: booktx validate . --fail-on-warnings && booktx build . --require-complete --require-reviewed && booktx check . --epub-output --fail-on-warnings

During review pass tasks, review the existing target critically. Preserve meaning, placeholders, protected terms, and inline XHTML. If the current target is already good, submit it unchanged – booktx stores an explicit review candidate either way.

Judge / selection workflow

When the user wants to assemble a best-of profile from several sibling translations, stay at the project root and use the dedicated judge workflow:

booktx judge create-profile ./book JUDGE_PROFILE \
  --target de \
  --target-locale de-DE \
  --sources PROFILE_A,PROFILE_B \
  --context-from PROFILE_A \
  --model gpt-5.5

booktx judge accept-identical ./book \
  --profile JUDGE_PROFILE \
  --sources PROFILE_A,PROFILE_B \
  --unit chapter \
  --chapter 0001 \
  --max-records 100 \
  --write

booktx judge next ./book \
  --profile JUDGE_PROFILE \
  --sources PROFILE_A,PROFILE_B \
  --unit chapter \
  --chapter 0001 \
  --max-records 8 \
  --format decisions

Judge tasks expose the original source plus each source profile’s effective candidate. Prefer exact candidate copy when one option is already correct. For decision_kind: copy, set selected and reason and leave TARGET empty so booktx copies the selected candidate exactly. Choose decision_kind: edited only when every available candidate needs a repair. Submit the completed judge ingest file with booktx judge insert ...; store and records provenance in translation-selection-ledger.json.

In selection.purpose=compare (the default, shown above), prefer accept-identical and sweep-identical for true multi-source identical candidates.

In selection.purpose=revise, never use deterministic selection commands. Create the profile with --purpose revise and exactly one source; every record requires an explicit copy or edited judge decision. Later corrections must use booktx judge record . --record RECORD_ID, not translation or review revision commands, because revision output is valid only while each active target has matching judge-decision provenance. See Single-source judge revision profiles in docs/profiles.md.

For grammar-only fix runs on an existing translated book, create the revision profile with --revision-focus grammar. In that mode, BASE_TARGET is authoritative for wording and terminology, SOURCE is only a semantic guard, copy is preferred whenever the German is grammatically valid, and edited must be the complete minimally corrected target.

Isolated judge workflow

After the selection profile context is ready, prepare a profile-local snapshot of the source candidate stores:

booktx judge prepare-isolation ./book --profile JUDGE_PROFILE --write

This materializes the source profiles’ canonical store state into a portable snapshot (translation-store.json plus matching ledger/identity/config evidence) under judge-sources/snapshots/<SNAPSHOT_ID>/ and writes judge-specific AGENTS.md instructions. Then start the judge agent inside the profile root:

cd translations/JUDGE_PROFILE

# profile root
booktx judge status .
booktx judge accept-identical . --unit chapter --chapter 0001 --max-records 100 --write
booktx judge next . --unit chapter --chapter 0001 --max-records 8 --format decisions
booktx judge insert . --judge-task-id TASK --file judge-ingest/TASK.decisions.txt --format decisions
booktx judge reset-ingest . --judge-task-id TASK --format decisions --write
booktx judge continue . --max-records 8

The isolated judge workflow uses copied candidate data and never reads sibling profiles. Output is sanitized: no --profile flag, no parent paths, and no translations/<profile> references. Submission paths are confined to regular files inside the current profile. Do not chain judge insert and judge next in one shell command; continue only after a successful insert.

For revision profiles, replace the compare-mode accept-identical step with an explicit decision loop:

## 0001-000001
selected: A
decision_kind: copy
reason: grammatically correct
TARGET:

## 0001-000002
selected: A
decision_kind: edited
reason: grammar: corrected case agreement
TARGET:
Der vollständig korrigierte deutsche Zielsatz.

Do not tell an agent to use accept-identical in revise mode. One managed isolated profile contract is active at a time, so run isolated grammar benchmarks sequentially in one project unless you split them across worktrees or separate project copies.

Grammar judge revision profiles

Selection profiles are judge workflows, never translation workflows. Prepare them before starting the harness:

booktx judge prepare-grammar . --source-profile SOURCE --profile JUDGE --model MODEL --write
cd translations/JUDGE
booktx mode .
booktx doctor isolation .
booktx judge status .

Use booktx judge todo-next . --chapters N --write --resume for bounded chapter work. Use only explicit copy/edited decisions and never run booktx translate mutators in a selection profile. If a profile is contaminated by direct translation writes or lacks judge provenance, create a fresh profile; do not synthesize decisions from the contaminated output.

A judge task is one bounded batch; a judge todo is the immutable user-requested scope. One-command-at-a-time is a safety rule, not a one-batch-per-turn limit. For chapter ranges, prefer explicit --from-chapter and --through-chapter options plus --batch-records, --batch-sentences, --batch-words, and --batch-rendered-lines limits. Compatibility --max-* options remain accepted during migration.

The required agent loop is sequential but unbounded by batch count: run booktx judge todo-status . --latest --json, stop only if the todo is complete or a documented blocker exists, otherwise run booktx judge todo-resume . --latest, read/edit/lint/insert one task, and repeat status in the same turn. A successful insert is not a stop condition. Before reporting progress, use the persisted status counts; never estimate from attempted tasks. If an unavoidable harness limit interrupts the loop, report the exact status and resume command.

First-pass translation quality

When a profile enables [submission_quality], each generated translation task contains a same-call target-language quality gate. The agent drafts each sentence, rereads the target as target-language prose, checks the complete language checklist, rechecks source fidelity, and writes only the final target prose. After drafting a batch it performs one sequential target-only reread for agreement, reference, punctuation, and continuity. Checklist answers and intermediate drafts are never part of the ingest block.

translate lint-block, translate insert, and translate todo-submit share the same configured quality policy. protocol runs structural checks only; basic blocks configured linguistic errors while showing warnings; strict blocks warnings and errors. Direct insertion is therefore safe even when an agent skipped lint. The built-in audit is a conservative regression gate, not proof of grammatically perfect literary German. An explicitly configured local LanguageTool backend can broaden coverage without sending book text to a public service or making a second LLM call.

The grammar judge remains available for diagnostics, old-book repair, and benchmarking, but it is not a routine production stage.