@getxflow/cli 0.34.2 → 1.0.1

package/skills/xflow/SKILL.md

@@ -1,17 +1,18 @@
 ---
 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, UI built on the platform design system, or a public page on xflowpage.ru (a landing page, presentation or invoice for people outside the organization).
+description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever a folder has xflow.json (the project root or an app folder in apps/), and for any task that touches a project and its apps, deployment, publishing, rollback, source sync, who may open an app or call a function, sign-in inside a public app, 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, UI built on the template components, or a public page on xflowpage.ru (a landing page, presentation or invoice for people outside the organization).
 ---
 
 # 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 project is recognized by `xflow.json` in its root.
+Hosting for web apps. The code lives in an ordinary repository on the developer machine, the
+CLI sends the sources, the platform builds them in a clean sandbox, serves each app at its own
+address and runs its backend: one database and cloud functions per project.
 
-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 (an empty
-folder also gets the sources), and `xflow init` starts a new project from the template.
+No `xflow.json` in the folder or above it means it 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 (an empty folder gets the whole project), and `xflow init` starts a new
+project with its first app.
 
 ## First rule
 
@@ -22,7 +23,7 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.34.2, so the copy you are reading can be older than
+These instructions ship with xflow CLI 1.0.1, so the copy you are reading can be older than
 the CLI answering your commands.
 
 When the CLI says this file does not match it, run `xflow skills --refresh` and then **read
@@ -30,9 +31,8 @@ again the file it names**: refreshing only writes to disk, and until you re-read
 still working from the old rules. Do it yourself, no need to ask.
 
 Updating the CLI is not yours. `xflow update` replaces a program shared by every project on
-the machine, and most installations only print the command for a person: offer the update in
-your summary. The exception is a platform refusing the CLI as too old: nothing runs until it
-is updated, so say what you are doing and run it.
+the machine: offer the update in your summary. The exception is a platform refusing the CLI as too old (`outdated_cli`):
+nothing runs until it is updated, so say what you are doing and run it.
 
 ## Hard rules
 
@@ -44,359 +44,424 @@ the error points away from the cause. The sections below carry the details.
    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.
+   `xflow deploy functions`, 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, and `xflow db migrate` refuses a
+   function to go. The next deploy removes it from the cloud together with its keys and
+   schedules, and that is final.
+4. A function an app or a page calls needs that caller in its `callers` in the root
+   `xflow.json`. Without it the call answers 404 `not_bound`, and a new function is not
+   reachable from anywhere.
+5. Every function with a public caller (a page, an app open to anyone) can be called by
+   anybody on the internet with curl. Write it as such, see **Your function is open to the
+   whole internet**.
+6. An already applied migration is never re-run, and `xflow db migrate` refuses a
    name it already holds with different content. A schema change is always a new file.
-5. When inserts start failing with `db_write_locked`, the database is over its plan size
-   and Postgres itself refuses. Reads and deletes keep working, so the fix is a migration
+7. When `xflow db migrate` answers `db_write_locked`, or an INSERT or CREATE TABLE in a
+   function fails with `permission denied` (42501), the database is over its plan size and
+   Postgres itself refuses. Reads, updates and deletes keep working, so the fix is a migration
    that deletes data, never a rewrite of the SQL. Write comes back within the hour.
-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
+8. 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
+## Projects and apps
+
+- A project is a box: one database with its migrations, the cloud functions, secrets and
+  members. It has no code of its own.
+- An app is code the platform builds and serves at `https://<id>--<org>.xflowpage.ru`
+  (`<id>` is six random characters the platform gives the app, `<org>` the name of the
+  organization): its own versions, its own access level. A project holds one or more apps,
+  and all of them use the same database and the same functions.
+- A project without apps is fine (`xflow init --no-app`): its functions are workflows, woken
+  by a schedule, by an outside service holding a key, or by `xflow functions invoke`.
+- `xflow projects get` shows the apps with their folders, addresses and access levels, and
+  who may call each function.
+
+## Folder layout
+
+One folder per project, apps in subfolders:
+
+    clinic/
+      xflow.json                 projectId, and who may call each function
+      package.json               dependencies of the functions
+      functions/<name>/index.ts  cloud functions, shared by every app
+      migrations/0001_init.sql   the one database of the project
+      apps/
+        priem/                   an app: a Vite project with its own xflow.json (appId, build)
+        zapis/
+
+- Two kinds of history: the project root (functions, migrations, `xflow.json`) is one, each
+  app is another. `apps/**` never travels with the root, the root never travels with an app.
+- An app sees only its own folder when it is built. What two apps share is data and logic,
+  and that lives in functions. Functions never go inside an app folder: the build refuses
+  `functions/` there (`functions-in-app`).
+- `xflow apps add <folder>` creates an app, lays the template into `apps/<folder>` and prints
+  its address. Never create an app folder by hand: without its `appId` it is nobody's.
+  `--color <color>` sets the tile the user sees in the project; a wrong one is answered with
+  the list of colors. Its icon and a later color change belong to the person in the web
+  interface.
+- Rename an app folder freely: the app is its `appId`.
+- Commands follow the folder you stand in: inside `apps/zapis` they mean that app, anywhere
+  else in the project they mean the project. `--project <id>` and `--app <id>` name them
+  without a folder.
+- Neither `xflow.json` is edited by hand except `functions.<name>.callers` in the root one.
 
-The organization runs on a plan with limits: projects, databases, functions, active
-connections, seats, database and file storage, function minutes, builds per month and at
-once, schedules and how often they may run. Most are finite; a plan may leave one uncapped,
-and then `whoami` prints `no limit` instead of a ceiling. `xflow whoami` prints every one of
-them next to what is used, and the rights of your own key with them: destroying data in a migration,
-deleting files from storage and linking a connected account each need a right that is off by
-default. Reading it before a long task turns a refusal halfway through the work into a
-sentence said before it starts.
+## Plan limits
 
-Two of them behave unlike the rest:
+The organization runs on a plan with limits: apps, functions, pages, active connections,
+seats, database and file storage, function minutes, builds per month and at once, schedules
+and how often they may run, and which access levels an app may have. Most are finite; a plan
+may leave one uncapped, and then `whoami` prints `no limit` instead of a ceiling.
+`xflow whoami` prints every one of them next to what is used, and the rights of your own key
+with them: destroying data in a migration, deleting files from storage, moving a database and
+linking a connected account each need a right. Reading it before a long task turns a refusal
+halfway through the work into a sentence said before it starts.
 
 - Connections are counted while active: switching an unused one off frees the seat without
   deleting it.
+- Function minutes are shared by the whole organization: every app, page and schedule spends
+  them. When they run out, every function of the organization stops (`functions_stopped`).
 - The cap on how long one function call may run is written into the function when it is
