@getxflow/cli 0.10.0 → 0.10.2

package/skills/xflow/SKILL.md

@@ -1,540 +1,552 @@
----
-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`), a name built from an expression, `?.` and
-   spreading the environment all read as no mention of the variable at all. The
-   build rejects them, and `xflow env check` names them before that.
-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: the platform reads
-   the real size from storage, so an early call answers that the file is not there.
-7. Heavy media does not travel with the sources. Photos, video and PDFs go up with
-   `xflow storage push`, not into the repository: the archive is capped at 10 MB.
-
-## 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 pages. The one exception is
-the very first version of a project: it publishes automatically, since there is no
-live version to protect yet.
-
-**Only pages are versioned.** Cloud functions and the database are one per project: they
-are not versioned, and dev and live share them. So `xflow deploy` changes the running
-application the moment it finishes, before any `publish`, and `publish` moves the pages
-only. Tell the user this when a deploy touches `functions/`: there is no staging step for
-server code.
-
-Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>` points
-the project at the pages of an earlier build. Only the pages come back — those pages then
-talk to today's functions. The sources stay on their own revision; fetching the code of
-that build is a separate command (`xflow pull --revision N --into ../old-version`, keep the
-copy outside the project folder). Building that code over the current one is a further,
-deliberate step: it replaces the server revision, needs `--force`, and asks a human to type
-the project name, so you cannot do it on your own.
-
-The platform keeps the **last 30 successful builds**. Older ones are deleted, files and
-history row alike, and rolling back to them stops working. That is rollback depth, not a
-backup of the code: the code lives in revisions (the last 100, and a revision a live
-version was built from is never deleted), and a build is made from a revision again.
-Keep anything you must not lose in your own git repository, not in the version history.
-
-**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.
-- Heavy media does not belong in the sources at all: the archive is capped at 10 MB and
-  the built application at 15 MB unpacked. Upload it with `xflow storage push` instead
-  and refer to the addresses it prints, see **File storage**.
-
-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, never reach the environment through `?.`, and
-never destructure or spread it (`const { API_KEY } = process.env` reads as no mention at all,
-and the variable arrives empty). The build stops on such a read rather than shipping a
-function whose secret silently never arrives. 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
-
-Two kinds of files live here, and they arrive through different doors.
-
-**Static assets of the application you are building** — product photos, video, PDFs, big
-artwork — you upload yourself, from the terminal:
-
-```bash
-xflow storage push ./media --to media   # a folder, its structure kept
-xflow storage ls                        # what is there, with addresses and sizes
-xflow storage ls --json                 # the same for a script, after 300 files
-```
-
-Sources go up as one archive, capped at 10 MB, and the built application has its own cap of
-15 MB unpacked. Those caps are about heavy media, not about code: icons, fonts and small
-artwork the build needs belong in the repository as usual, and an application with hundreds
-of source files is nowhere near them. Everything heavy goes to storage instead, where it is
-metered against the organization plan and is not rebuilt and re-uploaded on every deploy.
-
-`push` prints the address of every file and skips what is already stored under the same path
-and size, so running it again after a broken connection is cheap and quiet. A file whose
-size differs is left alone unless `--replace` is given, and a replacement keeps the address:
-it belongs to the record, not to the bytes, so links in the code and in the tables of the
-application keep working. Put those addresses into the code or into a table; there is no
-command that fetches the files back to a machine.
-
-Deleting needs a right of its own, off by default (**Delete files** in the Developers
-section of the platform), so `xflow storage rm` may answer that the key was not granted it.
-Ask the person to switch it on, and do not look for a way around: whatever the users of the
-application uploaded lives in the same folders, and there is no undo. A folder first tells
-you how many files it holds and deletes them only with `--yes`.
-
-**Files that users of the application upload** go through a cloud function of your own. The
-browser cannot reach storage directly: 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 returned `s3Key` and answers with the file and its address; `delete`
-takes that same `url`. Never pipe the bytes through the function itself.
-
-There is no endpoint that lists files back to a function, so the address that `confirm`
-returns is the only copy this door gives you: write it into a table of your own in the same
-call, and the application reads its files from there.
-
-That address never expires and is safe to store, but it is not a public link. It opens only
-for a visitor who is signed in and has access to this project, the same rule that guards the
-application itself, so it works on your pages and does nothing in an email or on a page
-anyone can open.
-
-Three things bite an upload that otherwise looks right:
-
-- **A name already taken in that folder is refused before the link is issued.** Pass
-  `overwrite: true` to replace the file: the bytes change and the address stays, which is
-  what the pages of the application expect. Without it, give the name a suffix of your own.
-- **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 and content type from there, not from what you declared, so an
-  early `confirm` answers that the file is not there. Send on the PUT the `Content-Type` you
-  named when asking for the link: storage serves the file under the header it received.
-
-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 deploy` sends sources, `xflow pull` fetches them.
-
-If a deploy is rejected before the build starts, the server revision is newer, meaning
-someone deployed first. Fetch their work next to yours (`xflow pull --into ./server-copy`),
-merge it locally, then deploy 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 deploy 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, 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.
-- Deploy 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, file storage and uploads of photos, video or PDFs, connected accounts of external services, 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.
+
+No `xflow.json` means the folder is not bound to a project yet. `xflow projects list`
+names the projects of the organization with their ids, `xflow link <id>` binds the
+folder to one of them (an empty folder also gets the sources), and `xflow init` starts
+a new project from the platform template.
+
+## 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.
+
+## Keeping these instructions current
+
+These instructions ship with xflow CLI 0.10.2. They travel inside the package, so the copy
+you are reading can be older than the CLI answering your commands, and nothing about that
+is visible in the text itself.
+
+When the CLI says this file is out of date, run `xflow skills --refresh` and then **read
+again the file it names**. Refreshing only writes new text to disk; until you re-read it you
+are still working from the old rules, and the command will look like it did nothing. This
+repair is yours to make, no need to ask anyone.
+
+Updating the CLI itself is a different matter and not yours by default. `xflow update`
+replaces a program shared by every project on the machine, and in most installations it
+cannot even do that: it prints the command for a person instead. So when a newer version is
+merely available, finish the task and offer the update in your summary. The one exception is
+a platform refusing to work with the CLI as too old: nothing runs until it is updated, so say
+what you are doing and run it.
+
+## 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`), a name built from an expression, `?.` and
+   spreading the environment all read as no mention of the variable at all. The
+   build rejects them, and `xflow env check` names them before that.
+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: the platform reads
+   the real size from storage, so an early call answers that the file is not there.
+7. Heavy media does not travel with the sources. Photos, video and PDFs go up with
+   `xflow storage push`, not into the repository: the archive is capped at 10 MB.
+
+## 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 schedules and
+how often they may run. `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.
+
+The same output names the rights of your own key, which is the other half of the answer:
+destroying data in a migration, deleting files from storage and linking a connected
+account each need a right that is off by default. Reading that line first turns a refusal
+halfway through the work into a sentence said before it starts.
+
+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.
+
+A schedule refused for running too often is one of these too, not a bad cron string: the
+minimum interval comes from the plan, so widen the interval or say what the plan allows.
+The number is in `xflow whoami`, never guess it.
+
+On `db_write_locked` (hard rule 5) it is Postgres itself refusing, not the platform. Reads
+and deletes keep working, which is what makes a deleting migration the way out. Write comes
+back within an hour of the data going 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. The platform builds again in its own
+   sandbox, on one Node version for everyone, so this is only a fast way to see errors early.
+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 pages. The one exception is
+the very first version of a project: it publishes automatically, since there is no
+live version to protect yet.
+
+`xflow status` says how the local copy differs from the server revision. When a deploy is
+rejected before the build starts, the server revision is newer: somebody deployed first.
+Fetch their work next to yours (`xflow pull --into ./server-copy`), merge it in git, deploy
+again. `--force` destroys their work, a last resort rather than a way around the error.
+
+**Only pages are versioned.** Cloud functions and the database are one per project: they
+are not versioned, and dev and live share them. So `xflow deploy` changes the running
+application the moment it finishes, before any `publish`, and `publish` moves the pages
+only. Tell the user this when a deploy touches `functions/`: there is no staging step for
+server code.
+
+Rolling back: `xflow deployments` lists the history, `xflow rollback <id>` points the project
+at the pages of an earlier build. Only the pages come back, and they then talk to today's
+functions. The code of that build is a separate fetch (`xflow pull --revision N --into
+../old-version`, kept outside the project folder); building it over the current one needs
+`--force` and a human typing the project name, so you cannot do it on your own.
+
+The platform keeps the **last 30 successful builds** and the **last 100 revisions** (a
+revision a live version was built from is never deleted). That is rollback depth, not a
+backup: keep anything you must not lose in your own git repository.
+
+**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.
+
+## Build gate
+
+Before the sandbox starts, the platform checks the sources against the template. Every
+rule below blocks the build, and violations come back together with files and line
+numbers rather than one per attempt: up to fifty of them, and a count when there are
+more. 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 and an entry point at `src/main.tsx` (`.ts`, `.jsx` and `.js`
+  count too).
+- Application code under `src/`. Root `app/`, `pages/`, `next/` are rejected.
+- Heavy media does not belong in the sources at all: the archive is capped at 10 MB and
+  the built application at 15 MB unpacked. Upload it with `xflow storage push` instead
+  and refer to the addresses it prints, see **File storage**.
+
+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` (`index.js` and
+`index.mjs` are read too). The directory name is the name of the function, and the build gate
+is strict about it: lowercase latin letters, digits and hyphens, starting with a letter or a
+digit, up to 41 characters. `send-mail` passes, `sendMail` and `send_mail` do not, and the
+build stops before the sandbox rather than halfway through it.
+
+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. Send it in the `X-Function-Key` header. 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.
+
+## Secrets and connected accounts
+
+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.
+
+These commands see only what this project can see: variables shared across the organization
+and the ones bound to this project. A variable bound to another project is invisible here, so
+`env rm` reports it as missing even though names are unique within the organization.
+
+Why hard rules 1 and 2 are hard rules: a function receives only the variables it mentions by
+name, and the platform reads those names out of the text of the code, so an opaque read ships
+a function whose secret silently never arrives. The build stops on one instead. And a value
+written today reaches the running function on the next `xflow deploy`, not before.
+
+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; `xflow help connections` has the
+naming rules and the flags. 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 on the key, and only accounts granted to the
+owner of the key personally can be linked at all. If the right 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. Connecting a new account and switching one off stay with a person too.
+
+## Schedules
+
+`xflow schedules set report "0 3 ? * * *"` runs a function 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, and `--payload '{"mode":"full"}'`
+is how it gets a body. How often a schedule may run is a plan limit, see **Plan limits**.
+
+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 ? * * *" --payload '{"mode":"full"}'   # 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.
+
+The platform keeps no database history and no backups, so anything that destroys data
+(`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) needs two
+things at once: the `--allow-destructive` flag, and the right to destroy data on the key.
+That right is off by default and only its owner turns it on, under Developers in the
+platform settings. When the refusal is about 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` first.
+
+One logical database can be shared by several projects, so your migration can break an app
+you do not see, and `xflow db status` lists applied migrations that have no file in your
+repository: that is somebody else's project. For the same reason `migrations/` is not the
+schema. It says what you did; `xflow db schema [table]` says what is in the database right
+now, and `xflow db query "select ..."` reads it inside a READ ONLY transaction. Look before
+you write a migration against a shared database.
+
+## File storage
+
+Two kinds of files live here, and they arrive through different doors.
+
+**Static assets of the application you are building** — product photos, video, PDFs, big
+artwork — you upload yourself, from the terminal:
+
+```bash
+xflow storage push ./media --to media   # a folder, its structure kept
+xflow storage ls                        # what is there, with addresses and sizes
+xflow storage ls --json                 # the same list, machine-readable
+```
+
+The caps that send them here (10 MB of sources, 15 MB unpacked) are about heavy media, not
+about code: icons, fonts and small artwork the build needs stay in the repository as usual.
+Everything heavy goes to storage, where it is metered against the organization plan and is
+not re-uploaded on every deploy.
+
+`push` prints the address of every file and skips what is already stored under the same path
+and size, so a repeat run after a broken connection is cheap; `--replace` overwrites a file
+whose size differs. An address belongs to the record rather than to the bytes, so a
+replacement keeps it and the links in your code and tables keep working. Put those addresses
+into the code or into a table: there is no command that fetches files back to a machine.
+
+Deleting needs a right of its own, off by default (**Delete files** in the Developers
+section of the platform), so `xflow storage rm` may answer that the key was not granted it.
+Ask the person to switch it on, and do not look for a way around: whatever the users of the
+application uploaded lives in the same folders, and there is no undo. A folder first tells
+you how many files it holds and deletes them only with `--yes`.
+
+**Files that users of the application upload** go through a cloud function of your own. The
+browser cannot reach storage directly: 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 returned `s3Key` and answers with the file and its address; `delete`
+takes that same `url`. Never pipe the bytes through the function itself.
+
+There is no endpoint that lists files back to a function, so the address that `confirm`
+returns is the only copy this door gives you: write it into a table of your own in the same
+call, and the application reads its files from there.
+
+That address never expires and is safe to store, but it is not a public link. It opens only
+for a visitor who is signed in and has access to this project, the same rule that guards the
+application itself, so it works on your pages and does nothing in an email or on a page
+anyone can open.
+
+Three things bite an upload that otherwise looks right:
+
+- **A name already taken in that folder is refused before the link is issued.** Pass
+  `overwrite: true` to replace the file: the bytes change and the address stays, which is
+  what the pages of the application expect. Without it, give the name a suffix of your own.
+- **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 and content type from there, not from what you declared, so an
+  early `confirm` answers that the file is not there. Send on the PUT the `Content-Type` you
+  named when asking for the link: storage serves the file under the header it received.
+
+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.
+
+## Organizations and keys
+
+One key per organization, stored side by side rather than replacing each other:
+`xflow org` lists them, `xflow org switch <name|id>` changes the active one, and
+`xflow help org` has the precedence rules. Two things are worth knowing without asking.
+
+Inside a project folder there is nothing to switch: commands follow the organization the
+folder is bound to, whatever the active one is. That is what lets two projects of two
+organizations work side by side.
+
+A "not found" on a project you know exists usually means the key belongs to another
+organization, not that the project is gone: ids are unique across the platform, so a
+wrong key can never reach somebody else's project. 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, 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.
+- Deploy 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.