@getxflow/cli 0.9.1 → 0.10.1

package/skills/xflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xflow
-description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever the project root has xflow.json or VITE_XFLOW_* variables, and for any task that touches deployment, publishing, rollback, source sync, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, production errors and logs, or UI built on the platform design system.
+description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever the project root has xflow.json or VITE_XFLOW_* variables, and for any task that touches deployment, publishing, rollback, source sync, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, file storage and uploads of photos, video or PDFs, connected accounts of external services, production errors and logs, or UI built on the platform design system.
 ---
 
 # XFlow
@@ -10,6 +10,11 @@ machine, `xflow deploy` sends the sources, and the platform builds them in a cle
 sandbox and serves the result as static files. A platform project is recognized by
 the `xflow.json` file in its root.
 
+No `xflow.json` means the folder is not bound to a project yet. `xflow projects list`
+names the projects of the organization with their ids, `xflow link <id>` binds the
+folder to one of them (an empty folder also gets the sources), and `xflow init` starts
+a new project from the platform template.
+
 ## First rule
 
 Check commands and flags against `xflow help` and `xflow help <command>`, not against
@@ -17,9 +22,23 @@ memory. If a command is not in the help output, it does not exist: guessing flag
 pointless. The CLI prints a hint with almost every error, read it in full, it usually
 contains the fix.
 
-When the CLI says a newer version is out, or refuses to work because the platform wants
-a newer one, run `xflow update`. It also rewrites these instructions, which ship inside
-the package: what you are reading may be older than the platform you are working on.
+## Keeping these instructions current
+
+These instructions ship with xflow CLI 0.10.1. They travel inside the package, so the copy
+you are reading can be older than the CLI answering your commands, and nothing about that
+is visible in the text itself.
+
+When the CLI says this file is out of date, run `xflow skills --refresh` and then **read
+again the file it names**. Refreshing only writes new text to disk; until you re-read it you
+are still working from the old rules, and the command will look like it did nothing. This
+repair is yours to make, no need to ask anyone.
+
+Updating the CLI itself is a different matter and not yours by default. `xflow update`
+replaces a program shared by every project on the machine, and in most installations it
+cannot even do that: it prints the command for a person instead. So when a newer version is
+merely available, finish the task and offer the update in your summary. The one exception is
+a platform refusing to work with the CLI as too old: nothing runs until it is updated, so say
+what you are doing and run it.
 
 ## Hard rules
 
@@ -39,15 +58,22 @@ the error points away from the cause. The sections below carry the details.
    nothing. A schema change is always a new file.
 5. When inserts start failing with `db_write_locked`, the database is over its plan
    size. The fix is a migration that deletes data, never a rewrite of the failing SQL.
-6. In file storage, call `confirm` only after the PUT has finished, and send the same
-   `Content-Type` in both calls. Both mistakes answer 200 and break later.
+6. In file storage, call `confirm` only after the PUT has finished: the platform reads
+   the real size from storage, so an early call answers that the file is not there.
+7. Heavy media does not travel with the sources. Photos, video and PDFs go up with
+   `xflow storage push`, not into the repository: the archive is capped at 10 MB.
 
 ## Plan limits
 
 The organization runs on a plan with finite limits: projects, cloud functions, developer
-and staff seats, database and file storage, function minutes per month, plus the right to
-use schedules. `xflow whoami` prints every one of them next to what is already used, and
-reading it before a long task is cheaper than hitting a wall mid-way.
+and staff seats, database and file storage, function minutes per month, plus schedules and
+how often they may run. `xflow whoami` prints every one of them next to what is already
+used, and reading it before a long task is cheaper than hitting a wall mid-way.
+
+The same output names the rights of your own key, which is the other half of the answer:
+destroying data in a migration, deleting files from storage and linking a connected
+account each need a right that is off by default. Reading that line first turns a refusal
+halfway through the work into a sentence said before it starts.
 
 A limit refusal is not a bad request. The CLI prints a line starting with `Plan limit:`,
 the API answers `code: "forbidden"` with a `limit` object (`code`, `used`, `limit`), and
