@chalksurf/cli 0.3.6 → 0.4.0

package/docs/agents.md

@@ -53,25 +53,29 @@ In `--json` mode:
 - known failures still produce JSON on stdout
 - stderr is reserved for unexpected runtime failures
 
-Wait-style failures still include a populated `result` payload, so agents can inspect partial outcomes on exit code `6` or `7`.
-When an import requests translations, `--wait` waits for the import job only. Follow-up translation jobs are listed under each completed import job's `translationJobs`.
+Add `--result-file PATH` to any operational command when the complete terminal envelope should survive outside agent context. Both successful and failed envelopes are published. The destination must be new and its parent must already exist; obvious path failures stop the command before it runs. After publication, stdout contains a compact envelope with the absolute `resultFile` path. If publication loses a race or otherwise fails after execution, stdout falls back to the complete envelope with one warning and the original exit code is preserved.
+
+Wait-style failures still include a populated `result` payload, so agents can inspect partial outcomes on exit codes `6`–`9` or `130`.
+Import waits observe primary jobs and authoritative translation-import children. Automatic generation and metadata aftercare remain separately reported follow-ups in `result.observation`.
 
 ## Shared CLI/MCP Primitive Contract
 
-The CLI and MCP surface are backed by the same agent resource contracts in `packages/shared/src/agent-tools`. Prefer these primitives over UI-only assumptions or direct database access:
+CLI 0.4 content commands use versioned CLI contracts and reuse the existing domain authorization and persistence services. MCP contracts are unchanged. Content results expose `items[]` containing receipts/jobs plus derived `summary` counts; unrelated commands retain their existing receipt formats. Prefer these primitives over direct database access:
 
 - Read tools return complete resource details or focused repair queues.
 - Write tools return a `receipt` with `resource`, `operation`, `changedPaths`, `precondition`, `warnings`, and `details`.
 - Patch-style writes require `expectedUpdatedAt` from a fresh `get` call.
 - Exercise updates require shared-usage care. Use `exercise usage` first when the exercise might appear outside the target sheet.
-- Agent exercise create/update writes are stricter than the human UI: invalid LaTeX is rejected with `agentErrorCode: "invalid_latex"` instead of being saved with a warning. Validate proposed LaTeX with `exercise validate-latex` before applying content updates.
+- Agent exercise create/update writes are stricter than the human UI: invalid LaTeX is rejected with `agentErrorCode: "invalid_latex"` instead of being saved with a warning. Validate proposed LaTeX with `exercise latex validate` before applying content updates.
 - For exercise creates, the server validates all submitted normalized translation fields. For exercise updates, the server validates only translation fields explicitly present in `patch.translations`; omitted invalid fields do not block unrelated partial updates.
 - Successful exercise create/update receipts include `details.latexValidation`. The scope is `all_translation_fields`, `changed_translation_fields`, or `none` when no translation content changed.
 - Failed invalid-LaTeX writes include `error.agentErrorDetails.results[].patchPath`, `validation.issues[].code`, `message`, `snippet`, offsets, and optional `hint` values so agents can repair and retry without guessing.
 - Use figure tools to create and attach figures to exercises. Use `figure capabilities` before drafting, visually review `figure render-draft`, then upload and attach only after the figure looks correct.
-- Use `exercise labels` / `list_exercise_labels` before writing labels. Exercise create and update reject labels outside the canonical taxonomy.
+- Use `exercise label list` / `list_exercise_labels` before writing labels. Exercise create and update reject labels outside the canonical taxonomy.
 - Delete and visibility tools are exposed, but destructive writes require exact resource-ID confirmation and current `expectedUpdatedAt` values where applicable.
-- After any uncertain bulk-sheet apply response, submit the exact update list to CLI `sheet bulk-update verify` or MCP `verify_bulk_sheet_updates`. It reads normalized target state without writing or creating an audit entry; target matches are classified before stale preconditions so a completed apply can be identified safely. Never retry the apply blindly.
+- After an uncertain CLI apply response, use `plan verify PLAN_FILE`; for direct content requests inspect `job list --request-id ID`, including its durable `acceptance` record. Read failure never authorizes replay.
+- Save executable plans with `--dry-run --plan-out FILE`, review every item, then use `plan apply FILE`. Result envelopes cannot be executed. The CLI binds origin and organization; the server rechecks authority and complete reviewed effects.
+
 - No transfer-between-organization agent primitive is intentionally exposed.
 
 Write receipts are the agent audit log. Preserve them in run notes or user-visible summaries when the user needs to double-check what changed.
@@ -84,25 +88,26 @@ Use these commands after authentication and organization selection:
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
 | Save a complete owned-sheet inventory | `chalksurf sheet list --all --result-file inventory.json --json`                                                                        |
 | Fetch one sheet                      | `chalksurf sheet get SHEET_ID --json`                                                                                                   |
