@toloka-platform/sdk 0.2.1 → 0.3.0

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

@@ -1 +1 @@
-5c6e6ba38b31803da60d3f8371a159ce99d5e156595e002cd7a4f6e6c9432cf8  toloka.js.jsc
+a22866960e3e7f99095169d57097612bd388f58b10fcc6ba2f11c44d2673a59a  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-88ba4c829ee5f68917b216cfdaefcbf44528cb059013afd242f499d15caf506d  toloka.js
+4280c470c616abb21bd56a2f9528ba82a88b45b6ac02fd8c8ad21a5bfedd1284  toloka.js

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]
@@ -120,36 +169,40 @@ Lists every expert specialization (platform qualification) with `ID`, `NAME`, an
 
 ## 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
 
@@ -372,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.2.1",
+  "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.1",
-      "digest": "b7ffd9ccebdbb7cae9cf672cd3e43afa2c353398b8ea89a2558e8b7277b83fb7",
+      "version": "0.3.0",
+      "digest": "c5433bf9639a469672ae24f9edcb05b091f83c3c451ed83400dba86027c4b88f",
       "files": [
         "SKILL.md",
         "references/node-semantics.md",
@@ -29,8 +29,8 @@
         "bug",
         "report"
       ],
-      "version": "0.2.1",
-      "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.1",
-      "digest": "61a3cf60f0b7d00e48c9663ed6e0e3d77fd3923e528cee52e16ef6e2ccebae69",
+      "version": "0.3.0",
+      "digest": "ccf148c682de4e452bb031db95d3933257899006b1766f0fdbc3d15265a63bb9",
       "files": [
         "SKILL.md"
       ]
@@ -63,8 +63,8 @@
         "sft",
         "models"
       ],
-      "version": "0.2.1",
-      "digest": "75b7909bfaf8fdc13a91515efdcdbdcad31fd3355fa3401f22ee66e24258098c",
+      "version": "0.3.0",
+      "digest": "eeea5c38f65319b8d825be951094fbd00354dc5b990bdca383c1006e84c825e9",
       "files": [
         "SKILL.md"
       ]
@@ -80,8 +80,8 @@
         "prompt",
         "models"
       ],
-      "version": "0.2.1",
-      "digest": "8bd6fee5baa84e6f94871eebf34e916bf3f5deb202c60fb9e063ebbc68ddb5b3",
+      "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/workflow-and-cli.md

@@ -28,47 +28,69 @@ Treat the three layers differently:
 
 For a first-time guided session, consult `https://platform.toloka.ai/agents/data-labeling.md` for orientation. Adapt the journey to the user's goal and already-complete setup while preserving dependencies, cost approval, and identity/source protection; use this reference for command details.
 
-Install the SDK before invoking project commands:
+Bun is the recommended runtime and package manager for pipeline authoring. In an existing source root, install its declared dependencies:
 
 ```sh
-bun add --dev @toloka-platform/sdk@latest
+bun i
+```
+
+For a new pipeline project, add the SDK, TypeScript, and Vitest:
+
+```sh
+bun add -d @toloka-platform/sdk@latest typescript vitest
+```
+
+These are project authoring and test dependencies, not prerequisites for running the standalone CLI or a Training-only workflow. Task UI scenarios additionally require Playwright and Chromium:
+
+```sh
+bun add -d playwright
+bunx playwright install chromium
 ```
 
 Select or create the intended platform project before `toloka init` when the checkout should be bound immediately; follow the adoption or scratch recipe below. Running `init` without explicit or checkout-local project identity installs only the agent entry points and never adopts the machine registry's current project.
 
-`toloka init` 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.
+`toloka init` warns when `@toloka-platform/sdk` is not declared in `dependencies` or `devDependencies`, then maintains one `<toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: a Claude skill at `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and an always-applied Cursor rule at `.cursor/rules/toloka-bootstrap.mdc` when `.cursor/rules/` exists. The dependency warning applies to pipeline authoring; Training commands do not require the SDK dependency. `init` writes `toloka.json` only from an explicit project flag/environment value or an existing checkout binding.
 
