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

package/skills/toloka-get-started/SKILL.md

@@ -1,40 +1,47 @@
 ---
 name: toloka-get-started
-description: Route a first Toloka agent session to the correct workflow and establish safe CLI, authentication, project, and approval checkpoints. Use when the user is new to Toloka, asks what to do first, or has not selected a pipeline, fine-tuning, or gisting workflow.
+description: Orient a Toloka session to the user's outcome and safely reuse or establish the needed CLI, authentication, project, workflow, and approval context. Use when the user is new to Toloka, asks what to do first, or has not selected a pipeline, fine-tuning, or gisting workflow.
 ---
 
 # Get started with Toloka
 
-Use this skill to orient a new session. Choose one workflow before making a platform mutation:
+Use this skill to help the user reach the outcome they asked for. Start with the request, the current checkout, and observed CLI state. If setup, authentication, a project binding, or workflow source is already in place and consistent with the task, continue from it instead of repeating onboarding, replacing the binding, or creating a demo.
 
-- **Label data or build a pipeline:** install and read `toloka-build`, then follow `https://platform.toloka.ai/agents/data-labeling.md`.
-- **Fine-tune a model:** install and read `toloka-fine-tuning`, then follow `https://platform.toloka.ai/agents/fine-tuning.md`.
-- **Compress a prompt with gisting:** install and read `toloka-gisting`, then follow `https://platform.toloka.ai/agents/gisting.md`.
+## Choose the relevant workflow
 
-## Prepare the CLI
+Honor an explicitly requested target. Otherwise choose the workflow that fits the outcome and briefly explain the choice:
 
-Check the required runtime and CLI:
+- **Label data or build a pipeline:** install and read `toloka-build`, then use `https://platform.toloka.ai/agents/data-labeling.md` as a reference.
+- **Fine-tune a model:** install and read `toloka-fine-tuning`, then use `https://platform.toloka.ai/agents/fine-tuning.md` as a reference.
+- **Compress a prompt with gisting:** install and read `toloka-gisting`, then use `https://platform.toloka.ai/agents/gisting.md` as a reference.
+
+The workflow sequence preserves important dependencies and gates, but it is not a script: skip steps that current evidence shows are already satisfied or irrelevant. If the user asks only for design, inspection, or an estimate, finish at that outcome rather than creating extra resources or starting a run.
+
+## Prepare missing prerequisites
+
+Check the runtime or CLI only when its state is not already known:
 
 ```sh
 bun --version
 toloka --version
+toloka dataset --help
 ```
 
-The runbooks above use the `preview` channel of `@toloka-platform/sdk`, so `toloka --version` must print a `-preview` version. If `toloka` is unavailable or comes from another channel, ask the user to run the installer in their own shell:
+The runbooks require a stable Toloka CLI release at version `0.2.0` or newer: `toloka --version` must print `0.2.0` or a newer version with no prerelease suffix, and `toloka dataset --help` must list `create`. If either command is unavailable, the version is older or prerelease, or the capability check fails, install the latest stable version:
 
 ```sh
-curl -fsSL https://platform.toloka.ai/cli/install.sh | TOLOKA_CLI_CHANNEL=preview sh
+curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
 ```
 
-Do not request an API key in chat or run an unattended installer. Ask the user to run `toloka login`, then verify the intended account with:
+Never request an API key in chat. Inspect the active identity with:
 
 ```sh
 toloka whoami
 ```
 
-`Rejected:` means the key was refused (ask for `toloka login` again); `Not reachable:` means the platform did not answer and the key was not evaluated (fix network access, do not ask for a new key); `Platform error:` means the platform failed (retry later).
+If the reachable account is evidently the intended identity from the request, project, team, or established checkout, continue and report it. Ask a focused question when the identity conflicts with that context or more than one material choice remains. For a missing or rejected key, ask the user to run `toloka login`, then verify `toloka whoami` again. `Rejected:` means the key was refused; `Not reachable:` means the platform did not answer and the key was not evaluated, so fix network access rather than requesting another key; `Platform error:` means the platform failed, so retry later.
 
