@toloka-platform/sdk 0.11.2 → 0.11.4

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

@@ -24,231 +24,53 @@ Treat the three layers differently:
 - `toloka.json` is CLI-managed identity state. Read it for orientation; let import and apply write it.
 - Dataset rows and secret values are operational data. Keep them outside committed source.
 
-## Initialize the source root
-
-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.
-
-Bun is the recommended runtime and package manager for pipeline authoring. In an existing source root, install its declared dependencies:
-
-```sh
-bun i
-```
-
-For a new pipeline project, add the SDK, TypeScript, and Vitest:
-
-```sh
-bun add -d @toloka-platform/sdk@latest typescript vitest
-```
-
-These are project authoring and test dependencies, not prerequisites for running the standalone CLI or a Training-only workflow. Task UI scenarios additionally require Playwright and Chromium:
-
-```sh
-bun add -d playwright
-bunx playwright install chromium
-```
-
-Select or create the intended platform project before `toloka init` when the checkout should be bound immediately; follow the adoption or scratch recipe below. Running `init` without explicit or checkout-local project identity installs only the agent entry points and never adopts the machine registry's current project.
-
-`toloka init` warns when `@toloka-platform/sdk` is not declared in `dependencies` or `devDependencies`, then maintains one `<toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: a Claude skill at `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and an always-applied Cursor rule at `.cursor/rules/toloka-bootstrap.mdc` when `.cursor/rules/` exists. The dependency warning applies to pipeline authoring; Training commands do not require the SDK dependency. `init` writes `toloka.json` only from an explicit project flag/environment value or an existing checkout binding.
-
-The bootstrap is small: it tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search <query>`, install the match with `toloka skill install <skill-id>`, and read `.agents/skills/<skill-id>/SKILL.md`. This skill is that installed copy. Commands warn on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the running CLI's bundled version, independently of any project SDK dependency. Help, `init`, `report`, `project url`, `config`, and version invocations skip this checkout-dependent warning. The warning never blocks a command; after updating the standalone CLI, re-run `toloka init` to refresh the bootstrap and its pointers.
-
-## Sign in once
-
-```sh
-toloka login
-```
-
-It asks whether to sign in through the browser or with an API key. The browser choice opens a page in
-the browser where the user continues with Google or Microsoft (testing environments also offer email
-and password and the testing users), hands them to the Toloka login page, waits for the sign-in to finish, verifies access by
-listing one project, and only then saves the browser session under `~/.toloka/cli/credentials/` with
-mode `0600`. Nothing is written when the platform does not accept the account. The session renews
-itself for up to 14 days; after that `toloka login` is needed again. Run `toloka login --browser` yourself
-by default: it skips the question, opens the sign-in page in the user's browser, and waits for them to
-finish; without a terminal it fails fast when no browser can be opened. `toloka login --no-browser` prints
-the link instead of opening a browser.
-
-The API key choice does not expire: the key works until it is deleted in the Business Console, which
-suits scripts, CI, and coding agents. Type it at the masked prompt, or pipe it to `toloka login --api-key-stdin`.
-`toloka login --api-key <key>` also works but leaves the key in shell history. Most later commands read the stored login, so
-`--api-key` becomes optional. For networked commands that do not mutate the machine project registry,
-credential precedence is flag, then `TOLOKA_SCOPED_TOKEN`, then `TOLOKA_API_KEY`, then the stored API key,
-then the browser session; CI can use an environment variable without running login. A scoped token is
-minted by the platform for one user and one project (agent sandboxes receive it in `TOLOKA_SCOPED_TOKEN`);
-it cannot issue further tokens and expires on its own. The base URL defaults to the platform.
-
-```sh
-toloka auth-status     # or toloka whoami
-toloka logout
-```
-
-`auth-status` reports which platform and login are in effect and where each came from and exits
-non-zero on failure — use it to check a setup rather than guessing. It masks the credential; `--show-token`
-prints the full API key or the browser session's live access token, so pass it only when a command
-genuinely needs the raw value and never paste the output into chat. Its last lines say which failure it was: `Rejected:` means the platform refused the login
-(run `toloka login` again); `Not reachable:` means the platform did not answer, so the login was not
-evaluated (fix network access, do not ask for a new login); `Platform error:` means the platform
-failed (retry later). `logout` ends every stored browser session and deletes the stored files; it does not
-revoke an API key.
-
-Standalone and Bun-global `toloka` installations check the public npm registry at most once per day and install eligible releases at least 24 hours old before rerunning the command. Project-local installs, CI, and `config`, `version`, and `help` skip the check. Turn it off with `toloka config set auto-update false`. For manual standalone updates, rerun `curl -fsSL https://platform.toloka.ai/cli/install.sh | sh -s -- --native`; Bun-global updates should use `--bun` instead. Preserve the mode and put any original `TOLOKA_CLI_INSTALL_DIR`, `TOLOKA_CLI_CHANNEL`, `TOLOKA_CLI_PACKAGE`, and `TOLOKA_CLI_REGISTRY` overrides on the `sh` side of the pipe again. A package version pin does not disable automatic updates, which always use the public npm registry.
-
-## Hand out a project-scoped token
-
-`toloka project token` mints a token that acts as the signed-in user inside the selected project only (`--projects` adds more projects of the same team), with the permissions of `--preset` (default `write`) or an explicit `--permissions` list, for at most six hours. It is printed once and never stored; pass it to another agent or script as `TOLOKA_API_KEY`. `toloka project tokens` lists the live tokens of the project; `toloka project revoke-token <tokenId>` ends one and `toloka project revoke-tokens` ends every live token of the project at once, for example when a run finished or a token leaked. One user may hold at most 1000 live tokens per project; when `token` fails with `429 … revoke unused tokens first`, run `revoke-tokens`.
-
-A scoped token downloads project files in two steps: a request to `ProjectFile.url` with the token answers `200 {"url": "<storage URL>"}` instead of the redirect a human credential gets. Fetch that `url` as a plain request without the `X-Scoped-Token` header; HTTP clients replay custom headers across redirects, and the token must never reach the storage host.
-
-## Configure the CLI
-
-Provide the credential and base URL on networked workflows through `TOLOKA_SCOPED_TOKEN` or
-`TOLOKA_API_KEY` and `TOLOKA_BASE_URL`, or with `--api-key` and `--base-url`. A base URL with a path (a gateway such as
-`https://gateway.example/ss/pp.1`) keeps that path on every request, with or without a trailing
-slash; use the given URL unchanged. 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
-`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`). 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.
 