-The bootstrap is small: it tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search <query>`, install the match with `toloka skill install <skill-id>`, and read `.agents/skills/<skill-id>/SKILL.md`. This skill is that installed copy. Commands warn on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the 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.
+The bootstrap is small: it tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search <query>`, install the match with `toloka skill install <skill-id>`, and read `.agents/skills/<skill-id>/SKILL.md`. This skill is that installed copy. Commands warn on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the running CLI's bundled version, independently of any project SDK dependency. Help, `init`, `report`, `project url`, `config`, and version invocations skip this checkout-dependent warning. The warning never blocks a command; after updating the standalone CLI, re-run `toloka init` to refresh the bootstrap and its pointers.
 
-## Store credentials once
+## Sign in once
 
 ```sh
 toloka login
 ```
 
-It explains where to generate an API key — `console.toloka.ai` → Company → API Keys → Generate API Key
-— reads the key without echoing it, verifies it by listing one project, and only then saves the
-credentials file with mode `0600`. Nothing is written when the key does not authenticate.
-
-Most later commands read that file, so `--api-key` becomes optional. For networked commands that do
-not mutate the machine project registry, key precedence is flag, then `TOLOKA_API_KEY`, then the
-stored file; CI can use an environment variable without running login. Non-interactive callers can
-skip the login prompt by piping the key to `toloka login --api-key-stdin`; `toloka login --api-key <key>`
-also works but leaves the key in shell history. The base URL defaults to the platform.
+It asks whether to sign in through the browser or with an API key. The browser choice opens a page in
+the browser where the user continues with Google or Microsoft (testing environments also offer email
+and password and the testing users), hands them to the Toloka login page, waits for the sign-in to finish, verifies access by
+listing one project, and only then saves the browser session under `~/.toloka/cli/credentials/` with
+mode `0600`. Nothing is written when the platform does not accept the account. The session renews
+itself for up to 14 days; after that `toloka login` is needed again. Run `toloka login --browser` yourself
+by default: it skips the question, opens the sign-in page in the user's browser, and waits for them to
+finish; without a terminal it fails fast when no browser can be opened. `toloka login --no-browser` prints
+the link instead of opening a browser.
+
+The API key choice does not expire: the key works until it is deleted in the Business Console, which
+suits scripts, CI, and coding agents. Type it at the masked prompt, or pipe it to `toloka login --api-key-stdin`.
+`toloka login --api-key <key>` also works but leaves the key in shell history. Most later commands read the stored login, so
+`--api-key` becomes optional. For networked commands that do not mutate the machine project registry,
+credential precedence is flag, then `TOLOKA_API_KEY`, then the stored API key, then the browser
+session; CI can use an environment variable without running login. The base URL defaults to the platform.
 
 ```sh
 toloka auth-status     # or toloka whoami
 toloka logout
 ```
 
-`auth-status` reports which platform and key are in effect and where each came from, masks the key
-unless you pass `--show-token`, and exits non-zero on failure — use it to check a setup rather than
-guessing. Its last lines say which failure it was: `Rejected:` means the platform refused the key
-(run `toloka login` with a working one); `Not reachable:` means the platform did not answer, so the
-key was not evaluated (fix network access, do not ask for a new key); `Platform error:` means the
-platform failed (retry later). `logout` deletes the stored file; it does not revoke the key.
+`auth-status` reports which platform and login are in effect and where each came from and exits
+non-zero on failure — use it to check a setup rather than guessing. It masks the credential; `--show-token`
+prints the full API key or the browser session's live access token, so pass it only when a command
+genuinely needs the raw value and never paste the output into chat. Its last lines say which failure it was: `Rejected:` means the platform refused the login
+(run `toloka login` again); `Not reachable:` means the platform did not answer, so the login was not
+evaluated (fix network access, do not ask for a new login); `Platform error:` means the platform
+failed (retry later). `logout` ends every stored browser session and deletes the stored files; it does not
+revoke an API key.
 
-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`.
+Standalone and Bun-global `toloka` installations check the public npm registry at most once per day and install eligible releases at least 24 hours old before rerunning the command. Project-local installs, CI, and `config`, `version`, and `help` skip the check. Turn it off with `toloka config set auto-update false`. For manual standalone updates, rerun `curl -fsSL https://platform.toloka.ai/cli/install.sh | sh -s -- --native`; Bun-global updates should use `--bun` instead. Preserve the mode and put any original `TOLOKA_CLI_INSTALL_DIR`, `TOLOKA_CLI_CHANNEL`, `TOLOKA_CLI_PACKAGE`, and `TOLOKA_CLI_REGISTRY` overrides on the `sh` side of the pipe again. A package version pin does not disable automatic updates, which always use the public npm registry.
 
 ## Configure the CLI
 
