@toloka-platform/sdk 0.1.0-preview.4 → 0.1.0-preview.5

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

@@ -1 +1 @@
-dfdcb0c64d04df834c08b292facaf8edb31aba8a00876f29d6240cd08c9bf378  toloka.js.jsc
+bbe06fffb8a659ebc2903d962ff2b4a225fe3abc691e607a01258350163c36c7  toloka.js.jsc

package/dist/cli/toloka.js.sha256

@@ -1 +1 @@
-0e0efdf2d8a9bfacfacd3801a8cd89ceaa80534f262dbf4c9617fc7c22ef822c  toloka.js
+43e152b2ae5342013785dd1c89843bead8b68039ea6576ae5a8bea5944263127  toloka.js

package/docs/cli-v2.md

@@ -80,6 +80,7 @@ toloka project list                          # remote projects this key can see
 toloka project add cat-labeling pp.019f…     # register + select
 toloka project switch cat-labeling
 toloka project current                       # alias of the project line in whoami
+toloka project url                           # print the selected project's UI URL
 toloka project remove cat-labeling           # local unbind only
 ```
 
@@ -95,6 +96,8 @@ toloka project create cat-labeling --team-id <teamId>
 
 `project create` writes the machine alias, sets `current`, and if cwd has no `toloka.json`, writes one.
 
+UI links follow the resource-first shape `toloka <resource> url`. `project url` is available now; future pipeline, dataset, and other entity links belong under their existing resource groups. Every `url` command prints exactly one URL with no label to stdout. Opening a browser, if added, must be an explicit `--web` option rather than the default.
+
 ### init
 
 `init` sets up **this directory** for an agent. A selected platform project is optional.
@@ -118,6 +121,7 @@ Resource commands never search the disk for a pipeline first. They load the proj
 
 | Command                       | Scope                         | Pipeline required? |
 | ----------------------------- | ----------------------------- | ------------------ |
+| `project url`                 | project UI URL                | no                 |
 | `plan` / `apply` / `validate` | whole project                 | no                 |
 | `secret set`                  | project                       | no                 |
 | `dataset list`                | project                       | no                 |

package/docs/cli.md

@@ -33,7 +33,7 @@ Credentials and the platform base URL resolve from the same precedence order, hi
 
 `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.
 
-Anonymous 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. Event payloads contain only an allowlisted command classifier, duration, exit code, outcome or error code, SDK and Bun versions, actor, and channel. Raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, 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 turn this off. CI is off unless you set `TOLOKA_TELEMETRY=1`.
+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. Their payloads contain only an allowlisted command classifier, duration, exit code, outcome or error code, SDK and Bun versions, actor, and channel. Raw arguments, flag values, environment variables, API keys, secret names, base URLs and hosts, local paths, project ids, error messages, stack traces, 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).
 
 The root program accepts these flags before any command:
 
@@ -44,7 +44,21 @@ The root program accepts these flags before any command:
 | `--base-url <url>`          | Platform base URL for this command only                          |
 | `--project-id <id>`         | Target project; overrides env, checkout, and the registry        |
 
-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` does not walk up: it binds the working directory or `--source-root` only. The authentication commands `login`, `logout`, and `auth-status` do not need a project root.
+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.
+
+## Resources and Base Actions
+
+The CLI is resource-first: `toloka <resource> <action>`. A Base Action has one meaning wherever a resource implements it. A resource exposes only the Base Actions that have real behavior; there are no placeholder actions.
+
+| Base Action | Meaning                                                                                   |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `list`      | Read a bounded, paginated collection of one Resource type.                                |
+| `get`       | Read exactly one Resource selected by a stable identifier.                                |
+| `create`    | Create exactly one Resource and return its stable identifier and representation.          |
+| `delete`    | Remove exactly one Resource selected by a stable identifier and return no representation. |
+| `url`       | Read exactly one browser-ready URL with no surrounding prose.                             |
+
+Resources may also expose specialized actions beyond the Base Actions, such as `pipeline cost`, `skill search`, and `skill install`.
 
 ## project
 
@@ -55,12 +69,15 @@ toloka project list
 toloka project add [alias] [projectId]
 toloka project switch <alias>
 toloka project current
+toloka project url
 toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>]
 ```
 
 `add`, `switch`, `remove`, and `create` write the machine registry in the credentials file. They refuse `--api-key` / `--base-url` / `POTATO_*` when those would select a different key or platform than the stored file. `create` reuses the only visible team when every listed project shares one; otherwise pass `--team-id`.
 