-The real command surface is:
-
-```text
-toloka version [--json]
-toloka -v
-toloka --version
-toloka login [--browser] [--no-browser] [--api-key-stdin]
-toloka logout
-toloka auth-status
-toloka config
-toloka config get [name]
-toloka config set <name> <value>
-toloka project list [--limit <n>]
-toloka project add [alias] [projectId]
-toloka project switch <alias>
-toloka project current
-toloka project url
-toloka project remove <alias>
-toloka project create [alias] [--name <name>] [--team-id <id>] [--delivery-order-id <id>]
-toloka project untrack <pipeline|dataset> <name> [--confirm]
-toloka project token [--preset <name>] [--permissions <list>] [--expires-in <seconds>] [--projects <list>]
-toloka project tokens
-toloka project revoke-token <tokenId>
-toloka project revoke-tokens
-toloka delivery-order list
-toloka audience specialization list [--json]
-toloka init
-toloka import [projectId]
-toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]
-toloka validate
-toloka plan
-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>
-toloka pipeline list [--limit <n>]
-toloka pipeline run [name] [--wait] [--timeout <ms>]
-toloka pipeline status [name]
-toloka pipeline runs [name] [--limit <n>]
-toloka pipeline cost [name] [--item-limit <n>]
-toloka pipeline results <runId> [--limit <n>] [--failed]
-toloka pipeline cancel <runId>
-toloka base-model list [--json]
-toloka base-model get <id> [--json]
-toloka model list [--json]
-toloka model get <name-or-id> [--json]
-toloka model versions <name-or-id> [--json]
-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> [--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|1/4|1/8|1/16|1/32] [--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|1/4|1/8|1/16|1/32] [--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 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]
-```
+## Find commands and catalogs
 
