@chalksurf/cli 0.2.0 → 0.2.2

package/dist/lib/config-store.js

@@ -5,7 +5,11 @@ import { CliCommandError } from './cli-error.js';
 export const chalksurfBaseUrlEnvVar = 'CHALKSURF_BASE_URL';
 export const chalksurfTokenEnvVar = 'CHALKSURF_TOKEN';
 export const chalksurfOrganizationIdEnvVar = 'CHALKSURF_ORGANIZATION_ID';
+export const chalksurfProfileEnvVar = 'CHALKSURF_PROFILE';
 export const chalksurfConfigPathEnvVar = 'CHALKSURF_CONFIG_PATH';
+export const cliConfigSchemaVersion = 2;
+export const implicitDefaultProfileName = 'default';
+const profileNamePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const normalizeOptionalString = (value) => {
     const trimmedValue = value?.trim();
     return trimmedValue ? trimmedValue : undefined;
@@ -14,13 +18,91 @@ const normalizeStoredBaseUrl = (value) => {
     const normalizedValue = normalizeOptionalString(value);
     return normalizedValue?.replace(/\/+$/, '') || undefined;
 };
-const sanitizeConfig = (config) => {
+const isRecord = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+export const assertValidProfileName = (profileName) => {
+    if (!profileNamePattern.test(profileName)) {
+        throw new CliCommandError(`Invalid profile "${profileName}". Profile names must start with a letter or number and contain only letters, numbers, ".", "_", or "-".`, 2);
+    }
+};
+const normalizeProfileName = (value) => {
+    const profileName = normalizeOptionalString(value);
+    if (!profileName) {
+        return undefined;
+    }
+    assertValidProfileName(profileName);
+    return profileName;
+};
+const sanitizeProfileConfig = (config) => {
     return Object.fromEntries(Object.entries({
         token: normalizeOptionalString(config.token),
         baseUrl: normalizeStoredBaseUrl(config.baseUrl),
         organizationId: normalizeOptionalString(config.organizationId),
     }).filter(([, value]) => value !== undefined));
 };
+const hasProfileConfigValues = (config) => {
+    return Boolean(config.baseUrl || config.token || config.organizationId);
+};
+const readProfileConfig = (value) => {
+    if (!isRecord(value)) {
+        return {};
+    }
+    return sanitizeProfileConfig({
+        baseUrl: typeof value.baseUrl === 'string' ? value.baseUrl : undefined,
+        organizationId: typeof value.organizationId === 'string' ? value.organizationId : undefined,
+        token: typeof value.token === 'string' ? value.token : undefined,
+    });
+};
+const sanitizeRootConfig = (config) => {
+    const profiles = Object.fromEntries(Object.entries(config.profiles)
+        .map(([profileName, profileConfig]) => {
+        const normalizedProfileName = normalizeProfileName(profileName);
+        const sanitizedProfileConfig = sanitizeProfileConfig(profileConfig);
+        return normalizedProfileName && hasProfileConfigValues(sanitizedProfileConfig)
+            ? [normalizedProfileName, sanitizedProfileConfig]
+            : null;
+    })
+        .filter((entry) => entry !== null));
+    const defaultProfile = normalizeProfileName(config.defaultProfile);
+    return {
+        schemaVersion: cliConfigSchemaVersion,
+        ...(defaultProfile && profiles[defaultProfile] ? { defaultProfile } : {}),
+        profiles,
+    };
+};
+const readRootConfig = (value) => {
+    if (!isRecord(value)) {
+        return { schemaVersion: cliConfigSchemaVersion, profiles: {} };
+    }
+    if (isRecord(value.profiles)) {
+        const profiles = Object.fromEntries(Object.entries(value.profiles)
+            .map(([profileName, profileConfig]) => {
+            const sanitizedProfileConfig = readProfileConfig(profileConfig);
+            return hasProfileConfigValues(sanitizedProfileConfig)
+                ? [profileName, sanitizedProfileConfig]
+                : null;
+        })
+            .filter((entry) => entry !== null));
+        return sanitizeRootConfig({
+            schemaVersion: cliConfigSchemaVersion,
+            defaultProfile: typeof value.defaultProfile === 'string' ? value.defaultProfile : undefined,
+            profiles,
+        });
+    }
+    const legacyProfile = readProfileConfig(value);
+    if (!hasProfileConfigValues(legacyProfile)) {
+        return { schemaVersion: cliConfigSchemaVersion, profiles: {} };
+    }
+    return {
+        schemaVersion: cliConfigSchemaVersion,
+        defaultProfile: implicitDefaultProfileName,
+        profiles: {
+            [implicitDefaultProfileName]: legacyProfile,
+        },
+    };
+};
+const rootConfigHasProfiles = (config) => Object.keys(config.profiles).length > 0;
 const getDefaultConfigPath = ({ env, platform, homeDirectory, }) => {
     const explicitConfigPath = normalizeOptionalString(env[chalksurfConfigPathEnvVar]);
     if (explicitConfigPath) {
@@ -73,6 +155,24 @@ export const resolveToken = ({ env, config }) => {
     }
     return { source: 'none' };
 };
+export const resolveProfile = ({ flagValue, env, config, }) => {
+    const flagProfileName = normalizeProfileName(flagValue);
+    if (flagProfileName) {
+        return { profileName: flagProfileName, profileSource: 'flag' };
+    }
+    const envProfileName = normalizeProfileName(env[chalksurfProfileEnvVar]);
+    if (envProfileName) {
+        return { profileName: envProfileName, profileSource: 'env' };
+    }
+    const defaultProfile = normalizeProfileName(config.defaultProfile);
+    if (defaultProfile) {
+        return { profileName: defaultProfile, profileSource: 'config' };
+    }
+    if (!rootConfigHasProfiles(config)) {
+        return { profileName: implicitDefaultProfileName, profileSource: 'implicit-default' };
+    }
+    throw new CliCommandError(`No active ChalkSurf profile selected. Pass --profile, set ${chalksurfProfileEnvVar}, or run "chalksurf profile use <profile>".`, 2);
+};
 export const resolveOrganization = ({ flagValue, env, config, profile, }) => {
     const flagOrganizationId = normalizeOptionalString(flagValue);
     if (flagOrganizationId) {
@@ -134,14 +234,23 @@ export const resolveOrganization = ({ flagValue, env, config, profile, }) => {
 export const createConfigStore = ({ configPath, env = process.env, platform = process.platform, homeDirectory = homedir(), fs = { chmod, mkdir, readFile, rm, writeFile }, } = {}) => {
     const resolvedConfigPath = configPath || getDefaultConfigPath({ env, platform, homeDirectory });
     const load = async () => {
+        const rootConfig = await loadRoot();
+        const resolvedProfile = resolveProfile({ env, config: rootConfig });
+        const profileConfig = rootConfig.profiles[resolvedProfile.profileName] ?? {};
+        return {
+            ...profileConfig,
+            ...resolvedProfile,
+        };
+    };
+    const loadRoot = async () => {
         try {
             const configContents = await fs.readFile(resolvedConfigPath, 'utf8');
             const parsedConfig = JSON.parse(configContents);
-            return sanitizeConfig(parsedConfig);
+            return readRootConfig(parsedConfig);
         }
         catch (error) {
             if (error.code === 'ENOENT') {
-                return {};
+                return { schemaVersion: cliConfigSchemaVersion, profiles: {} };
             }
             if (error instanceof SyntaxError) {
                 throw new CliCommandError(`Failed to parse CLI config at ${resolvedConfigPath}.`, 2);
@@ -149,9 +258,18 @@ export const createConfigStore = ({ configPath, env = process.env, platform = pr
             throw error;
         }
     };
-    const save = async (config) => {
-        const sanitizedConfig = sanitizeConfig(config);
-        if (Object.keys(sanitizedConfig).length === 0) {
+    const loadProfile = async ({ profileName } = {}) => {
+        const rootConfig = await loadRoot();
+        const resolvedProfile = resolveProfile({ flagValue: profileName, env, config: rootConfig });
+        const profileConfig = rootConfig.profiles[resolvedProfile.profileName] ?? {};
+        return {
+            ...profileConfig,
+            ...resolvedProfile,
+        };
+    };
+    const saveRoot = async (config) => {
+        const sanitizedConfig = sanitizeRootConfig(config);
+        if (!rootConfigHasProfiles(sanitizedConfig)) {
             await fs.rm(resolvedConfigPath, { force: true });
             return sanitizedConfig;
         }
@@ -162,15 +280,75 @@ export const createConfigStore = ({ configPath, env = process.env, platform = pr
         await fs.chmod(resolvedConfigPath, 0o600);
         return sanitizedConfig;
     };
-    const update = async (updater) => {
-        const currentConfig = await load();
-        const nextConfig = await updater(currentConfig);
-        return await save(nextConfig);
+    const save = async (config) => {
+        const rootConfig = await loadRoot();
+        const nextProfileConfig = sanitizeProfileConfig(config);
+        const nextRootConfig = {
+            ...rootConfig,
+            profiles: {
+                ...rootConfig.profiles,
+            },
+        };
+        if (hasProfileConfigValues(nextProfileConfig)) {
+            nextRootConfig.profiles[config.profileName] = nextProfileConfig;
+        }
+        else {
+            delete nextRootConfig.profiles[config.profileName];
+        }
+        if (config.profileSource === 'implicit-default' && hasProfileConfigValues(nextProfileConfig)) {
+            nextRootConfig.defaultProfile = config.profileName;
+        }
+        return await saveRoot(nextRootConfig);
+    };
+    const update = async ({ profileName }, updater) => {
+        const currentConfig = await loadProfile({ profileName });
+        const nextProfileConfig = await updater(currentConfig);
+        return await save({
+            ...nextProfileConfig,
+            profileName: currentConfig.profileName,
+            profileSource: currentConfig.profileSource,
+        });
+    };
+    const setDefaultProfile = async (profileName) => {
+        const normalizedProfileName = normalizeProfileName(profileName);
+        if (!normalizedProfileName) {
+            throw new CliCommandError('Profile name is required.', 2);
+        }
+        const rootConfig = await loadRoot();
+        if (!rootConfig.profiles[normalizedProfileName]) {
+            throw new CliCommandError(`Profile "${normalizedProfileName}" does not exist. Run "chalksurf auth login --profile ${normalizedProfileName} --base-url <url>" first.`, 2);
+        }
+        return await saveRoot({
+            ...rootConfig,
+            defaultProfile: normalizedProfileName,
+        });
+    };
+    const deleteProfile = async (profileName) => {
+        const normalizedProfileName = normalizeProfileName(profileName);
+        if (!normalizedProfileName) {
+            throw new CliCommandError('Profile name is required.', 2);
+        }
+        const rootConfig = await loadRoot();
+        if (!rootConfig.profiles[normalizedProfileName]) {
+            throw new CliCommandError(`Profile "${normalizedProfileName}" does not exist.`, 2);
+        }
+        const profiles = { ...rootConfig.profiles };
+        delete profiles[normalizedProfileName];
+        return await saveRoot({
+            schemaVersion: cliConfigSchemaVersion,
+            ...(rootConfig.defaultProfile === normalizedProfileName ? {} : { defaultProfile: rootConfig.defaultProfile }),
+            profiles,
+        });
     };
     return {
         path: resolvedConfigPath,
         load,
+        loadProfile,
+        loadRoot,
         save,
+        saveRoot,
         update,
+        setDefaultProfile,
+        deleteProfile,
     };
 };

package/dist/lib/import-output.js

@@ -65,3 +65,17 @@ export const formatCliImportSummary = (summary) => {
     }
     return `Summary: ${parts.join(', ') || '0 jobs'}.`;
 };
+export const formatCliImportTranslationJobs = (translationJobs) => {
+    if (!translationJobs || translationJobs.length === 0) {
+        return [];
+    }
+    return [
+        `Queued ${translationJobs.length} translation job${translationJobs.length === 1 ? '' : 's'}:`,
+        ...translationJobs.map((job) => {
+            if (job.type === 'exercise_translation_generation') {
+                return `${job.jobId}  exercise ${job.exerciseId}  ${job.languages.join(', ')}`;
+            }
+            return `${job.jobId}  sheet ${job.exerciseSheetId}  ${job.language}`;
+        }),
+    ];
+};

package/dist/lib/manifest.js

@@ -161,6 +161,10 @@ const parseExerciseImportManifest = (manifestText) => {
             parsedManifest,
             topLevelFields: ['exerciseSheetId'],
         }),
+        translateTo: parseTranslateTo({
+            value: parsedManifest.translateTo,
+            label: 'Manifest',
+        }),
         sources,
     };
 };
@@ -176,6 +180,18 @@ const parseExerciseSolutionImportManifest = (manifestText) => {
         sources,
     };
 };
+const parseExerciseSheetSolutionImportManifest = (manifestText) => {
+    const parsedManifest = parseSourceManifestObject(manifestText);
+    const sources = parsedManifest.sources.map((source, index) => parseBaseManifestSource(source, index));
+    assertUniqueSourceIds(sources);
+    return {
+        ...parseManifestMetadata({
+            parsedManifest,
+            topLevelFields: ['exerciseSheetId'],
+        }),
+        sources,
+    };
+};
 const parseSheetImportManifest = (manifestText) => {
     const parsedManifest = parseManifestObject(manifestText);
     if ('sources' in parsedManifest) {
@@ -261,6 +277,14 @@ export const loadExerciseSolutionImportManifest = async ({ cwd, manifestPath, st
         stdin,
     });
 };
+export const loadExerciseSheetSolutionImportManifest = async ({ cwd, manifestPath, stdin, }) => {
+    return await loadManifest({
+        cwd,
+        manifestPath,
+        parseManifest: parseExerciseSheetSolutionImportManifest,
+        stdin,
+    });
+};
 export const loadSheetImportManifest = async ({ cwd, manifestPath, stdin, }) => {
     return await loadManifest({
         cwd,

package/dist/lib/session.js

@@ -1,3 +1,4 @@
+import { createApiClient } from './api-client.js';
 import { CliCommandError } from './cli-error.js';
 import { chalksurfBaseUrlEnvVar, chalksurfOrganizationIdEnvVar, chalksurfTokenEnvVar, resolveBaseUrl, resolveToken, } from './config-store.js';
 const normalizeOptionalString = (value) => {
@@ -31,6 +32,32 @@ export const resolveRequestedOrganizationId = ({ config, env, fallbackValue, fla
         normalizeOptionalString(env[chalksurfOrganizationIdEnvVar]) ??
         normalizeOptionalString(config.organizationId));
 };
+export const createResolvedApiClient = async ({ context, baseUrlFlagValue, organizationFallbackValue, organizationFlagValue, profileName, }) => {
+    const config = await context.configStore.loadProfile({ profileName });
+    const resolvedBaseUrl = requireResolvedBaseUrl({
+        flagValue: baseUrlFlagValue,
+        env: context.env,
+        config,
+    });
+    const resolvedToken = requireResolvedToken({
+        env: context.env,
+        config,
+    });
+    const organizationId = resolveRequestedOrganizationId({
+        flagValue: organizationFlagValue,
+        fallbackValue: organizationFallbackValue,
+        env: context.env,
+        config,
+    });
+    return {
+        apiClient: createApiClient({
+            baseUrl: resolvedBaseUrl.value,
+            token: resolvedToken.value,
+            organizationId,
+        }),
+        organizationId,
+    };
+};
 export const formatUserIdentity = (profile) => {
     if (profile.name && profile.email) {
         return `${profile.name} <${profile.email}>`;

package/dist/lib/translation-languages.js

@@ -1 +1,16 @@
+import { CliCommandError } from './cli-error.js';
 export const translationLanguages = ['english', 'hungarian', 'german', 'french', 'spanish', 'italian'];
+export const resolveRequestedTranslateToLanguages = (rawValues) => {
+    if (!rawValues || rawValues.length === 0) {
+        return undefined;
+    }
+    const invalidLanguage = rawValues.find((value) => !translationLanguages.includes(value));
+    if (invalidLanguage) {
+        throw new CliCommandError(`--translate-to must be one of: ${translationLanguages.join(', ')}`, 2);
+    }
+    const languages = rawValues;
+    if (new Set(languages).size !== languages.length) {
+        throw new CliCommandError('--translate-to languages must be unique.', 2);
+    }
+    return languages;
+};

package/dist/lib/user-jobs.js

@@ -14,7 +14,13 @@ export const serializeCliJob = (job) => {
         exerciseId: job.result?.exerciseId,
         exerciseIds: job.result?.exerciseIds,
         exerciseSheetId: job.result?.exerciseSheetId,
+        eligibleExerciseCount: job.result?.eligibleExerciseCount,
+        nonUpdatableExerciseCount: job.result?.nonUpdatableExerciseCount,
         resultCode: job.result?.resultCode,
+        skippedExerciseCount: job.result?.skippedExerciseCount,
+        translationJobs: job.result?.translationJobs,
+        unmatchedImportedSolutionCount: job.result?.unmatchedImportedSolutionCount,
+        updatedExerciseCount: job.result?.updatedExerciseCount,
     };
 };
 export const formatCliJobSummary = (job) => {

package/docs/agents.md

@@ -4,34 +4,42 @@ Use this flow when ChalkSurf is driven by Codex, CI, or another orchestration la
 
 ## Authentication Strategy
 
-Prefer environment variables over interactive config:
+Agents must always use an explicit profile. The profile name must follow the
+`ENV-AGENT_TYPE` convention, such as `prod-codex`, `staging-codex`, `dev-claude`,
+or `prod-claude`.
 
 ```bash
-export CHALKSURF_BASE_URL=https://api.chalksurf.com
-export CHALKSURF_TOKEN=cs_cli_...
-export CHALKSURF_ORGANIZATION_ID=org_123
+chalksurf --profile prod-codex auth status --json
 ```
 
-Check the session in machine-readable mode:
+Do not rely on the default profile in agent-driven runs. The default profile is
+for the human operator's terminal workflow and may point at a different
+environment, user token, or selected organization.
+
+Create or refresh an agent profile explicitly:
 
 ```bash
-chalksurf auth status --json
+printf '%s' "$CHALKSURF_TOKEN" | chalksurf auth login \
+  --profile prod-codex \
+  --base-url https://chalksurf-api.fly.dev \
+  --with-token
 ```
 
-Avoid `auth login` for short-lived runs unless you explicitly want local persistence.
+Use `CHALKSURF_TOKEN` only as the source for login or as a short-lived override.
+Prefer storing the token in the explicit agent profile for repeated Codex/CI runs.
 
 ## Command Contract
 
 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:
 
 ```bash
-chalksurf sheet import --manifest - --wait --json
+chalksurf --profile prod-codex sheet import --manifest - --wait --json
 ```
 
 In `--json` mode:
@@ -41,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
 
@@ -52,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:
@@ -90,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
 
@@ -112,6 +124,7 @@ Each job includes:
 - `sourceIndexes`
 - `sourceIds`
 - `status`
+- `translationJobs` when requested translations were queued after import
 
 `summary` includes:
 
@@ -125,13 +138,14 @@ 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:
 
 ```bash
-cat import.json | chalksurf sheet import --manifest - --wait --json
+cat import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json
 ```
 
 On success, the envelope looks like:
@@ -155,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:
@@ -168,13 +230,13 @@ Recommended workflow:
 3. Codex builds a sheet-import manifest with one `sheets[]` entry per resulting sheet.
 4. Codex groups multiple source files inside one `sources[]` array when they belong to the same resulting sheet.
 5. Codex sets `translateTo: ["english"]` on the sheet entries that should produce an English translation.
-6. Codex runs `chalksurf sheet import --manifest - --wait --json`.
+6. Codex runs `chalksurf --profile prod-codex sheet import --manifest - --wait --json`.
 7. Codex inspects `result.summary.failed`, `result.summary.timedOut`, and `jobs` to decide whether to retry or report failures.
 
 Minimal shell shape:
 
 ```bash
-cat import.json | chalksurf sheet import --manifest - --wait --json
+cat import.json | chalksurf --profile prod-codex sheet import --manifest - --wait --json
 ```
 
 The discovery step belongs outside the ChalkSurf CLI. The CLI contract starts at a concrete manifest and ends at structured import results.

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.