-  deployed, so a plan change reaches the cloud only with the next `xflow deploy` of each
-  project, in both directions.
+  deployed, so a plan change reaches the cloud only with the next `xflow deploy functions` of
+  each project, in both directions.
 
 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`), MCP tools
 carry the same field. Retrying, renaming or rewriting the code changes nothing: tell the user
-what ran out and stop, only the owner or an admin lifts it. A schedule refused for running too
-often is one of these too, not a bad cron string: the minimum interval comes from the plan,
-never guess it.
-
-## 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 -m "what changed"` 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. The comment is required: one short line in the language the
-   user speaks, it names this version in the history.
-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: until `publish` runs, visitors keep seeing the previous pages. The
-one exception is the very first version of a project, which publishes automatically.
-
-`xflow status` says how the local copy differs from the server revision. A deploy rejected
-before the build starts means the server holds a version this folder has never seen: somebody
-deployed first, or the folder was linked elsewhere. Fetch it next to yours (`xflow pull --into
-./server-copy`), merge in git, deploy again. `--force` destroys that work. A folder with no
-record of the server revision (a fresh clone, a CI checkout) is not rejected: its first deploy
-goes on top of the current revision and says so, the check applies from the next one.
-
-**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 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 a human.
-
-Bringing the code back instead of the pages: `xflow deploy --revision N -m "what came back"`
-builds a revision the platform already holds. Nothing goes up, so no copy of that code is needed
-next to you and the newest revision stays the newest. It is the only way back for a standalone
-function, which has no pages to return, and it needs no folder at all: `--project <id>` names the
-project. Functions that exist now but not in that revision are removed, with the usual question.
-
-Pages are kept for the **three latest successful builds** plus whatever dev and live show;
-older versions stay in the history with `pages_kept` false, readable but not openable. The
-history holds the **last 30 builds**, each keeping the revision it was built from; any other
-revision is kept only while it is among the **10 latest**. Three builds is the whole rollback
-depth, hours on an active project: 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: a build address has the version baked into it and
-after the next publish keeps answering with the old copy, so whoever holds it stares at a
-frozen app and concludes nothing shipped. The project page always shows the current state.
+what ran out and stop, only the owner lifts it. A schedule refused for running too often is one
+of these too, not a bad cron string: the minimum interval comes from the plan, never guess it.
+
+## Deploying
+
+1. Change the code. In an app folder `npm run typecheck` is a two-second check, `npm run build`
+   a fast way to see build errors early: the platform builds again in its own sandbox.
+2. `xflow db migrate` when the schema changes. It stores the project root first (migrations
+   live in its history), then applies what is new.
+3. `xflow deploy functions -m "what changed"` sends the project root, checks it, ships the
+   functions and their callers. Every app runs the new code the moment it finishes: there is
+   no staging and no publish step for server code. Say so to the user.
+4. `xflow deploy apps/zapis -m "what changed"` sends and builds one app; inside `apps/zapis` a
+   plain `xflow deploy` does the same. In the root a plain `xflow deploy` refuses and names the
+   targets. The comment is required: one short line in the language the user speaks.
+5. `xflow publish` in the app folder (or with `--app <id>`) shows that build to visitors.
+
+A change that touches data and screens goes in this order: the migration, the functions, then
+every app that shows it. `xflow deploy apps/...` warns when the root holds changes nobody
+deployed.
+
+- A build of an app is not shown to visitors until `xflow publish`. Publishing points the
+  address at a build and takes a second; `xflow publish <number>` (or `xflow rollback <number>`)
+  points it at an older kept build, and that is the rollback. The very first build of a new
+  app publishes itself.
+- Only the app moves on publish and rollback. Functions come back with
+  `xflow deploy functions --revision N -m "why"` (`xflow deployments functions` lists the revisions);
+  `--project <id>` names the project without a folder.
+- Files of the **three latest successful builds** of each app are kept, plus the live one;
+  `xflow deployments` marks the rest `no pages`. The history keeps 30 builds, a revision stays
+  while its build is in it or it is among the 10 latest. Keep anything you must not lose in
+  your own git repository.
+- Give a person the app address the CLI printed, or the project page it printed. Name builds
+  by their number.
+- `xflow status` says how the local copies differ from the server. A deploy rejected before
+  the build starts means the server holds a revision this folder has never seen: fetch it next
+  to yours (`xflow pull --into ./server-copy`), merge in git, deploy again. `--force` destroys
+  that work. A folder with no record of the server revision (a fresh clone, a CI checkout) is
+  not rejected: its first deploy goes on top and says so.
+- A deploy that would delete functions gone from the sources refuses until somebody agrees;
+  `--allow-removals` is the only way past it without a terminal. Reaching for it to get a
+  build running means you deleted something the user never asked you to: put the directories
+  back. If the removal is intended, name the functions and let the user answer.
 
 ## 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, up to
-fifty at a time. A rejected attempt costs nothing, the sandbox never starts. Write code that
-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**.
-- Every file in the project is named with latin letters, digits, spaces and `. - _ ~`.
-  A name outside that set does not survive unpacking in the build sandbox, so `Größe.png`
-  and `логотип.png` break the build the same way. This is about the file name, not its
-  contents: interface text stays in whatever language the application speaks.
-
-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.
+Before the sandbox starts, the platform checks the sources. Everything below blocks the build,
+all violations come back together with files and lines, and a rejected attempt costs nothing.
+
+An app:
+
+- `package.json` with the build script named in its `xflow.json` (`npm run build` by default),
+  a `vite.config.*` and `vite` in dependencies. No server frameworks: `next`, `nuxt`, Remix,
+  `@sveltejs/kit`, `astro`.
+- `index.html` in the app root with `id="root"` and the script that loads `src/main.tsx`
+  (`.ts`, `.jsx`, `.js` count too). Code under `src/`; root `app/`, `pages/`, `next/` are rejected.
+- Keep `base` in `vite.config.js` as the template has it: the platform serves each build from
+  `/_b/<key>/`, and a build whose `index.html` points elsewhere is refused.
+- The built app at most 15 MB unpacked, the sources at most 10 MB.
+- File names in latin letters, digits, spaces and `. - _ ~` only: `логотип.png` breaks the build.
+- Call functions through `xflow.functions.invoke`, never a hardcoded function address.
+- No keys or tokens in the sources, no server modules (`fs`, `express`, `http`, `child_process`).
+- Outside `src/components/ui` and `src/components/blocks`: no `alert()`, `confirm()`,
+  `prompt()` (use Dialog and Toast), no `console.log` (visitors read the console;
+  `console.error` and `console.warn` reach the logs).
 - 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. Part of the platform 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.