+`url` fetches the selected project to resolve its team and prints only its platform UI URL to stdout, making the output safe to capture in scripts and agent workflows.
+
 ## login
 
 Stores an API key for this machine after verifying it.
@@ -93,15 +110,17 @@ On success it prints the platform URL with its source, the API key masked unless
 
 ## init
 
-Initializes the current project directory and installs agent entry points.
+Initializes the current project directory and installs the Agent Bootstrap entry points.
 
 ```sh
 toloka init
 ```
 
-`init` does not require a selected platform project. It always writes `.claude/skills/toloka-build/SKILL.md`, `.cursor/rules/toloka-build.mdc` when Cursor configuration exists, and an SDK-owned block in `AGENTS.md`. When a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing. It does not walk up to a parent checkout.
+`init` does not require a selected platform project. It always maintains one `<toloka>` … `</toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and `.cursor/rules/toloka-bootstrap.mdc` with `alwaysApply: true` when `.cursor/rules/` exists. The bootstrap tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search`, install a matching skill with `toloka skill install`, and read `.agents/skills/<skill-id>/SKILL.md`; it does not embed the build workflow. Bytes outside the block are preserved, and re-running `init` refreshes the block and both pointers in place without adding duplicates. When a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing. It does not walk up to a parent checkout.
+
+`init` removes only Toloka-generated legacy entry points that still carry the `<!-- toloka:sdk-version … -->` marker: the full `toloka-build` and `toloka-pipeline-as-code` Claude skills and Cursor rules, plus the `<!-- toloka:begin -->` … `<!-- toloka:end -->` block in `AGENTS.md`, which is replaced by the `<toloka>` block in place. Files without that marker, other skills and rules, and installed skills under `.agents/skills/` are left untouched. An `AGENTS.md` whose current or legacy block is unterminated, reversed, or duplicated is refused with the file's full path before anything, including `toloka.json`, is written.
 
-On success it prints `Initialized agent entry points for @toloka-platform/sdk <version> in <root>:` followed by the file list, or `Agent entry points are up to date` when nothing changed. It warns on stderr when the SDK is not listed in the project dependencies. Every other `toloka` command compares the recorded skill digest with the installed SDK and warns on stderr when the generated files are stale; that warning never blocks the command.
+On success it prints `Initialized agent entry points for @toloka-platform/sdk <version> in <root>:` followed by the file list and one `removed <path>` line per legacy entry point, or `Agent entry points are up to date` when nothing changed. It warns on stderr when the SDK is not listed in the project dependencies. Every other project command warns on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the installed SDK; that warning never blocks the command. `support` commands skip the check because they never read the checkout.
 
 ## import
 
@@ -202,6 +221,38 @@ toloka dataset upload <name> <file>
 
 `dataset upload` appends JSONL rows. Field schemas are immutable after the first upload: you can add columns, never alter or remove one. See [datasets](./datasets.md).
 
