@toloka-platform/sdk 0.2.0 → 0.3.0

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

@@ -1 +1 @@
-ef3e378cf44fae35729752064f23960c37016cb6fd231756a974fc8e239c89ff  toloka.js.jsc
+a22866960e3e7f99095169d57097612bd388f58b10fcc6ba2f11c44d2673a59a  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-f411e3d6a2289108ed93862aedb96f9628cef1a7ee21ec197aa4cf1bb9390ce3  toloka.js
+4280c470c616abb21bd56a2f9528ba82a88b45b6ac02fd8c8ad21a5bfedd1284  toloka.js

package/docs/authoring.md

@@ -152,6 +152,8 @@ export const annotateFaces = generation("annotate_faces", {
 });
 ```
 
+To require a specialization, add `{ value, qualificationId }` entries to `audience.specializations.values`. Both come from the platform catalog — `toloka audience specialization list` — where `NAME` is the `value`, `ID` is the `qualificationId`, and `EXPERTS` tells you how large the pool is. Specializations require `verifiedExperts: true`.
+
 Test the interface locally before applying it. The SDK's Vitest fixture renders this exact `ui` block in Chromium, interacts with Fields by `path`, runs postprocess, validates output entities, and saves screenshots. See [Test pipelines locally](./testing.md).
 
 ### quorum

package/docs/cli.md

@@ -2,19 +2,68 @@
 
 The `toloka` CLI reads TypeScript source as the desired state, compares it with the live platform state, and reconciles the two.
 
-`toloka` `0.2.0` is the current stable CLI on the `latest` channel. Because it ships as part of the `0.x` SDK, commands, flags, and output can change between minor releases.
+The CLI and SDK are versioned together. Before 1.0, commands and authoring APIs can change between minor releases.
 
-`toloka` requires Bun 1.4.0 or newer. The published package ships CLI bytecode built with Bun 1.4.0; another Bun version runs the same bundled JavaScript without that cache and starts slower. The launcher falls back to TypeScript source in a development checkout when the bytecode is absent.
+## Install
+
+```sh
+curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
+```
+
+The installer prefers stable Bun 1.4.0 or newer matching the host architecture and installs the SDK's CLI into Bun's global binary directory. If Bun is missing, older, or built for a different architecture, it installs a standalone executable in `~/.local/bin` without changing Bun. Native downloads support macOS and glibc Linux on ARM64/x64 and require `curl`, `tar`, `mktemp`, and `shasum` or `sha256sum`. Compatible Bun can be used on musl Linux; this shell installer does not support native Windows.
+
+Force the install mode:
+
+```sh
+curl -fsSL https://platform.toloka.ai/cli/install.sh | sh -s -- --native
+curl -fsSL https://platform.toloka.ai/cli/install.sh | sh -s -- --bun
+```
+
+`--native` ignores installed Bun. `--bun` fails if Bun is incompatible. A Bun package installation failure is reported, not retried as a native install.
+
+Add the printed directory to `PATH` if prompted. Verify the selected executable:
+
+```sh
+toloka version --json
+```
+
+Standalone installs report `"channel":"native"`. **Bun is the recommended runtime and package manager for SDK development:**
+
+```sh
+bun add @toloka-platform/sdk@latest
+```
+
+Use `bun i` for an existing project's dependencies. Training-only workflows need no SDK dependency. Local tests may also need Python or Chromium; see [Testing](./testing.md).
+
+The installer accepts these environment variables:
+
+| Variable                 | Effect                                                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `TOLOKA_CLI_INSTALL_DIR` | Override the native install directory; use with `--native`. Bun mode rejects this option and uses Bun's global binary directory. |
+| `TOLOKA_CLI_CHANNEL`     | Select `latest` (the default) or `preview`.                                                                                                  |
+| `TOLOKA_CLI_PACKAGE` | Override the selected mode's package: an SDK package for `--bun`, a matching native package for `--native`. A trailing version or tag overrides the channel. |
+| `TOLOKA_CLI_REGISTRY`    | Fetch installer metadata and the tarball from another npm registry. Automatic updates still use the public npm registry.                    |
+
+Pass overrides to the `sh` process on the right side of the pipe, for example `curl -fsSL https://platform.toloka.ai/cli/install.sh | TOLOKA_CLI_CHANNEL=preview sh`.
+
+### Updates and migration from Bun global installs
+
+Standalone and Bun-global CLIs check the public npm registry at most daily and install eligible releases at least 24 hours old, then rerun the command. Disable with `toloka config set auto-update false`. Project-local installs, CI, help, version, and config commands skip updates; `TOLOKA_SKIP_AUTO_UPDATE=1` also skips them. `TOLOKA_AUTO_UPDATE=0` or `1` overrides the stored setting for one command.
+
+For a manual update, rerun the installer with the original mode (`--bun` or `--native`), directory, channel, package, and registry overrides. A version pin does not disable auto-update; automatic updates always use the public npm registry.
+
+If both installations exist, put the desired directory first on `PATH`, run `hash -r` (Bash) or `rehash` (Zsh), and check `toloka version --json`: `native` means the standalone executable, `global-registry` means the Bun-global CLI. Credentials, settings, and project dependencies stay unchanged.
 
 ## Configuration
 
 Credentials and the platform base URL resolve from the same precedence order, highest first.
 