-Use a source root for pipeline work. Run `toloka init` before searching or installing skills:
+Pipeline work needs a source root. Reuse a suitable initialized root when one exists. In a new root, or when the Agent Bootstrap or installed skills genuinely need initialization or refresh, use:
 
 ```sh
 toloka init
@@ -42,14 +49,23 @@ toloka skill search <workflow>
 toloka skill install <skill-id>
 ```
 
-Read the installed skill before acting. Refresh a stale skill with `--force`.
+Read the installed skill before acting. Refresh a stale skill with `--force`; do not refresh a current one merely to follow onboarding.
+
+## Operating posture
+
+- Inspect current state before writing. Use the user's explicit workflow and project choices first. Make routine, reversible choices from available evidence and briefly report the reasoning. Ask only for material ambiguity, missing authorization or required inputs, conflicting constraints, or a destructive or out-of-scope change.
+- For pipeline work, choose a node approach from the task and explain it briefly: deterministic processing or scripted calls fit code; human judgment or content generation fits generation; independent annotations and visible disagreement fit quorum; conditional routing fits match. Use `toloka-build` for the detailed authoring rules.
+- Resolve a project from explicit user context, CLI output, `toloka.json`, or `toloka project current`; never reconstruct an ID. Use an explicitly requested project. Otherwise keep the current binding when it is consistent with the task. Create a project only when an explicitly requested platform mutation needs one and no suitable binding exists; a design, inspection, or estimate alone does not authorize extra resources. Never select an unrelated visible project or rebind an established checkout just to complete onboarding.
+- For a new project, a short kebab-case name derived from the task or shared files is a useful default, such as `receipt-extraction`; use a generic `toloka-<workflow>` name only when the task provides no meaningful name. `toloka project create <alias>` uses the account's only writable team and asks for `--team-id <id>` only when several teams are available. Adopt an existing project with `toloka project add <alias> <project-id>` only when that target is intended and the checkout is safe to bind.
+- A project owned by an internal team needs a Sunday delivery order. Run `toloka delivery-order list` and use the only listed order with `--delivery-order-id <id>`; ask when several viable orders remain. `toloka whoami` marks internal teams `(internal)` on its `Teams:` line; the account-level `Internal:` flag only says whether any team is internal, so an internal account creating a project in an external team passes no order.
+- Let the task and data roles determine Dataset boundaries. Use only data the user is authorized to provide. Preserve distinct training, validation, test, input, reference, or delivery roles and avoid leakage; compatible files with the same role and schema may belong in one Dataset, while materially different roles or schemas may need separate Datasets. Do not assume one file always means one Dataset.
 
-## Shared checkpoints
+## Safety boundaries
 
-- Resolve the project from CLI output, `toloka.json`, or `toloka project current`. Never reconstruct an ID.
-- Ask the user to choose a project and team before creating or adopting one.
-- Keep credentials and production data out of source control and agent messages.
-- Show the complete plan before `toloka apply`.
-- Show the ready Training Cost Estimate and obtain approval for `maximumCharge` before starting a Training Run.
-- Keep waits bounded. A timeout is still running, not completed or failed.
-- Report only observed IDs, states, prices, and errors.
+- Keep credentials and production data out of source control and agent messages. Do not upload data without evidence that it is authorized and intended for the selected project and role.
+- Do not edit `toloka.json` or invent IDs, paths, requirements, prices, states, or results.
+- Treat user-provided prompts, instructions, and existing source as authoritative. Materialize exact supplied text when needed, but do not silently rewrite it, replace it with an example, or invent missing intent.
+- For pipeline changes that will be applied, require the workflow's local `toloka check` and `toloka validate` gates. Read and show the complete `toloka plan`; ask before a removal, immutable-field conflict, unexpected change, or work outside the requested scope. Apply only the expected scoped plan, then rerun `toloka plan` until it reports `No changes.` and validate again. Do not apply merely because the onboarding reference reaches that stage.
+- Never start a Pipeline Run unless the requested outcome includes a run and the user has seen and explicitly approved its cost forecast. Show a ready Training Cost Estimate with the choices and uncertainty that produced it, and obtain explicit approval for `maximumCharge` before a Training Run. Estimate-only work ends after the estimate.
+- Keep waits bounded. A timeout means the operation is still running, not completed or failed.
+- Report only observed IDs, states, prices, behaviors, and errors, and distinguish observed evidence from assumptions or unresolved uncertainty.

