@chalksurf/cli 0.3.6 → 0.4.0

package/docs/manifest.md

@@ -1,174 +1,21 @@
-# Manifest Reference
+# Content manifests
 
-ChalkSurf uses JSON manifests for batch and agent-driven imports.
+Use `--manifest FILE` for repeated content operations. Files and stdin (`--manifest -`) are limited to 16 MiB. A manifest is a strict object containing `schemaVersion: "v1"`, a canonical dot-separated `operation`, and `items`. Every item has a unique `itemId`; explicit target IDs must also be unique. Do not put profile, organization, wait, timeout, request ID, or artifact settings in the manifest. Competing flags or positional targets are rejected.
 
-One manifest file is passed to exactly one command:
+Local paths resolve relative to the manifest file. Stdin paths resolve relative to the current directory. Sources use `kind: "local"` with `path`, `kind: "directory"` with `path`, or `kind: "url"` with an HTTP(S) `url`. Optional `sourceId` identifies a source within its ordered group; `relativePath` sets a file's logical path, and `relativeRoot` applies to directory sources. File order matters. Duplicate source IDs within a group are rejected.
 
-- `chalksurf sheet import --manifest <path|->`
-- `chalksurf exercise import --manifest <path|->`
-- `chalksurf exercise import-solution --manifest <path|->`
-- `chalksurf sheet import-solutions --manifest <path|->`
+Exercise imports use optional `exerciseSheetId`, `sources`, and optional `targetLanguages`. Exercise solution imports require `exerciseId`; sheet solution imports require `exerciseSheetId`. Authoritative sheet translation imports require `exerciseSheetId`, `sourceLanguage`, `targetLanguage`, and `sources`. Target languages are the existing English enum names, such as `english` and `hungarian`.
 
-Use `--manifest -` to pipe JSON on stdin.
+A `sheet.import` item describes one logical group using exactly one of:
 
-## Common Fields
+- `sources`, optional `targetFolderPath`, `title`, and `targetLanguages`.
+- `sources` and `components`, each with a unique `componentId`, a `description` identifying the section, and optional destination/title/target languages.
+- `base: {language, sources}` and `translations: [{language, sources}]`, with optional destination/title. Authoritative groups require explicit files or URLs, preserve language-local order, and accept no source roles.
 
-Every manifest is a JSON object with these shared metadata fields:
+The CLI accepts at most 20 logical sheet import groups and 100 known work units after component/language expansion. It never truncates inputs or implicitly splits an oversized atomic operation. Directory extraction and AI exercise counts remain unknown in preflight; no remote source is downloaded by `--dry-run`.
 
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `organizationId` | string | no | Overrides the default organization for this invocation. |
-| `wait` | boolean | no | Behaves like `--wait`. The CLI also accepts `--wait`, which wins if set. Requested translations run as follow-up jobs listed in the import result. |
+Examples in [examples](examples/) use this v1 contract. Old top-level `sheets`/`sources`, manifest organization/wait controls, and `translateTo` fields are rejected. Use `targetLanguages` in manifests and repeatable `--target-language` in direct commands.
 
