@chalksurf/cli 0.3.3 → 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,6 +82,7 @@ Use these commands after authentication and organization selection:
 
 | Goal                                 | CLI command                                                                                                                             |
 | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| 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`                                                                                    |
@@ -90,8 +92,9 @@ Use these commands after authentication and organization selection:
 | 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`                                                    |
-| List valid sheet-series paths        | `chalksurf sheet series list --json`                                                                                                   |
-| Validate/apply bulk sheet patches    | `chalksurf sheet bulk-update --input-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`                                                                                                    |
@@ -101,10 +104,13 @@ 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 a figure image                | `chalksurf exercise figure upload ./figure.png --figure-type text --json`                                                               |
-| Attach figures to an exercise        | `chalksurf exercise figure attach EXERCISE_ID --expected-updated-at ISO --figure-json JSON --json`                                      |
+| 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`                                              |
@@ -118,6 +124,8 @@ Pass `folderId` in the `sheet create --input-json` payload to place a new sheet
 
 When appending private exercises to a public sheet, the CLI requires `--confirm-make-exercises-public` because the append makes those exercises public.
 
+For reviewed bulk sheet updates, prefer `--input batch.json` or pipe the same object through `--input -`. Keep `--input-json` for short inline payloads. Submit the unchanged update list in dry-run and apply modes, copy the returned `confirmationDigest` into the apply object, and preserve both outputs and the apply receipt.
+
 For `--private`, visibility commands do not require `--confirm-make-public-resource-id`. If visibility controls are disabled for the selected organization/user, the CLI and MCP return `feature_disabled`.
 
 For deletes, fetch the resource immediately before deleting, use that `updated_at` as `--expected-updated-at`, and pass the target ID again as `--confirm-resource-id`. Exercise deletes fail while the exercise is used by any active sheet. Folder deletes fail unless the folder has no child folders and no active child sheets.
@@ -171,26 +179,14 @@ chalksurf --profile prod-codex figure render-draft \
   --json
 ```
 
-3. Upload the reviewed image:
+3. Upload and attach the reviewed image to its exercise:
 
 ```bash
-chalksurf --profile prod-codex exercise figure upload figure.png \
+chalksurf --profile prod-codex exercise figure upload EXERCISE_ID figure.png \
   --figure-type text \
   --json
 ```
 
-4. Fetch the exercise, then attach the returned `result.figure` with the latest `updated_at`:
-
-```bash
-chalksurf --profile prod-codex exercise get EXERCISE_ID --json
-chalksurf --profile prod-codex exercise figure attach EXERCISE_ID \
-  --expected-updated-at 2026-01-01T00:00:00.000Z \
-  --figure-json '{"type":"text","url":"https://...","widthInCm":6}' \
-  --json
-```
-
-Use `--mode replace_type --figure-type text` to replace only exercise-text figures, or `--mode replace_all` to replace the full figure list. Attach uses the same shared-exercise acknowledgement rules as `exercise update`.
-
 ## Variant Workflow: Create A Slightly Easier Sheet
 
 Use `copy_all_exercises` when the target is an editable variant. Shared public exercises often cannot be edited by the selected organization, so keeping references usually blocks variant edits.
@@ -217,10 +213,12 @@ 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`            |
-| `exercise figure attach`   | `attach_exercise_figures`           |
 | `exercise create`          | `create_exercise`                   |
 | `exercise copy`            | `copy_exercise`                     |
 | `exercise update`          | `update_exercise`                   |
@@ -230,6 +228,7 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `exercise validate-latex`  | `validate_latex_snippets`           |
 | `exercise import`          | `import_exercise`                   |
 | `exercise import-solution` | `import_exercise_solution`          |
+| `sheet list`               | `list_sheets`                       |
 | `sheet search`             | `search_sheets`                     |
 | `sheet get`                | `get_sheet`                         |
 | `sheet versions`           | `list_sheet_versions`               |
@@ -241,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`                      |
@@ -256,7 +256,15 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `feedback user`            | `send_user_feedback`                |
 | `feedback agent`           | `send_agent_feedback`               |
 
-MCP calls authenticate through ChalkSurf OAuth, not CLI tokens. Read tools require `chalksurf:read`; write tools require `chalksurf:write` plus a write grant for the requested `organizationId`. Each organization-scoped MCP call must pass `organizationId`.
+`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.
 
 ## Feedback
 

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
@@ -175,12 +194,33 @@ Add `--wait` to either translate command to wait for the queued translation job
 
 Search commands default to `--ownership own`, which means resources in the selected organization.
 
+List every sheet owned by the selected organization, including folder paths and current series assignments:
+
+```bash
+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
 chalksurf sheet search --text "OKTV 2014"
 ```
 
+Find sheets from one series and edition-year range:
+
+```bash
+chalksurf sheet search \
+  --series-path hungary.oktv.mathematics \
+  --from-year 1980 \
+  --to-year 1990 \
+  --json
+```
+
 Find exercises by text:
 
 ```bash