-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.
+Run `toloka --help` and `toloka <command> --help` for the exact commands and options of the installed version. The commands fall into these groups:
 
-`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.
+- sign-in and settings: `login`, `logout`, `auth-status` (`whoami`), `config`, `version`;
+- projects and tokens: `project` (`list`, `add`, `switch`, `current`, `url`, `remove`, `create`, `untrack`, `token`, `tokens`, `revoke-token`, `revoke-tokens`), `delivery-order list`;
+- source reconciliation: `init`, `import`, `check`, `validate`, `plan`, `apply`, `status`, `secret set`;
+- catalogs: `audience specialization list`, `generation-model list`, `ui components`;
+- data and runs: `dataset` (`list`, `create`, `fields`, `load`, `upload`), `pipeline` (`list`, `run`, `status`, `runs`, `cost`, `results`, `cancel`);
+- models and training: `base-model`, `model` (including `model version download`), `training`;
+- skills and reports: `skill` (`list`, `search`, `install`), `report`.
 
-`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.
+`toloka audience specialization list` prints the global specialization catalog: `ID`, `NAME`, and `EXPERTS` columns (`--json` for the array). Run it before setting `audience.specializations` on a node, pick entries by name, and copy `ID` into `qualificationId` and `NAME` into `value`; never invent a `qualificationId`. `EXPERTS` counts ID-verified experts currently eligible for tasks; a `0` means the id is valid but nobody currently qualifies, so prefer another specialization or widen the audience.
 
-`toloka audience specialization list` prints the global specialization catalog: `ID`, `NAME`, and `EXPERTS` columns sorted by name (`--json` for the array). Run it before setting `audience.specializations` on a node, pick entries by name, and copy `ID` into `qualificationId` and `NAME` into `value`; never invent a `qualificationId`. `EXPERTS` counts ID-verified experts currently eligible for tasks; a `0` means the id is valid but nobody currently qualifies, so prefer another specialization or widen the audience.
+`toloka generation-model list` prints the synthetic generation models: `ID`, `NAME`, the supported `REASONING EFFORT` values with the default marked, and the `TYPICAL`, `MIN` and `MAX` cost of one attempt, followed by `Default model:` and, when there are any, `Recommended:` lines (`--json` adds descriptions). Run it before configuring a synthetic node.
 
 `toloka pipeline cost [name] [--item-limit <n>]` forecasts what a run of a live, validated pipeline would bill. It does not start a run or change the graph. If any billed node is marked `skipped`, the displayed total is incomplete and must not be presented as the pipeline price. Compute and label a labor floor for each skipped billed node as `items × pricePerTask × annotations per item`, using `1` for generation and `overlap` for quorum. Also report `maxEntities`, quality-criteria count, and only exclusions applicable to the authored QA and workflow. Apply accepting a rate does not prove its final billed value. If the output lists warnings, include them when you present the forecast.
 
 ## Manage model checkpoints
 
-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.
+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. `toloka model version download <model-version> --out <directory>` downloads and verifies a Model Version's content; uploading and validating a Model Version have no command yet.
 
 ## Train a model
 
 `toloka training create` requires one source (`--base-model` or `--model-version`) and a training Dataset. A `--model-version` source must be a LoRA adapter Model Version (one produced by fine-tuning) and works for both methods — SFT continues the adapter, gisting merges it and trains gist tokens over it; a full-weights version is rejected with "Training from a Model Version requires a LoRA adapter source". The first Training Run creates a new output Model named after the Training; a source Model Version is only the training parent, never the output binding.
 
