@getxflow/cli 0.1.8 → 0.1.10

package/dist/help.js

@@ -3,265 +3,264 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.help = help;
 const ui_1 = require("./ui");
 const version_1 = require("./version");
-/**
- * Справка. Заменяет агенту машинную документацию: у CLI её роль играет `--help`,
- * поэтому текст пишем так, чтобы по нему можно было работать, не открывая сайт.
- */
+/** Help text. For agents this is the reference documentation. */
 function help(topic) {
     if (topic && TOPICS[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
-
-${(0, ui_1.bold)('Начало работы')}
-  xflow login                     вход через браузер
-  xflow init [папка]              новый проект из шаблона платформы
-  xflow templates                 какие шаблоны доступны
-  xflow link <id>                 связать текущую папку с проектом (id: xflow projects list)
-  xflow skills [--global]         обновить инструкцию о платформе для ИИ-агента
-  xflow mcp install               доступ к платформе для агента без терминала
-
-${(0, ui_1.bold)('Код')}
-  xflow status                    что на сервере и чем отличается локальная копия
-  xflow push [--force]            отправить исходники новой ревизией
+    (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 [--global]         refresh the platform instructions for an AI agent
+  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]
-                                  забрать исходники (по умолчанию последнюю ревизию)
-
-${(0, ui_1.bold)('Выкладка')}
-  xflow deploy [--no-push]        отправить код, собрать на платформе и выложить на dev
-  xflow publish                   показать dev-версию посетителям
-  xflow rollback <номер версии>    вернуть проект на прошлую версию
-  xflow deployments               история версий
-
-${(0, ui_1.bold)('Функции')}
-  xflow functions list            что выложено
-  xflow functions deploy [имя]    собрать и выкатить функцию
-  xflow functions invoke <имя> [--data '{"a":1}']
-                                  вызвать функцию и показать ответ
-  xflow functions logs [имя]      падения функций: стек и вывод консоли
-  xflow schedules list            что запускается по времени
-  xflow schedules set <имя> "0 3 ? * * *"
-                                  запускать функцию по расписанию (UTC)
-  xflow schedules rm <имя>        снять расписание
-  xflow env [check]               переменные функций: что записано, чего не хватает
-  xflow env set ИМЯ=значение      записать переменную
-  xflow env rm ИМЯ                удалить переменную
-
-${(0, ui_1.bold)('База данных')}
-  xflow db status                 какие миграции применены, а какие ждут
+                                  fetch the sources (the latest revision by default)
+
+${(0, ui_1.bold)('Releasing')}
+  xflow deploy [--no-push]        send the code, build on the platform, release to dev
+  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
+  xflow functions deploy [name]   build and ship a function
+  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 migrate [--dry-run] [--allow-destructive]
-                                  применить миграции из migrations/*.sql
+                                  apply the migrations from migrations/*.sql
 
-${(0, ui_1.bold)('Справочное')}
-  xflow logs [--limit N]          ошибки выложенного приложения в браузере
-  xflow projects list             проекты организации
-  xflow projects get [id]         карточка проекта
-  xflow whoami                    чей ключ и что он может
-  xflow logout                    забыть ключ
+${(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
 
-${(0, ui_1.bold)('Окружение')}
-  XFLOW_TOKEN                     ключ доступа (для CI: вместо xflow login)
-  XFLOW_API_URL                   адрес платформы, если он не app.getxflow.com
+${(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
 
-Подробнее о команде: xflow help <команда>`);
+More about one command: xflow help <command>`);
 }
 const TOPICS = {
-    db: `${(0, ui_1.bold)('xflow db migrate')} — применить миграции
+    db: `${(0, ui_1.bold)('xflow db migrate')}: apply migrations
 
-Файлы лежат в репозитории: ${(0, ui_1.bold)('migrations/0001_init.sql')}, ${(0, ui_1.bold)('migrations/0002_orders.sql')} и так
-далее. Порядок — по имени файла, поэтому номер в начале обязателен. Каждая миграция
-применяется своей транзакцией, история хранится в самой базе, и повторно применённое
-не запускается.
+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              показать, что применится, и не трогать базу
-  --allow-destructive    разрешить операции, уничтожающие данные
+  --dry-run              report what would be applied without touching the database
+  --allow-destructive    allow operations that destroy data
 
-Про разрушающие. Истории базы платформа не хранит и бэкапов не делает, поэтому
-${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} и ${(0, ui_1.bold)('DELETE FROM')} без условия
-отклоняются без явного флага. С флагом содержимое затронутых таблиц уезжает в дамп
-и хранится 7 суток — это страховка «сразу заметил», а не резервная копия.
-${(0, ui_1.bold)('DROP DATABASE')} не пропускается никогда: база общая для организации.
+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 are rejected unless the flag is given. With the flag, 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)('xflow db status')} такой файл покажет отдельно — заводите новую
-миграцию.
+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.
 
-Одна логическая база может быть привязана к нескольким проектам, поэтому в истории
-попадаются миграции, которых нет в вашем репозитории. Это нормально, но означает,
-что ваша миграция может сломать чужое приложение.`,
-    logs: `${(0, ui_1.bold)('xflow logs')} и ${(0, ui_1.bold)('xflow functions logs')} — ошибки проекта
+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
 
-Один поток на проект: падения выложенного приложения в браузере и падения
-облачных функций. Хранятся последние 200 записей, дальше вытесняются.
+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          сколько показать (по умолчанию 10)
+  --limit N          how many to show (10 by default)
 
-Функция сообщает о падении сама: свои логи Yandex наружу отдаёт только по gRPC,
-поэтому обёртка ловит исключение, уносит вместе с ним хвост консоли (последние 40
-строк ${(0, ui_1.bold)('console.log')} этого вызова) и отправляет на платформу. Успешные вызовы не
-пишут ничего: иначе каждый запрос платил бы за это задержкой.
+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.
 
-Не попадёт сюда: падение на старте модуля (функция не успевает дойти до обёртки),
-превышение 30 секунд и нехватка памяти. Такое видно ответом на
-${(0, ui_1.bold)('xflow functions invoke')}.
+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')}.
 
-Ошибки браузера собирает ${(0, ui_1.bold)('src/utils/error-logger.ts')} шаблона и только с
-выложенных адресов: локальный ${(0, ui_1.bold)('npm run dev')} сюда не пишет.`,
-    env: `${(0, ui_1.bold)('xflow env')} — переменные окружения функций
+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                        что записано (имена, не значения)
-  xflow env check                  чего не хватает функциям этого проекта
-  xflow env set SMTP_PASSWORD=…    записать
-  xflow env rm SMTP_PASSWORD       удалить
+  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                  видно только этому проекту, а не всей организации
+  --scope project                  visible to this project only, not the whole organization
 
-${(0, ui_1.bold)('check')} читает исходники в ${(0, ui_1.bold)('functions/')} и ищет обращения ${(0, ui_1.bold)('process.env.ИМЯ')}. Это же
-правило действует на выкатке: функция получает только те переменные, которые сама
-упоминает по имени. Имя, собранное выражением (${(0, ui_1.bold)("process.env['KEY_' + n]")}), в окружение
-не попадёт — читайте переменные буквально.
+${(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.
 
-Значение доезжает до функции на выкатке, а не в момент записи: после ${(0, ui_1.bold)('env set')} нужно
-${(0, ui_1.bold)('xflow functions deploy')} затронутых функций. То же и после удаления: в уже выложенной
-функции старое значение останется до следующей выкатки.`,
-    schedules: `${(0, ui_1.bold)('xflow schedules')} — запуск функций по времени
+The value reaches the function on deploy, not at the moment it is stored: after
+${(0, ui_1.bold)('env set')} you need ${(0, ui_1.bold)('xflow functions deploy')} for the functions involved. 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
 
-Расписание это таймер-триггер Yandex: он зовёт функцию сам, без участия
-приложения и браузера.
+A schedule is a Yandex timer trigger: it calls the function itself, with no
+application and no browser involved.
 
-  xflow schedules set отчёт "0 3 ? * * *"     каждый день в 03:00
-  xflow schedules set сводка "0 */4 ? * * *"  каждые 4 часа
-  xflow schedules rm отчёт                    снять все расписания функции
+  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
 
-Формат из шести полей: ${(0, ui_1.bold)('минуты часы день-месяца месяц день-недели год')}. Ровно одно
-из полей «День месяца» и «День недели» должно быть ${(0, ui_1.bold)('?')} — это не наша причуда, так
-устроен Яндекс. ${(0, ui_1.bold)('Время всегда UTC')}, местное он не знает.
+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 '{"режим":"полный"}'   тело, которое получит функция
+  --payload '{"mode":"full"}'      the body the function will receive
 
-Запуск по расписанию приходит хендлеру как POST без заголовков, и токен проекта
-у него не проверяется: снаружи такое событие не подделать. Функция при этом должна
-быть уже выложена — расписание ссылается на неё, а не наоборот.
+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.
 
-Упавший запуск виден в ${(0, ui_1.bold)('xflow functions logs')}: по расписанию за функцией никто не
-смотрит, поэтому обёртка отчитывается о падении так же, как при обычном вызове.`,
-    invoke: `${(0, ui_1.bold)('xflow functions invoke')} <имя> — вызвать функцию
+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
 
-Вызывает так же, как её вызывает приложение: с заголовком X-Project-Token.
-Токен берётся из карточки проекта на платформе, локальный .env не нужен.
+Calls it exactly the way the application does, with the X-Project-Token header. The
+token is taken from the project card on the platform, no local .env is needed.
 
-  --data '{"a":1}'   тело запроса (по умолчанию метод становится POST)
-  --method GET       другой метод
+  --data '{"a":1}'   request body (the method becomes POST by default)
+  --method GET       a different method
 
-Печатает статус, время ответа и тело. Ненулевой код возврата на статусе 4xx и
-5xx: в CI такой вызов должен ронять шаг. Причину падения показывает
-${(0, ui_1.bold)('xflow functions logs <имя>')}.`,
-    mcp: `${(0, ui_1.bold)('xflow mcp install')} — подключить агента к платформе напрямую
+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
 
-Прописывает сервер MCP в конфигурацию клиента, у которого есть своя команда
-подключения: сегодня это Claude Code, остальным команда покажет, что вписать
-руками. После этого агент управляет платформой без терминала: смотрит базу,
-применяет миграции, выкладывает и вызывает функции, ставит расписания, читает
-логи. Команды остаются: код, сборку и выкладку по-прежнему делает CLI, гнать
-исходники через MCP значит забивать контекст агента и тратить ваши деньги.
+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    всё же показать ключ (не под агентом)
+  --show-token    print the key anyway (not while under an agent)
 
-Ключ один на человека в организации, и область у него не сужается: агент видит
-все проекты организации и называет нужный сам. Проект он берёт из аргумента
-${(0, ui_1.bold)('project_id')}, а не из вашей папки — папки он не видит.`,
-    skills: `${(0, ui_1.bold)('xflow skills')} — инструкция о платформе для ИИ-агента
+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
 
-Про XFlow агенту знать неоткуда: в его обучении платформы нет. Инструкция объясняет,
-как выкладывать и публиковать, откуда брать компоненты дизайн-системы, где смотреть
-ошибки прода. ${(0, ui_1.bold)('init')} и ${(0, ui_1.bold)('link')} раскладывают её сами — эта команда нужна, чтобы
-обновить её после обновления CLI: они едут одной версией.
+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, so this command is for refreshing them after a CLI update: the two
+ship as one version.
 
-Формат общий (agentskills.io), а папки у инструментов разные, поэтому кладём во все:
+The format is shared (agentskills.io) but the folders differ per tool, so we write all:
 
   .claude/skills/xflow/SKILL.md    Claude Code
   .agents/skills/xflow/SKILL.md    Codex, OpenClaw
-  .cursor/rules/xflow.mdc          Cursor: общий формат он не читает
-
-  --global    то же в домашней папке, тогда скилл виден во всех проектах.
-              Там добавляется ~/.codex/skills: общий каталог Codex смотрит
-              только внутри репозитория. Правило Cursor и AGENTS.md остаются
-              проектными, глобальных аналогов у них нет
-
-Плюс несколько строк-указателей в ${(0, ui_1.bold)('AGENTS.md')}. Скилл подхватывается лениво, только
-когда описание совпало с задачей, и на «добавь таблицу клиентов» он не сработает.
-AGENTS.md агент читает всегда, поэтому указатель дописывается туда — в конец файла и
-один раз. ${(0, ui_1.bold)('CLAUDE.md')} не трогаем: Claude Code и так читает .claude/skills.`,
-    push: `${(0, ui_1.bold)('xflow push')} — отправить исходники
-
-Уходит вся рабочая копия целиком, одной ревизией. Не отправляются: node_modules,
-.git, dist, build, .next, любые .env, а также всё, что перечислено в .xflowignore
-и в поле ignore файла xflow.json.
-
-Если на сервере ревизия новее той, от которой вы работали, push отклоняется.
-Это значит, что кто-то запушил раньше: заберите его правки рядом
-(${(0, ui_1.bold)('xflow pull --into ./server-copy')}), сведите их у себя в git и повторите.
-
---force перетирает серверную ревизию. Перед этим CLI показывает, чью работу вы
-затираете, и просит подтверждение вводом имени проекта. В неинтерактивном режиме
-(CI, запуск агентом) подтвердить нельзя: расхождение версий должно ронять сборку,
-а не молча уничтожать чужую работу.`,
-    pull: `${(0, ui_1.bold)('xflow pull')} — забрать исходники
-
-По умолчанию забирает последнюю ревизию в папку проекта и отказывается писать в
-непустую: слить изменения платформа не умеет, это работа git.
-
-  --into <папка>     выгрузить рядом, чтобы сравнить
-  --revision <N>     конкретная ревизия (список: xflow deployments)
-  --force            перезаписать папку целиком`,
-    deploy: `${(0, ui_1.bold)('xflow deploy')} — собрать и выложить
-
-Два шага: отправка исходников и сборка на платформе. Команда сборки и каталог
-результата берутся из xflow.json (по умолчанию npm run build и dist).
-
-  --no-push       не отправлять исходники, собрать из последней серверной ревизии
-  --force         разрешить перезапись серверной ревизии при отправке
-
-Собирает платформа, в чистой песочнице с одинаковой для всех версией Node,
-поэтому «у меня работало» больше не зависит от вашей машины. Перед сборкой
-проект проверяется на соответствие шаблону: несоответствия печатаются списком,
-и сборка не запускается вовсе.
-
-Собранную версию видно на странице проекта, ссылку CLI печатает. Посетителям — после
-${(0, ui_1.bold)('xflow publish')}. Адрес самой сборки не печатается: в нём зашит номер версии, и
-после следующей публикации такая ссылка молча отдаёт старую копию.`,
-    init: `${(0, ui_1.bold)('xflow init')} [папка] — новый проект
-
-Разворачивает шаблон платформы: React на Vite, Tailwind, набор компонентов
-(${(0, ui_1.bold)('src/components/ui')}) и готовые блоки (${(0, ui_1.bold)('src/components/blocks')}) — таблица,
-форма, фильтры, канбан, графики. Тот же шаблон получают проекты, созданные в вебе,
-поэтому приложения выглядят одинаково.
-
-Строить интерфейс поверх этих компонентов и токенов из ${(0, ui_1.bold)('src/index.css')} — не
-формальность: своя палитра поверх них выглядит чужеродно внутри платформы.
-
-  --name <имя>        имя проекта (по умолчанию — имя папки)
-  --template <id>     другой шаблон (список: xflow templates)
-  --database <id>     привязать логическую базу организации
-
-Порядок: проект заводится на платформе первым, потому что без него неоткуда взять
-токен для .env. Если запись файлов сорвётся, проект останется пустым, и CLI скажет,
-как подобрать его командой link.`,
-    rollback: `${(0, ui_1.bold)('xflow rollback')} <номер версии> — вернуть прошлую сборку
-
-Переключает проект на выбранную сборку. Возвращается только она: исходники
-остаются на своей ревизии, и вернуть их — отдельное решение
-(${(0, ui_1.bold)('xflow pull --revision N --into ./старая-версия')}).
-
-Посетители продолжают видеть опубликованную версию, пока не выполнен
-${(0, ui_1.bold)('xflow publish')}.`,
+  .cursor/rules/xflow.mdc          Cursor: it does not read the shared format
+
+  --global    the same in the home folder, which makes the skill visible in every
+              project. There ~/.codex/skills is added as well, because Codex looks in
+              its shared catalog only inside a repository. The Cursor rule and
+              AGENTS.md stay per project, they have no global counterpart
+
+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
+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)
+  --force            overwrite the folder completely`,
+    deploy: `${(0, ui_1.bold)('xflow deploy')}: build and release
+
+Two steps: sending the sources and building on the platform. 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
+
+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.
+
+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
+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')}).
+
+Visitors keep seeing the published version until ${(0, ui_1.bold)('xflow publish')} is run.`,
 };

package/dist/limits.js

@@ -0,0 +1,68 @@
+"use strict";
+/** Plan limits in CLI output: whoami and command refusals. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.limitLine = limitLine;
+exports.quotaRows = quotaRows;
+const DENIAL_LABELS = {
+    limit_projects: 'projects',
+    limit_functions: 'cloud functions',
+    limit_builds: 'builds this month',
+    limit_seats: 'seats in the organization',
+    limit_schedule_interval: 'schedule frequency',
+    db_write_locked: 'database volume, writes are off',
+    plan_no_schedules: 'schedules',
+    subscription_blocked: 'the subscription is unpaid',
+    billing_unavailable: 'plan check',
+};
+/** Why repeating the same command will not help. */
+function limitLine(detail) {
+    const label = DENIAL_LABELS[detail.code] ?? detail.code;
+    const numbers = detail.used !== undefined && detail.limit !== undefined
+        ? `, ${detail.used} of ${detail.limit} used`
+        : '';
+    return `Plan limit: ${label}${numbers}. Repeating the same command will not help.`;
+}
+const QUOTA_ORDER = [
+    'projects',
+    'functions',
+    'developers',
+    'members',
+    'database_mb',
+    'files_mb',
+    'function_minutes',
+    'builds',
+];
+const QUOTA_LABELS = {
+    projects: 'Projects',
+    functions: 'Cloud functions',
+    developers: 'Developers',
+    members: 'Staff',
+    database_mb: 'Database',
+    files_mb: 'Files',
+    function_minutes: 'Function minutes',
+    builds: 'Builds this month',
+};
+/** Decimal units, 1000 MB per GB: matches how volumes are sold. */
+function sizeLabel(mb) {
+    if (mb < 1000)
+        return `${Math.round(mb)} MB`;
+    const gb = mb / 1000;
+    return `${Number.isInteger(gb) ? String(gb) : gb.toFixed(1)} GB`;
+}
+function quotaValue(key, use) {
+    // Same unit on both sides: "0.2 of 15 GB", not "245 of 15360".
+    if (key.endsWith('_mb')) {
+        const used = use.limit >= 1000 ? (use.used / 1000).toFixed(1) : String(use.used);
+        return `${used} of ${sizeLabel(use.limit)}`;
+    }
+    return `${use.used} of ${use.limit}`;
+}
+/** Unknown keys stay visible: the server may add new ones. */
+function quotaRows(quotas) {
+    const known = QUOTA_ORDER.filter((key) => quotas[key]);
+    const rest = Object.keys(quotas).filter((key) => !QUOTA_ORDER.includes(key));
+    return [...known, ...rest].map((key) => [
+        `  ${QUOTA_LABELS[key] ?? key}`,
+        quotaValue(key, quotas[key]),
+    ]);
+}