+## report
+
+Preview and submit one Markdown issue report through the CLI's existing PostHog telemetry client. The command is project-independent: it does not read `toloka.json`, walk up to find a project root, require credentials, or call the Toloka API.
+
+```sh
+toloka report <markdownPath> [--authored-by human|agent] [--confirm]
+```
+
+The report path must name a non-empty regular UTF-8 file no larger than 256 KiB. The CLI refuses symbolic-link files and paths that traverse a symbolic-link directory under the selected source root. It prints the complete report, declared authorship, and platform origin before submission. Control and bidirectional formatting characters are escaped in the preview but preserved in the submitted report text.
+
+In a terminal the command asks `Send this report to Toloka? [y/N]`; outside a terminal it refuses unless `--confirm` is passed. `--authored-by` defaults to `human`. Add `--confirm` only after reviewing the exact preview.
+
+One `sdk_cli_issue_report_submitted` event carries `report_id`, the complete `report_text`, its UTF-8 `report_length_bytes`, `authored_by`, and `platform`, plus the standard pseudonymous CLI telemetry context. The command never reads or sends an API key. It flushes PostHog before printing `Submitted issue report: <id>`; a delivery failure exits non-zero and prints no success ID. When CLI telemetry is disabled, issue reporting is unavailable rather than bypassing that preference.
+
+## skill
+
+Discover bundled agent skills and install them into the project. The Skill Catalog ships inside the SDK package, so these actions are local and deterministic: they need no credentials, make no network requests, and change with the package version only.
+
+```sh
+toloka skill list [--json]
+toloka skill search <query> [--json]
+toloka skill install <skillId> [--force]
+```
+
+`list` prints every skill in the catalog with its installation status: `not-installed` when `.agents/skills/<skillId>` is absent, `current` when the installed files match the catalog digest, and `stale` when they differ. Each skill line (`id`, status, name) is followed by one indented description line. `--json` prints the Skill Descriptors (`id`, `name`, `description`, `tags`, `version`, `digest`, `files`) plus `status` and never includes file contents.
+
+`search` matches `<query>` case-insensitively against each skill's id, name, description, and tags and prints the matches in the same format. When nothing matches it says so (or prints `[]` with `--json`), exits 0, and installs nothing.
+
+`install` copies the complete skill — its `SKILL.md` entry point and every reference — from the package into `.agents/skills/<skillId>/` under the project root and prints the destination. Every path is confined to that directory and the command refuses to write through symbolic links. An existing `.agents/skills/<skillId>` is refused unless `--force` is passed. With `--force` the new copy is written to a temporary sibling directory and verified against the catalog digest, the existing directory is renamed to a backup, the verified copy is moved into place, and the backup is removed; a failed swap restores the backup, so the directory never holds a mixed version. A malformed catalog, an unsafe path, or a digest mismatch fails before any existing file changes.
+
+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.
+
 ## Exit codes
 
 `toloka pipeline run --wait` maps the run outcome to the process exit code.

package/docs/getting-started.md

@@ -44,7 +44,7 @@ CI does not need `login`. Set `POTATO_API_KEY` and the stored file is ignored. S
 
 ## Start with an agent
 
