# Документация xflow

> Как устроен xflow и как с ним работать через AI-агента.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

xflow это платформа, на которой AI-агент собирает веб-приложения и автоматизации для вашей
компании. Агент пишет код, xflow даёт базу данных, облачные функции, интеграции с сервисами,
хостинг и доступ для сотрудников.

## С чего начать

- [Что такое xflow](https://docs.getxflow.com/start/overview.md): что умеет платформа и кому она подходит.
- [Быстрый старт](https://docs.getxflow.com/start/quickstart.md): подключить агента и получить первое приложение.
- [Основные понятия](https://docs.getxflow.com/start/concepts.md): организация, проект, приложение, страница, функция.
- [Установка и вход](https://docs.getxflow.com/cli/install.md): CLI `xflow`, вход и инструкция о платформе для агента.

## AI агент

- [Подключение и права](https://docs.getxflow.com/agent/setup.md): ключ агента и что ему разрешено
- [Как ставить задачи](https://docs.getxflow.com/agent/tasks.md): что агент делает сам и что остаётся вам

## Платформа

- [Проекты](https://docs.getxflow.com/platform/projects.md) и [Приложения](https://docs.getxflow.com/platform/apps.md)
- [База данных](https://docs.getxflow.com/platform/database.md), [Свои серверы баз](https://docs.getxflow.com/platform/db-servers.md), [Функции](https://docs.getxflow.com/platform/functions.md)
- [Страницы](https://docs.getxflow.com/platform/pages.md): публичные сайты организации
- [Файлы](https://docs.getxflow.com/platform/storage.md), [Интеграции](https://docs.getxflow.com/platform/integrations.md), [Переменные и секреты](https://docs.getxflow.com/platform/secrets.md)
- [Участники и доступ](https://docs.getxflow.com/platform/access.md), [Тарифы и лимиты](https://docs.getxflow.com/platform/billing.md)

## Разработка

- [Шаблон приложения](https://docs.getxflow.com/develop/template.md) и [Проверка перед сборкой](https://docs.getxflow.com/develop/build-check.md)
- [Вход в публичном приложении](https://docs.getxflow.com/develop/public-signin.md)
- [Локальный запуск и ошибки](https://docs.getxflow.com/develop/local.md)

## Справочник

- [Команды CLI](https://docs.getxflow.com/cli/commands.md), [xflow.json](https://docs.getxflow.com/reference/xflow-json.md), [Коды ошибок](https://docs.getxflow.com/reference/errors.md), [MCP](https://docs.getxflow.com/reference/mcp.md)

У каждой страницы есть копия в Markdown: добавьте `.md` к адресу без последней косой черты.
Оглавление для агента: [llms.txt](https://docs.getxflow.com/llms.txt), вся документация одним
файлом: [llms-full.txt](https://docs.getxflow.com/llms-full.txt).

---

# Что такое xflow

> Платформа, на которой AI-агент собирает приложения для компании, а сотрудники ими пользуются.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Приложение пишет AI-агент: Claude Code, Codex, Cursor, OpenClaw или любой другой, который умеет
запускать команды в терминале. Всё остальное, что нужно приложению, даёт платформа.

## Что даёт платформа

- **База данных PostgreSQL** у каждого проекта: схему меняет агент миграциями, люди смотрят
  данные на экране проекта.
- **Облачные функции**: серверный код. Запускаются из приложения, по расписанию, по вебхуку
  или кнопкой.
- **Хранилище файлов** для фото, видео и PDF.
- **Интеграции**: Wildberries, Ozon, amoCRM, Яндекс Метрика, Google Таблицы, Telegram и другие.
  Ключи хранятся зашифрованными и в код не попадают.
- **Хостинг**: платформа собирает приложение и выдаёт ему адрес, каждая сборка остаётся версией.
- **Доступ**: приложение открывается участникам проекта или любому по ссылке.

## Как выглядит работа

1. Вы ставите агенту задачу обычными словами: «Сделай дашборд продаж на Wildberries».
2. Агент создаёт проект, пишет код и отправляет его командой `xflow deploy`.
3. Платформа проверяет и собирает код, приложение появляется на своём адресе.
4. Вы открываете доступ команде. Сотрудники работают в приложении, агента они не видят.

Подходит тем, кто автоматизирует процессы компании без своей команды разработки, и тем, кто
уже работает с AI-агентом и хочет, чтобы результат жил на хостинге с базой и доступами, а не
на локальной машине. Данные хранятся в России.

---

# Быстрый старт

> Подключить AI-агента к xflow и получить первое приложение на своём адресе.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Понадобится аккаунт в [xflow](https://app.getxflow.com) и AI-агент, который умеет запускать
команды в терминале.

## 1. Подключите агента

Отправьте агенту одно сообщение:

```text
Подключи xflow по инструкции https://getxflow.com/agent.md
```

Агент сам установит CLI `xflow`, выполнит вход и разложит себе инструкцию о платформе. Шаги:
[Установка и вход](https://docs.getxflow.com/cli/install.md).

## 2. Подтвердите вход

Агент покажет код и ссылку. Откройте ссылку, сверьте код и нажмите «Подтвердить вход». Агент
получит ключ организации без пароля. Подтвердить может Админ или Редактор организации.

## 3. Поставьте задачу

```text
Сделай приложение для учёта заявок: форма для менеджеров, список со статусами,
у каждой заявки ответственный.
```

Агент создаст проект, напишет код и отправит его на сборку. Первая удачная сборка публикуется
сама, агент пришлёт адрес вида `https://a1b2c3--acme.xflowpage.ru`.

## 4. Откройте доступ команде

Новое приложение видят только участники проекта. Людей в проект зовут кнопкой «Пригласить».
Открыть приложение любому по ссылке (с тарифа Старт): кнопка «Опубликовать» в шапке
приложения, поле «Кто может открыть».

Дальше: [Основные понятия](https://docs.getxflow.com/start/concepts.md).

---

# Основные понятия

> Организация, проект, приложение, страница, функция, база данных и роли.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

## Организация

Ваша компания в xflow. Ей принадлежат проекты, страницы, интеграции, файлы, участники, тариф
и баланс.

## Проект

Коробка для одной задачи бизнеса, например «Склад» или «Заявки»: одна база данных PostgreSQL,
облачные функции, секреты и переменные, участники с доступом. Своего кода у проекта нет, код
живёт в приложениях. Проект без приложений тоже работает: его функции запускаются по
расписанию или по вебхуку. Подробно: [Проекты](https://docs.getxflow.com/platform/projects.md).

## Приложение

Код, который собирает платформа, со своим адресом `https://<id>--<организация>.xflowpage.ru`.
В проекте может быть несколько приложений, например кабинет менеджера и экран склада: у
каждого свои версии и уровень доступа («Участники проекта» или «Любой по ссылке»), а база и
функции общие. Откат приложения функции и базу не откатывает. Подробно:
[Приложения](https://docs.getxflow.com/platform/apps.md).

## Страница

Публичный сайт организации на `https://<имя>.xflowpage.ru`: лендинг, презентация, счёт для
клиента. Это готовые файлы без сборки, базы, входа и функций, вне проектов. Нужно, чтобы
входили и вводили данные, делайте приложение. Подробно: [Страницы](https://docs.getxflow.com/platform/pages.md).

## Функция

Серверный код проекта. Приложение зовёт её по своему адресу `/_fn/<имя>`, если оно указано
среди зовущих в `xflow.json` проекта. Ещё функцию запускают расписание, внешний сервис по
вебхуку с ключом, человек или агент вручную. Подробно: [Функции](https://docs.getxflow.com/platform/functions.md).

## База данных

Одна база PostgreSQL на проект. Схему меняет агент миграциями: каждая это SQL-файл, который
применяется один раз. Блок «Данные» на главной проекта только показывает данные. Подробно:
[База данных](https://docs.getxflow.com/platform/database.md).

## Участники и роли

Роли в организации: Админ, Редактор, Просмотр. Новый проект видят автор и Админы, открыть его
можно всей организации или отдельным людям и группам. Подробно:
[Участники и доступ](https://docs.getxflow.com/platform/access.md).

---

# Подключение и права

> Как подключить агента, что такое ключ агента и какие действия ему разрешены.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Раздел «AI агент» в боковом меню xflow. Здесь подключают агента, видят его ключ и решают,
что агенту можно делать.

## Подключить агента

1. Выберите своего агента в списке: Claude Code, Codex, Cursor и другие.
2. Скопируйте фразу и вставьте её в чат агента.
3. Агент установит CLI и попросит подтвердить вход в браузере.

Это делают один раз на компьютер. Когда агент подключён, экран показывает, когда была его
последняя команда. Подробно шаги в разделе [Установка и вход](https://docs.getxflow.com/cli/install.md).

## Ключ агента

Ключ выпускается сам при первом входе. Он один у человека на организацию: вход на втором
компьютере выдаёт тот же ключ. Агент работает от вашего имени и видит только ваши проекты.

Ключ нельзя показывать посторонним. Если он утёк, нажмите «Перевыпустить ключ»: старый
перестанет работать, на каждом компьютере нужно заново выполнить `xflow login`.

## Разрешения

Каждое действие включается отдельно. Просмотр проектов, версий, базы и логов есть всегда.

| Разрешение | Что даёт | По умолчанию |
|---|---|---|
| Отправлять код и заводить проекты | `xflow deploy` (отправка), `xflow init`, вызов функций | вкл |
| Сборка и публикация версии | `xflow deploy`, `publish`, `rollback`, расписания | вкл |
| Изменения схемы базы | `xflow db migrate` | вкл |
| Хранить переменные окружения | `xflow env set`, `env rm` | вкл |
| Пользоваться интеграциями организации | `xflow connections link`, `unlink`, `call` к непривязанному кабинету | вкл |
| Удалять данные | `DROP`, `TRUNCATE` и `DELETE` без условия в миграциях | выкл |
| Переносить базы между серверами | `xflow db move` | выкл |
| Удалять файлы | `xflow storage rm` | выкл |

Выключенное разрешение агент обойти не может: платформа проверяет его на каждом запросе.

## Что остаётся за человеком

Этого агент не делает ни с каким разрешением:

- уровень доступа приложения и кому открыт проект;
- ключи функций для вебхуков;
- приглашения, роли, тариф и оплата;
- подключение интеграций (вход в кабинет сервиса);
- удаление проектов и приложений.

## MCP

Кроме CLI агента можно подключить к платформе по MCP, настройка вручную: [MCP](https://docs.getxflow.com/reference/mcp.md). Через MCP удобно смотреть состояние проекта, базу, логи и вызывать функции.
Отправка кода и сборка остаются в CLI.

---

# Как ставить задачи

> Как формулировать задачу агенту, что он делает сам и что проверить после.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Агенту пишут задачу обычными словами, как сотруднику. Про устройство xflow он знает из
скилла, который CLI кладёт ему при входе.

## Хорошая задача

Назовите, кто пользуется, что он делает и какие данные нужны:

```text
Сделай приложение для склада: кладовщик видит остатки по товарам,
отмечает приход и расход. Каждое утро присылай в Telegram список
товаров, которых осталось меньше 10 штук.
```

Агент сам разложит это на части: таблицы в базе, функции, расписание, экраны.

| Лучше | Хуже |
|---|---|
| «Менеджер видит свои заявки, руководитель все» | «Сделай CRM» |
| «Данные из Wildberries, кабинет уже в интеграциях» | «Подключи WB» без кабинета |
| «Форма для клиентов без входа» | «Сделай публичным» |

## Что агент делает сам

- создаёт проект и приложения;
- пишет код, миграции базы и функции;
- отправляет код на сборку и публикует версии;
- ставит расписания и переменные окружения;
- смотрит ошибки приложения и функций и чинит их.

## Что сделать вам

- подключить кабинет сервиса в «Интеграциях», если задача про внешний сервис;
- открыть приложение людям: окно «Опубликовать», поле «Кто может открыть»;
- пригласить коллег в проект;
- выпустить ключ функции, если её зовёт внешний сервис.

Агент сам скажет, когда нужен один из этих шагов.

## После работы

- Откройте приложение по адресу, который прислал агент, и пройдите основной сценарий.
- Если что-то сломалось, опишите агенту, что сделали и что увидели. Ошибки из браузера и
  функций он прочитает сам: `xflow logs`, `xflow functions logs`.
- Прежнюю версию приложения можно вернуть за секунду, см. [Приложения](https://docs.getxflow.com/platform/apps.md).

## Если агент просит лишнего

Опасные действия выключены в [разрешениях](https://docs.getxflow.com/agent/setup.md) по умолчанию. Если агент
предлагает `--force`, удаление данных или файлов, сначала спросите, что именно пропадёт.

---

# Проекты

> Что лежит в проекте, как его создать и связать с папкой, кому он открыт и как его удалить.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Проект это коробка под одну задачу бизнеса: «Склад», «Заявки», «Клиника». В нём общие части
для его приложений: одна [база данных](https://docs.getxflow.com/platform/database.md), [функции](https://docs.getxflow.com/platform/functions.md)
с расписаниями, [переменные и секреты](https://docs.getxflow.com/platform/secrets.md), [файлы](https://docs.getxflow.com/platform/storage.md) и
люди с доступом. Код живёт в [приложениях](https://docs.getxflow.com/platform/apps.md). Проект всегда принадлежит
организации, личных проектов нет.

## Создать проект

В интерфейсе, кнопка «Новый проект»:

- **Создать через агента**: xflow даёт фразу для чата агента, агент заводит проект сам;
- **Создать пустой проект**: проект с первым приложением из стартового шаблона. Так заранее
  настраивают базу и доступы, а агента подключают потом по инструкции внутри проекта.

Агент создаёт проект с первым приложением и папкой на компьютере:

```bash
xflow init <папка> --name "Склад"
```

| Флаг | Что делает |
|---|---|
| `--name` | название проекта |
| `--app <папка>` | имя папки первого приложения |
| `--no-app` | проект без приложений: автоматизация, чьи функции запускают расписание, вебхук или человек |

## Папка проекта

```
sklad/
  xflow.json            id проекта и кто может звать каждую функцию
  package.json          зависимости функций
  functions/<имя>/      функции, общие для всех приложений
  migrations/           миграции базы
  apps/
    priem/              приложение со своим xflow.json
    ostatki/
```

У проекта две истории изменений, их отправляют разными командами:

| Что отправить | Команда |
|---|---|
| функции, миграции и корневой `xflow.json` | `xflow deploy functions` |
| одно приложение | `xflow deploy apps/<папка>` |

Корень и приложения друг с другом не уезжают. Функции внутри папки приложения сборка не
принимает.

## Связать проект с папкой

| Команда | Что делает |
|---|---|
| `xflow projects list` | проекты организации с id |
| `xflow link <id>` | в пустой папке забирает весь проект: корень и каждое приложение |
| `xflow projects get` | карточка проекта: приложения, база, функции с зовущими, расписания |
| `xflow status` | чем папка отличается от платформы |
| `xflow pull` | забрать последнюю версию с платформы |
| `xflow pull --revision <N>` | забрать конкретную версию |

Многие команды работают и без папки: им передают `--project <id>`.

## Несколько человек на одном проекте

Платформа не сводит правки двух людей: код держат в git, а на платформу отправляют уже
сведённую версию, обычно из CI. Если папка отстала от платформы, `xflow deploy` откажет и предложит сначала забрать свежую
версию. `--force` кладёт папку поверх чужой работы. Прежняя ревизия хранится, пока она среди 10
последних, и команда печатает `xflow pull --revision N`, которым её вернуть.

## Кому открыт проект

Новый проект видят автор и Админы. Открывают его людям, группам или всей организации в окне
«Пригласить» на экране проекта, с уровнем «Просмотр» или «Редактирование». Уровни и роли:
[Участники и доступ](https://docs.getxflow.com/platform/access.md).

## Удалить проект

Удаляют в интерфейсе: автор проекта или Админ. Через CLI проект не удаляется. Корзины нет:
удаление сразу и целиком стирает приложения с версиями, функции и расписания, базу и файлы.
Восстановить нельзя.

---

# Приложения

> Адрес приложения, сборка и версии, публикация и откат, уровни доступа и удаление.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Приложение это веб-интерфейс для людей: кабинет менеджера, экран склада, форма записи. Код
пишет агент, собирает и раздаёт xflow. Приложение живёт в [проекте](https://docs.getxflow.com/platform/projects.md) и
пользуется его [базой](https://docs.getxflow.com/platform/database.md) и [функциями](https://docs.getxflow.com/platform/functions.md). В проекте
может быть несколько приложений, у каждого свой код, версии, адрес и уровень доступа.

## Адрес

```
https://<id>--<организация>.xflowpage.ru
```

`<id>` выдаётся при создании, `<организация>` это короткое имя
организации. Адрес не меняется при переименовании приложения или папки. Поисковикам
приложения не показываются.

## Добавить и собрать

`xflow apps add <папка>` создаёт приложение, кладёт стартовый шаблон в `apps/<папка>` и
печатает адрес. `xflow apps --json` выводит приложения проекта с id.

```bash
xflow deploy apps/<папка> -m "что изменилось"
```

Платформа проверяет исходники, собирает приложение в чистом окружении и сохраняет новую
версию. Если проверка не прошла, сборка не начинается, а агент получает список нарушений с
файлами и строками. Локальная сборка на платформу не попадает.

## Версии

Посетители видят одну версию, живую. Новая сборка не показывается, пока её не опубликуют,
кроме самой первой сборки нового приложения: она публикуется сама.

| Что хранится | Сколько |
|---|---|
| Сборки с файлами, к которым можно вернуться | три последних успешных и живая |
| История сборок | 30 последних |
| Исходники ревизий | пока их сборка в истории, и 10 последних |

`xflow deployments` выводит сборки. Сборка без файлов помечена `no pages`: на неё уже не
вернуться. Код, который нельзя потерять, держите в своём git.

## Публикация и откат

Публикация переключает адрес на выбранную сборку без копирования файлов: за секунду и без
пустого экрана.

| Действие | Как |
|---|---|
| Опубликовать последнюю сборку | кнопка «Опубликовать» в шапке приложения или `xflow publish` в папке приложения |
| Вернуть прежнюю сборку | `xflow publish <номер>` или `xflow rollback <номер>` |
| Без папки | `--app <id>` у тех же команд |

Откат касается только приложения: функции и база проекта остаются текущими. Функции
откатывают отдельно: `xflow deploy functions --revision N`.

## Кто может открыть приложение

| Уровень | Кто откроет | Тариф |
|---|---|---|
| Участники проекта | вошедшие в xflow люди с доступом к проекту | любой |
| Любой по ссылке | кто угодно, без входа | Старт и выше |

На Бесплатном тарифе приложение работает только внутри xflow: прямой заход по адресу уводит на
экран приложения в xflow. Старт добавляет прямой адрес и «Любой по ссылке».

Отдельного списка людей у приложения нет: его открывает каждый, кому открыт проект.

Уровень меняет человек: окно «Опубликовать» в шапке приложения, поле «Кто может открыть».
Пересборка не нужна, агент уровень не меняет. При переключении на «Любой по ссылке» интерфейс
показывает функции, которые станут [открытыми](https://docs.getxflow.com/platform/functions.md), и просит подтвердить. На
этом уровне платформа никого не узнаёт: вход, пользователей и права на данные делает само
приложение через свои функции, см. [Вход в публичном приложении](https://docs.getxflow.com/develop/public-signin.md).

## Удаление

В интерфейсе, из меню приложения, с вводом названия. Удалить может автор проекта или Админ.
Через CLI приложение не удаляется. Удаляются код, версии и адрес; база, функции и файлы
проекта остаются. Корзины нет.

---

# База данных

> Одна база PostgreSQL на проект: миграции, раздел «Данные», чтение агентом, лимит объёма.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

У каждого проекта одна база PostgreSQL на все его приложения и функции. Браузер в базу не
ходит: приложение зовёт [функцию](https://docs.getxflow.com/platform/functions.md), и какие строки увидит посетитель,
решает её код.

Строка подключения лежит в `DATABASE_URL`. Платформа передаёт её только функциям, которые её
упоминают, и сама направляет запросы в базу проекта. В SQL пишут простые имена таблиц:
`select * from tasks`.

## Миграции

Миграция это SQL-файл в `migrations/` в корне проекта: `migrations/0001_init.sql`,
`migrations/0002_orders.sql`.

- Файлы применяются по порядку имён, каждый один раз.
- Применённый файл не правят: платформа откажет, если под тем же именем лежит другой текст.
  Любое изменение схемы это новый файл.
- `BEGIN` и `COMMIT` не нужны и отклоняются: каждая миграция идёт в своей транзакции.

| Команда | Что делает |
|---|---|
| `xflow db migrate` | сохраняет корень проекта и применяет новые миграции |
| `xflow db migrate --dry-run` | показывает, что будет применено, без изменений |
| `xflow db status` | какие миграции применены, какие ждут |
| `xflow db schema [таблица]` | что сейчас лежит в базе |

### Операции, которые уничтожают данные

Истории базы и резервных копий нет. Миграция, которая удаляет или опустошает таблицу,
удаляет столбец или строки (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE`), проходит только
при двух условиях:

- у команды флаг `--allow-destructive`;
- у ключа агента включено право «Удалять данные» (по умолчанию выключено, включает человек в
  разделе «AI агент»).

Платформа судит по результату, а не по тексту SQL: без обоих условий такую миграцию она
откатывает. С ними перед миграцией сохраняет затронутые таблицы (до 50 000 строк каждая) на
7 дней. Вернуть копию можно только по запросу человека, команды нет.

## Чтение данных

Блок «Данные» на главной проекта: таблицы, строки постранично, значение ячейки целиком с
копированием, панель SQL для чтения (до 500 строк в ответе). Изменить строку или схему отсюда
нельзя. Агент читает командой:

```bash
xflow db query 'select * from orders order by created_at desc limit 20'
```

Запрос идёт в транзакции только для чтения. Строк выводится столько, сколько просит `limit` в
запросе: 50 без него, не больше 300. `--json` печатает длинные значения целиком. Запрос с
кавычками удобнее положить в `.sql` файл вне папки проекта: `xflow db query ../q.sql`.

## Объём базы сверх тарифа

Предел объёма баз организации задаёт [тариф](https://docs.getxflow.com/platform/billing.md), занятое показывают
`xflow whoami` и экран тарифа. Через сутки после превышения запись отключается:

| Что | Работает |
|---|---|
| чтение | да |
| изменение и удаление строк | да |
| новые строки, новые таблицы | нет |
| `xflow db migrate` | нет, ответ `db_write_locked` |

В шапке интерфейса появляется красная полоса «Запись в базу отключена». Функции, которые
добавляют строки, получают `permission denied` (код 42501). Выход: удалить лишнее (миграцией с
`DELETE` или функцией) или расширить объём на экране тарифа. Объём проверяется раз в час,
запись включается, когда занятое ниже 90% предела. Кнопка «Проверить снова» в полосе
проверяет сразу.

## Свой сервер

Базу проекта можно перенести на отдельную машину организации: [Свои серверы баз](https://docs.getxflow.com/platform/db-servers.md).

---

# Свои серверы баз

> Отдельная машина с PostgreSQL для баз организации: покупка, перенос базы, продление и удаление.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

По умолчанию базы проектов живут на общем сервере, он входит в тариф. Если базе нужно больше
памяти и диска, организация покупает свой сервер: отдельную машину с PostgreSQL. На одном
сервере может лежать несколько баз, место на диске у них общее.

## Покупка

Раздел «Базы данных» в боковом меню, кнопка «Купить сервер». Выбирают тариф сервера (Мини,
Базовый, Про, Макс) и имя, цены показаны там же. Покупает и оплачивает Админ, оплата помесячно.
Сервер поднимается после оплаты счёта, пустым.

## Перенос базы

Человек переносит базу пунктом «Перенести базу» в меню проекта. Агент командой:

| Команда | Что делает |
|---|---|
| `xflow db list` | на каком сервере база каждого проекта (`platform` это общий) и свои серверы с занятым местом |
| `xflow init --server <имя>` | новый проект с базой на выбранном сервере |
| `xflow db move --to <имя> --yes` | перенести базу существующего проекта, в том числе обратно на `platform` |

Ключу агента для переноса нужно право «Переносить базы между серверами», по умолчанию оно
выключено. Пока идёт копия, обычно пару минут, приложения показывают данные, но не сохраняют
новое. Функции переключаются сами, выкладывать их заново не нужно.

## Отличия от общего сервера

Код функций тот же: `DATABASE_URL` передают как есть.

- Расширения: `pgcrypto`, `pg_trgm`, `unaccent`, `citext`, `btree_gin`, `btree_gist`,
  `pg_stat_statements`.
- Запрос прерывается через 30 секунд, ожидание блокировки через 3 секунды.
- Пока сервер не работает, миграции и запросы сообщают об этом, а функции с базой не отвечают.

## Тариф, продление, удаление

Всё в меню сервера в разделе «Базы данных». «Не продлевать» и «Удалить сервер» видит только
Админ:

- «Сменить тариф»: только вверх, доплата за оставшиеся дни. После оплаты сервер перезапускается
  на пару минут, данные и адрес остаются.
- «Продлевать» и «Не продлевать»: счёт на следующий месяц приходит заранее. Не оплачен к концу
  месяца: сервер останавливается, через 5 дней удаляется вместе с базами.
- «Удалить сервер»: сразу и без возврата, вместе с его базами. Проекты остаются без базы,
  деньги за оставшиеся дни не возвращаются. Нужную базу сначала переносят.

---

# Функции

> Серверный код проекта: кто может звать функцию, открытые функции, вебхуки, расписания, логи и квота минут.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Функция это серверный код проекта: читает и пишет [базу](https://docs.getxflow.com/platform/database.md), ходит во
внешние сервисы. Приложения получают данные только через функции, одни на все приложения
проекта.

## Код, выкатка и откат

Функция это папка `functions/<имя>/` в корне проекта с `index.ts` (или `index.js`,
`index.mjs`). Имя: строчные латинские буквы, цифры и дефис, до 41 символа, например
`send-mail`. Зависимости в корневом `package.json`.

```bash
xflow deploy functions -m "что изменилось"
```

Выкатывает функции со списком зовущих. Публикации нет: все приложения работают с новым кодом
сразу после выкатки.

| Действие | Команда |
|---|---|
| Список выкаток | `xflow deployments functions` |
| Вернуть прежнюю ревизию | `xflow deploy functions --revision N -m "почему"` |
| Без папки проекта | `--project <id>` у тех же команд |

Откат возвращает и код, и списки зовущих. Функция, папку которой удалили, при выкатке
необратимо удаляется вместе с ключами и расписаниями, поэтому выкатка сначала спрашивает
подтверждение.

## Кто может звать функцию

Зовущих перечисляют в корневом `xflow.json`, в `functions.<имя>.callers`:

```json
{
  "projectId": "…",
  "functions": {
    "list-slots": { "callers": ["zapis", "priem"] },
    "book-slot":  { "callers": ["zapis"] }
  }
}
```

Зовущий это папка приложения этого проекта: `apps/zapis` пишется как `"zapis"`. Другое имя
выкатка отклоняет. [Страница](https://docs.getxflow.com/platform/pages.md) зовущим не бывает.

Приложение зовёт функцию по своему адресу `/_fn/<имя>` через
`xflow.functions.invoke('book-slot', { body })` из шаблона, без адресов и ключей в коде.
Приложение не из списка получает 404 `not_bound`. Функция без зовущих (нет в `functions` или
`"callers": []`) недоступна приложениям, её запускают расписание, вебхук или человек.

## Открытая функция

Функция открыта, если среди её зовущих есть приложение с уровнем «Любой по ссылке». Это не
настройка, а следствие списка зовущих и уровня приложения. `xflow deploy functions` пишет об
этом отдельной строкой, `xflow functions list` и интерфейс помечают её `open`.

Открытую функцию может вызвать любой человек в интернете, без вашего приложения:

- каждый входящий параметр проверяется в коде функции;
- функция отдаёт только нужное этому вызову, без чужих строк и служебных полей;
- скрытый адрес, проверка `Origin` и токен в коде приложения не защищают;
- каждую минуту работы оплачивает организация.

Платформа ограничивает частоту вызовов `/_fn` с одного адреса. Вход и права пользователей
публичного приложения делает само приложение, см. [Вход в публичном приложении](https://docs.getxflow.com/develop/public-signin.md).

## Вебхуки и вызов из другой функции

Внешний сервис (платёжная система, бот, CRM) зовёт функцию по адресу
`https://fn.xflowpage.ru/<projectId>/<имя>` с ключом функции в заголовке `X-Function-Key` или
в параметре `?key=`. Ключи выпускает человек на экране функции, вкладка «Доступ», CLI и агент ключей не выпускают.
У функции не больше двух ключей: второй нужен, чтобы заменить первый без перерыва.

Функция зовёт другую функцию проекта по тому же адресу через `process.env.XFLOW_FN_URL` с
заголовком `X-Server-Key` из `process.env.XFLOW_SERVER_KEY`.

## Расписания

```bash
xflow schedules set report "0 3 ? * * *" --payload '{"mode":"full"}'
```

Запускает `report` каждый день в 03:00 по UTC. В выражении шесть полей, ровно одно из полей
«день месяца» и «день недели» равно `?`. Функцию нужно выкатить заранее.

| Команда | Что делает |
|---|---|
| `xflow schedules list` | расписания проекта |
| `xflow schedules set <функция> "<cron>"` | завести расписание; с тем же cron меняет тело, с другим добавляет ещё одно |
| `xflow schedules rm <функция> ["<cron>"]` | снять одно расписание или все расписания функции |

Сколько расписаний у организации (по всем проектам) и как часто они могут идти, задаёт тариф.

## Ручной вызов и логи

| Команда | Что делает |
|---|---|
| `xflow functions invoke report --data '{"a":1}'` | вызывает функцию от вашего имени и печатает тело ответа, на 4xx и 5xx завершается с ошибкой. Флаги `--data-file body.json`, `--method GET`. Работает и без зовущих в `callers` |
| `xflow functions logs report` | падения и ответы 5xx со стеком и выводом консоли: последние 10, `--limit N` для большего, хранятся 200. Успешные вызовы не записываются |
| `xflow functions list` | адрес вебхука, пометка `open`, последний вызов и последняя ошибка каждой функции |

Падение при запуске модуля, превышение времени или памяти в логи не попадает: его видно в
выводе `invoke`. Человек видит ошибки на экране функции, вкладка «Ошибки».

## Минуты и остановка

Квота минут общая на организацию: её тратят все приложения, вебхуки и расписания. Когда
минуты кончились или подписка не оплачена, функции и расписания всей организации
останавливаются, вызовы получают 403 `functions_stopped`. Предел на одно выполнение тоже
задаёт тариф, он применяется со следующей выкатки функций. Подробно:
[Тарифы и лимиты](https://docs.getxflow.com/platform/billing.md).

---

# Страницы

> Публичные сайты организации на xflowpage.ru: создание, версии, откат и удаление.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Страница это публичный сайт организации на `https://<имя>.xflowpage.ru`: лендинг,
презентация, счёт для клиента. Её открывает любой по ссылке, без входа.

## Страница или приложение

| | Страница | Приложение |
|---|---|---|
| Адрес | `https://<имя>.xflowpage.ru` | `https://<id>--<организация>.xflowpage.ru` |
| Кто открывает | любой по ссылке, всегда | по [уровню доступа](https://docs.getxflow.com/platform/apps.md) |
| Что загружают | готовые файлы сайта | исходный код, платформа собирает его сама |
| Публикация | загруженная версия сразу на адресе | сборку публикуют отдельным шагом |
| База данных и функции | нет | база и функции проекта |
| Где живёт | в организации, вне проектов | в проекте |

Форма заявки, проверка ИНН, калькулятор для посторонних это приложение «Любой по ссылке» (с
тарифа Старт): каждый вызов его функций проверяет платформа.

Страница функции не вызывает. В неё можно положить только ключ функции для вебхуков: HTML-форма
отправит данные на адрес вебхука с `?key=`, но прочитать ответ скриптом не сможет. Такой ключ
открывает [функцию](https://docs.getxflow.com/platform/functions.md) каждому посетителю, защищают её только проверки в её
коде.

## Что можно загрузить

- Папку собранного сайта с `index.html` в корне, её `.zip` или один `.html` файл.
- Архив до 5 МБ, распакованное до 25 МБ, до 1000 файлов.
- Папку с `package.json` платформа не примет: нужна сборка (`dist`, `build` или `out`).
- Картинки и видео лежат внутри страницы: [хранилище файлов](https://docs.getxflow.com/platform/storage.md) страницам не
  служит.

Всё в странице видит каждый посетитель. Загрузка с ключом известного формата отклоняется,
кроме ключа функции для вебхуков (`xffn_`): его выдаёт человек, и он открывает одну функцию.

## Создание и новая версия

Страница создаётся сразу с первой версией:

```bash
xflow pages create "Прайс-лист" ./dist --slug price-list
xflow pages deploy price-list ./dist -m "новые цены"
```

Название это все слова между командой и путём. `--slug` задаёт имя в адресе, без него имя
собирается из названия со случайным хвостом. `create` печатает адрес, сайт на нём через
несколько секунд.

Черновика нет: после `deploy` новая версия сразу на адресе, `-m` необязателен. Если файлы не
изменились, платформа отвечает, что эта версия уже на адресе, и ничего не делает.

## Версии, откат и удаление

```bash
xflow pages status price-list
xflow pages rollback price-list 2
xflow pages rm price-list --yes
```

`status` показывает адрес, состояние и версии. `rollback` возвращает версию с этим номером за
секунды. Файлы хранятся у пяти последних версий.

`rm` стирает все версии навсегда, адрес пустеет. Без `--yes` команда называет, что пропадёт, и
ничего не делает. Имя остаётся за организацией 90 дней. Пробную страницу удаляйте, когда она
больше не нужна.

## Имя страницы

От 3 до 40 символов: строчные латинские буквы, цифры и дефис. Дефис не в начале и не в конце,
двух подряд нет (такие адреса у приложений). Имя уникально на всю платформу. Служебные имена, названия брендов и
слова, похожие на приманку для фишинга, заняты.

## Раздел «Страницы»

Пункт в боковом меню, роли «Просмотр» закрыт. Там список с поиском, версии с откатом и
загрузка перетаскиванием (папка, `.zip` или `.html`), имя адреса собирается из названия.
Временно выключить страницу можно только в интерфейсе. Создают, загружают и откатывают Админы
и Редакторы, выключает и удаляет автор страницы или Админ.

## Ограничения

- Число страниц ограничено тарифом, в счёт идут и выключенные.
- На организацию не больше 100 страниц, 20 новых и 200 загрузок в сутки.
- Между загрузками одной страницы не меньше 10 секунд: собирайте правки в одну загрузку.
- Страницы закрыты от индексации поисковиками.
- Значок вкладки у всех страниц общий, платформенный.
- Загрузка, откат и удаление видны через несколько секунд, браузер может держать прежние
  файлы до минуты.

---

# Файлы

> Хранилище файлов проекта для фото, видео и PDF: загрузка, адреса, удаление и лимиты.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

У каждого проекта есть хранилище для фото, видео, PDF и больших картинок. Файлы переживают
любую сборку, их адреса не меняются. Код приложения ограничен 10 МБ архива и 15 МБ
распакованной сборки, поэтому тяжёлое в код не кладут:

| Где лежит | Что |
|---|---|
| в коде приложения | иконки, шрифты, небольшие картинки |
| в хранилище проекта | фото, видео, PDF, большие иллюстрации |
| в самой [странице](https://docs.getxflow.com/platform/pages.md) | всё, что она показывает: хранилище страницам не служит |

Файлы приложения кладёт агент командой `xflow storage push`. Файлы от пользователей приложения
идут через [функцию](https://docs.getxflow.com/platform/functions.md): её код решает, можно ли посетителю загружать.

## Загрузка

```bash
xflow storage push ./media --to media
```

Заливает папку или файл, сохраняя структуру папок.

| Флаг | Что делает |
|---|---|
| `--to <папка>` | в какую папку хранилища положить |
| `--replace` | заменить файл с другим размером, адрес сохраняется |
| `--json` | вывод одним JSON |

Заливается только недостающее: файл с тем же путём и размером пропускается, поэтому после
обрыва команду повторяют. Файл с другим размером без `--replace` остаётся как был. Скрытые
файлы (имя с точки) не уезжают.

`xflow storage ls [папка]` печатает путь, размер и адрес каждого файла, `--json` отдаёт список
целиком. Команды скачать файлы в папку нет.

## Адреса файлов

`push` и `ls` печатают относительный адрес `/_files/<id>`, его отдаёт адрес самого приложения:

```html
<img src="/_files/8c1f…" alt="Товар">
```

- Файл открывает тот, кто может открыть приложение. У приложения «Любой по ссылке» это любой
  посетитель без входа.
- Адрес постоянный, `--replace` его не меняет: ссылки в коде и в таблицах базы остаются рабочими.
- В интерфейсе платформы файлы открывает тот, у кого есть доступ к проекту.

Файлы от пользователей приложения: функция просит у платформы одноразовую ссылку, браузер
отправляет файл по ней в хранилище,
функция подтверждает загрузку и получает адрес. Списка загруженного платформа не отдаёт: адрес
нужно сразу записать в свою таблицу. Подробности агент знает из инструкции о платформе.

## Удаление

```bash
xflow storage rm /_files/8c1f…
xflow storage rm --folder media --yes
```

Удаление необратимо. Без `--yes` удаление папки называет число файлов и ничего не делает.

Агенту нужно право «Удалять файлы»: по умолчанию выключено (в тех же папках файлы
пользователей), включает человек в разделе «AI агент», без него команда отвечает отказом. В
интерфейсе удаляет уровень «Редактирование».

## Лимиты и типы

До 200 МБ на файл. Общий объём у организации задаёт [тариф](https://docs.getxflow.com/platform/billing.md), его можно
докупить. Занятое и лимит показывает `xflow whoami`.

| Вид | Расширения |
|---|---|
| изображения | `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `svg`, `ico`, `bmp`, `tif`, `tiff`, `heic`, `heif` |
| документы | `pdf`, `txt`, `md`, `rtf`, `csv`, `doc`, `docx`, `xls`, `xlsx`, `ppt`, `pptx`, `odt`, `ods`, `odp` |
| данные | `json`, `xml`, `yaml`, `yml`, `geojson`, `vtt`, `srt`, `dat` |
| аудио | `mp3`, `wav`, `ogg`, `oga`, `m4a`, `aac`, `flac`, `opus`, `weba` |
| видео | `mp4`, `webm`, `mov`, `m4v`, `mpg`, `mpeg`, `avi`, `mkv` |
| шрифты | `woff`, `woff2`, `ttf`, `otf` |
| архивы | `zip`, `gz`, `tgz`, `tar`, `7z`, `rar` |

Страницы, скрипты и программы (`html`, `js`, `exe` и подобные) не принимаются: код приложения
уезжает через деплой.

| Код отказа | Что значит |
|---|---|
| `invalid_name` | пустое или слишком длинное имя, `/` в имени файла |
| `file_too_large` | файл больше 200 МБ |
| `quota_exceeded` | место организации кончилось |
| `forbidden_type` | такой тип файла не принимается |
| `duplicate_name` | файл с таким именем уже есть в папке |
| `not_found` | файла или папки нет |

В интерфейсе файлы в блоке «Хранилище» на главной проекта: папки, занятое место, загрузка,
предпросмотр, скачивание и удаление.

---

# Интеграции

> Кабинеты внешних сервисов организации: кто подключает, как функции получают ключи и кто интеграцией распоряжается.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Интеграция это кабинет внешнего сервиса в организации: Wildberries, Ozon, amoCRM, Яндекс
Метрика, Яндекс Директ, Google Таблицы, Telegram и другие. Человек подключает кабинет один
раз, а [функции](https://docs.getxflow.com/platform/functions.md) проектов получают его ключи через переменные окружения.

## Подключение и ключи

Подключает человек в интерфейсе, пункт «Интеграции» в боковом меню (видят Админы и
Редакторы): вход через браузер (OAuth) или ключ в форме. Заводит, выключает интеграцию и
выдаёт к ней доступ только человек. Агенту доступны привязка к проекту, список, состояние
доступа и разовый вызов API.

- Секретные поля хранятся зашифрованными, после сохранения их не видит никто. Название и
  несекретные поля (например, логин) видят Админы и Редакторы. Значение существует только
  внутри запущенной функции.
- Токены OAuth платформа обновляет сама при выкатке функций, когда до истечения меньше 90 дней.
  За 30 дней до конца интерфейс и `xflow status` предлагают выкатить функции.
- Если доступ отозвал сам сервис (сменили пароль, убрали разрешение), выкатка не поможет:
  кабинет переподключает человек. `xflow status` говорит, какой из двух случаев.

## Привязка к проекту

```bash
xflow connections
xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA
xflow deploy functions
xflow connections unlink YANDEX_METRIKA
```

`xflow connections` показывает привязанные кабинеты (с псевдонимом и состоянием доступа) и
доступные, но не привязанные (`available, not linked`). Интеграцию называют именем из первой
колонки или идентификатором, при одинаковых именах команда попросит выбрать по
идентификатору. Значения доезжают до функций на следующей выкатке. В интерфейсе привязать
можно и на экране проекта.

Пока функции проекта читают переменные интеграции, `unlink` отказывает и называет их, `--yes`
отвязывает всё равно. Выкаченные функции держат значения до своей следующей выкатки.

| Переменная в функции | Что в ней |
|---|---|
| `<ПСЕВДОНИМ>_TOKEN` | токен OAuth |
| `<ПСЕВДОНИМ>_<ПОЛЕ>` | остальные поля, например `YANDEX_DIRECT_CLIENT_LOGIN` |

Читают как обычные переменные: `process.env.YANDEX_METRIKA_TOKEN`. В `xflow env` они только для
чтения: `env set` под таким именем отказывает, `env check` считает их имеющимися. У выключенной
интеграции привязка остаётся, но значения в функции не уезжают. Остальное о переменных:
[Переменные и секреты](https://docs.getxflow.com/platform/secrets.md).

## Разовый вызов API без деплоя

```bash
xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
xflow connections call "Яндекс Метрика" /management/v1/counters
xflow connections call OZON /v1/product/list --method POST --data '{}' --header '{"Client-Id":"{CLIENT_ID}"}'
```

Ключи подставляет платформа и запрос делает сама, агенту ключ не достаётся. Привязанный
кабинет зовут псевдонимом, непривязанный именем из списка.

| Флаг | Что делает |
|---|---|
| `--method` | метод запроса. По умолчанию `GET`, с телом `POST` |
| `--data` | тело запроса, JSON |
| `--header` | заголовки, объект JSON |
| `--json` | весь ответ одним JSON |

- `{ИМЯ}` в пути и заголовках заменяется несекретным полем интеграции. Имена печатает
  `xflow connections` в фигурных скобках, неизвестное имя остаётся как набрано.
- Звать можно только адреса этого сервиса из каталога xflow.
- CLI печатает начало ответа: для формы хватает `limit=1`, весь массив обрабатывает функция.
- Статус чужого API приходит внутри ответа, отдельно от ошибок платформы.
- `POST` и `DELETE` меняют данные в живом кабинете безвозвратно: если метод не только читает,
  агенту стоит спросить человека.
- В Git Bash под Windows путь с ведущим `/` портится оболочкой: пишите полный адрес `https://…`
  или ставьте перед командой `MSYS_NO_PATHCONV=1`.

## Кто видит и кто распоряжается

| Режим при заведении | Кто может пустить кабинет в дело |
|---|---|
| только себе | тот, кто завёл |
| выбранным | тот, кто завёл, и названные люди или группы |
| всей организации | все в организации |

- **Владелец организации** ([Участники и доступ](https://docs.getxflow.com/platform/access.md)) использует любую интеграцию.
- **Привязать** к проекту можно только кабинет, доступный тому, кто привязывает.
- **Привязанный** кабинет видит каждый с доступом к проекту. Его ключи читает всякий, кто
  выкатывает код в этот проект: он пишет код функции.
- **Править, переподключать и удалять** может только тот, кто завёл, и Владелец. Режим «всей
  организации» этого права не даёт.
- **Отвязать** от проекта можно без проверки режима.

Агенту для привязки и вызова непривязанного кабинета нужно право «Пользоваться интеграциями
организации» (включено по умолчанию, выключает человек в разделе «AI агент»). Вызов
привязанного кабинета требует того же права, что и выкатка функций.

Число активных интеграций ограничено [тарифом](https://docs.getxflow.com/platform/billing.md) по всей организации.
Выключенная интеграция место не занимает и не удаляется.

---

# Переменные и секреты

> Как хранить ключи, пароли и настройки для функций проекта и как функции их читают.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Переменная окружения это пара «имя и значение» для облачных функций проекта: пароль от почты,
ключ чужого API, адрес сервиса. Значения хранятся на платформе, а не в коде. Приложения
переменных не получают.

## Команды

| Команда | Что делает |
|---|---|
| `xflow env` | список переменных: имя и для кого она |
| `xflow env set ИМЯ=значение` | записать переменную или заменить значение |
| `xflow env rm ИМЯ` | удалить переменную |
| `xflow env check` | сверить код функций с тем, что записано на платформе |

```bash
xflow env set SMTP_PASSWORD=секрет --scope project
xflow env check
xflow deploy functions
```

`env set` и `env check` запускают в папке проекта, `env` и `env rm` работают и с
`--project <id>`. Записывать и удалять может уровень «Редактирование», с «Просмотром» видны
только имена.

Новое значение получат функции, выложенные после записи: нужен `xflow deploy functions`. До
этого функции держат прежнее значение, удалённую переменную тоже видят до новой выкладки.
После `env set` CLI подсказывает, какие функции читают переменную.

## Для кого переменная

| Флаг | Кто получает |
|---|---|
| `--scope organization` | функции всех проектов организации (по умолчанию) |
| `--scope project` | функции только этого проекта |

Другое слово после `--scope` отклоняется. Для одного проекта выбирайте `--scope project`.
Переменную на организацию записывает только тот, кому открыты на правку все проекты, иначе
ответ `organization_scope_denied`: запишите на проект или попросите Админа.

Имя уникально в организации. Команды видят только переменные, доступные проекту, поэтому
`env rm` назовёт переменную чужого проекта отсутствующей. `DATABASE_URL` и всё, что начинается с
`XFLOW`, заполняет платформа, записать их нельзя.

## Как читать в коде

Только буквальным именем:

```ts
const password = process.env.SMTP_PASSWORD
const token = process.env['WB_TOKEN']
```

Платформа передаёт функции только переменные, имена которых написаны в её коде целиком. Такие
формы значение не получат, и сборка функций с ними отклоняется:

```ts
const { SMTP_PASSWORD } = process.env      // деструктуризация
const value = process.env[name]            // имя из выражения
const value = process.env?.SMTP_PASSWORD   // через ?.
const all = { ...process.env }             // разворот целиком
```

`xflow env check` находит их заранее с файлом и строкой, а ещё переменные, которых нет на
платформе (до записи функция получает `undefined`).

## Хранение и ключи в коде

Значения хранятся зашифрованными и не возвращаются: ни в `xflow env`, ни в API, ни в логах.
Забытое значение не прочитать, запишите новое.

Ключи, токены и пароли не пишут в исходники: код видят участники проекта, а ключ в коде
приложения уезжает в браузер каждому посетителю. Сборка останавливается, если находит ключ
знакомого вида: ключи xflow, Stripe, AWS, OpenAI, GitHub, OAuth-токены Яндекса и похожие.
Незнакомый сборке ключ тоже не должен попадать в код.

Ключи привязанных интеграций появляются среди переменных сами, только для чтения:
[Интеграции](https://docs.getxflow.com/platform/integrations.md).

---

# Участники и доступ

> Роли в организации, доступ к проектам и приложениям и ключ агента.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Роль в организации задаёт, что человек может вообще. Доступ к проекту задаёт, какие проекты он
видит и может ли их менять. Уровень приложения задаёт, кто откроет его по адресу.

Всё про организацию в «Настройках» (меню организации внизу бокового меню):

| Раздел | Что там | Кому виден |
|---|---|---|
| Организация | название, логотип, владелец, идентификатор | всем |
| Участники | состав, роли, приглашения; вкладка «Группы» | всем; правит Админ, группы ещё и Редактор |
| Тариф, Счета | [тариф, лимиты и оплата](https://docs.getxflow.com/platform/billing.md), счета за тариф и серверы баз | Админу |

## Роли в организации

| Роль | Код в `xflow org members` | Что может |
|---|---|---|
| Админ | `owner` | всё: проекты, участники, тариф и счета, настройки. Видит и правит все проекты |
| Редактор | `developer` | создаёт проекты и правит те, где ему дали «Редактирование». Не меняет состав организации и тариф |
| Просмотр | `member` | смотрит и пользуется тем, чем с ним поделились: приложения и проекты на чтение, без логов и настроек |

Роль это потолок: «Просмотр» не получит правку в проекте, даже если её выдали. Повысят до
Редактора, и выданная правка заработает. Админов может быть несколько, они равны.

Логов функций и приложений роль «Просмотр» не видит: там бывают персональные данные клиентов.

## Владелец организации

Один из Админов отмечен короной, в интерфейсе он «Владелец», обычно создатель организации:

- его роль нельзя сменить, а его самого удалить из организации;
- только он удаляет организацию;
- он пользуется любой интеграцией организации и распоряжается ею наравне с тем, кто её завёл.

Корону передаёт её хозяин другому Админу пунктом «Передать владение» в списке участников.

## Приглашения и смена ролей

Приглашает, меняет роли и удаляет участников только Админ, в веб-интерфейсе. Агент только
смотрит состав: `xflow org members`. Число людей ограничено тарифом, в счёт идут все роли и
неотвеченные приглашения ([Тарифы и лимиты](https://docs.getxflow.com/platform/billing.md)).

## Доступ к проекту

Новый проект видят автор и Админы. В окне «Пригласить» его открывают всей организации или
выбранным людям и группам (группы на платных тарифах).

| Уровень | Что можно |
|---|---|
| Просмотр | видеть приложения, версии, функции, данные на чтение, файлы, имена переменных |
| Редактирование | всё то же, плюс выкладывать и публиковать, менять базу и миграции, переменные, расписания, файлы и доступ |

Новая выдача получает «Просмотр», уровень меняют в том же окне. Выдают доступ Админ и
Редактор с правкой в этом проекте. Человека не из организации Админ приглашает из того же
окна, роль подберётся по уровню.

Удалить проект может автор или Админ: [Проекты](https://docs.getxflow.com/platform/projects.md).

## Доступ к приложению

У каждого приложения свой уровень: «Участники проекта» или «Любой по ссылке» (со Старта).
Меняют его в интерфейсе на экране приложения. Подробно: [Приложения](https://docs.getxflow.com/platform/apps.md).

## Ключ агента

Агент работает с ключом участника, который выдаётся при `xflow login` после подтверждения
человеком (Админом или Редактором): [Установка и вход](https://docs.getxflow.com/cli/install.md). Ключ один на участника и
организацию.

В каждом проекте ключ получает уровень своего хозяина. При «Просмотре» чтение работает, а
изменение отвечает `forbidden`: правку выдаёт человек в окне
доступа проекта. При понижении роли личный ключ отзывается. `xflow whoami` показывает, чей
ключ, в какой организации и с какими правами.

---

# Тарифы и лимиты

> Тарифы xflow, что в них ограничено, как смотреть занятое и что бывает при превышении.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Тариф подключается организации целиком, на все её проекты вместе. Тарифов три: Бесплатный,
Старт и Бизнес. Цены и точные числа в «Настройках» (меню организации внизу бокового меню), раздел «Тариф».

## Что ограничивает тариф

| Лимит | Как считается |
|---|---|
| Люди в организации | все роли и неотвеченные приглашения |
| Приложения | все приложения организации |
| Облачные функции | все функции организации |
| Страницы | все страницы, включая выключенные |
| Интеграции с сервисами | только включённые |
| Объём баз данных | сумма по всем проектам организации |
| Хранилище файлов | сумма по всем проектам организации |
| Минуты функций | общие на организацию, обнуляются раз в месяц |
| Сборки в месяц | сборки приложений и выкатки функций, обнуляются раз в месяц |
| Сборки одновременно | сколько сборок идёт одновременно |
| Время одного вызова функции | потолок в секундах на вызов |
| Расписания | сколько их в организации и как часто они могут идти |

| | Бесплатный | Старт | Бизнес |
|---|---|---|---|
| Людей в организации | 3 | 8 | без лимита |
| Где открывается приложение | только внутри xflow | по своему адресу | по своему адресу |
| «Любой по ссылке» | нет | есть | есть |
| Группы участников | нет | есть | есть |
| Одновременных вызовов одной функции | 5 | 15 | 35 |

Вызов сверх этого числа сразу получает 429.

## Как посмотреть занятое

```bash
xflow whoami
```

Тариф и каждый лимит рядом с занятым, снятый лимит печатается как `no limit`. Агенту стоит
прочитать это перед долгой задачей. Админ видит то же в разделе «Тариф».

## Оплата

Платный тариф оплачивается счётом за период. Оплачивает, меняет тариф, переходит на Бесплатный
и докупает объём базы или хранилища (если тариф его продаёт) только Админ, в разделах «Тариф»
и «Счета».

## Когда лимит кончился

Отказ по лимиту не ошибка в команде. CLI печатает строку, которая начинается с `Plan limit:`,
в JSON-ответе `code: "forbidden"` с полем `limit` (`code`, `used`, `limit`). Повтор, другое имя
или переписанный код ничего не меняют: освободите занятое или перейдите на тариф выше.

| Что кончилось | Что происходит |
|---|---|
| Люди, приложения, функции, страницы, интеграции | нельзя добавить новое, работающее не ломается. Интеграцию можно выключить, а не удалять |
| Сборки в месяц | новые сборки и выкатки функций отклоняются до обнуления счётчика, дата названа в отказе |
| Хранилище файлов | новые файлы не загружаются (`quota_exceeded`), пока не удалить лишнее |
| Объём базы | новые строки не пишутся (`db_write_locked`), правка и удаление работают. Почистите базу, и запись вернётся в течение часа: [База данных](https://docs.getxflow.com/platform/database.md) |
| Минуты функций | все функции и расписания организации останавливаются (`functions_stopped`) до нового месяца или перехода на тариф выше |

Потолок времени одного вызова записывается в функцию при выкладке: после смены тарифа он
меняется только со следующим `xflow deploy functions` каждого проекта.

## Неоплаченный тариф

Если счёт не оплачен к концу периода, функции и расписания останавливаются сразу. Через пять
дней организация замораживается:

- все команды CLI, кроме `xflow whoami`, и все инструменты MCP отвечают `subscription_blocked`;
- приложения и страницы показывают страницу о приостановке;
- в настройках доступны разделы «Тариф» и «Счета».

Данные не удаляются, всё возвращается после оплаты.

---

# Шаблон приложения

> Из чего рождается приложение, что в шаблоне можно менять и что принадлежит платформе.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Каждое новое приложение рождается из шаблона xflow: проект на Vite и React с готовыми
компонентами в стиле интерфейса xflow. Шаблон приходит один раз при создании приложения и
дальше не обновляется.

## Что можно менять

- Компоненты в `src/components/ui` и готовые блоки в `src/components/blocks` это стартовый
  набор: их правят, перекрашивают или удаляют.
- Любые цвета, своя палитра, одна тема без тёмной: всё разрешено.
- Пока в приложении остаётся хоть один компонент шаблона, имена цветов в `:root` файла
  `src/index.css` не переименовывают: компоненты красятся ими. Значения менять можно, это
  HSL без `#` (`216 95% 40%`). Свои цвета заводят под новыми именами.
- Картинки импортируют из `src/` (`import logo from './assets/logo.png'`), а не кладут в
  `public/`: путь вида `/logo.png` ломается внутри xflow в Safari.

## Что принадлежит платформе

Эти файлы остаются такими, какими пришли: через них работают вход, вызов функций и сбор ошибок.

- `src/lib/platform-auth.ts`, `src/contexts/platform-auth-context.tsx`,
  `src/hooks/use-platform-auth.ts`;
- `src/lib/xflow.ts`, `src/utils/error-logger.ts`.

Код продолжает вызывать `initPlatformAuth()` и `initErrorLogger()` и подключать `index.css`.
Если файл изменили, сборка откажет и назовёт версию, из которой взять оригинал:

```bash
xflow pull --revision N --into ./original
```

## Функции из приложения

Функцию проекта зовут через `xflow.functions.invoke('имя', { body })`, а не по адресу.
Приложение должно быть среди зовущих функции, см. [Функции](https://docs.getxflow.com/platform/functions.md).

## Как сделать хорошо

- Сначала взять готовый блок или компонент, свой писать, когда их не хватает.
- Списки, флажки и даты через `Select`, `Checkbox`, `DatePicker` из `src/components/ui`:
  голый `<select>` в Safari и Firefox открывает системный список.
- У каждого экрана четыре состояния: загрузка, ошибка, пусто, данные. Пустой экран говорит,
  что здесь появится, и предлагает действие.
- Цвет только для смысла: статус, действие, ошибка. Структуру держит серый.
- В первой миграции 5-10 правдоподобных строк: пустой экран выглядит недоделанным.
- Своё название вкладки и иконка.

---

# Проверка перед сборкой

> Что платформа проверяет в исходниках до сборки и что блокирует сборку.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

До сборки платформа проверяет исходники. Нарушения приходят разом (до 50), с файлами и
строками. Отклонённая проверкой попытка ничего не стоит.

## Приложение

| Правило | Почему |
|---|---|
| `package.json` со скриптом сборки, `vite.config.*`, `vite` в зависимостях | платформа собирает только Vite |
| нет `next`, `nuxt`, Remix, `@sveltejs/kit`, `astro` | серверных фреймворков нет |
| `index.html` в корне с `id="root"` и скриптом `src/main.tsx` (или `.ts`, `.jsx`, `.js`) | точка входа шаблона |
| имена файлов латиницей, цифры, пробел и `. - _ ~` | `логотип.png` ломает сборку |
| функции через `xflow.functions.invoke`, без адресов | см. [Шаблон](https://docs.getxflow.com/develop/template.md) |
| нет ключей и токенов, нет `fs`, `express`, `http`, `child_process` | код открыт в браузере |
| нет `alert()`, `confirm()`, `prompt()`, `console.log` вне `src/components/ui` и `blocks` | посетители видят консоль |
| у `react-query`, `react-redux`, `sonner` и подобных подключён провайдер | иначе белый экран |
| файлы платформы не изменены | см. [Шаблон](https://docs.getxflow.com/develop/template.md) |

`console.error` и `console.warn` разрешены, но в логи не попадают.

Уже после сборки проверяются её размер (до 15 МБ) и `base` в `vite.config.*` как в шаблоне:
такая неудача тратит сборку. Архив исходников до 10 МБ, тяжёлое кладут в [файлы](https://docs.getxflow.com/platform/storage.md).

## Корень проекта

- Имя функции: строчные латинские буквы, цифры и дефис, до 41 символа (`send-mail`).
- У каждого имени в `functions` корневого `xflow.json` есть папка `functions/<имя>/` с
  `index.ts` (или `.js`, `.mjs`).
- Зовущий это папка приложения этого проекта, иначе `unknown-caller`.
- Переменные читаются буквально: `process.env.ИМЯ`, см. [Переменные и секреты](https://docs.getxflow.com/platform/secrets.md).

## Пометки «Unfinished»

Не блокируют, но приходят строкой `Unfinished:`. До того как сказать «готово», их исправляют:

- заголовок страницы остался из шаблона;
- в `index.html` нет `<link rel="icon">`;
- в функции `exports.access`: он ничего не значит, зовущих задаёт `xflow.json`.

---

# Вход в публичном приложении

> Как сделать свою регистрацию и вход в приложении с уровнем «Любой по ссылке».

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

На уровне «Участники проекта» xflow сам знает, кто открыл приложение, ничего делать не
нужно. На уровне «Любой по ссылке» платформа посетителя не узнаёт: регистрацию, вход и права
делает само приложение через свои [функции](https://docs.getxflow.com/platform/functions.md). Эти функции открыты всему
интернету.

## Пароли

- Хранить только хеш: `crypto.scrypt` со своей солью на каждого пользователя, сравнивать
  через `crypto.timingSafeEqual`.
- Пароль не пишут в логи, не возвращают и не держат в браузере.
- Неудачные входы считают по почте и по `event.xflow.ip` и притормаживают.

## Сессия

- После входа функция создаёт случайный токен (`crypto.randomBytes(32)`), хранит в таблице его
  SHA-256 и срок, а сам токен отдаёт в ответе.
- Приложение держит токен в `localStorage` и шлёт в заголовке `X-Session`. Куки не работают:
  платформа их не пропускает.
- Срок несколько часов, каждый вызов его продлевает. Выход и смена пароля удаляют сессии.
- Токен не кладут в адрес (`?session=`): он останется в истории.
- Свой заголовок вроде `X-Session`, а не `Authorization` и не служебные заголовки платформы:
  их она заменяет или вырезает.

## Каждая функция

Функция, которая отдаёт данные вошедшему, читает `X-Session` из `event.headers`, находит
сессию и фильтрует строки по пользователю в SQL. Спрятанная кнопка не защищает.

В коде приложения не бывает ключей, списка пользователей, хешей и проверки роли как
единственной защиты.

## Письма

Платформа не отправляет письма за приложение. Для подтверждения почты и сброса пароля нужен
почтовый сервис, его ключ кладут в `xflow env set`.

## Проверка

`xflow dev` не передаёт `X-Session` и зовёт функции от вашего имени. Вход проверяют на адресе
приложения.

---

# Локальный запуск и ошибки

> Как запустить приложение у себя и где смотреть ошибки опубликованного приложения.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

## Локальный запуск

```bash
xflow dev
```

Запускают в папке приложения вместо `npm run dev`. Приложение открывается на
`127.0.0.1:3000`, а вызовы `/_fn/<имя>` уходят на платформу так же, как с адреса приложения:
с теми же зовущими и доступом. Голый `npm run dev` ключа не имеет, и вызовы функций падают.

Локальный запуск в логи ничего не пишет.

## Ошибки

| Что сломалось | Команда | В интерфейсе |
|---|---|---|
| приложение в браузере | `xflow logs` | панель «Ошибки» приложения |
| функция | `xflow functions logs` | вкладка «Ошибки» на экране функции |

`xflow logs` показывает необработанные ошибки, отклонённые промисы и ответы 5xx на адресах
приложений. В папке приложения только его, в корне проекта все приложения. `--limit N`
показывает больше. Хранятся последние 200 записей каждого вида.

`console.error` и `console.warn` в лог не попадают: ошибку, которую надо увидеть, не глушат
`catch` без повторного выброса.

---

# Установка и вход

> Установить CLI xflow, войти в организацию и разложить агенту инструкцию о платформе.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

CLI `xflow` это программа, через которую агент работает с платформой. Обычно всё на этой
странице агент делает сам по инструкции [getxflow.com/agent.md](https://getxflow.com/agent.md).
От человека нужно одно: подтвердить вход в браузере.

## Установка и вход

Нужен Node.js 20 или новее.

```bash
npm i -g @getxflow/cli
xflow --version
xflow login
```

`xflow login` печатает код и ссылку. Человек открывает ссылку, сверяет код и подтверждает вход. CLI
хранит ключ организации в `~/.xflow/credentials.json`. У участника один ключ на организацию:
вход на второй машине выдаёт тот же ключ.

| Команда | Что делает |
|---|---|
| `xflow whoami` | чей ключ, организация, тариф и лимиты с занятым |
| `xflow logout` | забыть ключ активной организации, `--all` забывает все |
| `xflow org` | организации с сохранённым ключом, активная помечена |
| `xflow org switch <имя или id>` | переключить активную организацию без браузера |
| `xflow login` ещё раз | войти в ещё одну организацию, CLI хранит по ключу на каждую |

В папке проекта команды идут в организацию этого проекта, какая бы ни была активной. Если
проект «не найден», хотя он есть, обычно ключ от другой организации: проверьте `xflow org`.

## Инструкция для агента

```bash
xflow skills
```

Кладёт агентам на этой машине инструкцию о платформе (скилл). Без неё агент не знает про
xflow. `xflow init` и `xflow link` раскладывают скилл сами.

| Флаг | Что делает |
|---|---|
| без флагов | Claude Code, Cursor, Codex и всё уже установленное |
| `--agent claude,cursor` | только названные агенты |
| `--global` | в домашнюю папку, скилл виден во всех проектах |
| `list` | каким агентам и куда скилл уже разложен |

## Обновление

| Команда | Что делает |
|---|---|
| `xflow update` | ставит свежую версию CLI и обновляет разложенные копии скилла |

О новой версии CLI напоминает строкой не чаще раза в сутки. Ответ `outdated_cli` значит, что
старая версия больше не работает: обновиться нужно сразу.

## Переменные окружения

| Переменная | Зачем |
|---|---|
| `XFLOW_TOKEN` | ключ там, где нет браузера (CI, сервер), главнее сохранённого |
| `XFLOW_DEBUG` | печатать стек при неожиданной ошибке |
| `NO_COLOR` | вывод без цвета |

---

# Команды

> Все команды xflow с главными флагами, сгруппированные по задачам.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

## Общие правила

- Установка и первый вход: [Установка](https://docs.getxflow.com/cli/install.md).
- Точные флаги установленной версии даёт `xflow help` и `xflow help <команда>`: при расхождении верьте им.
- Команды берут проект и приложение из папки, в которой стоят. Без папки проект называют
  `--project <id>`, приложение `--app <id>`, вместе эти флаги не указывают. Какие команды их
  принимают: `xflow help project`.
- `--json` печатает ответ для машины там, где он есть: `apps`, `db query`, `storage`, `pages`, `connections call`.
- Незнакомый флаг отклоняется с подсказкой, какие флаги есть у команды. Флаг без значения тоже.
- JSON в `--data` и `--payload` проверяется до отправки. В PowerShell двойные кавычки
  экранируют (`--data '{\"a\":1}'`) или кладут тело в файл: `--data-file body.json`.
- `-m` это короткая форма `--message`.

## Вход и организации

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow login` | вход через браузер, ключ организации сохраняется рядом с прежними | |
| `xflow logout` | забыть ключ активной организации | `--all`: все ключи |
| `xflow whoami` | чей ключ, его права, лимиты тарифа и занятое | |
| `xflow org` | организации с сохранённым ключом, активная отмечена | |
| `xflow org members` | кто в организации и с какой ролью | |
| `xflow org switch <имя\|id>` | сделать активной другую организацию, локально | |

## Проекты и приложения

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow init [папка]` | новый проект с первым приложением из шаблона | `--name`, `--app <папка>`, `--no-app`, `--server <имя>` |
| `xflow link <id>` | привязать папку к проекту, пустая получает весь проект | |
| `xflow projects list` | проекты организации | |
| `xflow projects get [id]` | карточка проекта: приложения, база, функции и зовущие, расписания | |
| `xflow apps` | приложения проекта, их папки и адреса | `--json`, `--project` |
| `xflow apps add <папка>` | новое приложение в `apps/<папка>` из шаблона | `--name`, `--color` |
| `xflow status` | что на платформе и чем отличаются локальные копии | |

Подробнее: [Проекты](https://docs.getxflow.com/platform/projects.md), [Приложения](https://docs.getxflow.com/platform/apps.md).

## Код и версии

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow deploy functions -m "…"` | отправить корень проекта, применить миграции, выкатить функции и зовущих | `--allow-removals`, `--revision N`, `--project` (только с `--revision`), `--force` |
| `xflow deploy apps/<папка> -m "…"` | отправить одно приложение и собрать его; в его папке хватит `xflow deploy` | `--revision N`, `--app` (только с `--revision`), `--force` |
| `xflow publish [сборка]` | поставить на адрес приложения новейшую или названную сборку | `--app` |
| `xflow rollback <сборка>` | то же со старой сборкой, номер обязателен | `--app` |
| `xflow deployments [functions]` | сборки приложения или выкатки функций | `--app`, `--project` |
| `xflow pull [functions\|apps/<папка>]` | скачать исходники корня или одного приложения | `--into <папка>`, `--revision N`, `--force` |
| `xflow dev` | в папке приложения: запустить его на `127.0.0.1:3000`, функции отвечают с платформы | |
| `xflow logs` | ошибки браузера опубликованных приложений | `--limit N`, `--app`, `--project` |

`-m` обязателен: одна строка о том, что изменилось. `--force` кладёт папку поверх чужой ревизии и
печатает `xflow pull --revision N`, которым её вернуть. Что проверяется до сборки:
[Проверка перед сборкой](https://docs.getxflow.com/develop/build-check.md). Локальный запуск: [Локальная разработка](https://docs.getxflow.com/develop/local.md).

## База

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow db status` | какие миграции применены и какие ждут | `--project` |
| `xflow db list` | базы проектов и серверы организации | |
| `xflow db schema [таблица]` | таблицы проекта или колонки одной | `--project` |
| `xflow db query 'select …'` | чтение в транзакции только на чтение; запрос можно дать файлом `.sql` | `--json`, `--project` |
| `xflow db migrate` | сохранить корень проекта и применить новые `migrations/*.sql` | `--dry-run`, `--allow-destructive` |
| `xflow db move --to <сервер> --yes` | перенести базу проекта на другой сервер | `--project` |

Без лимита в SQL `db query` отдаёт 50 строк, потолок 300. `--allow-destructive` и `db move`
требуют права на ключе, его включает владелец ключа. Подробнее: [База данных](https://docs.getxflow.com/platform/database.md).

## Функции и расписания

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow functions list` | функции, их зовущие, открыта ли, последний вызов и ошибка | `--project` |
| `xflow functions invoke <имя>` | вызвать функцию от своего имени и напечатать ответ | `--data`, `--data-file`, `--method`, `--project` |
| `xflow functions logs [имя]` | падения функций: стек и вывод консоли | `--limit N`, `--project` |
| `xflow schedules list` | что запускается по таймеру и с каким телом | `--project` |
| `xflow schedules set <имя> "0 3 ? * * *"` | запускать функцию по расписанию, время UTC; другой cron добавляет ещё одно расписание | `--payload`, `--payload-file`, `--project` |
| `xflow schedules rm <имя> ["<cron>"]` | снять одно расписание функции или все | `--project` |

`functions invoke` печатает только тело ответа и выходит с ненулевым кодом на 4xx и 5xx.
В расписании шесть полей, ровно одно из «день месяца» и «день недели» равно `?`.
Подробнее: [Функции](https://docs.getxflow.com/platform/functions.md).

## Переменные и интеграции

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow env` | какие переменные сохранены (имена, без значений) | `--project` |
| `xflow env check` | каких переменных не хватает функциям | |
| `xflow env set ИМЯ=значение` | сохранить переменную | `--scope project\|organization` |
| `xflow env rm ИМЯ` | удалить переменную | `--project` |
| `xflow connections` | подключённые аккаунты, доступные проекту, и их переменные | `--project` |
| `xflow connections link <имя> --as АЛИАС` | отдать функциям доступы аккаунта | `--project` |
| `xflow connections unlink <АЛИАС>` | забрать их обратно | `--yes`, `--project` |
| `xflow connections call <имя> <путь>` | один запрос к API аккаунта без выкатки | `--method`, `--data`, `--data-file`, `--header`, `--json`, `--project` |

Значение доезжает до функции на следующей `xflow deploy functions`. По умолчанию `--scope organization`.
Подробнее: [Переменные и секреты](https://docs.getxflow.com/platform/secrets.md), [Интеграции](https://docs.getxflow.com/platform/integrations.md).

## Файлы

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow storage ls [папка]` | что лежит в хранилище проекта, с адресами и размерами | `--json`, `--project` |
| `xflow storage push <папка>` | залить фото, видео, PDF, сохраняя структуру; уже залитое пропускается | `--to <папка>`, `--replace`, `--json`, `--project` |
| `xflow storage rm <адрес>` | удалить один файл | `--project` |
| `xflow storage rm --folder <путь> --yes` | удалить папку со всем содержимым | `--project` |

`rm` требует права «Удалять файлы» на ключе. Подробнее: [Файлы](https://docs.getxflow.com/platform/storage.md).

## Страницы

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow pages` | страницы организации, их состояние и адрес | `--json` |
| `xflow pages create <название> <путь>` | новая страница сразу с первой версией | `--slug <имя>` |
| `xflow pages deploy <страница> <путь>` | залить новую версию, видна сразу | `-m` |
| `xflow pages status <страница>` | страница и её версии | `--json` |
| `xflow pages rollback <страница> <N>` | вернуть на адрес версию N | |
| `xflow pages rm <страница> --yes` | удалить страницу насовсем | |

`<путь>` это папка с `index.html`, её `.zip` или один `.html`. `--project` у страниц нет: они
принадлежат организации. Подробнее: [Страницы](https://docs.getxflow.com/platform/pages.md).

## Агент и обновление

| Команда | Что делает | Флаги |
|---|---|---|
| `xflow skills` | разложить агентам инструкции платформы | `--agent claude,cursor`, `--global`, `--refresh` |
| `xflow skills list` | агенты, их папки и что установлено | |
| `xflow update` | обновить CLI и скилл, который идёт с ним | |
| `xflow --version` | установленная версия | |
| `xflow help [команда]` | справка: общий список или страница команды | |

Подробнее: [Подключение агента](https://docs.getxflow.com/agent/setup.md), [MCP](https://docs.getxflow.com/reference/mcp.md).

## Окружение

| Переменная | Зачем |
|---|---|
| `XFLOW_TOKEN` | ключ доступа для CI вместо `xflow login` |
| `XFLOW_DEBUG` | печатать стек при неожиданной ошибке |
| `NO_COLOR` | вывод без цвета |

---

# xflow.json

> Поля файла в корне проекта и в папке приложения, исключения из отправки и локальное состояние.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Файлов два вида: в корне проекта лежит `projectId`, в каждой `apps/<папка>/` лежит `appId`.
По ним CLI понимает, где стоит команда. Оба файла пишут `xflow init`, `xflow link` и
`xflow apps add`; руками правят `functions`, `build` и `ignore`.

## Корень проекта

```json
{
  "projectId": "3f2a9c1e-…",
  "functions": {
    "book-slot": { "callers": ["zapis"] },
    "nightly-report": { "callers": [] }
  },
  "ignore": ["drafts/"]
}
```

| Поле | Обязательно | Что значит |
|---|---|---|
| `projectId` | да | id проекта на платформе |
| `functions` | нет | объект `{ "<имя функции>": { "callers": [...] } }` |
| `functions.<имя>.callers` | нет | папки приложений этого проекта, которым можно звать функцию (`"zapis"` для `apps/zapis`) |
| `ignore` | нет | дополнительные правила исключения для корня, синтаксис как в `.xflowignore` |

- Функция без записи в `functions` или с `"callers": []` никем из приложений не зовётся: её
  будит расписание, ключ или `xflow functions invoke`.
- Зовущие доезжают до платформы на `xflow deploy functions`, а не при сохранении файла.
- У каждого имени в `functions` должна быть папка `functions/<имя>/index.ts`. Зовущий это
  папка приложения этого проекта, страница зовущим не бывает. Ошибки: [Коды ошибок](https://docs.getxflow.com/reference/errors.md).
- Кто ещё откроет приложение-зовущего, решает его уровень доступа: [Доступ](https://docs.getxflow.com/platform/access.md).

## Папка приложения

```json
{
  "appId": "8b41d0f2-…",
  "build": { "command": "npm run build", "dir": "dist" },
  "ignore": ["fixtures/"]
}
```

| Поле | Обязательно | Что значит |
|---|---|---|
| `appId` | да | id приложения; папку можно переименовать, приложение остаётся тем же |
| `build.command` | нет | команда сборки, по умолчанию `npm run build`; скрипт должен быть в `package.json` |
| `build.dir` | нет | куда пишет сборка, по умолчанию `dist`; путь внутри папки приложения, на платформу не уходит |
| `ignore` | нет | дополнительные правила исключения для этого приложения |

Файл приложения без корня проекта выше не работает: клонируйте проект целиком через
`xflow link <id>` в пустой папке. Подробнее: [Приложения](https://docs.getxflow.com/platform/apps.md).

## Что уходит на платформу

Корень проекта и каждое приложение отправляются отдельно. Корень отправляет всё, кроме
`apps/`, плюс файлы `apps/<папка>/xflow.json`: из них читаются зовущие. Приложение
отправляет свою папку.

Никогда не уходят:

| Что | Почему |
|---|---|
| `node_modules/`, `dist/`, `build/`, `.next/` | зависимости и сборку платформа делает сама |
| `.git/`, `.xflow/` | история и локальное состояние |
| `.env`, `.env.*` | секреты хранятся в переменных: [Переменные и секреты](https://docs.getxflow.com/platform/secrets.md) |
| `.DS_Store`, `Thumbs.db`, `tsconfig.tsbuildinfo` | служебные файлы системы и компилятора |
| копии скилла xflow, которые раскладывает CLI | CLI кладёт свежую копию сам |
| символические ссылки | не архивируются |

Тяжёлые фото, видео и PDF держат в [файлах проекта](https://docs.getxflow.com/platform/storage.md), а не в исходниках.

## .xflowignore

Лежит в корне проекта или в папке приложения и действует на то, что отправляется оттуда.
Правила складываются с полем `ignore` и списком выше.

```
# черновики и дампы
drafts/
*.psd
/data/dump.sql
```

| Запись | Значит |
|---|---|
| `#` в начале | комментарий |
| `*`, `?` | любые символы и один символ внутри имени |
| `**` | любая глубина папок |
| `/` в конце | только папка |
| `/` в начале или внутри | путь от папки, где лежит файл; иначе имя ищется на любой глубине |

Отрицания `!` нет. Если отправлять стало нечего, команда так и скажет: проверьте `.xflowignore`.

## .xflow/

Локальное состояние папки: с какой ревизией на платформе она сверялась последней и к какой
организации привязан проект. Оно своё у каждой машины, поэтому `xflow init` и `xflow link`
дописывают `.xflow/` в `.gitignore`. Удалённая `.xflow/` не ломает проект: следующая выкатка
ляжет поверх текущей ревизии и скажет об этом.

---

# Коды ошибок

> Коды отказов платформы: когда возникают и что делать.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Ошибка платформы приходит в форме `{ "error": "…", "code": "…", "hint": "…" }`. Ветвиться
можно только по `code` и `limit.code`: тексты `error` и `hint` меняются, коды нет. Тексты
английские, их читает агент.

## Доступ и ключи

| Код | Когда | Что делать |
|---|---|---|
| `unauthorized` | ключа нет или он недействителен | `xflow login`; в CI проверить `XFLOW_TOKEN` |
| `forbidden` | у ключа нет нужного права, или доступ к проекту только на просмотр | право включает владелец ключа в настройках платформы, уровень «Редактирование» выдают в окне «Пригласить» проекта |
| `not_found` | проекта, приложения или функции нет, либо проект вам закрыт | проверить id; ключ мог быть от другой организации: `xflow org` |
| `invalid_request` | запрос неверен; текст называет, что именно | исправить по `hint` |
| `invalid_request` | на платформе ревизия новее той, от которой вы работали | `xflow pull --into ./server-copy`, слить изменения в git, повторить |
| `invalid_request` | переменная уровня организации, а часть её проектов вам закрыта | `xflow env set … --scope project` или попросить владельца организации |
| `confirm_required` | действие необратимо и нужно явное согласие | повторить с согласием: `--allow-removals`, `--yes` |
| `conflict` | состояние успело измениться: имя занято, идёт перенос базы | прочитать текст и повторить |
| `rate_limited` | слишком много запросов с ключа или адреса | подождать столько, сколько в `Retry-After` |
| `outdated_cli` | версия CLI ниже минимальной | `xflow update`, до этого ничего не заработает |
| `internal` | сбой на стороне платформы | повторить позже |

Доступ к проектам и права ключа: [Участники и доступ](https://docs.getxflow.com/platform/access.md), [Подключение агента](https://docs.getxflow.com/agent/setup.md).

## Сборка и проверка

Отказ проверки приходит списком `issues`, у каждого нарушения код, файл и строки. Сборка не
начинается, попытка ничего не стоит. Правила: [Проверка перед сборкой](https://docs.getxflow.com/develop/build-check.md).

| Код | Когда | Что делать |
|---|---|---|
| `no-package-json`, `bad-package-json`, `no-build-script` | нет `package.json`, он не читается или в нём нет скрипта сборки | вернуть `package.json` и скрипт из `build.command` |
| `not-vite`, `ssr-framework`, `forbidden-directory` | не Vite или серверный фреймворк | приложение это Vite SPA, код в `src/` |
| `no-index-html`, `no-entry-point` | нет `index.html` или `src/main.tsx` (`.ts`, `.jsx`, `.js`) | вернуть точку входа шаблона |
| `bad-build-dir` | `build.dir` указывает за пределы папки | путь внутри папки приложения: [xflow.json](https://docs.getxflow.com/reference/xflow-json.md) |
| `bad-file-name` | имя файла не латиницей | переименовать: латиница, цифры, пробел и `. - _ ~` |
| `secret-in-source` | в исходниках ключ или токен | убрать в [переменные](https://docs.getxflow.com/platform/secrets.md) функции |
| `server-only-api` | во фронтенде `fs`, `http`, `express` и подобные | серверная часть живёт в функциях |
| `hardcoded-function-url` | адрес функции вписан в код | звать через `xflow.functions.invoke` |
| `no-alert`, `no-confirm`, `no-prompt`, `no-console-log` | системные окна или `console.log` вне `src/components/ui` и `blocks` | диалоги шаблона; `console.error` разрешён, но в логи не попадает |
| `missing-provider` | библиотеке нужен провайдер, а он не подключён | подключить провайдер, иначе белый экран |
| `missing-ui-component` | импорт компонента из `@/components/ui`, которого нет | вернуть компонент или убрать импорт |
| `platform-file-changed`, `platform-file-removed`, `template-wiring-broken` | изменён или удалён файл платформы, сломана проводка шаблона | вернуть оригинал командой из текста отказа: [Шаблон](https://docs.getxflow.com/develop/template.md) |
| `theme-token-removed`, `theme-token-unmapped` | удалены токены темы, которыми красят компоненты шаблона | менять значения, а не имена, или удалить и эти компоненты |
| `functions-in-app` | функция лежит в папке приложения | перенести в `functions/<имя>/` корня, выкатить `xflow deploy functions` |
| `no-xflow-json`, `bad-xflow-json` | нет `xflow.json` в корне или он неверен | `xflow link <id>`; поправить по тексту |
| `bad-function-name` | имя функции не по правилам | строчная латиница, цифры, дефис, до 41 символа |
| `binding-without-function` | у имени в `functions` нет папки `functions/<имя>/` с `index.ts` | добавить функцию или убрать запись |
| `unknown-caller` | зовущий не приложение этого проекта | указать папку приложения из `apps/` |
| `env-name-not-literal` | имя переменной собрано выражением | писать `process.env.ИМЯ` буквально |
| `unknown-min-role` | `minRole` называет роль, которой нет | роль из шкалы платформы: [Функции](https://docs.getxflow.com/platform/functions.md) |

Пометки сборку не останавливают, но до слова «готово» их исправляют: `default-title`
(заголовок из шаблона), `default-icon` (нет иконки), `access-export-ignored` (`exports.access`
ничего не значит, зовущие задаются в `xflow.json`).

## База

| Код | Когда | Что делать |
|---|---|---|
| `invalid_request` | миграция удаляет данные без `--allow-destructive`, или изменён уже применённый файл | для удаления флаг и право на ключе; правку писать новой миграцией |
| `forbidden` | у ключа нет права удалять данные или переносить базу | право включает владелец ключа |
| `forbidden`, `limit.code: db_write_locked` | объём данных вышел за лимит тарифа, запись в базу выключена | удалить лишние строки: запись вернётся в течение часа; или поднять тариф |

Подробнее: [База данных](https://docs.getxflow.com/platform/database.md).

## Функции

Отказ при вызове функции приходит в поле `reason` ответа, в коде приложения это `code` у `XFlowError`.

| Код | Статус | Когда | Что делать |
|---|---|---|---|
| `not_bound` | 404 | приложение не указано в `callers` функции | добавить папку в `xflow.json`, `xflow deploy functions` |
| `not_found` | 404 | функция не выкачена | `xflow deploy functions` |
| `login_required`, `invalid_credential` | 401 | посетитель не вошёл или вход устарел | войти заново |
| `no_access` | 403 | у человека нет доступа к приложению | доступ даёт человек: [Участники и доступ](https://docs.getxflow.com/platform/access.md) |
| `role_too_low` | 403 | роль ниже `minRole` функции | роль выше или другой порог |
| `functions_stopped` | 403 | функции организации остановлены | см. «Тариф» ниже, код тут не поможет |
| `bad_min_role` | 500 | `minRole` с неизвестной ролью | исправить `minRole` в коде функции |
| `rate_limited` | 429 | слишком много вызовов сразу | вызывать пачками, не все элементы списка параллельно |
| `unavailable` | 503 | платформа не смогла проверить вызов | повторить позже |

Падения самого кода смотрят в `xflow functions logs <имя>`.

## Тариф

Отказ по тарифу приходит как `forbidden` с полем `limit`: `{ "code": "limit_apps", "used": 1, "limit": 1 }`.
Повтор, переименование и правка кода не помогают: лимит снимает владелец организации.
Лимиты и занятое: `xflow whoami`. Подробнее: [Тариф](https://docs.getxflow.com/platform/billing.md).

| `limit.code` | Когда | Что делать |
|---|---|---|
| `limit_apps`, `limit_functions`, `limit_pages`, `limit_connections` | кончились приложения, функции, страницы или активные подключения | удалить ненужное, отключить неиспользуемое подключение или поднять тариф |
| `limit_projects` | 100 проектов в организации | удалить ненужные проекты |
| `limit_seats` | кончились места для людей, считая приглашения | поднять тариф |
| `limit_builds` | кончились сборки месяца | ждать даты обнуления из текста или поднять тариф |
| `limit_builds_concurrent` | идёт максимум сборок одновременно | дождаться их и повторить |
| `plan_no_schedules`, `limit_schedules`, `limit_schedule_interval` | расписаний нет на тарифе, кончились или запуск чаще разрешённого | реже запускать или поднять тариф; cron тут ни при чём |
| `db_write_locked` | база больше лимита | см. «База» выше |
| `functions_stopped` | кончились минуты функций или подписка не оплачена | оплатить или перейти на тариф выше, функции вернутся сразу |
| `subscription_blocked` | организация заморожена за неоплату: отказ на всё, кроме `xflow whoami` | владелец оплачивает счёт в настройках организации |
| `billing_unavailable` | платформа не смогла проверить тариф | повторить позже |

## Файлы

Загрузка файлов из кода функции отвечает своими кодами: [Файлы](https://docs.getxflow.com/platform/storage.md).

| Код | Когда | Что делать |
|---|---|---|
| `quota_exceeded` | хранилище организации заполнено | удалить ненужные файлы или поднять тариф |
| `file_too_large` | файл больше 200 МБ | уменьшить файл |
| `duplicate_name` | имя в этой папке занято | `overwrite: true` заменяет файл, адрес остаётся |
| `forbidden_type` | страницы, скрипты, исполняемые файлы | хранилище только для ресурсов приложения |
| `not_uploaded` | подтверждение до конца загрузки | подтверждать после завершения PUT |
| `invalid_name` | недопустимое имя файла | переименовать |

---

# MCP

> Сервер MCP: агент читает и меняет проекты платформы без терминала.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

MCP-сервер даёт агенту платформу тулами: проекты, база, функции, расписания, публикация
сборок. Тот же движок и те же права, что у CLI.

## Подключение

Сервер прописывают в настройки агента вручную.

| Параметр | Значение |
|---|---|
| Адрес | `https://app.getxflow.com/api/mcp` |
| Транспорт | HTTP (streamable), без сессий |
| Заголовок | `Authorization: Bearer xfk_…`, ключ участника, тот же, что у CLI |

Ключ лежит в `~/.xflow/credentials.json` после `xflow login`, см. [Установка](https://docs.getxflow.com/cli/install.md).

| Клиент | Как подключить вручную |
|---|---|
| Claude Code | `claude mcp add --transport http xflow <адрес> --header "Authorization: Bearer <ключ>"` |
| Codex | `codex mcp add xflow --url <адрес> --bearer-token-env-var XFLOW_TOKEN` |
| Cursor | `.cursor/mcp.json`: `{"mcpServers":{"xflow":{"url":"<адрес>","headers":{"Authorization":"Bearer <ключ>"}}}}` |
| VS Code | `.vscode/mcp.json`: `{"servers":{"xflow":{"type":"http","url":"<адрес>","headers":{"Authorization":"Bearer <ключ>"}}}}` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json`: `{"mcpServers":{"xflow":{"serverUrl":"<адрес>","headers":{"Authorization":"Bearer <ключ>"}}}}` |
| OpenClaw | `openclaw mcp add xflow --url <адрес> --transport streamable-http --header "Authorization: Bearer <ключ>"` |
| ChatGPT, claude.ai | адрес `https://app.getxflow.com/api/mcp/<ключ>` без заголовка: эти клиенты не умеют свои заголовки |

Адрес с ключом внутри равен ключу: кто его увидел, получил весь доступ участника. Перевыпуск
ключа в разделе «AI агент» гасит и его.

## Тулы

Ключ равен доступу своего хозяина: тулам проекта нужен `project_id`, чужой проект отвечает
как несуществующий. Действие выбирается полем `action`.

| Тул | Действия | Что делает | Право ключа |
|---|---|---|---|
| `get_schema` | | устройство платформы и порядок работы, один вызов в начале | Просмотр |
| `org` | `whoami`, `members` | организация, права ключа, квоты; участники | Просмотр |
| `projects` | `list`, `get` | проекты с приложениями; карточка: приложения, база, функции с зовущими, расписания, интеграции | Просмотр |
| `db` | `list`, `schema`, `query`, `migrations`, `move_status` | базы и серверы, таблицы, `SELECT`, история миграций, ход переноса | Просмотр |
| `db_migrate` | | применить миграции, `dry_run` показывает план | «Изменения схемы базы»; `DROP`, `TRUNCATE`, `DELETE` без условия ещё «Удалять данные» |
| `db_move` | | перенести базу проекта на другой сервер: `to`, `confirm` (имя проекта) | «Переносить базы между серверами» |
| `functions` | `list`, `logs`, `stats` | функции и зовущие, падения, расход | Просмотр |
| `functions` | `invoke` | вызвать функцию от имени хозяина ключа | «Отправлять код и заводить проекты» |
| `schedules` | `list` | расписания функций | Просмотр |
| `schedules` | `upsert`, `remove` | завести, изменить, снять расписание | «Сборка и публикация версии» |
| `deployments` | `status`, `list` | состояние и история сборок приложения (`app_id`) | Просмотр |
| `deployments` | `publish` | показать сборку посетителям; без `deploy_id` новейшая удачная, старая это откат | «Сборка и публикация версии» |
| `secrets` | `list` | имена переменных окружения, без значений | Просмотр |
| `secrets` | `set`, `rm` | записать, удалить переменную | «Хранить переменные окружения» |
| `pages` | `list`, `status` | страницы организации и их версии | Просмотр |
| `pages` | `create`, `deploy`, `rollback` | страница из одного HTML до 150 КБ, новая версия, возврат версии | «Сборка и публикация версии» |

Права включает хозяин ключа в разделе «AI агент», см. [Подключить агента](https://docs.getxflow.com/agent/setup.md).

## Чего нет в MCP

| Действие | Где |
|---|---|
| отправка кода, сборка приложения | `xflow deploy apps/<папка>` |
| выкатка функций | `xflow deploy functions` |
| создание проекта и приложения | `xflow init`, `xflow apps add` |
| файлы хранилища, привязка интеграций | `xflow storage`, `xflow connections` |
| сайт страницы из многих файлов, удаление страницы | `xflow pages deploy`, `xflow pages rm` |
| уровень доступа приложения, ключи функций, тариф, участники | веб-интерфейс |

Команды: [CLI](https://docs.getxflow.com/cli/commands.md).

## Ответы

| Поле | Смысл |
|---|---|
| `truncated` | есть в каждом успешном ответе; `true` значит показана часть |
| `total` | сколько всего, рядом с `truncated: true` |
| `reason` | почему часть, например `First 50 shown` |
| `hint` | что сделать: сузить запрос или исправить вызов |
| `row_count` | у `db` `query`: строки в ответе, а не всего |
| `isError` | ошибка тула; в ней `hint` и, при отказе тарифа, `limit.code` |

Потолок ответа 8 КБ. Больший сервер ужимает и ставит `truncated` и `reason`.
Получив `truncated: true`, агент сужает запрос, а не угадывает остальное. Коды отказов:
[Ошибки](https://docs.getxflow.com/reference/errors.md).