@chalksurf/cli 0.3.4 → 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`.
 
@@ -71,6 +73,8 @@ The CLI and MCP surface are backed by the same agent resource contracts in `pack
 - 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.
 - 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.
@@ -81,7 +85,7 @@ Use these commands after authentication and organization selection:
 
 | Goal                                 | CLI command                                                                                                                             |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
-| List organization-owned sheets       | `chalksurf sheet list --limit 100 --json`                                                                                               |
+| 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`                                                                                    |
@@ -93,6 +97,8 @@ 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`                                       |
 | List folders                         | `chalksurf sheet folder list --json`                                                                                                    |
@@ -102,6 +108,10 @@ Use these commands after authentication and organization selection:
 | Fetch one exercise                   | `chalksurf exercise get EXERCISE_ID --json`                                                                                             |
 | List valid exercise labels           | `chalksurf exercise labels --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`           |
+| Dismiss a confirmed false positive   | `chalksurf quality-issue dismiss ISSUE_ID --expected-exercise-updated-at ISO --profile PROFILE --organization ORG_ID --json`           |
+| Validate a quality-review run        | `chalksurf quality-issue artifact validate --run-dir PATH --json`                                                                       |
 | Inspect figure building blocks       | `chalksurf figure capabilities --json`                                                                                                  |
 | Render a draft figure                | `chalksurf figure render-draft --input-json JSON --output figure.png --json`                                                            |
 | Upload and attach a figure image     | `chalksurf exercise figure upload EXERCISE_ID ./figure.png --figure-type text --json`                                                   |
@@ -207,6 +217,9 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `exercise get`             | `get_exercise`                      |
 | `exercise labels`          | `list_exercise_labels`              |
 | `exercise usage`           | `get_exercise_usage`                |
+| `quality-issue list`       | `list_quality_issues`               |
+| `quality-issue resolve`    | `resolve_quality_issue`             |
+| `quality-issue dismiss`    | `dismiss_quality_issue`             |
 | `figure capabilities`      | `figure_get_capabilities`           |
 | `figure render-draft`      | `figure_render_draft`               |
 | `exercise figure upload`   | `upload_exercise_figure`            |
@@ -231,6 +244,8 @@ 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`    |
 | `sheet delete`             | `delete_sheet`                      |
@@ -246,9 +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` file/stdin handling is a CLI transport convenience. MCP clients pass the same strict object directly to `bulk_update_sheets`; the dry-run, confirmation-digest, batch limit, and atomic-apply contract is 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. 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 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

@@ -108,6 +108,25 @@ chalksurf exercise import-solution \
   --wait
 ```
 
+## Quality Issue Review
+
+Quality-issue API commands require both an explicit profile and organization. List findings in bounded pages, preserve `nextCursor`, and use the exercise timestamp returned with the approved evidence:
+
+```bash
+chalksurf quality-issue list --profile prod-codex --organization ORG_ID --limit 100 --json
+chalksurf quality-issue resolve ISSUE_ID --profile prod-codex --organization ORG_ID --expected-exercise-updated-at ISO --json
+chalksurf quality-issue dismiss ISSUE_ID --profile prod-codex --organization ORG_ID --expected-exercise-updated-at ISO --json
+```
+
+For approval-gated batch reviews, validate, digest, verify, and reconcile the local partition artifacts with `quality-issue artifact`. These commands never call the API:
+
+```bash
+chalksurf quality-issue artifact validate --run-dir PATH --json
+chalksurf quality-issue artifact digest --run-dir PATH --json
+chalksurf quality-issue artifact verify --run-dir PATH --approved-digest SHA256 --json
+chalksurf quality-issue artifact reconcile --run-dir PATH --json
+```
+
 Import a separate solution file for an existing exercise sheet:
 
 ```bash
@@ -178,12 +197,14 @@ Search commands default to `--ownership own`, which means resources in the selec
 List every sheet owned by the selected organization, including folder paths and current series assignments:
 
 ```bash
-chalksurf sheet list --limit 100 --json
+chalksurf sheet list --all --result-file sheet-inventory.json --json
 chalksurf sheet list --folder-id FOLDER_ID --include-descendants --json
 ```
 
 `sheet list` is for folder-hierarchy inventory. Use `sheet search` for text, subject, ownership, readiness, series, or edition-year predicates.
 