-| List owned sheet versions            | `chalksurf sheet versions SHEET_ID --json`                                                                                              |
-| Fetch one owned sheet version        | `chalksurf sheet version SHEET_ID VERSION_ID --json`                                                                                    |
+| List owned sheet versions            | `chalksurf sheet version list SHEET_ID --json`                                                                                              |
+| Fetch one owned sheet version        | `chalksurf sheet version get SHEET_ID VERSION_ID --json`                                                                                    |
 | Get a sheet repair queue             | `chalksurf sheet issues SHEET_ID --json`                                                                                                |
 | Create a sheet                       | `chalksurf sheet create --input-json JSON --json`                                                                                       |
 | Copy a sheet                         | `chalksurf sheet copy SHEET_ID "New name" --exercise-copy-mode keep_references --json`                                                  |
 | Create an editable variant sheet     | `chalksurf sheet copy SHEET_ID "Variant name" --exercise-copy-mode copy_all_exercises --json`                                           |
-| Append existing exercises to a sheet | `chalksurf sheet append SHEET_ID EXERCISE_ID... --json`                                                                                 |
-| Patch sheet metadata                 | `chalksurf sheet update SHEET_ID --expected-updated-at ISO --patch-json JSON --json`                                                    |
+| Append existing exercises to a sheet | `chalksurf sheet exercise append SHEET_ID EXERCISE_ID... --json`                                                                                 |
+| Patch sheet metadata                 | `chalksurf sheet update SHEET_ID --expected-updated-at ISO --input patch.json --json`                                                    |
 | List valid sheet-series paths        | `chalksurf sheet series list --subject math --json`                                                                                     |
-| Validate/apply bulk sheet patches    | `chalksurf sheet bulk-update --input batch.json --json`                                                                                 |
-| Verify an uncertain bulk apply       | `chalksurf sheet bulk-update verify --input batch.json --result-file verify.json --json`                                                |
-| Set sheet visibility                 | `chalksurf sheet set-visibility SHEET_ID --public --expected-updated-at ISO --confirm-make-public-resource-id SHEET_ID --json`          |
+| Validate/apply bulk sheet patches    | `chalksurf sheet update --manifest batch.json --dry-run --plan-out plan.json --json`                                                                                 |
+| Apply a reviewed bulk dry-run        | `chalksurf plan apply plan.json --result-file apply.json --json`                                       |
+| Verify an uncertain bulk apply       | `chalksurf plan verify plan.json --result-file verify.json --json`                                                |
+| Set sheet visibility                 | `chalksurf sheet visibility set SHEET_ID --public --expected-updated-at ISO --confirm-make-public-resource-id SHEET_ID --json`          |
 | Delete a sheet                       | `chalksurf sheet delete SHEET_ID --expected-updated-at ISO --confirm-resource-id SHEET_ID --json`                                       |
 | List folders                         | `chalksurf sheet folder list --json`                                                                                                    |
 | Create a folder                      | `chalksurf sheet folder create "Folder name" --parent-id FOLDER_ID --json`                                                              |
 | Rename a folder                      | `chalksurf sheet folder rename FOLDER_ID "New name" --json`                                                                             |
 | Delete an empty folder               | `chalksurf sheet folder delete FOLDER_ID --confirm-resource-id FOLDER_ID --json`                                                        |
 | Fetch one exercise                   | `chalksurf exercise get EXERCISE_ID --json`                                                                                             |
-| List valid exercise labels           | `chalksurf exercise labels --json`                                                                                                      |
+| List valid exercise labels           | `chalksurf exercise label list --json`                                                                                                      |
 | Inspect exercise usage               | `chalksurf exercise usage EXERCISE_ID --json`                                                                                           |
 | List active quality issues           | `chalksurf quality-issue list --profile PROFILE --organization ORG_ID --json`                                                           |
 | Resolve a repaired quality issue     | `chalksurf quality-issue resolve ISSUE_ID --expected-exercise-updated-at ISO --profile PROFILE --organization ORG_ID --json`           |
@@ -113,10 +118,10 @@ Use these commands after authentication and organization selection:
 | Upload and attach a figure image     | `chalksurf exercise figure upload EXERCISE_ID ./figure.png --figure-type text --json`                                                   |
 | Create an exercise                   | `chalksurf exercise create --input-json JSON --json`                                                                                    |
 | Copy one exercise                    | `chalksurf exercise copy EXERCISE_ID --json`                                                                                            |
