@chalksurf/cli 0.2.4 → 0.3.0

package/docs/agents.md

@@ -65,7 +65,9 @@ The CLI and MCP surface are backed by the same agent resource contracts in `pack
 - Patch-style writes require `expectedUpdatedAt` from a fresh `get` call.
 - Exercise updates require shared-usage care. Use `exercise usage` first when the exercise might appear outside the target sheet.
 - Validate proposed LaTeX with `exercise validate-latex` before applying content updates.
-- No delete or transfer-between-organization agent primitive is intentionally exposed.
+- 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.
+- 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.
 
@@ -76,22 +78,38 @@ Use these commands after authentication and organization selection:
 | Goal | CLI command |
 | --- | --- |
 | 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` |
 | Get a sheet repair queue | `chalksurf sheet issues SHEET_ID --json` |
+| Create a sheet | `chalksurf sheet create --input-json JSON --json` |
 | Copy a sheet | `chalksurf sheet copy SHEET_ID "New name" --exercise-copy-mode keep_references --json` |
 | 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` |
+| 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` |
 | Create a folder | `chalksurf sheet folder create "Folder name" --parent-id FOLDER_ID --json` |
 | Rename a folder | `chalksurf sheet folder rename FOLDER_ID "New name" --json` |
+| Delete an empty folder | `chalksurf sheet folder delete FOLDER_ID --confirm-resource-id FOLDER_ID --json` |
 | 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` |
+| 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` |
+| Set exercise visibility | `chalksurf exercise set-visibility EXERCISE_ID --public --expected-updated-at ISO --confirm-make-public-resource-id EXERCISE_ID --json` |
+| Delete an unused exercise | `chalksurf exercise delete EXERCISE_ID --expected-updated-at ISO --confirm-resource-id EXERCISE_ID --json` |
 | Validate LaTeX snippets | `chalksurf exercise validate-latex --snippet "path=value" --json` |
+| Send user-consented feedback | `chalksurf feedback user --message "..." --user-consent --json` |
+| Send agent-observed feedback | `chalksurf feedback agent --message "..." --json` |
 
 When appending private exercises to a public sheet, the CLI requires `--confirm-make-exercises-public` because the append makes those exercises public.
 
+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.
+
 ## Repair Workflow: Fix LaTeX Errors In A Sheet
 
 1. Fetch the sheet and issue queue:
@@ -148,29 +166,47 @@ MCP clients should use tool discovery from the client. The ChalkSurf MCP endpoin
 | `org list` | `list_organizations` |
 | `exercise search` | `search_exercises` |
 | `exercise get` | `get_exercise` |
+| `exercise labels` | `list_exercise_labels` |
 | `exercise usage` | `get_exercise_usage` |
+| `exercise create` | `create_exercise` |
 | `exercise copy` | `copy_exercise` |
 | `exercise update` | `update_exercise` |
+| `exercise set-visibility` | `set_exercise_visibility` |
+| `exercise delete` | `delete_exercise` |
 | `exercise validate-latex` | `validate_latex_snippets` |
 | `exercise import` | `import_exercise` |
 | `exercise import-solution` | `import_exercise_solution` |
 | `sheet search` | `search_sheets` |
 | `sheet get` | `get_sheet` |
+| `sheet versions` | `list_sheet_versions` |
+| `sheet version` | `get_sheet_version` |
 | `sheet issues` | `get_sheet_issues` |
+| `sheet create` | `create_sheet` |
 | `sheet copy` | `copy_sheet` |
 | `sheet append` | `append_exercises_to_sheet` |
 | `sheet update` | `update_sheet` |
+| `sheet set-visibility` | `set_sheet_visibility` |
+| `sheet delete` | `delete_sheet` |
 | `sheet import` | `import_sheet` |
 | `sheet import-solutions` | `import_sheet_solutions` |
 | `sheet folder list` | `list_folders` |
 | `sheet folder create` | `create_folder` |
 | `sheet folder rename` | `rename_folder` |
+| `sheet folder delete` | `delete_folder` |
 | `job list` | `list_jobs` |
 | `job get` | `get_job` |
 | `job wait` | `wait_for_jobs` |
+| `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`.
 
+## Feedback
+
+Use `feedback user` / `send_user_feedback` only when the user explicitly agrees to send feedback. The command requires `--user-consent`; the MCP input requires `userConsent: true`. Good cases include user-requested bug reports, feature requests, visible frustration, or a request that cannot currently be completed through the CLI or MCP surface.
+
+Use `feedback agent` / `send_agent_feedback` for agent-observed problems, such as an API behavior that differs from the docs, an MCP response that is internally inconsistent, or a missing capability discovered while completing a task. Do not present agent feedback as user feedback unless the user explicitly asks you to send it on their behalf.
+
 ## Manifest Design
 
 Prefer manifests over large positional argument lists.

package/docs/exit-codes.md

@@ -17,6 +17,8 @@ The CLI uses stable exit codes so automation can branch without parsing human te
 
 These same codes are mirrored in `error.exitCode` and `error.code` inside the JSON envelope.
 
+API errors may also include `error.agentErrorCode`, a stable ChalkSurf agent error code such as `precondition_failed`, `confirmation_required`, `invalid_label`, or `resource_in_use`.
+
 ## JSON Envelope
 
 In `--json` mode, stdout contains a stable envelope:

package/docs/manual.md

@@ -193,6 +193,13 @@ chalksurf sheet get 00000000-0000-4000-8000-000000000001 --json
 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
+```
+
 List sheet issues that are useful for repair workflows:
 
 ```bash

package/docs/mcp.md

@@ -36,28 +36,46 @@ Treat write receipts as an agent audit log. They are suitable for user-visible s
 | `list_organizations` | read | List organizations granted to the MCP client. |
 | `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. |
+| `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. |
+| `set_exercise_visibility` | write | Make one writable exercise public or private when visibility controls are enabled. |
 | `import_exercise` | write | Queue an exercise import from MCP files or HTTPS URLs. |
 | `import_exercise_solution` | write | Queue a solution import for one exercise. |
 | `search_sheets` | read | Search visible sheets, optionally by readiness issues. |
 | `get_sheet` | read | Fetch full details for one visible sheet. |
+| `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. |
+| `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. |
 | `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 MCP files 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. |
 
-No MCP tool currently deletes resources or transfers resources between organizations.
+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.
+
+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.
 
 ## Common Workflows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "engines": {
@@ -27,7 +27,7 @@
     "prepack": "npm run build",
     "build": "node --import tsx ./scripts/build.ts",
     "lint": "eslint .",
-    "type-check": "tsc --noEmit --project ./tsconfig.json",
+    "type-check": "tsgo --noEmit --project ./tsconfig.json --checkers 2",
     "test": "vitest --config ./vitest.config.ts --run --maxWorkers=1",
     "test:watch": "vitest --config ./vitest.config.ts --watch --maxWorkers=1",
     "smoke-pack": "node --import tsx ./scripts/smoke-pack.ts"
@@ -40,9 +40,10 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/yargs": "^17.0.35",
+    "@typescript/native-preview": "^7.0.0-dev.20260527.2",
     "esbuild": "^0.27.0",
     "tsx": "^4.20.6",
-    "typescript": "^5.0.0",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.2"
   }
 }