-| Precedence  | API key source                             |
-| ----------- | ------------------------------------------ |
-| 1 (highest) | `--api-key` flag                           |
-| 2           | `TOLOKA_API_KEY` environment variable      |
-| 3 (lowest)  | credentials file written by `toloka login` |
+| 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`         |
 
 | Precedence  | Base URL source                         |
 | ----------- | --------------------------------------- |
@@ -26,15 +75,13 @@ Credentials and the platform base URL resolve from the same precedence order, hi
 | Precedence  | Project id source                             |
 | ----------- | --------------------------------------------- |
 | 1 (highest) | `--project-id` flag                           |
-| 2           | `TOLOKA_PROJECT_ID` |
+| 2           | `TOLOKA_PROJECT_ID` environment variable      |
 | 3           | `projectId` in `toloka.json`                  |
 | 4 (lowest)  | `current` alias in the credentials file       |
 
 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 login` verifies the key against the platform before saving anything. It writes `$XDG_CONFIG_HOME/toloka/credentials.json`, which defaults to `~/.config/toloka/credentials.json`, with file mode `0600` and a parent directory with mode `0700`. The file may also store local project aliases. The legacy `~/.toloka/credentials.json` is still read when the new path has no file. `toloka logout` deletes the stored file but does not revoke the key.
-
-Machine settings live next to that credentials file in `settings.json` and default `auto-update` to `true`. A globally installed `toloka` checks `https://registry.npmjs.org/` at most once per day and, when a newer `@toloka-platform/sdk` version has been published for at least 24 hours, installs it with `bun add --global` and re-runs the original command. The check is pinned to that registry; a checkout `.env` cannot retarget it. `config`, `version`, and `help` never trigger a check. Project-local installs, CI, and `TOLOKA_SKIP_AUTO_UPDATE=1` also skip it. `TOLOKA_AUTO_UPDATE=0` turns it off for one command; `TOLOKA_AUTO_UPDATE=1` turns it on even when the setting is false.
+`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).
 
@@ -49,6 +96,8 @@ 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.
 
+The CLI colors its output only when standard output is a terminal. `NO_COLOR` with any value, or `TERM=dumb`, turns color off. `FORCE_COLOR` overrides the terminal detection in both directions: `FORCE_COLOR=0` turns color off even on a terminal, and any other value turns it on even when the output is piped.
+
 ## 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>`.
@@ -69,7 +118,7 @@ Resources may also expose specialized actions beyond the Base Actions, such as `
 
 ## version
 
-Print the SDK/CLI version. `toloka version --json` also prints build provenance: the build commit when the bytecode bundle recorded one, the install channel (`global-registry`, `linked`, or `project-local`), and the local package path for linked installs. `toloka -v` and `toloka --version` remain semver-only for scripts.
+Print the SDK/CLI version. `toloka version --json` also prints build provenance: the build commit, the install channel (`native`, `global-registry`, `linked`, or `project-local`), the executable path for a native install, and the package path for a linked install. `toloka -v` and `toloka --version` remain semver-only for scripts.
 
 ```sh
 toloka version [--json]
@@ -108,38 +157,52 @@ toloka delivery-order list
 
 Prints `ID`, `NAME`, `STATUS`, and `CLIENT` columns. Empty output is `No delivery orders visible.`
 
+## audience
+
+Inspect the global, read-only expert audience catalog: the values a node's `audienceAndPricing.audience` filter can use.
+
+```sh
+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.`
+
 ## login
 