-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` (default `1/8`) is gisting-only — passing one to the other method fails before any request. `--gist-tokens` takes an absolute count `8|32|64` or a fraction of the prompt being compressed (`1/4`, `1/8`, `1/16`, `1/32`), which the run resolves to `ceil(prompt tokens / N)` clamped to 8..256. `--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.
+Hyperparameters are optional flags on `training create` and `training update`; the `toloka-fine-tuning` and `toloka-gisting` skills list their ranges and defaults. `--lora-rank` is SFT-only and `--gist-tokens` gisting-only: passing one to the other method fails before any request. `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. `training cancel` before training starts is free; on a run that is already training it stops the GPU job, and the run is charged only for the GPU seconds used until then and produces no Model Version.
 
-## Adopt an existing live project
-
-1. Install `@toloka-platform/sdk` in the intended source root.
-2. Run `toloka project add <alias> <projectId>`, or `toloka project switch <alias>` when the project is already registered.
-3. Run `toloka import` into the empty source root.
-4. Run `toloka init` to install or refresh the agent entry points without rebinding project identity.
-5. Confirm `toloka.json.projectId` equals `toloka project current`, then run `toloka plan` before editing and require `No changes.`. A non-empty baseline is importer or live-state drift to understand separately from your change.
-6. Inspect every generated `pipelines/**/pipeline.ts` dependency, preserve constructor `id` options that bind source to the existing graph, and make the smallest source change.
-7. Validate offline, plan, apply, and plan again. Never copy imported IDs to unrelated declarations or invent replacements.
-
-Import refuses an existing `pipelines/` directory. Pass `--force` to replace it with the live graph as TypeScript. Never use `--force` as a harmless refresh over uncommitted source work.
-
-## Author against a project from scratch
-
-1. Run `toloka project create <alias>` for a new project, or `toloka project add <alias> <projectId>` for an existing empty project.
-2. Run `toloka init` after creation. For an existing empty project, run `toloka --project-id <projectId> init`. Then require `toloka project current` and `toloka.json` to name the same project.
-3. Create `pipelines/<name>/pipeline.ts` and its imported modules.
-4. Default-export `definePipeline({ dataset, fields, nodes, connections })`.
-5. Add typed node and pipeline-flow tests, then run `toloka check`.
-6. Run `toloka validate`; a not-yet-created pipeline is reported as skipped, not server-validated.
-7. Run `toloka plan` and resolve missing secrets or immutable-field conflicts.
-8. Run `toloka apply`; it reruns `toloka check` before any platform write.
-9. Require a final `toloka plan` to print `No changes.`
-
-On first apply, the CLI creates each missing named dataset, adds fields required by the authored graphs, creates each missing pipeline, attaches its dataset, and records the resolved IDs. Two pipelines that name the same dataset contribute the union of their required fields.
-
 ## Check locally and validate against the platform
 
 Run the complete local gate first, then validate every bound pipeline remotely:
 
 ```sh
 toloka check