+  `react-hot-toast`, `react-dnd`) must have it mounted. A missing provider builds fine and
+  gives visitors a white screen.
+- The platform files stay byte for byte as they arrived: `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`. The code keeps calling `initPlatformAuth()`
+  and `initErrorLogger()` and importing `index.css`, and the Tailwind
+  `content` globs keep covering `src/**`. A rejection names the revision to take the original
+  from: `xflow pull --revision N --into ./original`, then copy the file back.
+
+The project root: function names are lowercase latin letters, digits and hyphens, up to 41
+characters (`send-mail`, not `sendMail`); every name under `functions` in `xflow.json` has its
+`functions/<name>/index.ts`; every caller is an app folder of this project or an existing page
+of the organization (`unknown-caller`).
+
+Passes with a line `Unfinished:` instead of blocking: the template's page title, no
+`<link rel="icon">` in `index.html`, an `exports.access` left in a function (it does nothing).
+Fix the first two before you tell the person the app is done.
+
+## The template is a starter kit
+
+- `src/components/ui` and `src/components/blocks` are a starting set: change them, restyle them
+  or delete what you do not use. Any colors, your own color scheme, inline styles, a single
+  theme without dark mode: all allowed.
+- The template looks like the xflow interface: warm grays, hairline controls (`ctl-solid`,
+  `ctl-raised`, `ctl-inset`, `ctl-select`), segments (`seg-track`, `seg-on`) and surfaces
+  (`surface-raised`, `surface-pop`, `surface-modal`) in `src/index.css`.
+- While any template component is left, the theme token names in `:root` of `src/index.css`
+  and their `hsl(var(--name))` mapping in the Tailwind config stay: those components paint with
+  them. Values change freely; they are HSL components (`216 95% 40%`), not `#hex`. Your own
+  colors go under new names.
+- Images and other assets: import them from `src/` (`import logo from './assets/logo.png'`)
+  so the build puts them next to the code. An absolute path into `public/` (`/logo.png`) goes
+  through the access check of the app and fails inside the xflow frame in Safari.
+
+## Who opens an app
+
+A person sets this in the web interface; you cannot, and you should not ask for a way around.
+
+| Level | Who gets in |
+|---|---|
+| Project members | people who have access to the project: the team through xflow, staff with a login |
+| By list | the members named for this app |
+| Anyone with the link | anybody, no sign-in at all |
+
+- The plan decides which levels exist: on Free an app opens only inside xflow, Start adds the
+  direct address and "By list", Business adds "Anyone with the link".
+- At the two closed levels the platform signs people in, and a function receives the person in
+  `event.xflow.user` (`id`, `role` in the organization, `name`, `login`).
+- Staff (a doctor, a picker) never sign in to xflow: an admin gives them a login and a password,
+  they enter at the address of the app, `login` is set for them and null for the team. Keep
+  roles inside the app (doctor, receptionist) in your own table keyed by `user.id`.
+- A "Sign out" button: `const r = await fetch('/_xflow/logout', { method: 'POST' })`, then
+  `location.href = (await r.json()).next`. It ends every sign-in of the person.
+- At "Anyone with the link" the platform signs nobody in: `event.xflow.user` is null for
+  visitors. Accounts, sign-in and who sees which rows are the code of your app, see below.
+- `usePlatformAuth()` in the frontend knows the person only inside the xflow frame, and even
+  there it is a hint for drawing the interface, edited from the console by anyone. On the
+  direct address it answers `anonymous`. Guard data in the function, by `event.xflow`.
+
+## Which functions an app may call
+
+The root `xflow.json` names the callers of each function:
+
+    {
+      "projectId": "…",
+      "functions": {
+        "list-slots": { "callers": ["zapis", "priem"] },
+        "book-slot":  { "callers": ["zapis", "clinic-landing"] }
+      }
+    }
+
+- A caller is an app folder of this project (`apps/zapis` is `"zapis"`) or the address name of
+  a page of the organization (`clinic` for `clinic.xflowpage.ru`). A function without callers is
+  left out of `functions` or given `"callers": []`, the same thing.
+- A function nobody lists has no callers: no app and no page reaches it. That is a workflow,
+  run by a schedule, a key or `xflow functions invoke`.
+- Callers ship with `xflow deploy functions` and come back with its `--revision N`.
+- The app calls `xflow.functions.invoke('book-slot', { body })` from `src/lib/xflow.ts`. The call
+  goes to `/_fn/book-slot` on the app's own address: no function addresses, tokens or keys in
+  the bundle, nothing to rebuild when a function changes.
+- A refusal throws `XFlowError` with `status` and `code`: `not_bound` (404, add the caller and
+  deploy functions), `not_found` (404, the function is not deployed), `login_required` and
+  `invalid_credential` (401, the visitor has to sign in again), `no_access`, `role_too_low`,
+  `functions_stopped` (403, minutes ran out or the plan is unpaid: a person settles it),
+  `rate_limited` (429), `unavailable` (503, retry later). Branch on `code`, never on the message.
+- A page has to exist before a function can name it: create the page, then deploy functions.
+
+## Your function is open to the whole internet
+
+A function is open when any of its callers is public: a page (always) or an app at "Anyone
+with the link". `xflow deploy functions` says so in a line of its own, `xflow functions list`
+prints `open`, the web interface marks it.
+
+Open means anybody can call it with curl, without your page: the browser is not a gate.
+Hiding the address, checking `Origin` or `Referer`, a token baked into the bundle: all of it is
+readable or forgeable and protects nothing. Write every open function as if the request came
+from a stranger, because it may:
+
+- Check every input: types, lengths, allowed values; refuse fields you do not expect. Put input
+  into SQL as parameters only (`$1`), never into the text.
+- Return only what this caller needs: no `select *` into a response, no rows of other people,
+  no internal fields, no stack traces.
+- Make writes safe to repeat: take a request id from the client and put a unique index on it,
+  so a retry or a replay changes nothing.
+- Deduplicate and limit per visitor where it costs: `event.xflow.ip` is the visitor's address,
+  set by the platform proxy and not by the caller. The proxy caps requests per address; the
+  organization pays for every minute a function runs.
+- A form open to strangers needs a captcha: Cloudflare Turnstile, with the token checked in the
+  function against `https://challenges.cloudflare.com/turnstile/v0/siteverify` and the secret
+  from `xflow env set`. The site key is public and stays in the source. A check in the browser
+  checks nothing.
+- `minRole` on an open function refuses every anonymous visitor (`login_required`): use it only
+  where members call.
+
+## Sign-in in a public app
+
+At the closed levels do none of this: the platform already knows the person.
+
+- Passwords: store only a hash, `crypto.scrypt` from Node with a random salt per user, compare
+  with `crypto.timingSafeEqual`. Never log a password, never return it, never keep it in the
+  browser.
+- Session: after sign-in the function makes a random token (`crypto.randomBytes(32)`), stores
+  its SHA-256 and an expiry in a table and returns it as a cookie in its response headers:
+  `Set-Cookie: __Host-sid=…; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=…`. The `__Host-`
+  prefix stops a neighbouring `*.xflowpage.ru` site from planting its own `sid`. `/_fn` is on
+  the same address, so the browser sends it back by itself. Not `localStorage`: every script on
+  the page reads it.
+- Not the `Authorization` header: `/_fn` replaces it with the platform's own. Nor headers named
+  `X-Xflow-*`, `X-Project-Pass`, `X-Server-Key`, `X-Function-Key`: the platform strips them.
+  Cookies reach the function as they are.
+- Every function that serves a signed-in visitor reads the cookie from `event.headers`, finds
+  the session and filters rows by that user in SQL. A hidden button is not access control.
+- Count failed sign-ins per email and per `event.xflow.ip` in a table and slow them down.
+- Never in the frontend: keys, secrets, the list of users, hashes, a role check that is the only
+  guard.
+- The platform sends no email for your app: confirmation and reset letters need a mail provider
+  whose key goes into `xflow env set`.
+- `xflow dev` carries neither cookies nor `Set-Cookie`, and calls functions as you (a member).
+  Try the sign-in on the app address.
+
+## Page or app
+
+- A page is finished static files at `https://<name>.xflowpage.ru`: public, live the moment it
+  is uploaded, no build, no publish step, no database. A landing page, a presentation, an invoice.
+- An app is source the platform builds: versions and publish, access levels, a database through
+  functions. Anything people sign in to, enter data into or come back to.
+- A form open to strangers on a plan without "Anyone with the link" is a page: pages are public
+  on every plan.
+- Keep the sources of a page outside the project folder, or list them in `.xflowignore`: the
+  root travels with `deploy functions`.
+- A page that needs a backend (a form, a lookup) calls `/_fn/<name>` on its own address with the
+  header `X-Xflow-Fn: 1` (without it 403 `bad_request`), and a function of a project answers only
+  when its callers name the page. The function is then open. A refusal carries its code in
+  `reason` of the JSON body, the same codes as above.
 
 ## 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.