@@ -55,17 +81,21 @@ MCP tools carry the same field. Retrying the command, renaming things or rewriti
 code changes nothing: tell the user what ran out and stop. Only the owner or an admin
 lifts it, in the web interface, by freeing the resource or moving to a bigger plan.
 
-One refusal looks like a code error but is not: when the database is over its plan size,
-Postgres itself rejects inserts (`db_write_locked`). Reads and deletes still work, so the
-fix is a migration that deletes data, never a rewrite of the failing SQL. Write is
-restored within an hour of the data going back under the limit.
+A schedule refused for running too often is one of these too, not a bad cron string: the
+minimum interval comes from the plan, so widen the interval or say what the plan allows.
+The number is in `xflow whoami`, never guess it.
+
+On `db_write_locked` (hard rule 5) it is Postgres itself refusing, not the platform. Reads
+and deletes keep working, which is what makes a deleting migration the way out. Write comes
+back within an hour of the data going under the limit.
 
 ## Workflow
 
 1. Change the code.
 2. `npm run typecheck` for a two-second type check (older projects may not have the
    script, then `npx tsc --noEmit`).
-3. `npm run build` if the change is substantial, before deploying.
+3. `npm run build` if the change is substantial. The platform builds again in its own
+   sandbox, on one Node version for everyone, so this is only a fast way to see errors early.
 4. `xflow deploy` sends the sources, ships the cloud functions and builds the application
    on the platform, printing each phase and the six-digit number of the version it built.
 5. Give the user the project link the CLI printed and let them look. Do not open a
@@ -77,25 +107,26 @@ Until `publish` runs, visitors keep seeing the previous pages. The one exception
 the very first version of a project: it publishes automatically, since there is no
 live version to protect yet.
 
+`xflow status` says how the local copy differs from the server revision. When a deploy is
+rejected before the build starts, the server revision is newer: somebody deployed first.
+Fetch their work next to yours (`xflow pull --into ./server-copy`), merge it in git, deploy
+again. `--force` destroys their work, a last resort rather than a way around the error.
+
 **Only pages are versioned.** Cloud functions and the database are one per project: they
 are not versioned, and dev and live share them. So `xflow deploy` changes the running
 application the moment it finishes, before any `publish`, and `publish` moves the pages
 only. Tell the user this when a deploy touches `functions/`: there is no staging step for
 server code.
 
-Rolling back: `xflow deployments` lists the version history, `xflow rollback <id>` points
-the project at the pages of an earlier build. Only the pages come back — those pages then
-talk to today's functions. The sources stay on their own revision; fetching the code of
-that build is a separate command (`xflow pull --revision N --into ../old-version`, keep the
-copy outside the project folder). Building that code over the current one is a further,
-deliberate step: it replaces the server revision, needs `--force`, and asks a human to type
-the project name, so you cannot do it on your own.
+Rolling back: `xflow deployments` lists the history, `xflow rollback <id>` points the project
+at the pages of an earlier build. Only the pages come back, and they then talk to today's
+functions. The code of that build is a separate fetch (`xflow pull --revision N --into
+../old-version`, kept outside the project folder); building it over the current one needs
+`--force` and a human typing the project name, so you cannot do it on your own.
 