-| Patch exercise fields                | `chalksurf exercise update EXERCISE_ID --expected-updated-at ISO --patch-json JSON --json`                                              |
-| Set exercise visibility              | `chalksurf exercise set-visibility EXERCISE_ID --public --expected-updated-at ISO --confirm-make-public-resource-id EXERCISE_ID --json` |
+| Patch exercise fields                | `chalksurf exercise update EXERCISE_ID --expected-updated-at ISO --input patch.json --json`                                              |
+| Set exercise visibility              | `chalksurf exercise visibility set EXERCISE_ID --public --expected-updated-at ISO --confirm-make-public-resource-id EXERCISE_ID --json` |
 | Delete an unused exercise            | `chalksurf exercise delete EXERCISE_ID --expected-updated-at ISO --confirm-resource-id EXERCISE_ID --json`                              |
-| Validate LaTeX snippets              | `chalksurf exercise validate-latex --snippet "path=value" --json`                                                                       |
+| Validate LaTeX snippets              | `chalksurf exercise latex validate --snippet "path=value" --json`                                                                       |
 | Send user-consented feedback         | `chalksurf feedback user --message "..." --user-consent --json`                                                                         |
 | Send agent-observed feedback         | `chalksurf feedback agent --message "..." --json`                                                                                       |
 
@@ -143,7 +148,7 @@ chalksurf --profile prod-codex sheet issues SHEET_ID --json
 3. Validate proposed replacements before writing:
 
 ```bash
-chalksurf --profile prod-codex exercise validate-latex \
+chalksurf --profile prod-codex exercise latex validate \
   --snippet "translations.english.exercise_text=Find $x^2$." \
   --json
 ```
@@ -154,8 +159,9 @@ chalksurf --profile prod-codex exercise validate-latex \
 chalksurf --profile prod-codex exercise update EXERCISE_ID \
   --target-sheet-id SHEET_ID \
   --expected-updated-at 2026-01-01T00:00:00.000Z \