-
-There is no separate deploy command: `xflow deploy` ships the functions and then builds the
-application, in that order. `xflow functions list` shows what is live. The handler returns
-`{ statusCode, body }` where `body` is a JSON string.
-
-A function that belongs to no single application is created on its own: `xflow init <dir>
---function` makes a project without a site, with one handler and no template. The function name
-comes from the project name, or from the folder when the project name is not latin. It is a shared
-backend of the organization, and any application of that organization calls it; who is let in
-is decided by `minRole` inside the function. Deploy builds and releases it the same way, but it
-has no pages, so `xflow publish` and `xflow rollback` do not apply; an earlier version comes back
-with `xflow deploy --revision N`. It counts against the plan
-limit of functions, not of applications. Put a function here when it serves several
-applications, a bot or a webhook; a function serving one application belongs in that project.
-
-An application calls it like its own: `xflow.functions.invoke('<name>')`, the platform puts the
-address into the map the bundle carries. Two things follow from that map. An application sees a
-newly created standalone function only after its own `xflow deploy`, and a function of the
-project always wins a name it shares with a standalone one: the deploy names such a name in its
-output, and the shared function stays unreachable from that project until one of them is
-renamed. Such a call carries a person: a server key of another project opens the functions of
-its own project only.
-
-Inside a standalone function, remember who can reach it: any member of the organization,
-including someone whose access to projects is narrowed to one folder. The role in `minRole` is
-the role in the organization, so a function holding data that is not for everyone checks the
-caller itself (`event.xflow.user`).
-
-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.
-
-How a non-2xx answer reaches the page depends on the generation of `src/lib/xflow.ts`, so read
-that file before writing the catch: a copy declaring `XFlowError` throws it with `code` and
-`status`, an older copy throws a plain `Error` whose message is all there is. In an older
-project, a function whose error text must be seen answers `200` with `{ success: false, error }`.
-
-The sources are the whole truth about which functions exist: a deleted directory takes the
-function and its schedules out of the cloud, undoably, and a function created again later gets
-a different address. Such a deploy refuses until somebody agrees, and `--allow-removals` is the
-only way past it. Reaching for that flag to get a build running means you deleted something the
-user never asked you to delete: put the directories back. If the removal is intended, name the
-functions 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}'`, `--data-file body.json`,
-`--json` for the body alone), and `xflow functions logs <name>` shows the failures with stacks
-and console output. Only failed calls are logged, so empty output means it never crashed.
+`functions/<name>/index.ts` in the project root exports `handler` (`index.js` and `index.mjs`
+are read too), `export const handler` and `exports.handler` both work. The request arrives as
+`event.httpMethod`, `event.headers`, `event.queryStringParameters` and `event.body`, a string
+(`JSON.parse` it; `event.isBase64Encoded` marks a binary body). The handler returns
+`{ statusCode, body }` where `body` is a JSON string, and may add `headers`.
+`xflow functions list` shows status, callers, `open`, keys, last call and last error.
+
+- Dependencies (`pg`, a mail client) go into the root `package.json`; the platform installs them
+  on every deploy, and a lock file next to it makes that exact.
+- Code shared by functions lives in a root folder such as `lib/`, imported by relative path: each
+  function is bundled with what it imports. A folder in `functions/` without `index.*` is not a
+  function. Read `process.env` in `functions/<name>/` itself: `xflow env check` looks only there.
+
+Keep one shape inside that string across the project: `{ success: true, data }` when it worked,
+`{ success: false, error: { message, code } }` when it did not. Branch the frontend on
+`error.code`, never on `error.message`.
+
+A function whose code and variables did not change is not shipped again, and one that fails to
+ship fails the whole deploy.
+
+Debugging a deployed function is two commands: `xflow functions invoke <name>` calls it as you,
+through the platform, and prints status, timing and body (`--data '{"a":1}'`, `--data-file
+body.json`, `--method GET`, `--json` for the body alone); `xflow functions logs <name>` shows
+the crashes and 5xx answers with stacks and console output, the latest 10 (`--limit N` for more).
+Only failed calls are logged. Empty output does not clear a function that fails at module start,
+runs over its time cap or out of memory: those never reach the logs, `invoke` shows them.
 
 The body has to be JSON and the CLI checks it before calling. In PowerShell the double quotes
 never reach the CLI (`--data '{"a":1}'` arrives as `{a:1}`): escape them (`--data '{\"a\":1}'`)
 or pass a file. It bites `--payload` of a schedule the same way. A command that worked writes
 nothing to stderr, so a red line there means it really failed.
 
