@getxflow/cli 0.19.0 → 0.20.0

package/dist/help.js

@@ -593,9 +593,10 @@ old copy.`,
     init: `${(0, ui_1.bold)('xflow init')} [dir]: a new project
 
 Lays down the platform template: React on Vite, Tailwind, a set of components
-(${(0, ui_1.bold)('src/components/ui')}) and ready-made blocks (${(0, ui_1.bold)('src/components/blocks')}): table,
-form, filters, kanban, charts. Projects created in the web get the same template, which
-is what makes the applications look alike.
+(${(0, ui_1.bold)('src/components/ui')}) and ready-made blocks (${(0, ui_1.bold)('src/components/blocks')}): app
+shell, page header, section, toolbar, list, empty state, stats, detail card, form rows,
+card grid, timeline, table, charts. Projects created in the web get the same template,
+which is what makes the applications look alike.
 
 Building the interface on top of these components and the tokens in ${(0, ui_1.bold)('src/index.css')}
 is not a formality: your own palette on top of them looks foreign inside the platform.

package/dist/session.js

@@ -31,7 +31,11 @@ function connect(config, options) {
         ...(0, credentials_1.storedKeyInputs)(apiUrl),
     });
     if (!picked) {
-        throw new errors_1.CliError(`No access key for ${apiUrl}`, 'Sign in: xflow login. In CI pass the key in the XFLOW_TOKEN variable');
+        throw new errors_1.CliError(`No access key for ${apiUrl}`, 
+        // Who does it, not where the key comes from: the key is issued by the sign-in
+        // itself and by nothing else, so an agent reading this has to hand the step over
+        // instead of hunting for a value to paste.
+        'Sign in: xflow login (needs a person with a browser). In CI pass the key in XFLOW_TOKEN');
     }
     if ('missing' in picked) {
         throw new errors_1.CliError(`This folder is bound to the organization ${picked.organizationId}, and there is no stored key for it`, 'Sign in to that organization: xflow login. The stored ones: xflow org');

package/dist/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
 /** Keep in sync with cli/package.json. */
-exports.CLI_VERSION = '0.19.0';
+exports.CLI_VERSION = '0.20.0';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getxflow/cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -5,15 +5,13 @@ description: Build, deploy and publish apps on the XFlow platform with the xflow
 
 # 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.
+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.
 
-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.
+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.
 
 ## First rule
 
@@ -24,21 +22,17 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.19.0. 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.
+These instructions ship with xflow CLI 0.20.0, 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
-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.
+again the file it names**: refreshing only writes to disk, and until you re-read it you are
+still working from the old rules. Do it yourself, no need to ask.
 
-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.
+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.
 
 ## Hard rules
 
@@ -56,8 +50,9 @@ the error points away from the cause. The sections below carry the details.
    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.
+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
+   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
@@ -65,41 +60,31 @@ the error points away from the cause. The sections below carry the details.
 
 ## Plan limits
 
-The organization runs on a plan with finite limits: projects, databases, cloud functions,
-active connector connections, developer and staff seats, database and file storage,
-function minutes and builds per month, builds running at once, 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.
-
-Two of them deserve a word. A database outlives its project (deleting a project only
-detaches it), so a refused database on a small plan usually means an orphan: the fix is
-deleting the unused database in the "Data" section of the web interface, not renaming
-anything. Connector connections are counted while active: switching an unused connection
-off in the web interface frees the seat without deleting it.
-
-The plan also caps how long one call of a cloud function may run. The cap 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. `xflow whoami` names the plan's
-cap; what a deployed function actually carries is what it was last deployed with.
-
-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.
+The organization runs on a plan with finite 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. `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.
+
+Three of them behave unlike the rest:
+
+- A database outlives its project (deleting a project only detaches it), so a refused
+  database usually means an orphan: delete the unused one in the "Data" section of the web
+  interface.
+- Connections are counted while active: switching an unused one off frees the seat without
+  deleting it.
+- 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.
+
+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
 
@@ -116,16 +101,13 @@ back within an hour of the data going under the limit.
    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.
+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. When a deploy is
-rejected before the build starts, the server holds a version this folder has never seen:
-somebody deployed first, or the folder was linked to a different project along the way.
-Fetch the server work next to yours (`xflow pull --into ./server-copy`), merge it in git,
-deploy again. `--force` destroys that work, a last resort rather than a way around the error.
+`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.
 
 **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
@@ -133,35 +115,29 @@ application the moment it finishes, before any `publish`, and `publish` moves th
 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.
+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.
 
-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: you can read what they were and
-which revision they came from, but you cannot open or roll back to them. The history itself
-holds the **last 30 builds** and the sources the **last 50 revisions** (a revision a live
-version was built from is never deleted). Three builds is the whole rollback depth and on an
-active project it is a matter of hours, so it is not a backup: keep anything you must not
-lose in your own git repository.
+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**, the sources the **last 50 revisions** (a revision a live
+version was built from is never deleted). 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. 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.
+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.
 
 ## 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.
+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:
 
@@ -198,9 +174,9 @@ Interface rules, checked outside `src/components/ui` and `src/components/blocks`
   `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:
+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`,
@@ -225,14 +201,13 @@ A rejection names the file and the revision to take the original from:
 ## 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.
+`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. List what is live with `xflow functions list`. The handler
-returns `{ statusCode, body }` where `body` is a JSON string.
+application, in that order. `xflow functions list` shows what is live. 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
@@ -240,44 +215,32 @@ enforces this, but a project where every function answers its own way costs an a
 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`
-in the project, so look at that file before writing the catch: a copy that declares
-`XFlowError` throws it carrying `code` and `status`, and a copy that says nothing about
-errors is older and throws a plain `Error` whose message is all there is. In an older
-project, a function that wants its error text seen on the page answers `200` with
-`{ success: false, error }` in the body.
-
-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,
-`--data-file body.json` sends the same from a file, `--json` prints the body alone), 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.
-
-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}`, so escape them
-(`--data '{\"a\":1}'`) or pass a file. This is a shell habit, not a bug in the function, and
-it bites `--payload` of a schedule the same way. A command that worked writes nothing to
-stderr, so a red line in PowerShell means it really failed; `--json` prints the payload and
-nothing else.
+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.
+
+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 } })`. 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.
+`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
 
@@ -318,13 +281,12 @@ and `X-Server-Key` with `process.env.XFLOW_SERVER_KEY`. The token is the ticket
 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.
+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 → «Настройки». Ask the user to do
+that and to paste the address back — never invent another way in. Send it in the
+`X-Function-Key` header. A function holds at most two keys, the second one 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
@@ -333,33 +295,29 @@ 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.
+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.
 
 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: 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.
+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.
+
+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`.
+
+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.
 
 `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
@@ -373,11 +331,10 @@ while a function still reads one of the variables, naming those functions, so re
 list before reaching for `--force`. Under `--project` there is no folder to read: it
 prints the variables that go and removes the link.
 
-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. If the right was taken away, say so and
-ask the person to turn it back on where the key permissions live in the platform settings: a key cannot
-grant it to itself. Connecting a new account and switching one off stay with a person too.
+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.
 
 ### Asking an API what it returns
 
@@ -406,10 +363,9 @@ linked or not: an invented name is left in the text as you typed it and the requ
 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.
 
-**Ask for the shape, not the volume.** One day and `limit=1` is enough to learn what the
-fields are called; the answer is printed head first and says when there is more. The whole
-dataset belongs in a cloud function, which is where you were going anyway. `--json | jq
-'.response.body | keys'` gives the field names without the body entering your context at all.
+**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
@@ -457,23 +413,19 @@ You never write that variable yourself: `xflow env set DATABASE_URL=...` is refu
 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, where the key permissions live 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. `xflow db list` names the databases of the
-organization and the projects on each, which is where you find out 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` raises that to 300). The table cuts long values to keep the columns
-readable; `--json` prints them whole. Look before
-you write a migration against a shared database.
+(`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). Look
+before you write a migration against a shared database.
 
 ## File storage
 
@@ -489,29 +441,28 @@ 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.
+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 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.
+`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 (**Delete files**, where the key permissions
-live in the platform settings), 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`.
+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, 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`.
+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
-then sends the bytes straight to storage, and a second call records the file:
+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:
 
 ```js
 const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/upload-url`, {
@@ -527,14 +478,12 @@ const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/uploa
 `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.
+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 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.
+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:
 
@@ -559,28 +508,27 @@ A refusal comes back as `{ error, code }`. Branch on `code` (`invalid_name`, `fi
 `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 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.
+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.
 
 ## 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.
+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.
 
-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. The exception is `--project <id>`, which every command
-that can answer without the working copy takes (`xflow help project` lists them): it ignores
-the folder whole, so a second project needs no second checkout. `projects get` and `link`
-take no flag and name the project by its id as an argument instead.
+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, 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.
+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.
 
 ## Direct access without the terminal
 
@@ -605,18 +553,28 @@ through tool calls also burns the user's tokens for nothing.
 
 ## App design
 
-The platform design system already ships inside the project, and the app is supposed
-to look like a part of the platform:
+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.
 
-- `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
+Screens that read as a product, not as a form:
 
-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.
+- 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.
+- 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