> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/ru/prilozheniya-v-rome/bloom/issuing.md).

# Выпуск

Bloom позволяет вам выпускать **разрешённый реальный актив** как обычный контракт Solidity в цепочке Rome и управлять им из консоли для каждого актива. Актив доступен из кошельков как EVM, так и Solana, но **выпуск возможен только через EVM** — кошелёк Solana может хранить активы; он не создаёт их. Это руководство охватывает консоль эмитента, мастер создания, входную защиту консоли и каждую из шести вкладок администрирования.

> **Вы не передаёте Bloom никаких документов или персональных данных, и ваш инвестор тоже.** Bloom фиксирует *результат* результат вашего решения по комплаенсу; цепочка записывает одно булево значение на адрес. Ваш процесс KYC/AML — ваши поставщики, ваши файлы, сроки хранения — полностью остаётся в вашей системе. Полная модель изложена в [COMPLIANCE.md](https://docs.rome.builders/ru/prilozheniya-v-rome/bloom/compliance.md); это руководство лишь ссылается на неё, а не повторяет.

***

## Что вы можете делать

Как администратор актива, вы можете делать из консоли всё, что перечислено ниже, — и каждое из этих действий является реальной транзакцией в цепочке, ссылка на которую приведена на [Доказательства](https://docs.rome.builders/ru/prilozheniya-v-rome/bloom/evidence.md) странице:

* **Выпустить актив** — мастер разворачивает его как три контракта (см. ниже).
* **Рассмотреть заявки** — одобрить или отклонить каждую из них (отказ сопровождается причиной, которую следует сообщить заявителю), и добавить одобренный адрес в allowlist.
* **Управлять allowlist** — добавить один адрес, добавить **пакет адресов в одной транзакции** (`batchAddToWhitelist`), или удалить адрес; токен проверяет список при каждом переводе.
* **Ограничить актив** — ограничить переводы allowlist (что делает объём эмиссии окончательным), или снять ограничение.
* **Управлять эмиссией** — просмотреть общий объём и выпускать или сжигать токены, если у вас есть эта роль.
* **Провести продажу** — открыть продажу (количество и цена), закрыть её, вернуть непроданный остаток и вывести выручку.
* **Задать и распределить доход** — задать валюту выплаты, затем распределить выплату, которая проходит по держателям по одной транзакции за раз; исключённые держатели пропускаются.
* **Управлять ролями** — выдать роль адресу, отозвать роль или отказаться от собственной.

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

***

## Консоль эмитента

![Консоль эмитента по адресу /issuer, где перечислены активы, известные этому развёртыванию, и состояние их продажи.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-c94de7c7a94a287a4d9b90a92b2b16022213b702%2Fissuer-console.png?alt=media\&token=657509e2-8263-4579-b54b-b6b4af33b6d6)

`/issuer` перечисляет активы, которые вы выпустили в этой цепочке, и позволяет начать выпуск нового.

* Подключите **EVM-кошелек**. Отключённому посетителю или кошельку Solana показывается запрос на подключение подходящего типа кошелька, а не пустая консоль — кошелёк Solana не может выпускать активы, и это граница продукта, которую цепочка обеспечивает как вторую, независимую проверку.
* Таблица перечисляет каждый актив с его **названием и символом**, его жизненным циклом **этапом**, а также его **Продажа** состоянием (значок *Откройте* или *Закрыто*).

Два столбца — **Держатели** и **На рассмотрении** — показывают тире. Подсчёт держателей требует перечисления allowlist, а очередь на рассмотрение — это внесетевое хранилище, в которое вы входите отдельно для каждого актива; тире означает *не запрашивалось* там, где `0` было бы заявлено как факт, который приложение не прочитало.

Нажмите **Выпустить актив** чтобы открыть мастер, или выберите строку, чтобы открыть консоль этого актива.

***

## Создание актива: мастер

![Мастер создания по адресу /create: поля актива, затем шесть карточек, которые загораются по мере проведения соответствующих транзакций.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-94683a3a49ac2418aed8cc66dbf47fad940814f7%2Fcreate-wizard.png?alt=media\&token=38b47568-d343-483d-8ce1-f437164bdeae)

`/create` собирает четыре поля, а затем разворачивает ваш актив.

| Поле                 | Правило                  |
| -------------------- | ------------------------ |
| **Название**         | Обязательное поле.       |
| **Символ**           | Обязательное поле.       |
| **Объём эмиссии**    | Целое число больше нуля. |
| **Десятичные знаки** | Целое число от 0 до 18.  |

Нажмите **Начать**. Если поле некорректно, мастер сообщает, какое именно и почему, а не просто остаётся за неактивной кнопкой. Когда черновик корректен, ваш кошелёк по очереди запрашивают для подписи каждого шага.

### Почему развёртывание выполняется по частям

> **Токен разворачивается как три контракта в рамках нескольких транзакций — никогда не одной.** Однотранзакционная `createToken` Arc потребовала бы **77 блокировок аккаунтов**, а Rome ограничивает одну транзакцию **62 блокировки**. `ArcTokenFactoryV2.registerToken`. Поэтому мастер разворачивает каждую часть отдельной транзакцией, а затем получает статус фабрики через [COMPLIANCE.md](https://docs.rome.builders/ru/prilozheniya-v-rome/bloom/compliance.md#what-rome-adds-and-what-registertoken-preserves).

### Шесть карточек

Мастер показывает шесть карточек, которые отражают ход развёртывания. Карточка меняется с **Ожидание** в **Подписание…** в **Готово** (или **Ошибка**) по мере выполнения транзакции.

| # | Карточка                        | Что делает                                                                                                                   |
| - | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Реализация**                  | Общая реализация актива для этой цепочки — уже определена, подписывать ничего не нужно. (Выполняется до начала любого шага.) |
| 2 | **Актив**                       | Разворачивает ваш актив и задаёт его название, символ, объём эмиссии и десятичные знаки за один шаг.                         |
| 3 | **Кто может владеть им**        | Разворачивает собственный модуль разрешений этого актива, где вы выступаете администратором.                                 |
| 4 | **Применять его при переводах** | Указывает активу на этот модуль, чтобы каждый перевод проверялся самим активом.                                              |
| 5 | **Правила доходности**          | Разворачивает и подключает модуль, который определяет, кому производится выплата.                                            |
| 6 | **Регистрация**                 | Регистрирует актив — именно это открывает продажу и позволяет позже обновлять его.                                           |

Шесть карточек объединяют восемь базовых шагов развёртывания, поэтому одна **Начать** приводит к **восьми подписям**. Примечание под кнопкой гласит *"Ваш кошелёк попросит вас подписать каждый шаг. Вы можете остановиться в любой момент и продолжить с того же места — ничего не потеряется."* То, что регистрация является последним шагом, и делает остановку безопасной: на каждом этапе актив уже является реальным развёртыванием, а регистрируется только в конце.

Когда выполнение завершается, мастер выводит *"Выпущено. Ваш актив доступен по адресу …"* со ссылкой на консоль актива по адресу `/token/[address]`.

> **`инициализация` предоставляет вам все роли.** Инициатор мастера — ваш адрес EVM — получает роли администратора токена, минтера/сжигателя, управляющего/распределяющего доход и обновляющего, а также роль администратора модуля allowlist. Таким образом, хранение ваших ключей является частью комплаенс-позиции актива: утерянный кошелёк инвестора можно восстановить только через ваше административное действие, а вкладка консоли **Права** делает видимым, кто обладает каждой из полномочий. (`UPGRADER_ROLE` равен *не* автоматически предоставляется фабрике — выдайте его явно, если хотите обновления через фабрику.)

***

## Консоль для каждого актива и входная защита

![Входная защита консоли: подпишите сообщение своим кошельком — пароля нет.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-a9377e3cad8460af1d9bb4eb3cf6f2a6a8f28b22%2Fconsole-signin.png?alt=media\&token=fdc19e4f-8724-4d36-999b-def1990685f9)

Открывая `/token/[address]` не **не** сразу показывает консоль. Она отображает **входную защиту**:

> *"Войдите, чтобы управлять этим активом. Подпишите сообщение своим кошельком — пароля нет. Ваши полномочия исходят от самого актива и повторно проверяются при каждом действии, поэтому их отзыв вступает в силу немедленно."*

Нажмите **Войти с помощью кошелька**. Вот что именно происходит:

1. Ваш кошелёк запрашивают на `personal_sign` короткое, понятное человеку заявление (с заголовком *"Bloom — подтвердите, что вы управляете этим активом"*) в котором указано единственное действие, на которое оно даёт разрешение, — чтение очереди заявок этого актива, — а также адрес актива, идентификатор цепочки и метку времени.
2. Приложение отправляет это подписанное заявление на `GET /api/applications`.
3. Названия **сервер** проверяет его: извлекает ваш адрес из подписи, подтверждает, что заявление относится к этой цепочке и остаётся свежим (оно действует два минуты, а не всю сессию), читает **собственный модуль allowlist токена** из цепочки и проверяет, что ваш адрес обладает той ролью, которая действительно требуется для записи в allowlist, — `MANAGER_ROLE` в этом модуле.
4. Если она у вас есть, очередь возвращается и консоль отображается. Если нет, сервер отказывает с `403` и причиной.

![Входная защита показывает отказ в кавычках: кошелёк, который не управляет этим активом, отклоняется.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-99040b8d3c752f0f84615b913d6b75fb0d36f81b%2Fconsole-refusal.png?alt=media\&token=29c3ffcf-b826-4aa7-b9da-41bdc3ec2e1e)

> **Кто может управлять им, решает сам актив — не это приложение.** Роль проверяется в allowlist **модуле**, а не на токене, и наличие одноимённой роли на токене не *не* переносится — это разные полномочия. Здесь нет ни аккаунта, ни сессии: каждый следующий запрос несёт собственную свежую подпись, и именно это *"повторно проверяется при каждом действии"* и означает. Отзовите роль кошелька в цепочке, и он немедленно потеряет возможность входа.

Отказ показывает причину **в кавычках** — Bloom никогда не пишет фразу о том, почему кошельку было отказано. Если вы отклоняете подпись в своём кошельке, это ваше *"нет"*, а не актива, и это не считается отказом.

> **Входная защита определяет, чья это консоль, а не то, что скрыто.** Объём эмиссии, состояние продажи, список allowlist и роли — это публичные данные цепочки, которые покажет любой обозреватель. Подпись даёт доступ к **очереди заявок** — заявкам других людей — и право вообще видеть консоль.

### Заголовок консоли

После входа заголовок называет актив и показывает его **этапом** — самый важный параметр, который у него есть:

| Этап               | Значение                                                                                                                                      |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Черновик**       | Модуль разрешений ещё не подключён, поэтому ничто не ограничивает, кто может владеть им.                                                      |
| **Откройте**       | Переводы открыты, и объём эмиссии ещё может измениться. Ограничение актива делает его объём эмиссии окончательным, и это необратимо.          |
| **С ограничением** | Только адреса из allowlist могут владеть этим, **и его объём эмиссии окончателен** — больше нельзя ни выпускать, ни сжигать токены, навсегда. |

Над вкладками сводка показывает четыре показателя — **Держатели · На рассмотрении · Продано · Выплаченный доход**. Два из них считываются из цепочки и хранилища (*На рассмотрении* после входа; *Продано* из витрины продаж); *Держатели* ждёт числа держателей в предварительном просмотре доходности, а *Выплаченный доход* ждёт ещё не реализованного курсора истории выплат. Каждая ожидающая ячейка показывает тире и объясняет, что ей нужно, вместо `0` того чтобы утверждать факт, который никто не запрашивал у цепочки.

***

## Шесть вкладок

В консоли есть шесть вкладок в таком порядке: **Заявки · Кто может владеть им · Эмиссия · Продажа · Доходность · Права.**

Каждая операция записи на этих вкладках использует единый элемент управления, который отображает **названные предварительные условия** и его **последствия** *до* кнопки, а также называет её этап по мере выполнения (*"Ожидание вашего кошелька…"*, *"Выход на цепочку…"*). Ничто не должно откатываться только для того, чтобы показать, что следовало проверить заранее.

### Заявки — очередь на рассмотрение

![Вкладка «Заявки» — очередь на рассмотрение, с ожидающей заявкой, которую нужно одобрить или отклонить, и местом интеграции комплаенса.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-8249de8b76f757101cc945ca4a2687103428839c%2Ftab-applications.png?alt=media\&token=ab0def9b-0bcb-49eb-b785-fd78e6fa2f92)

На этой вкладке перечислены те, кто подал заявку на владение активом. В каждой строке показаны адрес заявителя, юрисдикция, тип держателя, **Проверки** столбец (*Пройдено* если ваш провайдер зафиксировал результат, иначе *Заявлено*), и **Статус** (*На рассмотрении*, *Одобрено*, *Отказано*). Разверните строку, чтобы увидеть сведения о ней и два элемента управления: **Одобрить — может владеть им** и **Отклонить**. Для отказа требуется причина, которая становится ответом заявителю.

> **Одобрение состоит из двух отдельных действий, и вкладка не позволяет их смешивать.** Нажатие **Разрешить** *записывает* ваше решение в хранилище заявок. Добавление адреса в allowlist актива в цепочке — это **вторая подпись** — `batchAddToWhitelist` — и до её подтверждения строка об этом сообщает. Когда записанное решение и данные цепочки расходятся, вкладка называет расхождение и предлагает запись, которая его устраняет: **Допустить** чтобы добавить одобренный адрес в allowlist, или (для отклонённого адреса, который всё ещё указан) элемент управления для его удаления. Адрес не может владеть активом, пока запись в allowlist не подтвердится.

Постоянная заметка на этой вкладке — **место интеграции комплаенса** — указывает, где подключается ваш собственный процесс:

> *"Здесь не запрашиваются и не хранятся никакие документы — проверки выполняете вы сами. Подключите вашего провайдера за `вкладкой «Заявки»` интерфейсом, или импортируйте уже принятые решения. Bloom фиксирует результат, а цепочка записывает одно да или нет для адреса."*

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

### Кто может владеть им — ограничение переводов

![Вкладка «Кто может владеть им» — счётчик allowlist и управление ограничением переводов, демонстрирующее необратимые последствия.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-d32c410e3b5798d86dc5b914bce2f927eb4b1620%2Ftab-holders.png?alt=media\&token=aefe491d-2ce8-4478-a776-b9e612536d60)

Эта вкладка показывает, сколько адресов включено в allowlist актива, и позволяет переключить, применяется ли allowlist **принудительно**:

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

На *без ограничений* активе (черновике), к которому не подключён модуль разрешений, вкладка прямо сообщает об этом — *"Модуль разрешений не подключён, поэтому ничто не ограничивает, кто может владеть этим"* — и переключатель не отображается.

> **Токен проверяет обе стороны каждого перевода.** Пока актив ограничен, перевод, в котором хотя бы одна сторона отсутствует в allowlist, откатывается в цепочке с типизированной ошибкой. Это же ограничение действует для перевода из EVM-кошелька, перевода, подписанного Solana, продажи через витрину и первоначального перемещения ликвидности — обойти его можно только собственными административными полномочиями.

### Объём эмиссии

![Вкладка «Эмиссия» — общий объём существующих единиц.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-29eb2d741e5193eef3ea94a214a199f2eb404fe7%2Ftab-supply.png?alt=media\&token=2ab35474-ed9a-4d30-b978-5f69e1c0e7b9)

Эта вкладка показывает общий существующий объём эмиссии в целых единицах.

### Продажа — открыть, закрыть и получить выручку

![Вкладка «Продажа» — открытая продажа с элементами управления закрытием продажи, возвратом непроданного остатка и выводом выручки.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-573a99f9028a984b038162dc885a16b715673293%2Ftab-sale.png?alt=media\&token=18f59a19-9d83-4780-abf2-47e4a3e37d14)

Эта вкладка проводит основную продажу через контракт витрины.

* **Когда продажа не открыта**, она предлагает открыть её: введите **Единиц к продаже** и **Цена за единицу** (в `wUSDC`), затем нажмите **Открыть продажу**. Сначала показываются предварительные условия записи — токен должен быть зарегистрирован, витрина должна удерживать товарный запас продажи, и сама витрина должна быть включена в allowlist токена, который она продаёт, — так что продажа, которую ещё нельзя открыть, точно указывает, что ей нужно.
* **Когда продажа открыта**, она показывает, сколько единиц осталось в предложении, и предлагает **Закрыть эту продажу**.
* **Вернуть непроданные единицы** перемещает непроданный запас из витрины обратно получателю (по умолчанию вам). Это **не** не закрытие — продажа остаётся включённой, и это прямо указано в последствиях записи, так что возврат нельзя принять за отмену.
* **Вывести выручку** отправляет выручку витрины на адрес (по умолчанию вам). Выручка накапливается независимо от состояния продажи, поэтому её можно вывести как при открытой, так и при закрытой продаже.

### Доходность — выплата держателям, по одному за транзакцию

![Вкладка «Доходность» — поле суммы распределения с напоминанием сначала задать валюту выплаты.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-cc8150ea6fee72d99bd5a2254073779cbd896c11%2Ftab-yield.png?alt=media\&token=d190f7bd-1a1c-4ed2-b9a2-d27a399602f6)

Эта вкладка распределяет выплату дохода среди держателей.

> **Распределение — это проход по списку, а не одно нажатие.** В Rome, `distributeYieldWithLimit` выплачивает **одному держателю за транзакцию** (лимит аккаунтов), поэтому выплата — это последовательность окон, каждое со своей подписью. Вы вводите сумму один раз в целых единицах валюты выплаты, и она блокируется после начала прохода. Окно **сначала** забирает у вас всю сумму выплаты и выплачивает первому держателю; каждое последующее окно перемещает только деньги, уже находящиеся в контракте токена. Bloom перечитывает курсор из цепочки после каждого окна — набор держателей перестраивается по мере изменения балансов, и отправка устаревшего индекса привела бы к повторному запуску с нуля и повторному списанию ваших средств.

Вкладка показывает прогресс — *"Выплата держателю N из M"* — и завершается, когда курсор проходит весь список. Если для актива не задана валюта выплаты, вкладка сообщает об этом; задание валюты выплаты — это единственное поле распределения, которое можете выбрать только вы.

> **Доли ограниченных держателей остаются в контракте.** Адрес, исключённый модулем чёрного списка доходности, пропускается, а его пропорциональная доля остаётся в контракте токена, а не выплачивается.

Прошлые выплаты пока не показываются — чтобы прочитать их, нужно пройти по событиям распределения назад до первого блока актива, для чего ещё нужен курсор истории. Вкладка сообщает об этом внутри себя, а не показывает `0`.

### Права — роли

![Вкладка «Права» — каждая роль и то, удерживается ли она, а также управление выдачей / отзывом / отказом.](https://1351373662-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-fb54f6c73c2d194dd5b6321bc3cb0af825f6f637%2Ftab-rights.png?alt=media\&token=6f545a79-96f8-4c9e-ac38-ce435e547deb)

На этой вкладке перечислены все роли, которые объявляет токен, и указано, удерживается ли каждая из них; каждая читается одним `hasRole` вызовом к токену. Роль, которая **не** удерживается, отображается явно, а не опускается — на вкладке прав отсутствующая строка и *"нет"* — это разные факты.

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

| Действие                      | Действует на                                                                        | Полномочие           |
| ----------------------------- | ----------------------------------------------------------------------------------- | -------------------- |
| **Выдать аккаунту**           | Введённый вами адрес                                                                | `DEFAULT_ADMIN_ROLE` |
| **Отозвать у аккаунта**       | Введённый вами адрес                                                                | `DEFAULT_ADMIN_ROLE` |
| **Отказаться от собственной** | Для себя (OpenZeppelin требует, чтобы подтверждение исходило от вызывающей стороны) | Вы                   |

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

***

## Что никогда не касается Bloom или цепочки

Чтобы однозначно указать, где находится комплаенс:

| Объект                                        | Где это хранится                                                                                            |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Документы KYC/AML и персональные данные (PII) | Ваша собственная система, с вашими поставщиками и сроками хранения — **никогда** это приложение или цепочка |
| Ваше решение допустить адрес                  | Внесетевой реестр; хранилище принадлежит вам                                                                |
| Эффект этого решения в цепочке                | Одно булево значение — `isWhitelisted(address)` — записываемое `batchAddToWhitelist`                        |
| Принудительное применение правила             | Контракт актива при каждом переводе                                                                         |
| Кто может администрировать актив              | Роль, удерживаемая в модуле allowlist актива и проверяемая при каждом запросе                               |

Чтобы ознакомиться с полной моделью комплаенса, читайте [COMPLIANCE.md](https://docs.rome.builders/ru/prilozheniya-v-rome/bloom/compliance.md); а для механики двух направлений (EVM и Solana), которой пользуются ваши держатели, читайте [LANES.md](https://docs.rome.builders/ru/prilozheniya-v-rome/bloom/lanes.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/ru/prilozheniya-v-rome/bloom/issuing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
