@toloka-platform/sdk 0.1.0-preview.3

package/docs/cli.md

@@ -0,0 +1,245 @@
+# CLI reference
+
+The `toloka` CLI reads TypeScript source as the desired state, compares it with the live platform state, and reconciles the two.
+
+This CLI is Preview software. Commands, flags, and output can change without a major version bump.
+
+`toloka` requires Bun. The binary declares a `bun` shebang and the package ships TypeScript source with no
+build step, so it does not run under plain Node.
+
+## 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           | `POTATO_API_KEY` environment variable      |
+| 3 (lowest)  | credentials file written by `toloka login` |
+
+| Precedence  | Base URL source                         |
+| ----------- | --------------------------------------- |
+| 1 (highest) | `--base-url` flag                       |
+| 2           | `POTATO_BASE_URL` environment variable  |
+| 3           | base URL stored in the credentials file |
+| 4 (default) | `https://platform.toloka.ai`            |
+
+| Precedence  | Project id source                             |
+| ----------- | --------------------------------------------- |
+| 1 (highest) | `--project-id` flag                           |
+| 2           | `TOLOKA_PROJECT_ID`, then `POTATO_PROJECT_ID` |
+| 3           | `projectId` in `toloka.json`                  |
+| 4 (lowest)  | `current` alias in the credentials file       |
+
+`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`.
+
+The root program accepts these flags before any command:
+
+| Flag                        | Meaning                                                          |
+| --------------------------- | ---------------------------------------------------------------- |
+| `--source-root <directory>` | Project root; discovered from the working directory when omitted |
+| `--api-key <key>`           | API key for this command only                                    |
+| `--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.
+
+## project
+
+Register and select the platform project later commands use.
+
+```sh
+toloka project list
+toloka project add [alias] [projectId]
+toloka project switch <alias>
+toloka project current
+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`.
+
+## login
+
+Stores an API key for this machine after verifying it.
+
+```sh
+toloka login
+```
+
+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>.`
+
+## logout
+
+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>.`
+
+## auth-status
+
+Shows which platform and key 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, and `Reachable: N project(s) visible.` The project line is printed even when no key is in effect or the platform is not reachable. It exits `1` when no key is in effect or the platform is not reachable.
+
+## init
+
+Initializes the current project directory and installs agent 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.
+
+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.
+
+## import
+
+Generates TypeScript source from a live project.
+
+```sh
+toloka import [projectId] [-f]
+```
+
+When `projectId` is omitted, the selected project is imported. If `pipelines/` already exists, the command exits with `Folder already exists: <path>. Pass --force to replace it.` Pass `-f` or `--force` to replace that directory. On success it prints `Imported project <projectId> with N pipelines and M datasets into <root>.`
+
+## plan
+
+Shows what `apply` would change.
+
+```sh
+toloka plan
+```
+
+On success it prints `No changes.` when the platform matches source, otherwise `Plan: N changes` followed by one line per change. The plan also lists missing project secrets and dataset field schema conflicts so you can resolve them before applying.
+
+## validate
+
+Runs platform spec validation for each bound pipeline and reports the latest matching check jobs. Does not write the graph.
+
+```sh
+toloka validate
+```
+
+On success it prints one line per pipeline: `valid`, `invalid` with issue details, or `skipped` when the pipeline is not on the platform yet. Exits `1` when any submitted graph is invalid.
+
+## apply
+
+Makes the platform match source.
+
+```sh
+toloka apply
+```
+
+A preflight pass refuses before any write when a pipeline or dataset is removed from source, a project secret is missing, or a dataset field schema conflicts. On success it prints `No changes.` or `Applied N writes to project <projectId>.`
+
+## secret set
+
+Sets a secret value without writing it to disk.
+
+```sh
+toloka secret set <name> [--from-env <variable>]
+```
+
+`<name>` is a secret name referenced by a code node. The value is read from stdin, or from the environment variable named by `--from-env`. A project ID is required. On success it prints `Set secret <name>.` On failure it prints `Failed to set secret <name>.` on stderr and exits `1`.
+
+## status
+
+Reports project health: live pipeline, dataset, and secret counts, plus whether source has pending apply-plan changes.
+
+```sh
+toloka status
+```
+
+On success it prints the project id and name, team id, live counts, and either `Source has no pending changes.` or `Source has N pending change(s).` That last line means the same thing as `toloka plan`, not that every live resource is declared in source. The command takes no pipeline argument.
+
+## pipeline
+
+Operate on a live pipeline in the selected project. Name or id is required unless a TTY picker can choose among several live pipelines. There is no implicit "the only pipeline."
+
+```sh
+toloka pipeline list
+toloka pipeline run [name] [--wait] [--timeout <ms>]
+toloka pipeline status [name]
+toloka pipeline runs [name] [--limit <n>]
+toloka pipeline cost [name] [--item-limit <n>]
+toloka pipeline cancel <runId>
+toloka pipeline results <runId> [--limit <n>] [--failed]
+```
+
+`pipeline list` prints live `name`, id, and a bound source directory when one exists. Zero live pipelines prints `This project has no pipelines.`
+
+`pipeline run` without `--wait` prints `Started run <id> is <status> for <name>.` and a follow-up that uses the pipeline id. Exit code `0` means only that the run was accepted. With `--wait`, it prints `Run <id> succeeded.` or `Run <id> failed.` and sets the exit code accordingly; see [Exit codes](#exit-codes).
+
+`pipeline status` reports the latest run of that pipeline. `pipeline runs` lists recent runs (default 10). `pipeline cost` forecasts what a run would bill. `pipeline cancel` and `pipeline results` take a run id.
+
+## dataset
+
+Catalog and row commands for datasets in the selected project. Name or id is accepted; duplicate names must be addressed by id.
+
+```sh
+toloka dataset list
+toloka dataset fields <name>
+toloka dataset load <name> --out <file> [--limit <n>] [--timeout <ms>]
+toloka dataset upload <name> <file>
+```
+
+`dataset list` prints live `name` and id. It does not page items.
+
+`dataset fields` prints inferred `field()` TypeScript, or `Dataset <name> has no inferred fields yet.`
+
+`dataset load` starts a platform export, waits for it (default 60s; pass `--timeout`), downloads the JSON array, and writes JSONL to `--out`. `--limit` slices after download; it still waits for the full export. On timeout the message names the export id. Failed downloads and invalid payloads leave `--out` untouched.
+
+`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).
+
+## Exit codes
+
+`toloka pipeline run --wait` maps the run outcome to the process exit code.
+
+| Code | Meaning                                       |
+| ---- | --------------------------------------------- |
+| 0    | Run succeeded (terminal state)                |
+| 1    | Run failed (terminal state)                   |
+| 2    | Run still running when the wait window closed |
+
+Without `--wait`, exit code `0` means only that the run was accepted. Every other failure exits non-zero with a message on stderr: missing `toloka.json`, a rejected login, an unauthenticated `auth-status`, or a failed `secret set`.
+
+## The reconcile loop
+
+Treat the TypeScript source as authoritative. The canonical sequence is: typecheck, validate against the platform, plan, apply, then plan again to confirm convergence.
+
+```sh
+# 1. Typecheck the project
+bun run typecheck
+
+# 2. Validate each bound pipeline against the platform
+toloka validate
+
+# 3. Preview what apply would change
+toloka plan
+
+# 4. Apply only when the plan matches the intent
+toloka apply
+
+# 5. Confirm the platform matches source
+toloka plan  # expect: No changes.
+```
+
+`toloka validate` posts each authored graph to `POST /pipelines/:pipelineId/graph/validate`. It runs platform spec validation and reports the latest matching check jobs. It does not write the graph. A pipeline that is not on the platform yet is skipped until `toloka apply` creates it. Resolve every unexpected plan change, missing secret, and immutable-field conflict before applying.
+
+## Further reading
+
+- [Getting started](./getting-started.md)
+- [Authoring pipelines](./authoring.md)
+- [Datasets](./datasets.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/datasets.md

@@ -0,0 +1,163 @@
+# Datasets
+
+How data enters a pipeline project, which parts of a dataset the platform lets you change, and what the preflight checks catch before anything is written.
+
+## The model
+
+A dataset is rows (items) and typed columns (fields). Each field carries a name and a JSON Schema. Each row is an item.
+
+A pipeline binds exactly one source dataset. Items flow in through the fields the pipeline reads, and every output field is written back to the same dataset as a column. The dataset is both the input and the result.
+
+## Declare columns in source
+
+The dataset is named in `definePipeline`, and its columns are the fields the pipeline reads and writes:
+
+```ts
+// pipelines/face-image-collection/pipeline.ts
+import { connect, definePipeline } from "@toloka-platform/sdk";
+import { imageUrl, draftFaces, faces } from "./fields";
+
+export const pipeline = definePipeline({
+  dataset: "face-images",
+  fields: [imageUrl, draftFaces, faces],
+  nodes: [collection, annotateFaces, orderFaces],
+  connections: [
+    connect(collection.started, annotateFaces.input),
+    connect(annotateFaces.output, orderFaces.input),
+    connect(orderFaces.output, collection.completed),
+  ],
+});
+```
+
+Each field is declared with a name and a JSON Schema by calling `field`:
+
+```ts
+// pipelines/face-image-collection/fields.ts
+import { field } from "@toloka-platform/sdk";
+
+export const imageUrl = field("image_url", { type: "string", format: "uri" });
+export const draftFaces = field("draft_faces", {
+  type: "array",
+  items: { type: "object" /* ... */ },
+});
+export const faces = field("faces", { type: "array", items: { type: "object" /* ... */ } });
+```
+
+The `dataset` string and `fields` array are the only dataset-related declarations in source. There is no dataset ID, no dataset schema file, and no items file. The dataset name resolves to a platform ID at apply time, and that binding is recorded in `toloka.json`.
+
+`toloka plan` compares the declaration against live state and reports what is missing:
+
+```
+Plan: 4 changes
++ Dataset added: face-images
++ Dataset field added: face-images.image_url
++ Dataset field added: face-images.draft_faces
++ Dataset field added: face-images.faces
+```
+
+`toloka apply` creates the dataset and each missing column. It never alters an existing column and never deletes one.
+
+## Immutability
+
+**A dataset field can be added. It can never be altered or removed after creation.**
+
+The platform API exposes exactly two field operations:
+
+| Method | Path                                       | Operation      |
+| ------ | ------------------------------------------ | -------------- |
+| `GET`  | `/api/v2-beta/datasets/{datasetId}/fields` | List fields    |
+| `POST` | `/api/v2-beta/datasets/{datasetId}/fields` | Create a field |
+
+There is no `PATCH` or `DELETE` for fields. The `POST` endpoint's description states the rule: "Create a field in a dataset. Field names and JSON schemas are immutable after creation."
+
+The OpenAPI document defines no `DELETE` for the dataset itself either, and no CLI command removes one.
+
+When source declares a schema that disagrees with a stored field, `plan` reports the conflict and `apply` refuses:
+
+```
+Dataset field schemas conflict with source: face-images.faces. Existing fields are never rewritten.
+```
+
+Two legitimate ways forward:
+
+1. **Declare a new column.** Pick a name the dataset does not have yet with the schema you want. The old column stays, holding the data it already holds.
+2. **Bind a new dataset.** Change the `dataset` string in `definePipeline`. `apply` creates the new dataset with exactly the declared columns.
+
+There is no flag to force an in-place change. The schema you declare on first apply is the one you live with.
+
+## Catalog vs rows
+
+`toloka dataset list` and `toloka dataset fields` talk to the catalog: names, ids, and inferred column schemas. They do not write a data file. Rows stay on the platform until you pull them.
+
+```sh
+toloka dataset list
+toloka dataset fields face-images
+toloka dataset load face-images --out data/face_images.jsonl
+toloka dataset load face-images --limit 100 --out data/face_images.sample.jsonl
+toloka dataset upload face-images data/face_images.jsonl
+```
+
+`load` starts a platform export, waits (default 60s), downloads a JSON array, and writes JSONL to `--out`. `--limit` slices after that download. `--timeout` raises the wait. Failed downloads leave `--out` untouched.
+
+## Load rows
+
+Rows are data, not source. They never belong in pipeline source or `toloka.json`.
+
+```sh
+toloka dataset upload face-images data/face_images.jsonl
+```
+
+The command takes two positional arguments and has no flags:
+
+| Argument | Description                          |
+| -------- | ------------------------------------ |
+| `<name>` | Dataset name or id                   |
+| `<file>` | JSONL file, one JSON object per line |
+
+Each line is a JSON object with keys matching column names:
+
+```json
+{"image_url": "https://example.com/cat-1.jpg"}
+{"image_url": "https://example.com/cat-2.jpg"}
+```
+
+Upload is additive: it appends items and never rewrites existing ones. If the dataset does not exist yet and a pipeline in source declares it, `dataset upload` creates the dataset with the declared columns automatically. If no pipeline declares the dataset, upload stops and asks you to bind a pipeline to it in source so its columns are known, or to upload to an existing dataset. Duplicate live names must be addressed by id.
+
+## Inspect columns
+
+```sh
+toloka dataset fields face-images
+```
+
+Prints TypeScript `field(...)` declarations inferred from the first successful upload. The output is ready to paste into a `fields.ts` file:
+
+```
+import { field } from '@toloka-platform/sdk';
+
+export const imageUrl = field(
+  'image_url',
+  { type: 'string', format: 'uri' }
+);
+
+export const faces = field(
+  'faces',
+  { type: 'array', items: { type: 'object' /* ... */ } }
+);
+```
+
+Inference runs once, after the first upload attaches rows to the dataset. When no upload has completed, the command prints "Dataset X has no inferred fields yet." Upload a representative file first.
+
+## What plan refuses
+
+`plan` is read-only and reports everything `apply` will not do. Two dataset-related refusals are safety properties, not obstacles:
+
+| Refusal message                                                                                       | Why it fires                                                                                                                       |
+| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `Refusing to delete datasets absent from source: <names>. Dataset items are never deleted.`           | A dataset tracked in `toloka.json` is named by no pipeline in source. Deleting data must never be a side effect of editing a file. |
+| `Dataset field schemas conflict with source: <dataset>.<field>. Existing fields are never rewritten.` | A required field exists with a different JSON Schema, and fields are immutable after creation.                                     |
+
+To fix a schema conflict, either declare a new column name or bind the pipeline to a new dataset (see [Immutability](#immutability)).
+
+## See also
+
+[CLI reference](./cli.md) · [Authoring pipelines](./authoring.md) · [Troubleshooting](./troubleshooting.md)

package/docs/getting-started.md

@@ -0,0 +1,148 @@
+# Getting started
+
+Install the SDK, sign in, and get a pipeline project reconciling from source in one sitting.
+
+## Install
+
+The package is not published to npm yet. Link it from a checkout of this repository:
+
+```sh
+cd packages/sdk && bun link
+cd /path/to/your/project && bun link @toloka-platform/sdk
+```
+
+Declare the dependency in `package.json` so `toloka init` recognizes it. Once the hosted installer is deployed, install the bytecode-cached CLI and add the SDK to the project:
+
+```sh
+curl -fsSL https://platform.toloka.ai/cli/install.sh | sh
+bun add @toloka-platform/sdk@preview
+```
+
+The installer writes `toloka` to `~/.local/bin` and uses an isolated Bun 1.4 runtime with precompiled bytecode. The project install makes `@toloka-platform/sdk` imports resolvable.
+
+## Sign in
+
+```sh
+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.
+
+```
+API key: ******************
+Authenticated against https://platform.toloka.ai: 12 project(s) visible.
+Saved credentials to /Users/you/.config/toloka/credentials.json.
+```
+
+Check what the CLI will use at any time:
+
+```sh
+toloka whoami
+```
+
+CI does not need `login`. Set `POTATO_API_KEY` and the stored file is ignored. See the precedence table in the [CLI reference](./cli.md).
+
+## Start with an agent
+
+Initialize the current directory and install the bundled agent skills. No platform project needs to be selected yet.
+
+```sh
+toloka init
+```
+
+Open your coding agent in this directory and describe the project you want, for example:
+
+> 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.
+
+## Manual project setup
+
+You are either adopting a project that already exists on the platform, or creating a new one. Adoption is the shorter manual path because it gives you correct source to read.
+
+### Adopt an existing project
+
+```sh
+mkdir my-project && cd my-project
+toloka project add cats pp.019ffa5f-29a7-74de-a76c-7ba5ceedf37f
+toloka init
+toloka import
+```
+
+`import` writes a `pipelines/` tree and a `toloka.json` that maps your source to live IDs. If `pipelines/` already exists, pass `--force` to replace it. Read the generated TypeScript: it is the same shape you will edit from now on.
+
+Prove the round trip before you change anything:
+
+```sh
+toloka plan
+```
+
+A freshly imported project prints `No changes.` If it prints anything else, stop and read it — the source and the platform disagree, and you want to know why before you edit.
+
+### Author from scratch
+
+```sh
+toloka project create cats --team-id <teamId>
+toloka init
+```
+
+Then create `pipelines/<name>/pipeline.ts` with a default export and run `plan` / `apply`. The [authoring guide](./authoring.md) covers the graph API; [examples](../examples/) are complete projects you can copy from.
+
+## The loop you will live in
+
+Every change follows the same steps. `validate`, `plan`, and `apply` talk to the platform.
+
+```sh
+bunx tsc --noEmit
+toloka validate
+toloka plan
+toloka apply
+toloka plan
+```
+
+The second `plan` is the part people skip. It is how you learn that apply actually converged instead of leaving a difference behind.
+
+`plan` output names the resource and the action:
+
+```
+Plan: 4 changes
++ Dataset added: cat-images
++ Dataset field added: cat-images.annotations
++ Pipeline added: pipelines/cat-labeling
+```
+
+## Load data
+
+Rows never live in pipeline source. Once `apply` has created the dataset, append JSONL:
+
+```sh
+toloka dataset upload cat-images ./data/cat_images.jsonl
+```
+
+Column schemas are immutable once created, which makes the order matter: declare the columns you want in source, apply, then upload rows that match. See [datasets](./datasets.md).
+
+## Secrets
+
+Put secret _names_ in node settings and keep values out of source and out of shell history:
+
+```sh
+toloka secret set OPENAI_API_KEY --from-env OPENAI_API_KEY
+```
+
+`plan` lists every secret name a node references but the project does not have, and `apply` refuses until they exist.
+
+## Run it
+
+```sh
+toloka pipeline run cat-labeling --wait --timeout 600000
+```
+
+Exit code `0` means the run reached a successful terminal state, `1` a failed one, and `2` that the timeout closed while the run was still going. Without `--wait`, `0` means only that the platform accepted the run. A queue with no one working it stays in progress indefinitely, so always bound the wait and report what you actually observed.
+
+## Next
+
+- [Authoring](./authoring.md) — the typed graph API
+- [Nodes](./nodes.md) — which node to reach for, and the pricing floors you must clear
+- [CLI](./cli.md) — every command and flag
+- [Troubleshooting](./troubleshooting.md) — the failures you will hit
+- [Limitations](./limitations.md) — Preview status and what this SDK does not do yet

package/docs/limitations.md

@@ -0,0 +1,55 @@
+# Limitations
+
+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.3`. 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
+
+`toloka validate` posts each bound graph to the platform and reports spec errors, warnings, and the latest matching check jobs. It does not write the graph.
+
+A successful validate, and a successful `apply`, are still not proof that the pipeline can be launched. Gates that live outside that report are invisible to the CLI:
+
+| gate                                              | where it is enforced | what the CLI tells you |
+| ------------------------------------------------- | -------------------- | ---------------------- |
+| Training course content, when Training is enabled | platform validation  | nothing                |
+| labeler UI validation receipt                     | platform validation  | nothing                |
+
+## Node checks are reported, not started
+
+`toloka validate` includes the latest matching check jobs for the submitted graph. The typed client can list, start, and poll checks, but there is no `toloka check` command that discovers check contracts, configures cases, starts each required lint, waits, and explains reports. Configure and start missing checks in the platform UI for now.
+
+## 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.
+
+## One checkout targets one project
+
+`toloka.json` records exactly one `projectId`. To drive a second project from the same source — a copy for another customer, or a staging instance beside production — use a separate checkout, or pass `--project-id` and keep the state files apart. Overwriting the recorded id silently repoints every later `plan` and `apply`.
+
+## Code assets are inline strings
+
+A `code` node carries its Python as an inline string in `code.code`. There is no helper for loading a sibling `.py` file, so long programs make the node file long.
+
+## Authentication is API keys only
+
+`toloka login` stores a single API key per machine. There is no browser-based sign-in, no key rotation command, and `logout` deletes the local file without revoking the key. Revoke keys in the platform console.
+
+## Open platform defects
+
+These are reproduced platform-side issues that affect the SDK path. They are not SDK bugs and cannot be fixed from this package.
+
+| defect                                                                                  | effect on you                                                                                           | workaround                                                        |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Re-uploading a filename already used in a dataset returns a bodyless `500`              | running the same `toloka dataset upload` twice fails                                                    | use a distinct filename per upload                                |
+| A failed upload leaves a pending upload row, and a pending upload counts as in progress | later uploads to that dataset return `409 Another upload is already in progress`, with no public cancel | load into a new dataset; ask for the pending upload to be cleared |
+| Finalizing a file upload can return a bodyless `500`                                    | `toloka dataset upload` cannot complete on an affected environment                                      | declare columns in source and load rows through a client call     |
+| Rows added through the items endpoint skip column inference                             | `toloka dataset fields` reports no columns for a dataset that holds rows                                | declare columns in source rather than inferring them              |
+| Starting a run intermittently returns a bodyless `500`                                  | `toloka pipeline run` fails with nothing to act on                                                      | check `toloka pipeline runs <name>` for a created run, then retry |
+
+## Not attempted yet
+
+- No `toloka destroy` or any delete path. Removing live resources is deliberately manual.
+- No dry-run apply against a scratch copy of a project.
+- No source maps from a platform validation error back to the authoring line that caused it.
+- No shell completion.