-Initialize the current directory and install the bundled agent skills. No platform project needs to be selected yet.
+Initialize the current directory and install the Agent Bootstrap. No platform project needs to be selected yet.
 
 ```sh
 toloka init
@@ -54,7 +54,7 @@ Open your coding agent in this directory and describe the project you want, for
 
 > Create a Toloka project that collects captions for images. Show me the plan before applying it.
 
-The skill guides the agent through creating and selecting the platform project, authoring the TypeScript source, validating it, showing the plan, and applying the approved changes. `toloka.json` is created when the project is selected.
+The bootstrap directs the agent to `toloka --help` and to search and install the matching bundled skill; the `toloka-build` skill then guides the agent through creating and selecting the platform project, authoring the TypeScript source, validating it, showing the plan, and applying the approved changes. `toloka.json` is created when the project is selected.
 
 ## Manual project setup
 

package/docs/limitations.md

@@ -2,7 +2,7 @@
 
 What this Preview SDK does not do yet, stated plainly so you can decide what to depend on.
 
-`@toloka-platform/sdk` is `0.1.0-preview.4`. This is a Preview: the authoring API, the CLI surface, and the generated source layout can change without a major version bump. Pin an exact version. Do not depend on this in production yet.
+`@toloka-platform/sdk` is `0.1.0-preview.5`. This is a Preview: the authoring API, the CLI surface, and the generated source layout can change without a major version bump. Pin an exact version. Do not depend on this in production yet.
 
 ## The SDK does not certify deployability
 

package/openapi/gen/api.ts

@@ -54,6 +54,7 @@ import type {
   ProjectSecret,
   ProjectSecretName,
   ReplacePipelineGraphBody,
+  RunCost,
   RunId,
   RunItem,
   RunItemId,
@@ -707,6 +708,27 @@ export const getPipelineRun = async (runId: RunId, options?: RequestInit): Promi
 
 
 
+export const getGetPipelineRunCostUrl = (runId: RunId,) => {
+
+
+  
+
+  return `/api/v2-beta/runs/${runId}/cost`
+}
+
+export const getPipelineRunCost = async (runId: RunId, options?: RequestInit): Promise<RunCost> => {
+  
+  return potatoFetch<RunCost>(getGetPipelineRunCostUrl(runId),
+  {      
+    ...options,
+    method: 'GET'
+    
+    
+  }
+);}
+
+
+
 export const getCancelPipelineRunUrl = (runId: RunId,) => {
 
 

package/openapi/gen/models/createDatasetBody.ts

@@ -1,4 +1,6 @@
+import type { CreateDatasetBodyProfile } from './createDatasetBodyProfile';
 
 export type CreateDatasetBody = {
   name?: string;
+  profile?: CreateDatasetBodyProfile;
 };

package/openapi/gen/models/createDatasetBodyProfile.ts

@@ -0,0 +1,2 @@
+
+export type CreateDatasetBodyProfile = 'chat-sft' | 'instruction';

package/openapi/gen/models/createDatasetUploadBodyFormat.ts

@@ -1,2 +1,2 @@
 
-export type CreateDatasetUploadBodyFormat = 'json' | 'csv';
+export type CreateDatasetUploadBodyFormat = 'json' | 'csv' | 'jsonl';

package/openapi/gen/models/dataset.ts

@@ -1,10 +1,12 @@
 import type { DatasetId } from './datasetId';
 import type { ProjectId } from './projectId';
+import type { DatasetProfile } from './datasetProfile';
 
 export interface Dataset {
   id: DatasetId;
   projectId: ProjectId;
   name: string;
   hidden: boolean;
+  profile: DatasetProfile;
   createdAt: string;
 }

package/openapi/gen/models/datasetProfile.ts

@@ -0,0 +1,3 @@
+import type { DatasetProfileStamp } from './datasetProfileStamp';
+
+export type DatasetProfile = DatasetProfileStamp | null;

package/openapi/gen/models/datasetProfileStamp.ts

@@ -0,0 +1,6 @@
+import type { DatasetProfileStampName } from './datasetProfileStampName';
+
+export interface DatasetProfileStamp {
+  name: DatasetProfileStampName;
+  version: number;
+}

package/openapi/gen/models/datasetProfileStampName.ts

@@ -0,0 +1,2 @@
+
+export type DatasetProfileStampName = 'chat-sft' | 'instruction';

package/openapi/gen/models/index.ts

@@ -68,6 +68,7 @@ export * from './codeNodeSettingsFieldProxiesInputItem';
 export * from './codeNodeSettingsFieldProxiesOutputItem';
 export * from './copyPipelineBody';
 export * from './createDatasetBody';
+export * from './createDatasetBodyProfile';
 export * from './createDatasetExportBody';
 export * from './createDatasetField200';
 export * from './createDatasetFieldBody';
@@ -111,6 +112,9 @@ export * from './datasetItem';
 export * from './datasetItemCurrentSubmissionId';
 export * from './datasetItemDuplicateOfSubmissionId';
 export * from './datasetItemId';
+export * from './datasetProfile';
+export * from './datasetProfileStamp';
+export * from './datasetProfileStampName';
 export * from './estimatePipelineCostBody';
 export * from './estimatePipelineCostBodyItemFilter';
 export * from './estimatePipelineCostBodyItemFilterFieldSourcesItem';
@@ -691,6 +695,7 @@ export * from './rootNodeSettingsItemFilterFieldValuesItemSourcesItemOneOfTwo';
 export * from './rootNodeSettingsItemFilterFieldValuesItemValue';
 export * from './rootNodeSettingsStartedFieldProxies';
 export * from './rootNodeSettingsStartedFieldProxiesOutputItem';
+export * from './runCost';
 export * from './runId';
 export * from './runItem';
 export * from './runItemId';

package/openapi/gen/models/runCost.ts

@@ -0,0 +1,7 @@
+import type { RunId } from './runId';
+
+export interface RunCost {
+  runId: RunId;
+  computedAt: string;
+  total: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toloka-platform/sdk",
-  "version": "0.1.0-preview.4",
+  "version": "0.1.0-preview.5",
   "private": false,
   "description": "Preview. Build, inspect, and operate Toloka pipeline projects as TypeScript source. The public API may change.",
   "license": "Apache-2.0",
@@ -32,6 +32,7 @@
     "build": "bun ./scripts/build-cli.ts ./dist/cli",
     "generate": "orval --config ./openapi/orval.config.js",
     "prepack": "bun run build",
+    "sync-skill-catalog": "bun ./scripts/sync-skill-catalog.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },

package/skills/catalog.json

@@ -0,0 +1,22 @@
+{
+  "skills": [
+    {
+      "id": "toloka-build",
+      "name": "Build Toloka pipelines as code",
+      "description": "Build, inspect, and change Toloka platform pipeline projects as TypeScript source with @toloka-platform/sdk and toloka. Use when the user wants to create, adopt, inspect, plan, or apply a pipeline project as code.",
+      "tags": ["pipelines", "authoring", "sdk"],
+      "version": "0.1.0-preview.5",
+      "digest": "135d0b6ff6aa7bf26782bc26e6adbe7ee70c9db1565722ee356618211543d0bc",
+      "files": ["SKILL.md", "references/node-semantics.md", "references/workflow-and-cli.md"]
+    },
+    {
+      "id": "toloka-report-issue",
+      "name": "Report a Toloka problem",
+      "description": "Report a problem with the Toloka platform, CLI, or SDK as a redacted Markdown issue report sent through the toloka CLI only after explicit approval. Use when the user hits unexpected behavior, an error, or a bug and wants Toloka engineers to investigate.",
+      "tags": ["support", "issue", "bug", "report"],
+      "version": "0.1.0-preview.5",
+      "digest": "9a673337ad1cbbcec7c2fadb2d49d38e923c797d049818fdaa15ff30ffd153f3",
+      "files": ["SKILL.md", "references/report-template.md"]
+    }
+  ]
+}

package/skills/{SKILL.md → toloka-build/SKILL.md}

@@ -46,7 +46,7 @@ Import authoring helpers from `@toloka-platform/sdk`.
 
 Let constructors mint IDs for new declarations. Preserve `id` options generated by `toloka import`, but never invent or hand-edit raw `fp_…`, `ds.…`, `pl.…`, or `pp.…` values in authored settings. Never add a `layout` block: layout is not authored, existing layout is preserved, and the server supplies defaults.
 
-Read [node semantics](references/node-semantics.md) before selecting or configuring a node. Use the published [face image collection example](../examples/face-image-collection/) as a concrete authoring pattern.
+Read [node semantics](references/node-semantics.md) before selecting or configuring a node. Use `node_modules/@toloka-platform/sdk/examples/face-image-collection/` as a concrete authoring pattern.
 
 ## Get human-work settings right the first time
 

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

@@ -33,9 +33,9 @@ bun add --dev @toloka-platform/sdk
 toloka init
 ```
 