@@ -90,7 +112,7 @@ The real command surface is:
 toloka version [--json]
 toloka -v
 toloka --version
-toloka login
+toloka login [--browser] [--no-browser] [--api-key-stdin]
 toloka logout
 toloka auth-status
 toloka config

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

@@ -39,10 +39,9 @@ For first-time setup details, read `https://platform.toloka.ai/agents/fine-tunin
 
 ### 1. Establish only the context the goal needs
 
-When runtime, authentication, or binding is unknown, inspect it:
+When the CLI, authentication, or binding is unknown, inspect it. The runtime-inclusive standalone CLI is sufficient for Training-only work; no separate Bun or Node.js installation, SDK, TypeScript, or test packages are needed:
 
 ```sh
-bun --version
 toloka --version
 toloka whoami
 toloka project current

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

@@ -19,10 +19,11 @@ The workflow sequence preserves important dependencies and gates, but it is not
 
 ## Prepare missing prerequisites
 
-Check the runtime or CLI only when its state is not already known:
+Check the CLI only when its state is not already known. The installer prefers stable Bun 1.4.0 or newer matching the host architecture; otherwise it installs a standalone executable with its runtime included. Use `sh -s -- --native` or `sh -s -- --bun` on the installer pipe to force a mode. For custom packages or directories, choose the matching mode explicitly. Training-only workflows need no project SDK or test dependencies. For pipeline authoring, Bun is recommended: run `bun i` in an existing project and use `bun add -d` for missing packages.
+
+The shell installer supports macOS and Linux on ARM64/x64. The native path requires glibc on Linux, plus `curl`, `tar`, `mktemp`, and either `shasum` or `sha256sum`; compatible Bun can be used on musl. Native Windows packages are not available.
 
 ```sh
-bun --version
 toloka --version
 toloka dataset --help
 ```
@@ -39,7 +40,7 @@ Never request an API key in chat. Inspect the active identity with:
 toloka whoami
 ```
 
-If the reachable account is evidently the intended identity from the request, project, team, or established checkout, continue and report it. Ask a focused question when the identity conflicts with that context or more than one material choice remains. For a missing or rejected key, ask the user to run `toloka login`, then verify `toloka whoami` again. `Rejected:` means the key was refused; `Not reachable:` means the platform did not answer and the key was not evaluated, so fix network access rather than requesting another key; `Platform error:` means the platform failed, so retry later.
+If the reachable account is evidently the intended identity from the request, project, team, or established checkout, continue and report it. Ask a focused question when the identity conflicts with that context or more than one material choice remains. For a missing, expired, or rejected login, run `toloka login --browser` yourself: it opens the sign-in page in the user's browser and waits, so ask the user to finish signing in there, then verify `toloka whoami` again. `Rejected:` means the login was refused; `Not reachable:` means the platform did not answer and the login was not evaluated, so fix network access rather than requesting another sign-in; `Platform error:` means the platform failed, so retry later.
 
 Pipeline work needs a source root. Reuse a suitable initialized root when one exists. In a new root, or when the Agent Bootstrap or installed skills genuinely need initialization or refresh, use:
 

package/skills/toloka-gisting/SKILL.md

@@ -40,10 +40,9 @@ For first-time setup details, read `https://platform.toloka.ai/agents/gisting.md
 
 ### 1. Establish only the context the goal needs
 
-When runtime, authentication, or binding is unknown, inspect it:
+When the CLI, authentication, or binding is unknown, inspect it. The runtime-inclusive standalone CLI is sufficient for Training-only work; no separate Bun or Node.js installation, SDK, TypeScript, or test packages are needed:
 
 ```sh
-bun --version
 toloka --version
 toloka whoami
 toloka project current

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.2.0 (`toloka --version`), Bun 1.4.0, macOS 15
+- Toloka CLI: native 0.2.0, build a1b2c3d4e5f6 (`toloka version --json`); macOS 15
 - Platform: https://platform.toloka.ai
 
 ## Redactions