-Stores an API key for this machine after verifying it.
+Signs in through the browser, or stores an API key, after verifying access.
 
 ```sh
 toloka login
+toloka login --browser
+toloka login --no-browser
 toloka login --api-key-stdin < key.txt
 ```
 
-The command explains how to generate an API key, prompts for it with masked input, and verifies it against the platform before saving. On success it prints `Authenticated against <base-url>: N project(s) visible.` and `Saved credentials to <path>.`
+By default the command asks whether to sign in through the browser or with an API key. The browser choice opens a local page in the system browser where you continue with Google or Microsoft, the same providers as the platform's own sign-in page (testing environments also offer email and password and the testing users), or follow the link to create a Toloka account first; the page hands you to the Toloka login page, a one-time loopback redirect returns the result to the CLI, and the CLI verifies access by listing projects before saving anything. On success it prints `Logged in to <base-url> as <email>`, then the number of projects visible and when the session stops renewing. The session carries a short-lived access token that the CLI renews on its own; renewal stops 14 days after signing in, or after 8 days without use, and the next command asks you to run `toloka login` again. The session is a credential for the platform API only; it does not work against other Toloka services. `--browser` skips the question and goes straight to the browser flow, even when `TOLOKA_API_KEY` is set; coding agents and scripts that sign the user in should pass it. `--no-browser` does the same but prints the link instead of opening a browser. Set `BROWSER` to choose the browser command.
+
+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.
 
-Without a terminal there is no prompt. `--api-key-stdin` reads the key from standard input, 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.
+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.
 
 ## logout
 
-Removes stored credentials from this machine.
+Ends the browser login and removes stored credentials from this machine.
 
 ```sh
 toloka logout
 ```
 
-On success it prints `Removed <paths>.` and notes that the key is not revoked. When nothing is stored, it prints `No stored credentials found at <path>.`
+On success it prints `Removed <paths>.`; after a browser login it also ends every stored browser session (production and testing) at the login service, and after an API-key login it notes that the key is not revoked. When nothing is stored, it prints `No stored credentials found at <path>.`
 
 ## auth-status
 
-Shows which platform and key the CLI would use. Alias: `whoami`.
+Shows which platform and login the CLI would use. Alias: `whoami`.
 
 ```sh
 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.`, `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: …`).
+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: …`).
 
 ## config
 
@@ -294,8 +357,8 @@ 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 create <name> [--method sft|gisting] (--base-model <id> | --model-version <id>) --dataset <id> [--train-filter field=value] [--validation-dataset <id> [--validation-filter field=value]] [--prompt-file <path>] [--lora-rank 8|16|32 | --gist-tokens 8|32|64|1/4|1/8|1/16|1/32] [--epochs 1..5] [--learning-rate <rate>] [--batch-size 8|16|32|64] [--max-sequence-length <tokens>] [--json]
+toloka training update <name-or-id> [--base-model <id> | --model-version <id>] [--dataset <id>] [--train-filter field=value] [--validation-dataset <id> [--validation-filter field=value]] [--prompt-file <path>] [--lora-rank 8|16|32 | --gist-tokens 8|32|64|1/4|1/8|1/16|1/32] [--epochs 1..5] [--learning-rate <rate>] [--batch-size 8|16|32|64] [--max-sequence-length <tokens>] [--json]
 toloka training cost <name-or-id> [--idempotency-key <key>] [--json]
 toloka training run <name-or-id> [--estimate-file <path>] [--version-name <name>] [--idempotency-key <key>] [--json]
 toloka training runs <name-or-id> [--json]
@@ -306,7 +369,7 @@ 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.
+Hyperparameters are optional flags on `training create` and `training update`: `--epochs 1..5` (default 3), `--learning-rate` (SFT 0.00001–0.001, default 0.00015; gisting 0.001–0.3, default 0.03), `--batch-size 8|16|32|64` (default 8; sequences per optimizer step across all GPUs) and `--max-sequence-length 64..16384` (default 12288 for SFT, 3072 for gisting) apply to both methods; `--lora-rank 8|16|32` (default 16) is SFT-only and `--gist-tokens` (default 32) is gisting-only — passing one to the other method fails before any request. `--gist-tokens` takes an absolute count `8|32|64` or a fraction of the prompt being compressed (`1/4`, `1/8`, `1/16`, `1/32`), which the run resolves to `ceil(prompt tokens / N)` clamped to 8..256. `--regime` and `--eval-steps` no longer exist. `training update` has no `--method` flag: the method stays as created, and every flag you omit keeps its current value. `training cost` is blocked when the longest example exceeds `--max-sequence-length` or when the training selection leaves fewer rows than `--batch-size` after the 10% holdout. `training get` prints the resolved recipe, so omitted flags are visible as their defaults.
 
 ## dataset
 
@@ -362,7 +425,7 @@ toloka skill install <skillId> [--force]
 
 After an SDK upgrade `list` reports installed skills whose catalog digest changed as `stale` until they are refreshed with `install --force`. Local edits to an installed skill also make it `stale`; `list` and `search` never modify local files.
 
-The catalog is bound to the installed package version, so a skill that a newer release ships is simply absent from an older CLI. `install` then exits 1, names the missing skill and installed package version, and creates nothing. Run `toloka skill list` to see the available skills. To get the current supported catalog, update with `bun add --global @toloka-platform/sdk@latest` and retry.
+The catalog is bound to the installed CLI version, so a skill that a newer release ships is absent from an older CLI. `install` then exits 1, names the missing skill and installed version, and creates nothing. Run `toloka skill list` to see the available skills. To get the current supported catalog, rerun the CLI installer and retry.
 
 ## Exit codes
 

package/docs/getting-started.md

@@ -4,16 +4,17 @@ Install the SDK, sign in, and get a pipeline project reconciling from source in
 
 ## Install
 
-Install the bytecode-cached CLI globally and declare the stable SDK in the project:
+Install the CLI, then add the SDK for pipeline authoring:
 
 ```sh
 curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
 bun add @toloka-platform/sdk@latest