@@ -237,12 +277,25 @@ Write commands return a receipt with the affected resource, changed paths, warni
 Admin-only sheet-series labeling supports a two-step bulk flow:
 
 ```bash
-chalksurf sheet series list --json
-chalksurf sheet bulk-update --input-json '{"mode":"dry_run","updates":[...]}' --json
-chalksurf sheet bulk-update --input-json '{"mode":"apply","updates":[...],"confirmationDigest":"..."}' --json
+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
 ```
 
-The exact same update list must be submitted in both calls. A batch contains at most 100 sheets, applies atomically, and cannot update sheets outside the selected organization.
+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:
 

package/docs/mcp.md

@@ -5,11 +5,23 @@ ChalkSurf exposes a remote MCP endpoint for agent workflows that need the same c
 ## Endpoint And Auth
 
 - Endpoint: `/mcp` on the ChalkSurf API host.
+- 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`.
-- Read tools require the `chalksurf:read` scope.
-- Write tools require the `chalksurf:write` scope and a write grant for the requested organization.
-- Organization-scoped tools require an explicit `organizationId` argument.
+- Tools advertise `chalksurf:read` or `chalksurf:write` 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.
+
+Pass the full organization UUID returned by `get_auth_status` or `list_organizations`. If the organization is unknown,
+pass `organizationId: null`; the tool performs no operation and returns `organization_selection_required` with the
+complete current organization catalog. A supplied UUID that is no longer usable returns `organization_access_denied`
+with the same catalog. Retry the same tool with the selected UUID. Grant and membership changes are loaded on the next
+HTTP request, so clients do not need to reload tool definitions. Never infer an organization from a resource ID.
+
+`get_auth_status`, `list_organizations`, `list_exercise_labels`, `list_sheet_series`, `validate_latex_snippets`, and the
+figure capability/rendering tools are organization-independent. The three newly global tools temporarily accept and
+ignore an optional UUID from cached legacy tool definitions.
 
 MCP clients should use their built-in tool listing/search. ChalkSurf does not expose a second search abstraction just to rediscover tools.
 
@@ -63,25 +75,28 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
 
 | Tool                                | Permission | Purpose                                                                                                                             |
 | ----------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `get_auth_status`                   | read       | Confirm the authenticated ChalkSurf user and selected organization.                                                                 |
-| `list_organizations`                | read       | List organizations granted to the MCP client.                                                                                       |
+| `get_auth_status`                   | read       | Confirm the authenticated user and return the complete current organization catalog.                                                |
+| `list_organizations`                | read       | Return the complete current organizations usable through the MCP grant and membership.                                              |
 | `search_exercises`                  | read       | Search exercises by text, labels, status, ownership, age, difficulty, or semantic query.                                            |
 | `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 one reviewed image from a ChatGPT file parameter, HTTPS image, base64 image, or rendered figure into exercise-image storage. |
-| `attach_exercise_figures`           | write      | Append, replace one figure type, or replace all figures on one writable exercise with an `updated_at` precondition.                 |
+| `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.   |
 | `create_exercise`                   | write      | Create one exercise in the selected organization.                                                                                   |
 | `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.                                                                |
 | `import_exercise_solution`          | write      | Queue a solution import for one exercise.                                                                                           |
-| `search_sheets`                     | read       | Search visible sheets, optionally by readiness issues.                                                                              |
+| `search_sheets`                     | read       | Search visible sheets by text, subject, ownership, readiness, series, or edition year.                                               |
+| `list_sheets`                       | read       | List sheets owned by the selected organization, including folder paths and current series assignments.                              |
 | `get_sheet`                         | read       | Fetch full details for one visible sheet.                                                                                           |
 | `list_sheet_series`                 | read       | List the authoritative sheet-series hierarchy and valid assignment paths.                                                           |
 | `list_sheet_versions`               | read       | List version history for one sheet owned by the granted organization.                                                               |
@@ -92,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.                                                                       |
@@ -110,13 +126,17 @@ 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.
+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.
 
 Visibility tools respect the existing ChalkSurf visibility feature flag. If visibility controls are disabled, they return `feature_disabled`. Publicization requires `confirmMakePublicResourceId`; private visibility changes do not.
 
-Figure tools are available for agents to create and attach figures to exercises. The recommended flow is `figure_get_capabilities`, then one or more `figure_render_draft` calls with visual review, then `upload_exercise_figure`, then `attach_exercise_figures` using a fresh `get_exercise.updated_at` value. Figure drafts support semantic 2D constructions such as midpoints, projections, selected intersections, triangle centers, parallel/perpendicular lines, angle bisectors, incircles, diameter circles, and tangent circles; use assertions such as `angleBisected`, `tangent`, `pointOnSegment`, and `concurrent` to verify the intended relationships before upload.
+Figure tools are available for agents to create and attach figures to exercises. The recommended flow is `figure_get_capabilities`, then one or more `figure_render_draft` calls with visual review, then `upload_exercise_figure` with the target `exerciseId`. Upload and attachment are one operation. Figure drafts support semantic 2D constructions such as midpoints, projections, selected intersections, triangle centers, parallel/perpendicular lines, angle bisectors, incircles, diameter circles, and tangent circles; use assertions such as `angleBisected`, `tangent`, `pointOnSegment`, and `concurrent` to verify the intended relationships before upload.
 
 ### File Parameters
 

package/package.json

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