@toloka-platform/sdk 0.11.1 → 0.11.3

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

@@ -1 +1 @@
-6a0f8dbdd98f49a9c663bb3051960c4f168961bc4ebd8b428ae75fd5f07ba994  toloka.js.jsc
+6f99f48f6bd7c933cd5d2f6b2382d9c4149e6cfb4a39a32364d49994a16f436e  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-20b4b75534617c8aed19bf129f8b78fe18d43a5a91221f1aa4bf2fbc0f792175  toloka.js
+a038b95e14fe030c3d9b59182799dc89f8c76fd501fe42036831ea3d1daa27c5  toloka.js

package/docs/authoring.md

@@ -99,6 +99,14 @@ Choose entity cardinality from the task, not from the component's JavaScript val
 
 Use `dynamic: true` only when one labeler produces multiple independent entities. Set `maxEntities` to a task-grounded upper bound rather than a generic default. A component may expose an array while still producing one logical entity; for a single upload or recording, keep a scalar field and static entity and select the completed first value with a path such as `$.video_file[0].downloadLink`.
 
+Entity types and labels are checked locally, for both generation and quorum nodes, before anything is sent to the platform:
+
+- `entityType` on every input and output entity must be one of the platform's core entity types. The list ships with the SDK in `src/core-entity-types.json`, generated from the server schema: `JUDGEMENT`, `EXPLANATION`, `PROMPT`, `USER_PROMPT`, `RESPONSE`, `RESPONSE_EVALUATION`, `RUBRIC`, `RUBRICS_GROUP`, `DIALOG`, `DIALOG_STEP`, `DIALOG_EVALUATION`, `SHORT_ANSWER`, `FEEDBACK`, `CONTEXT`, `IMAGE`, `ANNOTATION`, `SINGLE_LABEL`, `MULTI_LABEL`, `VIDEO`, `DOCUMENT`, `GOLDEN_SET`, `LOGS`, `SOLUTION`, `CODE`, `METADATA`, `AUDIO`, `AGENT_TRAJECTORY`, `MCP_SERVER`, `CONTAINER`, `CUSTOM`.
+- An output entity of type `SINGLE_LABEL` or `MULTI_LABEL` needs `allowedLabels` with at least two entries.
+- Every label `value` must be snake_case (`first_video`, not `firstVideo` or `First Video`).
+
+A violation is thrown as `PipelineGraphValidationError`, with one issue per offending path, as soon as the pipeline source is loaded — so `toloka check`, `toloka plan`, `toloka apply` and `toloka validate` all fail on it locally before any platform request.
+
 The following task is legitimately dynamic because the labeler can draw one independent box for every visible face:
 
 ```ts
@@ -217,7 +225,7 @@ A quorum node **requires** an `onboarding` block: the Training course is part of
 
 ### match
 
-Predicate routing. Conditions are evaluated in declaration order.
+Predicate routing. Conditions are evaluated in declaration order. A condition's `logic` defaults to `'and'`, so every predicate must match; set `logic: 'or'` when any one predicate should match. `match()` writes the default into the graph, as the platform stores it, so `toloka plan` does not report the condition as changed after an apply.
 
 ```ts
 import { match } from "@toloka-platform/sdk";
@@ -276,7 +284,9 @@ export default definePipeline({
 });
 ```
 
-`dataset` names the source dataset. `plan` creates it if it is absent and records the resolved id in `toloka.json`.
+`dataset` names the source dataset. `apply` creates it if it is absent, binds it to the pipeline, and records the resolved id in `toloka.json`.
+
+Leave `dataset` out for a pipeline that has no dataset yet, such as one created from a template in the platform UI. `plan` and `apply` then edit its graph without binding a dataset, and `toloka import` writes such a pipeline the same way. The pipeline cannot run until it has a dataset: add `dataset` to its source later, or bind one in the platform UI and import again. Apply never removes a bound dataset, so it refuses to apply a source that drops `dataset` from a pipeline that has one.
 
 Each `pipelines/<name>/pipeline.ts` is one pipeline. A project can hold several; each names its own dataset, and a dataset can be shared.
 
@@ -288,7 +298,7 @@ Constructors mint deterministic ids from the node name, so authored source needs
 
 `toloka import` emits explicit `{ id }` options for nodes and fields that already exist on the platform. **Preserve them.** They are how reconciliation recognizes the same resource instead of replacing it.
 
-Never hand-write `fp_…`, `ds.…`, `pl.…`, or `pp.…` values into settings, and never author a `layout` block: layout is not authored, existing layout is preserved, and the server supplies defaults.
+Never hand-write `fp_…`, `ds.…`, `pl.…`, or `pp.…` values into settings, and never author a `layout` block: layout is not authored, existing nodes keep their canvas position, and the server places new nodes one column after their rightmost input and moves End to the right when they reach it.
 
 ## Validate
 
@@ -297,9 +307,9 @@ toloka check
 toloka validate
 ```
 