-The platform keeps the **last 30 successful builds**. Older ones are deleted, files and
-history row alike, and rolling back to them stops working. That is rollback depth, not a
-backup of the code: the code lives in revisions (the last 100, and a revision a live
-version was built from is never deleted), and a build is made from a revision again.
-Keep anything you must not lose in your own git repository, not in the version history.
+The platform keeps the **last 30 successful builds** and the **last 100 revisions** (a
+revision a live version was built from is never deleted). That is rollback depth, not a
+backup: keep anything you must not lose in your own git repository.
 
 **The only link you give a person is the project page**, `https://app.getxflow.com/projects/<id>`,
 which the CLI prints for you. Refer to builds by their number ("version 481203 is built,
@@ -105,25 +136,25 @@ and after the next publish it does not break, it keeps answering with the old co
 holding that link then stares at a frozen app and concludes the changes never shipped. The
 project page always shows the current state, and every version is reachable from it.
 
-The platform builds the project itself, in a clean sandbox with one Node version for
-everyone, and serves the result as static files. Nothing is built on your machine for
-deployment, so a local `npm run build` is only a fast way to see errors early.
-
 ## Build gate
 
 Before the sandbox starts, the platform checks the sources against the template. Every
-rule below blocks the build, and the whole list of violations comes back at once, with
-files and line numbers. Nothing is charged for a rejected attempt: the sandbox never
-starts. Write code that already satisfies these rules instead of learning them from
-rejections.
+rule below blocks the build, and violations come back together with files and line
+numbers rather than one per attempt: up to fifty of them, and a count when there are
+more. Nothing is charged for a rejected attempt, the sandbox never starts. Write code
+that already satisfies these rules instead of learning them from rejections.
 
 Build setup:
 
 - `package.json` with the build script named in `xflow.json` (`npm run build` by default).
 - Vite: a `vite.config.*` and `vite` in dependencies.
 - No server frameworks: `next`, `nuxt`, `remix`, `@sveltejs/kit`, `astro`.
-- `index.html` in the root, `src/main.tsx` as the entry point.
+- `index.html` in the root and an entry point at `src/main.tsx` (`.ts`, `.jsx` and `.js`
+  count too).
 - Application code under `src/`. Root `app/`, `pages/`, `next/` are rejected.
+- Heavy media does not belong in the sources at all: the archive is capped at 10 MB and
+  the built application at 15 MB unpacked. Upload it with `xflow storage push` instead
+  and refer to the addresses it prints, see **File storage**.
 
 Platform contract, checked across all of `src/`:
 
@@ -174,10 +205,15 @@ 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`. 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.
+Server-side code lives in `functions/<name>/index.ts` and exports `handler` (`index.js` and
+`index.mjs` are read too). The directory name is the name of the function, and the build gate
+is strict about it: lowercase latin letters, digits and hyphens, starting with a letter or a
+digit, up to 41 characters. `send-mail` passes, `sendMail` and `send_mail` do not, and the
+build stops before the sandbox rather than halfway through it.
+
+There is no separate deploy command: `xflow deploy` ships the functions and then builds the
+application, in that order. List what is live with `xflow functions list`. The handler
+returns `{ statusCode, body }` where `body` is a JSON string.
 
 Keep one shape inside that string across the whole project: `{ success: true, data }`
 when it worked, `{ success: false, error: { message, code } }` when it did not. Nothing
@@ -252,24 +288,29 @@ An outside service (a webhook from a payment provider, a bot, a CRM) has no pers
 and needs a key of that one function. Keys are not issued by default and the CLI cannot
 create one: a human issues it in the project settings: «Облачные функции» → the function →
 «Настройки». Ask the user to do that and to paste the address back to you — never invent
-another way in. A function holds at most two keys, and the second one exists to replace the
-first without downtime, not to serve a second consumer.
+another way in. Send it in the `X-Function-Key` header. A function holds at most two keys,
+and the second one exists to replace the first without downtime, not to serve a second
+consumer.
 
 `xflow functions list` shows who can reach each function: `in-app only` (no keys, answers
 only inside the application) or `external (N keys)` (a human issued external access). Key
 values are never shown there.
 
+## Secrets and connected accounts
+
 Keys and passwords live on the platform, not in the repository: `xflow env set SMTP_PASSWORD=…`
 writes one, `xflow env` lists the names, `xflow env check` tells you which variables your
 functions read but the platform does not have. Values never come back out — the only place
 they exist is inside the running function.
 
-A function receives only the variables it mentions by name via `process.env.NAME`, so never
-assemble a variable name from an expression, never reach the environment through `?.`, and
-never destructure or spread it (`const { API_KEY } = process.env` reads as no mention at all,
-and the variable arrives empty). The build stops on such a read rather than shipping a
-function whose secret silently never arrives. New values arrive on the next `xflow deploy`,
-not at the moment they are written.
+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
@@ -286,23 +327,22 @@ alias and the state of the access, and the ones the organization has but this pr
 not use yet, marked `available, not linked`. Check it before telling anyone a service is
 unavailable: the account you need is often connected already, one link away.
 
-`xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA` is that link, and
-`xflow connections unlink YANDEX_METRIKA` undoes it. Name the connection the way the list
-does, in its first column, or by its identifier; unlink also takes the alias, which your
-own code already knows. If two accounts of the same service share a name, the command
-prints their identifiers instead of guessing. Unlink refuses while a function still reads
-one of the variables and names those functions, so read that list before reaching for
-`--force`.
+`xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA` is that link and
+`xflow connections unlink YANDEX_METRIKA` undoes it; `xflow help connections` has the
+naming rules and the flags. Unlink refuses while a function still reads one of the
+variables and names those functions, so read that list before reaching for `--force`.
+
+Linking needs the `connections:link` right on the key, and only accounts granted to the
+owner of the key personally can be linked at all. If the right was taken away, say so and
+ask the person to turn it back on in the platform settings under Developers: a key cannot
+grant it to itself. Connecting a new account and switching one off stay with a person too.
 
-Linking needs the `connections:link` right, which keys are issued with. If it was taken
-away, say so and ask the person to turn it back on in the platform settings under
-Developers: a key cannot grant it to itself. Only accounts granted to the owner of the key
-personally can be linked at all. Connecting a new account and switching one off stay with a
-person too.
+## Schedules
 
-To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
-Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
-how Yandex wants it. A scheduled run reaches the handler as a POST with no headers.
+`xflow schedules set report "0 3 ? * * *"` runs a function daily at 03:00. Six fields, UTC,
+and exactly one of day-of-month / day-of-week must be `?` — that is how Yandex wants it.
+A scheduled run reaches the handler as a POST with no headers, and `--payload '{"mode":"full"}'`
+is how it gets a body. How often a schedule may run is a plan limit, see **Plan limits**.
 
 The pieces line up in one pass. From a new function to a verified schedule:
 
@@ -310,7 +350,7 @@ The pieces line up in one pass. From a new function to a verified schedule:
 xflow env set SMTP_PASSWORD=...            # secrets first: values ride the next deploy
 # write functions/report/index.ts, reading process.env.SMTP_PASSWORD literally
 xflow deploy                               # ships the function, then builds the app
-xflow schedules set report "0 3 ? * * *"   # after the deploy: a schedule needs a deployed function
+xflow 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
 ```
@@ -336,41 +376,55 @@ You never write that variable yourself: `xflow env set DATABASE_URL=...` is refu
 `xflow env rm DATABASE_URL`. The same goes for every name starting with `XFLOW`: the platform
 fills those in itself, and your value under one of them would shadow the real one.
 
-`env` commands reach only what this project can see: variables shared across the organization
-and the ones bound to this project. A variable bound to a different project is invisible here,
-so `env rm` reports it as missing even though names are unique within the organization.
-
-The platform keeps no database history and no backups. Anything that destroys data
-(`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) is refused
-unless two things hold at once: you pass `--allow-destructive`, and the access key carries
-the right to destroy data. That right is off by default and only its owner can turn it on,
-in the platform settings, under Developers. So when a destructive migration is refused for
-the right rather than the flag, adding the flag changes nothing: say what needs deleting and
-why, and let the person decide. With both in place the affected tables are dumped first and
-kept for 7 days. Check with `--dry-run` before applying.
+The platform keeps no database history and no backups, so anything that destroys data
+(`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) needs two
+things at once: the `--allow-destructive` flag, and the right to destroy data on the key.
+That right is off by default and only its owner turns it on, under Developers in the
+platform settings. When the refusal is about the right rather than the flag, adding the flag
+changes nothing: say what needs deleting and why, and let the person decide. With both in
+place the affected tables are dumped first and kept for 7 days. Check with `--dry-run` first.
 
 One logical database can be shared by several projects, so your migration can break an app
-you do not see. `xflow db status` lists applied migrations that have no file in your
-repository: that is what someone else's project did.
-
-For the same reason the `migrations/` directory is not the schema. It says what you did;
-`xflow db schema` says what is in the database right now, and `xflow db schema <table>` gives
-the columns of one table. `xflow db query "select ..."` reads data, inside a READ ONLY
-transaction, so a write there fails by design rather than by accident. Look before you write
-a migration against a shared database.
+you do not see, and `xflow db status` lists applied migrations that have no file in your
+repository: that is somebody else's project. For the same reason `migrations/` is not the
+schema. It says what you did; `xflow db schema [table]` says what is in the database right
+now, and `xflow db query "select ..."` reads it inside a READ ONLY transaction. Look before
+you write a migration against a shared database.
 
 ## File storage
 
-Sources go up as one archive, capped at 10 MB. That cap is about heavy media, not about
-code: an app with hundreds of files is nowhere near it. Icons, fonts and small artwork the
-build needs belong in the repository as usual. Photos, video, PDFs and anything a user
-uploads belong in file storage, which is metered against the organization plan and is not
-rebuilt and re-uploaded on every deploy.
+Two kinds of files live here, and they arrive through different doors.
+
+**Static assets of the application you are building** — product photos, video, PDFs, big
+artwork — you upload yourself, from the terminal:
+
+```bash
+xflow storage push ./media --to media   # a folder, its structure kept
+xflow storage ls                        # what is there, with addresses and sizes
+xflow storage ls --json                 # the same list, machine-readable
+```
+
+The caps that send them here (10 MB of sources, 15 MB unpacked) are about heavy media, not
+about code: icons, fonts and small artwork the build needs stay in the repository as usual.
+Everything heavy goes to storage, where it is metered against the organization plan and is
+not re-uploaded on every deploy.
 
-The project has file storage, and the browser cannot reach it. Those endpoints take only the
-server key of the project, and the platform puts it into the environment of your cloud
-functions as `XFLOW_SERVER_KEY`. Nothing else holds it: not the bundle, not `.env`, not
-`xflow env`.
+`push` prints the address of every file and skips what is already stored under the same path
+and size, so a repeat run after a broken connection is cheap; `--replace` overwrites a file
+whose size differs. An address belongs to the record rather than to the bytes, so a
+replacement keeps it and the links in your code and tables keep working. Put those addresses
+into the code or into a table: there is no command that fetches files back to a machine.
+
+Deleting needs a right of its own, off by default (**Delete files** in the Developers
+section of the platform), so `xflow storage rm` may answer that the key was not granted it.
+Ask the person to switch it on, and do not look for a way around: whatever the users of the
+application uploaded lives in the same folders, and there is no undo. A folder first tells
+you how many files it holds and deletes them only with `--yes`.
+
+**Files that users of the application upload** go through a cloud function of your own. The
+browser cannot reach storage directly: those endpoints take only the server key of the
+project, and the platform puts it into the environment of your cloud functions as
+`XFLOW_SERVER_KEY`. Nothing else holds it: not the bundle, not `.env`, not `xflow env`.
 
 So uploading is a function of your own. It asks the platform for a one-time link, the browser
 then sends the bytes straight to storage, and a second call records the file:
@@ -386,35 +440,30 @@ const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/uploa
 }).then((r) => r.json())
 ```
 
-`confirm` takes the same fields plus the returned `s3Key` and answers with the file and its
-address; `delete` takes that same `url`. Never pipe the bytes through the function itself.
+`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 the files back, so the address that `confirm` returns is the
-only copy you get: write it into a table of your own in the same call, and the application
-reads its files from there.
+There is no endpoint that lists files back to a function, so the address that `confirm`
+returns is the only copy this door gives you: write it into a table of your own in the same
+call, and the application reads its files from there.
 
 That address never expires and is safe to store, but it is not a public link. It opens only
 for a visitor who is signed in and has access to this project, the same rule that guards the
 application itself, so it works on your pages and does nothing in an email or on a page
 anyone can open.
 