-`init` does not require a selected project. It checks that `@toloka-platform/sdk` is declared in `dependencies` or `devDependencies`, then writes a Claude skill for `.claude/`, a Cursor rule when `.cursor/rules/` exists, and a marked block in an existing `AGENTS.md`; with no agent configuration, it creates the Claude skill and `AGENTS.md`. If a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing.
+`init` does not require a selected project. It checks that `@toloka-platform/sdk` is declared in `dependencies` or `devDependencies`, then maintains one `<toloka>` Agent Bootstrap block in `AGENTS.md` and writes minimal pointers to it: a Claude skill at `.claude/skills/toloka-bootstrap/SKILL.md` when `.claude/` exists (or when no agent configuration exists at all) and an always-applied Cursor rule at `.cursor/rules/toloka-bootstrap.mdc` when `.cursor/rules/` exists. If a project is already selected through `--project-id`, `TOLOKA_PROJECT_ID` / `POTATO_PROJECT_ID`, `toloka.json`, or the machine registry, it also writes `toloka.json` when missing.
 
-The generated entry points contain the core read, edit, validate, plan, and apply loop and point back to the fuller references in this package. Every `toloka` command except `init` compares the recorded skill-content digest with the installed SDK and warns on stderr when they differ. The warning never blocks the command; re-run `toloka init` to refresh the pointers.
+The bootstrap is small: it tells an agent to run `toloka --help`, search the bundled Skill Catalog with `toloka skill search <query>`, install the match with `toloka skill install <skill-id>`, and read `.agents/skills/<skill-id>/SKILL.md`. This skill is that installed copy. Commands warn on stderr when a generated legacy entry point is still present or the recorded bootstrap version differs from the installed SDK. Help, `init`, `report`, `project url`, and version invocations skip this checkout-dependent warning. The warning never blocks a command; re-run `toloka init` to refresh the bootstrap and its pointers.
 
 ## Store credentials once
 