-Every source object supports these common fields. For `sheet import`, sources appear inside `sheets[].sources[]`. For the exercise import commands and `sheet import-solutions`, they appear in top-level `sources[]`.
+Import results have `items` and `summary`; each item retains its identity and accepted jobs. Follow-up details and extracted resources appear in `observation.jobs` when waiting. Request/attempt evidence supports an intentional exact resend. Read [content operations](content-operations.md) before recovering an uncertain acceptance; never blindly reimport successful siblings.
 
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `sourceId` | string | no | Optional stable identifier for correlating source inputs to results. Must be unique within the manifest. |
-| `kind` | `local` \| `directory` \| `url` | yes | Selects the source shape. |
-
-### Source Kinds
-
-`local`
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `path` | string | yes | Local file path relative to `cwd` unless already absolute. |
-| `relativePath` | string | no | Stored path shown to ChalkSurf. Defaults to the basename of `path`. |
-
-`directory`
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `path` | string | yes | Directory to expand recursively. |
-| `relativeRoot` | string | no | Base directory used to compute stored relative paths. Defaults to `path`. |
-
-`url`
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `url` | string | yes | HTTP(S) URL to download before import. |
-| `relativePath` | string | no | Stored path shown to ChalkSurf. Defaults to the filename derived from the URL. |
-
-## Command-Specific Fields
-
-### Sheet Import
-
-Top-level fields:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `sheets` | array | yes | One or more sheets to import. Each sheet may contain one or more source files. |
-
-Normal sheet fields:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `targetFolderPath` | string \| null | yes | Destination folder for the resulting sheet. Use `null` for the root folder. |
-| `sources` | array | yes | One or more source files that belong to this sheet, in import order. |
-| `title` | string | no | Overrides the imported sheet title. |
-| `translateTo` | string[] | no | Target translation languages. Must be unique and non-empty when present. |
-
-Sheet import metadata is sheet-level, not source-level. Do not put `title` or `translateTo` on individual sources inside `sheets[].sources[]`.
-
-Source-level `relativePath` is only a source label or filename override. It does not choose the destination folder for grouped sheet imports; `targetFolderPath` is the only destination field.
-
-Declared-component sheet fields:
-
-Use `components[]` when the same source group contains a known fixed set of component sheets. In this mode, do not put `targetFolderPath`, `title`, or `translateTo` on the sheet itself; put output metadata on each component.
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `sources` | array | yes | One or more source files that contain the declared components. |
-| `components` | array | yes | The explicitly requested component sheets to extract from the shared source group. |
-
-Component fields:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `componentId` | string | yes | Stable key for this requested component. Must match `/^[a-zA-Z0-9_-]{1,80}$/` and be unique within the sheet group. |
-| `description` | string | yes | Matching instructions that identify this component in the source group. |
-| `targetFolderPath` | string \| null | no | Destination folder for this component. Omit or use `null` for the root folder. |
-| `title` | string | no | Overrides the imported component sheet title. |
-| `translateTo` | string[] | no | Target translation languages for this component. Must be unique and non-empty when present. |
-
-The model must return an explicit `import` or `not_present` decision for every declared `componentId`. Jobs complete when at least one component is imported and fail when all declared components are `not_present`.
-
-Canonical example:
-
-- [docs/examples/sheet-import-manifest.json](./examples/sheet-import-manifest.json)
-- [schemas/sheet-import-manifest.schema.json](../schemas/sheet-import-manifest.schema.json)
-
-### Exercise Import
-
-Top-level fields:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `sources` | array | yes | One or more import sources. |
-| `exerciseSheetId` | string | no | Default target sheet for the imported exercises. Can still be overridden by `--sheet-id`. |
-| `translateTo` | string[] | no | Target translation languages for every imported exercise. Must be unique and non-empty when present. |
-
-Per-source fields:
-
-- Only the common source fields are allowed.
-- `title` and source-level `translateTo` are rejected for this command.
-
-Canonical example:
-
-- [docs/examples/exercise-import-manifest.json](./examples/exercise-import-manifest.json)
-- [schemas/exercise-import-manifest.schema.json](../schemas/exercise-import-manifest.schema.json)
-
-### Exercise Solution Import
-
-Top-level fields:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `sources` | array | yes | One or more import sources. |
-| `exerciseId` | string | no | Default target exercise for the imported solution files. The command still requires an exercise id overall, either here or positionally. |
-
-Per-source fields:
-
-- Only the common source fields are allowed.
-- `title` and `translateTo` are rejected for this command.
-
-Canonical example:
-
-- [docs/examples/exercise-solution-import-manifest.json](./examples/exercise-solution-import-manifest.json)
-- [schemas/exercise-solution-import-manifest.schema.json](../schemas/exercise-solution-import-manifest.schema.json)
-
-### Exercise Sheet Solution Import
-
-Top-level fields:
-
-| Field | Type | Required | Notes |
-| --- | --- | --- | --- |
-| `sources` | array | yes | One or more source files containing solutions for some or all exercises in the target sheet. |
-| `exerciseSheetId` | string | no | Default target sheet for the imported solution files. The command still requires a sheet id overall, either here or positionally. |
-
-Per-source fields:
-
-- Only the common source fields are allowed.
-- `title` and `translateTo` are rejected for this command.
-
-Canonical example:
-
-- [docs/examples/exercise-sheet-solution-import-manifest.json](./examples/exercise-sheet-solution-import-manifest.json)
-- [schemas/exercise-sheet-solution-import-manifest.schema.json](../schemas/exercise-sheet-solution-import-manifest.schema.json)
-
-## Validation Notes
-
-The CLI validates more than the JSON schema can express on its own:
-
-- `sourceId` values must be unique within one manifest.
-- Sheet import `translateTo` values must be unique within one sheet.
-- Sheet import component `componentId` values must be unique within one sheet group.
-- Sheet import components require non-empty descriptions.
-- Exercise import top-level `translateTo` values must be unique.
-- `relativePath` cannot be empty or contain `..`.
-- Sheet import `targetFolderPath` must be `null` or a normalized folder path without `.` or `..` segments.
-- `directory` imports must resolve to at least one file.
-- URL imports must use `http` or `https`.
-
-Treat the schema files as a reference format and the CLI as the final validator.
+Import dry runs report SHA-256 fingerprints and byte counts for readable local files in `localSources`. These describe the observed local bytes, not future extraction results. Remote URL bytes remain unknown and are never downloaded by a dry run.

