@chalksurf/cli 0.3.6 → 0.3.7

package/docs/agents.md

@@ -53,6 +53,8 @@ In `--json` mode:
 - known failures still produce JSON on stdout
 - stderr is reserved for unexpected runtime failures
 
+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 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`.
 
@@ -72,6 +74,7 @@ The CLI and MCP surface are backed by the same agent resource contracts in `pack
 - Use `exercise labels` / `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.
+- For CLI bulk-sheet work, save the dry-run with `--result-file`, review the complete artifact, then pass it unchanged to `sheet bulk-update apply --dry-run-result FILE`. The CLI rejects failed, incomplete, foreign-environment, or foreign-organization artifacts before making a mutation request.
 - 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.
@@ -94,6 +97,7 @@ Use these commands after authentication and organization selection:
 | Patch sheet metadata                 | `chalksurf sheet update SHEET_ID --expected-updated-at ISO --patch-json 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`                                                                                 |
+| Apply a reviewed bulk dry-run        | `chalksurf sheet bulk-update apply --dry-run-result dry-run.json --result-file apply.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`          |
 | Delete a sheet                       | `chalksurf sheet delete SHEET_ID --expected-updated-at ISO --confirm-resource-id SHEET_ID --json`                                       |
@@ -240,6 +244,7 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `sheet update`             | `update_sheet`                      |
 | `sheet series list`        | `list_sheet_series`                 |
 | `sheet bulk-update`        | `bulk_update_sheets`                |
+| `sheet bulk-update apply`  | `bulk_update_sheets`                |
 | `sheet bulk-update verify` | `verify_bulk_sheet_updates`         |
 | `sheet set-visibility`     | `set_sheet_visibility`              |
 | `sheet translate`          | `generate_sheet_translation_job`    |
@@ -256,15 +261,15 @@ 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.
+`sheet bulk-update`, `sheet bulk-update apply`, and `sheet bulk-update verify` file handling is a CLI transport convenience. The direct-apply subcommand validates a complete CLI dry-run result artifact and forwards its exact updates and digest to the existing bulk update operation. 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.
 
-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 verifier accepts the same `updates` array and returns per-sheet `applied`, `pending`, `conflicting`, or `error` results plus aggregate counts. Bulk update and verification requests require write authorization and organization-owned sheets. Administrator access is required when any update contains `patch.seriesAssignments`; `expectedSeriesAssignments` alone is a non-mutating precondition and does not require administrator access. 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.
 
 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 `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`.
+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`.
 
-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
 

package/docs/exit-codes.md

@@ -62,3 +62,5 @@ Invalid agent-written exercise LaTeX returns exit code `5` with `error.agentErro
 - 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`.
+- 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.

package/docs/manual.md

@@ -280,22 +280,24 @@ Admin-only sheet-series labeling supports a two-step bulk flow:
 chalksurf sheet series list --subject math --json
 chalksurf sheet bulk-update \
   --input batch-001.dry-run.json --result-file batch-001.dry-run.result.json --json
-chalksurf sheet bulk-update \
-  --input batch-001.apply.json --result-file batch-001.apply.result.json --json
+chalksurf sheet bulk-update apply \
+  --dry-run-result batch-001.dry-run.result.json --result-file batch-001.apply.result.json --json
 ```
 
-Use `--input -` to read the object from stdin, or `--input-json` for short inline JSON. Exactly one input option is required. The exact same update list must be submitted in both calls; only change `mode` and add the returned `confirmationDigest`. A batch contains at most 100 sheets, applies atomically, and cannot update sheets outside the selected organization.
+Use `--input -` to read the dry-run object from stdin, or `--input-json` for short inline JSON. Exactly one input option is required. The explicit `apply` subcommand accepts only the complete result artifact saved by the dry-run. It validates the artifact, API environment, and organization selection, then submits its exact update list and confirmation digest. A batch contains at most 100 sheets, applies atomically, and cannot update sheets outside the selected organization. The original manifest-based apply mode remains available for scripts that construct a typed apply object directly.
 
 Make one apply attempt. If its response is lost or uncertain, verify the original manifest before retrying:
 
 ```bash
 chalksurf sheet bulk-update verify \