-`definePipeline` and the typed ports add local declaration and connection invariants. `toloka validate` posts each bound pipeline to `POST /pipelines/:pipelineId/graph/validate` and reports platform spec errors, warnings, and the latest matching check jobs. It does not write the graph.
+`definePipeline` and the typed ports add local declaration and connection invariants. `toloka check` also reports, as warnings, the platform rules that would reject a node connected to the root: node names, unique quality elements, quality-criterion thresholds, the minimum task and Human QA review times, a positive price per task, a media upload component on a human `data_collection` node, and the limits of an enabled exam. `toloka apply` refuses to write a new or changed pipeline that breaks them, before any platform write; an unchanged pipeline, such as a draft saved in the platform UI, does not block apply of the others. `toloka validate` posts each bound pipeline to `POST /pipelines/:pipelineId/graph/validate` and reports platform 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. The published JSON contract is still available as `validate(graph)` for importer and fixture tests; that helper makes no network call.
+A pipeline that is not on the platform yet is skipped until `toloka apply` creates it. The published JSON contract is still available as `validate(graph)` for importer and fixture tests; that helper also runs the local entity checks described under [generation](#generation) and makes no network call.
 
 A successful validate is necessary, not sufficient for launch. Gates outside the graph contract — an underpriced audience, a Training course that is enabled but unbuilt, a task UI that was never validated — can still block deployment. See [limitations](./limitations.md).
 

package/docs/cli.md

@@ -56,14 +56,15 @@ If both installations exist, put the desired directory first on `PATH`, run `has
 
 ## Configuration
 
-Credentials and the platform base URL resolve from the same precedence order, highest first.
+Credentials and the platform base URL resolve independently. Credentials use this precedence, highest first.
 
 | Precedence  | Credential source                                |
 | ----------- | ------------------------------------------------ |
 | 1 (highest) | `--api-key` flag                                 |
-| 2           | `TOLOKA_API_KEY` environment variable            |
-| 3           | API key stored by `toloka login --api-key-stdin` |
-| 4 (lowest)  | browser session stored by `toloka login`         |
+| 2           | `TOLOKA_SCOPED_TOKEN` environment variable       |
+| 3           | `TOLOKA_API_KEY` environment variable            |
+| 4           | API key stored by `toloka login --api-key-stdin` |
+| 5 (lowest)  | browser session stored by `toloka login`         |
 
 | Precedence  | Base URL source                         |
 | ----------- | --------------------------------------- |
@@ -81,6 +82,8 @@ Credentials and the platform base URL resolve from the same precedence order, hi
 
 Earlier releases named these variables `POTATO_API_KEY`, `POTATO_BASE_URL`, and `POTATO_PROJECT_ID`. The CLI still reads each legacy name when its `TOLOKA_*` counterpart is unset, prefers the `TOLOKA_*` value when both are set, and prints `POTATO_API_KEY is deprecated and will stop being read; set TOLOKA_API_KEY instead.` (and the same line for the other two) on stderr once per command. The aliases remain supported for compatibility; rename them to silence the warning and use the current names in new automation.
 
+`TOLOKA_SCOPED_TOKEN` always sends its value in `X-Scoped-Token`, so it supports both issued `pst_…` tokens and secret placeholders such as `dtn_secret_…`. The `--api-key` and `TOLOKA_API_KEY` slots continue to recognize the `pst_` prefix for backward compatibility. Use the explicit scoped-token variable for new agent and CI configuration.
+
 `toloka login` verifies access against the platform before saving anything. A browser login is saved as a session file under `$TOLOKA_CLI_CREDENTIALS_DIR`, which defaults to `~/.toloka/cli/credentials/<auth-host>/<realm>/<client>.json`. When `TOLOKA_CREDENTIALS_FILE` points at an explicit credentials file, sessions go to a `browser-sessions` directory next to it instead, so that profile stays isolated. The platform choice, a stored API key, and local project aliases live in `$XDG_CONFIG_HOME/toloka/credentials.json`, which defaults to `~/.config/toloka/credentials.json`. Both are written with file mode `0600` in directories with mode `0700`. The legacy `~/.toloka/credentials.json` is still read when the new path has no file. `toloka logout` ends the browser session and deletes both files; it does not revoke an API key.
 
 Ordinary usage events (`sdk_cli_command_completed` / `sdk_cli_command_failed`) go to Toloka's PostHog project so we can see which commands run and which error classes they hit. Every failed command with an exception also emits a sanitized PostHog Error Tracking `$exception`; usage errors such as unknown commands or invalid flags do not. Command events contain only an allowlisted command classifier, duration, exit code, outcome or error code, optional HTTP status and server request ID, SDK and Bun versions, actor, and channel. Error Tracking receives the same bounded metadata plus a synthetic exception; raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, response bodies, and source context are not sent. GeoIP enrichment is disabled. Distinct id starts as a random UUID stored next to the credentials file. After a successful authenticated command, the CLI calls `GET /me` and aliases that UUID onto the platform user id without setting person properties. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable capture. CI environments are disabled unless `TOLOKA_TELEMETRY=1`. The explicitly approved full-text `report` event is documented in [report](#report).
@@ -175,6 +178,16 @@ toloka audience specialization list [--json]
 
 Lists every expert specialization (platform qualification) with `ID`, `NAME`, and `EXPERTS` columns, sorted by name. Copy `ID` into `qualificationId` and `NAME` into `value` of `audience.specializations.values[]`; never invent a `qualificationId`. `EXPERTS` is the number of ID-verified experts currently eligible for tasks who hold the specialization; it can be `0` while the id is still valid. Pass `--json` for the full array. Empty output is `No specializations available.`
 
+## generation-model
+
+Inspect the global, read-only catalog of models a synthetic `generation` node can use.
+
+```sh
+toloka generation-model list [--json]
+```
+
+Prints one row per model and reasoning effort with `ID`, `NAME`, `REASONING EFFORT`, `TYPICAL`, `MIN`, and `MAX` columns, then the default and recommended models. Copy `ID` into `generationModelId`. A `-` in `REASONING EFFORT` means the model does not support `reasoningEffort`; leave it unset there. `MIN` and `MAX` bound the `maxCostPerAttempt` apply accepts; a budget below `TYPICAL` is accepted with a warning because generation can stop before the result is complete. `--json` adds each model's description. Empty output is `No generation models available.`
+
 ## login
 
 Signs in through the browser, or stores an API key, after verifying access.
@@ -190,7 +203,7 @@ By default the command asks whether to sign in through the browser or with an AP
 
 Browser login is available for `https://platform.toloka.ai` and the `*.platform.toloka-test.ai` environments. Without a terminal the command opens the chooser page directly and fails fast when no browser can be opened; automation uses an API key instead.
 
-The API key choice does not expire: the key works until it is deleted in the Business Console, which suits scripts, CI, and coding agents. Choosing it asks for the key with masked input; `--api-key-stdin` reads it from standard input instead, so it never appears in shell history or the process list; `--api-key <key>` and `TOLOKA_API_KEY` also work but expose the key to both. Platforms without a known login service go straight to the API key prompt. The command verifies the key and prints `Authenticated against <base-url> with an API key`, then the number of projects visible, where the key is stored, and a reminder that the key does not expire until you delete it in the Business Console.
+The API key choice does not expire: the key works until it is deleted in the Business Console, which suits scripts and CI. Choosing it asks for the key with masked input; `--api-key-stdin` reads it from standard input instead, so it never appears in shell history or the process list; `--api-key <key>` and `TOLOKA_API_KEY` also work but expose the key to both. For an already-issued project-scoped token, set `TOLOKA_SCOPED_TOKEN` for the command instead of storing it with `login`. Platforms without a known login service go straight to the API key prompt. The command verifies the key and prints `Authenticated against <base-url> with an API key`, then the number of projects visible, where the key is stored, and a reminder that the key does not expire until you delete it in the Business Console.
 
 ## logout
 
@@ -210,7 +223,7 @@ Shows which platform and login the CLI would use. Alias: `whoami`.
 toloka auth-status [--show-token]
 ```
 
-On success it prints the platform URL with its source, then either the masked API key or a `Login:` line for the browser session and a `Session:` line with the current refresh window, then the selected project, `Reachable: N project(s) visible.`, `Account:` with the email the platform reports, `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. `--show-token` prints the full API key or the browser session's live access token instead of the mask; pass it only when you need the raw value on this terminal. It exits `1` when no login is in effect, when the browser session has expired, when the platform rejects the login (`Rejected: …`, followed by the advice to run `toloka login`), when the platform does not answer (`Not reachable: …`; the login was not evaluated), or when the platform fails (`Platform error: …`).
+On success it prints the platform URL with its source, then either the masked API key, the masked scoped token with `from TOLOKA_SCOPED_TOKEN`, or a `Login:` line for the browser session and a `Session:` line with the current refresh window. It then prints the selected project, `Reachable: N project(s) visible.`, `Account:` with the email the platform reports, `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. `--show-token` prints the full active credential instead of the mask; pass it only when you need the raw value on this terminal. It exits `1` when no login is in effect, when the browser session has expired, when the platform rejects the credential, or when the platform cannot be reached.
 
 ## config
 
@@ -247,27 +260,33 @@ Generates TypeScript source from a live project.
 toloka import [projectId] [-f]
 ```
 
-When `projectId` is omitted, the selected project is imported. If `pipelines/` already exists, the command exits with `Folder already exists: <path>. Pass --force to replace it.` Pass `-f` or `--force` to replace that directory. On success it prints `Imported project <projectId> with N pipelines and M datasets into <root>.`
+When `projectId` is omitted, the selected project is imported. If `pipelines/` already exists, the command exits with `Folder already exists: <path>. Pass --force to replace it.` Pass `-f` or `--force` to replace that directory. On success it prints `Imported project <projectId> with N pipelines and M datasets into <root>.` A pipeline without a dataset is written without `dataset` in its `definePipeline`.
+
+The generated nodes keep every stored check case, including cases of the retired `ui` and `llmqa` types. A check type with no cases is left out, and a node whose check types are all empty gets no `checks` at all. `plan` and `apply` treat a check type that source leaves out as unmanaged: they neither report nor remove the cases the platform has for it, so set a type to an empty array to remove its cases.
+
+A field whose JSON Schema is stored on the platform as invalid JSON or as an unsupported schema, for example after an unfinished edit in the UI, is imported as `field("name", invalidJsonSchema({ field, reason, text }))` with the stored text. Loading the source then fails with `Field "<name>" has an unreadable JSON Schema on the platform.` until you replace the call with a valid JSON Schema object; the next `apply` writes that schema and repairs the field.
 
 ## plan
 
 Shows what `apply` would change.
 
 ```sh
-toloka plan
+toloka plan [--json]
 ```
 
-On success it prints `No changes.` when the platform matches source, otherwise `Plan: N changes` followed by one line per change. The plan also lists missing project secrets and dataset field schema conflicts so you can resolve them before applying.
+On success it prints `No changes.` when the platform matches source, otherwise `Plan: N changes` followed by one line per change. The plan also lists missing project secrets and dataset field schema conflicts so you can resolve them before applying. `--json` prints `{ "changes": [...], "missingSecrets": [...] }` instead, where each change has `kind`, `action`, `label`, and, when they apply, `pipeline`, `dataset`, and `id`.
 
 ## validate
 
 Runs platform spec validation for each bound pipeline and reports the latest matching check jobs. Does not write the graph.
 
 ```sh
-toloka validate
+toloka validate [--wait]
 ```
 
-On success it prints one line per pipeline: `valid`, `invalid` with issue details, or `skipped` when the pipeline is not on the platform yet. Exits `1` when any submitted graph is invalid.
+It prints one line per pipeline with its status, then its issues: `valid`; `invalid`; `checks-pending` when only check state is open, such as a stored test case or a lint that has not run on this graph; `checks-running` when `--wait` gave up on running checks; or `skipped` when the pipeline or its dataset is not on the platform yet. A `note:` line explains what to do next when `--wait` could not finish. Exits `1` when any submitted graph is invalid or its checks were still running at the `--wait` deadline.
+
+The platform lints a pipeline a few seconds after every apply. While a lint or a check is running, or a lint is about to start after an apply, validate lists it as `running running_node_check`; a lint that has not run on this graph and is no longer expected to start is `pending not_ran_node_check`, and the user runs it from the node's Checks tab. `--wait` validates again every 5 seconds until nothing is running, for up to 5 minutes, then prints the final report; a pipeline whose source differs from the applied graph is not waited on, because its lints start only after `toloka apply`. Right after an apply, plain `toloka validate` can print `valid` and exit `0` while lints are still running, so run `toloka validate --wait` before treating an applied pipeline as valid.
 
 ## check
 
@@ -277,7 +296,7 @@ Runs the complete local gate without platform credentials.
 toloka check [pipeline] [--node <name-or-id>] [--json] [--watch]
 ```
 
-The command loads authored source, runs the project's TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and compares passing typed test evidence with every code node, human-work node, and pipeline. Statuses distinguish `missing`, `failed`, `partial`, and `infrastructure_error`. Exit code `0` means all required checks passed, `1` means source, types, tests, or required coverage failed, and `2` means a required checker could not run.
+The command loads authored source, runs the project's TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and compares passing typed test evidence with every code node, human-work node, and pipeline. Statuses distinguish `missing`, `failed`, `partial`, `warning`, and `infrastructure_error`. `partial` marks a Task UI whose upload or recording fields the headless browser could not exercise; it is reported but does not fail the gate. `warning` marks a `platform-rules` result: nodes connected to the root that break a rule the platform enforces on write. It does not fail the gate, but `toloka apply` refuses to write that pipeline until it is fixed. Exit code `0` means all required checks passed, `1` means source, types, tests, or required coverage failed, and `2` means a required checker could not run.
 
 Use `test.code`, `test.ui`, and `test.pipeline` from `@toloka-platform/sdk/testing` to produce required evidence. Plain Vitest tests still run and can fail the command, but do not satisfy graph coverage. A focused check accepts a pipeline plus `--node`; `--watch` serializes reruns after relevant file changes.
 
@@ -285,7 +304,7 @@ With `--watch`, the command prints one complete report after each serialized run
 
 ## apply
 
-Runs the complete Local Check Gate, then makes the platform match source.
+Runs the complete local gate, then makes the platform match source. It takes no options and never asks for confirmation.
 
 ```sh
 toloka apply
@@ -415,6 +434,16 @@ In a terminal the command asks `Send this report to Toloka? [y/N]`; outside a te
 
 One `sdk_cli_issue_report_submitted` event carries `report_id`, the complete `report_text`, its UTF-8 `report_length_bytes`, `authored_by`, and `platform`, plus the standard pseudonymous CLI telemetry context. The command never reads or sends an API key. It flushes PostHog before printing `Submitted issue report: <id>`; a delivery failure exits non-zero and prints no success ID. When CLI telemetry is disabled, issue reporting is unavailable rather than bypassing that preference.
 
+## ui
+
+Inspect the Task UI components the launcher renders. The command opens the launcher in a headless Chromium (Playwright from the project's `node_modules`), so it needs the same local setup as `toloka check` and no credentials.
+
+```sh
+toloka ui components [names...] [--json]
+```
+
+Without names it prints one line per public component (`name: description When to use: …`). With names it prints each component's description, when to use it, capabilities, limitations, best practices, the `propsType` contract, the value shape, and the documented JSX example with its output. An unknown name fails with `Unknown Task UI components: <name>`. `--json` prints the same contracts keyed by component name. The output always reflects the currently deployed launcher, so run it instead of guessing component names or props from memory.
+
 ## skill
 
 Discover bundled agent skills and install them into the project. The Skill Catalog ships inside the SDK package, so these actions are local and deterministic: they need no credentials, make no network requests, and change with the package version only.
@@ -451,7 +480,7 @@ An unknown command exits 1 before anything else runs, even when `--help` is pres
 
 ## The reconcile loop
 
-Treat the TypeScript source as authoritative. The canonical sequence is: run the complete local gate, validate against the platform, plan, apply, then plan again to confirm convergence.
+Treat the TypeScript source as authoritative. The canonical sequence is: run the complete local gate, validate against the platform, plan, apply, validate again once the platform lints finish, then plan again to confirm convergence.
 
 ```sh
 # 1. Run source, type, and typed test checks
@@ -466,11 +495,14 @@ toloka plan
 # 4. Apply only when the plan matches the intent
 toloka apply
 
-# 5. Confirm the platform matches source
+# 5. Wait for the platform lints that start after apply
+toloka validate --wait
+
+# 6. Confirm the platform matches source
 toloka plan  # expect: No changes.
 ```
 
-`toloka apply` reruns the complete local gate before resolving credentials. `toloka validate` posts each authored graph to `POST /pipelines/:pipelineId/graph/validate`; it reports platform spec validation and the latest matching Remote Node Check jobs without writing the graph. Resolve every unexpected plan change, missing secret, and immutable-field conflict before applying.
+`toloka apply` reruns the complete local gate before resolving credentials. `toloka validate` posts each authored graph to `POST /pipelines/:pipelineId/graph/validate`; it reports platform spec validation and the latest matching check runs without writing the graph. Resolve every unexpected plan change, missing secret, and immutable-field conflict before applying.
 
 ## Further reading
 

package/docs/getting-started.md

@@ -37,7 +37,7 @@ The session renews itself for up to 14 days; after that, run `toloka login` agai
 toloka whoami
 ```
 
-CI does not need `login`. Set `TOLOKA_API_KEY` and the stored login is ignored; an agent without a terminal can pipe a key to `toloka login --api-key-stdin`. See the precedence table in the [CLI reference](./cli.md).
+CI does not need `login`. Set `TOLOKA_API_KEY` for a long-lived API key or `TOLOKA_SCOPED_TOKEN` for an issued project-scoped token, and the stored login is ignored; an agent without a terminal can pipe a long-lived key to `toloka login --api-key-stdin`. See the precedence table in the [CLI reference](./cli.md).
 
 ## Start with an agent
 

package/docs/limitations.md

@@ -19,7 +19,7 @@ The standalone CLI supports macOS and glibc Linux on ARM64 and x64. Native Windo
 | Training course content, when Training is enabled | platform validation  | nothing                |
 | labeler UI validation receipt                     | platform validation  | nothing                |
 
-The typed client can list, start, and poll Remote Node Checks. `toloka check` does not start them: it validates the authored source and its local tests. A `not_ran_node_check` result from `toloka validate` describes remote state rather than missing local evidence. Its severity is check-specific: lint checks report a blocking error, while other checks can report a warning.
+The typed client can list, start, and poll Remote Node Checks. `toloka check` does not start them: it validates the authored source and its local tests. A `not_ran_node_check` or `running_node_check` warning from `toloka validate` describes remote state rather than missing local evidence.
 
 Python code nodes have executable behavior checks but no useful static Python typecheck yet. Their generated `Inputs` and `Outputs` aliases are currently `dict[str, Any]`; adding Pyright or mypy before those aliases become field-derived `TypedDict` contracts would provide little protection.
 
@@ -27,7 +27,7 @@ The standalone CLI's runtime does not provide project test dependencies. Executa
 
 ## Layout is not authored
 
-Node canvas positions are not part of authored source. Existing layout is preserved across applies and the server supplies defaults for new nodes. You cannot lay out a graph from code.
+Node canvas positions are not part of authored source. Existing nodes keep their canvas position across applies. The server places a new node one column to the right of its rightmost input, below any node already in that spot, and moves End to the right when new nodes reach it. You cannot lay out a graph from code.
 
 ## One checkout targets one project
 

package/docs/testing.md

@@ -17,7 +17,7 @@ bun add -d vitest playwright
 bunx playwright install chromium
 ```
 
-Executable code-node tests also require `python3` on the test machine, including any third-party Python packages imported by the authored program. Browser-backed Task UI tests use the separately downloaded Playwright Chromium binary and require network access to the hosted launcher. Training-only CLI workflows require none of these project test tools or a separate JavaScript runtime. See [testing examples](./testing-examples.md) for parameterization, validation failures, hardware coverage, and cleanup patterns.
+Executable code-node tests also require `python3` on the test machine. The platform runs code nodes on Python 3.12 with the standard library only, so a program that imports a package installed only on the test machine passes locally and fails on the platform. Browser-backed Task UI tests use the separately downloaded Playwright Chromium binary and require network access to the hosted launcher. Training-only CLI workflows require none of these project test tools or a separate JavaScript runtime. See [testing examples](./testing-examples.md) for parameterization, validation failures, hardware coverage, and cleanup patterns.
 
 ## Test a code node
 
@@ -83,7 +83,7 @@ Use an ordinary TypeScript loop to register several `test.code` or `test.ui` sce
 
 The low-level `ui` fixture remains available inside ordinary Vitest tests for component discovery and exploratory work, but plain tests do not satisfy required node coverage. Use typed wrappers for committed gate evidence. Importing `@toloka-platform/sdk/testing` from a plain Bun script executes Vitest fixture setup and fails.
 
-- `ui.componentDocumentation(names?)` returns the current launcher's supported component contracts. Call it before choosing component names or props.
+- `ui.componentDocumentation(names?)` returns the current launcher's supported component contracts. `ui` is a fixture argument of `test` (`test("…", async ({ ui }) => …)`), not an export. Outside a test, `toloka ui components [names...]` prints the same contracts.
 - `ui.render(pipeline, node, options)` creates a fresh browser context and returns a Task UI session for exactly that authored node. `test.ui` supplies the equivalent bound `render(options?)` helper.
 
 The returned Task UI session supports:
@@ -110,6 +110,8 @@ Valid JavaScript: `items.map((item) => item.value)`
 
 Invalid runtime JavaScript: `items.map((item: unknown) => item.value)`
 
+Only `data` is in scope in `preprocess` and `postprocess`. `CONST` exists only in `ui.code`, so `toloka check` reports `Cannot find name 'CONST'` when either function reads it: write the value inline in the function, or read it from `ui.code` instead.
+
 `preprocess` can run again after form state changes. Use it to shape input data; if it prefills a bound field, return that key only while it is absent so later edits are not overwritten. A `Field`-bound top-level key already enters the submission. `postprocess` must return only new top-level keys: bind a component to a draft key when postprocess must derive a different entity key.
 
 The fixture loads the hosted TBX launcher in a fresh local Chromium context, so tests require network access but do not use Azure Playwright or Potato application services. The context has no platform cookies or credentials. Use synthetic or redacted fixtures because the hosted launcher executes with access to the supplied test data.
@@ -120,4 +122,4 @@ File pickers, video upload/recording, and other hardware-backed fields cannot be
 
 ## Final gate
 
-`toloka check` loads every authored pipeline, runs the project TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and requires passing `test.code`, `test.ui`, and `test.pipeline` evidence. `missing`, `failed`, `partial`, and `infrastructure_error` are distinct blocking outcomes. `toloka apply` reruns this complete gate before resolving credentials or writing platform state. Platform validation remains separate: a `not_ran_node_check` describes Remote Node Check state rather than missing local evidence, but lint checks report it as a blocking remote error while other checks can report it as a warning.
+`toloka check` loads every authored pipeline, runs the project TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and requires passing `test.code`, `test.ui`, and `test.pipeline` evidence. `missing`, `failed`, and `infrastructure_error` are distinct blocking outcomes. `partial` is reported for a Task UI with hardware-backed fields and does not block: verify those fields on a real device before launching a run. `toloka apply` reruns this complete gate before resolving credentials or writing platform state. Platform validation remains separate: a `not_ran_node_check` warning describes Remote Node Check state rather than missing local evidence.

package/docs/troubleshooting.md

@@ -96,7 +96,7 @@ toloka pipeline results <runId> --failed
 Not logged in. Run toloka login once to sign in through your browser on this machine:
 ```
 
-Run `toloka login`. Where a browser is not available, pipe an API key to `toloka login --api-key-stdin` or set `TOLOKA_API_KEY`. `toloka whoami` reports which platform and which login source is in effect, and exits non-zero when the platform is unreachable.
+Run `toloka login`. Where a browser is not available, pipe a long-lived API key to `toloka login --api-key-stdin` or set `TOLOKA_API_KEY`; set `TOLOKA_SCOPED_TOKEN` when using an issued project-scoped token. `toloka whoami` reports which platform and which credential source is in effect, and exits non-zero when the platform is unreachable.
 
 ## The browser login expired
 

package/examples/README.md

@@ -0,0 +1,11 @@
+# Examples
+
+Complete pipeline projects to borrow structure from. Each directory has a README and a `pipeline.browser.integration.spec.ts` with its typed tests. Borrow the patterns, not the task-specific choices: design the graph, entities, criteria, and Task UI for the task at hand.
+
+| example                        | read it for                                                                                                                                                     |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `product-moderation`           | **start here for a show-an-item, collect-a-judgment task**: one human `generation` node that shows an image and text and collects a label, a subcategory, and a rationale; label lists shared by fields and UI; variants for synthetic generation and several experts |
+| `face-image-collection`        | a human image-annotation node followed by a code node; a structured array output                                                                                |
+| `video-pair-rating`            | side-by-side rating with a `quorum`, deterministic code cascades over rater arrays, `match` routing with `default` branches, and human adjudication             |
+| `egocentric-video-collection`  | data collection with a recording field, a category label driven by one constant list, LLM QA with one criterion per concern, Training with quizzes, stored checks |
+| `app-crowdtesting`             | data collection with an upload field plus structured metadata answers, a step-by-step screen with long text in `ui.constants`, contributor diversity via the per-expert cap |

package/examples/app-crowdtesting/README.md

@@ -0,0 +1,41 @@
+# App crowdtesting
+
+A crowdtesting data-collection pipeline: each tester installs a pre-release Android build on their own phone, screen-records a full session through the app's key flows, uploads the recording, and reports their device model and Android version. An LLM reviews every submission against quality criteria before it is accepted.
+
+The task content is built around a fictional app, Acme Fitness. To adopt it, replace the app everywhere it appears: the install link, node description and public name, entity descriptions, every quality criterion, the instruction, the Task UI constants, and the Training steps and quiz.
+
+## Shape
+
+```
+root.started (item_id)
+  └─> app_flow_test   generation  a tester installs, records, uploads, and describes the device
+      └─> root.completed (app_test_video, device_model, os_version)
+```
+
+Two nodes: one root and one `data_collection` `generation`. Each dataset row is one recording slot; `item_id` carries no task content, so the number of rows is the number of recordings.
+
+## What to read first
+
+| file                                   | why                                                                       |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `nodes/app-flow-test/node.ts`          | the whole task: entities, criteria, instruction, Task UI, and Training    |
+| `fields.ts`                            | a scalar video field fed from a single upload, plus two free-text answers |
+| `pipeline.browser.integration.spec.ts` | how to drive an upload component in a headless UI scenario                |
+
+## Patterns this example demonstrates
+
+**One upload is one entity.** `Field.VideoUpload` always produces an array, but a tester submits one recording. The output field is a scalar URI, the entity is static, and its `jsonPath` selects `$.app_test_video[0].sasLink`, matching the component's `linkType={'sasLink'}` (the contract's recommended link type; `downloadLink` may be inaccessible to end users). Duration bounds are set on both the entity and the component, and they agree.
+
+**Structured metadata next to the upload.** Device model and OS version are separate `SHORT_ANSWER` outputs related to the recording, each with a `required` rule and its own `max` length rule, and each with a criterion that rejects placeholders.
+
+**A step-by-step screen.** The Task UI stacks install, record, and upload as three cards in the order the tester works. Long markdown and the install link live in `ui.constants` and are read as `CONST.*`, so `ui.code` needs no nested template literals and the install link is declared once for both the instruction and the screen.
+
+**LLM QA judges what is visible.** Criteria count attempted flow runs and required screens by on-screen text, never by which control was tapped, and a captured crash counts as a completed run rather than a failure.
+
+**Training that matches the task.** Three steps, ending in a quiz on the rules that most often fail a recording: when to start recording, how many runs each flow needs, and what to do when the app crashes.
+
+**Contributor diversity.** An unverified English-speaking crowd with a per-expert cap of 1, so every recording comes from a different person and device.
+
+## Check locally
+
+Upload and recording controls are hardware-backed, and headless Chromium cannot pick, capture, or upload a file. The UI scenario renders with `allowPartialCoverage: true`, sets the upload value from the component's documented example output, and asserts that coverage is incomplete. It verifies browser validation and the output mapping, not the upload itself, so `toloka check` reports this node as `partial`.

package/examples/app-crowdtesting/fields.ts

@@ -0,0 +1,6 @@
+import { field } from "@toloka-platform/sdk";
+
+export const itemId = field("item_id", { type: "number" });
+export const appTestVideo = field("app_test_video", { type: "string", format: "uri" });
+export const deviceModel = field("device_model", { type: "string" });
+export const osVersion = field("os_version", { type: "string" });