@toloka-platform/sdk 0.1.0-preview.6 → 0.1.0-preview.8

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

@@ -20,21 +20,21 @@ Choose by behavior, not by the data format:
 
 Use the typed node properties; never write handle strings yourself:
 
-| Node | Input | Output |
-| --- | --- | --- |
-| `root` | `collection.completed` | `collection.started` |
-| `code` | `transform.input` | `transform.output` |
-| `generation` | `annotate.input` | `annotate.output` |
-| `quorum` | `rate.input` | `rate.output` |
-| `match` | `route.input` | `route.matched(0)`, `route.matched(1)`, …, `route.default` |
+| Node         | Input                  | Output                                                     |
+| ------------ | ---------------------- | ---------------------------------------------------------- |
+| `root`       | `collection.completed` | `collection.started`                                       |
+| `code`       | `transform.input`      | `transform.output`                                         |
+| `generation` | `annotate.input`       | `annotate.output`                                          |
+| `quorum`     | `rate.input`           | `rate.output`                                              |
+| `match`      | `route.input`          | `route.matched(0)`, `route.matched(1)`, …, `route.default` |
 
 Connect them in the direction of data flow:
 
 ```ts
-connect(collection.started, transform.input)
-connect(transform.output, route.input)
-connect(route.matched(0), annotate.input)
-connect(annotate.output, collection.completed)
+connect(collection.started, transform.input);
+connect(transform.output, route.input);
+connect(route.matched(0), annotate.input);
+connect(annotate.output, collection.completed);
 ```
 
 `match.matched(index)` corresponds by index to `settings.conditions[index]`. The first matching condition wins; `default` receives items that match none.
@@ -52,14 +52,13 @@ The public authoring shape is `RootAuthoringSettings`:
 - Each entry can be a `Field` or `{ field, optional }`; a bare `Field` is required.
 - `itemLimit` exists in both `RootNodeSettings` and `RootAuthoringSettings`. Do not invent a limit; author one only when the user explicitly requests a bounded test or batch. Apply preserves a live `itemLimit` unless source declares its own.
 
-
 The dataset name belongs in `definePipeline({ dataset: 'name', ... })`, not in the root settings. `toloka apply` resolves or creates the named dataset and supplies its ID.
 
 ### Traps
 
 - Do not author `datasetId` or `itemFilter`; `RootAuthoringSettings` omits both. `toloka apply` binds the dataset and preserves the live `itemFilter` and `itemLimit` unless source declares its own `itemLimit`. Do not add a limit to source to restore one you saw in the UI.
 
-- Do not put a field in `completed` unless the final connected branch actually produces it.
+- `completed` may contain any declared field carried on the incoming branch, whether it originated at root input or an upstream output. Never list a field no upstream node provides. Until a run produces results, write-back of a pass-through input is unobserved and must be reported that way.
 - Declare every referenced `Field` in `definePipeline({ fields })`.
 - Dataset fields are immutable after creation. You may add a column, never alter or remove one. On a schema conflict, use a new column name or a new dataset.
 
@@ -76,7 +75,7 @@ Use a downstream `code` node after `quorum` only when the user asks for a derive
 Set `CodeAuthoringSettings`, derived from `CodeNodeSettings`, through `code(name, settings)`:
 
 - `about`: node `name`, optional `description`, and optional `projectType`.
-- `fieldProxies.input` and `.output`: `{ field, optional }` references to declared `Field` objects.
+- `input` and `output`: `{ field, optional }` references to declared `Field` objects.
 - `code.code`: Python source.
 - `envVars`: optional static values or secret bindings:
   - `{ type: 'static', name, value }`
@@ -138,21 +137,23 @@ Use `about.projectType: 'data_collection'` when experts produce new original con
 
 #### Entities
 