package/docs/manual.md

@@ -36,7 +36,7 @@ Config resolution rules:
 - `--profile` overrides `CHALKSURF_PROFILE`, which overrides the stored default profile.
 - `--base-url` overrides `CHALKSURF_BASE_URL`, which overrides the active profile.
 - `CHALKSURF_TOKEN` overrides the active profile token.
-- `--organization` overrides manifest `organizationId`, which overrides `CHALKSURF_ORGANIZATION_ID`, which overrides the active profile.
+- `--organization` overrides `CHALKSURF_ORGANIZATION_ID`, which overrides the active profile. Content manifests cannot select an organization.
 
 ## Organization Selection
 
@@ -77,7 +77,7 @@ Import one sheet, override its title, and request an English translation after i
 ```bash
 chalksurf sheet import ./fixtures/algebra.pdf \
   --title "OKTV 2014 Round 1" \
-  --translate-to english \
+  --target-language english \
   --wait
 ```
 
@@ -95,14 +95,14 @@ Import exercises into an existing sheet:
 ```bash
 chalksurf exercise import ./fixtures/problem-set.pdf \
   --sheet-id 00000000-0000-4000-8000-000000000001 \
-  --translate-to english \
+  --target-language english \
   --wait
 ```
 
 Import a solution into an existing exercise:
 
 ```bash
-chalksurf exercise import-solution \
+chalksurf exercise solution import \
   00000000-0000-4000-8000-000000000001 \
   ./fixtures/solution.pdf \
   --wait
@@ -130,7 +130,7 @@ chalksurf quality-issue artifact reconcile --run-dir PATH --json
 Import a separate solution file for an existing exercise sheet:
 
 ```bash
-chalksurf sheet import-solutions \
+chalksurf sheet solution import \
   00000000-0000-4000-8000-000000000001 \
   ./fixtures/sheet-solutions.pdf \
   --wait
@@ -151,7 +151,7 @@ Use a manifest for multi-source imports or when each resulting sheet needs expli
 chalksurf sheet import --manifest ./import.json --wait
 ```
 
-Sheet import manifests use top-level `sheets[]`. Each sheet has one destination `targetFolderPath`, optional `title` and `translateTo`, and one or more ordered `sources[]`.
+Content manifests use `schemaVersion: "v1"`, `operation: "sheet.import"` and `items[]` with unique `itemId` values. Normal items have ordered `sources`, optional `targetFolderPath`, `title` and `targetLanguages`. Files resolve relative to the manifest file; stdin paths use the invocation directory. Component and authoritative language groups are described in the [manifest reference](./manifest.md).
 
 ## Working With Jobs
 
@@ -179,17 +179,25 @@ Wait on one or more jobs later:
 chalksurf job wait job_123 job_124
 ```
 
