@chalksurf/cli 0.3.4 → 0.3.6

package/docs/agents.md

@@ -71,6 +71,7 @@ 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.
 - 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 +82,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 +94,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`                                                                                 |
+| 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 +104,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 +213,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 +240,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 verify` | `verify_bulk_sheet_updates`         |
 | `sheet set-visibility`     | `set_sheet_visibility`              |
 | `sheet translate`          | `generate_sheet_translation_job`    |
 | `sheet delete`             | `delete_sheet`                      |
@@ -246,7 +256,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` 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` 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.
+
+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.
+
+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`.
 
 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.
 

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,12 +278,25 @@ 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 \
+  --input batch-001.apply.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.
 
+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
+```
+
+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.
+
 Manage folders:
 
 ```bash

package/docs/mcp.md

@@ -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.
+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.
+
+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.
+
+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.
 

package/package.json

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