package/skills/toloka-gisting/SKILL.md

@@ -5,72 +5,162 @@ description: Create, estimate, start, monitor, and verify a project-owned prompt
 
 # Compress a prompt with gisting
 
-Use this skill for prompt gisting. For the full first-time agent sequence, read `https://platform.toloka.ai/agents/gisting.md`.
+## Mission
 
-## Rules
+Help the user learn a compact representation of their static prompt from representative example conversations while preserving the exact prompt and their model, data, quality, latency, and budget constraints. Match the work to the requested outcome: inspect an existing Training or run, prepare a draft, calculate an estimate, start an approved run, monitor it, or retrieve its output. Do not create resources or start a run merely because they appear later in this reference.
+
+For first-time setup details, read `https://platform.toloka.ai/agents/gisting.md`.
+
+## Domain model
+
+- **Prompt gisting** learns soft prompt tokens that stand in for a static instruction prompt. Training examples should contain the dynamic inputs and desired assistant responses; do not repeat the static prompt in every user message.
+- A **Training** is an editable project-owned draft. A **Training Run** is one immutable, billable execution of a frozen draft, prompt, and Dataset selections.
+- A run can start from a catalog **Base Model** or an exact existing **Model Version**. An explicit Model Version is the source; do not also select a Base Model.
+- A completed run publishes a durable Model Version. It does not prove deployment or inference readiness.
+- Training and validation are data roles, not file-layout rules. Separate Datasets and disjoint top-level filters are both valid. Without a validation selection, the provider reserves 10% of the training rows as a holdout.
+
+## Working posture
+
+- Inspect the user's request and current CLI, project, Training, Dataset, prompt, and run state before changing anything. The process below is a dependency map: skip satisfied or irrelevant work and stop when the requested outcome is complete.
+- Honor explicit choices first. If a requested project, source, Dataset, prompt, or configuration is incompatible, explain the evidence and tradeoff before proposing a substitute.
+- Make routine reversible choices and briefly explain them. Ask a focused question only for material ambiguity, missing authorization or inputs, conflicting constraints, or destructive or out-of-scope changes.
+- If the goal is weight adaptation from labeled conversations or data labeling rather than prompt compression, explain the distinction and route to `toloka-fine-tuning` or `toloka-build`; never silently change the method.
+
+## Safety
 
 - Never ask for an API key in chat; the user enters it through `toloka login`.