+`--all` fetches sequential keyset pages of 100 and cannot be combined with `--limit`, `--offset`, or `--after-id`. The server returns a stable membership token for every page, so the saved result detects same-count insert/delete drift as well as count changes, duplicates, and incomplete pages. `snapshot.complete` means sheet membership stayed stable throughout the observed collection; it is not a transactionally stable snapshot of every sheet field. Recollect before making writes when the snapshot is incomplete. For manual keyset paging, pass the previous page's last sheet ID as `--after-id`.
+
 Find exercise sheets by title:
 
 ```bash
@@ -257,11 +278,26 @@ Admin-only sheet-series labeling supports a two-step bulk flow:
 
 ```bash
 chalksurf sheet series list --subject math --json
-chalksurf sheet bulk-update --input batch-001.dry-run.json --json
-chalksurf sheet bulk-update --input batch-001.apply.json --json
+chalksurf sheet bulk-update \
+  --input batch-001.dry-run.json --result-file batch-001.dry-run.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 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.dry-run.json --result-file batch-001.verify.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.
+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.
+
+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.
@@ -81,6 +81,7 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
 | `get_exercise`                      | read       | Fetch full details for one visible exercise.                                                                                        |
 | `list_exercise_labels`              | read       | List the canonical exercise label taxonomy agents may write to exercises.                                                           |
 | `get_exercise_usage`                | read       | Inspect which sheets use one visible exercise.                                                                                      |
+| `list_quality_issues`               | read       | List active findings for organization-owned exercises with bounded selectors and keyset pagination.                                |
 | `figure_get_capabilities`           | read       | Inspect supported semantic 2D figure objects, construction definitions, assertions, limits, and snippets.                           |
 | `figure_render_draft`               | read       | Render a semantic figure draft to SVG/PNG metadata, PNG image content, diagnostics, assertions, and review hints.                   |
 | `upload_exercise_figure`            | write      | Upload and attach one reviewed image from a ChatGPT file parameter, HTTPS image, base64 image, or rendered figure to an exercise.   |
@@ -88,6 +89,8 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
 | `copy_exercise`                     | write      | Copy one visible exercise into the selected organization.                                                                           |
 | `delete_exercise`                   | write      | Soft-delete one unused writable exercise after `updated_at` and exact-ID confirmation checks.                                       |
 | `update_exercise`                   | write      | Patch exercise fields with an `updated_at` precondition and shared-usage acknowledgement.                                           |
+| `resolve_quality_issue`             | write      | Resolve one active finding after checking the exercise evidence timestamp.                                                          |
+| `dismiss_quality_issue`             | write      | Dismiss one active false positive after checking the exercise evidence timestamp.                                                   |
 | `set_exercise_visibility`           | write      | Make one writable exercise public or private when visibility controls are enabled.                                                  |
 | `generate_exercise_translation_job` | write      | Queue translation generation for one writable exercise.                                                                             |
 | `import_exercise`                   | write      | Queue an exercise import from ChatGPT file parameters or HTTPS URLs.                                                                |
@@ -104,6 +107,7 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
 | `delete_sheet`                      | write      | Soft-delete one writable sheet after `updated_at` and exact-ID confirmation checks.                                                 |
 | `update_sheet`                      | write      | Patch sheet metadata with an `updated_at` precondition.                                                                             |
 | `bulk_update_sheets`                | write      | Dry-run or atomically apply up to 100 sheet patches using a confirmation digest.                                                     |
+| `verify_bulk_sheet_updates`         | write      | Read back up to 100 exact sheet-patch targets after an uncertain bulk apply response.                                                |
 | `set_sheet_visibility`              | write      | Make one writable sheet public or private when visibility controls are enabled.                                                     |
 | `append_exercises_to_sheet`         | write      | Append existing visible exercises to the end of one writable sheet.                                                                 |
 | `generate_sheet_translation_job`    | write      | Queue translation generation for one writable exercise sheet.                                                                       |
@@ -122,7 +126,11 @@ 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 `--input` and stdin support are transport conveniences only: MCP clients pass the same strict bulk object directly.
+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. 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.
 
 Delete tools require exact `confirmResourceId` matching the target ID. Exercise and sheet deletes also require the latest `expectedUpdatedAt`. Exercise deletes fail while the exercise is used by an active sheet, and folder deletes fail unless the folder is empty.
 
@@ -159,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.4",
+  "version": "0.3.7",
   "private": false,
   "type": "module",
   "engines": {