-  --input batch-001.apply.json --result-file batch-001.verify.result.json --json
+  --input batch-001.dry-run.json --result-file batch-001.verify.result.json --json
 ```
 
 An `applied` result means the intended target is already present. `pending` means the original preconditions still match but the target is absent; rerun dry-run before a later apply. Inspect `conflicting` and `error` results. Never retry an uncertain apply blindly.
 
-For `sheet list`, `sheet bulk-update`, and `sheet bulk-update verify`, `--result-file` stores the complete JSON envelope while stdout reports only a compact summary. Result files are created privately and exclusively: an existing destination is never overwritten, so use a new path for every attempt. If artifact publication fails after the server confirms an apply, the CLI returns the complete confirmed response on stdout with a warning and a successful exit code. Preserve that response and do not retry the apply.
+Every operational CLI command accepts `--result-file PATH`. It stores the complete success or failure JSON envelope while stdout reports a compact result containing the absolute artifact path; the three sheet commands above retain their richer compact summaries. Result files are created privately and exclusively. The CLI rejects an existing destination, a missing parent directory, or another obvious path problem before running the command, so use a new path for every attempt.
+
+If publication still fails after the command reaches a terminal result, the CLI prints the complete envelope on stdout with a warning and preserves the command's original exit code. Preserve that response. In particular, never retry a confirmed mutation only because its artifact could not be published.
 
 Manage folders:
 

package/docs/mcp.md

@@ -8,7 +8,7 @@ ChalkSurf exposes a remote MCP endpoint for agent workflows that need the same c
 - Protocols: modern `2026-07-28` and stateless legacy `2025-11-25` are both supported on the same endpoint.
 - Authentication: OAuth access tokens issued through the ChalkSurf MCP authorization flow.
 - CLI tokens and browser session tokens are rejected on `/mcp`.
-- Tools advertise `chalksurf:read` or `chalksurf:write` during OAuth authorization. The editable MCP grant's current
+- Tools advertise the single `chalksurf:mcp` resource scope during OAuth authorization. The editable MCP grant's current
   per-organization permission is the authoritative runtime read/write boundary, so changing the grant does not require
   issuing a new access token.
 - Organization-scoped tools require an explicit `organizationId` argument for normal execution.
@@ -126,9 +126,9 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
 
 For `create_sheet`, pass `folderId` to create the sheet in a target folder. Omit it or pass `null` to create the sheet at the organization root.
 
-Sheet-series writes are currently restricted to admin users and sheets owned by the selected organization. Use `list_sheet_series`, then call `bulk_update_sheets` with `mode: "dry_run"`. Apply the unchanged batch with the returned `confirmationDigest`; no idempotency key or separate idempotency table is used. CLI `sheet bulk-update` and `sheet bulk-update verify` provide the same operation and recovery contracts. CLI file/stdin input, `--result-file`, and `sheet list --all` are local orchestration conveniences rather than MCP parameters. MCP inventory callers can use `list_sheets.afterId` with the previous page's last sheet ID for keyset pagination.
+Bulk sheet updates require write access and sheets owned by the selected organization. Requests containing any `patch.seriesAssignments` field are additionally restricted to admin users; `expectedSeriesAssignments` alone remains available as a non-mutating precondition for ordinary bulk updates. For series writes, use `list_sheet_series`, then call `bulk_update_sheets` with `mode: "dry_run"`. Apply the unchanged batch with the returned `confirmationDigest`; no idempotency key or separate idempotency table is used. CLI `sheet bulk-update`, `sheet bulk-update apply --dry-run-result FILE`, and `sheet bulk-update verify` provide the same operation and recovery contracts. Applying a complete dry-run result artifact, CLI file/stdin input, the global `--result-file` artifact publisher, and `sheet list --all` are local orchestration conveniences rather than MCP parameters. MCP inventory callers can use `list_sheets.afterId` with the previous page's last sheet ID for keyset pagination.
 
-If the apply response is lost or uncertain, pass the exact same `updates` array to `verify_bulk_sheet_updates`. It compares the normalized target fields before checking the original preconditions, so a completed apply is reported as `applied` even though its write changed `updated_at`. A result is `pending` when target fields still differ and the preconditions still match, `conflicting` when target fields differ and a precondition changed, and `error` when the target cannot be read or validated. The verifier performs no writes and creates no agent audit entry, but it requires the same administrator access, organization write grant, and `chalksurf:write` OAuth scope as the bulk apply because it evaluates privileged write intent.
+If the apply response is lost or uncertain, pass the exact same `updates` array to `verify_bulk_sheet_updates`. It compares the normalized target fields before checking the original preconditions, so a completed apply is reported as `applied` even though its write changed `updated_at`. A result is `pending` when target fields still differ and the preconditions still match, `conflicting` when target fields differ and a precondition changed, and `error` when the target cannot be read or validated. The verifier performs no writes and creates no agent audit entry. It requires an organization write grant and the `chalksurf:mcp` OAuth scope, plus administrator access when any verified update contains `patch.seriesAssignments`.
 
 The bulk receipt's singular `resource` remains populated for backward compatibility. It is not a complete attribution: use `details.sheetIds` and the per-sheet results for the authoritative affected set. ChalkSurf omits that compatibility value from durable bulk audit primary-resource attribution and displays the validated resource count instead.
 
@@ -167,7 +167,7 @@ Generic MCP clients should pass absolute HTTPS URLs in `sourceUrls` for import t
 
 No MCP tool currently transfers resources between organizations.
 
-`send_user_feedback` and `send_agent_feedback` are not read-only operations, but they require only the `chalksurf:read` OAuth scope because they do not mutate ChalkSurf exercises, sheets, or folders. Use `send_user_feedback` only after the user explicitly agrees to send feedback. Use `send_agent_feedback` when the agent itself observes inconsistent behavior, inaccurate docs, or missing agent-facing API coverage.
+`send_user_feedback` and `send_agent_feedback` are not read-only operations, but their application permission remains `read` because they do not mutate ChalkSurf exercises, sheets, or folders. Like every MCP tool, they require the `chalksurf:mcp` OAuth resource scope. Use `send_user_feedback` only after the user explicitly agrees to send feedback. Use `send_agent_feedback` when the agent itself observes inconsistent behavior, inaccurate docs, or missing agent-facing API coverage.
 
 ## Common Workflows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "private": false,
   "type": "module",
   "engines": {