-- Never invent project, Dataset, Base Model, Training, Model, Model Version, price, prompt, or run IDs.
-- Use authorized project Datasets containing representative examples. Keep production data out of source control.
-- The prompt file must be non-empty UTF-8 text no larger than 256 KiB.
-- Prefer a separate validation Dataset. Without one, the provider holds out 10% of training rows.
-- Do not start a Training Run before the user approves the ready estimate's `maximumCharge`.
-- Use `--model-version` only for an existing Model Version source.
-- Keep polling bounded and report terminal state only when the CLI shows it.
-
-## Workflow
-
-1. Verify `bun --version`, `toloka --version`, `toloka whoami`, and `toloka project current`.
-2. Inspect the exact training Dataset ID supplied by the user:
-   ```sh
-   toloka dataset fields <training-dataset-id>
-   ```
-3. Ask the user for an absolute prompt-file path and validate that it is non-empty UTF-8 text within the size limit.
-4. Verify the supplied Base Model ID or existing Model Version source:
-   ```sh
-   toloka base-model get <base-model-id>
-   ```
-5. Ask the user to choose the source, training Dataset, optional validation Dataset, prompt file, and Training name.
-6. Create the normalized gisting Training:
-   ```sh
-   toloka training create "<training-name>" \
-     --method gisting \
-     --prompt-file <absolute-prompt-path> \
-     --base-model <base-model-id> \
-     --dataset <training-dataset-id> \
-     --validation-dataset <validation-dataset-id> \
-     --json
-   ```
-   Omit `--validation-dataset` when the user chooses provider holdout. Use `--model-version <model-version-id>` instead of `--base-model` for an existing Model Version source.
-7. Verify the draft:
-   ```sh
-   toloka training get <training-id> --json
-   ```
-8. Calculate a ready estimate to an absolute path:
-   ```sh
-   toloka training cost <training-id> --json > <absolute-estimate-file>
-   ```
-   Report rows, tokens, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. Fix every blocked issue and recalculate after changing inputs.
-9. Ask the user to approve the exact `maximumCharge`. After approval, start one run:
-   ```sh
-   toloka training run <training-id> \
-     --estimate-file <absolute-estimate-file> \
-     --version-name <unique-version-name> \
-     --json
-   ```
-   Both flags are optional. Without `--estimate-file`, `training run` calculates a fresh ready estimate itself; without `--version-name`, the Model Version takes the Training name. Passing the approved estimate prevents a fresh quote from replacing the reviewed one.
-10. Monitor with bounded commands:
-    ```sh
-    toloka training status <training-run-id> --json
-    toloka training logs <training-run-id>
-    toloka training metrics <training-run-id> --json
-    ```
-    Resume only after the user confirms a billing block is resolved. Cancel only on explicit request.
-11. When completed, verify the output Model and Model Version, then download if requested:
-    ```sh
-    toloka training get <training-id> --json
-    toloka model get <model-id> --json
-    toloka model version download <model-version-id> --out <absolute-output-directory>
-    ```
-
-A completed Training Run produces a durable Model Version. It does not prove deployment or inference readiness.
+- Never invent project, Dataset, Base Model, Training, Model, Model Version, prompt, price, or run IDs. Read identity and source metadata from the CLI.
+- Use only authorized project Datasets containing representative examples. Keep credentials and production data out of source control and agent messages.
+- The prompt file must be non-empty UTF-8 text no larger than 256 KiB. Preserve user-provided prompt text exactly unless they ask to edit it; when the prompt is supplied in chat, materialize that exact text instead of inventing missing intent.
+- Preserve train/validation separation and avoid duplicate or near-duplicate examples across roles.
+- Never start a Training Run before the user approves the ready estimate's exact `maximumCharge`.
+- Keep polling bounded. Report terminal state only when the CLI shows it, and report timeouts as still running.
+
+## Process
+
+### 1. Establish only the context the goal needs
+
+When runtime, authentication, or binding is unknown, inspect it:
+
+```sh
+bun --version
+toloka --version
+toloka whoami
+toloka project current
+```
+
+Reuse an authenticated, compatible workspace. For an inspection request, inspect existing resources rather than creating a project, Dataset, Training, prompt file, or run.
+
+Use the project the user explicitly requested. Otherwise keep the current binding when it is consistent with the task. If no suitable project is bound and the requested work needs one, inspect `toloka project list --limit 20`, then create a task-named project or register the exact existing project the user identified. Do not silently select an unrelated project or rebind an existing checkout; use an explicit `--project-id` or a separate source root when working against another project without changing the binding.
+
+### 2. Inspect and assign data roles
+
+```sh
+toloka dataset list
+toloka dataset fields <dataset-name-or-id>
+```
+
+Use the user's authorized data and existing role assignments. If local JSONL files must be uploaded, organize Datasets by training and validation role, not automatically by file. `dataset upload` appends, so compatible files for one role can share a Dataset:
+
+```sh
+toloka dataset create <role-dataset-name>
+toloka dataset upload <role-dataset-name> <absolute-jsonl-path>
+toloka dataset fields <role-dataset-name>
+```
+
+CLI uploads to an otherwise undeclared Dataset store each row whole. A nested `split` value in that uploaded object is not a top-level Dataset field and cannot be used by `--train-filter` or `--validation-filter`. In that case, use separate role Datasets or omit validation flags and use the provider's 10% holdout. Existing Datasets with a real top-level split field can use disjoint filters. Never use overlapping selections or mix a supplied validation set back into training.
+
+Check that the examples demonstrate the desired behavior under the prompt: dynamic input in user messages, target output in the final assistant message, representative edge cases, and no prompt or answer leakage across validation.
+
+### 3. Preserve the prompt and choose the source
+
+Confirm the prompt path contains non-empty UTF-8 text within 256 KiB. Use the supplied file as-is. If the user supplied prompt text in the request instead, write that exact text to a UTF-8 file. Ask only when the required prompt or its intended boundaries are genuinely missing; do not author a replacement prompt from assumptions.
+
+Explicit source choices take precedence. An existing Model Version bypasses Base Model selection.
+
+Gisting supports only `qwen3-4b` and `qwen3-8b` because it publishes full model weights. This restriction also applies to the underlying Base Model of an existing Model Version. Unsupported tiers are rejected when creating or updating a Training draft; explain the constraint rather than silently substituting a model.
+
+```sh
+toloka base-model list --json
+toloka base-model get <base-model-id> --json
+toloka model list --json
+toloka model get <model-id> --json
+toloka model versions <model-id> --json
+```
+
+For a Base Model, compare available evidence about prompt and language fit, prior quality, data volume, desired compression fidelity, training budget, and serving latency or deployment constraints. Model size alone is not a quality decision; a smaller model is a useful cost and latency baseline when the task permits it, not a mandatory default. Verify the selected catalog ID, upstream model, and pinned revision with `base-model get`, and consult upstream documentation or user-provided evidence for capabilities the catalog does not expose.
+
+Gisting starts either from a catalog Base Model or, to compress a prompt for a model you already fine-tuned, from that model's LoRA adapter Model Version via `--model-version` (the adapter is merged into the base and the gist tokens are trained over the fine-tuned weights). Because gisting publishes a full model, it is limited to the qwen3-4b and qwen3-8b tiers, and a `--model-version` source must be a LoRA adapter version (a full-weights version is rejected).
+
+### 4. Reuse or create the draft
+
+Inspect before creating another Training:
+
+```sh
+toloka training list --json
+toloka training get <training-id> --json
+```
+
+When a new draft is needed, use a descriptive name and create normalized gisting configuration:
+
+```sh
+toloka training create "<training-name>" \
+  --method gisting \
+  --prompt-file <absolute-prompt-path> \
+  --base-model <base-model-id> \
+  --dataset <training-dataset-id> \
+  --validation-dataset <validation-dataset-id> \
+  --json
+```
+
+Omit `--validation-dataset` when no separate validation selection exists so the provider uses its 10% holdout. For disjoint selections in a Dataset with top-level fields, add `--train-filter <field>=<value>` and `--validation-filter <field>=<value>`.
+
+Preserve requested hyperparameters. The current CLI uses `--gist-tokens 8|32|64` (default 32), `--epochs 1..5` (default 3), `--learning-rate` within 0.001–0.3 (default 0.03), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 3072), rather than `regime`. Use defaults when suitable; 8 gist tokens favor compression for simple prompts, while 64 may help when 32 loses holdout accuracy. Choose sequence length from actual examples within the supported limit. `--lora-rank` is rejected for gisting. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values.
+
+Verify the saved method, exact source, prompt file, selections, filters, and configuration with `toloka training get <training-id> --json`.
+
+### 5. Validate and estimate
+
+```sh
+toloka training cost <training-id> --json > <absolute-estimate-file>
+```
+
+A blocked estimate exits 1, leaves the redirected file empty, and prints `Training cannot run with these inputs:` followed by one `- <message>` line per issue on stderr. Report every issue, correct the cause, and calculate a new estimate.
+
+For a duration issue, use the reported rows, tokens, epochs, GPU count, and wall time to compare supported options. Gisting publishes full model weights, so only `qwen3-4b` and `qwen3-8b` are supported; switching to the larger 8-GPU tiers is not a valid workaround. Reducing rows can weaken coverage and reducing epochs can weaken compression quality. Do not silently change the requested model, discard data, or alter epochs merely to make the estimate pass. Explain the tradeoff, obtain direction when material, update the draft, re-estimate, and obtain approval for the new quote.
+
+For a ready estimate, report the source, prompt, and selections, training and validation row counts, token totals, maximum GPU seconds, `maximumCharge`, currency, and fingerprint. If the user asked only for an estimate, stop here.
+
+### 6. Run only after explicit cost approval
+
+Ask the user to approve the exact ready `maximumCharge`. After approval, start only the requested run and pass the approved file so a new unseen quote cannot replace it:
+
+```sh
+toloka training run <training-id> \
+  --estimate-file <absolute-estimate-file> \
+  --version-name <unique-version-name> \
+  --json
+```
+
+Both flags are optional at the CLI level. Without `--estimate-file`, `training run` calculates a fresh ready estimate; do not use that path when the user approved a saved quote. Without `--version-name`, the Model Version takes the Training name.
+
+Monitor only as far as the user requested, with bounded commands:
+
+```sh
+toloka training status <training-run-id> --json
+toloka training logs <training-run-id>
+toloka training metrics <training-run-id> --json
+```
+
+Resume only after the user confirms a billing block is resolved. Cancel only on explicit request.
+
+For a completed run, verify the observed output and download only when requested:
+
+```sh
+toloka training get <training-id> --json
+toloka model get <model-id> --json
+toloka model versions <model-id> --json
+toloka model version download <model-version-id> --out <absolute-output-directory>
+```
+
+The downloaded folder contains full model weights (`config.json` and `model-*.safetensors`) and tokenizer files, including supported text sidecars such as `merges.txt` and `chat_template.jinja`. Keep the files together. The learned prompt is represented by `<|gist_…|>` tokens that prefix requests in place of the original prompt. Verify serving separately with a compatible runtime; a successful download alone does not establish inference readiness.