-toloka validate
+toloka validate          # before apply
+toloka validate --wait   # after apply: waits for the platform's lints
 ```
 
-`toloka check` requires no credentials or live pipeline. It loads source, runs the project TypeScript compiler, typechecks every Task UI against the SDK's bundled declarations, runs Vitest, and compares passing typed test evidence with every checkable node and pipeline. Use `toloka check <pipeline> --node <name-or-id>` for a focused edit loop, `--watch` for serialized reruns, and `--json` for automation. `missing` means required evidence was not produced; `failed` means a check ran and failed; `partial` means hardware-backed behavior remains unverified; `infrastructure_error` means a required tool, browser, or launcher could not run. All four block apply.
+`toloka check` requires no credentials or live pipeline; SKILL.md describes what it runs and what its statuses mean. Use `toloka check <pipeline> --node <name-or-id>` for a focused edit loop, `--watch` for serialized reruns, and `--json` for automation.
 
 With `--watch --json`, each completed rerun writes one JSON line. Do not start another watcher while one is active.
 
-`toloka validate` posts each authored graph to the platform. Distinguish source/spec errors, which require source changes; Remote Node Check state; and warnings. A lint `not_ran_node_check` is a blocking remote-validation error, while other check types can report the same code as a warning; neither replaces the Local Check Gate. Validation does not write the graph. A pipeline that is not on the platform yet is skipped until `toloka apply` creates it. When plan adds a dataset field used by an already-live pipeline, pre-apply validation can report that exact field as `misconfigured_node_form_component` because the column is not live yet. Treat it as expected only when the reviewed plan adds the same field, then require post-apply validation to clear the source/spec error.
+`toloka validate` posts each authored graph to the platform without writing it; the status table in SKILL.md lists what each result means and when to use `--wait`. Distinguish source/spec errors, which require source changes, from check state and warnings. When plan adds a dataset field used by an already-live pipeline, pre-apply validation can report that exact field as `misconfigured_node_form_component` because the column is not live yet. Treat it as expected only when the reviewed plan adds the same field, then require post-apply validation to clear the source/spec error.
 
 The authored API still supplies extra local safety:
 
@@ -257,11 +79,11 @@ The authored API still supplies extra local safety:
 - It rejects a `connect()` endpoint whose node is absent from `nodes`.
 - Typed ports prevent reversing input and output handles.
 
-`toloka apply` runs the full Local Check Gate again before resolving credentials or writing platform state. Plan compares source with live resources but does not submit the desired graph for acceptance. Apply can still expose graph-wide references, layout identity, or concurrent-version assumptions that only the backend owns.
+`toloka apply` runs the full local gate, `toloka check`, again before resolving credentials or writing platform state. Plan compares source with live resources but does not submit the desired graph for acceptance. Apply can still expose graph-wide references, layout identity, or concurrent-version assumptions that only the backend owns.
 
 ## Read and apply a plan
 
-Treat every plan line as evidence of what apply will attempt.
+Treat every plan line as evidence of what apply will attempt. `toloka plan --json` prints the same plan as `{ "changes": [...], "missingSecrets": [...] }`, where each change has `kind`, `action`, `label`, and, when they apply, `pipeline`, `dataset`, and `id`.
 
 - Confirm additions and changes match the request.
 - Stop on an unexpected removal. Apply refuses to delete tracked pipelines or datasets merely because their source entry disappeared.
@@ -269,21 +91,9 @@ Treat every plan line as evidence of what apply will attempt.
 - Set every secret listed as missing before apply.
 - If imported source contains live IDs, preserve them while editing around them.
 
-Apply preserves existing live layout and the root's live item filter. Do not add either to authored source. For graph replacement, apply reads the live graph version and sends it as `expectedVersion`; never put a version in source or state yourself.
-
-## Test pipeline nodes locally
-
-Register every code-node behavior with `test.code(pipeline, node, name, callback)`. Its callback receives a bound `run(inputs, options?)` helper with the same Python execution contract as `runCodeNode`; the test counts only after the bound executor runs, an assertion executes, and the callback passes.
+Apply preserves the canvas position of existing nodes and the root's live item filter. Do not add either to authored source; SKILL.md says where the server places new nodes. For graph replacement, apply reads the live graph version and sends it as `expectedVersion`; never put a version in source or state yourself.
 
-Before choosing component names or props, run `toloka ui components` to list the launcher's components and `toloka ui components <name> [name...]` for their contracts (on an SDK without the `ui` command, use the `ui` fixture argument of `test` from `@toloka-platform/sdk/testing` in a throwaway spec and delete it afterwards). 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 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
-```
-
-Plain Vitest tests still run and can fail the command, but only typed Toloka wrappers satisfy required node and pipeline coverage. Use synthetic or redacted data. `preprocess` and `postprocess` remain runtime JavaScript function bodies, not TypeScript.
+On first apply, the CLI creates each missing named dataset, adds fields required by the authored graphs, creates each missing pipeline, attaches its dataset, and records the resolved IDs. Two pipelines that name the same dataset contribute the union of their required fields.
 
 ## Add dataset rows
 
@@ -295,7 +105,9 @@ toloka dataset upload <dataset> <file>
 
 The upload file path resolves from the command process's working directory, not from `--source-root`. Use an absolute path when the command runs elsewhere.
 