-An authored entity uses `field`, not `fieldProxyId`. Set `entityType`, `optional`, `jsonPath`, `description`, `relations`, and the discriminant:
+An authored entity references a declared `field`. Set `entityType`, `optional`, `jsonPath`, `description`, `relations`, and the discriminant:
 
 - `dynamic: false` means one value in one annotation; use a path without `[*]` and omit `maxEntities`.
 - `dynamic: true` means repeated values inside one annotation; use exactly one `[*]` in `jsonPath` and set `maxEntities` from 1 through 50.
 - Use `allowedLabels: [{ label, value }]` for fixed choices. Use `SINGLE_LABEL` for exactly one stored value and `MULTI_LABEL` for multiple values.
-- Set both `minDurationSeconds` and `maxDurationSeconds` on `VIDEO` entities.
+- Set media duration bounds only when the expert produces the media through an upload or recording output. Input media used for annotation does not require duration bounds.
 - Give every output entity at least one relation to the input it uses: `{ field, rel_type: 'context' | 'references' | 'depends_on' | 'evaluates' }`, or a conditional relation supported by the public type.
 
+`entityType` is a closed platform vocabulary even where a generated TypeScript shape is currently broad. Use `CONTEXT` for any non-media input the expert reads, including text, numbers, and objects. Use `SHORT_ANSWER` for short produced text, `RESPONSE` for long produced text, and `EXPLANATION` only for reasoning about another value. Use `SINGLE_LABEL` or `MULTI_LABEL` for fixed choices and the matching media or annotation type for those values. Never invent `TEXT` or another natural-language type name; consult the documented vocabulary when these categories do not fit.
+
 Entities enforce format, not meaning. Put types, ranges, cardinality, requiredness, and labels in the field schema and entity. Put accuracy, correctness, completeness, and clarity in quality criteria.
 
-For video `data_collection`, the upload or recorder returns an array even when one video is requested. Use an output `VIDEO` entity with `dynamic: true`, `maxEntities: 1`, and a `jsonPath` ending in `[*]`; align its duration bounds with the UI component.
+For any single-item upload or recording control, the component value is still an array. Declare the output field as a top-level array with `minItems: 1` and `maxItems: 1`, the output entity as `dynamic: true` with `maxEntities: 1` and a `jsonPath` ending in `[*]`, and use the matching media or document entity type. Map the component's documented completed-value link field in `postprocess`. For video, also set both entity duration bounds and align them with the UI component.
 
 #### Quality and instructions
 
-Write at least one criterion for every output entity. Each criterion needs an authored UUID `id`, `qualityElement`, mutually exclusive and exhaustive `thresholds.pass` and `thresholds.fail`, and `targetEntity: outputField`. Invert the task into an observable check: “tag every car” becomes “every visible car has exactly one tag.” Keep format validation out of criteria.
+Write at least one criterion for every output entity. Each criterion needs an authored UUID `id`, `qualityElement`, mutually exclusive and exhaustive `thresholds.pass` and `thresholds.fail`, and `targetEntity: outputField`. Every criterion must resolve to pass or fail for every item; express edge cases as conditional clauses inside an always-applicable criterion. Criteria judge meaning, not an exact phrase you authored unless the request fixes that phrase. Before apply, walk every sample row through the instruction and all criteria: each criterion must yield one verdict, and no two authored rules may demand different values for the same row. Invert the task into an observable check: “tag every car” becomes “every visible car has exactly one tag.” Keep format validation out of criteria.
 
 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.
 
@@ -162,7 +163,7 @@ Keep `instruction` actionable and in English. Include the workflow, concepts, qu
 
 #### 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 `{ type: 'or', values: ['United States'] }`. 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. 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.
 
 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.
 
@@ -185,10 +186,10 @@ Use `reuseAudienceWithNodeId` only with real imported `{ pipelineId, nodeId }` v
 - Do not add fields, explanations, comments, or labor the task does not require.
 - Do not choose synthetic generation merely because a model could do the task; require an explicit request.
 - Do not treat the constructor's generated placeholder Training or blank UI as production-ready configuration.