-`--wait` on an import command means the parsed content has been saved before the command exits. Requested translations run as separate jobs; use `--json` to capture their job IDs or `chalksurf job list` to inspect them later.
+A successful `--wait` observes the primary import jobs and authoritative translation-import children. Automatically generated translations and metadata aftercare remain separate follow-ups; inspect `result.observation` and job IDs. A timeout, failed observation or interruption preserves known results and does not cancel remote work.
 
 Queue translations for existing resources:
 
 ```bash
-chalksurf exercise translate 00000000-0000-4000-8000-000000000001 --translate-to english
-chalksurf sheet translate 00000000-0000-4000-8000-000000000002 --translate-to english --source-language hungarian
+chalksurf exercise translation generate 00000000-0000-4000-8000-000000000001 --target-language english
+chalksurf sheet translation generate 00000000-0000-4000-8000-000000000002 --target-language english --source-language hungarian
 ```
 
 Add `--wait` to either translate command to wait for the queued translation job or jobs to finish.
 
+Import an authoritative translation from source documents into an existing sheet:
+
+```bash
+chalksurf sheet translation import 00000000-0000-4000-8000-000000000002 ./official-german-paper.pdf --source-language hungarian --target-language german --wait
+```
+
+This accepts a complete ready source language and a distinct missing or failed target language. It starts a fresh import job; successful sibling translations remain untouched.
+
 ## Searching From The CLI
 
 Search commands default to `--ownership own`, which means resources in the selected organization.
@@ -245,8 +253,8 @@ chalksurf exercise get 00000000-0000-4000-8000-000000000002 --json
 Inspect sheet version history and one stored snapshot:
 
 ```bash
-chalksurf sheet versions 00000000-0000-4000-8000-000000000001 --json
-chalksurf sheet version 00000000-0000-4000-8000-000000000001 00000000-0000-4000-8000-000000000003 --json
+chalksurf sheet version list 00000000-0000-4000-8000-000000000001 --json
+chalksurf sheet version get 00000000-0000-4000-8000-000000000001 00000000-0000-4000-8000-000000000003 --json
 ```
 
 List sheet issues that are useful for repair workflows:
@@ -268,34 +276,28 @@ Patch an exercise with an optimistic update precondition:
 ```bash
 chalksurf exercise update 00000000-0000-4000-8000-000000000002 \
   --expected-updated-at 2026-01-01T00:00:00.000Z \
-  --patch-json '{"translations":{"english":{"exercise_text":"Find $x^2$."}}}' \
-  --json
+  --input - --json <<'JSON'
+{"translations":{"english":{"exercise_text":"Find $x^2$."}}}
+JSON
 ```
 
 Write commands return a receipt with the affected resource, changed paths, warnings, and operation-specific details. Fetch the resource first and use its current `updated_at` value for patch commands.
 
-Admin-only sheet-series labeling supports a two-step bulk flow:
+Repeated sheet patches use a reviewed plan. Series-assignment changes retain their administrator requirement:
 
 ```bash
 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 update --manifest batch-001.json --dry-run --plan-out batch-001.plan.json --json
+chalksurf plan show batch-001.plan.json --json
+chalksurf plan apply batch-001.plan.json --result-file batch-001.apply.json --json
+chalksurf plan verify batch-001.plan.json --result-file batch-001.verify.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.
+A saved plan binds the exact request, environment, organization, targets and effects. Updates to multiple sheets remain atomic; exercise updates retain explicit best-effort outcomes. `--plan-out` requires `--dry-run`. Only updates and solution/description generation support executable plans. A result envelope is not a plan, and old bulk-update envelopes must be regenerated from the original input.
 
-Make one apply attempt. If its response is lost or uncertain, verify the original manifest before retrying:
+Verification reports `desired`, `original`, `conflicting` or `unreadable` current update state; it does not establish authorship. For generation, verification reads recorded acceptance and job outcomes. Never retry a write because a lookup failed. See [content operations](./content-operations.md) for exact resend and recovery.
 
-```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.
+Every operational command accepts `--result-file PATH`, a new private file containing the complete terminal envelope. Stdout then contains the absolute artifact path. Destination preflight failures stop execution; publication failure after a response prints the complete fallback and preserves the command's exit code.
 
 Manage folders:
 
