@getxflow/cli 0.6.4 → 0.6.5

package/dist/help.js

@@ -9,323 +9,348 @@ 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 (id: xflow projects list)
-  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)('Code')}
-  xflow status                    what is on the server and how the local copy differs
-  xflow push [--force]            send the sources as a new revision
-  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> return the project to an earlier version
-  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
-
-${(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 whoami                    whose key this is and what it can do
-  xflow logout                    forget the key
-  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 (id: xflow projects list)
+  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)('Code')}
+  xflow status                    what is on the server and how the local copy differs
+  xflow push [--force]            send the sources as a new revision
+  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> return the project to an earlier version
+  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
+
+${(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 whoami                    whose key this is and what it can do
+  xflow logout                    forget the key
+  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 = {
-    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]")})
-never reaches the environment, so read variables literally.
-
-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
+    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]")})
+never reaches the environment, so read variables literally.
+
+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.`,
-    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
+    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
+
+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.
+
+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 is done by a person, in the project settings under Connectors, and there is no
+command for it yet. That is on purpose: a link hands somebody else's credentials to
+everyone who deploys the project, and access to a connection is granted per person.
+The same goes for connecting a new account and for switching one off.`,
+    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.`,
-    push: `${(0, ui_1.bold)('xflow push')}: send 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 push is
-rejected. That means somebody pushed before you: fetch their changes alongside
-(${(0, ui_1.bold)('xflow pull --into ./server-copy')}), merge them in git on your side, and retry.
-
---force overwrites the server revision. 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
+    push: `${(0, ui_1.bold)('xflow push')}: send 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 push is
+rejected. That means somebody pushed before you: fetch their changes alongside
+(${(0, ui_1.bold)('xflow pull --into ./server-copy')}), merge them in git on your side, and retry.
+
+--force overwrites the server revision. 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.`,
-    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 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 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>: return an earlier build
-
-Switches the project to the chosen build. Only the build comes back: the sources stay
-at their own revision, and returning them is a separate decision
-(${(0, ui_1.bold)('xflow pull --revision N --into ./old-version')}).
-
+    rollback: `${(0, ui_1.bold)('xflow rollback')} <version number>: return an earlier build
+
+Switches the project to the chosen build. Only the build comes back: the sources stay
+at their own revision, and returning them is a separate decision
+(${(0, ui_1.bold)('xflow pull --revision N --into ./old-version')}).
+
 Visitors keep seeing the published version until ${(0, ui_1.bold)('xflow publish')} is run.`,
 };