-- Do not pair `projectType: 'general'` with `verifiedExperts: false`. General projects require an ID-verified audience, and the server rejects the graph with `General projects require an ID-verified audience`. `data_collection` supports both modes but requires a media upload component (`VideoUpload`, `VideoRecord`, or `FileUpload`) in the `ui` code. An annotation task with an unverified audience therefore cannot be expressed: `general` demands verified experts and `data_collection` demands an upload widget the task has no use for. When a request asks for one, say so and let the requester choose, rather than quietly flipping a setting.
+- Do not pair `projectType: 'general'` with `verifiedExperts: false`. General projects require an ID-verified audience, and the server rejects the graph with `General projects require an ID-verified audience`. `data_collection` supports both modes but requires a hardware upload or recording component supported by the current UI catalog. An annotation task with an unverified audience therefore cannot be expressed: `general` demands verified experts and `data_collection` demands an upload control the task has no use for. When a request asks for one, say so and let the requester choose, rather than quietly flipping a setting.
 - Do not omit `ui.constants`. It is required alongside `code`, `data`, `preprocess`, and `postprocess`; `'{}'` is the right value when there is nothing to pass. Omitting it fails validation with `must have required property 'constants'`, usually reported together with a misleading `type must be equal to constant` from the failed node discrimination.
 - Do not ship a generation node without Training. `onboarding` is mandatory: at least three `steps`, of which at least one carries a `quiz` block. The server rejects fewer with `Onboarding must have at least 3 steps` and `Onboarding must include at least one quiz block`.
-- Do not treat the server's materialized defaults as your configuration. A deployed node reports `qualityAssurance`, `exam`, `reuseAudienceWithNodeId`, and `smartSearch` even when source never set them. Leave them out of source unless you mean to control them; `plan` compares only what source declares.
+- Do not treat the server's materialized defaults as your configuration. A deployed node reports `qualityAssurance`, `exam`, `reuseAudienceWithNodeId`, and `smartSearch` even when source never set them. Leave them out unless you mean to control them. Omitted top-level object keys are preserved, but defaults materialized inside list elements can still cause drift; use the generic import-and-diff recovery flow.
 
 ## `quorum`
 
@@ -213,6 +214,8 @@ Quorum is human-only in the current public shape; its `audienceAndPricing.audien
 
 Configure entities for one labeler's contribution, not for the outer array. A single label per person therefore uses `dynamic: false` and `jsonPath: '$.label'`, while the declared output field is `{ type: 'array', items: { type: 'string' } }`. `dynamic: true` means an array inside each labeler's contribution and therefore produces an array of arrays. Build the UI to submit one value at `$.label`, never `$.label[0]`; the platform assembles the outer array.
 
+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`.
 
 #### Explanation-driven quality
@@ -256,20 +259,20 @@ Use `match` when one item must take one conditional path based on data. Do not u
 Set `MatchAuthoringSettings`, derived from `MatchNodeSettings`, through `match(name, settings)`:
 
 - `about`: `name`, optional `description`, optional `projectType`.
-- `fieldProxies.input`: every declared `Field` referenced by a predicate, each with `optional`.
-- `conditions`: ordered branches. Each has `name`, optional `logic: 'and' | 'or'`, and `predicates`.
+- `input`: every declared `Field` referenced by a predicate, each with `optional`.
+- `conditions`: ordered branches with optional `logic: 'and' | 'or'` and required `predicates`.
 - Each authored predicate uses `field`, `jsonPath`, `operator`, and scalar `value`.
 
 The current public type accepts only `operator: 'text_eq' | 'text_neq'` and `value: string | number | boolean | null`. Do not copy broader internal operator lists into source. Use `jsonPath: '$'` for the whole scalar or a restricted path into an object.
 