-The CLI infers the input format from its extension and uploads the original bytes without conversion: `.json` is an array of row objects, `.jsonl` has one object per non-empty line, and `.csv` uses its header row as field names with every value ingested as a string. JSONL is validated locally before upload. If transfer or finalization fails, the CLI cancels the started upload before returning the error, so another upload can start immediately and may reuse the same filename. The dataset does not have to exist yet: when a pipeline in source binds it, upload creates it and declares that pipeline's columns, so rows land in real columns rather than in the raw `uploaded` blob. Upload refuses when no pipeline in source declares a name because it would have no column names to map onto. An id-shaped argument is never created; upload fails when that dataset id does not exist in the project. Upload appends items; applying source never deletes them.
+The CLI infers the input format from its extension and uploads the original bytes without conversion: `.json` is an array of row objects, `.jsonl` has one object per non-empty line, and `.csv` uses its header row as field names with every value ingested as a string. JSONL is validated locally before upload. If transfer or finalization fails, the CLI cancels the started upload before returning the error, so another upload can start immediately and may reuse the same filename. The dataset does not have to exist yet: when a pipeline in source binds it, upload creates it and declares that pipeline's columns, so rows land in real columns rather than in the raw `uploaded` blob. When the dataset does not exist and no pipeline in source declares it, upload refuses, because it would have no column names to map onto; an existing dataset accepts the upload either way. An id-shaped argument is never created; upload fails when that dataset id does not exist in the project. Upload appends items; applying source never deletes them.
+
+After the upload the CLI prints the field types it inferred from the rows. They describe the rows, not the dataset's columns: inference omits enum, length, range, and format constraints, while the columns keep the schemas declared in source. Never edit `field()` declarations to match that list; `toloka plan` is what compares source with the live columns.
 
 If a later upload fails with a schema-incompatibility error, inspect the inferred schema from the first successful upload:
 
@@ -303,7 +115,7 @@ If a later upload fails with a schema-incompatibility error, inspect the inferre
 toloka dataset fields <dataset>
 ```
 
-That prints `field()` declarations for the top-level inferred columns. Use the output to recover stored names and base types, but do not copy it wholesale over stricter source schemas: inference can omit enum, length, range, and format constraints. It does not write source or mutate the dataset.
+That prints the same inferred types as `field()` declarations for the top-level columns. Use them to recover stored names and base types, never to replace stricter source schemas. The command does not write source or mutate the dataset.
 
 Keep item files outside the source tree or gitignored. Never embed sample or production rows in `pipeline.ts` to make reconciliation create them.
 
@@ -311,7 +123,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. 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.
+A run needs an applied pipeline. Apply any requested source changes and verify convergence first; an already-applied unchanged pipeline does not need another apply. SKILL.md covers cost approval, exit codes, and bounded monitoring. The commands below are available operations, not a sequence that requires starting or canceling a run.
 
 ```sh
 toloka pipeline run <name> --wait --timeout 900000
@@ -322,20 +134,10 @@ toloka pipeline results <runId> --failed
 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".
-
-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.
 
 A failed item carries an error, so `toloka pipeline results <runId> --failed` is the fastest path to why a run failed. Report counts and states from that output rather than inferring them from the run having started.
 
-## Work on more than one project
-
-`toloka.json` records exactly one `projectId`, so one checkout targets one project. To drive a second project from the same source — a copy for another customer, or a staging and a production instance — do not overwrite the state file in place. Use a separate checkout, or pass `--project-id` explicitly and keep the state files apart. Overwriting the recorded id silently repoints every later `plan` and `apply` at the wrong project.
-
-Create a second live project with `toloka project create <alias>` or register an existing one with `toloka project add <alias> <projectId>`. After a copy, prove the original is untouched by planning against it and seeing no changes.
-
 ## Set a secret
 
 Reference a secret name from a code node's `envVars`, then provide its value separately:
@@ -352,13 +154,17 @@ Without `--from-env`, `toloka secret set <name>` reads the value from stdin. Nev
 
 ### Field schema conflict
 
-Do not rename the live field in place, delete it, or retry apply. Keep the existing field untouched and either:
+Dataset fields are immutable after creation: they can be added, never altered or removed. Do not rename the live field in place, delete it, or retry apply. Keep the existing field untouched and either:
 
 1. declare a differently named `field()` with the new schema and migrate downstream node references, or
 2. change `definePipeline({ dataset })` to a new dataset name.
 
 Plan again and inspect the full rebind or new-column diff before applying.
 
