@toloka-platform/sdk 0.2.0-preview.3 → 0.2.0-preview.4

package/src/cli/project.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import { mkdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import type {
@@ -12,10 +11,11 @@ import type { Dataset, DatasetField, Pipeline, PotatoClient } from "../client";
 import { generatePipelineSourceTree } from "../importer";
 import { readTolokaState, TOLOKA_STATE_FILENAME, writeTolokaState } from "../state";
 import type { TolokaState } from "../state";
-import { MISSING_PROJECT_ID_MESSAGE } from "./project-context";
+import { assertProjectSelected } from "./project-context";
 import { collectGraphSecretNames } from "./secrets";
 import { loadProjectSource } from "./source";
 import type { ProjectPipelineSource, ProjectSource } from "./source";
+import { assertCli, REPORT_HINT } from "./cli-error";
 
 export type PipelinePlanChange = {
   readonly kind: "node" | "connection" | "field" | "layout";
@@ -296,9 +296,10 @@ export const desiredDatasets = (source: ProjectSource): readonly DesiredDataset[
     }
     for (const field of pipeline.definition.graph.fields) {
       const existing = fields.get(field.name);
-      assert(
+      assertCli(
         existing === undefined || valueKey(existing.jsonSchema) === valueKey(field.jsonSchema),
         `Dataset "${pipeline.definition.dataset}" has conflicting schemas for field "${field.name}".`,
+        { hint: { description: "Give the field one JSON schema across all pipelines that share the dataset." } },
       );
       if (existing === undefined) fields.set(field.name, field);
     }
@@ -314,13 +315,15 @@ export const desiredDatasets = (source: ProjectSource): readonly DesiredDataset[
 const validateSource = (source: ProjectSource) => {
   const sourceDirectories = new Set<string>();
   for (const pipeline of source.pipelines) {
-    assert(
+    assertCli(
       sourceDirectoryPattern.test(pipeline.sourceDirectory),
       `Invalid pipeline source directory ${pipeline.sourceDirectory}`,
+      { hint: { description: "Use a relative path without backslashes, // or . and .. segments." } },
     );
-    assert(
+    assertCli(
       !sourceDirectories.has(pipeline.sourceDirectory),
       `Pipeline source directory ${pipeline.sourceDirectory} is declared more than once`,
+      { hint: { description: "Give each pipeline its own source directory." } },
     );
     sourceDirectories.add(pipeline.sourceDirectory);
     validatePipelineDefinition(pipeline.definition);
@@ -338,14 +341,19 @@ const liveDatasetFor = (
       ? undefined
       : datasets.find((dataset) => dataset.id === binding.datasetId);
   if (bound !== undefined) {
-    assert(
+    assertCli(
       bound.name === name,
       `Dataset ${bound.id} is bound as "${name}" but is named "${bound.name}".`,
+      { hint: { description: "Rename the dataset in source to match the platform, or run toloka project untrack dataset <name> and bind it again with toloka apply." } },
     );
     return bound;
   }
   const matching = datasets.filter((dataset) => dataset.name === name);
-  assert(matching.length <= 1, `Project has multiple datasets named "${name}".`);
+  assertCli(
+    matching.length <= 1,
+    `Project has multiple datasets named "${name}".`,
+    { hint: { description: "Rename the duplicate datasets in the platform, or reference the dataset by id." } },
+  );
   return matching[0];
 };
 
@@ -360,7 +368,11 @@ const livePipelineFor = (
       : pipelines.find((pipeline) => pipeline.id === binding.pipelineId);
   if (bound !== undefined) return bound;
   const matching = pipelines.filter((pipeline) => pipeline.name === source.name);
-  assert(matching.length <= 1, `Project has multiple pipelines named "${source.name}".`);
+  assertCli(
+    matching.length <= 1,
+    `Project has multiple pipelines named "${source.name}".`,
+    { hint: { description: "Rename the duplicate pipelines in the platform, then re-run the command." } },
+  );
   return matching[0];
 };
 
@@ -542,7 +554,7 @@ const inspectProject = async (
   validateSource(source);
   const state = await readTolokaState(options.sourceRoot);
   const projectId = options.projectId ?? state?.projectId;
-  assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+  assertProjectSelected(projectId);
 
   const bindings = state?.projectId === projectId ? state : undefined;
   const requiredSecrets = new Set(
@@ -627,7 +639,11 @@ export async function importProject(
   const datasetIds = new Set<string>();
   for (const snapshot of snapshots) {
     const rootNode = snapshot.graph.nodes.find((node) => node.type === "root");
-    assert(rootNode?.settings.datasetId, "Every imported pipeline must have a bound dataset.");
+    assertCli(
+      rootNode?.settings.datasetId,
+      "Every imported pipeline must have a bound dataset.",
+      { hint: { description: "Bind a dataset to the pipeline in the platform, then re-run toloka import." } },
+    );
     datasetIds.add(rootNode.settings.datasetId);
   }
   const projectDatasets = await collectAsync(
@@ -636,7 +652,11 @@ export async function importProject(
   const datasets: Dataset[] = [];
   for (const datasetId of [...datasetIds].toSorted()) {
     const dataset = projectDatasets.find((candidate) => candidate.id === datasetId);
-    assert(dataset, `Project ${options.projectId} has no dataset ${datasetId}.`);
+    assertCli(
+      dataset,
+      `Project ${options.projectId} has no dataset ${datasetId}.`,
+      { hint: { description: "Check toloka dataset list; the pipeline's dataset binding must point at a dataset of this project." } },
+    );
     datasets.push(dataset);
   }
   const datasetsById = new Map<string, Dataset>(datasets.map((dataset) => [dataset.id, dataset]));
@@ -646,22 +666,32 @@ export async function importProject(
   const stateDatasets: Record<string, { readonly datasetId: string }> = {};
   for (const [index, pipeline] of pipelines.entries()) {
     const snapshot = snapshots[index];
-    assert(snapshot, `Pipeline ${pipeline.id} has no graph snapshot.`);
+    assertCli(snapshot, `Pipeline ${pipeline.id} has no graph snapshot.`, { hint: REPORT_HINT });
     const rootNode = snapshot.graph.nodes.find((node) => node.type === "root");
-    assert(rootNode?.settings.datasetId, `Pipeline ${pipeline.id} has no dataset binding.`);
+    assertCli(
+      rootNode?.settings.datasetId,
+      `Pipeline ${pipeline.id} has no dataset binding.`,
+      { hint: { description: "Bind a dataset to the pipeline in the platform, then re-run toloka import." } },
+    );
     const dataset = datasetsById.get(rootNode.settings.datasetId);
-    assert(
+    assertCli(
       dataset,
       `Pipeline ${pipeline.id} references unknown dataset ${rootNode.settings.datasetId}.`,
+      { hint: { description: "Check toloka dataset list; the pipeline's dataset binding must point at a dataset of this project." } },
     );
     const existingDatasetBinding = stateDatasets[dataset.name];
-    assert(
+    assertCli(
       existingDatasetBinding === undefined || existingDatasetBinding.datasetId === dataset.id,
       `Project has multiple referenced datasets named "${dataset.name}".`,
+      { hint: { description: "Rename the duplicate datasets in the platform, then re-run toloka import." } },
     );
     stateDatasets[dataset.name] = { datasetId: dataset.id };
     const sourceDirectory = directories.get(pipeline.id);
-    assert(sourceDirectory, `Pipeline ${pipeline.id} has no source directory.`);
+    assertCli(
+      sourceDirectory,
+      `Pipeline ${pipeline.id} has no source directory.`,
+      { hint: REPORT_HINT },
+    );
     statePipelines[sourceDirectory] = { pipelineId: pipeline.id };
     for (const [relativePath, source] of Object.entries(
       generatePipelineSourceTree(snapshot.graph, { dataset: dataset.name }),
@@ -678,9 +708,10 @@ export async function importProject(
   } catch (error) {
     if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT") throw error;
   }
-  assert(
+  assertCli(
     !pipelinesRootExists || options.force === true,
     `Folder already exists: ${pipelinesRoot}. Pass --force to replace it.`,
+    { hint: { disabled: true } },
   );
   if (pipelinesRootExists) await rm(pipelinesRoot, { recursive: true, force: true });
 
@@ -725,7 +756,7 @@ export async function projectStatus(
   options: PlanProjectOptions,
 ): Promise<ProjectStatusResult> {
   const projectId = options.projectId;
-  assert(projectId, MISSING_PROJECT_ID_MESSAGE);
+  assertProjectSelected(projectId);
   const live = await client.projects.get({ projectId });
   const inspection = await inspectProject(client, { ...options, listAllSecrets: true });
   const pending = inspection.changes.length;
@@ -751,24 +782,28 @@ export async function applyProject(
   options: ApplyProjectOptions,
 ): Promise<ApplyProjectResult> {
   const inspection = await inspectProject(client, options);
-  assert(
+  assertCli(
     inspection.removedPipelines.length === 0,
     `Refusing to delete pipelines absent from source: ${inspection.removedPipelines.join(", ")}.`,
+    { hint: { description: "Restore the pipeline in source, or run toloka project untrack pipeline <name> to stop managing it." } },
   );
-  assert(
+  assertCli(
     inspection.removedDatasets.length === 0,
     `Refusing to delete datasets absent from source: ${inspection.removedDatasets.join(", ")}. Dataset items are never deleted.`,
+    { hint: { description: "Restore the dataset in source, or run toloka project untrack dataset <name> to stop managing it." } },
   );
-  assert(
+  assertCli(
     inspection.missingSecrets.length === 0,
     `Required secrets are missing: ${inspection.missingSecrets.join(", ")}. Run toloka secret set <name> before apply.`,
+    { hint: { disabled: true } },
   );
   const conflictingFields = inspection.datasets.flatMap((dataset) =>
     dataset.conflictingFields.map((field) => `${dataset.name}.${field.name}`),
   );
-  assert(
+  assertCli(
     conflictingFields.length === 0,
     `Dataset field schemas conflict with source: ${conflictingFields.join(", ")}. Existing fields are never rewritten.`,
+    { hint: { description: "Add the changed columns under new field names, or create a new dataset for the new schema." } },
   );
 
   let writes = 0;
@@ -798,9 +833,10 @@ export async function applyProject(
   const pipelineIds = new Map<string, string>();
   for (const pipelineInspection of inspection.pipelines) {
     const datasetId = datasetIds.get(pipelineInspection.source.definition.dataset);
-    assert(
+    assertCli(
       datasetId,
       `Dataset ${pipelineInspection.source.definition.dataset} has no resolved ID.`,
+      { hint: REPORT_HINT },
     );
     const desiredGraph = resolvePipelineDefinition(pipelineInspection.source.definition, {
       datasetId,
@@ -819,7 +855,11 @@ export async function applyProject(
     pipelineIds.set(pipelineInspection.source.sourceDirectory, pipelineInspection.pipeline.id);
     if (pipelineInspection.graphChanges.length === 0) continue;
     const snapshot = pipelineInspection.snapshot;
-    assert(snapshot, `Pipeline ${pipelineInspection.pipeline.id} has no graph snapshot.`);
+    assertCli(
+      snapshot,
+      `Pipeline ${pipelineInspection.pipeline.id} has no graph snapshot.`,
+      { hint: REPORT_HINT },
+    );
     await client.pipelines.replaceGraph({
       pipelineId: pipelineInspection.pipeline.id,
       graph: graphWithLiveState(desiredGraph, snapshot.graph),
@@ -833,14 +873,18 @@ export async function applyProject(
     pipelines: Object.fromEntries(
       inspection.source.pipelines.map((pipeline) => {
         const pipelineId = pipelineIds.get(pipeline.sourceDirectory);
-        assert(pipelineId, `Pipeline ${pipeline.sourceDirectory} has no resolved ID.`);
+        assertCli(
+          pipelineId,
+          `Pipeline ${pipeline.sourceDirectory} has no resolved ID.`,
+          { hint: REPORT_HINT },
+        );
         return [pipeline.sourceDirectory, { pipelineId }];
       }),
     ),
     datasets: Object.fromEntries(
       inspection.datasets.map((dataset) => {
         const datasetId = datasetIds.get(dataset.name);
-        assert(datasetId, `Dataset ${dataset.name} has no resolved ID.`);
+        assertCli(datasetId, `Dataset ${dataset.name} has no resolved ID.`, { hint: REPORT_HINT });
         return [dataset.name, { datasetId }];
       }),
     ),
@@ -957,8 +1001,16 @@ export async function validateProject(
   const lines = results.flatMap((result) => {
     if (result.skipped !== undefined)
       return [`- ${result.sourceDirectory}: skipped (${result.skipped})`];
-    assert(result.report, `Pipeline ${result.sourceDirectory} is missing a validation report`);
-    assert(result.status, `Pipeline ${result.sourceDirectory} is missing a validation status`);
+    assertCli(
+      result.report,
+      `Pipeline ${result.sourceDirectory} is missing a validation report`,
+      { hint: REPORT_HINT },
+    );
+    assertCli(
+      result.status,
+      `Pipeline ${result.sourceDirectory} is missing a validation status`,
+      { hint: REPORT_HINT },
+    );
     const header = `- ${result.sourceDirectory}: ${result.status.replace("_", "-")}`;
     return [header, ...formatValidationIssues(result.report)];
   });

package/src/cli/report.ts

@@ -1,9 +1,9 @@
-import { assert } from "es-toolkit";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, open, type FileHandle } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import type { CliAnalytics } from "./analytics";
+import { assertCli, TolokaCliError } from "./cli-error";
 
 export type IssueReportAuthor = "human" | "agent";
 
@@ -31,9 +31,10 @@ const assertNoSymlinkParents = async (absolutePath: string, sourceRoot: string):
   for (let index = 1; index < segments.length; index += 1) {
     const directory = join(sourceRoot, ...segments.slice(0, index));
     const stats = await lstat(directory);
-    assert(
+    assertCli(
       !stats.isSymbolicLink(),
       `Report file ${absolutePath} is inside the symbolic link ${directory}; select a path that does not traverse symbolic links.`,
+      { hint: { disabled: true } },
     );
   }
 };
@@ -49,20 +50,30 @@ const openReportFile = async (
   try {
     handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
   } catch (error) {
-    assert(
+    assertCli(
       !(error instanceof Error && "code" in error && error.code === "ELOOP"),
       `Report file ${absolutePath} is a symbolic link; select the file it points to directly.`,
+      { hint: { disabled: true } },
     );
     throw error;
   }
 
   try {
     const stats = await handle.stat();
-    assert(stats.isFile(), `Report file ${absolutePath} is not a regular file.`);
-    assert(stats.size > 0, `Report file ${absolutePath} is empty.`);
-    assert(
+    assertCli(
+      stats.isFile(),
+      `Report file ${absolutePath} is not a regular file.`,
+      { hint: { description: "Pass the path of a Markdown or text file." } },
+    );
+    assertCli(
+      stats.size > 0,
+      `Report file ${absolutePath} is empty.`,
+      { hint: { description: "Write the report first; the toloka-report-issue skill describes the format." } },
+    );
+    assertCli(
       stats.size <= ISSUE_REPORT_MAX_BYTES,
       `Report file ${absolutePath} is ${stats.size} bytes; the limit is 256 KiB.`,
+      { hint: { description: "Trim the report to under 256 KiB, for example by shortening logs." } },
     );
     return { handle, absolutePath, size: stats.size };
   } catch (error) {
@@ -75,14 +86,17 @@ const readReportText = async (path: string, sourceRoot: string, cwd: string): Pr
   const opened = await openReportFile(path, sourceRoot, cwd);
   try {
     const bytes = await opened.handle.readFile();
-    assert(
+    assertCli(
       bytes.byteLength === opened.size,
       `${opened.absolutePath} changed while it was being read.`,
+      { hint: { description: "Re-run toloka report once the file is no longer being written." } },
     );
     try {
       return REPORT_DECODER.decode(bytes);
     } catch {
-      throw new Error(`Report file ${opened.absolutePath} is not valid UTF-8.`);
+      throw new TolokaCliError(`Report file ${opened.absolutePath} is not valid UTF-8.`, {
+        hint: { description: "Save the report as UTF-8 text." },
+      });
     }
   } finally {
     await opened.handle.close();
@@ -107,9 +121,10 @@ export async function submitIssueReport(options: {
   readonly io: IssueReportIo;
 }): Promise<number> {
   const { analytics, io } = options;
-  assert(
+  assertCli(
     analytics.issueReportingEnabled,
     "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.",
+    { hint: { disabled: true } },
   );
   const reportText = await readReportText(options.path, options.sourceRoot, options.cwd);
   io.stdout("Issue report preview:");

package/src/cli/runs.ts

@@ -1,9 +1,9 @@
 import select from "@inquirer/select";
-import { assert } from "es-toolkit";
 import type { Pipeline, PotatoClient } from "../client";
 import { PotatoApiError } from "../errors";
 import type { TolokaState } from "../state";
 import type { RunItem, RunJob } from "../index";
+import { assertCli } from "./cli-error";
 
 export type PipelineRef = {
   readonly pipelineId: string;
@@ -131,10 +131,18 @@ const uniqueMatch = (
   ambiguous: string,
   unknown: string,
 ): PipelineRef | undefined => {
-  assert(matches.length <= 1, ambiguous);
+  assertCli(
+    matches.length <= 1,
+    ambiguous,
+    { hint: { description: "Pass the pipeline id shown by toloka pipeline list instead of the name." } },
+  );
   if (matches.length !== 1) return undefined;
   const [ref] = matches;
-  assert(ref, unknown);
+  assertCli(
+    ref,
+    unknown,
+    { hint: { description: "Run toloka pipeline list to see the pipelines of this project." } },
+  );
   return ref;
 };
 
@@ -174,7 +182,11 @@ const resolveToken = (token: string, live: readonly PipelineRef[]): PipelineRef
   );
   if (basename !== undefined) return basename;
 
-  assert(false, unknown);
+  assertCli(
+    false,
+    unknown,
+    { hint: { description: "Run toloka pipeline list to see the pipelines of this project." } },
+  );
 };
 
 export async function resolvePipelineRef(options: {
@@ -188,7 +200,11 @@ export async function resolvePipelineRef(options: {
 
   if (options.pipeline !== undefined) return resolveToken(options.pipeline, live);
 
-  assert(live.length > 0, "This project has no pipelines.");
+  assertCli(
+    live.length > 0,
+    "This project has no pipelines.",
+    { hint: { description: "Run toloka apply to create the pipelines declared in source." } },
+  );
 
   if (live.length > 1 && options.select !== undefined) {
     const chosen = await options.select(
@@ -199,13 +215,22 @@ export async function resolvePipelineRef(options: {
 
   if (live.length === 1) {
     const [only] = live;
-    assert(only, "This project has no pipelines.");
-    assert(false, `Pass a pipeline name. This project has: ${formatPipelineChoice(only)}.`);
+    assertCli(
+      only,
+      "This project has no pipelines.",
+      { hint: { description: "Run toloka apply to create the pipelines declared in source." } },
+    );
+    assertCli(
+      false,
+      `Pass a pipeline name. This project has: ${formatPipelineChoice(only)}.`,
+      { hint: { disabled: true } },
+    );
   }
 
-  assert(
+  assertCli(
     false,
     `This project tracks several pipelines, so name one: ${live.map(formatPipelineChoice).join(", ")}.`,
+    { hint: { disabled: true } },
   );
 }
 

package/src/cli/settings.ts

@@ -3,6 +3,8 @@ import { join } from "node:path";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
 import type { CliEnvironment } from "./credentials";
 import { configDirectory, preparePrivateFilePath } from "./credentials";
+import { TolokaCliError } from "./cli-error";
+import type { TolokaCliErrorOptions } from "./cli-error";
 
 export const AUTO_UPDATE_SETTING = "auto-update";
 
@@ -14,8 +16,8 @@ export const DEFAULT_CLI_SETTINGS: CliSettings = {
   autoUpdate: true,
 };
 
-export class SettingsError extends Error {
-  constructor(message: string, options?: { readonly cause?: unknown }) {
+export class SettingsError extends TolokaCliError {
+  constructor(message: string, options: TolokaCliErrorOptions) {
     super(message, options);
     this.name = "SettingsError";
   }
@@ -59,7 +61,9 @@ export async function writeCliSettings(
 export const parseBooleanSetting = (value: string): boolean => {
   if (isTruthyFlag(value)) return true;
   if (isFalseyFlag(value)) return false;
-  throw new SettingsError(`Expected a boolean (true or false), got ${JSON.stringify(value)}.`);
+  throw new SettingsError(`Expected a boolean (true or false), got ${JSON.stringify(value)}.`, {
+    hint: { description: "Run toloka config set auto-update true or false." },
+  });
 };
 
 export const formatCliSettings = (settings: CliSettings): string =>
@@ -71,7 +75,9 @@ export const getCliSetting = (
 ): { readonly output: string } => {
   if (name === undefined || name.length === 0) return { output: formatCliSettings(settings) };
   if (name !== AUTO_UPDATE_SETTING) {
-    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`);
+    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`, {
+      hint: { disabled: true },
+    });
   }
   return { output: String(settings.autoUpdate) };
 };
@@ -82,7 +88,9 @@ export async function setCliSetting(
   value: string,
 ): Promise<{ readonly output: string; readonly settings: CliSettings }> {
   if (name !== AUTO_UPDATE_SETTING) {
-    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`);
+    throw new SettingsError(`Unknown setting "${name}". Known settings: ${AUTO_UPDATE_SETTING}.`, {
+      hint: { disabled: true },
+    });
   }
   const settings = { autoUpdate: parseBooleanSetting(value) };
   await writeCliSettings(settings, environment);

package/src/cli/skill.ts

@@ -1,10 +1,10 @@
-import { assert } from "es-toolkit";
 import { createHash } from "node:crypto";
 import { copyFile, mkdir, mkdtemp, readFile, realpath, rename, rm, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { assertSafeDestination, entryStats, hasErrorCode } from "./file-system";
 import { formatCliError } from "./format-error";
 import { releaseChannelFor, SDK_PACKAGE_NAME, SDK_VERSION } from "./sdk-version";
+import { assertCli, REINSTALL_HINT, TolokaCliError } from "./cli-error";
 
 export const SKILL_CATALOG_MANIFEST = "catalog.json";
 export const SKILL_INSTALL_ROOT = ".agents/skills";
@@ -76,31 +76,51 @@ const isSafeRelativePath = (path: string) =>
   path.split("/").every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
 
 const parseDescriptor = (value: unknown, invalid: (detail: string) => string): SkillDescriptor => {
-  assert(isRecord(value), invalid("every skill must be an object."));
+  assertCli(isRecord(value), invalid("every skill must be an object."), { hint: REINSTALL_HINT });
   const { id, name, description, tags, version, digest, files } = value;
-  assert(
+  assertCli(
     isSafeSkillId(id),
     invalid(
       `skill id ${JSON.stringify(id)} must be at most ${MAX_SKILL_ID_LENGTH} lowercase letters, digits, and single hyphens.`,
     ),
+    { hint: REINSTALL_HINT },
   );
-  assert(isNonEmptyString(name), invalid(`skill ${id} needs a name.`));
-  assert(isNonEmptyString(description), invalid(`skill ${id} needs a description.`));
-  assert(isStringArray(tags), invalid(`skill ${id} tags must be strings.`));
-  assert(isNonEmptyString(version), invalid(`skill ${id} needs a version.`));
-  assert(
+  assertCli(isNonEmptyString(name), invalid(`skill ${id} needs a name.`), { hint: REINSTALL_HINT });
+  assertCli(
+    isNonEmptyString(description),
+    invalid(`skill ${id} needs a description.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
+    isStringArray(tags),
+    invalid(`skill ${id} tags must be strings.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
+    isNonEmptyString(version),
+    invalid(`skill ${id} needs a version.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
     typeof digest === "string" && DIGEST_PATTERN.test(digest),
     invalid(`skill ${id} digest must be the sha256 hex digest of its files.`),
+    { hint: REINSTALL_HINT },
   );
-  assert(
+  assertCli(
     isStringArray(files) && files.includes(SKILL_ENTRY_POINT),
     invalid(`skill ${id} files must include ${SKILL_ENTRY_POINT}.`),
+    { hint: REINSTALL_HINT },
   );
-  assert(
+  assertCli(
     files.every(isSafeRelativePath),
     invalid(`skill ${id} files must be relative paths inside its directory.`),
+    { hint: REINSTALL_HINT },
+  );
+  assertCli(
+    new Set(files).size === files.length,
+    invalid(`skill ${id} lists a file more than once.`),
+    { hint: REINSTALL_HINT },
   );
-  assert(new Set(files).size === files.length, invalid(`skill ${id} lists a file more than once.`));
   return { id, name, description, tags, version, digest, files };
 };
 
@@ -108,7 +128,10 @@ const parseManifest = (source: string, manifestPath: string): unknown => {
   try {
     return JSON.parse(source);
   } catch (error) {
-    throw new Error(`Invalid skill catalog ${manifestPath}: ${formatCliError(error)}`);
+    throw new TolokaCliError(`Invalid skill catalog ${manifestPath}: ${formatCliError(error)}`, {
+      cause: error,
+      hint: REINSTALL_HINT,
+    });
   }
 };
 
@@ -140,9 +163,10 @@ export async function resolveBundledSkillCatalogRoot(
     entry === undefined
       ? "process.argv[1] names no runtime entry"
       : `none exists between ${entry} and the filesystem root`;
-  assert(
+  assertCli(
     workingDirectoryRoot !== undefined,
     `Cannot locate the bundled skill catalog. An installed @toloka-platform/sdk must ship ${SKILL_CATALOG_DIRECTORY}/${SKILL_CATALOG_MANIFEST} in a directory above its runtime entry, but ${searched}, and no ${SKILL_CATALOG_DIRECTORY}/${SKILL_CATALOG_MANIFEST} exists above ${process.cwd()} either. Reinstall @toloka-platform/sdk.`,
+    { hint: { disabled: true } },
   );
   return workingDirectoryRoot;
 }
@@ -154,23 +178,30 @@ export async function loadSkillCatalog(catalogRoot: string): Promise<SkillCatalo
   const manifestPath = join(catalogRoot, SKILL_CATALOG_MANIFEST);
   const invalid = (detail: string) => `Invalid skill catalog ${manifestPath}: ${detail}`;
   const { size } = await stat(manifestPath);
-  assert(
+  assertCli(
     size <= MAX_MANIFEST_BYTES,
     invalid(`the manifest is ${size} bytes; the limit is ${MAX_MANIFEST_BYTES} bytes.`),
+    { hint: REINSTALL_HINT },
   );
   const manifest = parseManifest(await readFile(manifestPath, "utf8"), manifestPath);
-  assert(
+  assertCli(
     isRecord(manifest) && Array.isArray(manifest.skills),
     invalid("expected an object with a skills array."),
+    { hint: REINSTALL_HINT },
   );
-  assert(
+  assertCli(
     manifest.skills.length <= MAX_SKILL_COUNT,
     invalid(`${manifest.skills.length} skills exceed the limit of ${MAX_SKILL_COUNT}.`),
+    { hint: REINSTALL_HINT },
   );
   const skills = manifest.skills.map((skill) => parseDescriptor(skill, invalid));
   const ids = new Set<string>();
   for (const skill of skills) {
-    assert(!ids.has(skill.id), invalid(`skill id ${skill.id} appears more than once.`));
+    assertCli(
+      !ids.has(skill.id),
+      invalid(`skill id ${skill.id} appears more than once.`),
+      { hint: REINSTALL_HINT },
+    );
     ids.add(skill.id);
   }
   return { root: catalogRoot, manifestPath, skills };
@@ -253,9 +284,14 @@ const swapDirectories = async (
     try {
       await renameEntry(backup, destination);
     } catch (restoreError) {
-      throw new Error(
+      throw new TolokaCliError(
         `Failed to replace ${destination}; the previous version is preserved at ${backup}. ${formatCliError(restoreError)}`,
-        { cause: error },
+        {
+          cause: error,
+          hint: {
+            description: `Move ${backup} back to ${destination} by hand, then re-run toloka skill install <skill-id> --force.`,
+          },
+        },
       );
     }
     throw error;
@@ -271,17 +307,19 @@ export async function installSkill({
   rename: renameEntry = rename,
 }: InstallSkillOptions): Promise<InstalledSkill> {
   const skill = catalog.skills.find((candidate) => candidate.id === skillId);
-  assert(
+  assertCli(
     skill,
     `Skill ${JSON.stringify(skillId)} is not in the catalog bundled with ${SDK_PACKAGE_NAME} ${SDK_VERSION}. Run \`toloka skill list\` to see the available skills; a newer release may ship it (${UPGRADE_HINT}).`,
+    { hint: { disabled: true } },
   );
   const relativeDestination = `${SKILL_INSTALL_ROOT}/${skill.id}`;
   await assertSafeDestination(sourceRoot, relativeDestination);
   const destination = join(sourceRoot, relativeDestination);
   const existing = await entryStats(destination);
-  assert(
+  assertCli(
     existing === undefined || force,
     `${relativeDestination} already exists. Re-run with --force to replace it with the catalog version of ${skill.id}.`,
+    { hint: { disabled: true } },
   );
 
   const skillsRoot = dirname(destination);
@@ -293,9 +331,10 @@ export async function installSkill({
       await mkdir(dirname(target), { recursive: true });
       await copyFile(join(catalog.root, skill.id, path), target);
     }
-    assert(
+    assertCli(
       (await computeSkillDigest(temporary, skill.files)) === skill.digest,
       `Skill ${skill.id} failed its digest check: the packaged files do not match the catalog digest ${skill.digest}. Nothing was installed.`,
+      { hint: REINSTALL_HINT },
     );
     if (existing === undefined) {
       await renameEntry(temporary, destination);