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

package/skills/toloka-build/references/workflow-and-cli.md

@@ -26,7 +26,7 @@ Treat the three layers differently:
 
 ## Initialize the source root
 
-For a first-time guided session, read `https://platform.toloka.ai/agents/data-labeling.md` first. Keep its stage order and checkpoints; use this reference for the commands and source-first invariants inside those stages.
+For a first-time guided session, consult `https://platform.toloka.ai/agents/data-labeling.md` for orientation. Adapt the journey to the user's goal and already-complete setup while preserving dependencies, cost approval, and identity/source protection; use this reference for command details.
 
 Install the SDK before invoking project commands:
 
@@ -51,9 +51,10 @@ It explains where to generate an API key — `console.toloka.ai` → Company →
 credentials file with mode `0600`. Nothing is written when the key does not authenticate.
 
 Most later commands read that file, so `--api-key` becomes optional. For networked commands that do
-not mutate the machine project registry, key precedence is flag, then `POTATO_API_KEY`, then the
+not mutate the machine project registry, key precedence is flag, then `TOLOKA_API_KEY`, then the
 stored file; CI can use an environment variable without running login. Non-interactive callers can
-skip the login prompt with `toloka login --api-key <key>`. The base URL defaults to the platform.
+skip the login prompt by piping the key to `toloka login --api-key-stdin`; `toloka login --api-key <key>`
+also works but leaves the key in shell history. The base URL defaults to the platform.
 
 ```sh
 toloka auth-status     # or toloka whoami
@@ -61,22 +62,25 @@ toloka logout
 ```
 
 `auth-status` reports which platform and key are in effect and where each came from, masks the key
-unless you pass `--show-token`, and exits non-zero when the platform is unreachable — use it to check a
-setup rather than guessing. `logout` deletes the stored file; it does not revoke the key.
+unless you pass `--show-token`, and exits non-zero on failure — use it to check a setup rather than
+guessing. Its last lines say which failure it was: `Rejected:` means the platform refused the key
+(run `toloka login` with a working one); `Not reachable:` means the platform did not answer, so the
+key was not evaluated (fix network access, do not ask for a new key); `Platform error:` means the
+platform failed (retry later). `logout` deletes the stored file; it does not revoke the key.
 
 A globally installed `toloka` auto-updates by default. It checks npm at most once per day and installs a newer `@toloka-platform/sdk` only after that version has been published for at least 24 hours, then re-runs the original command. `config`, `version`, and `help` never trigger a check. Project-local installs and CI skip it. Turn it off with `toloka config set auto-update false`.
 
 ## Configure the CLI
 
-Provide the API key and base URL on networked workflows through `POTATO_API_KEY` and
-`POTATO_BASE_URL`, or with `--api-key` and `--base-url`. The registry-mutating commands
+Provide the API key and base URL on networked workflows through `TOLOKA_API_KEY` and
+`TOLOKA_BASE_URL`, or with `--api-key` and `--base-url`. The registry-mutating commands
 `toloka project add`, `toloka project switch`, `toloka project remove`, and `toloka project create`
 require `toloka login` first because they read and write the credentials file. When flags or
-`POTATO_*` variables are also present, they must identify the same stored key and platform. Resolve
-project ID in this order: `--project-id`, `TOLOKA_PROJECT_ID`, `POTATO_PROJECT_ID`, `toloka.json`,
+`TOLOKA_*` variables are also present, they must identify the same stored key and platform. Resolve
+project ID in this order: `--project-id`, `TOLOKA_PROJECT_ID`, `toloka.json`,
 then the machine registry `current`.
 
-Anonymous command telemetry is on by default (`sdk_cli_command_completed` / `sdk_cli_command_failed`). `toloka report` uses the same PostHog client to send explicitly approved Markdown in `sdk_cli_issue_report_submitted`. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable both; CI is off unless `TOLOKA_TELEMETRY=1`.
+Anonymous command telemetry is on by default (`sdk_cli_command_completed` / `sdk_cli_command_failed`). Failed commands with exceptions also emit a sanitized PostHog Error Tracking `$exception`; API failures include the status code and server request ID when available. Raw arguments, messages, stacks, response bodies, and paths are excluded. `toloka report` uses the same PostHog client to send explicitly approved Markdown in `sdk_cli_issue_report_submitted`. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable all capture; CI is off unless `TOLOKA_TELEMETRY=1`.
 
 All commands accept `--source-root <directory>`. Prefer running from the source root so paths and diffs stay obvious. `init` does not walk up: it binds the working directory or `--source-root` only.
 