@@ -71,13 +71,16 @@ require `toloka login` first because they read and write the credentials file. W
 project ID in this order: `--project-id`, `TOLOKA_PROJECT_ID`, `POTATO_PROJECT_ID`, `toloka.json`,
 then the machine registry `current`.
 
-Anonymous command telemetry is on by default (`sdk_cli_command_completed` / `sdk_cli_command_failed`). Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable it. CI is off unless `TOLOKA_TELEMETRY=1`.
+Anonymous command telemetry is on by default (`sdk_cli_command_completed` / `sdk_cli_command_failed`). `toloka report` uses the same PostHog client to send explicitly approved Markdown in `sdk_cli_issue_report_submitted`. Set `TOLOKA_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable both; CI is off unless `TOLOKA_TELEMETRY=1`.
 
 All commands accept `--source-root <directory>`. Prefer running from the source root so paths and diffs stay obvious. `init` does not walk up: it binds the working directory or `--source-root` only.
 
 The real command surface is:
 
 ```text
+toloka version
+toloka -v
+toloka --version
 toloka login
 toloka logout
 toloka auth-status
@@ -85,6 +88,7 @@ toloka project list
 toloka project add [alias] [projectId]
 toloka project switch <alias>
 toloka project current
+toloka project url
 toloka project remove <alias>
 toloka project create [alias] [--name <name>] [--team-id <id>]
 toloka init
@@ -105,10 +109,16 @@ toloka pipeline runs [name] [--limit <n>]
 toloka pipeline cost [name] [--item-limit <n>]
 toloka pipeline results <runId> [--limit <n>] [--failed]
 toloka pipeline cancel <runId>