+toloka --version
 ```
 
-The installer requires Bun 1.4.0 or newer, installs `@toloka-platform/sdk` globally, and exposes `toloka` through Bun's global binary directory. The published CLI includes bytecode built with Bun 1.4.0; another Bun version runs the same bundled JavaScript without that cache and starts slower. The project install makes SDK imports resolvable.
+**Bun is the recommended runtime and package manager for SDK development.** In an existing project, run `bun i` instead of adding dependencies again. The standalone CLI includes its runtime; Training-only workflows do not need the SDK.
 
-`latest` currently installs stable `0.2.0`, including Training commands and the bundled agent runbooks and skills. Use `bun add @toloka-platform/sdk@0.2.0` when you need an exact, reproducible project dependency.
+The installer prefers compatible Bun and otherwise installs a standalone executable. Add the printed directory to `PATH` if prompted. See [CLI setup](./cli.md#install) for mode overrides and updates, and [Testing](./testing.md) for local test dependencies.
 
 ## Sign in
 
@@ -21,21 +22,22 @@ The installer requires Bun 1.4.0 or newer, installs `@toloka-platform/sdk` globa
 toloka login
 ```
 
-`login` explains where to generate an API key, prompts for it without echoing, verifies it against the platform, and only then stores it. A key that does not authenticate is never written to disk.
+`login` asks whether to sign in through the browser or with an API key, opens a page in your browser where you pick the provider, verifies access against the platform, and only then stores the session. Nothing is written when the platform does not accept the account.
 
 ```
-API key: ******************
-Authenticated against https://platform.toloka.ai: 12 project(s) visible.
-Saved credentials to /Users/you/.config/toloka/credentials.json.
+? How do you want to sign in? Sign in with your browser
+Waiting for the sign-in to finish in your browser... If no browser opened, run toloka login --no-browser to get a link.
+✔ Logged in to https://platform.toloka.ai as you@example.com
+  12 projects visible · session renews automatically until 2026-09-25T10:00:00Z, then run toloka login again
 ```
 
-Check what the CLI will use at any time:
+The session renews itself for up to 14 days; after that, run `toloka login` again. Check what the CLI will use at any time:
 
 ```sh
 toloka whoami
 ```
 
-CI does not need `login`. Set `TOLOKA_API_KEY` and the stored file is ignored. See the precedence table in the [CLI reference](./cli.md).
+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).
 
 ## Start with an agent
 

package/docs/limitations.md

@@ -4,6 +4,10 @@ Current constraints of the stable SDK, stated plainly so you can decide what to
 
 `@toloka-platform/sdk` `0.2.0` is the current stable release on `latest`. Because it is a `0.x` release, the authoring API, CLI surface, and generated source layout can change between minor versions. Use `latest` for the current supported release, or pin `@toloka-platform/sdk@0.2.0` for reproducible installs.
 
