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

package/src/cli/format-error.ts

@@ -1,4 +1,5 @@
 import { PotatoApiError } from "../errors";
+import { formatHint, TolokaCliError } from "./cli-error";
 
 export const apiErrorDetails = (error: PotatoApiError): string | undefined => {
   const details =
@@ -10,10 +11,52 @@ export const apiErrorDetails = (error: PotatoApiError): string | undefined => {
   return details === undefined || details.length === 0 ? undefined : details;
 };
 
+const apiErrorHint = (error: PotatoApiError): string | undefined => {
+  if (error.code === "wait_timeout") {
+    return "Hint: The job is still running. Check it later with its status command; commands that accept --timeout can wait longer.";
+  }
+  if (error.status === 401 || error.status === 403) {
+    return "Hint: Run toloka whoami to see which key and platform are in use; toloka login stores a new key.";
+  }
+  if (error.status === 404) {
+    return "Hint: Check the id against toloka project current and the matching list command; ids belong to one project on one platform.";
+  }
+  if (error.status === 429) {
+    return "Hint: The platform is rate limiting this key; wait a moment and retry.";
+  }
+  if (error.status !== undefined && error.status >= 500) {
+    return "Hint: The platform failed to handle the request. Retry; if it keeps failing, write a report as the toloka-report-issue skill describes and send it with toloka report <report.md>.";
+  }
+  return undefined;
+};
+
+const joinLines = (lines: ReadonlyArray<string | undefined>): string =>
+  lines.filter((line) => line !== undefined && line.length > 0).join("\n");
+
+export const findPotatoApiError = (error: unknown): PotatoApiError | undefined => {
+  if (error instanceof PotatoApiError) return error;
+  if (error instanceof AggregateError) {
+    for (const nested of error.errors) {
+      const apiError = findPotatoApiError(nested);
+      if (apiError !== undefined) return apiError;
+    }
+  }
+  return error instanceof Error ? findPotatoApiError(error.cause) : undefined;
+};
+
 export const formatCliError = (error: unknown): string => {
+  if (error instanceof TolokaCliError) {
+    const cause = findPotatoApiError(error.cause);
+    const causeLines =
+      cause === undefined
+        ? []
+        : cause.message === error.message
+          ? [apiErrorDetails(cause)]
+          : [cause.message, apiErrorDetails(cause)];
+    return joinLines([error.message, ...causeLines, formatHint(error.hint)]);
+  }
   if (error instanceof PotatoApiError) {
-    const details = apiErrorDetails(error);
-    return details === undefined ? error.message : `${error.message}\n${details}`;
+    return joinLines([error.message, apiErrorDetails(error), apiErrorHint(error)]);
   }
   return error instanceof Error ? error.message : String(error);
 };

package/src/cli/init.ts

@@ -1,10 +1,10 @@
-import { assert } from "es-toolkit";
 import { lstat, mkdir, readdir, readFile, realpath, rm, rmdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { readTolokaState, writeTolokaState } from "../state";
 import { assertSafeDestination, entryStats, isMissingFileError } from "./file-system";
 import { SDK_PACKAGE_NAME, SDK_VERSION } from "./sdk-version";
 import { SKILL_ENTRY_POINT, SKILL_INSTALL_ROOT } from "./skill";
+import { assertCli } from "./cli-error";
 
 const BOOTSTRAP_NAME = "toloka-bootstrap";
 const CLAUDE_POINTER_PATH = `.claude/skills/${BOOTSTRAP_NAME}/SKILL.md`;
@@ -106,14 +106,16 @@ const locateBlock = (source: string, markers: BlockMarkers, path: string) => {
   const beginIndex = source.indexOf(markers.begin);
   const endIndex = source.indexOf(markers.end);
   if (beginIndex === -1 && endIndex === -1) return undefined;
-  assert(
+  assertCli(
     beginIndex !== -1 && endIndex !== -1 && beginIndex < endIndex,
     `Malformed Toloka block in ${path}: expected one ${markers.begin} followed by one ${markers.end}. Repair the file by hand, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
-  assert(
+  assertCli(
     !source.includes(markers.begin, beginIndex + markers.begin.length) &&
       !source.includes(markers.end, endIndex + markers.end.length),
     `Multiple Toloka blocks in ${path}: keep exactly one ${markers.begin} ... ${markers.end} block, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
   return { beginIndex, endIndex: endIndex + markers.end.length };
 };
@@ -121,9 +123,10 @@ const locateBlock = (source: string, markers: BlockMarkers, path: string) => {
 const mergeBootstrap = (source: string, path: string) => {
   const current = locateBlock(source, CURRENT_BLOCK, path);
   const legacy = locateBlock(source, LEGACY_BLOCK, path);
-  assert(
+  assertCli(
     current === undefined || legacy === undefined,
     `Ambiguous Toloka blocks in ${path}: both ${CURRENT_BLOCK.begin} and ${LEGACY_BLOCK.begin} are present. Keep one, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
   const lineEnding = source.includes("\r\n") ? "\r\n" : "\n";
   const block = BOOTSTRAP_BLOCK.replaceAll("\n", lineEnding);
@@ -146,9 +149,10 @@ const hasSdkDependency = async (targetDirectory: string) => {
   const source = await readOptionalFile(join(targetDirectory, "package.json"));
   if (source === undefined) return false;
   const manifest: unknown = JSON.parse(source);
-  assert(
+  assertCli(
     typeof manifest === "object" && manifest !== null,
     "package.json must contain a JSON object.",
+    { hint: { description: "Fix package.json in the source root, then re-run toloka init." } },
   );
   return ["dependencies", "devDependencies"].some((key) => {
     const dependencies = Reflect.get(manifest, key);
@@ -170,9 +174,10 @@ const writeIfChanged = async (path: string, source: string) => {
 const assertRefreshablePointer = async (targetRoot: string, relativePath: string) => {
   const path = join(targetRoot, relativePath);
   const existing = await readOptionalFile(path);
-  assert(
+  assertCli(
     existing === undefined || isGenerated(existing),
     `Refusing to overwrite ${path}: it carries no \`<!-- toloka:sdk-version ... -->\` marker, so it is not a pointer generated by ${SDK_PACKAGE_NAME}. Move it aside, then re-run \`toloka init\`.`,
+    { hint: { disabled: true } },
   );
 };
 
@@ -215,9 +220,10 @@ const bindCheckout = async (
 ): Promise<string | undefined> => {
   if (projectId === undefined) return undefined;
   const existing = await readTolokaState(targetRoot);
-  assert(
+  assertCli(
     existing === undefined || existing.projectId === projectId,
     `This directory is already bound to ${existing?.projectId}.`,
+    { hint: { description: "Run toloka init without --project-id to keep the current binding, or remove toloka.json to bind another project." } },
   );
   if (existing !== undefined) return undefined;
   await writeTolokaState(targetRoot, { projectId, pipelines: {}, datasets: {} });

package/src/cli/models.ts

@@ -5,9 +5,9 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
-import { assert } from "es-toolkit";
 
 import type { BaseModel, BaseModelId, Model, ModelVersion, PotatoClient } from "../client";
+import { assertCli, REPORT_HINT, RETRY_OR_REPORT_HINT } from "./cli-error";
 
 type ModelApi = Pick<PotatoClient, "baseModels" | "models">;
 type ModelIo = { readonly stdout: (text: string) => void };
@@ -46,6 +46,7 @@ const formatBaseModel = (model: BaseModel): string =>
     ["Provider", model.provider],
     ["Upstream model", model.upstreamModel],
     ["Upstream revision", model.upstreamRevision],
+    ["Upstream snapshot", model.upstreamUrl],
   ]);
 
 const formatModel = (model: Model): string =>
@@ -62,7 +63,11 @@ const formatModel = (model: Model): string =>
 
 export const parseBaseModelId = (value: string): BaseModelId => {
   const modelId = BASE_MODEL_IDS.find((candidate) => candidate === value);
-  assert(modelId, `Unknown base model ${value}.`);
+  assertCli(
+    modelId,
+    `Unknown base model ${value}.`,
+    { hint: { description: "Run toloka base-model list to see the catalog." } },
+  );
   return modelId;
 };
 
@@ -76,7 +81,11 @@ const resolveModel = async (
   for await (const model of client.models.listAll({ projectId, limit: 100 })) {
     if (model.name === nameOrId) matches.push(model);
   }
-  assert(matches.length === 1, `Model ${nameOrId} was not found or is ambiguous.`);
+  assertCli(
+    matches.length === 1,
+    `Model ${nameOrId} was not found or is ambiguous.`,
+    { hint: { description: "Run toloka model list and pass the model id (mdl.…)." } },
+  );
   return matches[0]!;
 };
 
@@ -87,8 +96,16 @@ const resolveModelVersion = async (
 ): Promise<ModelVersion> => {
   if (nameOrId.startsWith("mdv.")) return client.models.getVersion({ modelVersionId: nameOrId });
   const separator = nameOrId.lastIndexOf("@");
-  assert(separator > 0, `Model Version ${nameOrId} was not found. Use mdv.<id> or Model@name.`);
-  assert(projectId, "Select a project to resolve Model Version names.");
+  assertCli(
+    separator > 0,
+    `Model Version ${nameOrId} was not found. Use mdv.<id> or Model@name.`,
+    { hint: { disabled: true } },
+  );
+  assertCli(
+    projectId,
+    "Select a project to resolve Model Version names.",
+    { hint: { description: "Select a project with toloka project add or toloka project switch, or pass the version id (mdv.…) directly." } },
+  );
   const model = await resolveModel(client, projectId, nameOrId.slice(0, separator));
   const versionName = nameOrId.slice(separator + 1);
   const matches: ModelVersion[] = [];
@@ -99,7 +116,11 @@ const resolveModelVersion = async (
   })) {
     if (version.name === versionName) matches.push(version);
   }
-  assert(matches.length === 1, `Model Version ${nameOrId} was not found or is ambiguous.`);
+  assertCli(
+    matches.length === 1,
+    `Model Version ${nameOrId} was not found or is ambiguous.`,
+    { hint: { description: "Run toloka model versions <model> and pass the version id (mdv.…)." } },
+  );
   return matches[0]!;
 };
 
@@ -116,12 +137,14 @@ export const listBaseModels = async (
     models.length === 0
       ? "No base models found."
       : formatTable([
-          ["ID", "NAME", "PROVIDER", "UPSTREAM MODEL"],
+          ["ID", "NAME", "PROVIDER", "UPSTREAM MODEL", "REVISION", "UPSTREAM SNAPSHOT"],
           ...models.map((model) => [
             model.id,
             model.displayName,
             model.provider,
             model.upstreamModel,
+            model.upstreamRevision.slice(0, 12),
+            model.upstreamUrl,
           ]),
         ]),
   );
@@ -238,25 +261,31 @@ export const downloadModelVersion = async (
   for (const file of descriptor.files) {
     const target = resolve(root, file.path);
     const relativeTarget = relative(root, target);
-    assert(
+    assertCli(
       relativeTarget !== "" &&
         relativeTarget !== ".." &&
         !relativeTarget.startsWith(`..${sep}`) &&
         !isAbsolute(relativeTarget),
       `Invalid Model Version file path: ${file.path}`,
+      { hint: REPORT_HINT },
     );
     let parent = root;
     for (const segment of file.path.split("/").slice(0, -1)) {
       parent = resolve(parent, segment);
       await mkdir(parent, { recursive: true });
       const realParent = await realpath(parent);
-      assert(
+      assertCli(
         realParent === realRoot || realParent.startsWith(`${realRoot}${sep}`),
         `Invalid Model Version file path: ${file.path}`,
+        { hint: REPORT_HINT },
       );
     }
     const response = await fetch(file.url, { redirect: "error" });
-    assert(response.ok && response.body, `Failed to download Model Version file ${file.path}.`);
+    assertCli(
+      response.ok && response.body,
+      `Failed to download Model Version file ${file.path}.`,
+      { hint: RETRY_OR_REPORT_HINT },
+    );
     const hash = createHash("sha256");
     let byteSize = 0;
     const verify = new Transform({
@@ -274,13 +303,15 @@ export const downloadModelVersion = async (
         0o600,
       );
       await pipeline(Readable.from(response.body), verify, handle.createWriteStream());
-      assert(
+      assertCli(
         byteSize === file.byteSize,
         `Downloaded Model Version file ${file.path} has an unexpected size.`,
+        { hint: { description: "Delete the partial download and retry; if it keeps failing, run toloka report." } },
       );
-      assert(
+      assertCli(
         hash.digest("hex") === file.sha256,
         `Downloaded Model Version file ${file.path} has an invalid hash.`,
+        { hint: { description: "Delete the partial download and retry; if it keeps failing, run toloka report." } },
       );
       await rename(temporary, target);
     } catch (error) {

package/src/cli/program.ts

@@ -1,5 +1,5 @@
 import { Command, CommanderError } from "commander";
-import { createClient, type PotatoClient } from "../client";
+import type { PotatoClient } from "../client";
 import { commandNameFromArgv, createCliAnalytics } from "./analytics";
 import type { CliAnalytics, CliAnalyticsCommandOutcome } from "./analytics";
 import type { AutoUpdateHooks } from "./auto-update";
@@ -19,11 +19,9 @@ import { registerSourceCommands } from "./commands/source";
 import { registerStatusCommand } from "./commands/status";
 import { registerTrainingCommands } from "./commands/training";
 import { registerVersionCommand } from "./commands/version";
-import { resolveTolokaConfig, type TolokaEnvironment } from "./config";
-import { findCommandCredentials } from "./credentials";
+import type { TolokaEnvironment } from "./config";
 import {
   CREDENTIAL_PRECEDENCE,
-  resolveInternalUser,
   resolveSourceRoot,
   type CliIo,
   type CreatedProgram,
@@ -39,51 +37,6 @@ import { terminalIo } from "./terminal-io";
 export type { CliIo, CreatedProgram, ProgramContext } from "./context";
 export { terminalIo } from "./terminal-io";
 
-const argvFlag = (argv: readonly string[], flag: string): string | undefined => {
-  const index = argv.indexOf(flag);
-  if (index < 0) return undefined;
-  const value = argv[index + 1];
-  return value === undefined || value.startsWith("-") ? undefined : value;
-};
-
-const resolveInternalCommandAccess = async (
-  argv: readonly string[],
-  environment: TolokaEnvironment,
-  injectedClient: PotatoClient | undefined,
-): Promise<boolean | undefined> => {
-  const commandName = commandNameFromArgv(argv);
-  if (
-    commandName !== "help" &&
-    commandName !== "project create" &&
-    !commandName.startsWith("delivery-order")
-  ) {
-    return undefined;
-  }
-  if (injectedClient !== undefined) return resolveInternalUser(injectedClient);
-  try {
-    const apiKey = argvFlag(argv, "--api-key");
-    const baseUrl = argvFlag(argv, "--base-url");
-    const { found } = await findCommandCredentials(
-      environment,
-      apiKey ?? environment.TOLOKA_API_KEY,
-    );
-    const config = resolveTolokaConfig(
-      {
-        ...(apiKey === undefined ? {} : { apiKey }),
-        ...(baseUrl === undefined ? {} : { baseUrl }),
-      },
-      undefined,
-      environment,
-      found?.credentials,
-    );
-    return await resolveInternalUser(
-      createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl }),
-    );
-  } catch {
-    return undefined;
-  }
-};
-
 export function createProgram(context: ProgramContext): CreatedProgram {
   const program = new Command("toloka");
   const exitCode = { value: 0 };
@@ -137,7 +90,7 @@ export function createProgram(context: ProgramContext): CreatedProgram {
   registerConfigCommands(program, host);
   registerAuthCommands(program, host);
   registerProjectCommands(program, host);
-  if (context.internalUser === true) registerDeliveryOrderCommands(program, host);
+  registerDeliveryOrderCommands(program, host);
   registerSourceCommands(program, host);
   registerSecretCommands(program, host);
   registerModelCommands(program, host);
@@ -263,11 +216,7 @@ export async function runTolokaCli(
     ...(injectedClient === undefined ? {} : { injectedClient }),
     ...(runChecks === undefined ? {} : { runChecks }),
   };
-  const internalUser = await resolveInternalCommandAccess(argv, environment, injectedClient);
-  const { program, exitCode } = createProgram({
-    ...baseContext,
-    ...(internalUser === undefined ? {} : { internalUser }),
-  });
+  const { program, exitCode } = createProgram(baseContext);
   const startedAt = Date.now();
 
   try {

package/src/cli/project-context.ts

@@ -1,4 +1,4 @@
-import { assert } from "es-toolkit";
+import { PotatoApiError } from "../errors";
 import { readTolokaState, TOLOKA_STATE_FILENAME, writeTolokaState } from "../state";
 import type { TolokaState } from "../state";
 import type { AuthPrompt } from "./auth";
@@ -6,6 +6,8 @@ import type { TolokaCliFlags, TolokaEnvironment } from "./config";
 import { resolveInternalBaseUrl } from "./config";
 import { normalizeBaseUrl, requireStoredCredentials, writeStoredCredentials } from "./credentials";
 import type { CliEnvironment, StoredCredentials, StoredProjectAlias } from "./credentials";
+import { apiErrorDetails } from "./format-error";
+import { assertCli, TolokaCliError } from "./cli-error";
 
 type ProjectRecord = { readonly id: string; readonly name: string; readonly teamId: string };
 
@@ -24,20 +26,26 @@ export type ProjectGetApi = {
   };
 };
 
+export type AccountTeam = { readonly id: string; readonly writable: boolean; readonly internal?: boolean };
+
 export type ProjectCreateApi = {
+  readonly me: () => Promise<{ readonly teams?: readonly AccountTeam[] }>;
   readonly projects: {
     readonly create: (input: {
       readonly teamId: string;
       readonly name?: string;
       readonly deliveryOrderId?: string;
     }) => Promise<ProjectRecord>;
-    readonly listAll: (params?: object) => AsyncIterable<ProjectRecord>;
   };
 };
 
 export const MISSING_PROJECT_ID_MESSAGE =
   "Missing project ID. Pass --project-id, set TOLOKA_PROJECT_ID, use a bound toloka.json, run toloka project create for a new project, or run toloka project add for an existing project.";
 
+export function assertProjectSelected(projectId: string | undefined): asserts projectId is string {
+  assertCli(projectId, MISSING_PROJECT_ID_MESSAGE, { hint: { disabled: true } });
+}
+
 export const NO_PROJECT_SELECTED_MESSAGE =
   "No project selected. Run toloka project create for a new project, toloka project add for an existing project, or cd into a checkout.";
 
@@ -70,9 +78,10 @@ export type ProjectIo = {
 
 export const validateProjectAlias = (alias: string): string => {
   const trimmed = alias.trim();
-  assert(
+  assertCli(
     trimmed.length > 0 && ALIAS_PATTERN.test(trimmed),
     "Project alias must be non-empty and contain no / or whitespace.",
+    { hint: { description: "Use letters, digits, dashes, or underscores, for example my-project." } },
   );
   return trimmed;
 };
@@ -183,11 +192,16 @@ const assertStoredNetworkMatches = (
     firstNonEmpty(flags.baseUrl) ??
     firstNonEmpty(environment.TOLOKA_BASE_URL) ??
     resolveInternalBaseUrl(environment);
-  assert(flagOrEnvKey === undefined || flagOrEnvKey === stored.apiKey, NETWORK_MISMATCH_MESSAGE);
-  assert(
+  assertCli(
+    flagOrEnvKey === undefined || flagOrEnvKey === stored.apiKey,
+    NETWORK_MISMATCH_MESSAGE,
+    { hint: { disabled: true } },
+  );
+  assertCli(
     flagOrEnvBase === undefined ||
       normalizeBaseUrl(flagOrEnvBase) === normalizeBaseUrl(stored.baseUrl),
     NETWORK_MISMATCH_MESSAGE,
+    { hint: { disabled: true } },
   );
 };
 
@@ -214,9 +228,9 @@ const promptOrFail = async (
   question: string,
   missing: string,
 ): Promise<string> => {
-  assert(io?.prompt, missing);
+  assertCli(io?.prompt, missing, { hint: { disabled: true } });
   const value = (await io.prompt(question)).trim();
-  assert(value.length > 0, missing);
+  assertCli(value.length > 0, missing, { hint: { disabled: true } });
   return value;
 };
 
@@ -254,27 +268,37 @@ export async function untrackProjectResource(options: {
   readonly io: ProjectIo;
 }): Promise<{ readonly output: string }> {
   const state = await readTolokaState(options.sourceRoot);
-  assert(state, `No ${TOLOKA_STATE_FILENAME} found in ${options.sourceRoot}.`);
+  assertCli(
+    state,
+    `No ${TOLOKA_STATE_FILENAME} found in ${options.sourceRoot}.`,
+    { hint: { description: "Run toloka init in the source root, or cd into the checkout that holds toloka.json." } },
+  );
   const bindings = options.type === "pipeline" ? state.pipelines : state.datasets;
   const binding = bindings[options.name];
-  assert(
+  assertCli(
     binding,
     `${options.type === "pipeline" ? "Pipeline" : "Dataset"} ${options.name} is not tracked.`,
+    { hint: { description: "Open toloka.json to see the tracked pipelines and datasets." } },
   );
   const id = "pipelineId" in binding ? binding.pipelineId : binding.datasetId;
   const label = `${options.type} ${options.name} (${id})`;
 
   if (!options.confirm) {
-    assert(
+    assertCli(
       options.io.prompt,
       `Refusing to untrack ${label} without confirmation. Pass --confirm after reviewing ${TOLOKA_STATE_FILENAME}.`,
+      { hint: { disabled: true } },
     );
     const answer = (
       await options.io.prompt(`Untrack ${label}? The live resource will not be deleted. [y/N] `)
     )
       .trim()
       .toLowerCase();
-    assert(answer === "y" || answer === "yes", "Untrack canceled.");
+    assertCli(
+      answer === "y" || answer === "yes",
+      "Untrack canceled.",
+      { hint: { disabled: true } },
+    );
   }
 
   const remaining = Object.fromEntries(
@@ -319,9 +343,10 @@ export async function addProject(options: {
 
   const existing = ownProject(found.credentials.projects, alias);
 
-  assert(
+  assertCli(
     existing === undefined || existing.id === projectId,
     `Alias ${alias} already points at ${existing?.id}. Run toloka project remove ${alias} first.`,
+    { hint: { disabled: true } },
   );
 
   await options.afterPreflight?.();
@@ -346,7 +371,11 @@ export async function switchProject(options: {
   assertStoredNetworkMatches(options.flags ?? {}, options.environment, found.credentials);
   const alias = validateProjectAlias(options.alias);
   const project = ownProject(found.credentials.projects, alias);
-  assert(project, `Unknown project alias ${alias}.`);
+  assertCli(
+    project,
+    `Unknown project alias ${alias}.`,
+    { hint: { description: "Run toloka project add <alias> <project-id> to register it, or check the alias spelling." } },
+  );
 
   await writeRegistry({ ...found.credentials, current: alias }, options.environment);
   const output = `Using project ${project.id} as ${alias}.`;
@@ -367,7 +396,11 @@ export async function removeProject(options: {
     string,
     StoredProjectAlias
   >;
-  assert(ownProject(projects, alias), `Unknown project alias ${alias}.`);
+  assertCli(
+    ownProject(projects, alias),
+    `Unknown project alias ${alias}.`,
+    { hint: { description: "Run toloka project add <alias> <project-id> to register it, or check the alias spelling." } },
+  );
   delete projects[alias];
 
   const current = found.credentials.current === alias ? undefined : found.credentials.current;
@@ -401,25 +434,71 @@ export function currentProject(options: {
   return project === undefined ? { output } : { output, project };
 }
 
-const uniqueTeamId = (projects: ReadonlyArray<{ readonly teamId: string }>): string | undefined => {
-  const teams = [...new Set(projects.map((project) => project.teamId))];
-  return teams.length === 1 ? teams[0] : undefined;
-};
-
 const resolveTeamId = async (
   client: ProjectCreateApi,
   teamId: string | undefined,
 ): Promise<string> => {
   const explicit = firstNonEmpty(teamId);
   if (explicit !== undefined) return explicit;
-  const visible: Array<{ readonly teamId: string }> = [];
-  for await (const project of client.projects.listAll()) visible.push(project);
-  const inferred = uniqueTeamId(visible);
-  assert(
-    inferred,
-    "Missing team id. Pass --team-id. Visible projects do not share a single team, or none are visible.",
+  const { teams } = await client.me();
+  assertCli(
+    teams !== undefined,
+    "Missing team id. Pass --team-id. This platform does not report team memberships, so the team cannot be inferred.",
+    {
+      hint: {
+        description: "Copy the team id from the platform URL after /teams/, or update the platform.",
+      },
+    },
+  );
+  const writable = teams.filter((team) => team.writable).map((team) => team.id);
+  assertCli(
+    writable.length > 0,
+    "This account has no writable team, so it cannot create a project. Ask a team admin for write access or use toloka project add for an existing project.",
+    { hint: { disabled: true } },
   );
-  return inferred;
+  const [single] = writable;
+  assertCli(
+    single !== undefined && writable.length === 1,
+    `Missing team id. Pass --team-id. This account can create projects in several teams: ${writable.join(", ")}.`,
+    { hint: { disabled: true } },
+  );
+  return single;
+};
+
+const DELIVERY_ORDER_HINT =
+  "Internal teams attach a Sunday delivery order to every project: run toloka delivery-order list, then re-run toloka project create with --delivery-order-id <id>.";
+
+const DELIVERY_ORDER_NOT_ALLOWED_HINT =
+  "The owning team is not internal, so re-run toloka project create without --delivery-order-id. toloka whoami marks internal teams (internal) on its Teams: line.";
+
+const deliveryOrderHint = (
+  input: Parameters<ProjectCreateApi["projects"]["create"]>[0],
+  details: string,
+): string | undefined => {
+  if (!details.includes("deliveryOrderId")) return undefined;
+  if (input.deliveryOrderId === undefined && details.includes("required")) return DELIVERY_ORDER_HINT;
+  if (input.deliveryOrderId !== undefined && details.includes("only be set")) {
+    return DELIVERY_ORDER_NOT_ALLOWED_HINT;
+  }
+  return undefined;
+};
+
+const createLiveProject = async (
+  client: ProjectCreateApi,
+  input: Parameters<ProjectCreateApi["projects"]["create"]>[0],
+): Promise<ProjectRecord> => {
+  try {
+    return await client.projects.create(input);
+  } catch (error) {
+    if (error instanceof PotatoApiError && error.status === 400) {
+      const details = apiErrorDetails(error);
+      const hint = details === undefined ? undefined : deliveryOrderHint(input, details);
+      if (hint !== undefined) {
+        throw new TolokaCliError(error.message, { cause: error, hint: { description: hint } });
+      }
+    }
+    throw error;
+  }
 };
 
 const bindCheckout = async (
@@ -437,12 +516,17 @@ const bindCheckout = async (
       });
     } catch (error) {
       const reason = error instanceof Error ? error.message : String(error);
-      throw new Error(
+      throw new TolokaCliError(
         [
           `Created project ${created.id} as ${alias}.`,
           `Failed to write toloka.json: ${reason}`,
         ].join("\n"),
-        { cause: error },
+        {
+          cause: error,
+          hint: {
+            description: `The project exists. Make ${sourceRoot} writable, then run toloka --project-id ${created.id} init to bind it.`,
+          },
+        },
       );
     }
     return undefined;
@@ -474,9 +558,10 @@ export async function createProject(options: {
         "Missing project alias. Pass an alias or run this in a terminal.",
       )),
   );
-  assert(
+  assertCli(
     found.credentials.projects?.[alias] === undefined,
     `Alias ${alias} already exists. Run toloka project remove ${alias} first.`,
+    { hint: { disabled: true } },
   );
 
   const existingState =
@@ -486,7 +571,7 @@ export async function createProject(options: {
 
   const teamId = await resolveTeamId(options.client, options.teamId);
   const deliveryOrderId = firstNonEmpty(options.deliveryOrderId);
-  const created = await options.client.projects.create({
+  const created = await createLiveProject(options.client, {
     teamId,
     name: firstNonEmpty(options.name) ?? alias,
     ...(deliveryOrderId === undefined ? {} : { deliveryOrderId }),
@@ -499,12 +584,12 @@ export async function createProject(options: {
     );
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
-    throw new Error(
+    throw new TolokaCliError(
       [
         `Created ${created.id} but failed to update the local registry: ${reason}`,
         `Run: toloka project add ${alias} ${created.id}`,
       ].join("\n"),
-      { cause: error },
+      { cause: error, hint: { disabled: true } },
     );
   }