@@ -98,8 +102,9 @@ toloka project switch <alias>
 toloka project current
 toloka project url
 toloka project remove <alias>
-toloka project create [alias] [--name <name>] [--team-id <id>]
+toloka project create [alias] [--name <name>] [--team-id <id>] [--delivery-order-id <id>]
 toloka project untrack <pipeline|dataset> <name> [--confirm]
+toloka delivery-order list
 toloka init
 toloka import [projectId]
 toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]
@@ -109,6 +114,7 @@ toloka apply
 toloka status
 toloka secret set <name> [--from-env <variable>]
 toloka dataset list
+toloka dataset create <name>
 toloka dataset fields <name>
 toloka dataset load <name> --out <file> [--limit <n>] [--timeout <ms>]
 toloka dataset upload <name> <file>
@@ -128,22 +134,25 @@ toloka model create <name> --base <base-model-id> [--description <text>] [--json
 toloka model archive <name-or-id> [--json]
 toloka training list [--json]
 toloka training get <name-or-id> [--json]
-toloka training create <name> (--base-model <id> | --model-version <id>) --dataset <id> [--json]
-toloka training update <name-or-id> [configuration flags] [--json]
+toloka training create <name> [--method sft|gisting] (--base-model <id> | --model-version <id>) --dataset <id> [--train-filter field=value] [--validation-dataset <id> [--validation-filter field=value]] [--prompt-file <path>] [--lora-rank 8|16|32 | --gist-tokens 8|32|64] [--epochs 1..5] [--learning-rate <rate>] [--batch-size 8|16|32|64] [--max-sequence-length <tokens>] [--json]
+toloka training update <name-or-id> [--base-model <id> | --model-version <id>] [--dataset <id>] [--train-filter field=value] [--validation-dataset <id> [--validation-filter field=value]] [--prompt-file <path>] [--lora-rank 8|16|32 | --gist-tokens 8|32|64] [--epochs 1..5] [--learning-rate <rate>] [--batch-size 8|16|32|64] [--max-sequence-length <tokens>] [--json]
 toloka training cost <name-or-id> [--idempotency-key <key>] [--json]
-toloka training run <name-or-id> --estimate-file <path> --version-name <name> [--idempotency-key <key>] [--json]
+toloka training run <name-or-id> [--estimate-file <path>] [--version-name <name>] [--idempotency-key <key>] [--json]
 toloka training runs <name-or-id> [--json]
 toloka training status <training-run-id> [--json]
 toloka training resume <training-run-id> [--json]
 toloka training cancel <training-run-id> [--json]
 toloka training logs <training-run-id> [--follow]
+toloka training metrics <training-run-id> [--key <metric>] [--resolution <n>] [--json]
 toloka skill list [--json]
 toloka skill search <query> [--json]
 toloka skill install <skill-id> [--force]
 toloka report <markdown> [--authored-by human|agent] [--confirm]
 ```
 
-Select the platform project with `toloka project add` or `toloka project create` before `import`, `plan`, or `apply`. For `init`, `toloka --project-id <id> init`, `TOLOKA_PROJECT_ID`, and `POTATO_PROJECT_ID` bind an empty checkout directly without changing the machine registry. `project create` also writes `toloka.json`; `project add` changes only the machine registry, so follow it with `import <projectId>` for an existing project or an explicit project ID on `init` for an empty one. Confirm `toloka project current` and `toloka.json` resolve to the intended ID before authoring.
+Resolve the intended platform project before `import`, `plan`, or `apply`; use an existing correct binding rather than registering or creating a project again. For `init`, `toloka --project-id <id> init` and `TOLOKA_PROJECT_ID` bind an empty checkout directly without changing the machine registry. `project create` also writes `toloka.json`; `project add` changes only the machine registry, so follow it with `import <projectId>` for an existing project or an explicit project ID on `init` for an empty one. Confirm `toloka project current` and `toloka.json` resolve to the intended ID before authoring.
+
+`toloka delivery-order list` and `project create --delivery-order-id` are always available; the platform accepts them only for internal teams. When `toloka whoami` marks the project's owning team `(internal)` on its `Teams:` line, list active Sunday orders first; if the list is empty, stop. Pass a selected id to `project create` — internal teams require it. For a project in an external team, omit the flag; the platform rejects an order there.
 
 `toloka project url` prints only the selected project's platform UI URL. Use it when the user needs a working link to inspect the live project.
 
@@ -151,13 +160,15 @@ Select the platform project with `toloka project add` or `toloka project create`
 
 ## Manage model checkpoints
 
-The global Base Model Catalog is read-only and uses `toloka base-model`. `base-model list` prints aligned ID, name, provider, and upstream-model columns by default. `toloka model` manages project-owned lineages; creation requires one catalog `baseModelId` and creates metadata without a Model Version. Every Base Model and Model command accepts `--json` for machine-readable output. Model Version upload, validation, and download commands are deferred until the separate upload-processing contract is implemented.
+The global Base Model Catalog is read-only and uses `toloka base-model`. `base-model list` prints aligned ID, name, provider, upstream-model, revision (first 12 characters) and upstream-snapshot URL columns by default; `base-model get` prints the full pinned revision and the `https://huggingface.co/<model>/tree/<revision>` snapshot URL, which is the exact base every Training Run trains on. `toloka model` manages project-owned lineages; creation requires one catalog `baseModelId` and creates metadata without a Model Version. Every Base Model and Model command accepts `--json` for machine-readable output. Model Version upload, validation, and download commands are deferred until the separate upload-processing contract is implemented.
 
 ## Train a model
 
 `toloka training create` requires one source (`--base-model` or `--model-version`) and a training Dataset. The output Model is created on the first Training Run from the Training name, or bound from an existing Model Version source.
 
-Use `training cost` to validate inputs and produce a ready estimate JSON file before `training run`. The run command requires that file and an explicit maximum cost. Use `training status`, `training logs`, `training resume`, and `training cancel` with the returned Training Run ID.
+Hyperparameters are optional flags on `training create` and `training update`: `--epochs 1..5` (default 3), `--learning-rate` (SFT 0.00001–0.001, default 0.00015; gisting 0.001–0.3, default 0.03), `--batch-size 8|16|32|64` (default 8; sequences per optimizer step across all GPUs) and `--max-sequence-length 64..16384` (default 12288 for SFT, 3072 for gisting) apply to both methods; `--lora-rank 8|16|32` (default 16) is SFT-only and `--gist-tokens 8|32|64` (default 32) is gisting-only — passing one to the other method fails before any request. `--regime` and `--eval-steps` no longer exist. `training update` has no `--method` flag: the method stays as created, and every flag you omit keeps its current value. `training cost` is blocked when the longest example exceeds `--max-sequence-length` or when the training selection leaves fewer rows than `--batch-size` after the 10% holdout.
+
+Use `training cost` to validate inputs and show the maximum charge before `training run`. A blocked estimate exits 1 and lists the issues on stderr instead of printing the estimate; fix them and recalculate. `training run` accepts that ready estimate JSON through `--estimate-file`; without it, the command calculates a fresh ready estimate itself before creating the run. `--version-name` defaults to the Training name; pass it when a Model Version with that name already exists. Use `training status`, `training logs`, `training metrics`, `training resume`, and `training cancel` with the returned Training Run ID. `training metrics` lists each metric's latest value while the run is still training; `--key` prints one metric's point history instead.
 
 ## Adopt an existing live project
 
@@ -227,7 +238,7 @@ Register every code-node behavior with `test.code(pipeline, node, name, callback
 
 Before choosing component names or props, call `ui.componentDocumentation()` in a local `@toloka-platform/sdk/testing` scenario. A component's contract is its returned `propsType`, `valueType`, and `example`. For structured or array-valued Fields, derive the dataset field schema from `valueType`, then feed the documented example value through `setValue`, `getValue`, and `submit`; never translate undocumented property names or replace missing values with defaults. Register required human-work behavior with `test.ui(pipeline, node, name, callback)`. Its callback receives bound `render(options?)`; the test counts only after a successful `submit`, at least one assertion, and a passing callback.
 
-Register the representative connected flow with `test.pipeline(pipeline, name, callback)`. When a local dataset file is available, use its first row as the initial item state; redact sensitive values while preserving field names, nesting, optionality, and media/value shapes. Use synthetic input only when no local row exists. Use the callback's bound `runCode` and `renderUi` helpers, merge only declared node outputs, and assert the final `root.completed` fields. Keep a linear happy path in one test; use separate scenarios for match branches, optional routes, and failures.
+Register representative connected flows with `test.pipeline(pipeline, name, callback)`. Choose fixtures from available data that exercise the task, redacting sensitive values while preserving field names, nesting, optionality, and media/value shapes. Use synthetic cases for privacy or boundaries absent from the sample. Use the callback's bound `runCode` and `renderUi` helpers, merge only declared node outputs, and assert the final `root.completed` fields. Cover meaningful match branches, optional routes, and failures as well as the happy path.
 
 ```sh
 toloka check
@@ -261,7 +272,7 @@ Pull live rows with `toloka dataset load <name> --out <file> [--limit <n>]`. `--
 
 ## Run a pipeline and report results
 
-A run needs a deployed pipeline, so apply before starting one.
+A run needs a deployed pipeline. Apply any requested source changes and verify convergence first; an already-deployed unchanged pipeline does not need another apply. Present the cost forecast and obtain run approval before starting. The commands below are available operations, not a sequence that requires starting or canceling a run.
 
 ```sh
 toloka pipeline run <name> --wait --timeout 900000
@@ -274,7 +285,7 @@ toloka pipeline cancel <runId>
 
 Read the exit code, not just the text. `toloka pipeline run --wait` exits `0` when the run reaches a successful terminal state, `1` when it reaches a failed one, and `2` when the wait window elapses while the run is still going. Without `--wait` the command returns as soon as the run is accepted, and exit `0` means "accepted", not "succeeded".
 
-Never treat a started run as a finished one. There is no background watcher: nothing will report back later. But bound every wait — a queue no one is working stays in progress indefinitely, and an unbounded poll loop ends with the agent killed and no report written. Pick a window, and when it closes report the observed counts and states along with the fact that the run had not finished. Poll in the foreground and deliver that report before you finish: there is no later turn, so promising to report once a window closes loses the observation entirely.
+A started run is not a finished one. Choose a bounded monitoring window appropriate to the task, then report observed counts and states even if work is still in progress. Continue with another bounded check when useful; do not promise an automatic later update unless a reporting mechanism actually exists.
 
 `toloka pipeline runs` lists ids and timestamps. `toloka pipeline status` reports the latest run. `toloka status` (no prefix) is project health. When a listing is capped it says so; report the cap rather than presenting a page as the whole picture.
 

package/skills/toloka-fine-tuning/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: toloka-fine-tuning
+description: Create, estimate, start, monitor, and verify a project-owned supervised fine-tuning Training through the Toloka CLI. Use when the user wants to adapt a base model or existing Model Version from labeled conversations.
+---
+
+# Fine-tune a model with Toloka
+
+## Mission
+
+Help the user adapt a compatible model from labeled conversations while preserving their intended task, data, model, 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/fine-tuning.md`.
+
+## Domain model
+
+- **SFT** adapts model weights from representative chat examples. Each training row must follow the platform chat contract and end with the assistant response the model should learn to produce.
+- A **Training** is an editable project-owned draft. A **Training Run** is one immutable, billable execution of a frozen draft 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, 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, 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 prompt compression or data labeling rather than SFT, explain the distinction and route to `toloka-gisting` 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, or run IDs. Read identity and source metadata from the CLI.
+- Use only authorized project Datasets containing representative data. Keep credentials and production data out of source control and agent messages.
+- 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, 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.
+
+### 3. Choose and verify the source
+
+Explicit source choices take precedence. An existing Model Version bypasses Base Model selection.
+
+```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 upstream documentation, user-provided benchmarks, and prior results for task and language fit, data volume, quality, 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. Use `base-model get` only to verify the selected catalog ID, upstream model, and pinned revision; it does not establish those broader capabilities.
+
+For a Model Version, verify the exact ID and revision under its project-owned Model, and record the owning Model's Base Model and the Version's runtime base from JSON. If those identities conflict, report the conflict rather than guessing or substituting. Use `--model-version` only for that existing version. The ready cost estimate is the concrete final check that the source type, underlying Base Model, method, and data are supported together.
+
+### 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 SFT configuration:
+
+```sh
+toloka training create "<training-name>" \
+  --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>`. For an existing Model Version source, replace `--base-model` with `--model-version <model-version-id>`.
+
+Preserve requested hyperparameters. The current CLI uses `--lora-rank 8|16|32` (default 16), `--epochs 1..5` (default 3), `--learning-rate` within 0.00001–0.001 (default 0.00015), `--batch-size 8|16|32|64` (default 8), and `--max-sequence-length 64..16384` (default 12288), rather than `regime`. Use defaults when suitable; rank 8 can fit narrow tasks or small data, while 32 may help when 16 underfits and the data supports more capacity. Choose sequence length from actual examples within the supported limit. `--gist-tokens` is rejected for SFT. `training update <name-or-id>` takes the same flags except `--method`; omitted flags retain current values.
+
+Verify the saved method, exact source, 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. `qwen3-32b` and `qwen3-235b` use 8 GPUs and can reduce wall time, but changing the model also changes quality, serving constraints, and cost; reducing rows can weaken coverage; reducing epochs can weaken adaptation. Do not change the requested model, silently discard data, or alter epochs merely to make the estimate pass. Present the tradeoff, obtain direction when it is material, then update the draft, re-estimate, and obtain approval for the new quote.
+
+For a ready estimate, report the source 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>
+```

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

@@ -0,0 +1,70 @@
+---
+name: toloka-get-started
+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 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.
+
+## Choose the relevant workflow
+
+Honor an explicitly requested target. Otherwise choose the workflow that fits the outcome and briefly explain the choice:
+
+- **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
+```
+
+The runbooks use the `preview` channel of `@toloka-platform/sdk`, so `toloka --version` must print `0.2.0-preview.4` or newer. If `toloka` is unavailable or comes from another channel, install the preview version:
+
+```sh
+curl -fsSL https://platform.toloka.ai/cli/install.sh | TOLOKA_CLI_CHANNEL=preview sh
+```
+
+Never request an API key in chat. Inspect the active identity with:
+
+```sh
+toloka whoami
+```
+
+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.
+
+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
+toloka skill search <workflow>
+toloka skill install <skill-id>
+```
+
+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.
+
+## Safety boundaries
+
+- 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

@@ -0,0 +1,166 @@
+---
+name: toloka-gisting
+description: Create, estimate, start, monitor, and verify a project-owned prompt-gisting Training through the Toloka CLI. Use when the user wants a compact prompt representation from example conversations and a prompt file.
+---
+
+# Compress a prompt with gisting
+
+## Mission
+
+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, 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.
+
+For a Model Version, verify the exact ID and revision under its project-owned Model, and record the owning Model's Base Model and the Version's runtime base from JSON. If those identities conflict, report the conflict rather than guessing or substituting. Use `--model-version` only for that existing version. The ready cost estimate is the concrete final check that the source type, underlying Base Model, method, prompt, and data are supported together.
+
+### 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>`. For an existing Model Version source, replace `--base-model` with `--model-version <model-version-id>`.
+
+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.2 (`toloka --version`), Bun 1.4.0, macOS 15
+- toloka CLI 0.2.0-preview.3 (`toloka --version`), Bun 1.4.0, macOS 15
 - Platform: https://platform.toloka.ai
 
 ## Redactions

package/src/authoring/index.ts

@@ -524,6 +524,20 @@ export function match(
   settings: MatchAuthoringSettings,
   options: AuthoringIdOptions = {},
 ): AuthoredMatchNode {
+  const conditionNames = new Set<string>();
+  for (const condition of settings.conditions) {
+    assert(condition.name !== "", "Condition must have a name");
+    assert(
+      condition.name.length >= 2 && condition.name.length <= 32,
+      "Condition name must be between 2 and 32 characters long",
+    );
+    assert(
+      /^[a-z]([a-z0-9_]*[a-z0-9])?$/u.test(condition.name),
+      "Condition name must start with a letter, contain only lowercase letters, numbers and underscores, and end with a letter or number",
+    );
+    assert(!conditionNames.has(condition.name), "Condition names must be unique");
+    conditionNames.add(condition.name);
+  }
   const id = options.id ?? mintedId("match", name);
   const { conditions, input, ...wireSettings } = settings;
   return {