@chalksurf/cli 0.2.0 → 0.2.2

package/docs/manual.md

@@ -4,16 +4,25 @@ Use this flow when a person is driving the CLI directly from a terminal.
 
 ## Authentication
 
-Interactive login stores the token and base URL in the local CLI config:
+Interactive login stores the token and base URL in a named profile:
 
 ```bash
-chalksurf auth login --base-url https://api.chalksurf.com
+chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
 ```
 
 The same command also works with piped stdin:
 
 ```bash
-printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login --base-url https://api.chalksurf.com
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login \
+  --profile prod-cztamas \
+  --base-url https://chalksurf-api.fly.dev \
+  --with-token
+```
+
+Set the profile you want to use by default in your terminal workflow:
+
+```bash
+chalksurf profile use prod-cztamas
 ```
 
 Check what the CLI will use for the current session:
@@ -24,9 +33,10 @@ chalksurf auth status
 
 Config resolution rules:
 
-- `--base-url` overrides `CHALKSURF_BASE_URL`, which overrides the stored config.
-- `CHALKSURF_TOKEN` overrides the stored config token.
-- `--organization` overrides manifest `organizationId`, which overrides `CHALKSURF_ORGANIZATION_ID`, which overrides the stored config.
+- `--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 Selection
 
@@ -42,6 +52,12 @@ Store a default organization for future commands:
 chalksurf org use org_123
 ```
 
+Store a default organization in a different profile without changing your default profile:
+
+```bash
+chalksurf --profile prod-codex org use org_456
+```
+
 Override it for one command:
 
 ```bash
@@ -56,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 \
@@ -79,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
 ```
 
@@ -91,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
@@ -110,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
@@ -122,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
 
@@ -132,11 +192,12 @@ Missing auth:
 chalksurf auth status
 ```
 
-Use a separate config file when switching between local, staging, and production:
+Use profiles when switching between local, staging, production, humans, and agents:
 
 ```bash
-export CHALKSURF_CONFIG_PATH=/tmp/chalksurf-staging.json
-chalksurf auth login --base-url https://staging-api.chalksurf.com
+chalksurf auth login --profile staging-cztamas --base-url https://chalksurf-api-staging.fly.dev
+chalksurf auth login --profile prod-cztamas --base-url https://chalksurf-api.fly.dev
+chalksurf profile use prod-cztamas
 ```
 
 Use JSON mode when you need exact machine-readable output:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chalksurf/cli",
-  "version": "0.2.0",
+  "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"
+        }
+      ]
+    }
+  }
+}