@getxflow/cli 0.9.1 → 0.10.0

package/dist/help.js

@@ -9,404 +9,453 @@ function help(topic) {
         (0, ui_1.out)(TOPICS[topic]);
         return;
     }
-    (0, ui_1.out)(`${(0, ui_1.bold)('xflow')} ${(0, ui_1.dim)(version_1.CLI_VERSION)} XFlow application hosting
-
-${(0, ui_1.bold)('Getting started')}
-  xflow login                     sign in through the browser
-  xflow init [dir]                new project from the platform template
-  xflow templates                 which templates are available
-  xflow link <id>                 link this folder to a project, an empty one also gets the sources
-  xflow skills                    pick the agents that get the platform instructions
-  xflow mcp install               give the agent platform access without a terminal
-
-${(0, ui_1.bold)('Sources')}
-  xflow status                    what is on the server and how the local copy differs
-  xflow pull [--into dir] [--revision N]
-                                  fetch the sources (the latest revision by default)
-
-${(0, ui_1.bold)('Releasing')}
-  xflow deploy [--no-push]        send the code, ship the functions, build on the platform
-  xflow publish                   show the dev version to visitors
-  xflow rollback <version number> serve the pages of an earlier build
-  xflow deployments               version history
-
-${(0, ui_1.bold)('Functions')}
-  xflow functions list            what is deployed (they ship with xflow deploy)
-  xflow functions invoke <name> [--data '{"a":1}']
-                                  call a function and print the answer
-  xflow functions logs [name]     function crashes: stack and console output
-  xflow schedules list            what runs on a timer
-  xflow schedules set <name> "0 3 ? * * *"
-                                  run a function on a schedule (UTC)
-  xflow schedules rm <name>       take a schedule off
-  xflow env [check]               function variables: what is stored, what is missing
-  xflow env set NAME=value        store a variable
-  xflow env rm NAME               delete a variable
-  xflow connections               connected accounts the project can use, and their variables
-  xflow connections link <name> --as ALIAS
-                                  give the functions the credentials of an account
-  xflow connections unlink <ALIAS> [--force]
-                                  take them away again
-
-${(0, ui_1.bold)('Database')}
-  xflow db status                 which migrations are applied and which are waiting
-  xflow db schema [table]         tables of the project, or the columns of one
-  xflow db query "select ..."     read data, in a read-only transaction
-  xflow db migrate [--dry-run] [--allow-destructive]
-                                  apply the migrations from migrations/*.sql
-
-${(0, ui_1.bold)('Reference')}
-  xflow logs [--limit N]          browser errors from the released application
-  xflow projects list             projects of the organization
-  xflow projects get [id]         project card
-  xflow org                       organizations with a stored key, the active one marked
-  xflow org switch <name|id>      make another organization the active one
-  xflow whoami                    whose key this is and what it can do
-  xflow logout [--all]            forget the key of the active organization (--all: every one)
-  xflow update                    update the CLI itself, and the skill that ships with it
-
-${(0, ui_1.bold)('Environment')}
-  XFLOW_TOKEN                     access key (for CI, instead of xflow login)
-  XFLOW_API_URL                   platform address when it is not app.getxflow.com
-
+    (0, ui_1.out)(`${(0, ui_1.bold)('xflow')} ${(0, ui_1.dim)(version_1.CLI_VERSION)} XFlow application hosting
+
+${(0, ui_1.bold)('Getting started')}
+  xflow login                     sign in through the browser
+  xflow init [dir]                new project from the platform template
+  xflow templates                 which templates are available
+  xflow link <id>                 link this folder to a project, an empty one also gets the sources
+  xflow skills                    pick the agents that get the platform instructions
+  xflow mcp install               give the agent platform access without a terminal
+
+${(0, ui_1.bold)('Sources')}
+  xflow status                    what is on the server and how the local copy differs
+  xflow pull [--into dir] [--revision N]
+                                  fetch the sources (the latest revision by default)
+
+${(0, ui_1.bold)('Files')}
+  xflow storage ls [folder]       what the file storage of the project holds
+  xflow storage push <dir> [--to folder] [--replace]
+                                  upload heavy static assets: photos, video, PDFs
+  xflow storage rm <address>      delete one file
+  xflow storage rm --folder <path> --yes
+                                  delete a folder with everything in it
+
+${(0, ui_1.bold)('Releasing')}
+  xflow deploy [--no-push]        send the code, ship the functions, build on the platform
+  xflow publish                   show the dev version to visitors
+  xflow rollback <version number> serve the pages of an earlier build
+  xflow deployments               version history
+
+${(0, ui_1.bold)('Functions')}
+  xflow functions list            what is deployed (they ship with xflow deploy)
+  xflow functions invoke <name> [--data '{"a":1}']
+                                  call a function and print the answer
+  xflow functions logs [name]     function crashes: stack and console output
+  xflow schedules list            what runs on a timer
+  xflow schedules set <name> "0 3 ? * * *"
+                                  run a function on a schedule (UTC)
+  xflow schedules rm <name>       take a schedule off
+  xflow env [check]               function variables: what is stored, what is missing
+  xflow env set NAME=value        store a variable
+  xflow env rm NAME               delete a variable
+  xflow connections               connected accounts the project can use, and their variables
+  xflow connections link <name> --as ALIAS
+                                  give the functions the credentials of an account
+  xflow connections unlink <ALIAS> [--force]
+                                  take them away again
+
+${(0, ui_1.bold)('Database')}
+  xflow db status                 which migrations are applied and which are waiting
+  xflow db schema [table]         tables of the project, or the columns of one
+  xflow db query "select ..."     read data, in a read-only transaction
+  xflow db migrate [--dry-run] [--allow-destructive]
+                                  apply the migrations from migrations/*.sql
+
+${(0, ui_1.bold)('Reference')}
+  xflow logs [--limit N]          browser errors from the released application
+  xflow projects list             projects of the organization
+  xflow projects get [id]         project card
+  xflow org                       organizations with a stored key, the active one marked
+  xflow org switch <name|id>      make another organization the active one
+  xflow whoami                    whose key this is and what it can do
+  xflow logout [--all]            forget the key of the active organization (--all: every one)
+  xflow update                    update the CLI itself, and the skill that ships with it
+
+${(0, ui_1.bold)('Environment')}
+  XFLOW_TOKEN                     access key (for CI, instead of xflow login)
+  XFLOW_API_URL                   platform address when it is not app.getxflow.com
+
 More about one command: xflow help <command>`);
 }
 const TOPICS = {
-    org: `${(0, ui_1.bold)('xflow org')}: several organizations, one terminal
-
-One key per organization: every ${(0, ui_1.bold)('xflow login')} stores the key of the organization
-chosen in the browser next to the ones already stored, it does not replace them.
-Which key a command then uses, in order:
-
-  1. XFLOW_TOKEN, when set (and only for the default platform address)
-  2. the organization this folder is bound to (${(0, ui_1.bold)('.xflow/state.json')}, written by
-     init, link and the first successful deploy or pull)
-  3. the active organization
-
-  xflow org                      the stored organizations, the active one marked
-  xflow org switch <name|id>     make another one active, no browser involved
-  xflow logout                   forget the key of the active organization
-  xflow logout --all             forget every key of this platform address
-
-The switch is local: it changes which stored key is used and nothing happens on
-the platform. A folder bound to an organization is not affected, its commands
-stay in its own organization: two projects of two organizations in two terminals
-work without switching anything.
-
-Outside a project folder the switch also rewrites the key in the agent config
-(see ${(0, ui_1.bold)('xflow mcp')}) when an xflow entry already exists there; a running agent
-session picks the new key up only after a restart.
-
-A project id is unique across the whole platform, so "project not found" under
-the wrong organization can never touch somebody else's project. When that error
-names a project you know exists, the key is simply from another organization:
+    org: `${(0, ui_1.bold)('xflow org')}: several organizations, one terminal
+
+One key per organization: every ${(0, ui_1.bold)('xflow login')} stores the key of the organization
+chosen in the browser next to the ones already stored, it does not replace them.
+Which key a command then uses, in order:
+
+  1. XFLOW_TOKEN, when set (and only for the default platform address)
+  2. the organization this folder is bound to (${(0, ui_1.bold)('.xflow/state.json')}, written by
+     init, link and the first successful deploy or pull)
+  3. the active organization
+
+  xflow org                      the stored organizations, the active one marked
+  xflow org switch <name|id>     make another one active, no browser involved
+  xflow logout                   forget the key of the active organization
+  xflow logout --all             forget every key of this platform address
+
+The switch is local: it changes which stored key is used and nothing happens on
+the platform. A folder bound to an organization is not affected, its commands
+stay in its own organization: two projects of two organizations in two terminals
+work without switching anything.
+
+Outside a project folder the switch also rewrites the key in the agent config
+(see ${(0, ui_1.bold)('xflow mcp')}) when an xflow entry already exists there; a running agent
+session picks the new key up only after a restart.
+
+A project id is unique across the whole platform, so "project not found" under
+the wrong organization can never touch somebody else's project. When that error
+names a project you know exists, the key is simply from another organization:
 check ${(0, ui_1.bold)('xflow org')}.`,
-    update: `${(0, ui_1.bold)('xflow update')}: bring the CLI up to date
-
-Installs the published version and, if anything changed, rewrites the platform
-instructions the agents already have: the skill ships inside the package and shares
-its version, so a fresh CLI next to a stale skill means the agent is reading last
-month's rules. Copies that are not installed are not created, so it is safe to run
-from any folder.
-
-The platform reports the published version with every answer, which is where the
-${(0, ui_1.bold)('xflow N is out')} line comes from. It appears once a day at most, and never in CI,
-where nobody is going to update anything anyway.
-
-The command works out how this copy was installed from its own path, and refuses to
-cross package managers: an install made by pnpm or bun is printed as their own
-command rather than handed to npm, which would leave you with two copies and no way
-to tell which one answers. Two more cases end the same way. Under ${(0, ui_1.bold)('npx')} there is
-nothing to update, only a cache. And a copy inside a project's node_modules is a
-dependency of that project: ${(0, ui_1.bold)('npm i -D @getxflow/cli@latest')} is the fix, because
-inside npm scripts the local copy wins over anything installed globally.
-
-A refusal from the platform saying the CLI is too old is a different thing: that one
-is a hard gate on a changed contract, and until you run this command nothing else
+    update: `${(0, ui_1.bold)('xflow update')}: bring the CLI up to date
+
+Installs the published version and, if anything changed, rewrites the platform
+instructions the agents already have: the skill ships inside the package and shares
+its version, so a fresh CLI next to a stale skill means the agent is reading last
+month's rules. Copies that are not installed are not created, so it is safe to run
+from any folder.
+
+The platform reports the published version with every answer, which is where the
+${(0, ui_1.bold)('xflow N is out')} line comes from. It appears once a day at most, and never in CI,
+where nobody is going to update anything anyway.
+
+The command works out how this copy was installed from its own path, and refuses to
+cross package managers: an install made by pnpm or bun is printed as their own
+command rather than handed to npm, which would leave you with two copies and no way
+to tell which one answers. Two more cases end the same way. Under ${(0, ui_1.bold)('npx')} there is
+nothing to update, only a cache. And a copy inside a project's node_modules is a
+dependency of that project: ${(0, ui_1.bold)('npm i -D @getxflow/cli@latest')} is the fix, because
+inside npm scripts the local copy wins over anything installed globally.
+
+A refusal from the platform saying the CLI is too old is a different thing: that one
+is a hard gate on a changed contract, and until you run this command nothing else
 will work.`,
-    db: `${(0, ui_1.bold)('xflow db')}: schema, data, migrations
-
-  xflow db status                  what is applied and what is waiting
-  xflow db schema [table]          tables of the project, or the columns of one
-  xflow db query "select ..."      read data (--limit N)
-  xflow db migrate                 apply migrations/*.sql
-
-${(0, ui_1.bold)('schema')} answers a different question than the ${(0, ui_1.bold)('migrations/')} directory: one logical
-database is shared by several projects, so the files say what you did, and the schema
-says what is actually in there. ${(0, ui_1.bold)('query')} runs inside a READ ONLY transaction, so
-writes are rejected by the database itself, not by us reading your SQL.
-
-${(0, ui_1.bold)('migrate')}: the files live in the repository (${(0, ui_1.bold)('migrations/0001_init.sql')},
-${(0, ui_1.bold)('migrations/0002_orders.sql')} and so on). The order comes from the file name, which
-is why the leading number is required. Every migration runs in its own transaction, the
-history is kept in the database itself, and anything already applied is not run again.
-
-  --dry-run              report what would be applied without touching the database
-  --allow-destructive    allow operations that destroy data
-
-About destructive ones. The platform keeps no database history and makes no backups,
-so ${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} and ${(0, ui_1.bold)('DELETE FROM')} without a
-condition need two things at once: this flag, and the right to destroy data on the
-access key. That right is off by default, and only its owner turns it on, in the
-platform settings under Developers: a flag is something an agent adds by itself, a
-right is not. With both in place, the contents of the affected tables are dumped and
-kept for 7 days: that is a "caught it right away" safety net, not a backup.
-${(0, ui_1.bold)('DROP DATABASE')} is never allowed, because the database is shared across the
-organization.
-
-Editing an already applied file achieves nothing: the comparison is by name, not by
-content. ${(0, ui_1.bold)('xflow db status')} lists such a file separately, so write a new migration
-instead.
-
-One logical database can be attached to several projects, so the history may hold
-migrations that are not in your repository. That is normal, but it also means your
+    db: `${(0, ui_1.bold)('xflow db')}: schema, data, migrations
+
+  xflow db status                  what is applied and what is waiting
+  xflow db schema [table]          tables of the project, or the columns of one
+  xflow db query "select ..."      read data (--limit N)
+  xflow db migrate                 apply migrations/*.sql
+
+${(0, ui_1.bold)('schema')} answers a different question than the ${(0, ui_1.bold)('migrations/')} directory: one logical
+database is shared by several projects, so the files say what you did, and the schema
+says what is actually in there. ${(0, ui_1.bold)('query')} runs inside a READ ONLY transaction, so
+writes are rejected by the database itself, not by us reading your SQL.
+
+${(0, ui_1.bold)('migrate')}: the files live in the repository (${(0, ui_1.bold)('migrations/0001_init.sql')},
+${(0, ui_1.bold)('migrations/0002_orders.sql')} and so on). The order comes from the file name, which
+is why the leading number is required. Every migration runs in its own transaction, the
+history is kept in the database itself, and anything already applied is not run again.
+
+  --dry-run              report what would be applied without touching the database
+  --allow-destructive    allow operations that destroy data
+
+About destructive ones. The platform keeps no database history and makes no backups,
+so ${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} and ${(0, ui_1.bold)('DELETE FROM')} without a
+condition need two things at once: this flag, and the right to destroy data on the
+access key. That right is off by default, and only its owner turns it on, in the
+platform settings under Developers: a flag is something an agent adds by itself, a
+right is not. With both in place, the contents of the affected tables are dumped and
+kept for 7 days: that is a "caught it right away" safety net, not a backup.
+${(0, ui_1.bold)('DROP DATABASE')} is never allowed, because the database is shared across the
+organization.
+
+Editing an already applied file achieves nothing: the comparison is by name, not by
+content. ${(0, ui_1.bold)('xflow db status')} lists such a file separately, so write a new migration
+instead.
+
+One logical database can be attached to several projects, so the history may hold
+migrations that are not in your repository. That is normal, but it also means your
 migration can break somebody else's application.`,
-    logs: `${(0, ui_1.bold)('xflow logs')} and ${(0, ui_1.bold)('xflow functions logs')}: project errors
-
-One stream per project: crashes of the released application in the browser and
-crashes of the cloud functions. The last 200 entries are kept, older ones fall off.
-
-  --limit N          how many to show (10 by default)
-
-A function reports its own crashes: Yandex exposes its logs only over gRPC, so the
-wrapper catches the exception, carries the tail of the console with it (the last 40
-${(0, ui_1.bold)('console.log')} lines of that call) and sends it to the platform. Successful calls
-write nothing, otherwise every request would pay for it in latency.
-
-What never reaches this list: a crash while the module is starting (the function
-never gets as far as the wrapper), going over 90 seconds, and running out of memory.
-Those show up in the answer to ${(0, ui_1.bold)('xflow functions invoke')}.
-
-Browser errors are collected by ${(0, ui_1.bold)('src/utils/error-logger.ts')} of the template and
+    logs: `${(0, ui_1.bold)('xflow logs')} and ${(0, ui_1.bold)('xflow functions logs')}: project errors
+
+One stream per project: crashes of the released application in the browser and
+crashes of the cloud functions. The last 200 entries are kept, older ones fall off.
+
+  --limit N          how many to show (10 by default)
+
+A function reports its own crashes: Yandex exposes its logs only over gRPC, so the
+wrapper catches the exception, carries the tail of the console with it (the last 40
+${(0, ui_1.bold)('console.log')} lines of that call) and sends it to the platform. Successful calls
+write nothing, otherwise every request would pay for it in latency.
+
+What never reaches this list: a crash while the module is starting (the function
+never gets as far as the wrapper), going over 90 seconds, and running out of memory.
+Those show up in the answer to ${(0, ui_1.bold)('xflow functions invoke')}.
+
+Browser errors are collected by ${(0, ui_1.bold)('src/utils/error-logger.ts')} of the template and
 only from released addresses: a local ${(0, ui_1.bold)('npm run dev')} writes nothing here.`,
-    env: `${(0, ui_1.bold)('xflow env')}: environment variables of the functions
-
-Keys, passwords and third-party addresses are kept by the platform, not by the
-repository. A value goes up and never comes back: the only place to see it is inside
-the function. So keep your own copy wherever you got it from.
-
-  xflow env                        what is stored (names, not values)
-  xflow env check                  what the functions of this project are missing
-  xflow env set SMTP_PASSWORD=…    store
-  xflow env rm SMTP_PASSWORD       delete
-
-  --scope project                  visible to this project only, not the whole organization
-
-${(0, ui_1.bold)('check')} reads the sources in ${(0, ui_1.bold)('functions/')} and looks for ${(0, ui_1.bold)('process.env.NAME')}
-references. The same rule applies on deploy: a function receives only the variables it
-mentions by name. A name assembled from an expression (${(0, ui_1.bold)("process.env['KEY_' + n]")}),
-reached through ${(0, ui_1.bold)('?.')}, destructured or spread never reaches the environment, so read
-variables literally. ${(0, ui_1.bold)('check')} names those reads and the build rejects them: a secret
-that quietly fails to arrive is found by the function falling over weeks later.
-
-The value reaches the function on deploy, not at the moment it is stored: after
-${(0, ui_1.bold)('env set')} run ${(0, ui_1.bold)('xflow deploy')}. The build ships a function whose code did not
-change but whose variables did, so nothing is left holding an old value. The same after a
+    storage: `${(0, ui_1.bold)('xflow storage')}: files of the application
+
+The sources archive is capped at 10 MB and is rebuilt and re-uploaded on every
+deploy, so photos, video and PDFs do not belong in the repository. File storage
+is the place for them: the files sit beside the versions, survive a build, and
+are metered against the plan of the organization.
+
+  xflow storage ls [folder]        what is there, with addresses and sizes
+  xflow storage push ./media --to media
+                                   upload a folder, keeping its structure
+  xflow storage rm <address>       delete one file
+  xflow storage rm --folder photos --yes
+                                   delete a folder with everything in it
+
+  --to <folder>                    where to put it in the project storage
+  --replace                        upload files whose size differs from the stored one
+  --json                           machine-readable output, with every address
+
+${(0, ui_1.bold)('push')} sends only what is missing: a file already stored under the same path and
+size is skipped, so running the command again after a broken connection is cheap.
+A file that differs is left alone unless ${(0, ui_1.bold)('--replace')} is given. Bytes go straight
+into the bucket, they do not pass through the platform.
+
+Addresses are permanent and belong to the record, not to the bytes: replacing a
+file keeps its address, so the links in the code and in the tables of the
+application keep working. That is why there is no delete-and-upload-again.
+
+The address is not public: it is a page of the platform that checks the rights of
+the viewer on every request, so a closed project stops serving its pictures too.
+Use the address as it came back, in ${(0, ui_1.bold)('<img src>')} and in the data of the application.
+
+Dot entries and symbolic links are skipped, and ${(0, ui_1.bold)('.xflowignore')} is not read here:
+those are the rules for the sources, and a media folder is exactly what one is
+asked to put there so it stays out of the archive.
+
+${(0, ui_1.bold)('rm')} needs a right of its own (${(0, ui_1.bold)('Delete files')} in the Developers section of the
+platform), off by default. The reason is the neighbourhood: whatever the users of
+the application uploaded lives in the same folders, and there is no undo. A folder
+first answers with the number of files it holds and deletes only on ${(0, ui_1.bold)('--yes')}.
+
+There is no command back: sources return with ${(0, ui_1.bold)('xflow pull')}, files do not.`,
+    env: `${(0, ui_1.bold)('xflow env')}: environment variables of the functions
+
+Keys, passwords and third-party addresses are kept by the platform, not by the
+repository. A value goes up and never comes back: the only place to see it is inside
+the function. So keep your own copy wherever you got it from.
+
+  xflow env                        what is stored (names, not values)
+  xflow env check                  what the functions of this project are missing
+  xflow env set SMTP_PASSWORD=…    store
+  xflow env rm SMTP_PASSWORD       delete
+
+  --scope project                  visible to this project only, not the whole organization
+
+${(0, ui_1.bold)('check')} reads the sources in ${(0, ui_1.bold)('functions/')} and looks for ${(0, ui_1.bold)('process.env.NAME')}
+references. The same rule applies on deploy: a function receives only the variables it
+mentions by name. A name assembled from an expression (${(0, ui_1.bold)("process.env['KEY_' + n]")}),
+reached through ${(0, ui_1.bold)('?.')}, destructured or spread never reaches the environment, so read
+variables literally. ${(0, ui_1.bold)('check')} names those reads and the build rejects them: a secret
+that quietly fails to arrive is found by the function falling over weeks later.
+
+The value reaches the function on deploy, not at the moment it is stored: after
+${(0, ui_1.bold)('env set')} run ${(0, ui_1.bold)('xflow deploy')}. The build ships a function whose code did not
+change but whose variables did, so nothing is left holding an old value. The same after a
 delete: a function already deployed keeps the old value until its next deploy.`,
-    connections: `${(0, ui_1.bold)('xflow connections')}: accounts connected to the organization
-
-Somebody signs in to Yandex Metrika, Bitrix or a mail service once, in the platform,
-and that account becomes a connection of the organization. Linked to a project, it
-hands its credentials to the cloud functions as environment variables. Nobody has to
-paste a token into the repository, and nobody sees the value: it goes straight from
-the platform into the function.
-
-  xflow connections                what this project can use, and what it already uses
-  xflow connections link <name> --as ALIAS
-                                   hand its credentials to the functions
-  xflow connections unlink <ALIAS> take them away again
-
-Every row says whether the connection is linked to this project (its alias) and what
-state the access is in. ${(0, ui_1.bold)('available, not linked')} is the useful one: the account
-exists in the organization, but this project gets nothing from it yet: link it.
-
-Both commands take the name of the connection, the first column of the list, and both
-also take its identifier. ${(0, ui_1.bold)('unlink')} takes the alias as well, and prefers it: the
-alias is the name your own code already uses. One organization can hold several accounts
-of the same service under one name; then the command prints their identifiers and asks
-for one of those instead of guessing.
-
-${(0, ui_1.bold)('unlink')} refuses while a function still reads one of the variables and names
-those functions; ${(0, ui_1.bold)('--force')} goes through anyway.
-
-Variables are named after the alias: an OAuth connection called ${(0, ui_1.bold)('YANDEX_METRIKA')}
-gives ${(0, ui_1.bold)('YANDEX_METRIKA_TOKEN')}, a key-based one gives a variable per field. They
-arrive at a function on its next deploy, like every other variable, so after a change
-run ${(0, ui_1.bold)('xflow deploy')}. A token close to expiry is renewed by any build on the way;
-a revoked one is not renewed by anything until a human reconnects the account.
-
-Linking needs a right on the key, ${(0, ui_1.bold)('connections:link')}. Keys are issued with it,
-and a person can take it away in the platform settings under Developers; a key cannot give
-it back to itself. Losing it is what the refusal says, and the answer is to ask a person,
-not to look for another route. Either way only the accounts granted to you personally can
-be linked at all: that rule holds whatever the key is allowed to do.
-
-Connecting a new account and switching one off stay with a person, in the platform
+    connections: `${(0, ui_1.bold)('xflow connections')}: accounts connected to the organization
+
+Somebody signs in to Yandex Metrika, Bitrix or a mail service once, in the platform,
+and that account becomes a connection of the organization. Linked to a project, it
+hands its credentials to the cloud functions as environment variables. Nobody has to
+paste a token into the repository, and nobody sees the value: it goes straight from
+the platform into the function.
+
+  xflow connections                what this project can use, and what it already uses
+  xflow connections link <name> --as ALIAS
+                                   hand its credentials to the functions
+  xflow connections unlink <ALIAS> take them away again
+
+Every row says whether the connection is linked to this project (its alias) and what
+state the access is in. ${(0, ui_1.bold)('available, not linked')} is the useful one: the account
+exists in the organization, but this project gets nothing from it yet: link it.
+
+Both commands take the name of the connection, the first column of the list, and both
+also take its identifier. ${(0, ui_1.bold)('unlink')} takes the alias as well, and prefers it: the
+alias is the name your own code already uses. One organization can hold several accounts
+of the same service under one name; then the command prints their identifiers and asks
+for one of those instead of guessing.
+
+${(0, ui_1.bold)('unlink')} refuses while a function still reads one of the variables and names
+those functions; ${(0, ui_1.bold)('--force')} goes through anyway.
+
+Variables are named after the alias: an OAuth connection called ${(0, ui_1.bold)('YANDEX_METRIKA')}
+gives ${(0, ui_1.bold)('YANDEX_METRIKA_TOKEN')}, a key-based one gives a variable per field. They
+arrive at a function on its next deploy, like every other variable, so after a change
+run ${(0, ui_1.bold)('xflow deploy')}. A token close to expiry is renewed by any build on the way;
+a revoked one is not renewed by anything until a human reconnects the account.
+
+Linking needs a right on the key, ${(0, ui_1.bold)('connections:link')}. Keys are issued with it,
+and a person can take it away in the platform settings under Developers; a key cannot give
+it back to itself. Losing it is what the refusal says, and the answer is to ask a person,
+not to look for another route. Either way only the accounts granted to you personally can
+be linked at all: that rule holds whatever the key is allowed to do.
+
+Connecting a new account and switching one off stay with a person, in the platform
 interface. There is no command for either.`,
-    schedules: `${(0, ui_1.bold)('xflow schedules')}: running functions on a timer
-
-A schedule is a Yandex timer trigger: it calls the function itself, with no
-application and no browser involved.
-
-  xflow schedules set report "0 3 ? * * *"     every day at 03:00
-  xflow schedules set digest "0 */4 ? * * *"   every 4 hours
-  xflow schedules rm report                    take off every schedule of a function
-
-Six fields: ${(0, ui_1.bold)('minutes hours day-of-month month day-of-week year')}. Exactly one of
-the day-of-month and day-of-week fields has to be ${(0, ui_1.bold)('?')}, which is not our quirk but
-how Yandex works. ${(0, ui_1.bold)('The time is always UTC')}, local time is not understood.
-
-  --payload '{"mode":"full"}'      the body the function will receive
-
-A scheduled run arrives at the handler as a POST with no headers, and the project
-token is not checked on it: such an event cannot be forged from outside. The function
-has to be deployed already, since the schedule points at it and not the other way round.
-
-A failed run shows up in ${(0, ui_1.bold)('xflow functions logs')}: nobody is watching a scheduled
+    schedules: `${(0, ui_1.bold)('xflow schedules')}: running functions on a timer
+
+A schedule is a Yandex timer trigger: it calls the function itself, with no
+application and no browser involved.
+
+  xflow schedules set report "0 3 ? * * *"     every day at 03:00
+  xflow schedules set digest "0 */4 ? * * *"   every 4 hours
+  xflow schedules rm report                    take off every schedule of a function
+
+Six fields: ${(0, ui_1.bold)('minutes hours day-of-month month day-of-week year')}. Exactly one of
+the day-of-month and day-of-week fields has to be ${(0, ui_1.bold)('?')}, which is not our quirk but
+how Yandex works. ${(0, ui_1.bold)('The time is always UTC')}, local time is not understood.
+
+  --payload '{"mode":"full"}'      the body the function will receive
+
+A scheduled run arrives at the handler as a POST with no headers, and the project
+token is not checked on it: such an event cannot be forged from outside. The function
+has to be deployed already, since the schedule points at it and not the other way round.
+
+A failed run shows up in ${(0, ui_1.bold)('xflow functions logs')}: nobody is watching a scheduled
 function, so the wrapper reports a crash the same way it does on an ordinary call.`,
-    invoke: `${(0, ui_1.bold)('xflow functions invoke')} <name>: call a function
-
-Calls it exactly the way the application does: the project token plus a visitor pass
-for the person who owns the key, so the function sees a real caller and its role.
-Both are taken from the platform, no local .env is needed.
-
-  --data '{"a":1}'   request body (the method becomes POST by default)
-  --method GET       a different method
-
-Prints the status, the response time and the body. A non-zero exit code on 4xx and
-5xx: in CI such a call has to fail the step. The cause of a crash is shown by
+    invoke: `${(0, ui_1.bold)('xflow functions invoke')} <name>: call a function
+
+Calls it exactly the way the application does: the project token plus a visitor pass
+for the person who owns the key, so the function sees a real caller and its role.
+Both are taken from the platform, no local .env is needed.
+
+  --data '{"a":1}'   request body (the method becomes POST by default)
+  --method GET       a different method
+
+Prints the status, the response time and the body. A non-zero exit code on 4xx and
+5xx: in CI such a call has to fail the step. The cause of a crash is shown by
 ${(0, ui_1.bold)('xflow functions logs <name>')}.`,
-    mcp: `${(0, ui_1.bold)('xflow mcp install')}: connect the agent to the platform directly
-
-Writes the MCP server into the configuration of a client that has its own connect
-command: today that is Claude Code, and for the rest the command prints what to enter
-by hand. After that the agent runs the platform without a terminal: it inspects the
-database, applies migrations, ships and calls functions, sets schedules, reads logs.
-The commands stay: code, builds and releases are still done by the CLI, because
-pushing sources through MCP means filling the agent context and spending your money.
-
-The command takes the access key from your own login and does not print it: usually
-the agent runs this command itself, and everything printed lands in its context and in
-the chat history.
-
-  --show-token    print the key anyway (not while under an agent)
-
-There is one key per person per organization and its scope is not narrowed: the agent
-sees every project of the organization and names the one it needs. It takes the
+    mcp: `${(0, ui_1.bold)('xflow mcp install')}: connect the agent to the platform directly
+
+Writes the MCP server into the configuration of a client that has its own connect
+command: today that is Claude Code, and for the rest the command prints what to enter
+by hand. After that the agent runs the platform without a terminal: it inspects the
+database, applies migrations, ships and calls functions, sets schedules, reads logs.
+The commands stay: code, builds and releases are still done by the CLI, because
+pushing sources through MCP means filling the agent context and spending your money.
+
+The command takes the access key from your own login and does not print it: usually
+the agent runs this command itself, and everything printed lands in its context and in
+the chat history.
+
+  --show-token    print the key anyway (not while under an agent)
+
+There is one key per person per organization and its scope is not narrowed: the agent
+sees every project of the organization and names the one it needs. It takes the
 project from the ${(0, ui_1.bold)('project_id')} argument, not from your folder, which it cannot see.`,
-    skills: `${(0, ui_1.bold)('xflow skills')}: platform instructions for an AI agent
-
-An agent has no way to know about XFlow: the platform is not in its training. The
-instructions explain how to release and publish, where the design system components
-come from, and where to look for production errors. ${(0, ui_1.bold)('init')} and ${(0, ui_1.bold)('link')} lay them
-down on their own for the common agents, so this command exists to pick tools
-precisely. Refreshing after a CLI update is not your job any more: the skill and the
-CLI ship as one version, and ${(0, ui_1.bold)('xflow update')} rewrites the copies you already have.
-
-Run in a terminal, it asks two questions: where (this project, or the home folder,
-which makes the skill visible in every project) and for which agents. Copies that are
-already installed come pre-selected and are updated in place. Without a terminal, in
-CI or when an agent runs the command, there are no questions: the defaults plus every
-already installed copy are refreshed.
-
-  xflow skills list               the agents, their folders and what is installed
-  --agent claude,cursor           exact agents, no questions asked
-  --global                        the home folder instead of the project
-  --yes                           no questions: defaults plus what is installed
-  --refresh                       rewrite the copies that exist, create none
-
-The format is shared (agentskills.io) and inside a project most tools read the shared
-.agents/skills folder, so the paths differ mostly in the home directory. Cursor also
-gets .cursor/rules/xflow.mdc: its older versions do not read the shared format.
-
-Plus a few pointer lines in ${(0, ui_1.bold)('AGENTS.md')}. A skill is picked up lazily, only when its
-description matches the task, and "add a customers table" will not trigger it. AGENTS.md
-is always read by the agent, which is why the pointer is appended there, at the end of
+    skills: `${(0, ui_1.bold)('xflow skills')}: platform instructions for an AI agent
+
+An agent has no way to know about XFlow: the platform is not in its training. The
+instructions explain how to release and publish, where the design system components
+come from, and where to look for production errors. ${(0, ui_1.bold)('init')} and ${(0, ui_1.bold)('link')} lay them
+down on their own for the common agents, so this command exists to pick tools
+precisely. Refreshing after a CLI update is not your job any more: the skill and the
+CLI ship as one version, and ${(0, ui_1.bold)('xflow update')} rewrites the copies you already have.
+
+Run in a terminal, it asks two questions: where (this project, or the home folder,
+which makes the skill visible in every project) and for which agents. Copies that are
+already installed come pre-selected and are updated in place. Without a terminal, in
+CI or when an agent runs the command, there are no questions: the defaults plus every
+already installed copy are refreshed.
+
+  xflow skills list               the agents, their folders and what is installed
+  --agent claude,cursor           exact agents, no questions asked
+  --global                        the home folder instead of the project
+  --yes                           no questions: defaults plus what is installed
+  --refresh                       rewrite the copies that exist, create none
+
+The format is shared (agentskills.io) and inside a project most tools read the shared
+.agents/skills folder, so the paths differ mostly in the home directory. Cursor also
+gets .cursor/rules/xflow.mdc: its older versions do not read the shared format.
+
+Plus a few pointer lines in ${(0, ui_1.bold)('AGENTS.md')}. A skill is picked up lazily, only when its
+description matches the task, and "add a customers table" will not trigger it. AGENTS.md
+is always read by the agent, which is why the pointer is appended there, at the end of
 the file and once. ${(0, ui_1.bold)('CLAUDE.md')} is left alone: Claude Code reads .claude/skills anyway.`,
-    pull: `${(0, ui_1.bold)('xflow pull')}: fetch the sources
-
-By default it fetches the latest revision into the project folder and refuses to write
-into a non-empty one: the platform cannot merge changes, that is git's job.
-
-  --into <dir>       unpack alongside, to compare
-  --revision <N>     a specific revision (the list: xflow deployments)
+    pull: `${(0, ui_1.bold)('xflow pull')}: fetch the sources
+
+By default it fetches the latest revision into the project folder and refuses to write
+into a non-empty one: the platform cannot merge changes, that is git's job.
+
+  --into <dir>       unpack alongside, to compare
+  --revision <N>     a specific revision (the list: xflow deployments)
   --force            overwrite the folder completely`,
-    deploy: `${(0, ui_1.bold)('xflow deploy')}: build and release
-
-Three steps: sending the sources, shipping the cloud functions, building the application.
-The build command and the output directory come from xflow.json (npm run build and dist
-by default).
-
-  --no-push          do not send sources, build from the latest server revision
-  --force            allow overwriting the server revision while sending
-  --allow-removals   agree in advance to remove the functions gone from the sources
-
-The whole working copy goes up at once, as one revision. What is not sent: node_modules,
-.git, dist, build, .next, any .env, plus everything listed in .xflowignore and in the
-ignore field of xflow.json.
-
-If the server holds a revision newer than the one you worked from, the sources are
-rejected and the build does not start. That means somebody deployed before you: fetch
-their changes alongside (${(0, ui_1.bold)('xflow pull --into ./server-copy')}), merge them in git on
-your side, and retry. ${(0, ui_1.bold)('--force')} overwrites the server revision, and before that the
-CLI shows whose work you are about to destroy and asks for confirmation by typing the
-project name. In a non-interactive run (CI, an agent) there is no way to confirm: a
-version conflict has to fail the build rather than silently destroy somebody else's work.
-
-The platform builds, in a clean sandbox on one Node version for everybody, so "it
-worked on my machine" no longer depends on your machine. Before the build the project
-is checked against the template: mismatches are printed as a list and the build does
-not start at all.
-
-Everything in ${(0, ui_1.bold)('functions/<name>/index.ts')} is bundled and shipped by the same run,
-before the application is built. That order is not a convention but the only one that
-works: the addresses of the functions are baked into the bundle, so they have to exist
-first. A function whose code and variables did not change is left alone, and a function
-that fails to ship fails the whole build.
-
-A function gone from the sources would be deleted from the cloud along with its
-schedules, and that is final: one created again later gets a different address. So the
-build does not start at all until you say yes. In a terminal the CLI names the functions
-and asks; without one (CI, an agent) it stops and ${(0, ui_1.bold)('--allow-removals')} is the only way
-to agree. If the sources hold no functions at all while the cloud holds several, nothing
-is deleted and nothing is asked: that looks like a directory which never made it (a
-${(0, ui_1.bold)('functions/')} line in .xflowignore) rather than a decision.
-
-The database is not part of this: migrations change data in ways nothing can undo, so
-they stay their own command (${(0, ui_1.bold)('xflow db migrate')}).
-
-The built version is visible on the project page, and the CLI prints the link. Visitors
-see it after ${(0, ui_1.bold)('xflow publish')}. The address of the build itself is not printed:
-it carries the version number, and after the next publish such a link quietly serves an
+    deploy: `${(0, ui_1.bold)('xflow deploy')}: build and release
+
+Three steps: sending the sources, shipping the cloud functions, building the application.
+The build command and the output directory come from xflow.json (npm run build and dist
+by default).
+
+  --no-push          do not send sources, build from the latest server revision
+  --force            allow overwriting the server revision while sending
+  --allow-removals   agree in advance to remove the functions gone from the sources
+
+The whole working copy goes up at once, as one revision. What is not sent: node_modules,
+.git, dist, build, .next, any .env, plus everything listed in .xflowignore and in the
+ignore field of xflow.json.
+
+If the server holds a revision newer than the one you worked from, the sources are
+rejected and the build does not start. That means somebody deployed before you: fetch
+their changes alongside (${(0, ui_1.bold)('xflow pull --into ./server-copy')}), merge them in git on
+your side, and retry. ${(0, ui_1.bold)('--force')} overwrites the server revision, and before that the
+CLI shows whose work you are about to destroy and asks for confirmation by typing the
+project name. In a non-interactive run (CI, an agent) there is no way to confirm: a
+version conflict has to fail the build rather than silently destroy somebody else's work.
+
+The platform builds, in a clean sandbox on one Node version for everybody, so "it
+worked on my machine" no longer depends on your machine. Before the build the project
+is checked against the template: mismatches are printed as a list and the build does
+not start at all.
+
+Everything in ${(0, ui_1.bold)('functions/<name>/index.ts')} is bundled and shipped by the same run,
+before the application is built. That order is not a convention but the only one that
+works: the addresses of the functions are baked into the bundle, so they have to exist
+first. A function whose code and variables did not change is left alone, and a function
+that fails to ship fails the whole build.
+
+A function gone from the sources would be deleted from the cloud along with its
+schedules, and that is final: one created again later gets a different address. So the
+build does not start at all until you say yes. In a terminal the CLI names the functions
+and asks; without one (CI, an agent) it stops and ${(0, ui_1.bold)('--allow-removals')} is the only way
+to agree. If the sources hold no functions at all while the cloud holds several, nothing
+is deleted and nothing is asked: that looks like a directory which never made it (a
+${(0, ui_1.bold)('functions/')} line in .xflowignore) rather than a decision.
+
+The database is not part of this: migrations change data in ways nothing can undo, so
+they stay their own command (${(0, ui_1.bold)('xflow db migrate')}).
+
+The built version is visible on the project page, and the CLI prints the link. Visitors
+see it after ${(0, ui_1.bold)('xflow publish')}. The address of the build itself is not printed:
+it carries the version number, and after the next publish such a link quietly serves an
 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.
-
-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.
-
-  --name <name>       project name (the folder name by default)
-  --template <id>     a different template (the list: xflow templates)
-  --database <id>     attach a logical database of the organization
-
-The order: the project is created on the platform first, because without it there is
-nowhere to get the token for .env. If writing the files fails, the project stays empty
+    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.
+
+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.
+
+  --name <name>       project name (the folder name by default)
+  --template <id>     a different template (the list: xflow templates)
+  --database <id>     attach a logical database of the organization
+
+The order: the project is created on the platform first, because without it there is
+nowhere to get the token for .env. If writing the files fails, the project stays empty
 and the CLI explains how to pick it up with the link command.`,
-    rollback: `${(0, ui_1.bold)('xflow rollback')} <version number>: serve the pages of an earlier build
-
-Points the project at the pages of that build. ${(0, ui_1.bold)('Only the pages come back.')} Cloud
-functions and the database are one per project: they are not versioned, they are shared
-with the published application, and they stay exactly as they are now. A page from August
-will be talking to today's functions.
-
-The sources stay at their own revision too. Fetching the code of that build is a separate
-command (${(0, ui_1.bold)('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, and whatever is newer on the platform goes away.
-
+    rollback: `${(0, ui_1.bold)('xflow rollback')} <version number>: serve the pages of an earlier build
+
+Points the project at the pages of that build. ${(0, ui_1.bold)('Only the pages come back.')} Cloud
+functions and the database are one per project: they are not versioned, they are shared
+with the published application, and they stay exactly as they are now. A page from August
+will be talking to today's functions.
+
+The sources stay at their own revision too. Fetching the code of that build is a separate
+command (${(0, ui_1.bold)('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, and whatever is newer on the platform goes away.
+
 Visitors keep seeing the published pages until ${(0, ui_1.bold)('xflow publish')} is run.`,
 };