-Ordering is semantic: `conditions[0]` routes to `matched(0)`, the first true condition wins, and an implicit `default` handles no match. Every predicate field must also appear in `fieldProxies.input`.
+Ordering is semantic: `conditions[0]` routes to `matched(0)`, the first true condition wins, and an implicit `default` handles no match. Every predicate field must also appear in `input`.
 
 ### Traps
 
 - Do not write a default condition; connect `route.default`.
 - Do not assume all matching branches run.
 - Do not use unsupported comparison, set-membership, range, or emptiness operators. Put that logic in `code`, emit a routing key, then compare it with `text_eq` or `text_neq`.
-- Do not reference a field in a predicate without binding it in `fieldProxies.input`.
+- Do not reference a field in a predicate without binding it in `input`.
 
 ## Public-surface gaps
 
@@ -278,14 +281,14 @@ When the requirement depends on one of these capabilities, state the gap instead
 - Audience discovery and validation helpers have no SDK or CLI path: valid-language/country/specialization suggestions, audience-size statistics, and recommended-rate calculation.
 - Audience-reuse candidate discovery has no SDK or CLI path. Source can store a known cross-pipeline pointer, but cannot search candidates.
 - Smart Search rendering, source-fingerprint computation, and stale-profile diagnosis have no SDK or CLI path. Source can carry the public profile; it cannot generate the server-owned fingerprint or preview rendered sourcing documents.
-- The interactive task-interface toolkit has no SDK/CLI testing path for component discovery, component documentation, rendered tree/value inspection, screenshots, TypeScript reports, or submission validation. Source can set `ui`; final UI verification remains server/UI work.
+- The `@toloka-platform/sdk/testing` entry point provides typed `test.code`, `test.ui`, and `test.pipeline` wrappers. `toloka check` runs their evidence with project TypeScript and automatic Task UI typechecking. Missing Remote Node Checks remain separate from this local gate.
 - Training's examples playbooks and automatic course authoring have no SDK/CLI path. Source can set `onboarding`, but cannot request geometry/numeric check templates or validate hands-on examples locally beyond the public graph schema.
 - Exam golden-dataset discovery, creation by symbolic dataset name, dataset lint execution, and generated-golden confirmation flow have no high-level SDK authoring path. `exam.goldenDatasetId` requires a real ID.
-- Per-node strict validation is not exposed separately. `definePipeline` and offline `validate(graph)` check the public contract; `toloka validate` runs platform spec validation and reports the latest matching check jobs without writing the graph.
-- Stored checks can be represented in settings and the low-level client can list/start pipeline checks, but `toloka` has no command that discovers check contracts, configures check cases, starts each required lint/test, waits, and explains reports.
+- Per-node platform validation is not exposed separately. `definePipeline` and `toloka check` enforce local contracts; `toloka validate` runs platform spec validation and reports the latest matching Remote Node Check jobs without writing the graph.
+- Stored Remote Node Checks can be represented in settings and the low-level client can list/start them. `toloka check` deliberately runs local source and authored tests; it does not configure or start platform check jobs.
 - Project rename and runtime item-filter authoring have no `toloka` source path. The CLI preserves the live item filter and a live `itemLimit` unless source declares its own limit.
 
 - Generation's platform-controlled redo cap, appeal behavior, payment retry, and exact terminal handling are intentionally not configurable SDK settings.
 - Dynamic quorum and per-item overlap are unsupported by both surfaces; this is a platform limitation, not missing TypeScript syntax.
 
-For every representable change above, edit the node's source file, run `toloka validate`, inspect `toloka plan`, and apply with `toloka apply`.
+For every representable change above, edit the node's source file, run `toloka validate`, inspect `toloka plan`, and apply with `toloka apply`.

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

@@ -26,16 +26,19 @@ Treat the three layers differently:
 
 ## Initialize the source root
 