package/skills/toloka-report-issue/references/report-template.md

@@ -26,7 +26,7 @@ The CLI exits 1 with `Potato API request failed with status 500`. The same comma
 
 ## Environment
 
-- toloka CLI 0.2.0-preview.3 (`toloka --version`), Bun 1.4.0, macOS 15
+- toloka CLI 0.2.0 (`toloka --version`), Bun 1.4.0, macOS 15
 - Platform: https://platform.toloka.ai
 
 ## Redactions

package/src/cli/analytics.ts

@@ -1,14 +1,15 @@
-import { assert } from "es-toolkit";
 import { randomUUID } from "node:crypto";
 import { chmod, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { PostHog } from "posthog-node";
-import { PipelineGraphValidationError, PotatoApiError } from "../errors";
+import { PipelineGraphValidationError } from "../errors";
 import type { TolokaEnvironment } from "./config";
 import type { CliEnvironment } from "./credentials";
 import { credentialsPath, preparePrivateFilePath } from "./credentials";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
 import { SDK_VERSION } from "./sdk-version";
+import { assertCli, TolokaCliError } from "./cli-error";
+import { findPotatoApiError } from "./format-error";
 
 export const POSTHOG_PROJECT_KEY = "phc_kqHt0f53B5MVqURyzWpW1aNlbOmYt1YbUYza0JPcg19";
 export const POSTHOG_HOST = "https://eu.posthog.com";
@@ -77,7 +78,9 @@ export function telemetryEnabled(environment: CliEnvironment): boolean {
   return true;
 }
 
-const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> = {
+type CommandGroup = Readonly<Record<string, true | Readonly<Record<string, true>>>>;
+
+const COMMAND_GROUPS: Readonly<Record<string, CommandGroup>> = {
   project: { list: true, add: true, switch: true, current: true, remove: true, create: true },
   pipeline: {
     list: true,
@@ -88,8 +91,31 @@ const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> =
     cancel: true,
     results: true,
   },
-  dataset: { list: true, fields: true, load: true, upload: true },
+  dataset: { list: true, create: true, fields: true, load: true, upload: true },
   "delivery-order": { list: true },
+  training: {
+    list: true,
+    get: true,
+    create: true,
+    update: true,
+    cost: true,
+    run: true,
+    runs: true,
+    status: true,
+    resume: true,
+    cancel: true,
+    metrics: true,
+    logs: true,
+  },
+  "base-model": { list: true, get: true },
+  model: {
+    list: true,
+    get: true,
+    versions: true,
+    create: true,
+    archive: true,
+    version: { download: true },
+  },
   secret: { set: true },
   skill: { list: true, search: true, install: true },
   config: { get: true, set: true },
@@ -121,9 +147,13 @@ const nameFromTokens = (tokens: readonly string[]): string => {
   if (subcommands === undefined) return ROOT_COMMANDS[command] === true ? command : "unknown";
 
   const subcommand = tokens[1];
-  return subcommand !== undefined && subcommands[subcommand] === true
-    ? `${command} ${subcommand}`
-    : command;
+  const nested = subcommand === undefined ? undefined : subcommands[subcommand];
+  if (nested === undefined) return command;
+  if (nested === true) return `${command} ${subcommand}`;
+  const leaf = tokens[2];
+  return leaf !== undefined && nested[leaf] === true
+    ? `${command} ${subcommand} ${leaf}`
+    : `${command} ${subcommand}`;
 };
 
 export function commandNameFromArgv(argv: readonly string[]): string {
@@ -142,19 +172,6 @@ export function commandNameFromArgv(argv: readonly string[]): string {
   return nameFromTokens(tokens);
 }
 
-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 function classifyCliError(error: unknown): { readonly error_code: string } {
   if (error === undefined) return { error_code: "command_failed" };
   const apiError = findPotatoApiError(error);
@@ -197,7 +214,11 @@ const noopAnalytics = (): CliAnalytics => ({
   identifyCurrentUser() {},
   captureCommand() {},
   async submitIssueReport() {
-    assert(false, "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.");
+    assertCli(
+      false,
+      "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.",
+      { hint: { disabled: true } },
+    );
   },
   async shutdown() {},
 });
@@ -270,7 +291,9 @@ export function createCliAnalytics(options: {
             const errorProperties = cliErrorProperties(event.error);
 
             if (event.error !== undefined) {
-              const exception = new Error(`CLI command failed: ${classified.error_code}`);
+              const exception = new TolokaCliError(`CLI command failed: ${classified.error_code}`, {
+                hint: { disabled: true },
+              });
               exception.name = "PotatoCliError";
               client.captureException(exception, distinctId, {
                 ...shared,
@@ -316,7 +339,11 @@ export function createCliAnalytics(options: {
     },
     submitIssueReport(report) {
       const submission = queue.then(async () => {
-        assert(client && distinctId, "PostHog issue reporting could not be initialized.");
+        assertCli(
+          client && distinctId,
+          "PostHog issue reporting could not be initialized.",
+          { hint: { description: "Set TOLOKA_TELEMETRY=1 and check that this machine can reach PostHog, then retry." } },
+        );
         deliveryErrors.length = 0;
         client.capture({
           distinctId,

package/src/cli/auth.ts

@@ -1,4 +1,3 @@
-import { assert } from "es-toolkit";
 import { createClient } from "../client";
 import { PotatoApiError } from "../errors";
 import { PRODUCTION_BASE_URL, consoleUrlFor, resolveInternalBaseUrl } from "./config";
@@ -19,6 +18,7 @@ import type {
 } from "./credentials";
 import type { ProjectContext } from "./project-context";
 import { formatProjectContextLine } from "./project-context";
+import { assertCli, TolokaCliError } from "./cli-error";
 
 type ProbeFailureKind = "rejected" | "unreachable" | "platform";
 
@@ -89,7 +89,14 @@ export type AuthProbe = {
       readonly pagination: { readonly total: number };
     }>;
   };
-  readonly me?: () => Promise<{ readonly internal: boolean }>;
+  readonly me?: () => Promise<{
+    readonly internal: boolean;
+    readonly teams?: ReadonlyArray<{
+      readonly id: string;
+      readonly writable: boolean;
+      readonly internal?: boolean;
+    }>;
+  }>;
 };
 
 export type LoginOptions = {
@@ -119,14 +126,19 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
 
   let apiKey = options.apiKey ?? environment.TOLOKA_API_KEY;
   if (apiKey === undefined) {
-    assert(
+    assertCli(
       options.prompt,
       "Missing API key. Without a terminal, pipe the key to toloka login --api-key-stdin, pass --api-key, or set TOLOKA_API_KEY.",
+      { hint: { disabled: true } },
     );
     write(`\n${apiKeyInstructions(baseUrl)}\n`);
     apiKey = (await options.prompt("API key: ", { mask: true })).trim();
   }
-  assert(apiKey.length > 0, "No API key entered.");
+  assertCli(
+    apiKey.length > 0,
+    "No API key entered.",
+    { hint: { description: "Re-run toloka login and paste the key at the prompt, or pass --api-key." } },
+  );
   const credentials: StoredCredentials = { baseUrl, apiKey };
   const probe: AuthProbe = options.probe?.(credentials) ?? createClient(credentials);
 
@@ -136,13 +148,13 @@ export async function login(options: LoginOptions = {}): Promise<LoginResult> {
     reachable = `Authenticated against ${baseUrl}: ${page.pagination.total} project(s) visible.`;
   } catch (error) {
     const failure = classifyProbeFailure(error);
-    throw new Error(
+    throw new TolokaCliError(
       [
         `Could not authenticate against ${baseUrl}: ${failure.reason}`,
         "",
         `Nothing was saved. ${LOGIN_FAILURE_ADVICE[failure.kind](baseUrl)}`,
       ].join("\n"),
-      { cause: error },
+      { cause: error, hint: { disabled: true } },
     );
   }
 
@@ -249,13 +261,21 @@ const resolvePlatform = (
   );
 };
 
-const internalStatusLine = async (probe: AuthProbe): Promise<string | undefined> => {
-  if (probe.me === undefined) return undefined;
+const accountLines = async (probe: AuthProbe): Promise<readonly string[]> => {
+  if (probe.me === undefined) return [];
   try {
     const me = await probe.me();
-    return `Internal: ${me.internal}`;
+    if (me.teams === undefined) return [`Internal: ${me.internal}`];
+    const teams = me.teams.map((team) => {
+      const qualifiers = [...(team.internal ? ["internal"] : []), ...(team.writable ? [] : ["read-only"])];
+      return qualifiers.length === 0 ? team.id : `${team.id} (${qualifiers.join(", ")})`;
+    });
+    return [
+      `Internal: ${me.internal}`,
+      `Teams:    ${teams.length === 0 ? "(none)" : teams.join(", ")}`,
+    ];
   } catch {
-    return undefined;
+    return [];
   }
 };
 
@@ -306,8 +326,7 @@ export async function authStatus(options: AuthStatusOptions = {}): Promise<AuthS
   try {
     const page = await probe.projects.listPage({ limit: 1 });
     lines.push("", `Reachable: ${page.pagination.total} project(s) visible.`);
-    const internalLine = await internalStatusLine(probe);
-    if (internalLine !== undefined) lines.push(internalLine);
+    lines.push(...(await accountLines(probe)));
     return { authenticated: true, output: lines.join("\n") };
   } catch (error) {
     const failure = classifyProbeFailure(error);

package/src/cli/auto-update.ts

@@ -17,6 +17,8 @@ import { commandNameFromArgv } from "./analytics";
 import { readCliSettings } from "./settings";
 import { CHECK_RESULT_FILE_ENV } from "./check";
 import { isFalseyFlag, isTruthyFlag } from "./boolean-flag";
+import { TolokaCliError } from "./cli-error";
+import { formatCliError } from "./format-error";
 
 export const AUTO_UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 export const AUTO_UPDATE_QUARANTINE_MS = 24 * 60 * 60 * 1000;
@@ -199,9 +201,9 @@ const collectOutput = async (stream: NodeJS.ReadableStream | null): Promise<stri
   return Buffer.concat(chunks).toString("utf8");
 };
 
-class RegistryError extends Error {
+class RegistryError extends TolokaCliError {
   constructor(message: string) {
-    super(message);
+    super(message, { hint: { disabled: true } });
     this.name = "RegistryError";
   }
 }
@@ -239,10 +241,16 @@ const defaultInstall: AutoUpdateInstall = async ({
   const exitCode = close[0];
   if (exitCode === 0) return;
   const detail = [stderr.trim(), stdout.trim()].filter((part) => part.length > 0).join("\n");
-  throw new Error(
+  throw new TolokaCliError(
     detail.length > 0
       ? `bun add --global failed: ${detail}`
       : `bun add --global exited ${String(exitCode)}`,
+    {
+      hint: {
+        description:
+          "Run the bun add --global command yourself, or turn the check off with toloka config set auto-update false.",
+      },
+    },
   );
 };
 
@@ -340,9 +348,7 @@ export async function maybeAutoUpdate(options: {
       environment,
     });
   } catch (error) {
-    io.stderr(
-      `Auto-update to ${candidate.version} failed: ${error instanceof Error ? error.message : String(error)}.`,
-    );
+    io.stderr(`Auto-update to ${candidate.version} failed: ${formatCliError(error)}`);
     return continueResult();
   }