@@ -327,6 +329,20 @@ Use JSON mode when you need exact machine-readable output:
 chalksurf job wait job_123 --json
 ```
 
+Generate solutions and descriptions, or manage jobs directly:
+
+```bash
+chalksurf exercise solution generate EXERCISE_ID --dry-run --json
+chalksurf sheet solution generate SHEET_ID --json
+chalksurf exercise description generate --sheet-id SHEET_ID --dry-run --plan-out descriptions.json --json
+chalksurf plan apply descriptions.json --wait --json
+chalksurf job list --request-id REQUEST_ID --json
+chalksurf job cancel JOB_ID --wait --json
+chalksurf job dismiss JOB_ID --json
+```
+
+Use `--replace-existing` to acknowledge replacing solution fields. Use `--allow-shared-exercise-update` only after reviewing shared usage. Draft translation uses `exercise translation generate --draft --input FILE` and never persists content. Published language removal uses `sheet translation remove SHEET_ID --target-language LANGUAGE --confirm-resource-id SHEET_ID`; pending work is cancelled with `job cancel`.
+
 Further reference:
 
 - [Agent and Codex guide](./agents.md)

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.
@@ -29,9 +29,11 @@ MCP clients should use their built-in tool listing/search. ChalkSurf does not ex
 
 The MCP tools and CLI commands are backed by the same agent resource contracts in `packages/shared/src/agent-tools`.
 
-Read tools return structured resource data. Write tools return a structured `receipt`:
+The core MCP exercise, sheet, and folder search/list/get tools return their primary structured result plus a top-level `resources` array of absolute links. `get_exercise_usage` links the sheets in its usage result. Nested matching sources, embedded exercises, versions, issues, and metadata are not linked. Empty primary results return `resources: []` without an extra link block. These sidecars are MCP-only; equivalent CLI and direct API read payloads are unchanged.
 
-- `resource`: the resource type and ID affected by the write
+Write tools return a structured `receipt`:
+
+- `resource`: the resource type and ID affected by the write, plus an absolute `url` for a surviving navigable exercise, sheet, or folder
 - `operation`: the stable operation name, such as `update_exercise`
 - `changedPaths`: field paths changed by the operation
 - `precondition`: optimistic update status, including `expectedUpdatedAt` and `actualUpdatedAt`
@@ -40,6 +42,8 @@ Read tools return structured resource data. Write tools return a structured `rec
 
 Treat write receipts as an agent audit log. They are suitable for user-visible summaries after an agent edits a sheet.
 
+The same absolute links are repeated in ordinary MCP text so clients can include them in conversation. Completed jobs returned by `list_jobs`, `get_job`, and `wait_for_jobs` contain a plural `resources` array for their resulting exercises or sheets; non-completed or malformed job results use an empty array. Browser links include `organizationId` as a navigation hint. ChalkSurf waits for the signed-in user and memberships before applying it, ignores and clears inaccessible hints, and preserves it through login when the browser is anonymous. The query parameter does not grant access; resource endpoints remain authoritative. Delete receipts and the legacy singular `bulk_update_sheets` receipt resource deliberately have no URL.
+
 Exercise content writes are stricter for agents than for the human UI. `create_exercise` validates all submitted normalized exercise translation fields before writing. `update_exercise` validates only translation fields explicitly present in `patch.translations`; omitted invalid fields do not block unrelated partial updates.
 
 Successful exercise create/update receipts include `details.latexValidation` with one of these scopes:
@@ -73,62 +77,63 @@ Use `error.agentErrorDetails.results[].patchPath` and `validation.issues[]` to r
 
 ## Tool Surface
 