-Install the SDK in the project, then initialize the directory before selecting a platform project:
+For a first-time guided session, read `https://platform.toloka.ai/onboarding.md` first. Keep its stage order and checkpoints; use this reference for the commands and source-first invariants inside those stages.
+
+Install the SDK before invoking project commands:
 
 ```sh
 bun add --dev @toloka-platform/sdk
-toloka init
 ```
 
-`init` does not require a selected project. It checks that `@toloka-platform/sdk` is 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. If a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing.
+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` checks that `@toloka-platform/sdk` is 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. It 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 installed SDK. Help, `init`, `report`, `project url`, and version invocations skip this checkout-dependent warning. The warning never blocks a command; re-run `toloka init` to refresh the bootstrap and its pointers.
+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 installed SDK. Help, `init`, `report`, `project url`, `config`, and version invocations skip this checkout-dependent warning. The warning never blocks a command; re-run `toloka init` to refresh the bootstrap and its pointers.
 
 ## Store credentials once
 
@@ -61,6 +64,8 @@ toloka logout
 unless you pass `--show-token`, and exits non-zero when the platform is unreachable — use it to check a
 setup rather than guessing. `logout` deletes the stored file; it does not revoke the key.
 
+A globally installed `toloka` auto-updates by default. It checks npm at most once per day and installs a newer `@toloka-platform/sdk` only after that version has been published for at least 24 hours, then re-runs the original command. `config`, `version`, and `help` never trigger a check. Project-local installs and CI skip it. Turn it off with `toloka config set auto-update false`.
+
 ## Configure the CLI
 
 Provide the API key and base URL on networked workflows through `POTATO_API_KEY` and
@@ -84,7 +89,10 @@ toloka --version
 toloka login
 toloka logout
 toloka auth-status
-toloka project list
+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
@@ -93,6 +101,7 @@ toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>]
 toloka init
 toloka import [projectId]
+toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]
 toloka validate
 toloka plan
 toloka apply
@@ -102,7 +111,7 @@ toloka dataset list
 toloka dataset fields <name>
 toloka dataset load <name> --out <file> [--limit <n>] [--timeout <ms>]
 toloka dataset upload <name> <file>
-toloka pipeline list
+toloka pipeline list [--limit <n>]
 toloka pipeline run [name] [--wait] [--timeout <ms>]
 toloka pipeline status [name]
 toloka pipeline runs [name] [--limit <n>]
@@ -122,11 +131,11 @@ toloka skill install <skill-id> [--force]
 toloka report <markdown> [--authored-by human|agent] [--confirm]
 ```
 
-Select the platform project with `toloka project add` or `toloka project create` before `import`, `plan`, or `apply`. `init` may run first, and `import` uses the selected project when the id is omitted.
+Select the platform project with `toloka project add` or `toloka project create` before `import`, `plan`, or `apply`. For `init`, `toloka --project-id <id> init`, `TOLOKA_PROJECT_ID`, and `POTATO_PROJECT_ID` bind an empty checkout directly without changing the machine registry. `project create` also writes `toloka.json`; `project add` changes only the machine registry, so follow it with `import <projectId>` for an existing project or an explicit project ID on `init` for an empty one. Confirm `toloka project current` and `toloka.json` resolve to the intended ID before authoring.
 
 `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 pipeline cost [name] [--item-limit <n>]` forecasts what a run of a live pipeline would bill. It does not start a run and does not change the graph. Name the live pipeline or id; a TTY may pick among several. The typed client equivalent is `client.pipelines.estimateCost({ pipelineId, itemLimit? })`.
+`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.
 
 ## Manage model checkpoints
 
@@ -134,39 +143,44 @@ The global Base Model Catalog is read-only and uses `toloka base-model`. `base-m
 
 ## Adopt an existing live project
 