-  --patch-json '{"translations":{"english":{"exercise_text":"Find $x^2$."}}}' \
-  --json
+  --input - --json <<'JSON'
+{"translations":{"english":{"exercise_text":"Find $x^2$."}}}
+JSON
 ```
 
 5. Re-run `sheet issues SHEET_ID --json` until the invalid LaTeX count is zero or the remaining items need human judgment.
@@ -211,7 +217,7 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `org list`                 | `list_organizations`                |
 | `exercise search`          | `search_exercises`                  |
 | `exercise get`             | `get_exercise`                      |
-| `exercise labels`          | `list_exercise_labels`              |
+| `exercise label list`          | `list_exercise_labels`              |
 | `exercise usage`           | `get_exercise_usage`                |
 | `quality-issue list`       | `list_quality_issues`               |
 | `quality-issue resolve`    | `resolve_quality_issue`             |
@@ -222,30 +228,32 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `exercise create`          | `create_exercise`                   |
 | `exercise copy`            | `copy_exercise`                     |
 | `exercise update`          | `update_exercise`                   |
-| `exercise set-visibility`  | `set_exercise_visibility`           |
-| `exercise translate`       | `generate_exercise_translation_job` |
+| `exercise visibility set`  | `set_exercise_visibility`           |
+| `exercise translation generate`       | `generate_exercise_translation_job` |
 | `exercise delete`          | `delete_exercise`                   |
-| `exercise validate-latex`  | `validate_latex_snippets`           |
+| `exercise latex validate`  | `validate_latex_snippets`           |
 | `exercise import`          | `import_exercise`                   |
-| `exercise import-solution` | `import_exercise_solution`          |
+| `exercise solution import` | `import_exercise_solution`          |
 | `sheet list`               | `list_sheets`                       |
 | `sheet search`             | `search_sheets`                     |
 | `sheet get`                | `get_sheet`                         |
-| `sheet versions`           | `list_sheet_versions`               |
-| `sheet version`            | `get_sheet_version`                 |
+| `sheet version list`           | `list_sheet_versions`               |
+| `sheet version get`            | `get_sheet_version`                 |
 | `sheet issues`             | `get_sheet_issues`                  |
 | `sheet create`             | `create_sheet`                      |
 | `sheet copy`               | `copy_sheet`                        |
-| `sheet append`             | `append_exercises_to_sheet`         |
+| `sheet exercise append`             | `append_exercises_to_sheet`         |
 | `sheet update`             | `update_sheet`                      |
 | `sheet series list`        | `list_sheet_series`                 |
-| `sheet bulk-update`        | `bulk_update_sheets`                |
-| `sheet bulk-update verify` | `verify_bulk_sheet_updates`         |
-| `sheet set-visibility`     | `set_sheet_visibility`              |
-| `sheet translate`          | `generate_sheet_translation_job`    |
+| `sheet update --manifest` | `bulk_update_sheets`                |
+| `plan apply` for sheet updates | `bulk_update_sheets`                |
+| `plan verify` for sheet updates | `verify_bulk_sheet_updates`         |
+| `sheet visibility set`     | `set_sheet_visibility`              |
+| `sheet translation generate` | `generate_sheet_translation`      |
 | `sheet delete`             | `delete_sheet`                      |
 | `sheet import`             | `import_sheet`                      |
-| `sheet import-solutions`   | `import_sheet_solutions`            |
+| `sheet solution import`   | `import_sheet_solutions`            |
+| `sheet translation import` | `import_sheet_translation`          |
 | `sheet folder list`        | `list_folders`                      |
 | `sheet folder create`      | `create_folder`                     |
 | `sheet folder rename`      | `rename_folder`                     |
@@ -256,15 +264,13 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `feedback user`            | `send_user_feedback`                |
 | `feedback agent`           | `send_agent_feedback`               |
 
-`sheet bulk-update` and `sheet bulk-update verify` file/stdin handling is a CLI transport convenience. MCP clients pass the same strict objects directly to `bulk_update_sheets` and `verify_bulk_sheet_updates`; the dry-run, confirmation-digest, batch limit, atomic-apply, and recovery contracts are identical.
+CLI `sheet update --manifest FILE --dry-run --plan-out PLAN` and `plan apply/verify PLAN` use the versioned saved-plan contract. MCP callers continue to pass their existing strict objects to `bulk_update_sheets` and `verify_bulk_sheet_updates`; CLI plan files are not MCP inputs. The underlying atomic sheet persistence and authorization rules remain shared.
 
-The verifier accepts the same `updates` array and returns per-sheet `applied`, `pending`, `conflicting`, or `error` results plus aggregate counts. Although it does not mutate data, it requires write authorization, administrator access, and organization-owned sheets because it verifies the intent of the privileged bulk update operation. Make only one bounded apply attempt; after a lost response, verify the original manifest. Stop for `applied`, rerun dry-run before applying `pending`, and inspect `conflicting` or `error` results.
+The MCP verifier retains `applied`, `pending`, `conflicting` and `error` statuses; CLI verification uses `desired`, `original`, `conflicting` and `unreadable`. Matching current values never prove authorship. Series-assignment changes require administrator access; `expectedSeriesAssignments` alone is a non-mutating precondition. Preserve all affected sheet IDs and per-item receipts rather than attributing a batch to its first sheet.
 
-For `bulk_update_sheets`, `receipt.resource` retains the legacy first-sheet value only for CLI/MCP wire compatibility. Treat `receipt.details.sheetIds` and the per-sheet results as the authoritative affected-resource set; the audit log intentionally does not attribute the operation to that arbitrary first sheet.
+CLI `--result-file` is available on every operational command. It exclusively creates a private full JSON envelope for either success or failure and prints a compact stdout result. Existing evidence is never overwritten. If publication fails after a terminal result, the CLI prints the complete response with a warning and preserves the original exit code; preserve stdout and never retry a confirmed mutation only because artifact publication failed. For complete inventories, use `sheet list --all` and require `result.snapshot.complete: true` in the artifact before deriving writes. Collection uses keyset paging and compares a server membership token on every page, so the flag detects same-count membership drift; it is not a transactionally stable snapshot of every sheet field. `--result-file` and automatic `--all` orchestration are CLI conveniences. MCP callers can page explicitly with `afterId`.
 
-CLI `--result-file` is available on `sheet list`, `sheet bulk-update`, and `sheet bulk-update verify`. It exclusively creates a private full JSON envelope and prints a compact stdout summary. Existing evidence is never overwritten. If publication fails after a confirmed apply, the CLI prints the complete confirmed response with a warning and exits successfully; preserve stdout and never retry that apply. For complete inventories, use `sheet list --all` and require `result.snapshot.complete: true` in the artifact before deriving writes. Collection uses keyset paging and compares a server membership token on every page, so the flag detects same-count membership drift; it is not a transactionally stable snapshot of every sheet field. `--result-file` and automatic `--all` orchestration are CLI conveniences. MCP callers can page explicitly with `afterId`.
-
-MCP calls authenticate through ChalkSurf OAuth, not CLI tokens. Tools advertise `chalksurf:read` or `chalksurf:write` during authorization, while the editable MCP grant's current per-organization permission is the authoritative runtime read/write boundary. For normal execution, each organization-scoped MCP call must pass a full `organizationId` from `get_auth_status` or `list_organizations`. If it is unknown, pass `organizationId: null`; no operation runs, and the response returns the complete current organization catalog for retry. `organization_selection_required` means a UUID must be selected, while `organization_access_denied` means the supplied UUID is not currently usable. Grant and membership edits take effect on the next HTTP request without reloading tools or issuing a new access token. Never infer the organization from a resource ID. Organization-independent tools omit the field, though `list_exercise_labels`, `list_sheet_series`, and `validate_latex_snippets` temporarily ignore an optional legacy UUID from cached tool definitions. ChalkSurf serves modern MCP `2026-07-28` and stateless legacy `2025-11-25` on the same endpoint.
+MCP calls authenticate through ChalkSurf OAuth, not CLI tokens. Tools advertise the single `chalksurf:mcp` resource scope during authorization, while the editable MCP grant's current per-organization permission is the authoritative runtime read/write boundary. For normal execution, each organization-scoped MCP call must pass a full `organizationId` from `get_auth_status` or `list_organizations`. If it is unknown, pass `organizationId: null`; no operation runs, and the response returns the complete current organization catalog for retry. `organization_selection_required` means a UUID must be selected, while `organization_access_denied` means the supplied UUID is not currently usable. Grant and membership edits take effect on the next HTTP request without reloading tools or issuing a new access token. Never infer the organization from a resource ID. Organization-independent tools omit the field, though `list_exercise_labels`, `list_sheet_series`, and `validate_latex_snippets` temporarily ignore an optional legacy UUID from cached tool definitions. ChalkSurf serves modern MCP `2026-07-28` and stateless legacy `2025-11-25` on the same endpoint.
 
 ## Feedback
 
@@ -281,8 +287,8 @@ Why:
 - multi-source imports stay explicit
 - each logical source can carry a stable `sourceId`
 - sheet imports can group multiple source files into one resulting sheet
-- sheet imports carry `targetFolderPath`, `title`, and `translateTo` at the sheet level
-- exercise imports can carry top-level `translateTo` for every imported exercise
+- sheet imports carry `targetFolderPath`, `title`, and `targetLanguages` at the sheet level
+- exercise imports can carry item-level `targetLanguages` for every imported exercise
 - sheet solution imports can reconcile one or more solution files against all updatable exercises in one existing sheet
 - agents can correlate import results back to the discovered source set
 
@@ -290,13 +296,14 @@ Use `sourceId` whenever a browsing step or upstream scraper already has a stable
 
 ```json
 {
-  "organizationId": "00000000-0000-4000-8000-000000000001",
-  "wait": true,
-  "sheets": [
+  "schemaVersion": "v1",
+  "operation": "sheet.import",
+  "items": [
     {
+      "itemId": "oktv-2014-round-1",
       "targetFolderPath": "OKTV/2014",
       "title": "OKTV 2014 Round 1",
-      "translateTo": ["english"],
+      "targetLanguages": ["english"],
       "sources": [
         {
           "sourceId": "oktv-2014-round-1-part-a",
@@ -323,6 +330,7 @@ Further reference:
 - [Exercise import schema](../schemas/exercise-import-manifest.schema.json)
 - [Exercise solution import schema](../schemas/exercise-solution-import-manifest.schema.json)
 - [Exercise sheet solution import schema](../schemas/exercise-sheet-solution-import-manifest.schema.json)
+- [Exercise sheet translation import schema](../schemas/exercise-sheet-translation-import-manifest.schema.json)
 
 ## JSON Result Shape
 
@@ -429,7 +437,7 @@ chalksurf --profile prod-codex exercise search \
 Import solutions for an already imported sheet when the solution key is separate:
 
 ```bash
-chalksurf --profile prod-codex sheet import-solutions \
+chalksurf --profile prod-codex sheet solution import \
   00000000-0000-4000-8000-000000000001 \
   ./solutions.pdf \
   --wait \
@@ -448,11 +456,11 @@ Recommended workflow:
 
 1. Codex browses the archive page and collects the relevant links.
 2. Codex filters the links to years `2010` through `2020`.
-3. Codex builds a sheet-import manifest with one `sheets[]` entry per resulting sheet.
+3. Codex builds a sheet-import manifest with one `items[]` entry per resulting sheet.
 4. Codex groups multiple source files inside one `sources[]` array when they belong to the same resulting sheet.
-5. Codex sets `translateTo: ["english"]` on the sheet entries that should produce an English translation.
+5. Codex sets `targetLanguages: ["english"]` on the sheet entries that should produce an English translation.
 6. Codex runs `chalksurf --profile prod-codex sheet import --manifest - --wait --json`.
-7. Codex inspects `result.summary.failed`, `result.summary.timedOut`, and `jobs` to decide whether to retry or report failures.
+7. Codex inspects `result.items`, `result.summary`, `result.observation` and the request ID. A timeout or uncertain response is not permission to reimport. Use request/job recovery before any intentional resend.
 
 Minimal shell shape:
 
@@ -471,8 +479,13 @@ Use the exit code and JSON `error.code` together:
 - `4` / `source_resolution_failed`: local file, directory, or URL preparation failed
 - `5` / `api_error`: the ChalkSurf API rejected the request
 - `6` / `wait_timed_out`: jobs did not finish in time
-- `7` / `job_failed`: one or more jobs finished with failure
+- `7` / `job_failed`: unsuccessful-only work, including blocked previews, cancellation or not-solved results
+- `8` / `mixed_results`: mixed successful/accepted and unsuccessful items
+- `9` / `unknown_write`: acceptance is uncertain; preserve request evidence and inspect before resending
+- `130` / `interrupted`: local dispatch or observation stopped; remote work continues
 
 Reference:
 
 - [Exit codes and JSON errors](./exit-codes.md)
+
+CLI generation, draft translation, saved-plan eligibility, input limits and file-relative path rules are detailed in [content operations](./content-operations.md). The packaged [content manifest schema](../schemas/content-manifest.schema.json) and [plan schema](../schemas/content-plan.schema.json) describe shape; runtime checks also validate digests and authority.

package/docs/content-operations.md

@@ -0,0 +1,36 @@
+# Content operations in CLI 0.4
+
+Content manifests have `schemaVersion: "v1"`, a canonical `operation`, and explicit `items` with unique `itemId` values. Targets, operation settings, and input transports cannot compete. Use `--input FILE` for one structured request, or `--manifest FILE` for repeated requests. Use `-` for stdin. JSON reads stop at 16 MiB. The maximum known expansion is 100 targets; sheet import accepts at most 20 logical groups.
+
+Local paths in a manifest resolve relative to the manifest file. Paths read from stdin resolve relative to the invocation directory. Ordered source groups, components and authoritative language groups retain their order and identity.
+
+Before dispatch, the CLI exclusively publishes a private attempt file under `operations/` beside its resolved configuration file. `--request-file PATH` selects another destination. Existing files and symlinks are never overwritten. A publication failure prevents submission. Attempt files contain request and item identity plus input digests, not source bytes or credentials; source URL credentials, queries and fragments are redacted, with their digest retained. Keep the original input for an intentional resend.
+
+`--request-id UUID` deliberately reuses the identity of an exact prior request. The server returns original accepted work rather than queueing duplicates; changing its input conflicts. The CLI never automatically retries a write. After an uncertain response (exit 9), inspect `job list --request-id UUID` and the attempt evidence before resending. Interrupting local observation or dispatch exits 130 and leaves already accepted remote work running.
+
+Generate with `exercise solution generate ID [ID..]`, `sheet solution generate ID [ID..]`, or `exercise description generate ID [ID..]`. Exercise generation also accepts `--sheet-id ID` as its sole selector. Use `--replace-existing` for existing solution fields and `--allow-shared-exercise-update` to acknowledge shared-use impact. Multiple replacements require a reviewed plan. Description generation replaces descriptions by definition.
+
+Persisted `exercise translation generate` and `sheet translation generate` use repeatable `--target-language`. Sheet translation optionally takes `--source-language`; the result reports the resolved source. `exercise translation generate --draft --input FILE` translates only explicit draft fields without persistence. Adding `--dry-run` validates without provider execution.
+
+For a single update, use `exercise update ID --expected-updated-at TIMESTAMP --input patch.json` or the corresponding sheet command. A repeated update manifest requires preview and plan application. `--patch-json` is removed from these update commands.
+
+Remove a published sheet language with `sheet translation remove ID --target-language LANGUAGE --confirm-resource-id ID`. Preview with `--dry-run`. Shared exercise translations and the last ready sheet language are preserved. Use `job cancel` for pending work; there is no translation-specific cancel command.
+
+## Saved plans
+
+Only exercise/sheet updates, solution generation and description generation support executable plans. Save one with the operation's `--dry-run --plan-out plan.json`; this does not create remote work. A preview containing blocked entries exits nonzero even when eligible independent entries can later be applied. Imports and translations have previews but no executable plans.
+
+```sh
+chalksurf --profile prod-codex sheet update --manifest patches.json --dry-run --plan-out plan.json --json
+chalksurf --profile prod-codex plan show plan.json --json
+chalksurf --profile prod-codex plan apply plan.json --result-file applied.json --json
+chalksurf --profile prod-codex plan verify plan.json --json
+```
+
+`plan show` is entirely local and requires no authentication. `plan apply` accepts no target, policy, patch or request-ID overrides. The selected API environment and organization must match the artifact. Its digest detects edits; it is not proof of human approval. The server authorizes and revalidates the full reviewed scope. Sheet batches retain native atomicity; independent exercise entries retain explicit per-item outcomes.
+
+Use a new private `--request-file` for each apply attempt, or retain the automatically created path. An intentional exact resend uses the saved request ID and returns already accepted results even after later content edits. Never infer permission to replay from a failed lookup.
+
+`plan verify` is read-only: updates report `desired`, `original`, `conflicting` or `unreadable` current state; matching values do not establish authorship. Generation verifies recorded acceptance and jobs, including retained identity when detailed results expire. `--wait` is available only on asynchronous `plan apply` and observes primary jobs. Follow-up state is reported separately.
+
+Saved plans and `--result-file` envelopes are different formats. Old `sheet bulk-update` dry-run envelopes cannot be applied; regenerate from the original patches using the v1 manifest and `--plan-out`. If result publication fails after a response, the complete stdout fallback and original command exit remain authoritative.

package/docs/examples/authoritative-sheet-import-manifest.json

@@ -0,0 +1,48 @@
+{
+  "schemaVersion": "v1",
+  "operation": "sheet.import",
+  "items": [
+    {
+      "itemId": "sheet-1",
+      "targetFolderPath": "School Leaving Examination/2025",
+      "title": "2025 Mathematics in a foreign language",
+      "base": {
+        "language": "hungarian",
+        "sources": [
+          {
+            "sourceId": "mathematics-2025-hungarian-statement",
+            "kind": "url",
+            "url": "https://example.com/mathematics-2025-hungarian-statement.pdf"
+          },
+          {
+            "sourceId": "mathematics-2025-hungarian-marking-guide",
+            "kind": "url",
+            "url": "https://example.com/mathematics-2025-hungarian-marking-guide.pdf"
+          }
+        ]
+      },
+      "translations": [
+        {
+          "language": "english",
+          "sources": [
+            {
+              "sourceId": "mathematics-2025-english-statement",
+              "kind": "url",
+              "url": "https://example.com/mathematics-2025-english-statement.pdf"
+            }
+          ]
+        },
+        {
+          "language": "german",
+          "sources": [
+            {
+              "sourceId": "mathematics-2025-german-statement",
+              "kind": "local",
+              "path": "./mathematics-2025-german-statement.pdf"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/docs/examples/exercise-import-manifest.json

@@ -1,14 +1,21 @@
 {
-  "organizationId": "org_123",
-  "exerciseSheetId": "00000000-0000-4000-8000-000000000111",
-  "translateTo": ["english"],
-  "wait": true,
-  "sources": [
+  "schemaVersion": "v1",
+  "operation": "exercise.import",
+  "items": [
     {
-      "sourceId": "problem-1",
-      "kind": "local",
-      "path": "./imports/problem-1.pdf",
-      "relativePath": "Problem Set/problem-1.pdf"
+      "itemId": "one",
+      "exerciseSheetId": "00000000-0000-4000-8000-000000000111",
+      "targetLanguages": [
+        "english"
+      ],
+      "sources": [
+        {
+          "sourceId": "problem-1",
+          "kind": "local",
+          "path": "./imports/problem-1.pdf",
+          "relativePath": "Problem Set/problem-1.pdf"
+        }
+      ]
     }
   ]
 }

package/docs/examples/exercise-sheet-solution-import-manifest.json

@@ -1,13 +1,18 @@
 {
-  "organizationId": "org_123",
-  "exerciseSheetId": "00000000-0000-4000-8000-000000000333",
-  "wait": true,
-  "sources": [
+  "schemaVersion": "v1",
+  "operation": "sheet.solution.import",
+  "items": [
     {
-      "sourceId": "problem-set-solutions",
-      "kind": "local",
-      "path": "./imports/problem-set-solutions.pdf",
-      "relativePath": "Solutions/problem-set-solutions.pdf"
+      "itemId": "one",
+      "exerciseSheetId": "00000000-0000-4000-8000-000000000333",
+      "sources": [
+        {
+          "sourceId": "problem-set-solutions",
+          "kind": "local",
+          "path": "./imports/problem-set-solutions.pdf",
+          "relativePath": "Solutions/problem-set-solutions.pdf"
+        }
+      ]
     }
   ]
 }

package/docs/examples/exercise-sheet-translation-import-manifest.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": "v1",
+  "operation": "sheet.translation.import",
+  "items": [
+    {
+      "itemId": "one",
+      "exerciseSheetId": "00000000-0000-4000-8000-000000000333",
+      "sourceLanguage": "hungarian",
+      "targetLanguage": "german",
+      "sources": [
+        {
+          "sourceId": "official-german-paper",
+          "kind": "url",
+          "url": "https://www.oktatas.hu/example/official-german-paper.pdf",
+          "relativePath": "official-german-paper.pdf"
+        }
+      ]
+    }
+  ]
+}

package/docs/examples/exercise-solution-import-manifest.json

@@ -1,13 +1,18 @@
 {
-  "organizationId": "org_123",
-  "exerciseId": "00000000-0000-4000-8000-000000000222",
-  "wait": true,
-  "sources": [
+  "schemaVersion": "v1",
+  "operation": "exercise.solution.import",
+  "items": [
     {
-      "sourceId": "problem-1-solution",
-      "kind": "local",
-      "path": "./imports/problem-1-solution.pdf",
-      "relativePath": "Solutions/problem-1.pdf"
+      "itemId": "one",
+      "exerciseId": "00000000-0000-4000-8000-000000000222",
+      "sources": [
+        {
+          "sourceId": "problem-1-solution",
+          "kind": "local",
+          "path": "./imports/problem-1-solution.pdf",
+          "relativePath": "Solutions/problem-1.pdf"
+        }
+      ]
     }
   ]
 }

package/docs/examples/sheet-import-manifest.json

@@ -1,11 +1,14 @@
 {
-  "organizationId": "org_123",
-  "wait": true,
-  "sheets": [
+  "schemaVersion": "v1",
+  "operation": "sheet.import",
+  "items": [
     {
+      "itemId": "sheet-1",
       "targetFolderPath": "OKTV/2014",
       "title": "OKTV 2014 Round 1",
-      "translateTo": ["english"],
+      "targetLanguages": [
+        "english"
+      ],
       "sources": [
         {
           "sourceId": "oktv-2014-round-1-part-a",
@@ -20,6 +23,7 @@
       ]
     },
     {
+      "itemId": "sheet-2",
       "targetFolderPath": null,
       "sources": [
         {
@@ -30,6 +34,7 @@
       ]
     },
     {
+      "itemId": "sheet-3",
       "sources": [
         {
           "sourceId": "combined-archive-file",
@@ -43,7 +48,9 @@
           "description": "The exercise sheet labeled Round 2, Part A.",
           "targetFolderPath": "OKTV/2014",
           "title": "OKTV 2014 Round 2 Part A",
-          "translateTo": ["english"]
+          "targetLanguages": [
+            "english"
+          ]
         },
         {
           "componentId": "round_2_part_b",

package/docs/exit-codes.md

@@ -11,9 +11,12 @@ The CLI uses stable exit codes so automation can branch without parsing human te
 | `2` | `usage_error` | Invalid arguments, invalid manifest, or missing required config such as `--base-url` |
 | `3` | `not_authenticated` | Missing token or rejected CLI token |
 | `4` | `source_resolution_failed` | Local file, directory, URL, or relative path resolution failed |
-| `5` | `api_error` | The ChalkSurf API returned a non-auth failure |
+| `5` | `api_error` | API rejection or observation failure; inspect retained state |
 | `6` | `wait_timed_out` | Waiting ended before all jobs reached a terminal state |
-| `7` | `job_failed` | One or more jobs completed with failure |
+| `7` | `job_failed` | Unsuccessful-only work or blocked preview, including cancellation and not-solved |
+| `8` | `mixed_results` | Mixed successful/accepted and unsuccessful items |
+| `9` | `unknown_write` | Acceptance is uncertain; inspect saved request evidence before resending |
+| `130` | `interrupted` | Local dispatch/observation stopped; accepted remote work continues |
 
 These same codes are mirrored in `error.exitCode` and `error.code` inside the JSON envelope.
 
@@ -54,11 +57,18 @@ Known failures also return JSON on stdout:
 }
 ```
 
-Invalid agent-written exercise LaTeX returns exit code `5` with `error.agentErrorCode = "invalid_latex"`. In JSON mode, inspect `error.agentErrorDetails.results[].patchPath` and `error.agentErrorDetails.results[].validation.issues[]` to repair the submitted fields and retry.
+Agent LaTeX validation rejects invalid submitted fields. Legacy resource commands can expose `error.agentErrorCode = "invalid_latex"` and structured `agentErrorDetails`; content operations also report per-item blocked/failed outcomes and reasons. Inspect the complete result, validate the affected snippets, and prepare a corrected request rather than blindly resending.
 
 ## Contract Notes
 
 - `warnings` contains informational messages that would otherwise be printed for humans.
 - In `--json` mode, stderr is reserved for unexpected runtime failures only.
 - Wait-style commands and imports keep their `result` payload even when `ok` is `false`.
-- Import commands normalize their `result` payloads around `request`, `sources`, `jobs`, and `summary`.
+- Content commands normalize `result` around `operation`, `phase`, `requestId`, `items` and `summary`. Item jobs and receipts retain native details; waited snapshots appear in `observation`. A successful enqueue has `unfinished` items.
+- Every operational command accepts `--result-file PATH`. The artifact contains the complete terminal envelope, including full error details on failure; compact stdout includes the absolute `resultFile` path and essential error fields.
+- Result destinations are preflighted before execution, created with private permissions, and never overwritten. A post-execution publication failure prints the complete envelope with a warning and does not change the command's exit code.
+
+
+A timeout does not mean the remote operation failed. Unknown acceptance (9) stops further dispatch and retains the request/attempt identity. Cancellation is terminal: ordinary generation waits treat it as unsuccessful, while `job cancel --wait` succeeds when the requested jobs cancel. A completed attempt with `not_solved`, stale/conflicting or missing-content output is not successful generation. Metadata aftercare is reported separately from primary success.
+
+`plan verify` reads current deterministic state or recorded async acceptance. It never replays a write. Request-filtered job listing retains known acceptance even if later live-job observation fails. Preserve every available item and job ID on nonzero exits.