-From the app, call a function through `src/lib/xflow.ts`:
-`await xflow.functions.invoke('send-mail', { body: { to } })`, which carries the credentials for
-you. Addresses are baked into the build, which is why functions go out first: by the time the
-bundle is built they already exist.
-
 ### Who is calling
 
-A function answers a member of the organization who has access to that project, an outside
-service holding a key of that function, and, when the code opens it, anyone at all. 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`:
+The platform checks every call before your code runs and hands the answer over 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),
-  //         'public' (anyone, see below)
-  // user:   { id, role } for a visitor, null for everything else
+  const { caller, slug, user, ip } = event.xflow
+  // caller: 'app' (an app of this project), 'page', 'service' (another function of this
+  //         project), 'external' (an outside service with a key), 'schedule',
+  //         'platform' (a person through xflow functions invoke or the web interface)
+  // slug:   the address name of the calling app (<id>--<org>) or page, null otherwise
+  // user:   { id, role, name, login } of a signed-in person (login only for staff),
+  //         null for anonymous visitors, pages, keys
+  // ip:     the visitor's address, null for a schedule
 }
 ```
 
-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.
+Never trust an identity that arrives in the body or in a header of the request: the page lives
+on someone else's computer. `event.xflow` is the only identity the platform stands behind.
 
-A function that changes data should say so instead of checking the role by hand:
+A function that changes data should say who may call it instead of checking the role by hand:
 
 ```js
 exports.minRole = 'developer'   // 'member' | 'developer' | '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 payment webhook, 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 → «Настройки»; a standalone
-function has a screen of its own, «Функции» → the function → «Настройки». Ask the user to do
-that — never invent another way in. The service sends the key in the `X-Function-Key` header
-to the address `xflow functions list` prints. A function holds at most two keys, the second
-one to replace the first without downtime, not to serve a second consumer.
-
-A function behind a public page (a form on a landing, a lookup, a calculator on
-`xflowpage.ru`) has neither a person nor a key: every visitor calls it. Declare that in the
-code and nothing else is needed, no key, no setting, nobody to ask:
-
-```js
-exports.access = 'public'
-```
-
-The wrapper then lets a call without any credential through, with `caller: 'public'` and
-`user: null`, and never asks the platform. The page calls the address from `xflow functions
-list` directly (CORS is open) and bakes no key into its files. Everything else stays as it
-is: a call that does carry a pass or a key is still checked. Use it only for a function whose
-work is fine for anyone on the internet to trigger: it cannot hold `minRole`, and it must not
-write or delete data on the caller's word, there is no caller to trust. The platform marks
-such a function «Открыта всем»
-in the interface, and removing the line and deploying closes it again.
-
-`xflow functions list` shows who can reach each function: `in-app only` (answers only inside
-the application), `external (N keys)` (a human issued external access), `public` (the code
-opened it), and the address of every deployed function. Key values are never shown there.
-Under the table it names the standalone functions of the organization this project calls by
-the same name, each with the `--project` id its code lives in: that list and the table
-together are everything `xflow.functions.invoke` reaches from here. A deploy prints the
-address of every function it left open, so a page needs no second command to find it.
+The platform refuses anything below that role before your code runs; it applies to people
+(apps, pages, `functions invoke`), not to keys and schedules. `member` is the people who only
+use the apps (staff of a clinic, managers), `developer` and `owner` build them. Without the line
+every member of the project can call the function. Losing access
+closes the function within a minute.
+
+- Another function of the project: `fetch(`${process.env.XFLOW_FN_URL}/<name>`, { headers:
+  { 'X-Server-Key': process.env.XFLOW_SERVER_KEY } })`. The key opens the functions of its own
+  project only, whatever their callers.
+- An outside service (a payment webhook, a bot, a CRM) calls
+  `https://fn.xflowpage.ru/<projectId>/<name>` (`xflow functions list` prints it) with a key of
+  that function in `X-Function-Key` or `?key=`. Keys are issued by a person on the function's
+  screen in the web interface, never by you: ask the user. A function holds at most two keys,
+  the second one to replace the first without downtime.
+- `exports.access` does nothing any more: who may call is `callers`.
 
 ## 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` names the 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.
+inside the running function. Apps get no variables at all.
 
 A variable goes to the whole organization unless you say otherwise: `--scope project` keeps it
-to this project alone, `--scope organization` is the default, and a third word is refused
-rather than read as the default. Pick the narrow one for anything that belongs to one
-application.
-
-These commands see only what this project can see: organization-wide variables and the ones
-bound to this project. One bound to another project is invisible here, so `env rm` reports it
-missing even though names are unique within the organization.
+to this project alone, `--scope organization` is the default, and a third word is refused.
+Pick the narrow one for anything that belongs to one project. These commands see only what
+this project can see, so `env rm` reports a variable of another project missing even though
+names are unique within the organization.
 
-Hence hard rules 1 and 2: 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 would ship a function
-whose secret never arrives. A value written today rides the next `xflow deploy`.
+`DATABASE_URL` and every name starting with `XFLOW` are filled in by the platform: writing them
+is refused.
 
 Some variables come from a connected account instead of from you. Credentials of an account
 linked to the project 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,
-`xflow env set` on those names is refused. If calls to that service start failing on
-authorisation, `xflow status` 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 reconnect.
+time (`YANDEX_DIRECT_TOKEN`, `YANDEX_DIRECT_CLIENT_LOGIN`): read them like any other variable.
+If calls to that service start failing on authorisation, `xflow status` says whether the token
+is merely expiring (any deploy of the functions renews it) or the account was disconnected on
+the provider's side, which only a human can reconnect.
 
-`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` lists those accounts: the ones 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.
 
 `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. In the project folder unlink reads `functions/` and refuses
-while a function still reads one of the variables, naming those functions, so read that
-list before reaching for `--force`. Under `--project` there is no folder to read: it
-prints the variables that go and removes the link.
+`xflow connections unlink YANDEX_METRIKA` undoes it; `xflow help connections` has the naming
+rules. In the project folder unlink refuses while a function still reads one of the variables,
+naming 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; the same right covers calling an unlinked account.
-A key cannot grant it to itself, so ask the person to turn it back on where the key permissions
-live. Connecting a new account and switching one off stay with a person too.
+of the key personally can be linked at all. A key cannot grant it to itself: ask the person.
+Connecting a new account and switching one off stay with a person too.
 
 ### Asking an API what it returns
 
-Before writing a function against an unfamiliar API, find out what it actually answers:
-
 ```
 xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
 xflow connections call "Яндекс Метрика" /management/v1/counters