-1. Run `toloka init` in the intended source root if the agent entry points are not installed yet.
-2. Run `toloka project add <alias> <projectId>`.
-3. Run `toloka import`.
-4. Inspect `toloka.json` and every generated `pipelines/**/pipeline.ts` dependency before editing.
-5. Preserve generated constructor `id` options. They bind imported source to the existing graph; never copy them to unrelated declarations or invent replacements.
-6. Make the smallest source change, validate offline, plan, apply, and plan again.
+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 init` in the intended source root if the agent entry points are not installed yet.
-2. Run `toloka project create <alias>` or `toloka project add <alias> <projectId>`.
+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. Run `toloka validate`.
-6. Run `toloka plan`.
-7. Resolve missing secrets and immutable-field conflicts.
-8. Run `toloka apply`.
+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.
 
-## Validate against the platform
+## Check locally and validate against the platform
 
-Run the project typecheck first. Then validate every bound pipeline:
+Run the complete local gate first, then validate every bound pipeline remotely:
 
 ```sh
-bunx tsc --noEmit
+toloka check
 toloka validate
 ```
 
-`toloka validate` posts each authored graph to the platform. It reports spec errors, warnings, and the latest matching check jobs. It does not write the graph. A pipeline that is not on the platform yet is skipped until `toloka apply` creates it.
+`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.
+
+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; `not_ran_node_check`, which describes a separate Remote Node Check; and warnings. It 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.
 
 The authored API still supplies extra local safety:
 
@@ -175,7 +189,7 @@ 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.
 
-These checks do not replace `toloka validate`. Plan compares source with live resources but does not submit the desired graph for acceptance. Apply is where the backend can reject graph-wide references, layout identity, or concurrent-version assumptions.
+`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.
 
 ## Read and apply a plan
 
@@ -189,6 +203,20 @@ Treat every plan line as evidence of what apply will attempt.
 
 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.
+
+Before choosing component names or props, call `ui.componentDocumentation()` in a local `@toloka-platform/sdk/testing` scenario. A component's contract is its returned `propsType`, `valueType`, and `example`. For structured or array-valued Fields, derive the dataset field schema from `valueType`, then feed the documented example value through `setValue`, `getValue`, and `submit`; never translate undocumented property names or replace missing values with defaults. Register required human-work behavior with `test.ui(pipeline, node, name, callback)`. Its callback receives bound `render(options?)`; the test counts only after a successful `submit`, at least one assertion, and a passing callback.
+
+Register the representative connected flow with `test.pipeline(pipeline, name, callback)`. When a local dataset file is available, use its first row as the initial item state; redact sensitive values while preserving field names, nesting, optionality, and media/value shapes. Use synthetic input only when no local row exists. Use the callback's bound `runCode` and `renderUi` helpers, merge only declared node outputs, and assert the final `root.completed` fields. Keep a linear happy path in one test; use separate scenarios for match branches, optional routes, and failures.
+
+```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.
+
 ## Add dataset rows
 
 Declare the fields in source, then upload rows:
@@ -197,6 +225,8 @@ Declare the fields in source, then upload rows:
 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.
 
 If a later upload fails with a schema-incompatibility error, inspect the inferred schema from the first successful upload:
@@ -205,7 +235,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. Copy them into source when you want authored fields to match the stored inference. It does not write source or mutate the 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.
 
 Keep item files outside the source tree or gitignored. Never embed sample or production rows in `pipeline.ts` to make reconciliation create them.
 
@@ -269,9 +299,13 @@ Use the exact name reported by plan. Set it with `toloka secret set`, rerun plan
 
 A 409 means live graph state changed after apply read it. Run plan again, compare the new live diff with the source, incorporate intentional live changes into source when required, and apply once more. Never add `expectedVersion` to source and never loop retries.
 
+### Unexplained node drift after apply
+
+Object settings preserve omitted live keys, but list-valued settings such as conditions, predicates, entities, steps, and rules can be compared as whole values after the server adds defaults inside an element. If plan reports an unnamed node change after a clean apply, run `toloka import` into a scratch directory outside the source root, compare that node with source, and declare only the materialized key needed for convergence. Delete the scratch directory afterward and never re-apply blindly.
+
 ### Server 400 after a clean validate
 