+toloka skill list [--json]
+toloka skill search <query> [--json]
+toloka skill install <skill-id> [--force]
+toloka report <markdown> [--authored-by human|agent] [--confirm]
 ```
 
 Select the platform project with `toloka project add` or `toloka project create` before `import`, `plan`, or `apply`. `init` may run first, and `import` uses the selected project when the id is omitted.
 
+`toloka project url` prints only the selected project's platform UI URL. Use it when the user needs a working link to inspect the live project.
+
 `toloka pipeline cost [name] [--item-limit <n>]` forecasts what a run of a live pipeline would bill. It does not start a run and does not change the graph. Name the live pipeline or id; a TTY may pick among several. The typed client equivalent is `client.pipelines.estimateCost({ pipelineId, itemLimit? })`.
 
 ## Adopt an existing live project
@@ -254,4 +264,4 @@ Read the returned path and reason. Check connection endpoints, duplicate or unkn
 
 ## Use the shipped example
 
-Read [the face image collection pipeline](../../examples/face-image-collection/pipeline.ts), its `fields.ts`, and its `nodes/` modules for a real composition of `field`, `root`, `generation`, `code`, `connect`, and `definePipeline`. Copy its source organization, not its task-specific settings.
+Read `node_modules/@toloka-platform/sdk/examples/face-image-collection/pipeline.ts`, its `fields.ts`, and its `nodes/` modules for a real composition of `field`, `root`, `generation`, `code`, `connect`, and `definePipeline`. Copy its source organization, not its task-specific settings.

package/skills/toloka-report-issue/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: toloka-report-issue
+description: Report a problem with the Toloka platform, CLI, or SDK as a redacted Markdown issue report sent through the toloka CLI only after explicit approval. Use when the user hits unexpected behavior, an error, or a bug and wants Toloka engineers to investigate.
+---
+
+# Report a Toloka problem
+
+Use this skill when Toloka platform, CLI, or SDK behavior blocks the user's work and they want Toloka engineers to investigate. The result is one Markdown issue report sent through the `toloka` CLI. Nothing leaves the machine until the user has reviewed the complete report and approved it.
+
+## Workflow
+
+1. Collect verified facts: what the user ran, what they expected, what happened, and any relevant project, pipeline, dataset, run, thread, or request IDs. Ask for missing reproduction steps or reproduce the failure with real commands. Never invent a timeline, command output, or identifier.
+2. Copy [the template](references/report-template.md), preserve its section order, and replace the example with the user's evidence. Write `None` for sections that do not apply. The final UTF-8 Markdown file must not exceed 256 KiB.
+3. Redact before previewing. Include only evidence the user selected. Replace every API key, token, password, cookie, connection string, or personal value with a marker such as `[REDACTED:api-key]`, and list each replacement under Redactions without the original value. Never read environment variables, credential files, shell history, or logs the user did not name.
+4. Show the user the exact complete Markdown file and ask whether to send it. If they decline or request changes, do not submit; revise the file and ask again.
+5. Only after approval, run `toloka report <report.md> --authored-by agent --confirm`. The command previews the same Markdown, submits it as one PostHog event, flushes delivery, and prints `Submitted issue report: <id>` only after PostHog accepts the flush.
+6. Return the printed report ID to the user. If submission fails, keep the Markdown file, report the exact error, and do not claim success or retry without approval.
+
+## Boundaries
+
+- Submit only the Markdown file. The command has no attachment or structured-reference flags; put relevant IDs and text evidence in the report itself.
+- The event contains the complete Markdown, report ID, UTF-8 byte length, declared authorship, platform origin, and the standard pseudonymous CLI telemetry context. It never reads or sends the API key.
+- `--authored-by agent` records who prepared the report. It does not authenticate or grant access.
+- Issue reporting is unavailable when CLI telemetry is disabled. Do not bypass that setting.
+- Use the CLI, not the SDK or raw PostHog API. The user-visible preview and explicit approval are the consent boundary.

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

@@ -0,0 +1,34 @@
+# Issue Report: `toloka apply` returns HTTP 500 for the cat labeling project
+
+## Summary
+
+`toloka apply` fails with HTTP 500 after `toloka validate` passed, so the edited pipeline never reaches the platform.
+
+## Steps to reproduce
+
+1. Change the labeler instruction in `pipelines/cat-labeling/nodes/annotate-cats/node.ts`.
+2. Run `toloka validate`; it reports no issues.
+3. Run `toloka apply`.
+
+## Expected behavior
+
+`toloka apply` writes the new graph version and prints the changed node.
+
+## Actual behavior
+
+The CLI exits 1 with `Potato API request failed with status 500`. The same command failed three times between 09:12 and 09:20 UTC; `toloka plan` still shows the pending change.
+
+## Relevant IDs
+
+- Project: pp.0192f3a4-5b6c-7d8e-9f01-23456789abcd
+- Pipeline: pl.0192f3a4-5b6c-7d8e-9f01-23456789abce
+- Request: None supplied
+
+## Environment
+
+- toloka CLI 0.1.0-preview.5 (`toloka --version`), Bun 1.4.0, macOS 15
+- Platform: https://platform.toloka.ai
+
+## Redactions
+
+- The API key in the user-selected command output was replaced with `[REDACTED:api-key]`.

package/src/cli/analytics.ts

@@ -1,3 +1,4 @@
+import { assert } from "es-toolkit";
 import { randomUUID } from "node:crypto";
 import { chmod, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -28,13 +29,22 @@ export type CliAnalyticsCapture = {
   readonly error?: unknown;
 };
 
+export type IssueReportSubmission = {
+  readonly reportId: string;
+  readonly reportText: string;
+  readonly authoredBy: "human" | "agent";
+  readonly platform: string;
+};
+
 export type CliAnalytics = {
   readonly shouldIdentify: boolean;
+  readonly issueReportingEnabled: boolean;
   readonly identifyCurrentUser: (user: {
     readonly id: string;
     readonly email: string | null;
   }) => void;
   readonly captureCommand: (event: CliAnalyticsCapture) => void;
+  readonly submitIssueReport: (report: IssueReportSubmission) => Promise<void>;
   readonly shutdown: () => Promise<void>;
 };
 
@@ -46,6 +56,8 @@ export type PosthogLike = {
     disableGeoip: boolean;
   }) => void;
   alias: (event: { distinctId: string; alias: string }) => void;
+  flush: () => Promise<void>;
+  on?: (event: "error", listener: (error: Error) => void) => void;
   shutdown: (shutdownTimeoutMs?: number) => Promise<void>;
 };
 
@@ -86,6 +98,7 @@ const COMMAND_GROUPS: Readonly<Record<string, Readonly<Record<string, true>>>> =
   },
   dataset: { list: true, fields: true, load: true, upload: true },
   secret: { set: true },
+  skill: { list: true, search: true, install: true },
 };
 
 const ROOT_COMMANDS: Readonly<Record<string, true>> = {
@@ -99,6 +112,8 @@ const ROOT_COMMANDS: Readonly<Record<string, true>> = {
   plan: true,
   status: true,
   validate: true,
+  report: true,
+  version: true,
   whoami: true,
 };
 
@@ -116,6 +131,7 @@ const nameFromTokens = (tokens: readonly string[]): string => {
 };
 
 export function commandNameFromArgv(argv: readonly string[]): string {
+  if (argv.includes("-v") || argv.includes("--version")) return "version";
   const tokens: string[] = [];
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
@@ -161,8 +177,12 @@ const readAnonymousId = async (environment: CliEnvironment): Promise<string> =>
 
 const noopAnalytics = (): CliAnalytics => ({
   shouldIdentify: false,
+  issueReportingEnabled: false,
   identifyCurrentUser() {},
   captureCommand() {},
+  async submitIssueReport() {
+    assert(false, "Issue reporting is disabled. Re-run with TOLOKA_TELEMETRY=1.");
+  },
   async shutdown() {},
 });
 
@@ -177,6 +197,11 @@ export function createCliAnalytics(options: {
   let client = options.client;
   let distinctId = options.distinctId;
   let identifiedUserId: string | undefined;
+  const deliveryErrors: Error[] = [];
+  const captureDeliveryError = (error: Error) => {
+    deliveryErrors.push(error);
+  };
+  client?.on?.("error", captureDeliveryError);
 
   const ensure = async () => {
     if (client !== undefined && distinctId !== undefined) return;
@@ -186,7 +211,7 @@ export function createCliAnalytics(options: {
         flushAt: 1,
         flushInterval: 0,
       });
-      created.on("error", () => {});
+      created.on("error", captureDeliveryError);
       client = created;
     }
     distinctId ??= await readAnonymousId(environment);
@@ -202,6 +227,7 @@ export function createCliAnalytics(options: {
   let queue: Promise<void> = ensure().catch(() => {});
 
   return {
+    issueReportingEnabled: true,
     shouldIdentify: true,
     identifyCurrentUser(user) {
       queue = queue
@@ -252,6 +278,32 @@ export function createCliAnalytics(options: {
         })
         .catch(() => {});
     },
+    submitIssueReport(report) {
+      const submission = queue.then(async () => {
+        assert(client && distinctId, "PostHog issue reporting could not be initialized.");
+        deliveryErrors.length = 0;
+        client.capture({
+          distinctId,
+          event: "sdk_cli_issue_report_submitted",
+          disableGeoip: true,
+          properties: {
+            ...sharedProperties(),
+            report_id: report.reportId,
+            report_text: report.reportText,
+            report_length_bytes: new TextEncoder().encode(report.reportText).length,
+            authored_by: report.authoredBy,
+            platform: report.platform,
+            $process_person_profile: false,
+          },
+        });
+        await client.flush();
+        const reportError = deliveryErrors[0];
+        deliveryErrors.length = 0;
+        if (reportError !== undefined) throw reportError;
+      });
+      queue = submission.catch(() => {});
+      return submission;
+    },
     async shutdown() {
       try {
         await queue;