@chalksurf/cli 0.3.6 → 0.4.0

package/README.md

@@ -1,13 +1,13 @@
 # `@chalksurf/cli`
 
-Publishable ChalkSurf CLI package. Expect breaking changes while the CLI is still only used internally.
+ChalkSurf CLI 0.4.0 provides content generation, imports, updates, saved plans and recoverable job controls. This release intentionally breaks older command and manifest formats; see the [migration guide](./docs/migration-0.4.md).
 
 ## Installation
 
 Run the published CLI without a global install:
 
 ```bash
-npx @chalksurf/cli@ --help
+npx @chalksurf/cli --help
 ```
 
 Install it globally when you want a persistent local binary:
@@ -31,7 +31,6 @@ chalksurf sheet import ./fixtures/algebra.pdf --wait
 Headless or agent flow:
 
 ```bash
-CHALKSURF_TOKEN=cs_cli_... \
 printf '%s' "$CHALKSURF_TOKEN" | npx @chalksurf/cli auth login \
   --profile prod-codex \
   --base-url https://chalksurf-api.fly.dev \
@@ -50,8 +49,9 @@ npx @chalksurf/cli --profile prod-codex sheet copy SHEET_ID "Easier variant" \
 npx @chalksurf/cli --profile prod-codex exercise update EXERCISE_ID \
   --target-sheet-id COPIED_SHEET_ID \
   --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
 ```
 
 Admin sheet-series labeling:
@@ -59,26 +59,32 @@ Admin sheet-series labeling:
 ```bash
 npx @chalksurf/cli --profile prod-codex sheet list --all --result-file inventory.json --json
 npx @chalksurf/cli --profile prod-codex sheet series list --subject math --json
-npx @chalksurf/cli --profile prod-codex sheet bulk-update \
-  --input batch-001.json --result-file batch-001.result.json --json
+npx @chalksurf/cli --profile prod-codex sheet update \
+  --manifest batch-001.json --dry-run --plan-out batch-001.plan.json --json
+npx @chalksurf/cli --profile prod-codex plan apply batch-001.plan.json --result-file applied.json --json
 ```
 
-Use the returned confirmation digest in an unchanged apply batch. `--input -` reads JSON from stdin; `--input-json` remains available for short inline payloads. If an apply response is uncertain, verify the original manifest with `sheet bulk-update verify` before considering another apply. Result files preserve complete private evidence and refuse to overwrite an existing destination.
+Review the saved plan before applying it. If the apply response is uncertain, use `plan verify batch-001.plan.json` and inspect request acceptance before considering another write. `--input FILE|-` supplies one patch; `--manifest FILE|-` supplies a strict v1 repeated request. See [content operations](./docs/content-operations.md) for the complete generation, translation, import and recovery flow.
+
+Every operational command accepts `--result-file PATH`. The CLI preflights a new destination before command execution, writes the complete success or failure JSON envelope to a private file, and refuses to overwrite existing evidence. Stdout stays compact and includes the absolute result path. If publication fails after the command finishes, stdout contains the complete envelope plus a warning and the command keeps its original exit code.
 
-Sheet import manifests use top-level `sheets[]`, where each sheet has one `targetFolderPath` and one or more ordered `sources[]`. See [the canonical example](./packages/cli/docs/examples/sheet-import-manifest.json).
+Content manifests use `schemaVersion: "v1"`, `operation` and `items[]`. Sheet entries retain ordered sources, components or authoritative language groups. File paths resolve relative to the manifest file; stdin paths use the invocation directory. See the [manifest reference](./docs/manifest.md) and [canonical examples](./docs/examples/).
 
 ## Docs
 
 - [Public CLI and MCP documentation](https://chalksurf.com/docs)
-- [Manual operator guide](./packages/cli/docs/manual.md)
-- [Agent and Codex guide](./packages/cli/docs/agents.md)
-- [MCP guide](./packages/cli/docs/mcp.md)
-- [Manifest reference](./packages/cli/docs/manifest.md)
-- [Exit codes and JSON errors](./packages/cli/docs/exit-codes.md)
-- [Sheet import schema](./packages/cli/schemas/sheet-import-manifest.schema.json)
-- [Exercise import schema](./packages/cli/schemas/exercise-import-manifest.schema.json)
-- [Exercise solution import schema](./packages/cli/schemas/exercise-solution-import-manifest.schema.json)
-- [Exercise sheet solution import schema](./packages/cli/schemas/exercise-sheet-solution-import-manifest.schema.json)
+- [Manual operator guide](./docs/manual.md)
+- [Agent and Codex guide](./docs/agents.md)
+- [MCP guide](./docs/mcp.md)
+- [Content operations and saved plans](./docs/content-operations.md)
+- [0.4.0 migration guide](./docs/migration-0.4.md)
+- [Manifest reference](./docs/manifest.md)
+- [Exit codes and JSON errors](./docs/exit-codes.md)
+- [Sheet import schema](./schemas/sheet-import-manifest.schema.json)
+- [Exercise import schema](./schemas/exercise-import-manifest.schema.json)
+- [Exercise solution import schema](./schemas/exercise-solution-import-manifest.schema.json)
+- [Exercise sheet solution import schema](./schemas/exercise-sheet-solution-import-manifest.schema.json)
+- [Exercise sheet translation import schema](./schemas/exercise-sheet-translation-import-manifest.schema.json)
 
 ## Local And Staging Testing