-Read the returned path and reason. Check connection endpoints, duplicate or unknown IDs preserved from imported source, field references, and any accidentally authored layout. Fix source, rerun `toloka validate`, plan, and apply. Do not 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. 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
 

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

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

package/src/authoring/index.ts

@@ -51,7 +51,7 @@ export interface Connection {
   readonly settings: PipelineGraphV1["connections"][number]["settings"];
 }
 
-type FieldProxyReference = {
+type FieldReference = {
   readonly field: Field;
   readonly optional: boolean;
 };
@@ -124,26 +124,24 @@ type QuorumOutputEntity = FieldEntity<QuorumNodeSettings["entities"]["output"][n
 type QuorumQualityCriterion = FieldTarget<QuorumNodeSettings["qualityCriteria"][number]>;
 type QuorumExam = FieldExam<NonNullable<QuorumNodeSettings["exam"]>>;
 
-type MatchPredicate = Omit<
+type MatchPredicate = Pick<
   MatchNodeSettings["conditions"][number]["predicates"][number],
-  "fieldProxyId"
+  "jsonPath" | "operator" | "value"
 > & {
   readonly field: Field;
 };
 
-export type RootAuthoringSettings = Omit<
-  RootNodeSettings,
-  "datasetId" | "itemFilter" | "startedFieldProxies" | "completedFieldProxies"
-> & {
+export type RootAuthoringSettings = Pick<RootNodeSettings, "itemLimit"> & {
   readonly started: ReadonlyArray<RootFieldReference>;
   readonly completed: ReadonlyArray<RootFieldReference>;
 };
 
-export type CodeAuthoringSettings = Omit<CodeNodeSettings, "fieldProxies"> & {
-  readonly fieldProxies: {
-    readonly input: ReadonlyArray<FieldProxyReference>;
-    readonly output: ReadonlyArray<FieldProxyReference>;
-  };
+export type CodeAuthoringSettings = Pick<
+  CodeNodeSettings,
+  "about" | "code" | "envVars" | "checks"
+> & {
+  readonly input: ReadonlyArray<FieldReference>;
+  readonly output: ReadonlyArray<FieldReference>;
 };
 
 export type GenerationAuthoringSettings = Omit<
@@ -162,15 +160,13 @@ export type GenerationAuthoringSettings = Omit<
   readonly exam?: GenerationExam;
 };
 
-export type MatchAuthoringSettings = Omit<MatchNodeSettings, "conditions" | "fieldProxies"> & {
+export type MatchAuthoringSettings = Pick<MatchNodeSettings, "about"> & {
   readonly conditions: ReadonlyArray<
     Omit<MatchNodeSettings["conditions"][number], "predicates"> & {
       readonly predicates: ReadonlyArray<MatchPredicate>;
     }
   >;
-  readonly fieldProxies: {
-    readonly input: ReadonlyArray<FieldProxyReference>;
-  };
+  readonly input: ReadonlyArray<FieldReference>;
 };
 
 export type QuorumAuthoringSettings = Omit<
@@ -316,11 +312,14 @@ function referencedFields(value: unknown): ReadonlyArray<Field> {
   return references;
 }
 
-function compileFieldProxy(reference: FieldProxyReference): { id: string; optional: boolean } {
+function compileFieldReference(reference: FieldReference): { id: string; optional: boolean } {
   return { id: reference.field.id, optional: reference.optional };
 }
 
-function compileRootFieldProxy(reference: RootFieldReference): { id: string; optional: boolean } {
+function compileRootFieldReference(reference: RootFieldReference): {
+  id: string;
+  optional: boolean;
+} {
   return isField(reference)
     ? { id: reference.id, optional: false }
     : { id: reference.field.id, optional: reference.optional ?? false };
@@ -457,8 +456,8 @@ function createRoot(
     type: "root",
     settings: {
       ...settingsWithoutFieldProxies,
-      startedFieldProxies: { output: started.map(compileRootFieldProxy) },
-      completedFieldProxies: { input: completed.map(compileRootFieldProxy) },
+      startedFieldProxies: { output: started.map(compileRootFieldReference) },
+      completedFieldProxies: { input: completed.map(compileRootFieldReference) },
     },
     started: outputPort(id, "started"),
     completed: inputPort(id, "completed"),
@@ -477,14 +476,15 @@ export function code(
   options: AuthoringIdOptions = {},
 ): AuthoredCodeNode {
   const id = options.id ?? mintedId("code", name);
+  const { input, output, ...wireSettings } = settings;
   return {
     id,
     type: "code",
     settings: {
-      ...settings,
+      ...wireSettings,
       fieldProxies: {
-        input: settings.fieldProxies.input.map(compileFieldProxy),
-        output: settings.fieldProxies.output.map(compileFieldProxy),
+        input: input.map(compileFieldReference),
+        output: output.map(compileFieldReference),
       },
     },
     input: inputPort(id, "input"),
@@ -515,19 +515,20 @@ export function match(
   options: AuthoringIdOptions = {},
 ): AuthoredMatchNode {
   const id = options.id ?? mintedId("match", name);
+  const { conditions, input, ...wireSettings } = settings;
   return {
     id,
     type: "match",
     settings: {
-      ...settings,
-      conditions: settings.conditions.map((condition) => ({
+      ...wireSettings,
+      conditions: conditions.map((condition) => ({
         ...condition,
         predicates: condition.predicates.map(({ field: referencedField, ...predicate }) => ({
           ...predicate,
           fieldProxyId: referencedField.id,
         })),
       })),
-      fieldProxies: { input: settings.fieldProxies.input.map(compileFieldProxy) },
+      fieldProxies: { input: input.map(compileFieldReference) },
     },
     input: inputPort(id, "input"),
     default: outputPort(id, "default"),

package/src/checks/ast.ts

@@ -0,0 +1,32 @@
+import type { JSXAttribute } from "oxc-parser";
+import { parseSync } from "oxc-parser";
+
+// Sources are parsed with the same wrapping buildCompositeSource (task-ui-typecheck.ts) injects — if that
+// wrapping changes, change parseProgram's callers with it.
+export const parseProgram = (filename: string, source: string, lang: "ts" | "tsx") => {
+  const result = parseSync(filename, source, { lang, preserveParens: false });
+
+  return result.errors.some((error) => error.severity === "Error") ? null : result.program;
+};
+
+export const resolveAttributeString = (attribute: JSXAttribute | undefined): string | null => {
+  const value = attribute?.value;
+
+  if (!value) return null;
+
+  if (value.type === "Literal") return typeof value.value === "string" ? value.value : null;
+
+  if (value.type === "JSXExpressionContainer") {
+    const expression = value.expression;
+
+    if (expression.type === "Literal" && typeof expression.value === "string") {
+      return expression.value;
+    }
+
+    if (expression.type === "TemplateLiteral" && expression.expressions.length === 0) {
+      return expression.quasis[0]?.value.cooked ?? null;
+    }
+  }
+
+  return null;
+};

package/src/checks/index.ts

@@ -0,0 +1,14 @@
+export { findPostprocessKeyCollisions } from "./postprocess-collisions";
+export {
+  createBundledTaskUiTypechecker,
+  createTaskUiTypechecker,
+  taskUiDeclarationSnapshot,
+} from "./task-ui-typecheck";
+export type {
+  TaskUiBlockKey,
+  TaskUiDeclarationSource,
+  TaskUiDiagnostic,
+  TaskUiDiagnosticsReport,
+  TaskUiSource,
+  TaskUiTypechecker,
+} from "./task-ui-typecheck";