@getxflow/cli 0.6.5 → 0.7.0

package/skills/xflow/SKILL.md

@@ -1,451 +1,485 @@
----
-name: xflow
-description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever the project root has xflow.json or VITE_XFLOW_* variables, and for any task that touches deployment, publishing, rollback, source sync, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, production errors and logs, or UI built on the platform design system.
----
-
-# XFlow
-
-Hosting for web apps. The code lives in an ordinary repository on the developer
-machine, `xflow deploy` sends the sources, and the platform builds them in a clean
-sandbox and serves the result as static files. A platform project is recognized by
-the `xflow.json` file in its root.
-
-## First rule
-
-Check commands and flags against `xflow help` and `xflow help <command>`, not against
-memory. If a command is not in the help output, it does not exist: guessing flags is
-pointless. The CLI prints a hint with almost every error, read it in full, it usually
-contains the fix.
-
-When the CLI says a newer version is out, or refuses to work because the platform wants
-a newer one, run `xflow update`. It also rewrites these instructions, which ship inside
-the package: what you are reading may be older than the platform you are working on.
-
-## Hard rules
-
-These mistakes cost the most because nothing fails at the moment they are made, or
-the error points away from the cause. The sections below carry the details.
-
-1. Read environment variables literally: `process.env.API_KEY`. Destructuring
-   (`const { API_KEY } = process.env`) reads as no mention of the variable at all,
-   and it arrives empty.
-2. A value written with `xflow env set` reaches the functions on the next
-   `xflow deploy`, not at the moment it is written.
-3. Never delete a `functions/<name>/` directory unless the user asked for that
-   function to go. The next deploy removes it from the cloud together with its
-   schedules, and a function created again later gets a different address.
-4. An already applied migration is never re-run, so editing its file changes
-   nothing. A schema change is always a new file.
-5. When inserts start failing with `db_write_locked`, the database is over its plan
-   size. The fix is a migration that deletes data, never a rewrite of the failing SQL.
-6. In file storage, call `confirm` only after the PUT has finished, and send the same
-   `Content-Type` in both calls. Both mistakes answer 200 and break later.
-
-## Plan limits
-
-The organization runs on a plan with finite limits: projects, cloud functions, developer
-and staff seats, database and file storage, function minutes per month, plus the right to
-use schedules. `xflow whoami` prints every one of them next to what is already used, and
-reading it before a long task is cheaper than hitting a wall mid-way.
-
-A limit refusal is not a bad request. The CLI prints a line starting with `Plan limit:`,
-the API answers `code: "forbidden"` with a `limit` object (`code`, `used`, `limit`), and
-MCP tools carry the same field. Retrying the command, renaming things or rewriting the
-code changes nothing: tell the user what ran out and stop. Only the owner or an admin
-lifts it, in the web interface, by freeing the resource or moving to a bigger plan.
-
-One refusal looks like a code error but is not: when the database is over its plan size,
-Postgres itself rejects inserts (`db_write_locked`). Reads and deletes still work, so the
-fix is a migration that deletes data, never a rewrite of the failing SQL. Write is
-restored within an hour of the data going back under the limit.
-
-## Workflow
-
-1. Change the code.
-2. `npm run typecheck` for a two-second type check (older projects may not have the
-   script, then `npx tsc --noEmit`).
-3. `npm run build` if the change is substantial, before deploying.
-4. `xflow deploy` sends the sources, ships the cloud functions and builds the application
-   on the platform, printing each phase and the six-digit number of the version it built.
-5. Give the user the project link the CLI printed and let them look. Do not open a
-   browser for them.
-6. `xflow publish` makes that same version visible to visitors.
-
-The split is deliberate: shipping a build and showing it are two separate decisions.
-Until `publish` runs, visitors keep seeing the previous version. The one exception is
-the very first version of a project: it publishes automatically, since there is no
-live version to protect yet.
-
-Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>`
-points the project back at an earlier build. Sources stay on their own revision.
-
-**The only link you give a person is the project page**, `https://app.getxflow.com/projects/<id>`,
-which the CLI prints for you. Refer to builds by their number ("version 481203 is built,
-092399 is what visitors see"), never by address. The platform does not hand out build
-addresses and neither should you: a build address has the version number baked into it,
-and after the next publish it does not break, it keeps answering with the old copy. Anyone
-holding that link then stares at a frozen app and concludes the changes never shipped. The
-project page always shows the current state, and every version is reachable from it.
-
-The platform builds the project itself, in a clean sandbox with one Node version for
-everyone, and serves the result as static files. Nothing is built on your machine for
-deployment, so a local `npm run build` is only a fast way to see errors early.
-
-## Build gate
-
-Before the sandbox starts, the platform checks the sources against the template. Every
-rule below blocks the build, and the whole list of violations comes back at once, with
-files and line numbers. Nothing is charged for a rejected attempt: the sandbox never
-starts. Write code that already satisfies these rules instead of learning them from
-rejections.
-
-Build setup:
-
-- `package.json` with the build script named in `xflow.json` (`npm run build` by default).
-- Vite: a `vite.config.*` and `vite` in dependencies.
-- No server frameworks: `next`, `nuxt`, `remix`, `@sveltejs/kit`, `astro`.
-- `index.html` in the root, `src/main.tsx` as the entry point.
-- Application code under `src/`. Root `app/`, `pages/`, `next/` are rejected.
-
-Platform contract, checked across all of `src/`:
-
-- Call cloud functions through `xflow.functions.invoke`, never through a hardcoded
-  `*.yandexcloud.net` URL: the address changes and the app breaks silently.
-- No API keys or tokens in the source: they end up in the bundle. Put the call in a
-  cloud function and the key in project secrets.
-- No server modules (`fs`, `express`, `http`, `child_process`): there is no server runtime.
-
-Interface rules, checked outside `src/components/ui` and `src/components/blocks`:
-
-- No `alert()`, `confirm()`, `prompt()`. Use the Dialog and Toast components.
-- No `console.log`. Deployed apps have a public console, and forgotten debugging prints
-  user data into it. `console.error` and `console.warn` are fine, they reach the project
-  logs.
-- No inline styles with literal values (`style={{ color: '#fff' }}`). Computed styles
-  (a drag transform, a progress width) are fine, Tailwind cannot express them.
-- No hex colors or Tailwind palette classes (`text-gray-500`): use the theme tokens.
-  Charts are exempt, they need real colors.
-- No importing a `@/components/ui/*` component that does not exist in the project.
-- A library that needs a provider (`@tanstack/react-query`, `react-redux`, `sonner`,
-  `react-hot-toast`, `react-dnd`) must have it mounted in `App.tsx`. Missing providers
-  build fine and give visitors a white screen.
-
-Template integrity. The app grows out of the platform template, and part of that template
-is not yours to change. The reference is a snapshot of the project itself, taken when the
-platform first looked at it, so these rules never argue with work that was already there:
-
-- Platform files must stay byte for byte as they arrived: `src/lib/theme-sync.ts`,
-  `src/lib/platform-auth.ts`, `src/contexts/platform-auth-context.tsx`,
-  `src/hooks/use-platform-auth.ts`, `src/utils/error-logger.ts`, `src/lib/xflow.ts`.
-  They wire the app to the platform, and every way they break is a silent one. Build what
-  you need around them, never inside them.
-- The entry point keeps calling `initThemeSync()`, `initPlatformAuth()` and
-  `initErrorLogger()`, keeps importing `index.css` and keeps mounting `ThemeProvider`.
-  How the file is written is up to you.
-- `index.html` keeps the element with `id="root"` and the script that loads `src/main`.
-- Theme token names in `src/index.css` stay declared, in `:root` and in `.dark` alike, and
-  the Tailwind config keeps mapping them. Change the values as much as the design needs:
-  it is the names that components paint with.
-- The Tailwind `content` globs keep covering `src/**`. Narrow them and Tailwind strips
-  every class the app uses.
-- Files under `src/components/ui` and `src/components/blocks` may be edited freely but
-  not deleted.
-
-A rejection names the file and the revision to take the original from:
-`xflow pull --revision N --into ./original`, then copy the file back.
-
-## Cloud functions
-
-Server-side code lives in `functions/<name>/index.ts` and exports `handler`. There is no
-separate deploy command: `xflow deploy` ships the functions and then builds the application,
-in that order. List what is live with `xflow functions list`. The handler returns
-`{ statusCode, body }` where `body` is a JSON string.
-
-Keep one shape inside that string across the whole project: `{ success: true, data }`
-when it worked, `{ success: false, error: { message, code } }` when it did not. Nothing
-enforces this, but a project where every function answers its own way costs an adapter
-on every call. Branch the frontend on `error.code`, never on `error.message`: wording
-gets rewritten on any edit, a code does not.
-
-The sources are the whole truth about which functions exist. Delete the directory and the
-next deploy would delete the function from the cloud, schedules included, and that cannot be
-undone: a function created again later gets a different address. So never remove a function
-directory to "clean up" unless the user asked for the function to go.
-
-Such a deploy does not start on its own: the platform names the functions it would remove and
-refuses until somebody agrees. Under an agent there is no terminal to ask in, so the refusal
-reaches you, and `--allow-removals` is the only way past it. Adding that flag to get the
-build running is exactly the wrong move: it means you deleted something the user did not ask
-you to delete. Put the directories back instead, and if the removal really is intended, say
-which functions are about to go and let the user answer.
-
-Debugging a deployed function is two commands: `xflow functions invoke <name>` calls it
-the way the app does and prints status, timing and body (`--data '{"a":1}'` sends a body),
-and `xflow functions logs <name>` shows the failures, each with its stack and the console
-output of that call. Only failed calls are logged, so an empty output means the function
-never crashed, not that logging is broken.
-
-From the app, call a function through `src/lib/xflow.ts`:
-`await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the credentials
-for you. Addresses are baked into the build, which is why the functions go out first:
-by the time the bundle is built they already exist, and a new function is never missing
-from the application that calls it.
-
-### Who is calling
-
-A function answers only to a member of the organization who has access to that project.
-The platform issues a short-lived pass when it opens the application, the wrapper checks it
-with the platform on every call, and the handler receives the answer in `event.xflow`:
-
-```js
-exports.handler = async (event) => {
-  const { caller, user } = event.xflow
-  // caller: 'visitor' (a person), 'service' (another function of this project),
-  //         'external' (an outside service with a key), 'schedule' (a timer run)
-  // user:   { id, role } for a visitor, null for everything else
-}
-```
-
-Never trust an identity that arrives in the body or in a header of the request: those are
-written by the page, which lives on someone else's computer. `event.xflow` is the only
-identity the platform stands behind, and `usePlatformAuth()` in the frontend is a hint for
-the interface, not a check.
-
-A function that changes data should say so instead of checking the role by hand:
-
-```js
-exports.minRole = 'admin'   // 'member' | 'developer' | 'admin' | 'owner'
-```
-
-The wrapper refuses anything below that role before your code runs. Without the line every
-member of the project can call the function, including the ones who may only look at apps.
-
-Losing access closes the function within five minutes, so a removed member cannot keep calling it.
-Opening the deployed address directly does not work either: there is no pass outside the
-platform.
-
-Calling a function from another function is a server call. Send two headers, both from the
-environment the platform fills in: `X-Project-Token` with `process.env.XFLOW_PROJECT_TOKEN`
-and `X-Server-Key` with `process.env.XFLOW_SERVER_KEY`. The token is the ticket into the
-project and the key is the identity; the wrapper checks the ticket first, so the key alone
-answers 401.
-
-An outside service (a webhook from a payment provider, a bot, a CRM) has no person behind it
-and needs a key of that one function. Keys are not issued by default and the CLI cannot
-create one: a human issues it in the project settings: «Облачные функции» → the function →
-«Настройки». Ask the user to do that and to paste the address back to you — never invent
-another way in. A function holds at most two keys, and the second one exists to replace the
-first without downtime, not to serve a second consumer.
-
-`xflow functions list` shows who can reach each function: `in-app only` (no keys, answers
-only inside the application) or `external (N keys)` (a human issued external access). Key
-values are never shown there.
-
-Keys and passwords live on the platform, not in the repository: `xflow env set SMTP_PASSWORD=…`
-writes one, `xflow env` lists the names, `xflow env check` tells you which variables your
-functions read but the platform does not have. Values never come back out — the only place
-they exist is inside the running function.
-
-A function receives only the variables it mentions by name via `process.env.NAME`, so never
-assemble a variable name from an expression and never destructure the environment
-(`const { API_KEY } = process.env` reads as no mention at all, and the variable arrives
-empty). New values arrive on the next `xflow deploy`, not at the moment they are written.
-
-Some variables come from a connected account instead of from you. When someone connects an
-advertising cabinet or another external service in the platform settings and links it to the
-project, its credentials show up in `xflow env` marked read-only, under a prefix chosen at
-link time: `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_CLIENT_LOGIN`. Read them like any other
-variable. Do not try to `xflow env set` those names: the platform keeps the values in sync
-and refuses. If a call to that service starts failing with an authorisation error, run
-`xflow status`: it says whether the token is merely expiring (any build renews it) or the
-account was disconnected on the provider's side, which only a human can fix by reconnecting
-it in the platform settings.
-
-`xflow connections` lists those accounts: the ones already linked to this project, with the
-alias and the state of the access, and the ones the organization has but this project does
-not use yet, marked `available, not linked`. Check it before telling anyone a service is
-unavailable: the account you need is often connected already, one link away. Linking is
-done by a person, in the project settings under Connectors, because it hands the credentials
-to everyone who deploys the project; there is no command for it.
-
-To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
-Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
-how Yandex wants it. A scheduled run reaches the handler as a POST with no headers.
-
-The pieces line up in one pass. From a new function to a verified schedule:
-
-```
-xflow env set SMTP_PASSWORD=...            # secrets first: values ride the next deploy
-# write functions/report/index.ts, reading process.env.SMTP_PASSWORD literally
-xflow deploy                               # ships the function, then builds the app
-xflow schedules set report "0 3 ? * * *"   # after the deploy: a schedule needs a deployed function
-xflow functions invoke report              # run it once, the way the app would
-xflow functions logs report                # empty output means it never crashed
-```
-
-## Database
-
-Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql`, applied
-in filename order by `xflow db migrate`. `xflow db status` shows what is applied and what
-waits. History lives in the database itself, so an already applied file is never re-run and
-editing it changes nothing: write a new migration instead.
-
-The browser never reaches the database directly. The app reads and writes through a cloud
-function, and inside the handler the connection string is already there:
-
-```js
-const { Client } = require('pg')
-const db = new Client({ connectionString: process.env.DATABASE_URL })
-```
-
-The platform passes `DATABASE_URL` only to functions that mention it, and sets the project
-schema on every connection, so plain table names (`select * from tasks`) hit your project.
-You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused. The same
-goes for every name starting with `XFLOW`: the platform fills those in itself, and your value
-under one of them would shadow the real one.
-
-The platform keeps no database history and no backups. Anything that destroys data
-(`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) is refused
-unless two things hold at once: you pass `--allow-destructive`, and the access key carries
-the right to destroy data. That right is off by default and only its owner can turn it on,
-in the platform settings, under Developers. So when a destructive migration is refused for
-the right rather than the flag, adding the flag changes nothing: say what needs deleting and
-why, and let the person decide. With both in place the affected tables are dumped first and
-kept for 7 days. Check with `--dry-run` before applying.
-
-One logical database can be shared by several projects, so your migration can break an app
-you do not see. `xflow db status` lists applied migrations that have no file in your
-repository: that is what someone else's project did.
-
-For the same reason the `migrations/` directory is not the schema. It says what you did;
-`xflow db schema` says what is in the database right now, and `xflow db schema <table>` gives
-the columns of one table. `xflow db query "select ..."` reads data, inside a READ ONLY
-transaction, so a write there fails by design rather than by accident. Look before you write
-a migration against a shared database.
-
-## File storage
-
-The project has file storage, and the browser cannot reach it. Those endpoints take only the
-server key of the project, and the platform puts it into the environment of your cloud
-functions as `XFLOW_SERVER_KEY`. Nothing else holds it: not the bundle, not `.env`, not
-`xflow env`.
-
-So uploading is a function of your own. It asks the platform for a one-time link, the browser
-then sends the bytes straight to storage, and a second call records the file:
-
-```js
-const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/upload-url`, {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'X-Server-Key': process.env.XFLOW_SERVER_KEY,
-  },
-  body: JSON.stringify({ fileName, fileSize, contentType, folderPath: 'invoices' }),
-}).then((r) => r.json())
-```
-
-`confirm` takes the same fields plus the returned `s3Key` and answers with the file and its
-public address; `delete` takes the file `url`. Never pipe the bytes through the function itself.
-
-There is no endpoint that lists the files back, so the address that `confirm` returns is the
-only copy you get: write it into a table of your own in the same call, and the application
-reads its files from there.
-
-Four things bite an upload that otherwise looks right, and none of them is obvious from the
-answers you get:
-
-- **The content type can quietly split in two.** Nothing checks that the `Content-Type` the
-  browser sends on the PUT matches the one you named in `upload-url`: both calls answer 200.
-  But storage keeps the header the browser sent and serves the file under it, while the
-  record keeps the one you named, so a card can say `image/png` about a file every browser
-  treats as HTML. Send the same string in both calls and they cannot drift.
-- **The same name in the same folder is refused.** Names are unique per folder, so a second
-  `avatar.png` fails instead of replacing the first. Give the name a suffix of your own, or
-  delete the old file before confirming the new one.
-- **The limits are 200 MB per file and the storage quota of the organization.** The quota is
-  checked again on `confirm`, by the real size, which means a refusal can land after the
-  bytes are already up; the platform then removes the object and your table stays clean.
-- **Confirm only after the PUT has finished.** The platform looks the object up in storage
-  and takes its real size from there, not from what you declared, so an early `confirm`
-  answers that the file is not there.
-
-A refusal comes back as `{ error, code }`. Branch on `code` (`invalid_name`, `file_too_large`,
-`quota_exceeded`, `not_uploaded`, `duplicate_name`, `not_found`, …) and never on the text:
-the wording is free to change, the code is not.
-
-What the app may do with files is decided inside that function, because the page in the
-browser can be edited by whoever opened it. Never write the key into the sources and never
-send it to the frontend: the build gate stops on a key found in the application code, and a
-key that reached a visitor lets them delete every file of the project.
-
-## Syncing code
-
-`xflow status` shows how the local copy differs from the server revision.
-`xflow push` sends sources, `xflow pull` fetches them.
-
-If a push is rejected, the server revision is newer, meaning someone pushed first.
-Fetch their work next to yours (`xflow pull --into ./server-copy`), merge it locally,
-then push again. `--force` destroys their work: a last resort, not a way around the
-error.
-
-## Direct access without the terminal
-
-The platform also exposes an MCP server, connected with `xflow mcp install`. When its tools
-are available, prefer them for control-plane work: project state, database schema and
-read-only queries, migrations, function logs and invocations, schedules, environment
-variables, versions, publish and rollback. They answer with aggregates and say explicitly
-when a result is truncated, which parsing terminal output does not.
-
-Anything that depends on the working copy stays in the CLI: sending sources (`xflow push`),
-building and shipping the functions (`xflow deploy`), creating a project (`xflow init`). The
-tools cannot see the folder you are working in, so a build started from there would release
-whatever revision the server happens to hold, not what you have on disk. Pulling a repository
-through tool calls also burns the user's tokens for nothing.
-
-## Do not
-
-- Edit `xflow.json` by hand: the CLI writes it.
-- Commit `.env`: it holds the project token.
-- Push with `--force` without checking `xflow status` first.
-- Invent platform commands: what is not in `xflow help` does not exist.
-
-## App design
-
-The platform design system already ships inside the project, and the app is supposed
-to look like a part of the platform:
-
-- `src/components/ui` for primitives: buttons, inputs, dialogs, tables, menus
-- `src/components/blocks` for composed blocks: `data-table` and `charts`
-- `src/index.css` for color tokens
-
-Before writing your own component, check whether a block already covers it: props are
-typed next to each block, larger ones keep a separate `types.ts`. Take colors from
-tokens (`bg-card`, `text-muted-foreground`, `bg-success-soft` and the like). A custom
-hex palette makes the app look foreign inside the platform, which is the whole reason
-the design system sits in the project.
-
-The app runs inside the platform in an iframe and receives the theme and the current
-user from it. The `usePlatformAuth()` hook gives the name, role, permissions and the
-list of organization members. Use it to draw the interface, never to guard data: the
-value lives on the page and is edited from the console. Guard data in the function, by
-`event.xflow`.
-
-## Errors from a deployed app
-
-`xflow logs` prints what broke in the browser on deployed addresses: unhandled errors,
-rejected promises and 5xx responses. The same stream, functions included, is in the
-platform UI: open the project, section «Облако» (Cloud), tab «Логи» (Logs). The last 200
-records per project are kept.
-
-Local `npm run dev` does not report anything: these logs exist for what you cannot open
-in your own devtools.
-
-Cloud functions do work under `npm run dev`, and nothing has to be configured for that:
-the dev server swaps the access key of the logged-in developer for the same narrow pass and
-forwards the call. If it answers that the key is missing, the fix is `xflow login`.
-
-## Environment
-
-`VITE_XFLOW_PROJECT_TOKEN` and `VITE_XFLOW_API_URL` are written by the CLI when the
-project is created, there is no need to edit them by hand. For CI and agent runs:
-`XFLOW_TOKEN` replaces `xflow login`, `XFLOW_API_URL` points at another platform host.
+---
+name: xflow
+description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever the project root has xflow.json or VITE_XFLOW_* variables, and for any task that touches deployment, publishing, rollback, source sync, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, production errors and logs, or UI built on the platform design system.
+---
+
+# XFlow
+
+Hosting for web apps. The code lives in an ordinary repository on the developer
+machine, `xflow deploy` sends the sources, and the platform builds them in a clean
+sandbox and serves the result as static files. A platform project is recognized by
+the `xflow.json` file in its root.
+
+## First rule
+
+Check commands and flags against `xflow help` and `xflow help <command>`, not against
+memory. If a command is not in the help output, it does not exist: guessing flags is
+pointless. The CLI prints a hint with almost every error, read it in full, it usually
+contains the fix.
+
+When the CLI says a newer version is out, or refuses to work because the platform wants
+a newer one, run `xflow update`. It also rewrites these instructions, which ship inside
+the package: what you are reading may be older than the platform you are working on.
+
+## Hard rules
+
+These mistakes cost the most because nothing fails at the moment they are made, or
+the error points away from the cause. The sections below carry the details.
+
+1. Read environment variables literally: `process.env.API_KEY`. Destructuring
+   (`const { API_KEY } = process.env`) reads as no mention of the variable at all,
+   and it arrives empty.
+2. A value written with `xflow env set` reaches the functions on the next
+   `xflow deploy`, not at the moment it is written.
+3. Never delete a `functions/<name>/` directory unless the user asked for that
+   function to go. The next deploy removes it from the cloud together with its
+   schedules, and a function created again later gets a different address.
+4. An already applied migration is never re-run, so editing its file changes
+   nothing. A schema change is always a new file.
+5. When inserts start failing with `db_write_locked`, the database is over its plan
+   size. The fix is a migration that deletes data, never a rewrite of the failing SQL.
+6. In file storage, call `confirm` only after the PUT has finished, and send the same
+   `Content-Type` in both calls. Both mistakes answer 200 and break later.
+
+## Plan limits
+
+The organization runs on a plan with finite limits: projects, cloud functions, developer
+and staff seats, database and file storage, function minutes per month, plus the right to
+use schedules. `xflow whoami` prints every one of them next to what is already used, and
+reading it before a long task is cheaper than hitting a wall mid-way.
+
+A limit refusal is not a bad request. The CLI prints a line starting with `Plan limit:`,
+the API answers `code: "forbidden"` with a `limit` object (`code`, `used`, `limit`), and
+MCP tools carry the same field. Retrying the command, renaming things or rewriting the
+code changes nothing: tell the user what ran out and stop. Only the owner or an admin
+lifts it, in the web interface, by freeing the resource or moving to a bigger plan.
+
+One refusal looks like a code error but is not: when the database is over its plan size,
+Postgres itself rejects inserts (`db_write_locked`). Reads and deletes still work, so the
+fix is a migration that deletes data, never a rewrite of the failing SQL. Write is
+restored within an hour of the data going back under the limit.
+
+## Workflow
+
+1. Change the code.
+2. `npm run typecheck` for a two-second type check (older projects may not have the
+   script, then `npx tsc --noEmit`).
+3. `npm run build` if the change is substantial, before deploying.
+4. `xflow deploy` sends the sources, ships the cloud functions and builds the application
+   on the platform, printing each phase and the six-digit number of the version it built.
+5. Give the user the project link the CLI printed and let them look. Do not open a
+   browser for them.
+6. `xflow publish` makes that same version visible to visitors.
+
+The split is deliberate: shipping a build and showing it are two separate decisions.
+Until `publish` runs, visitors keep seeing the previous version. The one exception is
+the very first version of a project: it publishes automatically, since there is no
+live version to protect yet.
+
+Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>`
+points the project back at an earlier build. Sources stay on their own revision.
+
+**The only link you give a person is the project page**, `https://app.getxflow.com/projects/<id>`,
+which the CLI prints for you. Refer to builds by their number ("version 481203 is built,
+092399 is what visitors see"), never by address. The platform does not hand out build
+addresses and neither should you: a build address has the version number baked into it,
+and after the next publish it does not break, it keeps answering with the old copy. Anyone
+holding that link then stares at a frozen app and concludes the changes never shipped. The
+project page always shows the current state, and every version is reachable from it.
+
+The platform builds the project itself, in a clean sandbox with one Node version for
+everyone, and serves the result as static files. Nothing is built on your machine for
+deployment, so a local `npm run build` is only a fast way to see errors early.
+
+## Build gate
+
+Before the sandbox starts, the platform checks the sources against the template. Every
+rule below blocks the build, and the whole list of violations comes back at once, with
+files and line numbers. Nothing is charged for a rejected attempt: the sandbox never
+starts. Write code that already satisfies these rules instead of learning them from
+rejections.
+
+Build setup:
+
+- `package.json` with the build script named in `xflow.json` (`npm run build` by default).
+- Vite: a `vite.config.*` and `vite` in dependencies.
+- No server frameworks: `next`, `nuxt`, `remix`, `@sveltejs/kit`, `astro`.
+- `index.html` in the root, `src/main.tsx` as the entry point.
+- Application code under `src/`. Root `app/`, `pages/`, `next/` are rejected.
+
+Platform contract, checked across all of `src/`:
+
+- Call cloud functions through `xflow.functions.invoke`, never through a hardcoded
+  `*.yandexcloud.net` URL: the address changes and the app breaks silently.
+- No API keys or tokens in the source: they end up in the bundle. Put the call in a
+  cloud function and the key in project secrets.
+- No server modules (`fs`, `express`, `http`, `child_process`): there is no server runtime.
+
+Interface rules, checked outside `src/components/ui` and `src/components/blocks`:
+
+- No `alert()`, `confirm()`, `prompt()`. Use the Dialog and Toast components.
+- No `console.log`. Deployed apps have a public console, and forgotten debugging prints
+  user data into it. `console.error` and `console.warn` are fine, they reach the project
+  logs.
+- No inline styles with literal values (`style={{ color: '#fff' }}`). Computed styles
+  (a drag transform, a progress width) are fine, Tailwind cannot express them.
+- No hex colors or Tailwind palette classes (`text-gray-500`): use the theme tokens.
+  Charts are exempt, they need real colors.
+- No importing a `@/components/ui/*` component that does not exist in the project.
+- A library that needs a provider (`@tanstack/react-query`, `react-redux`, `sonner`,
+  `react-hot-toast`, `react-dnd`) must have it mounted in `App.tsx`. Missing providers
+  build fine and give visitors a white screen.
+
+Template integrity. The app grows out of the platform template, and part of that template
+is not yours to change. The reference is a snapshot of the project itself, taken when the
+platform first looked at it, so these rules never argue with work that was already there:
+
+- Platform files must stay byte for byte as they arrived: `src/lib/theme-sync.ts`,
+  `src/lib/platform-auth.ts`, `src/contexts/platform-auth-context.tsx`,
+  `src/hooks/use-platform-auth.ts`, `src/utils/error-logger.ts`, `src/lib/xflow.ts`.
+  They wire the app to the platform, and every way they break is a silent one. Build what
+  you need around them, never inside them.
+- The entry point keeps calling `initThemeSync()`, `initPlatformAuth()` and
+  `initErrorLogger()`, keeps importing `index.css` and keeps mounting `ThemeProvider`.
+  How the file is written is up to you.
+- `index.html` keeps the element with `id="root"` and the script that loads `src/main`.
+- Theme token names in `src/index.css` stay declared, in `:root` and in `.dark` alike, and
+  the Tailwind config keeps mapping them. Change the values as much as the design needs:
+  it is the names that components paint with.
+- The Tailwind `content` globs keep covering `src/**`. Narrow them and Tailwind strips
+  every class the app uses.
+- Files under `src/components/ui` and `src/components/blocks` may be edited freely but
+  not deleted.
+
+A rejection names the file and the revision to take the original from:
+`xflow pull --revision N --into ./original`, then copy the file back.
+
+## Cloud functions
+
+Server-side code lives in `functions/<name>/index.ts` and exports `handler`. There is no
+separate deploy command: `xflow deploy` ships the functions and then builds the application,
+in that order. List what is live with `xflow functions list`. The handler returns
+`{ statusCode, body }` where `body` is a JSON string.
+
+Keep one shape inside that string across the whole project: `{ success: true, data }`
+when it worked, `{ success: false, error: { message, code } }` when it did not. Nothing
+enforces this, but a project where every function answers its own way costs an adapter
+on every call. Branch the frontend on `error.code`, never on `error.message`: wording
+gets rewritten on any edit, a code does not.
+
+The sources are the whole truth about which functions exist. Delete the directory and the
+next deploy would delete the function from the cloud, schedules included, and that cannot be
+undone: a function created again later gets a different address. So never remove a function
+directory to "clean up" unless the user asked for the function to go.
+
+Such a deploy does not start on its own: the platform names the functions it would remove and
+refuses until somebody agrees. Under an agent there is no terminal to ask in, so the refusal
+reaches you, and `--allow-removals` is the only way past it. Adding that flag to get the
+build running is exactly the wrong move: it means you deleted something the user did not ask
+you to delete. Put the directories back instead, and if the removal really is intended, say
+which functions are about to go and let the user answer.
+
+Debugging a deployed function is two commands: `xflow functions invoke <name>` calls it
+the way the app does and prints status, timing and body (`--data '{"a":1}'` sends a body),
+and `xflow functions logs <name>` shows the failures, each with its stack and the console
+output of that call. Only failed calls are logged, so an empty output means the function
+never crashed, not that logging is broken.
+
+From the app, call a function through `src/lib/xflow.ts`:
+`await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the credentials
+for you. Addresses are baked into the build, which is why the functions go out first:
+by the time the bundle is built they already exist, and a new function is never missing
+from the application that calls it.
+
+### Who is calling
+
+A function answers only to a member of the organization who has access to that project.
+The platform issues a short-lived pass when it opens the application, the wrapper checks it
+with the platform on every call, and the handler receives the answer in `event.xflow`:
+
+```js
+exports.handler = async (event) => {
+  const { caller, user } = event.xflow
+  // caller: 'visitor' (a person), 'service' (another function of this project),
+  //         'external' (an outside service with a key), 'schedule' (a timer run)
+  // user:   { id, role } for a visitor, null for everything else
+}
+```
+
+Never trust an identity that arrives in the body or in a header of the request: those are
+written by the page, which lives on someone else's computer. `event.xflow` is the only
+identity the platform stands behind, and `usePlatformAuth()` in the frontend is a hint for
+the interface, not a check.
+
+A function that changes data should say so instead of checking the role by hand:
+
+```js
+exports.minRole = 'admin'   // 'member' | 'developer' | 'admin' | 'owner'
+```
+
+The wrapper refuses anything below that role before your code runs. Without the line every
+member of the project can call the function, including the ones who may only look at apps.
+
+Losing access closes the function within five minutes, so a removed member cannot keep calling it.
+Opening the deployed address directly does not work either: there is no pass outside the
+platform.
+
+Calling a function from another function is a server call. Send two headers, both from the
+environment the platform fills in: `X-Project-Token` with `process.env.XFLOW_PROJECT_TOKEN`
+and `X-Server-Key` with `process.env.XFLOW_SERVER_KEY`. The token is the ticket into the
+project and the key is the identity; the wrapper checks the ticket first, so the key alone
+answers 401.
+
+An outside service (a webhook from a payment provider, a bot, a CRM) has no person behind it
+and needs a key of that one function. Keys are not issued by default and the CLI cannot
+create one: a human issues it in the project settings: «Облачные функции» → the function →
+«Настройки». Ask the user to do that and to paste the address back to you — never invent
+another way in. A function holds at most two keys, and the second one exists to replace the
+first without downtime, not to serve a second consumer.
+
+`xflow functions list` shows who can reach each function: `in-app only` (no keys, answers
+only inside the application) or `external (N keys)` (a human issued external access). Key
+values are never shown there.
+
+Keys and passwords live on the platform, not in the repository: `xflow env set SMTP_PASSWORD=…`
+writes one, `xflow env` lists the names, `xflow env check` tells you which variables your
+functions read but the platform does not have. Values never come back out — the only place
+they exist is inside the running function.
+
+A function receives only the variables it mentions by name via `process.env.NAME`, so never
+assemble a variable name from an expression and never destructure the environment
+(`const { API_KEY } = process.env` reads as no mention at all, and the variable arrives
+empty). New values arrive on the next `xflow deploy`, not at the moment they are written.
+
+Some variables come from a connected account instead of from you. When someone connects an
+advertising cabinet or another external service in the platform settings and links it to the
+project, its credentials show up in `xflow env` marked read-only, under a prefix chosen at
+link time: `YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_CLIENT_LOGIN`. Read them like any other
+variable. Do not try to `xflow env set` those names: the platform keeps the values in sync
+and refuses. If a call to that service starts failing with an authorisation error, run
+`xflow status`: it says whether the token is merely expiring (any build renews it) or the
+account was disconnected on the provider's side, which only a human can fix by reconnecting
+it in the platform settings.
+
+`xflow connections` lists those accounts: the ones already linked to this project, with the
+alias and the state of the access, and the ones the organization has but this project does
+not use yet, marked `available, not linked`. Check it before telling anyone a service is
+unavailable: the account you need is often connected already, one link away.
+
+`xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA` is that link, and
+`xflow connections unlink YANDEX_METRIKA` undoes it. Name the connection the way the list
+does, in its first column, or by its identifier; unlink also takes the alias, which your
+own code already knows. If two accounts of the same service share a name, the command
+prints their identifiers instead of guessing. Unlink refuses while a function still reads
+one of the variables and names those functions, so read that list before reaching for
+`--force`.
+
+Linking needs the `connections:link` right, which keys are issued with. If it was taken
+away, say so and ask the person to turn it back on in the platform settings under
+Developers: a key cannot grant it to itself. Only accounts granted to the owner of the key
+personally can be linked at all. Connecting a new account and switching one off stay with a
+person too.
+
+To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
+Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
+how Yandex wants it. A scheduled run reaches the handler as a POST with no headers.
+
+The pieces line up in one pass. From a new function to a verified schedule:
+
+```
+xflow env set SMTP_PASSWORD=...            # secrets first: values ride the next deploy
+# write functions/report/index.ts, reading process.env.SMTP_PASSWORD literally
+xflow deploy                               # ships the function, then builds the app
+xflow schedules set report "0 3 ? * * *"   # after the deploy: a schedule needs a deployed function
+xflow functions invoke report              # run it once, the way the app would
+xflow functions logs report                # empty output means it never crashed
+```
+
+## Database
+
+Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql`, applied
+in filename order by `xflow db migrate`. `xflow db status` shows what is applied and what
+waits. History lives in the database itself, so an already applied file is never re-run and
+editing it changes nothing: write a new migration instead.
+
+The browser never reaches the database directly. The app reads and writes through a cloud
+function, and inside the handler the connection string is already there:
+
+```js
+const { Client } = require('pg')
+const db = new Client({ connectionString: process.env.DATABASE_URL })
+```
+
+The platform passes `DATABASE_URL` only to functions that mention it, and sets the project
+schema on every connection, so plain table names (`select * from tasks`) hit your project.
+You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused, and so is
+`xflow env rm DATABASE_URL`. The same goes for every name starting with `XFLOW`: the platform
+fills those in itself, and your value under one of them would shadow the real one.
+
+`env` commands reach only what this project can see: variables shared across the organization
+and the ones bound to this project. A variable bound to a different project is invisible here,
+so `env rm` reports it as missing even though names are unique within the organization.
+
+The platform keeps no database history and no backups. Anything that destroys data
+(`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) is refused
+unless two things hold at once: you pass `--allow-destructive`, and the access key carries
+the right to destroy data. That right is off by default and only its owner can turn it on,
+in the platform settings, under Developers. So when a destructive migration is refused for
+the right rather than the flag, adding the flag changes nothing: say what needs deleting and
+why, and let the person decide. With both in place the affected tables are dumped first and
+kept for 7 days. Check with `--dry-run` before applying.
+
+One logical database can be shared by several projects, so your migration can break an app
+you do not see. `xflow db status` lists applied migrations that have no file in your
+repository: that is what someone else's project did.
+
+For the same reason the `migrations/` directory is not the schema. It says what you did;
+`xflow db schema` says what is in the database right now, and `xflow db schema <table>` gives
+the columns of one table. `xflow db query "select ..."` reads data, inside a READ ONLY
+transaction, so a write there fails by design rather than by accident. Look before you write
+a migration against a shared database.
+
+## File storage
+
+The project has file storage, and the browser cannot reach it. Those endpoints take only the
+server key of the project, and the platform puts it into the environment of your cloud
+functions as `XFLOW_SERVER_KEY`. Nothing else holds it: not the bundle, not `.env`, not
+`xflow env`.
+
+So uploading is a function of your own. It asks the platform for a one-time link, the browser
+then sends the bytes straight to storage, and a second call records the file:
+
+```js
+const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/upload-url`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Server-Key': process.env.XFLOW_SERVER_KEY,
+  },
+  body: JSON.stringify({ fileName, fileSize, contentType, folderPath: 'invoices' }),
+}).then((r) => r.json())
+```
+
+`confirm` takes the same fields plus the returned `s3Key` and answers with the file and its
+public address; `delete` takes the file `url`. Never pipe the bytes through the function itself.
+
+There is no endpoint that lists the files back, so the address that `confirm` returns is the
+only copy you get: write it into a table of your own in the same call, and the application
+reads its files from there.
+
+Four things bite an upload that otherwise looks right, and none of them is obvious from the
+answers you get:
+
+- **The content type can quietly split in two.** Nothing checks that the `Content-Type` the
+  browser sends on the PUT matches the one you named in `upload-url`: both calls answer 200.
+  But storage keeps the header the browser sent and serves the file under it, while the
+  record keeps the one you named, so a card can say `image/png` about a file every browser
+  treats as HTML. Send the same string in both calls and they cannot drift.
+- **The same name in the same folder is refused.** Names are unique per folder, so a second
+  `avatar.png` fails instead of replacing the first. Give the name a suffix of your own, or
+  delete the old file before confirming the new one.
+- **The limits are 200 MB per file and the storage quota of the organization.** The quota is
+  checked again on `confirm`, by the real size, which means a refusal can land after the
+  bytes are already up; the platform then removes the object and your table stays clean.
+- **Confirm only after the PUT has finished.** The platform looks the object up in storage
+  and takes its real size from there, not from what you declared, so an early `confirm`
+  answers that the file is not there.
+
+A refusal comes back as `{ error, code }`. Branch on `code` (`invalid_name`, `file_too_large`,
+`quota_exceeded`, `not_uploaded`, `duplicate_name`, `not_found`, …) and never on the text:
+the wording is free to change, the code is not.
+
+What the app may do with files is decided inside that function, because the page in the
+browser can be edited by whoever opened it. Never write the key into the sources and never
+send it to the frontend: the build gate stops on a key found in the application code, and a
+key that reached a visitor lets them delete every file of the project.
+
+## Syncing code
+
+`xflow status` shows how the local copy differs from the server revision.
+`xflow push` sends sources, `xflow pull` fetches them.
+
+If a push is rejected, the server revision is newer, meaning someone pushed first.
+Fetch their work next to yours (`xflow pull --into ./server-copy`), merge it locally,
+then push again. `--force` destroys their work: a last resort, not a way around the
+error.
+
+## Organizations and keys
+
+A key belongs to one organization, and `xflow login` stores it next to the ones already
+stored instead of replacing them. Which key a command uses, in order: `XFLOW_TOKEN` when
+set (default platform address only), then the organization the project folder is bound
+to (`.xflow/state.json`, written by init, link and the first successful push or pull),
+then the active organization. `xflow org` lists the stored organizations with the active
+one marked, `xflow org switch <name|id>` makes another one active without a browser, and
+`xflow whoami` names the organization behind the current key.
+
+Inside a project folder there is nothing to switch: commands follow the folder's own
+organization whatever the active one is, which is what lets two projects of two
+organizations work side by side. Project ids are unique across the platform, so a key of
+the wrong organization can never touch another organization's project: the command fails
+with "not found" instead. When that error names a project you know exists, check
+`xflow org`; signing in to a missing organization is `xflow login`, and that needs a
+person with a browser.
+
+## Direct access without the terminal
+
+The platform also exposes an MCP server, connected with `xflow mcp install`. When its tools
+are available, prefer them for control-plane work: project state, database schema and
+read-only queries, migrations, function logs and invocations, schedules, environment
+variables, versions, publish and rollback. They answer with aggregates and say explicitly
+when a result is truncated, which parsing terminal output does not.
+
+Anything that depends on the working copy stays in the CLI: sending sources (`xflow push`),
+building and shipping the functions (`xflow deploy`), creating a project (`xflow init`). The
+tools cannot see the folder you are working in, so a build started from there would release
+whatever revision the server happens to hold, not what you have on disk. Pulling a repository
+through tool calls also burns the user's tokens for nothing.
+
+## Do not
+
+- Edit `xflow.json` by hand: the CLI writes it.
+- Commit `.env`: it holds the project token.
+- Push with `--force` without checking `xflow status` first.
+- Invent platform commands: what is not in `xflow help` does not exist.
+
+## App design
+
+The platform design system already ships inside the project, and the app is supposed
+to look like a part of the platform:
+
+- `src/components/ui` for primitives: buttons, inputs, dialogs, tables, menus
+- `src/components/blocks` for composed blocks: `data-table` and `charts`
+- `src/index.css` for color tokens
+
+Before writing your own component, check whether a block already covers it: props are
+typed next to each block, larger ones keep a separate `types.ts`. Take colors from
+tokens (`bg-card`, `text-muted-foreground`, `bg-success-soft` and the like). A custom
+hex palette makes the app look foreign inside the platform, which is the whole reason
+the design system sits in the project.
+
+The app runs inside the platform in an iframe and receives the theme and the current
+user from it. The `usePlatformAuth()` hook gives the name, role, permissions and the
+list of organization members. Use it to draw the interface, never to guard data: the
+value lives on the page and is edited from the console. Guard data in the function, by
+`event.xflow`.
+
+## Errors from a deployed app
+
+`xflow logs` prints what broke in the browser on deployed addresses: unhandled errors,
+rejected promises and 5xx responses. The same stream, functions included, is in the
+platform UI: open the project, section «Облако» (Cloud), tab «Логи» (Logs). The last 200
+records per project are kept.
+
+Local `npm run dev` does not report anything: these logs exist for what you cannot open
+in your own devtools.
+
+Cloud functions do work under `npm run dev`, and nothing has to be configured for that:
+the dev server swaps the access key of the logged-in developer for the same narrow pass and
+forwards the call. If it answers that the key is missing, the fix is `xflow login`.
+
+## Environment
+
+`VITE_XFLOW_PROJECT_TOKEN` and `VITE_XFLOW_API_URL` are written by the CLI when the
+project is created, there is no need to edit them by hand. For CI and agent runs:
+`XFLOW_TOKEN` replaces `xflow login`, `XFLOW_API_URL` points at another platform host.