-Four things bite an upload that otherwise looks right, and none of them is obvious from the
-answers you get:
-
-- **The content type can quietly split in two.** Nothing checks that the `Content-Type` the
-  browser sends on the PUT matches the one you named in `upload-url`: both calls answer 200.
-  But storage keeps the header the browser sent and serves the file under it, while the
-  record keeps the one you named, so a card can say `image/png` about a file every browser
-  treats as HTML. Send the same string in both calls and they cannot drift.
-- **The same name in the same folder is refused.** Names are unique per folder, so a second
-  `avatar.png` fails instead of replacing the first. Give the name a suffix of your own, or
-  delete the old file before confirming the new one.
+Three things bite an upload that otherwise looks right:
+
+- **A name already taken in that folder is refused before the link is issued.** Pass
+  `overwrite: true` to replace the file: the bytes change and the address stays, which is
+  what the pages of the application expect. Without it, give the name a suffix of your own.
 - **The limits are 200 MB per file and the storage quota of the organization.** The quota is
   checked again on `confirm`, by the real size, which means a refusal can land after the
   bytes are already up; the platform then removes the object and your table stays clean.
 - **Confirm only after the PUT has finished.** The platform looks the object up in storage
-  and takes its real size from there, not from what you declared, so an early `confirm`
-  answers that the file is not there.
+  and takes its real size and content type from there, not from what you declared, so an
+  early `confirm` answers that the file is not there. Send on the PUT the `Content-Type` you
+  named when asking for the link: storage serves the file under the header it received.
 
 A refusal comes back as `{ error, code }`. Branch on `code` (`invalid_name`, `file_too_large`,
 `quota_exceeded`, `not_uploaded`, `duplicate_name`, `not_found`, …) and never on the text:
@@ -425,33 +474,20 @@ browser can be edited by whoever opened it. Never write the key into the sources
 send it to the frontend: the build gate stops on a key found in the application code, and a
 key that reached a visitor lets them delete every file of the project.
 
-## Syncing code
-
-`xflow status` shows how the local copy differs from the server revision.
-`xflow deploy` sends sources, `xflow pull` fetches them.
+## Organizations and keys
 
-If a deploy is rejected before the build starts, the server revision is newer, meaning
-someone deployed first. Fetch their work next to yours (`xflow pull --into ./server-copy`),
-merge it locally, then deploy again. `--force` destroys their work: a last resort, not a
-way around the error.
+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.
 
-## Organizations and keys
+Inside a project folder there is nothing to switch: commands follow the organization the
+folder is bound to, whatever the active one is. That is what lets two projects of two
+organizations work side by side.
 
-A key belongs to one organization, and `xflow login` stores it next to the ones already
-stored instead of replacing them. Which key a command uses, in order: `XFLOW_TOKEN` when
-set (default platform address only), then the organization the project folder is bound
-to (`.xflow/state.json`, written by init, link and the first successful deploy or pull),
-then the active organization. `xflow org` lists the stored organizations with the active
-one marked, `xflow org switch <name|id>` makes another one active without a browser, and
-`xflow whoami` names the organization behind the current key.
-
-Inside a project folder there is nothing to switch: commands follow the folder's own
-organization whatever the active one is, which is what lets two projects of two
-organizations work side by side. Project ids are unique across the platform, so a key of
-the wrong organization can never touch another organization's project: the command fails
-with "not found" instead. When that error names a project you know exists, check
-`xflow org`; signing in to a missing organization is `xflow login`, and that needs a
-person with a browser.
+A "not found" on a project you know exists usually means the key belongs to another
+organization, not that the project is gone: ids are unique across the platform, so a
+wrong key can never reach somebody else's project. Check `xflow org`. Signing in to a
+missing organization is `xflow login`, and that needs a person with a browser.
 
 ## Direct access without the terminal