-| Tool                                | Permission | Purpose                                                                                                                             |
-| ----------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `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 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 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.                                                               |
-| `get_sheet_version`                 | read       | Fetch one owned sheet version snapshot with referenced exercise details.                                                            |
-| `get_sheet_issues`                  | read       | Fetch actionable sheet issues: invalid LaTeX, missing translations, missing solutions, and missing scores.                          |
-| `create_sheet`                      | write      | Create one exercise sheet in the selected organization.                                                                             |
-| `copy_sheet`                        | write      | Copy a visible sheet, either keeping exercise references or copying all visible exercises.                                          |
-| `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.                                                                       |
-| `list_folders`                      | read       | List sheet folders in the selected organization.                                                                                    |
-| `create_folder`                     | write      | Create a sheet folder.                                                                                                              |
-| `rename_folder`                     | write      | Rename a sheet folder.                                                                                                              |
-| `delete_folder`                     | write      | Delete one empty sheet folder after exact-ID confirmation.                                                                          |
-| `validate_latex_snippets`           | read       | Validate proposed LaTeX snippets before writing.                                                                                    |
-| `import_sheet`                      | write      | Queue sheet imports from ChatGPT file parameters or HTTPS URLs.                                                                     |
-| `import_sheet_solutions`            | write      | Queue solution import for an existing sheet.                                                                                        |
-| `list_jobs`                         | read       | List jobs in the granted organization.                                                                                              |
-| `get_job`                           | read       | Fetch one job.                                                                                                                      |
-| `wait_for_jobs`                     | read       | Wait for one or more jobs to complete.                                                                                              |
-| `send_user_feedback`                | read       | Send user-consented product feedback, bug reports, or blocked-request reports.                                                      |
-| `send_agent_feedback`               | read       | Send agent-observed API, MCP, CLI, or documentation feedback.                                                                       |
+| Tool                                | Permission | Purpose                                                                                                                           |
+| ----------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `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 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 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.                                                             |
+| `get_sheet_version`                 | read       | Fetch one owned sheet version snapshot with referenced exercise details.                                                          |
+| `get_sheet_issues`                  | read       | Fetch actionable sheet issues: invalid LaTeX, missing translations, missing solutions, and missing scores.                        |
+| `create_sheet`                      | write      | Create one exercise sheet in the selected organization.                                                                           |
+| `copy_sheet`                        | write      | Copy a visible sheet, either keeping exercise references or copying all visible exercises.                                        |
+| `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`        | write      | Queue translation generation for one writable exercise sheet.                                                                     |
+| `list_folders`                      | read       | List sheet folders in the selected organization.                                                                                  |
+| `create_folder`                     | write      | Create a sheet folder.                                                                                                            |
+| `rename_folder`                     | write      | Rename a sheet folder.                                                                                                            |
+| `delete_folder`                     | write      | Delete one empty sheet folder after exact-ID confirmation.                                                                        |
+| `validate_latex_snippets`           | read       | Validate proposed LaTeX snippets before writing.                                                                                  |
+| `import_sheet`                      | write      | Queue sheet imports from ChatGPT file parameters or HTTPS URLs.                                                                   |
+| `import_sheet_solutions`            | write      | Queue solution import for an existing sheet.                                                                                      |
+| `import_sheet_translation`          | write      | Import one authoritative translation into an existing sheet.                                                                      |
+| `list_jobs`                         | read       | List jobs in the granted organization.                                                                                            |
+| `get_job`                           | read       | Fetch one job.                                                                                                                    |
+| `wait_for_jobs`                     | read       | Wait for one or more jobs to complete.                                                                                            |
+| `send_user_feedback`                | read       | Send user-consented product feedback, bug reports, or blocked-request reports.                                                    |
+| `send_agent_feedback`               | read       | Send agent-observed API, MCP, CLI, or documentation feedback.                                                                     |
 
 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.
 
@@ -140,7 +145,7 @@ Figure tools are available for agents to create and attach figures to exercises.
 
 ### File Parameters
 
-ChatGPT file uploads are advertised with `_meta["openai/fileParams"]`. For `import_exercise`, `import_exercise_solution`, `import_sheet`, and `import_sheet_solutions`, ChatGPT should pass uploaded files in top-level `file_id_N` arguments. The field names are model-facing: ChatGPT receives file IDs for those fields, then the harness passes ChalkSurf resolved file objects:
+ChatGPT file uploads are advertised with `_meta["openai/fileParams"]`. For `import_exercise`, `import_exercise_solution`, `import_sheet`, `import_sheet_solutions`, and `import_sheet_translation`, ChatGPT should pass uploaded files in top-level `file_id_N` arguments. The field names are model-facing: ChatGPT receives file IDs for those fields, then the harness passes ChalkSurf resolved file objects:
 
 ```json
 {
@@ -167,7 +172,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