@chalksurf/cli 0.2.1 → 0.2.2

package/docs/agents.md

@@ -33,7 +33,7 @@ Prefer storing the token in the explicit agent profile for repeated Codex/CI run
 For agent-driven imports, always use:
 
 - `--manifest -` or a generated manifest file
-- `--wait` when the next step depends on completed imports
+- `--wait` when the next step depends on parsed content being saved
 - `--json` so the response stays machine-readable
 
 Recommended invocation shape:
@@ -49,6 +49,7 @@ In `--json` mode:
 - stderr is reserved for unexpected runtime failures
 
 Wait-style failures still include a populated `result` payload, so agents can inspect partial outcomes on exit code `6` or `7`.
+When an import requests translations, `--wait` waits for the import job only. Follow-up translation jobs are listed under each completed import job's `translationJobs`.
 
 ## Manifest Design
 
@@ -60,6 +61,8 @@ Why:
 - each logical source can carry a stable `sourceId`
 - sheet imports can group multiple source files into one resulting sheet
 - sheet imports carry `targetFolderPath`, `title`, and `translateTo` at the sheet level
+- exercise imports can carry top-level `translateTo` for every imported exercise
+- sheet solution imports can reconcile one or more solution files against all updatable exercises in one existing sheet
 - agents can correlate import results back to the discovered source set
 
 Use `sourceId` whenever a browsing step or upstream scraper already has a stable identifier:
@@ -98,6 +101,7 @@ Further reference:
 - [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)
 
 ## JSON Result Shape
 
@@ -120,6 +124,7 @@ Each job includes:
 - `sourceIndexes`
 - `sourceIds`
 - `status`
+- `translationJobs` when requested translations were queued after import
 
 `summary` includes:
 
@@ -133,8 +138,9 @@ Each job includes:
 2. Filter them to the target scope.
 3. Build a manifest with stable `sourceId` values.
 4. Pipe the manifest into the CLI with `--wait --json`.
-5. Inspect `ok`, `result.summary`, and `result.jobs`.
-6. Retry only the failed or timed-out source set.
+5. Inspect `ok`, `result.summary`, `result.jobs`, and any nested `translationJobs`.
+6. Use `job list`, `job wait`, `sheet search`, and `exercise search` to verify the created resources or translation jobs when needed.
+7. Retry only the failed or timed-out source set.
 
 For example:
 
@@ -163,6 +169,54 @@ On success, the envelope looks like:
 
 On timeout or job failure, `ok` becomes `false`, `error.code` is stable, and `result` still contains the normalized import data needed for retries.
 
+## Verification Commands
+
+Agents can inspect their own work without opening the web UI. Search commands default to `--ownership own`, which means the selected organization from `--organization`, `CHALKSURF_ORGANIZATION_ID`, or the active profile.
+
+List recent jobs, including jobs the UI tray has already viewed or dismissed:
+
+```bash
+chalksurf --profile prod-codex job list --include-viewed --include-dismissed --json
+```
+
+Find failed import jobs for retry:
+
+```bash
+chalksurf --profile prod-codex job list \
+  --status failed \
+  --type exercise_sheet_import \
+  --include-viewed \
+  --include-dismissed \
+  --json
+```
+
+Verify an imported private sheet by title:
+
+```bash
+chalksurf --profile prod-codex sheet search --text "OKTV 2014" --json
+```
+
+Verify imported exercises by text. Text search requires an explicit language:
+
+```bash
+chalksurf --profile prod-codex exercise search \
+  --text "binomial theorem" \
+  --language english \
+  --json
+```
+
+Import solutions for an already imported sheet when the solution key is separate:
+
+```bash
+chalksurf --profile prod-codex sheet import-solutions \
+  00000000-0000-4000-8000-000000000001 \
+  ./solutions.pdf \
+  --wait \
+  --json
+```
+
+Use `--ownership public` for public-library checks and `--ownership all` when the agent intentionally wants public results plus selected-organization results.
+
 ## Codex Workflow Example
 
 Target task:

package/docs/examples/exercise-import-manifest.json

