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

package/dist/cli/toloka.js.jsc.sha256

@@ -1 +1 @@
-9ad43de333dbe074807e30a8c4dcac3218b8da3d35dcb5b9f73de5a828e0e1a5  toloka.js.jsc
+ee914e999937f98c40a657d10640ea64acda93b2e50f4a9306e25453c8897248  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-d94c96d189b79c2a18acad2d61fe57da2c580dc0219094434e1e44e822bcd7f0  toloka.js
+fabf11ce7545f788c03870778c18deda006d89c95c839ae8c1592f4eaa287366  toloka.js

package/docs/cli-v2.md

@@ -86,14 +86,14 @@ toloka project remove cat-labeling           # local unbind only
 
 `project add` with no arguments prompts for alias and id, like `wmill workspace add`. The new alias becomes `current`.
 
-Create a live project and bind it in one step. External teams omit `--delivery-order-id`. Internal users (`whoami` prints `Internal: true`) must pass an active id from `toloka delivery-order list`:
+Create a live project and bind it in one step. The delivery order follows the owning team, not the account (`toloka whoami` marks internal teams `(internal)` on its `Teams:` line): a project in an internal team must carry an active id from `toloka delivery-order list`, and a project in an external team must not carry one, even when the account is internal:
 
 ```sh
 toloka project create cat-labeling --team-id <teamId>
 toloka project create cat-labeling --team-id <teamId> --delivery-order-id <orderId>
 ```
 
-`POST /projects` requires `teamId`. There is no public team-list endpoint today, so `--team-id` is required unless every visible project shares one team, in which case we reuse that id. If teams differ, refuse and ask.
+`POST /projects` requires `teamId`. `GET /me` lists the caller's teams with their write access, so `--team-id` is optional when the account has exactly one writable team; with several, the CLI refuses and names them.
 
 `project create` writes the machine alias, sets `current`, and if cwd has no `toloka.json`, writes one.
 
@@ -126,6 +126,7 @@ Resource commands never search the disk for a pipeline first. They load the proj
 | `plan` / `apply` / `validate` | whole project                 | no                 |
 | `secret set`                  | project                       | no                 |
 | `dataset list`                | project                       | no                 |
+| `dataset create <name>`       | project                       | no                 |
 | `dataset fields <name>`       | named dataset in this project | no                 |
 | `dataset load <name>`         | named dataset in this project | no                 |
 | `dataset upload <name>`       | named dataset in this project | no                 |

package/docs/cli.md

@@ -49,6 +49,10 @@ The root program accepts these flags before any command:
 
 Commands resolve the project root by walking up from the working directory until they find a `toloka.json` file. The CLI reports that directory on stderr when it differs from the working directory. Passing `--source-root` disables discovery. With no marker found, the working directory is used. `init` and `report` do not walk up: they use the working directory or `--source-root` only. The authentication commands `login`, `logout`, and `auth-status` do not need a project root.
 
+## Errors and hints
+
+A failing command prints its message to stderr and exits `1`. Most messages are followed by a `Hint: …` line with the next command to run; messages that already spell out the remedy carry no hint. Platform failures print `Potato API request failed with status <code> (request id: <id>)`, the response body, and a status-based hint: `401`/`403` point at `toloka whoami` and `toloka login`, `404` at the selected project and the matching list command, `429` asks you to wait, and `5xx` asks you to retry and then send a report with `toloka report <report.md>`.
+
 ## Resources and Base Actions
 
 The CLI is resource-first: `toloka <resource> <action>`. A Base Action has one meaning wherever a resource implements it. A resource exposes only the Base Actions that have real behavior; there are no placeholder actions.