@@ -404,58 +469,41 @@ xflow connections call OZON /v1/product/list --method POST --data '{}' \
     --header '{"Client-Id":"{CLIENT_ID}"}'
 ```
 
-The platform attaches the credentials and makes the request itself, so no deploy is needed and
-the key never reaches you. A linked account is called by its alias, an `available, not linked`
-one by its name: **linking first is not needed to look**, so do not ask a person about that.
-
-**Calling is looking, not wiring**: no variable reaches the functions because you called
-something. To use the account in code, link it and deploy.
-
-Two refusals do need a person, and different ones: `connections:link` right — the owner of the
-key grants it where the key permissions live; `not granted to you` — ask whoever connected the account.
-
-`{NAME}` in the path or in a header value is filled in from the fields of the connection.
-**Take the names from `xflow connections`**, which prints them in braces for every account,
-linked or not: an invented name is left in the text as you typed it and the request goes out
-anyway, into somebody's live account. `xflow env` is not that list. Only the hosts of that
-connector are reachable and a refusal lists them.
+The platform attaches the credentials and makes the request itself: no deploy, and the key never
+reaches you. A linked account is called by its alias, an `available, not linked` one by its
+name: linking first is not needed to look. Calling is looking, not wiring: to use the account
+in code, link it and deploy functions.
 
-**Ask for the shape, not the volume.** One day and `limit=1` is enough to learn what the fields
-are called, and the whole dataset belongs in a cloud function anyway. `--json | jq
-'.response.body | keys'` gives the field names without the body entering your context.
-
-The call goes out for real, against a live account: `POST` and `DELETE` change things there,
-and nothing undoes that. Read the method of the endpoint before calling it, and ask the
-person first when the endpoint is not clearly a read.
+`{NAME}` in the path or in a header value is filled in from the fields of the connection. Take
+the names from `xflow connections`, which prints them in braces: an invented name is left in the
+text and the request goes out anyway, into somebody's live account. Ask for the shape, not the
+volume: one day and `limit=1`; `--json | jq '.response.body | keys'` gives the field names
+without the body entering your context. `POST` and `DELETE` change things in a live account and
+nothing undoes that: ask the person first when the endpoint is not clearly a read.
 
 ## 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"}'`
-(or `--payload-file body.json`) is how it gets a body. The payload has to be JSON: a broken one
-is refused when the schedule is set, not at three in the morning with nobody watching. 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:
+and exactly one of day-of-month / day-of-week must be `?`. A run reaches the handler as a POST
+with `event.xflow.caller === 'schedule'`, and `--payload '{"mode":"full"}'` (or
+`--payload-file body.json`) is its body. The function has to be deployed first.
 
 ```
-xflow env set SMTP_PASSWORD=...            # secrets first: values ride the next deploy
+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 -m "Nightly report function"  # 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
+xflow deploy functions -m "Nightly report"
+xflow schedules set report "0 3 ? * * *" --payload '{"mode":"full"}'
+xflow functions invoke report                   # run it once
+xflow functions logs report                     # crashes of real runs
 ```
 
 ## 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, and the database can be shared with other
-projects of the organization, so a migration name is taken once for all of them: `migrate`
-refuses a name that is already applied with different content. Never edit an applied file,
-write a new migration instead.
+Schema changes are files: `migrations/0001_init.sql`, `migrations/0002_orders.sql` in the
+project root, applied in filename order by `xflow db migrate` from any folder of the project.
+`xflow db status` shows what is applied and what waits. Never edit an applied file, write a new
+migration instead. Every project has exactly one database of its own, shared by all its apps and
+functions.
 
 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:
@@ -465,102 +513,71 @@ 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 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.
+
+`migrations/` says what you did; `xflow db schema [table]` says what is in the database now, and
+`xflow db query 'select ...'` reads it inside a READ ONLY transaction (50 rows by default,
+`--limit` up to 300; `--json` prints long values whole). Single quotes hold in PowerShell, bash
+and zsh, cmd.exe wants double ones; a query with quotes of its own goes in a `.sql` file outside
+the project, `xflow db query ../q.sql`.
 
 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 both the
 `--allow-destructive` flag and the right to destroy data on the key, which is off by default and
 only its owner turns on. When the refusal is about the right, 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`.
-
-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 with no file in your repository (that is
-somebody else's project), and `xflow db list` names who else is on yours. 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 (50 rows by default, `--limit` up to 300; `--json` prints long values whole). Single
-quotes hold in PowerShell, bash and zsh, while cmd.exe wants double ones; a query that needs
-quotes of its own goes in a `.sql` file outside the project, `xflow db query ../q.sql`, because
-PowerShell strips double quotes from arguments. Look before you write a migration against a shared database.
-
-An organization can have own database servers, several of them for different jobs. `xflow db
-list` names the server of each database (`platform` is the common one) and lists the own servers
-with the room used; `xflow db status` names the one under this project. The server belongs to the
-database: projects sharing a database share its server.
-- A new project with its database on a chosen server: `xflow init --server <name>` (`platform`
-  for the common one). Without it the first migration creates the database on `platform`.
-- An existing database: `xflow db move --to <name> --confirm <database name>`. Writes to every
-  project on it close while it copies, usually a couple of minutes; the platform switches the
-  functions itself, no deploy. It needs the right to move databases, off on the key by default:
-  refused for the right, say what should move where and why, and the person turns it on or
-  moves it in the "Data" section.
-- Buying, paying for and deleting servers are the person's, in the web interface. There is no
-  limit on how many. If a database has outgrown its server, say so and suggest buying one.
-
-Code stays the same: `DATABASE_URL` arrives as before, pass it as is, without an `ssl` option (an
-own server is reached over a closed network, and `ssl` makes the connection fail). While an own
-server is not running, migrations and queries say so and functions that use the database time
-out. That is not your code and not yours to fix: tell the person, who sees the server state in
-the "Data" section of the web interface, instead of retrying.
+dumped first (up to 50 000 rows each) and kept for 7 days; getting a dump back is a request to
+the person, no command does it. Check with `--dry-run`.
+
+An organization can have own database servers. `xflow db list` names the server of each project
+database (`platform` is the common one) and the own servers with the room used.
+- A new project with its database on a chosen server: `xflow init --server <name>`.
+- An existing one: `xflow db move --to <name> --confirm <project name>`. Writes close while it
+  copies, usually a couple of minutes; the platform switches the functions itself. It needs the
+  right to move databases, off on the key by default: refused for the right, say what should move
+  where and why, and the person turns it on or moves it in the «Базы данных» (Databases) section.
+- Buying, paying for and deleting servers are the person's, in the web interface.
+
+Code stays the same on an own server: pass `DATABASE_URL` as is, without an `ssl` option. While
+an own server is not running, migrations and queries say so and functions that use the database
+time out: tell the person instead of retrying.
 
 An own server comes tuned and guarded, so do not tune it from migrations:
-- Installed from the start: `pgcrypto`, `pg_trgm`, `unaccent`, `citext`, `btree_gin`,
-  `btree_gist`, `pg_stat_statements`. Use them, do not `CREATE EXTENSION` them again. UUIDs
-  need no extension anywhere: `gen_random_uuid()` is built in, and on an own server so is
-  `uuidv7()`. Never `uuid-ossp`. Anything else (`postgis`, `pgvector`) is a request to the
-  person, not a migration.
-- Limits on every connection: a statement is cut after 30 seconds, waiting for a lock after 3,
-  a transaction left open after 30. A query that needs longer is a wrong query (an index is
-  missing, or it is a report that belongs in a scheduled function writing a summary table). A
-  migration that needs longer is split into smaller ones. The one exception is a scheduled job
-  that genuinely needs more: it runs `SET statement_timeout = '5min'` on its own connection,
-  and nowhere else. A database that used `citext` or another extension type cannot move back to
-  `platform`: the move refuses, the common server has no such extensions.
-- A restart happens on a plan change and takes about a minute. Create the `Client` inside the
-  handler, or keep a `Pool` at module level: a `Client` created at module level dies with the
-  restart and stays dead until the function cold-starts.
+- Installed: `pgcrypto`, `pg_trgm`, `unaccent`, `citext`, `btree_gin`, `btree_gist`,
+  `pg_stat_statements`. `gen_random_uuid()` is built in everywhere, `uuidv7()` on an own server.
+  Never `uuid-ossp`. Anything else (`postgis`, `pgvector`) is a request to the person.
+- A statement is cut after 30 seconds, waiting for a lock after 3, a transaction left open after
+  30. A query that needs longer is a wrong query (a missing index, or a report that belongs in a
+  scheduled function writing a summary table). A scheduled job that genuinely needs more runs
+  `SET statement_timeout = '5min'` on its own connection. A database that used `citext` or
+  another extension type cannot move back to `platform`.
+- A restart on a plan change takes about a minute. Create the `Client` inside the handler, or
+  keep a `Pool` at module level: a `Client` created at module level dies with the restart.
 
 ## 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:
+**Static assets of an app** (product photos, video, PDFs, big artwork) you upload yourself:
 
 ```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 stay in the repository as usual. Everything heavy