+### Unreadable field schema
+
+`toloka import` writes a field whose stored JSON Schema is not valid JSON or not a supported schema as `invalidJsonSchema({ field, reason, text })`, and every command that loads the source fails on it. Replace the call with a valid JSON Schema object, keeping what the stored `text` meant when it is clear and asking the user when it is not, then plan and apply: the apply writes the schema and repairs the field.
+
 ### Missing secret
 
 Use the exact name reported by plan. Set it with `toloka secret set`, rerun plan, and apply only when no secret is marked missing.
@@ -373,8 +179,8 @@ Object settings preserve omitted live keys, but list-valued settings such as con
 
 ### Server 400 after a clean validate
 
-A new pipeline is skipped by `toloka validate` until it exists remotely, and apply can create its dataset and fields before pipeline import returns a 400. Fix the reported path or reason, then run plan again. If only the pipeline addition remains, continue from that diff; do not recreate or rename resources already created. Check connection endpoints, duplicate or unknown imported IDs, field references, and accidentally authored layout. Never bypass reconciliation with a raw API call.
+A new pipeline is skipped by `toloka validate` until it exists remotely, and apply can create its dataset and fields before pipeline import returns a 400. Fix the reported path or reason, then run plan again. If only the pipeline addition remains, continue from that diff; do not recreate or rename resources already created. If the rejection means a newly created field schema is wrong, that field is already immutable: follow the field schema conflict rule, prefer the option that preserves names the request fixes, and report the orphaned field instead of deleting it. Check connection endpoints, duplicate or unknown imported IDs, field references, and accidentally authored layout. Never bypass reconciliation with a raw API call.
 
-## Use the shipped example
+### Platform connection lost
 
-Read `node_modules/@toloka-platform/sdk/examples/face-image-collection/pipeline.ts`, its `fields.ts`, and its `nodes/` modules for a real composition of `field`, `root`, `generation`, `code`, `connect`, and `definePipeline`. Copy its source organization, not its task-specific settings.
+Inside a platform agent sandbox the CLI reaches the platform through the sandbox's connection and retries, for about 90 seconds, every request that connection reports as never sent. `Hint: The sandbox lost its connection to the platform … the request was not sent` therefore means nothing changed on the platform: retry the same command in a minute. Any other `5xx` may have reached the platform, so before repeating a command that changes state (`apply`, `dataset upload`, `pipeline run`), check whether it already took effect with the matching list or status command.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Create, estimate, start, monitor, and verify a project-owned supervised fine-tuning (SFT with LoRA adapters) Training through the Toloka CLI. Use when the user wants to adapt a base model or an existing LoRA Model Version from labeled conversations.
 ---
 
 # Fine-tune a model with Toloka

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

@@ -66,7 +66,7 @@ Read the installed skill before acting. Refresh a stale skill with `--force`; do
 - 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.
+- 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 run `toloka validate --wait`. 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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Create, estimate, start, monitor, and verify a project-owned prompt-gisting Training through the Toloka CLI, which learns soft prompt tokens that stand in for a long static system prompt. Use when the user wants a compact or cheaper replacement for a fixed prompt, learned from example conversations and the prompt file.
 ---
 
 # Compress a prompt with gisting

package/src/authoring/index.ts

@@ -240,20 +240,20 @@ export type UnboundPipelineGraphV1 = {
 };
 
 export type PipelineDefinitionInput<DatasetName extends string = string> = {
-  readonly dataset: DatasetName;
+  readonly dataset?: DatasetName;
   readonly fields: ReadonlyArray<Field>;
   readonly nodes: ReadonlyArray<PipelineNode>;
   readonly connections: ReadonlyArray<Connection>;
 };
 
 export type PipelineDefinition<DatasetName extends string = string> = {
-  readonly dataset: DatasetName;
+  readonly dataset?: DatasetName;
   readonly graph: UnboundPipelineGraphV1;
   readonly [PIPELINE_DEFINITION]: true;
 };
 
 export type PipelineDefinitionBindings = {
-  readonly datasetId: string;
+  readonly datasetId?: string;
 };
 
 function hash(value: string): string {
@@ -447,6 +447,18 @@ export function field<const Name extends string>(
   };
 }
 