+## Native CLI availability
+
+The standalone CLI supports macOS and glibc Linux on ARM64 and x64. Native Windows and musl Linux executables are not available yet. It includes its runtime, so running the CLI does not require Bun or Node.js. See [CLI installation](./cli.md#install).
+
 ## Local checks do not certify deployability
 
 `toloka check` is the required credential-free local gate. It runs project TypeScript, automatic Task UI typechecking, Vitest, and typed node and pipeline-flow coverage. `toloka apply` reruns it before any platform write.
@@ -19,6 +23,8 @@ The typed client can list, start, and poll Remote Node Checks. `toloka check` do
 
 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.
 
+The standalone CLI's runtime does not provide project test dependencies. Executable code-node tests need `python3` and their imported packages. Task UI tests need Playwright and its Chromium binary. See [Test pipelines locally](./testing.md#install-test-dependencies).
+
 ## 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.

package/docs/testing-examples.md

@@ -239,9 +239,9 @@ await task.close();
 
 ## Setup and execution
 
+Install any missing test tools as described in [Test pipelines locally](./testing.md#install-test-dependencies). Then run:
+
 ```sh
-bun add --dev vitest playwright
-bunx playwright install chromium
 toloka check
 ```
 

package/docs/testing.md

@@ -4,12 +4,20 @@ The `@toloka-platform/sdk/testing` entry point provides typed Vitest wrappers fo
 
 ## Install test dependencies
 
+The standalone CLI includes its runtime, but project test runners and browser binaries remain project dependencies. Bun is the recommended runtime and package manager for SDK development. In an existing project, install its declared dependencies first:
+
+```sh
+bun i
+```
+
+When they are not already declared, add Vitest and Playwright and install Chromium:
+
 ```sh
-bun add --dev vitest playwright
+bun add -d vitest playwright
 bunx playwright install chromium
 ```
 
-Code-node tests also require `python3` on the test machine. 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, 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.
 
 ## Test a code node
 

package/docs/troubleshooting.md

@@ -2,7 +2,11 @@
 
 The failures you will actually hit, what causes each, and the next step that works.
 
-Every entry here has been reproduced against a live platform. Where the right fix is on the platform side rather than yours, this page says so instead of suggesting a workaround that does not exist.
+Platform behavior described here has been reproduced against a live platform. Installation entries describe the shipped installer and CLI. Where the right fix is platform-side rather than local, this page says so instead of suggesting a workaround that does not exist.
+
+## Installer succeeded but the shell runs an old CLI
+
+Run `toloka version --json`. If it reports `"channel":"global-registry"` or an unexpected version or path, follow [Updates and migration from Bun global installs](./cli.md#updates-and-migration-from-bun-global-installs). Rerun the installer for an immediate update; there is no `toloka update` command.
 
 ## plan reports a change immediately after apply
 
@@ -89,11 +93,19 @@ toloka pipeline results <runId> --failed
 ## Missing credentials
 
 ```
-Missing API key. Run toloka login once to store credentials for this machine.
+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.
+
+## The browser login expired
+
+```
+Your browser login for https://platform.toloka.ai has expired.
 ```
 
-Run `toloka login`. Where interactive login is not possible, pipe the key to `toloka login --api-key-stdin` or set `TOLOKA_API_KEY`. `toloka whoami` reports which platform and which key source is in effect, and exits non-zero when the platform is unreachable.
+A browser session renews itself for up to 14 days after signing in, or 8 days without use. Run `toloka login` again.
 
 ## Authentication fails with a key you just generated
 
-Keys are scoped to the platform that issued them. A key from one platform's console will not authenticate against a different platform. `whoami` prints the base URL it is using; confirm it matches the console where the key was generated.
+Keys are scoped to the platform that issued them. A key from one platform's console will not authenticate against a different platform. `whoami` prints the base URL it is using; confirm it matches the console where the key was generated. The same holds for browser logins: `ENV=prestable toloka login` signs in to the testing login service, and a production login does not serve prestable.

package/openapi/gen/api.ts

@@ -32,6 +32,8 @@ import type {
   GetTrainingRunLogsParams,
   GetTrainingRunMetricHistoryParams,
   ImportPipelineBody,
+  ListAudienceSpecializations200,
+  ListAudienceSpecializationsParams,
   ListBaseModels200,
   ListDatasetFields200,
   ListDatasetFieldsParams,
@@ -686,6 +688,34 @@ export const cancelTrainingRun = async (trainingRunId: TrainingRunId, options?:
 
 
 
+export const getListAudienceSpecializationsUrl = (params?: ListAudienceSpecializationsParams,) => {
+  const normalizedParams = new URLSearchParams();
+
+  Object.entries(params || {}).forEach(([key, value]) => {
+    
+    if (value !== undefined) {
+      normalizedParams.append(key, value === null ? 'null' : value.toString())
+    }
+  });
+
+  const stringifiedParams = normalizedParams.toString();
+
+  return stringifiedParams.length > 0 ? `/api/v2-beta/audience/specializations?${stringifiedParams}` : `/api/v2-beta/audience/specializations`
+}
+
+export const listAudienceSpecializations = async (params?: ListAudienceSpecializationsParams, options?: RequestInit): Promise<ListAudienceSpecializations200> => {
+  
+  return potatoFetch<ListAudienceSpecializations200>(getListAudienceSpecializationsUrl(params),
+  {      
+    ...options,
+    method: 'GET'
+    
+    
+  }
+);}
+
+
+
 export const getGetCurrentUserUrl = () => {
 
 

package/openapi/gen/models/gistingTrainingConfigurationGistTokens.ts

@@ -1,2 +1,2 @@
 
-export type GistingTrainingConfigurationGistTokens = 8 | 32 | 64;
+export type GistingTrainingConfigurationGistTokens = 8 | 32 | 64 | '1/4' | '1/8' | '1/16' | '1/32';

package/openapi/gen/models/gistingTrainingConfigurationInputGistTokens.ts

@@ -1,2 +1,2 @@
 
-export type GistingTrainingConfigurationInputGistTokens = 8 | 32 | 64;
+export type GistingTrainingConfigurationInputGistTokens = 8 | 32 | 64 | '1/4' | '1/8' | '1/16' | '1/32';

package/openapi/gen/models/index.ts

@@ -280,6 +280,8 @@ export * from './jsonSchema';
 export * from './jsonSchemaAdditionalProperties';
 export * from './jsonSchemaType';
 export * from './jsonSchemaTypeAnyOfItem';
+export * from './listAudienceSpecializations200';
+export * from './listAudienceSpecializationsParams';
 export * from './listBaseModels200';
 export * from './listDatasetFields200';
 export * from './listDatasetFieldsParams';
@@ -829,6 +831,7 @@ export * from './sftTrainingConfigurationInput';
 export * from './sftTrainingConfigurationInputBatchSize';
 export * from './sftTrainingConfigurationInputLoraRank';
 export * from './sftTrainingConfigurationLoraRank';
+export * from './specialization';
 export * from './training';
 export * from './trainingArchivedAt';
 export * from './trainingConfiguration';

package/openapi/gen/models/listAudienceSpecializations200.ts

@@ -0,0 +1,7 @@
+import type { Specialization } from './specialization';
+import type { Pagination } from './pagination';
+
+export type ListAudienceSpecializations200 = {
+  specializations: Specialization[];
+  pagination: Pagination;
+};

package/openapi/gen/models/listAudienceSpecializationsParams.ts

@@ -0,0 +1,5 @@
+
+export type ListAudienceSpecializationsParams = {
+limit?: number;
+offset?: number;
+};

package/openapi/gen/models/specialization.ts

@@ -0,0 +1,6 @@
+
+export interface Specialization {
+  id: string;
+  name: string;
+  expertsCount: number;
+}

package/openapi/gen/models/trainingCostEstimateOneOfTwoseven.ts

@@ -15,8 +15,6 @@ export type TrainingCostEstimateOneOfTwoseven = {
   status: 'ready';
   issues: TrainingCostEstimateOneOfTwosevenIssuesItem[];
   budget: TrainingCostEstimateOneOfTwosevenBudget;
-  basePricePerGpuHour: string;
-  marginMultiplier: string;
   maximumCharge: string;
   currency: 'USD';
   fingerprint: string;

package/openapi/gen/models/trainingRunQuote.ts

@@ -10,8 +10,6 @@ export type TrainingRunQuote = {
   pricingVersion: string;
   calculatedAt: string;
   budget: TrainingRunQuoteBudget;
-  basePricePerGpuHour: string;
-  marginMultiplier: string;
   maximumCharge: string;
   currency: 'USD';
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change between minor versions before 1.0.",
   "license": "Apache-2.0",

package/skills/catalog.json

@@ -11,8 +11,8 @@
         "testing",
         "checks"
       ],
-      "version": "0.2.0",
-      "digest": "d1475f85dad9f81a8a0321778466ca21e2c93f04094f402a4ad83ac92641b99c",
+      "version": "0.3.0",
+      "digest": "c5433bf9639a469672ae24f9edcb05b091f83c3c451ed83400dba86027c4b88f",
       "files": [
         "SKILL.md",
         "references/node-semantics.md",
@@ -29,8 +29,8 @@
         "bug",
         "report"
       ],
-      "version": "0.2.0",
-      "digest": "56a0c283649052c85ba882f05d4a996bd98bf1bc011bc7a70af234b3664057d6",
+      "version": "0.3.0",
+      "digest": "70f0bd2c80b32f87896aeb27c363b8a2d37f40e22424f57fe1aad142e125ad67",
       "files": [
         "SKILL.md",
         "references/report-template.md"
@@ -46,8 +46,8 @@
         "getting-started",
         "agent"
       ],
-      "version": "0.2.0",
-      "digest": "61a3cf60f0b7d00e48c9663ed6e0e3d77fd3923e528cee52e16ef6e2ccebae69",
+      "version": "0.3.0",
+      "digest": "ccf148c682de4e452bb031db95d3933257899006b1766f0fdbc3d15265a63bb9",
       "files": [
         "SKILL.md"
       ]
@@ -63,8 +63,8 @@
         "sft",
         "models"
       ],
-      "version": "0.2.0",
-      "digest": "ee961e8daea643998b00918055214316e27ab99b43c1015c0af24f86deb97502",
+      "version": "0.3.0",
+      "digest": "eeea5c38f65319b8d825be951094fbd00354dc5b990bdca383c1006e84c825e9",
       "files": [
         "SKILL.md"
       ]
@@ -80,8 +80,8 @@
         "prompt",
         "models"
       ],
-      "version": "0.2.0",
-      "digest": "2dd5dc9aef29c7f2840b1047ac2c03d4f096bfdba62db72e848c4051b5481bed",
+      "version": "0.3.0",
+      "digest": "766a4029b344469d2df97fbd5f607d4dcbbae5f1e6ab209cea65825f64cdf6f4",
       "files": [
         "SKILL.md"
       ]

package/skills/toloka-build/SKILL.md

@@ -102,12 +102,15 @@ Register code behavior with `test.code(pipeline, node, name, callback)` and exec
 
 ## Credentials
 
-`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 credentials are missing, ask the user to run `toloka login` in their terminal; never request a key in chat.
+`toloka login` signs the user in through the browser, or stores an API key when they choose that, and
+keeps the login with owner-only permissions, so no later command needs `--api-key`. Precedence is flag,
+then environment variable (`TOLOKA_API_KEY`, `TOLOKA_BASE_URL`), then the stored API key, then the
+browser session. `toloka auth-status` reports what is in effect and where it came from; `toloka logout`
+ends the browser session and removes the stored files. If credentials are missing, run `toloka login --browser`
+yourself: it opens the sign-in page in the user's browser and waits, so ask the user to pick their
+provider and finish signing in there. 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`.
+Standalone and Bun-global CLI installations check for eligible public releases at most daily; turn that off with `toloka config set auto-update false`. See [workflow and CLI recipes](references/workflow-and-cli.md) for manual updates, installer overrides, and version-pin behavior.
 
 ## Recover from expected failures
 

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

@@ -164,7 +164,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 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.
+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 discover new ones with `toloka audience specialization list`, copying `ID` into `qualificationId` and `NAME` into `value`; never invent one.
 
 `$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.
 
@@ -281,7 +281,7 @@ Ordering is semantic: `conditions[0]` routes to `matched(0)`, the first true con
 
 When the requirement depends on one of these capabilities, state the gap instead of inventing source syntax:
 
-- Audience discovery and validation helpers have no SDK or CLI path: valid-language/country/specialization suggestions, audience-size statistics, and recommended-rate calculation.
+- Audience discovery beyond specializations has no SDK or CLI path: valid-language/country suggestions, audience-size statistics for a composed filter, and recommended-rate calculation. Specializations and their expert counts come from `toloka audience specialization list`.
 - 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 `@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.