@getxflow/cli 0.25.0 → 0.27.0

package/dist/bin.js

@@ -26,6 +26,7 @@ const schedules_1 = require("./commands/schedules");
 const skills_1 = require("./commands/skills");
 const sources_1 = require("./commands/sources");
 const storage_1 = require("./commands/storage");
+const pages_1 = require("./commands/pages");
 const deploy_1 = require("./commands/deploy");
 const dev_1 = require("./commands/dev");
 const update_1 = require("./commands/update");
@@ -194,6 +195,28 @@ async function run(args) {
                 return;
             }
             throw new errors_1.CliError(`Unknown command: storage ${second}`, 'Available: ls, push and rm');
+        case 'pages':
+            if (second === 'create') {
+                await (0, pages_1.pagesCreate)(rest);
+                return;
+            }
+            if (second === 'deploy') {
+                await (0, pages_1.pagesDeploy)(rest);
+                return;
+            }
+            if (second === 'status') {
+                await (0, pages_1.pagesStatus)(rest);
+                return;
+            }
+            if (second === 'rollback') {
+                await (0, pages_1.pagesRollback)(rest);
+                return;
+            }
+            if (second === undefined || second === 'list') {
+                await (0, pages_1.pagesList)(rest);
+                return;
+            }
+            throw new errors_1.CliError(`Unknown command: pages ${second}`, 'Available: list, create, deploy, status and rollback');
         case 'status':
             await (0, sources_1.status)();
             return;