+export type InvalidJsonSchemaSource = {
+  readonly field: string;
+  readonly reason: string;
+  readonly text: string;
+};
+
+export function invalidJsonSchema(source: InvalidJsonSchemaSource): never {
+  throw new Error(
+    `Field "${source.field}" has an unreadable JSON Schema on the platform. ${source.reason} Its stored text is in fields.ts as invalidJsonSchema({ text }); replace that call with a valid JSON Schema object for the field.`,
+  );
+}
+
 export function optional(referencedField: Field): OptionalFieldBinding {
   return { field: referencedField, optional: true };
 }
@@ -547,6 +559,7 @@ export function match(
       ...wireSettings,
       conditions: conditions.map((condition) => ({
         ...condition,
+        logic: condition.logic ?? "and",
         predicates: condition.predicates.map(({ field: referencedField, ...predicate }) => ({
           ...predicate,
           fieldProxyId: referencedField.id,
@@ -610,7 +623,7 @@ export function connect(
 export function definePipeline<const DatasetName extends string>(
   definition: PipelineDefinitionInput<DatasetName>,
 ): PipelineDefinition<DatasetName> {
-  assert(definition.dataset.length > 0, "Dataset name must not be empty");
+  assert(definition.dataset !== "", "Dataset name must not be empty");
   const declaredFields = new Set(definition.fields);
   const declaredFieldIds = new Set<string>();
   for (const declaredField of definition.fields) {
@@ -645,7 +658,7 @@ export function definePipeline<const DatasetName extends string>(
   }
 
   return {
-    dataset: definition.dataset,
+    ...(definition.dataset === undefined ? {} : { dataset: definition.dataset }),
     [PIPELINE_DEFINITION]: true,
     graph: {
       version: 1,
@@ -682,7 +695,7 @@ export function validatePipelineDefinition(value: unknown): asserts value is Pip
     isPipelineDefinition(value),
     "Invalid pipeline definition: expected a value returned by definePipeline",
   );
-  assert(value.dataset.length > 0, "Dataset name must not be empty");
+  assert(value.dataset !== "", "Dataset name must not be empty");
   for (const node of value.graph.nodes) {
     if (node.type !== "root") continue;
     assert(
@@ -706,7 +719,13 @@ export function resolvePipelineDefinition(
     fields: definition.graph.fields.map((fieldDefinition) => ({ ...fieldDefinition })),
     nodes: definition.graph.nodes.map((node) =>
       node.type === "root"
-        ? { ...node, settings: { ...node.settings, datasetId: bindings.datasetId } }
+        ? {
+            ...node,
+            settings: {
+              ...node.settings,
+              ...(bindings.datasetId === undefined ? {} : { datasetId: bindings.datasetId }),
+            },
+          }
         : node,
     ),
     connections: definition.graph.connections.map((connection) => ({

package/src/checks/task-ui-typecheck.ts

@@ -70,7 +70,7 @@ ${input.data}
 }
 
 declare global {
-const CONST: /* CONST_INJECTION_START */
+const taskUiConstantsForCodeOnly: /* CONST_INJECTION_START */
 (
 ${input.constants}
 )
@@ -89,11 +89,11 @@ ${input.postprocess}
 }
 /* POSTPROCESS_INJECTION_END */ )()
 
-/* CODE_INJECTION_START */
+((CONST: typeof taskUiConstantsForCodeOnly) => /* CODE_INJECTION_START */
 (
 ${input.code}
 )
-/* CODE_INJECTION_END */
+/* CODE_INJECTION_END */ )
 
 export {}`;
 

package/src/cli/analytics.ts

@@ -109,6 +109,7 @@ const COMMAND_GROUPS: Readonly<Record<string, CommandGroup>> = {
     logs: true,
   },
   "base-model": { list: true, get: true },
+  "generation-model": { list: true },
   model: {
     list: true,
     get: true,