@@ -86,7 +90,7 @@ toloka project create [alias] [--name <name>] [--team-id <id>] [--delivery-order
 toloka project untrack <pipeline|dataset> <name> [--confirm]
 ```
 
-`add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `TOLOKA_*` when those would select a different key or platform than the stored file. `project list` prints project id, name, and team id. `create` reuses the only visible team when every listed project shares one; otherwise pass `--team-id`. Internal users (`whoami` prints `Internal: true`) also see `--delivery-order-id` and `toloka delivery-order list`.
+`add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `TOLOKA_*` when those would select a different key or platform than the stored file. `project list` prints project id, name, and team id. `create` uses the account's only writable team (`GET /me` lists the teams; `whoami` prints them) and asks for `--team-id` when there are several. A project owned by an internal team also needs `--delivery-order-id`; `toloka delivery-order list` shows the orders and answers with an explanation for accounts without internal teams.
 
 `project untrack` removes one pipeline or dataset binding from `toloka.json` without deleting the live resource. It previews the name and id in a terminal; outside a terminal, pass `--confirm` after reviewing the state file.
 
@@ -96,7 +100,7 @@ toloka project untrack <pipeline|dataset> <name> [--confirm]
 
 ## delivery-order
 
-Internal users only. Listed in `toloka --help` and available as a command when `whoami` prints `Internal: true`.
+Lists the Sunday delivery orders this key can attach on `project create`. The command is always registered; the platform answers `403` for accounts without an internal team, which the CLI reports as `Delivery orders are available to internal teams only.`
 
 ```sh
 toloka delivery-order list
@@ -135,7 +139,7 @@ Shows which platform and key the CLI would use. Alias: `whoami`.
 toloka auth-status [--show-token]
 ```
 
-On success it prints the platform URL with its source, the API key masked unless `--show-token` is passed, the selected project, `Reachable: N project(s) visible.`, and `Internal: true` or `Internal: false`. The project line is printed even when the probe fails. It exits `1` when no key is in effect, when the platform rejects the key (`Rejected: …`, followed by the advice to run `toloka login`), when the platform does not answer (`Not reachable: …`; the key was not evaluated), or when the platform fails (`Platform error: …`).
+On success it prints the platform URL with its source, the API key masked unless `--show-token` is passed, the selected project, `Reachable: N project(s) visible.`, `Internal: true` or `Internal: false` for the account, and a `Teams:` line that marks each team `(internal)` and `(read-only)` where that applies. The project line is printed even when the probe fails. It exits `1` when no key is in effect, when the platform rejects the key (`Rejected: …`, followed by the advice to run `toloka login`), when the platform does not answer (`Not reachable: …`; the key was not evaluated), or when the platform fails (`Platform error: …`).
 
 ## config
 
@@ -267,7 +271,7 @@ toloka base-model list [--json]
 toloka base-model get <id> [--json]
 ```
 
-Human-readable output is the default. `base-model list` prints aligned ID, name, provider, and upstream-model columns; `base-model get` prints labeled fields including the pinned revision. Pass `--json` for machine-readable output.
+Human-readable output is the default. `base-model list` prints aligned ID, name, provider, upstream-model, revision (first 12 characters) and upstream-snapshot URL columns; `base-model get` prints labeled fields including the full pinned revision and the `https://huggingface.co/<model>/tree/<revision>` snapshot URL. Pass `--json` for machine-readable output.
 
 ## model
 
@@ -283,12 +287,34 @@ toloka model archive <name-or-id> [--json]
 
 `model create` creates project-owned Model metadata linked to one catalog Base Model; it does not create a Model Version. Human-readable output is the default for every command in this group. Pass `--json` for machine-readable objects or arrays. Weight upload, validation, download, and Model Version creation are deferred.
 
+## training
+
+Create a reusable Training draft, price it, and run it.
+
+```sh
+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] [--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 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>
+toloka training metrics <training-run-id> [--key <metric>] [--resolution <n>] [--json]
+```
+
+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. `training get` prints the resolved recipe, so omitted flags are visible as their defaults.
+
 ## dataset
 
 Catalog and row commands for datasets in the selected project. Name or id is accepted; duplicate names must be addressed by id.
 
 ```sh
 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>
@@ -296,6 +322,8 @@ toloka dataset upload <name> <file>
 
 `dataset list` prints live `name` and id. It does not page items.
 
+`dataset create` makes an empty dataset in the selected project; the first `dataset upload` infers its columns from the rows.
+
 `dataset fields` prints inferred `field()` TypeScript, or `Dataset <name> has no inferred fields yet.`
 
 `dataset load` starts a platform export, waits for it (default 60s; pass `--timeout`), downloads the JSON array, and writes JSONL to `--out`. `--limit` slices after download; it still waits for the full export. On timeout the message names the export id. Failed downloads and invalid payloads leave `--out` untouched.

package/openapi/gen/models/baseModel.ts

@@ -6,4 +6,5 @@ export interface BaseModel {
   provider: string;
   upstreamModel: string;
   upstreamRevision: string;
+  upstreamUrl: string;
 }

package/openapi/gen/models/currentUser.ts

@@ -1,7 +1,9 @@
 import type { CurrentUserEmail } from './currentUserEmail';
+import type { CurrentUserTeamsItem } from './currentUserTeamsItem';
 
 export interface CurrentUser {
   id: string;
   email: CurrentUserEmail;
   internal: boolean;
+  teams: CurrentUserTeamsItem[];
 }

package/openapi/gen/models/currentUserTeamsItem.ts

@@ -0,0 +1,6 @@
+
+export type CurrentUserTeamsItem = {
+  id: string;
+  writable: boolean;
+  internal: boolean;
+};

package/openapi/gen/models/gistingTrainingConfiguration.ts

@@ -1,6 +1,7 @@
 import type { TrainingModelSource } from './trainingModelSource';
 import type { TrainingDatasetSelection } from './trainingDatasetSelection';
-import type { GistingTrainingConfigurationRegime } from './gistingTrainingConfigurationRegime';
+import type { GistingTrainingConfigurationGistTokens } from './gistingTrainingConfigurationGistTokens';
+import type { GistingTrainingConfigurationBatchSize } from './gistingTrainingConfigurationBatchSize';
 
 export interface GistingTrainingConfiguration {
   method: 'gisting';
@@ -8,6 +9,9 @@ export interface GistingTrainingConfiguration {
   training: TrainingDatasetSelection;
   validation?: TrainingDatasetSelection;
   promptFileId: string;
-  regime: GistingTrainingConfigurationRegime;
+  gistTokens: GistingTrainingConfigurationGistTokens;
   epochs: number;
+  learningRate: number;
+  batchSize: GistingTrainingConfigurationBatchSize;
+  maxSequenceLength: number;
 }

package/openapi/gen/models/gistingTrainingConfigurationBatchSize.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationBatchSize = 8 | 16 | 32 | 64;

package/openapi/gen/models/gistingTrainingConfigurationGistTokens.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationGistTokens = 8 | 32 | 64;

package/openapi/gen/models/gistingTrainingConfigurationInput.ts

@@ -1,6 +1,7 @@
 import type { TrainingModelSource } from './trainingModelSource';
 import type { TrainingDatasetSelectionInput } from './trainingDatasetSelectionInput';
-import type { GistingTrainingConfigurationInputRegime } from './gistingTrainingConfigurationInputRegime';
+import type { GistingTrainingConfigurationInputGistTokens } from './gistingTrainingConfigurationInputGistTokens';
+import type { GistingTrainingConfigurationInputBatchSize } from './gistingTrainingConfigurationInputBatchSize';
 
 export interface GistingTrainingConfigurationInput {
   method: 'gisting';
@@ -8,6 +9,9 @@ export interface GistingTrainingConfigurationInput {
   training: TrainingDatasetSelectionInput;
   validation?: TrainingDatasetSelectionInput;
   promptFileId: string;
-  regime?: GistingTrainingConfigurationInputRegime;
+  gistTokens?: GistingTrainingConfigurationInputGistTokens;
   epochs?: number;
+  learningRate?: number;
+  batchSize?: GistingTrainingConfigurationInputBatchSize;
+  maxSequenceLength?: number;
 }

package/openapi/gen/models/gistingTrainingConfigurationInputBatchSize.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationInputBatchSize = 8 | 16 | 32 | 64;

package/openapi/gen/models/gistingTrainingConfigurationInputGistTokens.ts

@@ -0,0 +1,2 @@
+
+export type GistingTrainingConfigurationInputGistTokens = 8 | 32 | 64;

package/openapi/gen/models/index.ts

@@ -110,6 +110,7 @@ export * from './createTrainingRunBody';
 export * from './createdDatasetFields';
 export * from './currentUser';
 export * from './currentUserEmail';
+export * from './currentUserTeamsItem';
 export * from './dataset';
 export * from './datasetExportReport';
 export * from './datasetExportReportErrorsItem';
@@ -264,9 +265,11 @@ export * from './getDatasetInferredFields200';
 export * from './getTrainingRunLogsParams';
 export * from './getTrainingRunMetricHistoryParams';
 export * from './gistingTrainingConfiguration';
+export * from './gistingTrainingConfigurationBatchSize';
+export * from './gistingTrainingConfigurationGistTokens';
 export * from './gistingTrainingConfigurationInput';
-export * from './gistingTrainingConfigurationInputRegime';
-export * from './gistingTrainingConfigurationRegime';
+export * from './gistingTrainingConfigurationInputBatchSize';
+export * from './gistingTrainingConfigurationInputGistTokens';
 export * from './importPipelineBody';
 export * from './inferredField';
 export * from './inferredFieldJsonSchema';
@@ -821,9 +824,11 @@ export * from './sampleJobStatus';
 export * from './sampleResult';
 export * from './setProjectSecretBody';
 export * from './sftTrainingConfiguration';
+export * from './sftTrainingConfigurationBatchSize';
 export * from './sftTrainingConfigurationInput';
-export * from './sftTrainingConfigurationInputRegime';
-export * from './sftTrainingConfigurationRegime';
+export * from './sftTrainingConfigurationInputBatchSize';
+export * from './sftTrainingConfigurationInputLoraRank';
+export * from './sftTrainingConfigurationLoraRank';
 export * from './training';
 export * from './trainingArchivedAt';
 export * from './trainingConfiguration';

package/openapi/gen/models/sftTrainingConfiguration.ts

@@ -1,13 +1,16 @@
 import type { TrainingModelSource } from './trainingModelSource';
 import type { TrainingDatasetSelection } from './trainingDatasetSelection';
-import type { SftTrainingConfigurationRegime } from './sftTrainingConfigurationRegime';
+import type { SftTrainingConfigurationLoraRank } from './sftTrainingConfigurationLoraRank';
+import type { SftTrainingConfigurationBatchSize } from './sftTrainingConfigurationBatchSize';
 
 export interface SftTrainingConfiguration {
   method: 'sft';
   source: TrainingModelSource;
   training: TrainingDatasetSelection;
   validation?: TrainingDatasetSelection;
-  regime: SftTrainingConfigurationRegime;
+  loraRank: SftTrainingConfigurationLoraRank;
   epochs: number;
-  evalSteps: number;
+  learningRate: number;
+  batchSize: SftTrainingConfigurationBatchSize;
+  maxSequenceLength: number;
 }

package/openapi/gen/models/sftTrainingConfigurationBatchSize.ts

@@ -0,0 +1,2 @@
+
+export type SftTrainingConfigurationBatchSize = 8 | 16 | 32 | 64;

package/openapi/gen/models/sftTrainingConfigurationInput.ts

@@ -1,13 +1,16 @@
 import type { TrainingModelSource } from './trainingModelSource';
 import type { TrainingDatasetSelectionInput } from './trainingDatasetSelectionInput';
-import type { SftTrainingConfigurationInputRegime } from './sftTrainingConfigurationInputRegime';
+import type { SftTrainingConfigurationInputLoraRank } from './sftTrainingConfigurationInputLoraRank';
+import type { SftTrainingConfigurationInputBatchSize } from './sftTrainingConfigurationInputBatchSize';
 
 export interface SftTrainingConfigurationInput {
   method: 'sft';
   source: TrainingModelSource;
   training: TrainingDatasetSelectionInput;
   validation?: TrainingDatasetSelectionInput;
-  regime?: SftTrainingConfigurationInputRegime;
+  loraRank?: SftTrainingConfigurationInputLoraRank;
   epochs?: number;
-  evalSteps?: number;
+  learningRate?: number;
+  batchSize?: SftTrainingConfigurationInputBatchSize;
+  maxSequenceLength?: number;
 }

package/openapi/gen/models/sftTrainingConfigurationInputBatchSize.ts

@@ -0,0 +1,2 @@
+
+export type SftTrainingConfigurationInputBatchSize = 8 | 16 | 32 | 64;

package/openapi/gen/models/sftTrainingConfigurationInputLoraRank.ts

@@ -0,0 +1,2 @@
+
+export type SftTrainingConfigurationInputLoraRank = 8 | 16 | 32;

package/openapi/gen/models/sftTrainingConfigurationLoraRank.ts

@@ -0,0 +1,2 @@
+
+export type SftTrainingConfigurationLoraRank = 8 | 16 | 32;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.2.0-preview.3",
+  "version": "0.2.0-preview.4",
   "private": false,
   "description": "Beta. Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change.",
   "license": "Apache-2.0",

package/skills/catalog.json

@@ -11,8 +11,8 @@
         "testing",
         "checks"
       ],
-      "version": "0.2.0-preview.3",
-      "digest": "b5819b5f29ed0876850708e3fbe9b370433ddf68d9548260cf24ff7200104bb6",
+      "version": "0.2.0-preview.4",
+      "digest": "2d27360563da6ff5ef41d264982d89232087cf7c76393022c83a66c5301752b3",
       "files": [
         "SKILL.md",
         "references/node-semantics.md",
@@ -29,7 +29,7 @@
         "bug",
         "report"
       ],
-      "version": "0.2.0-preview.3",
+      "version": "0.2.0-preview.4",
       "digest": "76229bae596f8a1722ce7fc55bea3dd66698df5b61baa31f6cb98ca2b5fa03e8",
       "files": [
         "SKILL.md",
@@ -39,15 +39,15 @@
     {
       "id": "toloka-get-started",
       "name": "Get started with Toloka",
-      "description": "Route a first Toloka agent session to the correct workflow and establish safe CLI, authentication, project, and approval checkpoints. Use when the user is new to Toloka, asks what to do first, or has not selected a pipeline, fine-tuning, or gisting workflow.",
+      "description": "Orient a Toloka session to the user's outcome and safely reuse or establish the needed CLI, authentication, project, workflow, and approval context. Use when the user is new to Toloka, asks what to do first, or has not selected a pipeline, fine-tuning, or gisting workflow.",
       "tags": [
         "toloka",
         "onboarding",
         "getting-started",
         "agent"
       ],
-      "version": "0.2.0-preview.3",
-      "digest": "7e5e2d4b8daab4abece217ca2a00f76ce4e29da6a2724a44a91ff3dc63aec38a",
+      "version": "0.2.0-preview.4",
+      "digest": "f86ba45aba0bf2b06bc02b65c6f3dbb7b9b4cb28630191bafa62b6e627448138",
       "files": [
         "SKILL.md"
       ]
@@ -63,8 +63,8 @@
         "sft",
         "models"
       ],
-      "version": "0.2.0-preview.3",
-      "digest": "967a3e862d4a79f6e6462f2ab6d03241b45c24f5ae5550a453259f01289eb85e",
+      "version": "0.2.0-preview.4",
+      "digest": "81c43af9e78e1df322085dd2ec923e85a7be0d084c689906aa5db6cdbd03c9e3",
       "files": [
         "SKILL.md"
       ]
@@ -80,8 +80,8 @@
         "prompt",
         "models"
       ],
-      "version": "0.2.0-preview.3",
-      "digest": "e7f714ec5681648cba092a1ed737f2e6431da1da47f8f3553c4d774777af644a",
+      "version": "0.2.0-preview.4",
+      "digest": "ee30f006d8f7995a825db5e7c74732e35517d88b43a4f6671d6439f1c333c815",
       "files": [
         "SKILL.md"
       ]

package/skills/toloka-build/SKILL.md

@@ -7,16 +7,25 @@ description: Build, test, inspect, or change Toloka platform pipeline projects a
 
 This SDK is Beta software. The authoring API, the CLI, and generated source can change before general availability. Do not invent helpers or flags that are not in the installed package.
 
-Use this skill when the user has selected pipeline authoring or wants to create, inspect, test, or change a Toloka pipeline project as code. Work in the project source tree; do not translate the request into direct platform API calls.
+Help the user get a working pipeline that fits their task: understand the data and desired output, choose a suitable design, verify it, and apply or run it when requested. Work in the project source tree; TypeScript is the pipeline's desired state, not a transcription of direct platform API calls.
 
 ## Enter the pipeline workflow
 
-When a user is new to Toloka or has not selected a workflow, run `toloka skill install toloka-get-started`, read `.agents/skills/toloka-get-started/SKILL.md`, and follow the matching public runbook first. This skill starts after pipeline work is selected and owns pipeline authoring semantics, local tests, recovery, and evidence reporting.
+For first-time setup or help choosing a workflow, install and read `toloka-get-started` and consult the matching public runbook. Use its onboarding steps where needed; an existing project or a focused inspection request does not need the full first-run journey. A demo is useful for learning, not a prerequisite for the user's own task.
 
-Do not replace the selected runbook's quick demo with another example, and do not run the demo when the user chooses their own task. Never cross its API-key, project-creation, plan, or run-cost checkpoint without the user's required action or approval.
+Use your expertise for routine choices, and briefly explain decisions that affect quality, cost, or maintainability. Ask a focused question when missing requirements or conflicting constraints would materially change the result; do not ask the user to choose SDK mechanics you can determine yourself. Preserve explicit requirements and existing project intent. Credentials belong in the user's `toloka login` prompt, paid runs need cost approval, and destructive or out-of-scope changes need agreement before proceeding.
+
+## Choose a design that fits the task
+
+- Start with representative inputs and the output the user needs. Reuse an existing pipeline or node when it already serves that purpose; prefer the simplest graph that meets the requirements.
+- Use `code` for deterministic transformations, scripts, or programmatic API/LLM calls; `generation` for the platform's human or synthetic generation journey, including original content collection; `quorum` for independent annotations where agreement or disagreement matters; and `match` for conditional routing. `root` defines the input/output boundary.
+- Choose data contracts, audience, instructions, and quality criteria together: the person doing the task should be able to produce the declared output and understand how it will be judged. Let the task and observed data guide these choices rather than copying an example's settings.
+- Treat quality, turnaround, and cost as tradeoffs. Explain meaningful assumptions, and seek clarification for unresolved acceptance criteria rather than inventing business rules. Read [node semantics](references/node-semantics.md) for each selected node's actual capabilities and constraints.
 
 ## Follow the reconciliation loop
 
+For an applied change, the dependencies are read → edit → check/validate → plan → apply → confirm convergence. Iterate locally as needed. For inspection, design, or check-only requests, stop at the requested deliverable rather than creating resources, applying changes, or starting a run merely to finish this sequence.
+
 1. Read `toloka.json` when present, then read the relevant `pipelines/**/pipeline.ts` module and everything it imports.
 2. Edit the TypeScript source. Treat it as authoritative desired state.
 3. Run the complete local gate, then validate each changed pipeline against the platform:
@@ -25,7 +34,7 @@ Do not replace the selected runbook's quick demo with another example, and do no
    toloka validate
    ```
 4. Run `toloka plan`. Read the complete diff and resolve every conflict or missing prerequisite.
-5. Run `toloka apply`. Apply reruns the complete local gate and proceeds only when it passes. Apply only after the plan matches the request.
+5. Show the plan and run `toloka apply` when its changes match the requested work. Resolve removals, immutable-field conflicts, or changes outside that scope with the user first. Apply reruns the complete local gate and proceeds only when it passes.
 6. Run `toloka plan` again and require `No changes.`
 
 The CLI reads source, compares it with live state, and reconciles the platform. Edit files; never mutate a pipeline through raw HTTP, SDK client methods, or internal platform tool calls. Do not make a live edit and then reverse-engineer it into source.
@@ -37,13 +46,15 @@ Use the directory containing `toloka.json` as the source root. Commands default
 - If `toloka.json` exists, read it as CLI-managed identity state and confirm its `projectId` matches `toloka project current` before any plan or apply. It maps the project, pipeline source directories, and dataset names to live IDs. Do not hand-edit it.
 - If it is absent and the user is adopting an existing project, run `toloka project add <alias> <projectId>`, then run `toloka import <projectId>` in the intended source root before `toloka init`. Import refuses an existing `pipelines/` directory unless you pass `--force`.
 - After importing an existing project, run `toloka plan` before editing and require `No changes.`. Resolve importer or live-state drift separately so it cannot be mistaken for your change.
-- If it is absent and the user is authoring from scratch, run `toloka project create <alias>` before `toloka init`. Confirm `toloka project current` and the generated `toloka.json` name the new project before authoring.
+- If it is absent and the user is authoring from scratch, create a project with a task-derived name when a new project is needed. For an intended existing empty project, use `toloka project add <alias> <projectId>` and `toloka --project-id <projectId> init`. Confirm `toloka project current` and the generated `toloka.json` name the intended project before authoring; do not create a duplicate merely because the checkout is unbound.
 
 If `toloka project current` reports `from toloka.json` for a project you did not select in this checkout, stop: project create/add/switch does not rebind an existing checkout. A newly generated state file with empty `pipelines` and `datasets` can be removed before selecting the intended project and rerunning `toloka init`; any state file with live bindings may be someone else's checkout and must not be deleted without user approval.
 
 Never assume a project ID from conversation context. Resolve it from `--project-id`, `TOLOKA_PROJECT_ID`, `toloka.json`, or `toloka project current`.
 
-`project create`, `project add`, and `project switch` also change the machine-level current-project registry used outside a source root. For temporary or evaluation projects, record the previous alias and restore it before finishing. If create requires `--team-id`, use the team from `toloka status --project-id <authorized-project>` only when that project is known to share the intended owner; state the assumption and confirm the new project's team in `toloka project url`. With no such project, ask the user for the team ID.
+An unverified trial account holds one project and one pipeline, and cannot deploy or run. `project create` then fails with `Your trial allows a single project.` and pipeline creation with `Your trial allows a single pipeline.` Adopt the project that already exists instead: register it with `toloka project add <alias> <projectId>`, bind the checkout with `toloka import <projectId>`, and author inside its existing pipeline; the platform has no project delete, so there is nothing to clear. Both limits lift when the user completes identity or business verification from the banner in the platform.
+
+`project create`, `project add`, and `project switch` also change the machine-level current-project registry used outside a source root. For temporary or evaluation projects, record the previous alias and restore it before finishing. Without `--team-id`, create uses the account's only writable team; when `toloka whoami` lists several teams, ask the user which one owns the project and pass it explicitly. Confirm the new project's team in `toloka project url`.
 
 ## Author with the typed graph API
 
@@ -51,23 +62,23 @@ Import authoring helpers from `@toloka-platform/sdk`.
 
 - Declare every data contract once with `field(name, jsonSchema)`.
 - Decide entity cardinality from the task before choosing field schemas or Task UI components. One logical output from one labeler is a static entity, even when a component represents it with an array; only multiple independent outputs are dynamic. For dynamic entities, choose a tight task-grounded `maxEntities` instead of defaulting to 50.
-- Do not invent enum, length, range, format, label-precedence, tie-break, default, exact-phrase, or conditional-requiredness rules absent from the request or observed data. Before apply, list every authored rule the request did not fix—including criteria, quiz answers, and UI validation—as an assumption; choose the least surprising option and carry that list into the final report.
-- Use exactly these constructors: `root`, `code`, `generation`, `match`, and `quorum`.
+- Ground enum, length, range, format, label-precedence, tie-break, default, exact-phrase, and conditional-requiredness rules in the request, observed data, or documented platform requirements. Derive criteria, quiz answers, and UI validation from that evidence. Surface assumptions that affect accepted outputs before apply; if materially different interpretations remain, ask instead of silently deciding the user's business rules.
+- The supported node constructors are `root`, `code`, `generation`, `match`, and `quorum`.
 - Connect typed ports with `connect(from, to)`: `started`, `completed`, `input`, `output`, `matchNode.matched(0)`, and `default`.
 - Export a default `definePipeline({ dataset, fields, nodes, connections })` from every `pipelines/**/pipeline.ts`.
 - Keep the graph acyclic. Put review, retry, training, exam, appeal, and payment behavior in the owning human-work node rather than adding loop nodes.
 
 Let constructors mint IDs for new declarations. Preserve `id` options generated by `toloka import`, but never invent or hand-edit raw `fp_…`, `ds.…`, `pl.…`, or `pp.…` values in authored settings. Never add a `layout` block: layout is not authored, existing layout is preserved, and the server supplies defaults.
 
-Read [node semantics](references/node-semantics.md) before selecting or configuring a node. Use `node_modules/@toloka-platform/sdk/examples/face-image-collection/` as a concrete authoring pattern.
+Use `node_modules/@toloka-platform/sdk/examples/face-image-collection/` as a concrete authoring pattern when relevant; borrow its structure, not its task-specific choices.
 
 ## Get human-work settings right the first time
 
-These are server rules that `definePipeline` does not check. Each one costs an apply or a failed deployment to discover.
+Distinguish server requirements from optional design choices. The following constraints and defaults are not all checked by `definePipeline`:
 
 - **Do not pair `projectType: 'general'` with `verifiedExperts: false`.** The server answers `General projects require an ID-verified audience`. Specializations also require a verified audience.
 - **Training is part of the node, not extra.** A quorum node requires `onboarding`, and while it is enabled the platform wants at least three steps and at least one quiz block. Preserve an explicit `enabled: false` that a user or `toloka import` put there; never switch Training on to satisfy your own sense of completeness.
-- **Do not author placeholder optional settings.** Omit `exam`, non-default QA, audience reuse, and smart-search blocks unless the user requested them or imported source already controls them. An empty disabled block is still authored state.
+- **Optional settings should serve the task.** Exams, non-default QA, audience reuse, and smart search can be useful when the requirements call for them. Omit blocks that add no value rather than copying placeholders; an empty disabled block is still authored state. Preserve imported choices unless changing them is part of the task, and explain additions that affect cost or expert eligibility.
 - **Run scope belongs to the platform.** `itemFilter` and `itemLimit` on the root node are set from the platform, and apply preserves whatever is live unless source declares its own value. Do not add an item limit to source to "restore" one you saw in the UI.
 
 ## Know the validation boundary
@@ -82,7 +93,7 @@ Before choosing Task UI components, call `ui.componentDocumentation()` from a lo
 
 `ui.code` accepts TSX, including TypeScript annotations. `preprocess` and `postprocess` are JavaScript function bodies; do not put TypeScript-only syntax in either transform.
 
-Register code behavior with `test.code(pipeline, node, name, callback)` and execute the bound `run` helper. Add at least one `test.pipeline(pipeline, name, callback)` scenario. 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. Treat the fixture as `root.started` item state, execute connected nodes in order with the callback's bound code and UI helpers, merge only each node's declared outputs, and assert the final `root.completed` fields. One scenario is appropriate for a linear happy path; use separate scenarios for different match branches, optional paths, and failures.
+Register code behavior with `test.code(pipeline, node, name, callback)` and execute the bound `run` helper. Add at least one `test.pipeline(pipeline, name, callback)` scenario. Choose representative fixtures from available data, redacting sensitive values while preserving field names, nesting, optionality, and media/value shapes. Use synthetic cases when needed for privacy or to exercise boundaries absent from the sample. Treat the fixture as `root.started` item state, execute connected nodes in order with the callback's bound code and UI helpers, merge only each node's declared outputs, and assert the final `root.completed` fields. Cover meaningful match branches, optional paths, and failures as well as the happy path.
 
 ## Keep data and credentials out of source
 
@@ -94,7 +105,7 @@ Register code behavior with `test.code(pipeline, node, name, callback)` and exec
 `toloka login` verifies an API key and stores it with owner-only permissions, so no later command needs
 `--api-key`. Precedence is flag, then environment variable (`TOLOKA_API_KEY`, `TOLOKA_BASE_URL`), then
 that file. `toloka auth-status` reports what is in effect and where it came from; `toloka logout`
-removes it. If a command reports missing credentials, run `toloka login`; never invent a key.
+removes it. If credentials are missing, ask the user to run `toloka login` in their terminal; never request a key in chat.
 Anonymous command telemetry is on by default; set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable it.
 A globally installed CLI auto-updates by default; turn that off with `toloka config set auto-update false`.
 
@@ -107,14 +118,14 @@ A globally installed CLI auto-updates by default; turn that off with `toloka con
 
 ## Run a deployed pipeline
 
-Before starting a run, require a passing `toloka check` and no blocking error from `toloka validate`. A warning-severity `not_ran_node_check` concerns a separate Remote Node Check and does not block the Local Check Gate; an error-severity instance remains a blocking remote-validation result. Run `toloka pipeline cost <name>` when pricing evidence is needed; if it skips a billed node, report the authored rate and a labeled labor floor instead of presenting `$0.00` as the price.
+Before starting a run, require a passing `toloka check` and no blocking error from `toloka validate`. A warning-severity `not_ran_node_check` concerns a separate Remote Node Check and does not block the Local Check Gate; an error-severity instance remains a blocking remote-validation result. Run `toloka pipeline cost <name>` and present the forecast for user approval before starting the run. If it skips a billed node, report the authored rate and a labeled labor floor instead of presenting `$0.00` as the price; make the missing pricing evidence clear when seeking approval.
 
 Start a run with `toloka pipeline run <name> --wait --timeout <ms>`, then read its exit code: `0` succeeded, `1` reached a failed terminal state, `2` still running when the window closed. Without `--wait`, exit `0` only means the run was accepted. Nothing reports back later, so never describe a started run as a finished one. Name the live pipeline; there is no implicit only-pipeline.
 
-Always bound the wait. A queue with no one working it stays in progress indefinitely, so an unbounded poll loop ends with you killed and reporting nothing. On exit `2`, stop waiting and report what you observed: item counts, current states, and that the run had not finished. A bounded honest report beats an unbounded silent wait. Use `toloka pipeline status <name>` and `toloka pipeline results <runId> --failed` for counts, states, and errors. `toloka status` (no prefix) is project health, not the latest run.
+Keep monitoring bounded so the user receives a useful update even when expert work or queues take time. On exit `2`, report the observed item counts and states and say the run is still in progress; choose a further bounded check only when it serves the request. Use `toloka pipeline status <name>` and `toloka pipeline results <runId> --failed` for counts, states, and errors. `toloka status` (no prefix) is project health, not the latest run.
 
 ## Report with evidence
 
-Deliver that report in the same reply that does the work. There is no later turn and no background poller that will speak for you: if you end by promising to report once a window closes, the observation is lost and the work counts for nothing. Poll in the foreground, then state what you saw before you finish.
+Explain what changed, how it meets the task, what you verified, and what remains unresolved. Include relevant project/pipeline links, meaningful design assumptions, and observed run state and cost. Distinguish applied, validated, started, and completed; do not promise a later update unless a real reporting mechanism exists.
 
-For an autonomous or audited platform change, save stdout, stderr, and exit status for skill discovery and every networked mutation, check, and project-registry change outside authored source, then cite those records for counts, exit codes, and convergence claims. If skill installation fails, record the failure and identify the exact skill path and version or digest followed instead. Every reported defect or guidance gap must cite a saved record or be labeled `unrecorded`; mark recurrences from earlier work. Classify each as a skill rule, a rule present but not followed, a documentation gap, or a CLI/platform defect; use the bundled `toloka-report-issue` skill for product defects instead of teaching a workaround as normal workflow. Report every authored rule not fixed by the request as an assumption. For visual evidence, list every saved screenshot as inspected or uninspected and limit appearance claims to the inspected set.
+Keep enough command output and exit-status evidence to support claims about checks, mutations, and convergence, redacting secrets and sensitive data. For an audited task, retain the requested detailed records, including skill versions and project-registry changes. State when evidence is missing, and limit visual claims to surfaces you actually inspected. Use `toloka-report-issue` for product defects rather than presenting a workaround as normal workflow.

package/skills/toloka-build/references/node-semantics.md

@@ -68,7 +68,7 @@ The dataset name belongs in `definePipeline({ dataset: 'name', ... })`, not in t
 
 Use `code` whenever the result can be computed from inputs without a human task. This includes deterministic transforms, ETL, filtering, parsing, arithmetic, string manipulation, scripts, HTTP APIs, and LLM API calls. An LLM call made programmatically is still `code`; choose `generation` only when the platform's human or synthetic generation journey is wanted.
 
-Use a downstream `code` node after `quorum` only when the user asks for a derived consensus value such as majority vote, average, or deduplication. Quorum itself returns raw collected annotations.
+Use a downstream `code` node after `quorum` when the requested deliverable needs a derived consensus value such as majority vote, average, or deduplication. Quorum itself returns raw collected annotations. Choose an aggregation rule grounded in the task, and clarify material ambiguity rather than inventing label precedence.
 
 ### Configure it
 
@@ -158,17 +158,17 @@ Write at least one criterion for every output entity. Each criterion needs an au
 
 Use `llmQaInstruction` only when the evaluator needs a specific verification method, authoritative source, tool, or pinned edge case beyond the thresholds. It is evaluator guidance, not labeler guidance, and has no effect in `human_only` mode.
 
-Default QA is `qualityAssurance: { qaMode: 'llm_only' }`. Do not ask whether QA is wanted. Use `hybrid` only when the user explicitly requests human review; it adds sampled Human QA while retaining LLM review. Use `human_only` only when the user explicitly prohibits LLM grading. Human-bearing modes require `humanQaTimeForTask` of at least 10 seconds; omit `smartSamplingPercent` for the platform defaults of 30 for hybrid and 100 for human-only unless the user asks for another rate. QA mode applies to the whole node, not individual criteria. The redo cap is platform-controlled and is not an SDK setting.
+Default QA is `qualityAssurance: { qaMode: 'llm_only' }`. Keep it when it fits the task. `hybrid` adds sampled Human QA while retaining LLM review; `human_only` is appropriate when LLM grading is prohibited or human review alone is required. Recommend a mode based on the user's quality and privacy requirements, explaining cost and turnaround implications before changing it. Human-bearing modes require `humanQaTimeForTask` of at least 10 seconds; `smartSamplingPercent` defaults to 30 for hybrid and 100 for human-only. Use those defaults unless the task justifies a different rate. QA mode applies to the whole node, not individual criteria. The redo cap is platform-controlled and is not an SDK setting.
 
 Keep `instruction` actionable and in English. Include the workflow, concepts, quality rules, and at least one pass and fail example grounded in the task. Do not mention project schedules, dataset volume, workforce requirements, or compensation in labeler instructions.
 
 #### Audience and pricing
 
-For humans, set `audienceType: 'human'`, `verifiedExperts`, all three audience filters, `pricePerTask`, and `timeForTask`. The public shapes differ by filter: languages use `{ type: 'and' | 'or', values: [{ value: 'English' }] }`; specializations use `{ type: 'and' | 'or', values: [{ value, qualificationId }] }`; countries use ISO 3166-1 alpha-2 codes, for example `{ type: 'or', values: ['US'] }`. Verify every country value matches `/^[A-Z]{2}$/`; apply currently accepts arbitrary strings that can match no experts. Start unspecified filters with English, no specializations, and no countries. Do not put specializations on an unverified audience. A specialization's `qualificationId` is platform identity: preserve an imported value, and do not invent one when the SDK cannot discover it.
+For humans, set `audienceType: 'human'`, `verifiedExperts`, all three audience filters, `pricePerTask`, and `timeForTask`. The public shapes differ by filter: languages use `{ type: 'and' | 'or', values: [{ value: 'English' }] }`; specializations use `{ type: 'and' | 'or', values: [{ value, qualificationId }] }`; countries use ISO 3166-1 alpha-2 codes, for example `{ type: 'or', values: ['US'] }`. Verify every country value matches `/^[A-Z]{2}$/`; apply currently accepts arbitrary strings that can match no experts. Derive languages and expertise from the task and its inputs, leaving specialization and country filters unrestricted unless needed. English is a reasonable starting language for an English-language task, not a universal audience default. Ask when an unresolved audience requirement changes who can do the work. Do not put specializations on an unverified audience. A specialization's `qualificationId` is platform identity: preserve an imported value, and do not invent one when the SDK cannot discover it.
 
-Start with `$0.20` and 120 seconds when the task gives no stronger signal, then change them only for an explicit rate or clearly longer work. The per-expert cap is normally off. For `data_collection`, use a cap of 50 by default; use 1 for one-response-per-expert collection.
+`$0.20` and 120 seconds are a starting point for a short task, not a universal rate. Estimate effort from the work and required expertise, respect explicit rates, and explain meaningful adjustments in the cost forecast. The per-expert cap is normally off. For collection tasks, choose a cap based on contributor diversity and repetition requirements; 1 fits one-response-per-expert collection. Avoid copying an arbitrary cap into a task that does not need one.
 
-Use `audienceType: 'synthetic'` only when the user explicitly asks for synthetic or model-generated data. Set the required `maxCostPerAttempt`, the per-attempt ceiling in charged US dollars across fresh input, cached input, and output together, and configure the optional `generationModelId`, `reasoningEffort`, and `llmInstruction`; do not include human pricing or audience fields. Take `generationModelId` only from the union the SDK exports, and never invent an id; when the user names no model, omit the property and accept the platform default instead of guessing one. Synthetic generation is incompatible with `data_collection`, human QA, audience reuse, expert sourcing, and Training.
+Choose `audienceType: 'synthetic'` when model-generated data serves the requested outcome; preserve an explicit requirement for human judgments or original human content. Explain the quality and cost tradeoff if recommending synthetic generation. Set the required `maxCostPerAttempt`, the per-attempt ceiling in charged US dollars across fresh input, cached input, and output together, and configure the optional `generationModelId`, `reasoningEffort`, and `llmInstruction`; do not include human pricing or audience fields. Take `generationModelId` only from the union the SDK exports. Use a supported model suited to the task when there is evidence for that choice, or omit the property to use the platform default; do not guess IDs or capabilities. Synthetic generation is incompatible with `data_collection`, human QA, audience reuse, expert sourcing, and Training.
 
 #### Training, Exam, UI, and advanced settings
 
@@ -218,7 +218,7 @@ Configure entities for one labeler's contribution, not for the outer array. A si
 
 When a quorum output entity is `optional: true`, its outer field's `items` schema must also accept `null`, for example `{ type: 'array', items: { type: ['string', 'null'] } }`. The platform reserves a null annotation slot when that labeler omits the value and rejects an optional entity backed by non-nullable items.
 
-Quorum does not aggregate. It writes all raw annotations back, including rejected ones. Add a downstream `code` node only when the user asks for one consensus value, and make it tolerate arrays longer than `overlap`.
+Quorum does not aggregate. It writes all raw annotations back, including rejected ones. Add a downstream `code` node when the requested deliverable needs one consensus value, and make it tolerate arrays longer than `overlap`.
 
 #### Explanation-driven quality
 
@@ -232,7 +232,7 @@ Default to `qualityAssurance: { qaMode: 'llm_only' }`. The LLM accepts or reject
 
 **Quorum has no redo cycle.** A rejected annotation is never reopened or sent back to the same expert. Escalation adds a fresh annotation, and all collected annotations—accepted and rejected—remain in the output arrays. Hitting the cap with zero accepted annotations still returns the collected results.
 
-Use `qaMode: 'none'` only when the user explicitly asks for agreement-based quality control instead of LLM QA. Then:
+Use `qaMode: 'none'` when agreement-based quality control fits the task better than LLM grading, explaining the tradeoff before changing an existing QA strategy. This mode requires:
 
 - set `overlap` to at least 3;
 - disable the per-expert cap;