@@ -294,11 +317,15 @@ async function main() {
                 (0, ui_1.fatalNote)((0, ui_1.dim)(`  ${(0, limits_1.limitLine)(e.limit)}`));
             if (e.hint)
                 (0, ui_1.fatalNote)((0, ui_1.dim)(`  ${e.hint}`));
+            if (e.code === 'unauthorized' && process.env.XFLOW_TOKEN?.trim()) {
+                // Signing in again changes nothing here: the stored key is not the one being sent.
+                (0, ui_1.fatalNote)((0, ui_1.dim)('  XFLOW_TOKEN is set, so that is the key refused: put the current one there'));
+            }
             if (e.code === 'not_found') {
                 // XFLOW_TOKEN is taken as given and no organization is looked for, so a
                 // project of another one answers "not found" with nothing else to say.
                 if (process.env.XFLOW_TOKEN?.trim()) {
-                    (0, ui_1.fatalNote)((0, ui_1.dim)('  XFLOW_TOKEN is set: it is the key of one organization and is used as it comes, so a project of another one is not found'));
+                    (0, ui_1.fatalNote)((0, ui_1.dim)('  XFLOW_TOKEN is set: it is the key of one organization and is used as it comes, so a project or a page of another one is not found'));
                 }
                 else if ((0, credentials_1.anyMultipleOrgs)()) {
                     (0, ui_1.fatalNote)((0, ui_1.dim)('  Several organizations are signed in: the answer may live in another one, see xflow org'));

package/dist/commands/deploy.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.versionComment = versionComment;
 exports.deploy = deploy;
 exports.publish = publish;
 exports.rollback = rollback;
@@ -118,21 +119,26 @@ async function assertBuildAllowed(client, projectId) {
 const MAX_COMMENT_LENGTH = 200;
 /** Control and bidi-override characters: they spoof terminals, not comments. */
 const COMMENT_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/** The version comment as typed after -m, cleaned; empty when there is none. Pages take the same. */
+function versionComment(raw) {
+    const comment = (raw ?? '')
+        .replace(/\s+/g, ' ')
+        .replace(COMMENT_CONTROL_CHARS, '')
+        .trim();
+    if (comment.length > MAX_COMMENT_LENGTH) {
+        throw new errors_1.CliError(`The version comment is too long: ${MAX_COMMENT_LENGTH} characters at most`, 'One short line about what changed in this version is enough');
+    }
+    return comment;
+}
 /**
  * The version comment, checked before anything goes up: a refusal after the push
  * would leave the project with a revision newer than its build for no good reason.
  */
 function requireComment(args) {
-    const comment = ((0, args_1.flagString)(args, 'message') ?? '')
-        .replace(/\s+/g, ' ')
-        .replace(COMMENT_CONTROL_CHARS, '')
-        .trim();
+    const comment = versionComment((0, args_1.flagString)(args, 'message'));
     if (!comment) {
         throw new errors_1.CliError('Every version needs a comment saying what changed in it', 'Add -m: xflow deploy -m "Cart and card payments". One short line, written in the language the user speaks: it names this version in the history');
     }
-    if (comment.length > MAX_COMMENT_LENGTH) {
-        throw new errors_1.CliError(`The version comment is too long: ${MAX_COMMENT_LENGTH} characters at most`, 'One short line about what changed in this version is enough');
-    }
     return comment;
 }
 async function deploy(args) {

package/dist/commands/pages.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pagesList = pagesList;
+exports.pagesCreate = pagesCreate;
+exports.pagesDeploy = pagesDeploy;
+exports.pagesStatus = pagesStatus;
+exports.pagesRollback = pagesRollback;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const api_1 = require("../api");
+const args_1 = require("../args");
+const config_1 = require("../config");
+const credentials_1 = require("../credentials");
+const errors_1 = require("../errors");
+const session_1 = require("../session");
+const ui_1 = require("../ui");
+const zip_1 = require("../zip");
+const deploy_1 = require("./deploy");
+const storage_1 = require("./storage");
+/**
+ * Pages: public sites of the organization at <name>.xflowpage.ru. They open without
+ * signing in and outside the platform, and an upload is live at once.
+ */
+/** Keep in sync with the platform: a refusal here saves the upload. */
+const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+const MAX_UNPACKED_BYTES = 25 * 1024 * 1024;
+const MAX_FILES = 1000;
+/** Where build tools write the site: named when the folder turns out to be the sources. */
+const BUILD_DIRS = ['dist', 'build', 'out'];
+/** A page belongs to the organization, not to a project: the key is picked as for xflow org members. */
+function pagesClient() {
+    return (0, session_1.connect)((0, config_1.localConfig)());
+}
+function pagePath(ref) {
+    return `/api/v1/pages/${encodeURIComponent(ref)}`;
+}
+function clip(text, max) {
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function stateOf(page) {
+    if (page.status === 'blocked')
+        return 'taken down';
+    if (page.status === 'disabled')
+        return 'switched off';
+    return page.current_revision === null ? 'empty' : 'live';
+}
+function describeState(page) {
+    if (page.status === 'blocked') {
+        const reason = page.blocked_reason ? ': ' + page.blocked_reason : '';
+        return `Taken down by the platform${reason}. Write to team@getxflow.com if it is a mistake`;
+    }
+    if (page.status === 'disabled')
+        return 'Switched off: the address shows a placeholder until a person switches it on';
+    if (page.current_revision === null)
+        return 'Empty: nothing is uploaded yet';
+    return `Live: version ${page.current_revision}, put there ${(0, ui_1.formatAge)(page.deployed_at)}`;
+}
+async function pagesList(args) {
+    const client = pagesClient();
+    const { pages } = await (0, api_1.apiJson)(client, '/api/v1/pages');
+    if ((0, args_1.flagBool)(args, 'json')) {
+        (0, ui_1.out)(JSON.stringify({ pages }, null, 2));
+        return;
+    }
+    if (pages.length === 0) {
+        (0, ui_1.note)('The organization has no pages yet');
+        (0, ui_1.note)((0, ui_1.dim)('  A new one: xflow pages create "Price list" ./dist'));
+    }
+    else {
+        (0, ui_1.table)(pages.map((page) => [
+            page.slug,
+            clip(page.title, 40),
+            stateOf(page),
+            (0, ui_1.formatAge)(page.deployed_at ?? page.created_at),
+            page.url,
+        ]));
+    }
+    const orgs = (0, credentials_1.listOrgs)(client.apiUrl);
+    if (client.source === 'active' && orgs.length > 1) {
+        const name = orgs.find((org) => org.active)?.name;
+        const whose = name ? `"${name}"` : 'the active organization';
+        (0, ui_1.note)((0, ui_1.dim)(`  Pages of ${whose} only. For another organization: xflow org switch <name or id>`));
+    }
+}
+async function pagesCreate(args) {
+    const source = args.words.length > 2 ? args.words[args.words.length - 1] : undefined;
+    const title = args.words.slice(1, -1).join(' ').trim();
+    if (!source || !title) {
+        throw new errors_1.CliError('A title and what to put on the page are required', 'A page is born with its first version: xflow pages create "Price list" ./dist --slug price-list');
+    }
+    const upload = readUpload(source);
+    const slug = (0, args_1.flagString)(args, 'slug');
+    const query = new URLSearchParams(slug ? { title, slug } : { title });
+    (0, ui_1.step)(`Uploading ${upload.label}`);
+    const result = await (0, api_1.apiUpload)(pagesClient(), `/api/v1/pages?${query}`, upload.body, {
+        'Content-Type': contentTypeOf(upload),
+    });
+    (0, ui_1.ok)(`Page "${result.page.title}" is live: ${result.file_count} file(s), ${(0, ui_1.formatBytes)(result.size_bytes)}`);
+    (0, ui_1.out)(result.page.url);
+    (0, ui_1.note)((0, ui_1.dim)(`  Anyone with the address sees it within seconds. The next version: xflow pages deploy ${result.page.slug} <path>`));
+}
+function contentTypeOf(upload) {
+    return upload.kind === 'zip' ? 'application/zip' : 'text/html';
+}
+function assertUploadSize(bytes) {
+    if (bytes <= MAX_UPLOAD_BYTES)
+        return;
+    throw new errors_1.CliError(`The upload is ${(0, ui_1.formatBytes)(bytes)}, a page takes ${MAX_UPLOAD_BYTES / 1024 / 1024} MB at most`, 'Pages are for sites, presentations and invoices: compress the images and drop the sourcemaps');
+}
+/**
+ * The folder of a built site, zipped here. The sources of a site are refused before the
+ * walk: the platform would reject them anyway, and node_modules is a long way down.
+ */
+function zipSite(absolute, source) {
+    const built = BUILD_DIRS.find((dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(absolute, dir, 'index.html')));
+    const pointAtBuild = built
+        ? `The built site is in ${(0, node_path_1.join)(source, built)}: upload that folder`
+        : 'Build it and upload the folder the build writes';
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(absolute, 'package.json'))) {
+        throw new errors_1.CliError(`${source} holds the sources of a site, not a built one`, pointAtBuild);
+    }
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(absolute, 'index.html'))) {
+        throw new errors_1.CliError(`There is no index.html at the top of ${source}`, built ? pointAtBuild : 'The start page of a site is index.html at the top of its folder');
+    }
+    const files = (0, storage_1.collectMedia)(absolute);
+    if (files.length > MAX_FILES) {
+        throw new errors_1.CliError(`${source} holds ${files.length} files, a page takes ${MAX_FILES} at most`, 'Drop what the site never loads');
+    }
+    const bytes = files.reduce((sum, file) => sum + file.size, 0);
+    if (bytes > MAX_UNPACKED_BYTES) {
+        throw new errors_1.CliError(`${source} is ${(0, ui_1.formatBytes)(bytes)}, a page takes ${MAX_UNPACKED_BYTES / 1024 / 1024} MB at most`, 'Compress the images and drop the sourcemaps');
+    }
+    const body = (0, zip_1.zipCreate)(files.map((file) => ({ path: file.remote, content: (0, node_fs_1.readFileSync)(file.absolute) })));
+    assertUploadSize(body.length);
+    return { kind: 'zip', body, label: `${files.length} file(s), ${(0, ui_1.formatBytes)(bytes)}` };
+}
+function readUpload(source) {
+    const absolute = (0, node_path_1.resolve)(source);
+    let stat;
+    try {
+        stat = (0, node_fs_1.statSync)(absolute);
+    }
+    catch {
+        throw new errors_1.CliError(`No such file or folder: ${source}`);
+    }
+    if (stat.isDirectory())
+        return zipSite(absolute, source);
+    const extension = (0, node_path_1.extname)(absolute).toLowerCase();
+    if (extension !== '.html' && extension !== '.htm' && extension !== '.zip') {
+        throw new errors_1.CliError(`${(0, node_path_1.basename)(absolute)} cannot be a page`, 'A page goes up as a folder with index.html at the top, its .zip, or one .html file');
+    }
+    assertUploadSize(stat.size);
+    return {
+        kind: extension === '.zip' ? 'zip' : 'html',
+        body: (0, node_fs_1.readFileSync)(absolute),
+        label: `${(0, node_path_1.basename)(absolute)}, ${(0, ui_1.formatBytes)(stat.size)}`,
+    };
+}
+async function pagesDeploy(args) {
+    const [, ref, source] = args.words;
+    if (!ref || !source) {
+        throw new errors_1.CliError('A page and what to upload are required', 'For example: xflow pages deploy price-list ./dist. The pages: xflow pages');
+    }
+    const comment = (0, deploy_1.versionComment)((0, args_1.flagString)(args, 'message'));
+    const upload = readUpload(source);
+    const client = pagesClient();
+    (0, ui_1.step)(`Uploading ${upload.label}`);
+    const query = comment ? `?comment=${encodeURIComponent(comment)}` : '';
+    const result = await (0, api_1.apiUpload)(client, `${pagePath(ref)}/deploy${query}`, upload.body, {
+        'Content-Type': contentTypeOf(upload),
+    });
+    if (result.status === 'unchanged') {
+        (0, ui_1.ok)(`Nothing changed: version ${result.revision} is already on the address`);
+    }
+    else if (result.status === 'stored') {
+        (0, ui_1.warn)(`The page is switched off: version ${result.revision} is kept, not shown`);
+        (0, ui_1.note)((0, ui_1.dim)('  It goes live when a person switches the page on'));
+    }
+    else {
+        (0, ui_1.ok)(`Version ${result.revision} is live: ${result.file_count} file(s), ${(0, ui_1.formatBytes)(result.size_bytes)}`);
+    }
+    (0, ui_1.out)(result.page.url);
+    if (result.status === 'deployed') {
+        (0, ui_1.note)((0, ui_1.dim)(`  Anyone with the address sees it within seconds. The versions: xflow pages status ${result.page.slug}`));
+    }
+}
+async function pagesStatus(args) {
+    const ref = args.words[1];
+    if (!ref)
+        throw new errors_1.CliError('A page is required', 'The name from its address, or its id. The pages: xflow pages');
+    const data = await (0, api_1.apiJson)(pagesClient(), `${pagePath(ref)}/revisions`);
+    if ((0, args_1.flagBool)(args, 'json')) {
+        (0, ui_1.out)(JSON.stringify(data, null, 2));
+        return;
+    }
+    const { page, revisions } = data;
+    (0, ui_1.out)(`${(0, ui_1.bold)(page.title)}  ${page.url}`);
+    (0, ui_1.out)(describeState(page));
+    if (revisions.length === 0) {
+        (0, ui_1.note)((0, ui_1.dim)(`  Upload: xflow pages deploy ${page.slug} <folder, .zip or .html>`));
+        return;
+    }
+    (0, ui_1.out)();
+    (0, ui_1.table)(revisions.map((revision) => [
+        String(revision.revision),
+        (0, ui_1.formatAge)(revision.created_at),
+        `${revision.file_count} file(s)`,
+        (0, ui_1.formatBytes)(revision.size_bytes),
+        clip(revision.comment ?? '', 60),
+        revision.current ? 'current' : revision.restorable ? '' : 'files removed',
+    ]));
+    (0, ui_1.note)((0, ui_1.dim)(`  Put a version back: xflow pages rollback ${page.slug} <number>. The files of the last 5 are kept`));
+}
+async function pagesRollback(args) {
+    const [, ref, raw] = args.words;
+    if (!ref || !raw) {
+        throw new errors_1.CliError('A page and a version number are required', 'For example: xflow pages rollback price-list 2. The versions: xflow pages status <page>');
+    }
+    const revision = Number(raw);
+    if (!Number.isInteger(revision) || revision < 1) {
+        throw new errors_1.CliError(`A version number is a positive integer, got "${raw}"`, `The versions: xflow pages status ${ref}`);
+    }
+    const { page } = await (0, api_1.apiJson)(pagesClient(), `${pagePath(ref)}/rollback`, {
+        method: 'POST',
+        body: { revision },
+    });
+    if (page.status === 'active')
+        (0, ui_1.ok)(`Version ${revision} is back on the address`);
+    else
+        (0, ui_1.warn)(`The page is switched off: version ${revision} is current and goes live when it is switched on`);
+    (0, ui_1.out)(page.url);
+}

package/dist/commands/storage.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.contentTypeFor = contentTypeFor;
+exports.collectMedia = collectMedia;
 exports.planBatches = planBatches;
 exports.caseCollisions = caseCollisions;
 exports.storageList = storageList;
@@ -74,7 +75,7 @@ function contentTypeFor(name) {
  * what one is asked to put there so it stays out of the 10 MB archive.
  *
  * Dot entries and symlinks are skipped: pointing push at a working copy should
- * not upload .git, and a link is not ours to follow.
+ * not upload .git, and a link is not ours to follow. Pages walk a site the same way.
  */
 function collectMedia(root, prefix = '') {
     const found = [];

package/dist/flags.js

@@ -81,6 +81,12 @@ exports.KNOWN = {
     'storage push': ['to', 'replace', 'json', 'project'],
     'storage rm': ['folder', 'yes', 'project'],
     'storage remove': ['folder', 'yes', 'project'],
+    pages: ['json'],
+    'pages list': ['json'],
+    'pages create': ['slug'],
+    'pages deploy': ['message'],
+    'pages status': ['json'],
+    'pages rollback': [],
     status: [],
     dev: [],
     pull: ['into', 'force', 'revision'],
@@ -127,6 +133,7 @@ const NAMESPACES = new Set([
     'schedules',
     'db',
     'storage',
+    'pages',
     'mcp',
 ]);
 /** The command these words name, as far as the table knows it. */

package/dist/help.js

@@ -89,6 +89,15 @@ ${(0, ui_1.bold)('Database')}
   xflow db migrate [--dry-run] [--allow-destructive]
                                   apply the migrations from migrations/*.sql
 
+${(0, ui_1.bold)('Pages')}
+  xflow pages                     public sites of the organization at <name>.xflowpage.ru
+  xflow pages create <title> <folder|.zip|.html> [--slug name]
+                                  a new page with the site on it, live at once
+  xflow pages deploy <page> <folder|.zip|.html> [-m "what changed"]
+                                  upload the site: live at once, there is no publish step
+  xflow pages status <page>       the page and its versions
+  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 projects list             projects of the organization
@@ -202,6 +211,58 @@ active one outside. With several signed in, a line under the table says whose
 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.
+
+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.
+
+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')}.`,
+    pages: `${(0, ui_1.bold)('xflow pages')}: public sites of the organization
+
+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.
+
+  xflow pages                          the pages, their state and address
+  xflow pages create <title> <path>    a new page with its first version: there are no
+                                       empty pages
+      --slug <name>                    the name in the address; without it the name is made
+                                       from the title, with a random tail
+  xflow pages deploy <page> <path>     upload a new version
+      -m <text>                        what changed, one short line: it names the version
+  xflow pages status <page>            the page and its versions
+  xflow pages rollback <page> <N>      put version N back on the address
+
+${(0, ui_1.bold)('<path>')} is a folder with index.html at the top, its .zip, or one .html file.
+${(0, ui_1.bold)('<page>')} is the name from the address or the id. ${(0, ui_1.bold)('--json')} on list and status
+prints the answer as JSON. A page belongs to the organization, not to a project, so there is
+no ${(0, ui_1.bold)('--project')}: the key is picked as for every other command (${(0, ui_1.bold)('xflow help org')}).
+
+${(0, ui_1.bold)('An upload is live at once.')} There is no draft and no publish step: anyone with the
+address sees the new version within seconds. Uploading the same files again changes nothing.
+The files of the last 5 versions are kept, so a rollback takes seconds and needs no upload.
+
+What goes up is the built site: HTML, CSS, JS, images, fonts, PDF, audio and video. No code
+runs on the platform side, and a folder with package.json is refused as the sources of a site:
+build it and upload what the build writes. Dot entries are skipped. At most 5 MB zipped, 25 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 function key is the exception: it opens that one function to every visitor, which is
+what a form on a landing page needs. 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. The
+section is in beta: XFlow support switches it on for an organization. Switching a page off
+and deleting it are for a person, in the platform interface.`,
     update: `${(0, ui_1.bold)('xflow update')}: bring the CLI up to date
 
 Installs the published version and, if anything changed, rewrites the platform

package/dist/version.js

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

package/package.json

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

package/skills/xflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xflow
-description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever the project root has xflow.json or VITE_XFLOW_* variables, and for any task that touches deployment, publishing, rollback, source sync, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, file storage and uploads of photos, video or PDFs, connected accounts of external services, production errors and logs, or UI built on the platform design system.
+description: Build, deploy and publish apps on the XFlow platform with the xflow CLI. Use whenever the project root has xflow.json or VITE_XFLOW_* variables, and for any task that touches deployment, publishing, rollback, source sync, the project database or SQL migrations, cloud functions, schedules, environment variables and secrets, file storage and uploads of photos, video or PDFs, connected accounts of external services, production errors and logs, UI built on the platform design system, or a public page on xflowpage.ru (a landing page, presentation or invoice for people outside the organization).
 ---
 
 # XFlow
@@ -22,7 +22,7 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.25.0, so the copy you are reading can be older than
+These instructions ship with xflow CLI 0.27.0, so the copy you are reading can be older than
 the CLI answering your commands.
 
 When the CLI says this file does not match it, run `xflow skills --refresh` and then **read
@@ -125,9 +125,9 @@ outside the project folder); building it over the current one needs a human.
 
 Pages are kept for the **three latest successful builds** plus whatever dev and live show;
 older versions stay in the history with `pages_kept` false, readable but not openable. The
-history holds the **last 30 builds**, the sources the **last 50 revisions** (a revision a live
-version was built from is never deleted). Three builds is the whole rollback depth, hours on an
-active project: keep anything you must not lose in your own git repository.
+history holds the **last 30 builds**, each keeping the revision it was built from; any other
+revision is kept only while it is among the **10 latest**. Three builds is the whole rollback
+depth, hours on an active project: keep anything you must not lose in your own git repository.
 
 **The only link you give a person is the project page**, `https://app.getxflow.com/projects/<id>`,
 which the CLI prints for you. Refer to builds by their number ("version 481203 is built, 092399
@@ -520,6 +520,34 @@ What the app may do with files is decided inside that function, because the page
 by whoever opened it. Never send the key to the frontend: the build gate stops on a key found in
 the sources, and a key that reached a visitor deletes every file of the project.
 
+## Pages
+
+A page is a public static site at `https://<name>.xflowpage.ru`: a landing page, a
+presentation, an invoice for people outside the organization. Anyone with the address opens it,
+without signing in and outside the platform. A project is the opposite, it opens only inside the
+platform: pick a page when the audience is outside the organization.
+
+- `xflow pages create "Price list" ./dist` makes a page with the built site on it and prints its
+  address: there are no empty pages. `--slug price-list` picks the name, otherwise it comes from
+  the title with a random tail.
+- `xflow pages deploy <page> <folder|.zip|.html> -m "what changed"` uploads a new version.
+- **Both are public the moment the command finishes**: no draft, no publish step. Upload when the
+  user wants the page out, and give them the address the CLI printed.
+- `xflow pages status <page>` lists the versions, `xflow pages rollback <page> <N>` puts one back
+  in seconds; the files of the last 5 are kept.
+- Static files only: HTML, CSS, JS, images, fonts, PDF, audio, video. No server code, database
+  or functions on a page. Upload what the build writes (`dist`), never a folder with
+  `package.json`. At most 5 MB zipped, 25 MB unpacked, 1000 files.
+- Everything in a page is readable by every visitor. Never put a key, token or password into
+  it: a known key format gets the upload refused, anything else simply leaks. A function key is
+  the exception: a person issues it in the settings of the function, and a form on a page may
+  call that function with it. So can every visitor.
+- Search engines are asked not to index pages: do not promise SEO.
+- The MCP `pages` tool uploads one self-contained HTML document up to 150 KB.
+- Pages take the key of the whole organization, the one `xflow login` issues. The section is in
+  beta, switched on per organization by XFlow support: that refusal is not yours to fix. Switching
+  a page off and deleting it are for a person, in the platform interface.
+
 ## Organizations and keys
 
 One key per organization, stored side by side rather than replacing each other: `xflow org`