@getxflow/cli 0.34.1 → 1.0.0

package/dist/help.js

@@ -12,7 +12,10 @@ const version_1 = require("./version");
 const ALIASES = {
     invoke: 'functions',
     publish: 'deploy',
-    deployments: 'rollback',
+    rollback: 'deploy',
+    deployments: 'deploy',
+    apps: 'projects',
+    status: 'projects',
 };
 /** Help text. For agents this is the reference documentation. */
 /** Whether `xflow help <topic>` has a page: a hint that sends nowhere is a second dead end. */
@@ -35,19 +38,22 @@ Every command with a line of its own: xflow help`);
     }
     (0, ui_1.out)(`${(0, ui_1.bold)('xflow')} ${(0, ui_1.dim)(version_1.CLI_VERSION)} XFlow application hosting
 
+A project is a box: one database, cloud functions, secrets. Its apps live in apps/<folder>,
+each with its own versions and address. Commands follow the folder you stand in.
+
 ${(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 dev                       run the app on 127.0.0.1:3000, cloud functions included
+  xflow init [dir]                new project with its first app from the platform template
+  xflow apps add <folder>         another app of this project, in apps/<folder>
+  xflow link <id>                 link this folder to a project, an empty one gets the whole project
+  xflow dev                       in an app folder: run it on 127.0.0.1:3000, functions included
   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)
+  xflow status                    what is on the server and how the local copies differ
+  xflow pull [functions|apps/<folder>] [--into dir] [--revision N]
+                                  fetch the sources of the root or of one app
 
 ${(0, ui_1.bold)('Files')}
   xflow storage ls [folder]       what the file storage of the project holds
@@ -58,13 +64,16 @@ ${(0, ui_1.bold)('Files')}
                                   delete a folder with everything in it
 
 ${(0, ui_1.bold)('Releasing')}
-  xflow deploy -m "what changed"  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
+  xflow deploy functions -m "what changed"
+                                  send the project root, ship the functions and their callers
+  xflow deploy apps/<folder> -m "what changed"
+                                  send one app and build it (a bare deploy inside its folder)
+  xflow publish [build]           point the app address at the newest build, or a named one
+  xflow rollback <build>          the same with an older build
+  xflow deployments [functions]   builds of the app, or deploys of the functions
 
 ${(0, ui_1.bold)('Functions')}
-  xflow functions list            what is deployed, who may call it, the address
+  xflow functions list            what is deployed, its callers, open or not, last call
   xflow functions invoke <name> [--data '{"a":1}']
                                   call a function and print the answer
   xflow functions logs [name]     function crashes: stack and console output
@@ -83,9 +92,9 @@ ${(0, ui_1.bold)('Functions')}
 
 ${(0, ui_1.bold)('Database')}
   xflow db status                 which migrations are applied and which are waiting
-  xflow db list                   databases of the organization, servers, projects
+  xflow db list                   databases of the projects and the servers of the organization
   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 query 'select ...'     read data, in a read-only transaction
   xflow db migrate [--dry-run] [--allow-destructive]
                                   apply the migrations from migrations/*.sql
   xflow db move --to <server> --confirm <database>
@@ -101,9 +110,10 @@ ${(0, ui_1.bold)('Pages')}
   xflow pages rollback <page> <N> put an earlier version back on the address
 
 ${(0, ui_1.bold)('Reference')}
-  xflow logs [--limit N]          browser errors from the released application
+  xflow logs [--limit N]          browser errors of the published apps
   xflow projects list             projects of the organization
-  xflow projects get [id]         project card
+  xflow projects get [id]         project card: apps, database, functions
+  xflow apps                      the apps of this project and their folders
   xflow org                       organizations with a stored key, the active one marked
   xflow org members               who is in the organization, and with which role
   xflow org switch <name|id>      make another organization the active one
@@ -115,6 +125,7 @@ ${(0, ui_1.bold)('Reference')}
 ${(0, ui_1.bold)('Outside a project folder')}
   --project <id>                  name the project by id, for every command that can
                                   answer without the local files (xflow help project)
+  --app <id>                      name an app by id: deploy --revision, publish, deployments, logs
 
 ${(0, ui_1.bold)('Environment')}
   XFLOW_TOKEN                     access key (for CI, instead of xflow login)
@@ -161,26 +172,30 @@ check ${(0, ui_1.bold)('xflow org')}.`,
 Every command that only talks to the platform takes it, so a service project needs
 no working copy of its own:
 
-  xflow db query --project 3f2a… "select id, title from tasks where done = false"
+  xflow db query --project 3f2a… 'select id, title from tasks where done = false'
   xflow functions invoke kanban --project 3f2a… --data-file card.json
 
 Which commands: ${(0, ui_1.bold)('db status')}, ${(0, ui_1.bold)('db query')}, ${(0, ui_1.bold)('db schema')}, ${(0, ui_1.bold)('db move')}, ${(0, ui_1.bold)('functions list')},
 ${(0, ui_1.bold)('functions invoke')}, ${(0, ui_1.bold)('functions logs')}, ${(0, ui_1.bold)('logs')}, ${(0, ui_1.bold)('env')}, ${(0, ui_1.bold)('env rm')},
 ${(0, ui_1.bold)('connections')}, ${(0, ui_1.bold)('connections link')}, ${(0, ui_1.bold)('connections unlink')}, ${(0, ui_1.bold)('schedules')},
 ${(0, ui_1.bold)('schedules set')}, ${(0, ui_1.bold)('schedules rm')}, ${(0, ui_1.bold)('storage ls')}, ${(0, ui_1.bold)('storage push')},
-${(0, ui_1.bold)('storage rm')}, ${(0, ui_1.bold)('deployments')}, ${(0, ui_1.bold)('publish')}, ${(0, ui_1.bold)('rollback')}, ${(0, ui_1.bold)('deploy')}. Three of
+${(0, ui_1.bold)('storage rm')}, ${(0, ui_1.bold)('apps')}, ${(0, ui_1.bold)('deployments')} (the functions deploys) and ${(0, ui_1.bold)('deploy')}. Three of
 them answer with less under the flag: ${(0, ui_1.bold)('db status')} gives the applied history alone,
 because comparing it against the local ${(0, ui_1.bold)('migrations/')} directory needs the folder,
 ${(0, ui_1.bold)('connections unlink')} removes the link without naming the functions that read
 its variables, for the same reason, and ${(0, ui_1.bold)('deploy')} takes the flag only together with
-${(0, ui_1.bold)('--revision')}: that build runs a revision the platform already holds, so there is
-nothing to send and no folder to send it from. Without ${(0, ui_1.bold)('--revision')} it refuses and
-says so.
+${(0, ui_1.bold)('--revision')}: that deploy runs a revision of the functions the platform already holds,
+so there is nothing to send and no folder to send it from.
+
+${(0, ui_1.bold)('--app <id>')} does the same for one app: ${(0, ui_1.bold)('deploy --app <id> --revision N')}, ${(0, ui_1.bold)('deployments')},
+${(0, ui_1.bold)('logs')}, ${(0, ui_1.bold)('publish')} and ${(0, ui_1.bold)('rollback')}. Its project comes from the platform, so the two
+flags never go together.
 
 The rest cannot answer without the working copy and have nothing to do with an id
-instead: ${(0, ui_1.bold)('pull')}, ${(0, ui_1.bold)('status')}, ${(0, ui_1.bold)('dev')}, ${(0, ui_1.bold)('db migrate')},
+instead: ${(0, ui_1.bold)('pull')}, ${(0, ui_1.bold)('status')}, ${(0, ui_1.bold)('dev')}, ${(0, ui_1.bold)('apps add')}, ${(0, ui_1.bold)('db migrate')},
 ${(0, ui_1.bold)('env check')}, ${(0, ui_1.bold)('env set')}. They answer about the files next to them, so
-they keep asking for a folder. ${(0, ui_1.bold)('projects get')} and ${(0, ui_1.bold)('link')} take no flag either:
+they keep asking for a folder. ${(0, ui_1.bold)('publish')} and ${(0, ui_1.bold)('rollback')} take ${(0, ui_1.bold)('--app')} rather than
+${(0, ui_1.bold)('--project')}: they move one app. ${(0, ui_1.bold)('projects get')} and ${(0, ui_1.bold)('link')} take no flag either:
 they name the project by its id as an argument.
 
 The folder is then ignored whole, and that includes its ${(0, ui_1.bold)('xflow.json')}: the address
@@ -198,13 +213,35 @@ With several organizations signed in, the one holding the project is looked for
 every call: there is no folder to write the answer into, and a second place to
 remember it would be a second thing to keep true. When most calls go to one project,
 ${(0, ui_1.bold)('xflow org switch')} to its organization skips that search.`,
-    projects: `${(0, ui_1.bold)('xflow projects')}: the projects of the organization
-
-  xflow projects list             every project, its versions state and age
-  xflow projects get [id]         one card: versions, database, functions, schedules
-
-Both name the project positionally: the id is an argument, not a --project flag.
-Without one, ${(0, ui_1.bold)('get')} answers about the project of the folder it stands in.
+    projects: `${(0, ui_1.bold)('xflow projects')} and ${(0, ui_1.bold)('xflow apps')}: projects and their apps
+
+A project is a box: one database with its migrations, the cloud functions, secrets and
+members, and no code of its own. An app is code the platform builds and serves at
+https://<id>--<org>.xflowpage.ru, with its own versions and access level. One folder per
+project, apps in subfolders:
+
+  xflow.json                 projectId, and who may call each function
+  package.json               dependencies of the functions
+  functions/<name>/index.ts  cloud functions, shared by every app
+  migrations/0001_init.sql   the one database of the project
+  apps/<folder>/             an app: a Vite project with its own xflow.json (appId)
+
+  xflow projects list             every project, its apps count and age
+  xflow projects get [id]         one card: apps, database, functions and callers, schedules
+  xflow apps                      the apps of this project, their folders and addresses
+      --json                      as JSON, with the app ids
+  xflow apps add <folder>         a new app, laid into apps/<folder> from the template
+      --name <name>               its name (the folder by default)
+      --color <color>             its tile color (the platform picks one by default)
+  xflow status                    in the root: the root and every app; in an app: that app
+
+The root and every app are separate histories: apps/** never travels with the root, the
+root never travels with an app. The app is its appId, so a folder can be renamed freely.
+Who opens an app (members of the project, a list, anyone with the link) is set by a person
+in the web interface, not here.
+
+Both ${(0, ui_1.bold)('projects')} commands name the project positionally: the id is an argument, not a
+--project flag. Without one, ${(0, ui_1.bold)('get')} answers about the project of the folder it stands in.
 
 An id typed by hand is looked for across every signed-in organization, and the
 folder around the command is ignored whole, the way the ${(0, ui_1.bold)('--project')} flag does it
@@ -218,14 +255,14 @@ projects these are.
 ${(0, ui_1.bold)('xflow link <id>')} binds the current folder to a project; ${(0, ui_1.bold)('xflow init')} makes a new one.`,
     link: `${(0, ui_1.bold)('xflow link')} <id>: bind this folder to a project
 
-Writes xflow.json and .xflow/state.json, points .env at the project and lays down the
-instructions for the agents. The id comes from ${(0, ui_1.bold)('xflow projects list')}; a project of
-another signed-in organization is found too, and the folder is bound to that organization.
+Writes the root xflow.json and .xflow/state.json and lays down the instructions for the
+agents. The id comes from ${(0, ui_1.bold)('xflow projects list')}; a project of another signed-in
+organization is found too, and the folder is bound to that organization.
 
-An empty folder (.git alone counts as empty) also gets the latest sources, so there is no
-${(0, ui_1.bold)('pull')} after it: pull would refuse the folder anyway, it is not empty any more. A
-folder with files keeps them as they are: ${(0, ui_1.bold)('xflow status')} says how they differ from
-the server revision, ${(0, ui_1.bold)('xflow pull --into ./server-copy')} fetches it next to them.
+An empty folder (.git alone counts as empty) gets the whole project: the latest revision
+of the root and of every app, each app in apps/<folder> under the folder name the project
+revision records. A folder with files keeps them as they are: ${(0, ui_1.bold)('xflow status')} says
+how they differ, ${(0, ui_1.bold)('xflow pull --into ./server-copy')} fetches the whole project next to them.
 
 In a folder that is already linked, the command points xflow.json at the other project and
 keeps the rest of the file. A new project instead of an existing one: ${(0, ui_1.bold)('xflow init')}.`,
@@ -233,8 +270,8 @@ keeps the rest of the file. A new project instead of an existing one: ${(0, ui_1
 
 A page is a static site at https://<name>.xflowpage.ru: a landing page, a presentation, an
 invoice for people outside the organization. It opens by its address for anyone, without
-signing in and outside the platform. A project is the opposite: it opens only inside the
-platform, for the members of the organization.
+signing in, and has no build, no publish step and no database. An app is the opposite: code
+the platform builds, with versions, access levels and a database through functions.
 
   xflow pages                          the pages, their state and address
   xflow pages create <title> <path>    a new page with its first version: there are no
@@ -261,10 +298,11 @@ build it and upload what the build writes. Dot entries are skipped. At most 5 MB
 unpacked and 1000 files.
 
 The page is public, so a file holding a secret key is refused whole: every visitor would read
-it. A page that needs a backend (a form, a lookup) calls a cloud function that declares
-${(0, ui_1.bold)("exports.access = 'public'")}: such a function answers without a pass and without a
-key, and the page calls its address directly (${(0, ui_1.bold)('xflow functions list')} prints it). No
-key is baked into the page. Search engines are asked not to index pages, so do not promise SEO.
+it. A page that needs a backend (a form, a lookup) calls ${(0, ui_1.bold)('/_fn/<name>')} on its own address,
+and only a function whose callers in the root xflow.json of its project name the page answers:
+add the page name there and run ${(0, ui_1.bold)('xflow deploy functions')}. The page has to exist first.
+Such a function is open to the whole internet. Search engines are asked not to index pages,
+so do not promise SEO.
 
 A page takes the key of the whole organization, the one ${(0, ui_1.bold)('xflow login')} issues: a key
 scoped to projects is refused. Switching a page off and deleting it are for a person, in the
@@ -295,51 +333,50 @@ will work.`,
     db: `${(0, ui_1.bold)('xflow db')}: schema, data, migrations
 
   xflow db status                  what is applied, what is waiting, the server
-  xflow db list                    databases of the organization: servers, projects
+  xflow db list                    databases of the projects, the servers of the organization
   xflow db schema [table]          tables of the project, or the columns of one
-  xflow db query "select ..."      read data (--limit N: 50 by default, 300 at most;
+  xflow db query 'select ...'      read data (--limit N: 50 by default, 300 at most;
                                    --json prints the values whole)
   xflow db query <file>.sql        the same, the query read from a file
-  xflow db migrate                 apply migrations/*.sql
-  xflow db move --to <server> --confirm <database>
+  xflow db migrate                 store the project root, then apply migrations/*.sql
+  xflow db move --to <server> --confirm <project name>
                                    move the project database to another server
 
-${(0, ui_1.bold)('list')} is about the organization, not about this project: it names the logical
-databases, the identifier ${(0, ui_1.bold)('xflow init --database <id>')} asks for, and the projects
-attached to each one. That last column is the one to read before a migration. The server
-column says where a database lives: ${(0, ui_1.bold)('platform')} is the common one, ${(0, ui_1.bold)('own "<name>"')} the
-organization's own server. While an own server is not running, its databases do not
-answer, and that is not fixable from the code: its state is in the web interface. An
-organization with own servers also gets them listed, with the room used on each: that is
-the choice for ${(0, ui_1.bold)('xflow init --server')} and ${(0, ui_1.bold)('db move')}. Without that flag a new
-database goes to ${(0, ui_1.bold)('platform')}.
+Every project has exactly one database of its own, shared by all of its apps and functions,
+and every command here works from any folder of the project. ${(0, ui_1.bold)('list')} is about the
+organization: one database per project, and where each lives: ${(0, ui_1.bold)('platform')} is the common
+server, ${(0, ui_1.bold)('own "<name>"')} an own server of the organization. While an own server is not
+running, its databases do not answer, and that is not fixable from the code. An organization
+with own servers also gets them listed, with the room used on each: that is the choice for
+${(0, ui_1.bold)('xflow init --server')} and ${(0, ui_1.bold)('db move')}.
 
 ${(0, ui_1.bold)('move')} takes the database of this project to another server of the organization:
 ${(0, ui_1.bold)('platform')} or an own server by name (or id, when two share a name). The platform copies
-the tables, switches the functions of every project on the database and removes the old
-copy; nothing needs a deploy. While it copies, the applications read data but cannot save
-anything new, usually for a couple of minutes, and that goes for every project on the
-database, which is why ${(0, ui_1.bold)('--confirm')} takes the database name. It also needs the right
-to move databases on the key: off by default, only its owner turns it on, in the platform
-settings where the key permissions live. The command follows the move to the end;
+the tables, switches the functions of the project and removes the old copy; nothing needs a
+deploy. While it copies, the apps read data but cannot save anything new, usually for a
+couple of minutes, which is why ${(0, ui_1.bold)('--confirm')} takes the project name. It also needs the
+right to move databases on the key: off by default, only its owner turns it on, in the
+platform settings where the key permissions live. The command follows the move to the end;
 stopping it does not stop the move, and ${(0, ui_1.bold)('xflow db status')} shows where it stands. A move
-that fails is rolled back: the database stays where it was and works as before. Buying,
-paying for and deleting servers stay with the person, in the web interface.
-
-${(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. A query with
-double quotes goes in a .sql file outside the project: Windows PowerShell strips them from
-arguments, and a file in migrations/ would be taken for a migration. Its table cuts
+that fails is rolled back. Buying, paying for and deleting servers stay with the person.
+
+${(0, ui_1.bold)('schema')} answers a different question than the ${(0, ui_1.bold)('migrations/')} directory: the files say
+what you did, 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. Single quotes around
+the query hold in PowerShell, bash and zsh, while cmd.exe wants double ones; a query that
+needs quotes of its own goes in a .sql file outside the project, because Windows PowerShell
+strips double quotes from arguments and a file in migrations/ would be taken for a
+migration. Its table cuts
 long values to keep the columns readable; ${(0, ui_1.bold)('--json')} prints them whole, together with
 the applied limit and its ceiling. ${(0, ui_1.bold)('status')} named by id (${(0, ui_1.bold)('--project')}) answers with
 the applied history alone: comparing against ${(0, ui_1.bold)('migrations/')} needs the folder.
 
-${(0, ui_1.bold)('migrate')}: the files live in the repository (${(0, ui_1.bold)('migrations/0001_init.sql')},
+${(0, ui_1.bold)('migrate')}: the files live in the project root (${(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.
+is why the leading number is required. The command first stores the project root as a
+revision, so the migrations stay in its history and a clone gets them, then applies what is
+new. 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
@@ -351,21 +388,17 @@ access key. That right is off by default, and only its owner turns it on, in the
 platform settings, where the key permissions live: 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.
+${(0, ui_1.bold)('DROP DATABASE')} is never allowed.
 
 Editing an already applied file achieves nothing: ${(0, ui_1.bold)('migrate')} refuses a name that is
 already applied with different content, and ${(0, ui_1.bold)('xflow db status')} lists such a file
-separately. 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, and that a name already in that history
-is taken for you too: ${(0, ui_1.bold)('0001_init')} of a neighbour leaves yours no room.`,
+separately. Write a new migration instead.`,
     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.
+Two streams: crashes of the cloud functions of the project, and browser errors of each
+app. ${(0, ui_1.bold)('xflow logs')} in an app folder (or with ${(0, ui_1.bold)('--app <id>')}) shows that app, in the
+project root every app, each row named by its folder. The last 200 entries of each stream
+are kept, older ones fall off.
 
   --limit N          how many to show (10 by default)
 
@@ -380,7 +413,7 @@ never gets as far as the wrapper), going over the execution time cap of the plan
 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.`,
+only from the published addresses: a local ${(0, ui_1.bold)('xflow dev')} writes nothing here.`,
     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
@@ -447,9 +480,10 @@ variables literally. ${(0, ui_1.bold)('check')} names those reads and the build
 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
+${(0, ui_1.bold)('env set')} run ${(0, ui_1.bold)('xflow deploy functions')}. It 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.`,
+delete: a function already deployed keeps the old value until its next deploy. Apps get no
+variables at all: whatever a secret protects is reached through a function.`,
     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,
@@ -485,8 +519,8 @@ linked to a service project without a folder has to be removable the same way.
 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.
+run ${(0, ui_1.bold)('xflow deploy functions')}. A token close to expiry is renewed by that deploy 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, where the key permissions live; a key cannot give
@@ -556,41 +590,38 @@ how Yandex works. ${(0, ui_1.bold)('The time is always UTC')}, local time is not
 ${(0, ui_1.bold)('list')} prints that body next to the schedule, so what a timer sends can be read
 back without setting it again.
 
-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 scheduled run arrives at the handler as a POST with ${(0, ui_1.bold)("event.xflow.caller === 'schedule'")}:
+the envelope is signed by the platform, so such an event cannot be forged from outside. A
+function without callers that only a schedule wakes is a workflow, and a project without
+apps is made of those. 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.`,
     functions: `${(0, ui_1.bold)('xflow functions')}: what is deployed, and calling it
 
-  xflow functions list            name, state, who may call it, age, address
-  xflow functions invoke <name>   call one the way the application does
+  xflow functions list            name, state, callers, open, keys, last call and error
+  xflow functions invoke <name>   call one as yourself, through the platform
   xflow functions logs [name]     crashes: stack and console output
 
-There is no deploy command of their own: ${(0, ui_1.bold)('xflow deploy')} ships everything in
-${(0, ui_1.bold)('functions/<name>/index.ts')} and then builds the application.
-
-${(0, ui_1.bold)('list')} answers who may reach each function, and the code decides it:
+Functions belong to the project and ship on their own step: ${(0, ui_1.bold)('xflow deploy functions')}
+sends the project root and deploys everything in ${(0, ui_1.bold)('functions/<name>/index.ts')}. Every app
+of the project runs the new code the moment it finishes; there is no publish step for them.
 
-  in-app only        a visitor of the application, with a pass the platform issues
-  external (N keys)  plus an outside service holding a key a human issued in the interface
-  public             plus anyone at all: the code says ${(0, ui_1.bold)("exports.access = 'public'")}
+Who may call a function is its callers, in the root xflow.json:
 
-An open function is how a page on xflowpage.ru gets a backend: it answers without a pass
-and without a key, so the page calls the printed address directly and bakes no key into
-its files. Remove the line and deploy again to close it. The function that stays inside
-the application declares nothing, and ${(0, ui_1.bold)("exports.minRole = 'developer'")} raises the
-role the visitor needs. The address is printed for every deployed function; it is not a
-secret, the application bundle carries it.
+  { "projectId": "…", "functions": { "book-slot": { "callers": ["zapis", "clinic-landing"] } } }
 
-Under the table, when there are any: the standalone functions of the organization this
-project calls by the same name. Their code lives elsewhere, so reaching them from here
-takes ${(0, ui_1.bold)('--project <id>')}, which is printed next to each.
+A caller is an app folder of this project (apps/zapis is "zapis") or the name of a page of
+the organization. A function nobody lists has no callers: a workflow, woken by a schedule,
+by a service holding a key a person issued, or by ${(0, ui_1.bold)('invoke')}. ${(0, ui_1.bold)('open')} in the list means a
+caller is public (a page, or an app anyone with the link opens), so anyone on the internet
+can call it. The address in the note under the table is for webhooks and other functions,
+with a key; apps and pages call ${(0, ui_1.bold)('/_fn/<name>')} on their own address.
 
-${(0, ui_1.bold)('invoke')} 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.
+${(0, ui_1.bold)('invoke')} calls it as the person who owns the key: the platform checks the role, gives
+the function a one-minute ticket and calls it itself, so the function sees
+${(0, ui_1.bold)("event.xflow.caller === 'platform'")} and the person in ${(0, ui_1.bold)('event.xflow.user')}.
 
   --data '{"a":1}'        request body (the method becomes POST by default)
   --data-file body.json   the same body from a file
@@ -602,16 +633,17 @@ strips double quotes from a native call, so ${(0, ui_1.bold)('--data')} needs th
 (${(0, ui_1.bold)('--data \'{\\"a\\":1}\'')}) and a file needs nothing.
 
 Prints the status, the response time and the body; under ${(0, ui_1.bold)('--json')} the body
-alone. 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>')}.`,
+alone. A non-zero exit code on 4xx and 5xx: in CI such a call has to fail the step. A
+refusal of the guard names its reason in the body (${(0, ui_1.bold)('not_bound')}, ${(0, ui_1.bold)('no_access')},
+${(0, ui_1.bold)('functions_stopped')}); for a crash the hint points at ${(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.
+database, applies migrations, calls functions, sets schedules, publishes app builds, reads
+logs. The commands stay: code, builds and functions deploys 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
@@ -651,53 +683,57 @@ Plus a few pointer lines in ${(0, ui_1.bold)('AGENTS.md')}. A skill is picked up
 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.`,
-    dev: `${(0, ui_1.bold)('xflow dev')}: run the application on this machine
+    dev: `${(0, ui_1.bold)('xflow dev')}: run an app on this machine
 
-Runs ${(0, ui_1.bold)('npm run dev')} in the project folder (127.0.0.1:3000) with the access key of the
-organization that holds the project. The dev server trades that key for a visitor pass,
-so the cloud functions answer here the way they do on the platform. The key is picked
-as for every other command (${(0, ui_1.bold)('xflow help org')}): with several organizations signed
-in, the right one is found and the folder is bound to it.
+Runs ${(0, ui_1.bold)('npm run dev')} in the app folder it stands in (127.0.0.1:3000) with the access key
+of the organization that holds the project. Every ${(0, ui_1.bold)('/_fn/<name>')} call of the app goes to
+the platform as this app, so the callers, the access and the person calling are the same
+as on its address. Nothing about functions is kept on this machine: a function someone
+else shipped answers here at once.
 
-Use it instead of a bare ${(0, ui_1.bold)('npm run dev')}: that one is handed no key, so its calls to
-cloud functions fail. In a project made before this command the failure reads "No access
-key for the platform: run xflow login", and signing in will not help, because the key is
-no longer left in a file for that dev server to pick up.
-
-The platform address comes from the CLI too, not from .env, so the key goes to the
-platform that issued it and nowhere else. It never reaches the browser: the page gets
-only the ${(0, ui_1.bold)('VITE_')} variables. The project token and the function addresses are
-fetched on every start as well: a function someone else shipped answers here without a
-deploy of yours.
+Use it instead of a bare ${(0, ui_1.bold)('npm run dev')}: that one is handed no key and no app id, so
+its calls to functions fail. The platform address comes from the CLI too, so the key goes
+to the platform that issued it and nowhere else. It never reaches the browser.
 
 The server listens on 127.0.0.1 and nowhere else, because it holds that key: on a
 shared network, anything else would let a neighbour call the functions of the project
 as you. A phone on the same Wi-Fi therefore cannot open it either.`,
-    pull: `${(0, ui_1.bold)('xflow pull')}: fetch the sources
+    pull: `${(0, ui_1.bold)('xflow pull')} [functions|apps/<folder>]: 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.
+Every app and the project root are separate histories, and pull fetches one of them: in an
+app folder that app, in the project root the root (apps/ stays as it is), or the one named.
+It refuses to write into a non-empty folder: 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)
+  --into <dir>       unpack alongside, to compare; in the project root with nothing named
+                     it fetches the whole project there
+  --revision <N>     a specific revision of that history (xflow deployments lists them)
   --force            overwrite the folder completely`,
-    deploy: `${(0, ui_1.bold)('xflow deploy')}: build and release
+    deploy: `${(0, ui_1.bold)('xflow deploy')}: deploy the functions or build an app, then publish
+
+  xflow deploy functions -m "…"       send the project root, check it, ship the functions
+                                      and their callers
+  xflow deploy apps/<folder> -m "…"   send one app and build it; inside its folder a plain
+                                      xflow deploy does the same
+  xflow publish [build]               point the app address at the newest build, or a named one
+  xflow rollback <build>              the same, the number required
+  xflow deployments [functions]       the builds of the app, or the deploys of the functions
 
-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).
+In the project root a plain ${(0, ui_1.bold)('xflow deploy')} refuses and names the targets: functions and
+apps never go in one run, because a change of functions reaches every app at once.
 
   -m <text>          the version comment, required: one short line in the language the
-                     user speaks, saying what changed. It names the version in the
-                     history (--message is the long form)
+                     user speaks, saying what changed (--message is the long form)
   --no-push          do not send sources, build from the latest server revision
-  --revision <N>     build a revision the platform already holds: this is how a
-                     version comes back (the list: xflow deployments)
-  --project <id>     with --revision only: the project to rebuild, no folder needed
+  --revision <N>     run a revision the platform already holds: that is how the functions
+                     come back (xflow deployments functions lists them)
+  --project <id>     with --revision only: the functions of that project, no folder needed
+  --app <id>         with --revision only: that app, no folder needed
   --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,
+What goes up: an app sends its own folder; the project root sends everything but apps/,
+plus the apps/<folder>/xflow.json files its callers are read from. Never sent: node_modules,
 .git, dist, build, .next, any .env, plus everything listed in .xflowignore and in the
 ignore field of xflow.json.
 
@@ -711,20 +747,21 @@ CLI shows whose work you are about to destroy and asks for confirmation by typin
 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
+The platform builds, in a clean sandbox on one Node version for everybody. Before that the
+sources are checked: what breaks silently (the platform files, the calls in the entry point,
+keys in the code, alert instead of a dialog) is printed as a list and nothing starts. What is
+merely unfinished (the template page title, no icon) goes through and prints a line
+${(0, ui_1.bold)('Unfinished:')}. Fix it before telling the person the app is done.
+
+${(0, ui_1.bold)('deploy functions')} bundles everything in ${(0, ui_1.bold)('functions/<name>/index.ts')}. A function whose
+code and variables did not change is left alone, and one that fails to ship fails the whole
+deploy. It then records the callers and prints which functions are open to the whole
+internet now. A change that touches data and screens goes in this order: the migration,
+the functions, then every app that shows it; an app deploy warns when the root holds
+changes nobody deployed.
+
+A function gone from the sources would be deleted from the cloud along with its keys and
+schedules, and that is final. So the deploy 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
@@ -733,60 +770,26 @@ ${(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.
-
-${(0, ui_1.bold)('--revision <N>')} brings a version back. The sources of that revision are already on
-the server, so nothing goes up, no copy of them is needed next to you and the newest
-revision stays the newest: this build simply runs an older one. Since there is no folder
-to stand in, the project can be named by id (${(0, ui_1.bold)('--project')}), and for a standalone
-function that is the only way back: it has no pages, so ${(0, ui_1.bold)('xflow rollback')} has nothing
-to return. Functions that exist now but not in that revision would be removed, and the
-same question is asked as in any other deploy.`,
-    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')}): app
-shell, page header, section, toolbar, list, empty state, stats, detail card, form rows,
-card grid, timeline, table, charts. Projects created in the web get the same template,
-which is what makes the applications look alike.
-
-Building the interface on top of these components and the tokens in ${(0, ui_1.bold)('src/index.css')}
-is not a formality: your own palette on top of them looks foreign inside the platform.
+A build of an app is not shown to visitors until ${(0, ui_1.bold)('xflow publish')}: publishing points the
+app address at a build and takes a second, and an older kept build is the rollback. Only
+the app moves: the functions and the database are one per project and stay as they are.
+The very first build of a new app publishes itself. The files of the three latest builds
+are kept; ${(0, ui_1.bold)('xflow deployments')} marks the rest "no pages". Give a person the app address
+the CLI prints, and name builds by their number.`,
+    init: `${(0, ui_1.bold)('xflow init')} [dir]: a new project with its first app
+
+Creates the project on the platform and lays out its folder: the root xflow.json, a
+package.json for the functions, empty ${(0, ui_1.bold)('functions/')} and ${(0, ui_1.bold)('migrations/')}, and the first app in
+apps/<folder> from the platform template: React on Vite, Tailwind, components in
+${(0, ui_1.bold)('src/components/ui')} and blocks in ${(0, ui_1.bold)('src/components/blocks')}. Those are a starting set:
+change them, restyle them or delete what you do not use.
 
   --name <name>       project name (the folder name by default)
-  --function          a standalone function instead of an application
-  --template <id>     a different template (the list: xflow templates)
-  --database <id>     attach a logical database of the organization (the list: xflow db list)
-  --server <name>     a new database for the project, right away on that server:
+  --app <folder>      the folder of the first app (made from the name by default)
+  --no-app            a project without apps: its functions are workflows
+  --server <name>     the database of the project, right away on that server:
                       platform, or an own server of the organization (xflow db list)
 
-${(0, ui_1.bold)('--function')} makes a shared backend of the organization: a project without a site,
-with one handler in ${(0, ui_1.bold)('functions/<name>/index.ts')} and no template to fetch. Any
-application of the organization calls it; who exactly is allowed in is decided by
-${(0, ui_1.bold)('minRole')} inside the function. It builds and releases with the same deploy, but
-there are no pages to publish, so publish and rollback do not apply to it.
-
-Without either flag the project gets its database with the first migration, on the
-platform server. ${(0, ui_1.bold)('--server')} decides it up front: the server has to be running, and
-the database counts against the plan at once.
-
-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.
-
-Visitors keep seeing the published pages until ${(0, ui_1.bold)('xflow publish')} is run.`,
+More apps later: ${(0, ui_1.bold)('xflow apps add <folder>')}. If writing the files fails, the project stays
+on the platform and the CLI says how to pick it up with the link command.`,
 };