-goes to storage, metered against the organization plan and not re-uploaded on every deploy.
+`push` prints the address of every file (`/_files/<id>`) and skips what is already stored under
+the same path and size; `--replace` overwrites a file whose size differs and keeps its address.
+Use the address as is inside an app: the app's own host serves it to whoever may open the app,
+including anonymous visitors of a public one. Icons, fonts and small artwork stay in the
+repository.
 
-`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 existing links keep working. Put those addresses into the code or into a table: nothing
-fetches files back to a machine.
+Deleting needs a right of its own, off by default, so `xflow storage rm` may answer that the key
+was not granted it. Ask the person and do not look for a way around: whatever the users of the
+app uploaded lives in the same folders, and there is no undo. A folder is
+`xflow storage rm --folder <path> --yes`.
 
-Deleting needs a right of its own, off by default (**Delete files**, where the key permissions
-live), 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 says 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,
-which the platform puts into the environment of your functions as `XFLOW_SERVER_KEY` and
-nothing else holds — 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
-sends the bytes straight to storage, and a second call records the file:
+**Files that users of the app upload** go through a cloud function of your own: it asks the
+platform for a one-time link, the browser 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`, {
@@ -573,168 +590,109 @@ const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/uploa
 }).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.
-
-No endpoint lists files back to a function, so the address `confirm` returns is the only copy
-this door gives you: write it into a table of your own in the same call.
-
-That address never expires and is safe to store, but it is not public: it opens only for a
-signed-in visitor with access to this project, the same rule that guards the application itself,
-so it works on your pages and does nothing in an email.
-
-Four 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 exactly the
-  `Content-Type` you named when asking for the link: the link is signed for that header, a
-  different or missing type gets 403, and storage serves the file under it.
-- **Storage takes application assets, not code.** Images, documents, data files, audio,
-  video, fonts and archives pass; pages, scripts and executables (`html`, `js`, `exe`, …)
-  are refused with `forbidden_type` when the link is requested. Both the extension and the
-  declared `content_type` are checked. Application code travels through `xflow deploy`, not
-  through storage.
-
-A refusal comes back as `{ error, code }`. Branch on `code` (`invalid_name`, `file_too_large`,
-`quota_exceeded`, `not_uploaded`, `duplicate_name`, `forbidden_type`, `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 can be edited
-by whoever opened it. Never send the key to the frontend: the build gate stops on a key found in
-the sources, and a key that reached a visitor deletes every file of the project.
+`confirm` takes the returned `s3Key` and answers with the file and its address; `delete` takes
+that same `url`. No endpoint lists files back, so write the address into a table of your own in
+the same call. What a visitor may do with files is decided inside that function; never send the
+key to the frontend.
+
+- A name already taken in that folder is refused before the link is issued; `overwrite: true`
+  replaces the bytes and keeps the address.
+- 200 MB per file and the storage quota of the organization, checked again on `confirm`.
+- Confirm only after the PUT has finished, and send on the PUT exactly the `Content-Type` you
+  named: the link is signed for it, a different or missing type gets 403.
+- Assets only: pages, scripts and executables (`html`, `js`, `exe`, …) are refused with
+  `forbidden_type`.
+
+A refusal comes back as `{ error, code }` (`invalid_name`, `file_too_large`, `quota_exceeded`,
+`not_uploaded`, `duplicate_name`, `forbidden_type`, `not_found`, …): branch on `code`.
 
 ## Pages
 
-A page is a public static site at `https://<name>.xflowpage.ru`: a landing page, a
-presentation, an invoice for people outside the organization. Anyone with the address opens it,
-without signing in and outside the platform. A project is the opposite, it opens only inside the
-platform: pick a page when the audience is outside the organization.
+A page is a public static site at `https://<name>.xflowpage.ru`, outside projects. Anyone with
+the address opens it, without signing in.
 
 - `xflow pages create "Price list" ./dist` makes a page with the built site on it and prints its
   address: there are no empty pages. `--slug price-list` picks the name, otherwise it comes from
   the title with a random tail.
 - `xflow pages deploy <page> <folder|.zip|.html> -m "what changed"` uploads a new version.
-- **Both are public the moment the command finishes**: no draft, no publish step. Upload when the
-  user wants the page out, and give them the address the CLI printed.
+- **Both are public the moment the command finishes**: no draft, no publish step.
 - `xflow pages status <page>` lists the versions, `xflow pages rollback <page> <N>` puts one back
   in seconds; the files of the last 5 are kept.
-- Static files only: HTML, CSS, JS, images, fonts, PDF, audio, video. No server code, database
-  or functions on a page. Upload what the build writes (`dist`), never a folder with
-  `package.json`. At most 5 MB zipped, 25 MB unpacked, 1000 files.
-- Everything a page shows travels inside the page. File storage of a project is not an
-  option: its addresses open only for a signed-in member with access to that project, so in a
-  page they give a visitor nothing. Heavy media has to fit those caps or be hosted elsewhere,
-  and that is worth saying before a landing page is designed around a video.
-- A page that needs a backend (a form, a lookup) calls a cloud function of a project that
-  declares `exports.access = 'public'` (see «Who is calling»): the page fetches the address
-  from `xflow functions list` directly, with no key and no header. The function lives in a
-  project, the page does not: deploy the function first, then upload the page.
-- Everything in a page is readable by every visitor. Never put a key, token or password into
-  it: a known key format gets the upload refused, anything else simply leaks.
-- Search engines are asked not to index pages: do not promise SEO.
-- The tab icon is the platform's on every page: the upload drops any `<link rel="…icon…">` the
-  files carry and puts the XFlow one in. Do not spend a request on a favicon of your own.
+- `xflow pages rm <page> --yes` deletes the page: the address goes empty and every version is
+  gone for good, without `--yes` the command names what goes and stops. The name stays reserved
+  for the organization. A page put up to try something out is yours to take down when you are
+  done: do not leave it standing.
+- Names are 3-40 characters. At most 100 pages per organization, 20 new and 200 uploads a day,
+  10 seconds between uploads of one page: batch changes into one upload.
+- Static files only, what the build writes (`dist`), never a folder with `package.json`. At most
+  5 MB zipped, 25 MB unpacked, 1000 files. Everything a page shows travels inside it: project
+  file storage does not serve pages.
+- A backend for a page: see **Page or app**.
+- Everything in a page is readable by every visitor. A known key format gets the upload refused,
+  anything else simply leaks.
+- Search engines are asked not to index pages or apps: do not promise SEO.
+- The tab icon is the platform's on every page: do not spend a request on a favicon of your own.
 - The MCP `pages` tool uploads one self-contained HTML document up to 150 KB.
-- Pages take the key of the whole organization, the one `xflow login` issues; a key scoped to
-  projects is refused, and that refusal is not yours to fix. Switching a page off and deleting it
-  are for a person, in the platform interface.
+- A page is deleted by whoever made it, or by the owner of the organization. Switching a page
+  off for a while is for a person, in the platform interface.
 
 ## 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, `xflow help org` has the
-precedence rules.
+One key per organization, stored side by side: `xflow org` lists them, `xflow org switch
+<name|id>` changes the active one, `xflow help org` has the precedence rules.
 
-Inside a project folder there is nothing to switch: commands follow the organization the folder
-is bound to, whatever the active one is, which is what lets projects of two organizations work
-side by side. The exception is `--project <id>`, taken by every command that can answer without
-the working copy (`xflow help project` lists them): it ignores the folder whole, so a second
-project needs no second checkout. `projects get` and `link` name the project by id as an
-argument instead.
-
-A "not found" on a project you know exists usually means the key belongs to another
-organization: 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.
+Inside a project folder commands follow the organization the folder is bound to, whatever the
+active one is. `--project <id>` and `--app <id>` ignore the folder whole (`xflow help project`
+lists the commands that take them). A "not found" on a project you know exists usually means the
+key belongs to another organization: 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.
+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, variables, app builds and
+publish. They say explicitly when a result is truncated.
 
-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.
+Anything that depends on the working copy stays in the CLI: sending sources, building apps and
+deploying functions (`xflow deploy`), creating projects and apps (`xflow init`,
+`xflow apps add`). The tools cannot see your folder. Access levels, function keys, money and
+people are set by a person in the web interface.
 
 ## 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.
+- Ask for a way to change an app's access level or issue a function key: that is the person's.
 
 ## App design
 
-The platform design system ships inside the project, and the app should look like a part
-of the platform:
-
-- `src/components/ui` — primitives: buttons, inputs, dialogs, tables, menus
-- `src/components/blocks` — composed blocks: app shell, page header, section, toolbar with
-  filters, list, empty state, stats, detail card, form rows, card grid, timeline, table,
-  charts. Props are typed next to each block
-- `src/index.css` — colour tokens
-
-Take a block before writing your own layout, and colours from tokens (`bg-card`,
-`text-muted-foreground`, `bg-success-soft`): a custom hex palette makes the app look
-foreign inside the platform.
-
-Screens that read as a product, not as a form:
-
-- Every screen starts with `Page` and `PageHeader`; header, filters and content in one column.
-- Draw all four states: loading, error, empty, data. An empty screen says what appears here and offers an action.
+- Take a block from `src/components/blocks` or a primitive from `src/components/ui` before
+  writing your own layout; replace or delete them when the design needs something else.
+- Every screen starts with a clear header; header, filters and content in one column.
+- Draw all four states: loading, error, empty, data. An empty screen says what appears here and
+  offers an action.
 - Colour only when it communicates: status, action, error, success. Grey carries the structure.
 - Density over air: people scan and compare. Numbers in a column, `tabular-nums`.
 - Name the shape first: list, list with detail, dashboard, form, board.
 - Seed 5-10 believable rows in the first migration: a screen with zero rows looks unfinished.
-- Squint at the result: if the hierarchy blurs away, it is decoration, not structure.
-
-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`.
+- Give the app its own page title and icon.
 
 ## 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.
-
-A local run does not report anything: these logs exist for what you cannot open in your
-own devtools.
+`xflow logs` prints what broke in the browser on the app addresses: unhandled errors, rejected
+promises and 5xx responses; in an app folder that app, in the project root every app.
+`xflow functions logs` prints function crashes. A person sees the same in the web interface:
+browser errors in the «Ошибки» (Errors) panel of the app, function crashes on the «Ошибки» tab
+of the function's screen. The last 200 records of each stream are kept.
 
-Run the app locally with `xflow dev`, not a bare `npm run dev`: it hands the dev server
-the key of the project's organization, which cloud functions need to answer, and their
-current addresses, including functions someone else deployed. A bare `npm run dev` gets
-no key at all, so its function calls fail whatever the error says. The server answers
-`127.0.0.1` alone, because it holds that key: a phone on the same network cannot open it,
-and neither can anybody else on that network.
+Run an app locally with `xflow dev` in its folder, not a bare `npm run dev`: every `/_fn/<name>`
+call then goes to the platform as this app, with the same callers and access as on its address,
+and a function someone else deployed answers at once. A bare `npm run dev` has no key, so its
+function calls fail. The server answers `127.0.0.1` alone, because it holds that key. A local
+run reports nothing to the logs.
 
 ## 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.
+For CI and agent runs: `XFLOW_TOKEN` replaces `xflow login`, `XFLOW_API_URL` points at another
+platform host. There is no `.env` from the platform: the bundle carries no tokens or addresses.