@@ -1,6 +1,7 @@
 {
   "organizationId": "org_123",
   "exerciseSheetId": "00000000-0000-4000-8000-000000000111",
+  "translateTo": ["english"],
   "wait": true,
   "sources": [
     {

package/docs/examples/exercise-sheet-solution-import-manifest.json

@@ -0,0 +1,13 @@
+{
+  "organizationId": "org_123",
+  "exerciseSheetId": "00000000-0000-4000-8000-000000000333",
+  "wait": true,
+  "sources": [
+    {
+      "sourceId": "problem-set-solutions",
+      "kind": "local",
+      "path": "./imports/problem-set-solutions.pdf",
+      "relativePath": "Solutions/problem-set-solutions.pdf"
+    }
+  ]
+}

package/docs/manifest.md

@@ -7,6 +7,7 @@ One manifest file is passed to exactly one command:
 - `chalksurf sheet import --manifest <path|->`
 - `chalksurf exercise import --manifest <path|->`
 - `chalksurf exercise import-solution --manifest <path|->`
+- `chalksurf sheet import-solutions --manifest <path|->`
 
 Use `--manifest -` to pipe JSON on stdin.
 
@@ -17,9 +18,9 @@ Every manifest is a JSON object with these shared metadata fields:
 | 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. |
+| `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. |
 
-Every source object supports these common fields. For `sheet import`, sources appear inside `sheets[].sources[]`. For the exercise import commands, they appear in top-level `sources[]`.
+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[]`.
 
 | Field | Type | Required | Notes |
 | --- | --- | --- | --- |
@@ -85,11 +86,12 @@ Top-level fields:
 | --- | --- | --- | --- |
 | `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 `translateTo` are rejected for this command.
+- `title` and source-level `translateTo` are rejected for this command.
 
 Canonical example:
 
@@ -115,12 +117,32 @@ 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.
+- 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.

package/docs/manual.md

@@ -72,7 +72,7 @@ Import one sheet and wait for the background job to finish:
 chalksurf sheet import ./fixtures/algebra.pdf --wait
 ```
 
-Import one sheet, override its title, and request an English translation during import:
+Import one sheet, override its title, and request an English translation after import:
 
 ```bash
 chalksurf sheet import ./fixtures/algebra.pdf \
@@ -95,6 +95,7 @@ Import exercises into an existing sheet:
 ```bash
 chalksurf exercise import ./fixtures/problem-set.pdf \
   --sheet-id 00000000-0000-4000-8000-000000000001 \
+  --translate-to english \
   --wait
 ```
 
@@ -107,6 +108,15 @@ chalksurf exercise import-solution \
   --wait
 ```
 
+Import a separate solution file for an existing exercise sheet:
+
+```bash
+chalksurf sheet import-solutions \
+  00000000-0000-4000-8000-000000000001 \
+  ./fixtures/sheet-solutions.pdf \
+  --wait
+```
+
 Import from a remote URL:
 
 ```bash
@@ -126,6 +136,18 @@ Sheet import manifests use top-level `sheets[]`. Each sheet has one destination
 
 ## Working With Jobs
 
+List recent jobs:
+
+```bash
+chalksurf job list
+```
+
+Include jobs already viewed or dismissed in the web UI:
+
+```bash
+chalksurf job list --include-viewed --include-dismissed
+```
+
 Read one job:
 
 ```bash
@@ -138,7 +160,29 @@ Wait on one or more jobs later:
 chalksurf job wait job_123 job_124
 ```
 
-`--wait` on an import command means the requested import work is complete before the command exits. For sheet imports, that includes requested translations.
+`--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.
+
+## Searching From The CLI
+
+Search commands default to `--ownership own`, which means resources in the selected organization.
+
+Find exercise sheets by title:
+
+```bash
+chalksurf sheet search --text "OKTV 2014"
+```
+
+Find exercises by text:
+
+```bash
+chalksurf exercise search --text "binomial theorem" --language english
+```
+
+Search public resources instead:
+
+```bash
+chalksurf sheet search --text "OKTV" --ownership public
+```
 
 ## Troubleshooting
 

package/package.json

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

package/schemas/exercise-import-manifest.schema.json

@@ -14,6 +14,14 @@
       "type": "string",
       "minLength": 1
     },
+    "translateTo": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/translateLanguage"
+      }
+    },
     "wait": {
       "type": "boolean"
     },
@@ -30,6 +38,10 @@
       "type": "string",
       "minLength": 1
     },
+    "translateLanguage": {
+      "type": "string",
+      "enum": ["english", "hungarian", "german", "french", "spanish", "italian"]
+    },
     "localSource": {
       "type": "object",
       "additionalProperties": false,

package/schemas/exercise-sheet-solution-import-manifest.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/knowledge-maps/chalksurf/blob/main/packages/cli/schemas/exercise-sheet-solution-import-manifest.schema.json",
+  "title": "ChalkSurf Exercise Sheet Solution Import Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sources"],
+  "properties": {
+    "organizationId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "exerciseSheetId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "wait": {
+      "type": "boolean"
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/source"
+      }
+    }
+  },
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1
+    },
+    "localSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "local"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "directorySource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "path"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "directory"
+        },
+        "path": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativeRoot": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "urlSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "url"],
+      "properties": {
+        "sourceId": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "kind": {
+          "const": "url"
+        },
+        "url": {
+          "$ref": "#/$defs/nonEmptyString"
+        },
+        "relativePath": {
+          "$ref": "#/$defs/nonEmptyString"
+        }
+      }
+    },
+    "source": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/localSource"
+        },
+        {
+          "$ref": "#/$defs/directorySource"
+        },
+        {
+          "$ref": "#/$defs/urlSource"
+        }
+      ]
+    }
+  }
+}