# Для ИИ-агентов

> llms.txt, Markdown-версия каждой страницы и промпт, который ставит чат через Claude Code или Cursor.

Эта документация написана и для людей, и для ИИ-агентов, которые пишут код. Всё ниже доступно по обычному HTTP, без аккаунта и ключа.

## С чего начать
| Адрес | Что это |
|---|---|
| [`https://tolkly.io/llms.txt`](https://tolkly.io/llms.txt) | Короткая карта документации ([llmstxt.org](https://llmstxt.org)): описание, инструкции для агентов, ссылки на Markdown каждой страницы |
| [`https://tolkly.io/llms-full.txt`](https://tolkly.io/llms-full.txt) | Все английские страницы одним файлом |
| [`https://tolkly.io/docs/ru/llms.txt`](https://tolkly.io/docs/ru/llms.txt) | То же на русском; страницы без перевода даны на английском |

Исходник документации — английский, он всегда полный. Русские страницы — его перевод.

## Markdown каждой страницы
У каждой страницы есть Markdown-версия, собранная из того же исходника, что и HTML. Ссылки в ней абсолютные и ведут на Markdown-версии других страниц. Агент переходит по ним, не разбирая HTML.

- Добавьте `.md` к адресу страницы: `https://tolkly.io/docs/en/install.md`.
- Или запросите Markdown по адресу самой страницы: сервер учитывает заголовок `Accept`.

```sh
curl -H 'Accept: text/markdown' https://tolkly.io/docs/en/install
```

Страница, отданная как HTML, отвечает с `Vary: Accept` и указывает свою Markdown-версию и llms.txt:

```http
Link: </docs/en/install.md>; rel="alternate"; type="text/markdown", </llms.txt>; rel="describedby"; type="text/plain"
```

Такой же `<link rel="alternate" type="text/markdown">` есть в `<head>` HTML. На каждой странице «Копировать как Markdown» кладёт Markdown-версию в буфер обмена, а «Открыть в…» открывает её в Claude или ChatGPT с вопросом о ней.

## Промпт для установки
В приложении, в разделе проекта «Установка», под кодом установки владельцы видят «Поручить ИИ-агенту». Это промпт ниже, в котором уже подставлены проект и endpoint. Здесь вместо id проекта стоит `your-project`. На страницах установки его копирует «Открыть в…» → «Промпт для ИИ-агента».

```text
Установи на этот сайт чат поддержки Tolkly.

Проект: your-project
Endpoint виджета: https://api.tolkly.io

1. Прочитай https://tolkly.io/llms.txt, затем https://tolkly.io/docs/en/install.md и раздел про стек этого сайта в https://tolkly.io/docs/en/frameworks.md. Если они не открываются, хватит этого промпта.
2. Определи, как устроен сайт: статический HTML, серверный фреймворк (Next.js, Nuxt, Laravel, Django…), одностраничное приложение (React на Vite, Vue, Angular) или CMS (WordPress, Tilda, Битрикс).
3. Добавь эти две строки ровно один раз, в общий шаблон всех страниц, прямо перед </body>:

   <script type="module" src="https://api.tolkly.io/widget.js"></script>
   <tolkly-chat project="your-project"></tolkly-chat>

   Других атрибутов не добавляй: название, приветствие, цвета и кто отвечает приходят с сервера. Скрипт загружай с https://api.tolkly.io, не копируй его в проект и не включай в сборку.
4. В одностраничном приложении чат должен переживать смену страниц: тег вне router outlet (index.html или корневой layout), скрипт загружается один раз, а не на каждой странице. В TypeScript JSX объяви tolkly-chat как intrinsic element, без приведения к any.
5. Если сайт отдаёт Content-Security-Policy, разреши https://api.tolkly.io, https://ru.tolkly.io в script-src, connect-src и img-src и добавь blob: в img-src (превью файлов). В style-src ничего не нужно: виджет использует constructed stylesheets (Chrome 73+, Firefox 101+, Safari 16.4+). Если политика использует nonce, поставь тот же атрибут nonce на тег <tolkly-chat>, чтобы и старый Safari получил стили. Если в script-src есть 'strict-dynamic', источники-адреса не действуют: поставь nonce и на тег <script> виджета. Если политика этого не позволяет, остановись и скажи мне.
6. Не добавляй список разрешённых доменов: чат работает на любых моих доменах по умолчанию.
7. Если посетители входят на сайте, спроси меня, прежде чем добавлять подпись посетителя (https://tolkly.io/docs/en/identity.md). Секрет хранится на сервере в переменной окружения и никогда не попадает в код страницы.
8. Проверь в браузере: запусти сайт, открой две разные страницы и убедись, что кнопка чата есть на обеих, а во вкладке сети запрос к https://api.tolkly.io/v1/projects/your-project/widget отвечает 200 без поля "refused". Запрос из curl ничего не доказывает: без Origin страницы он разрешён всегда. Потом перечисли изменённые файлы. Через несколько минут после выкладки в разделе проекта «Установка» в Tolkly появится, что чат работает на этом сайте.
```

Чего в промпте нет, и это намеренно:

- **Секрета.** Секрет подписи остаётся у владельца. Он сам кладёт его на сервер сайта через переменную окружения ([Подпись посетителя](https://tolkly.io/docs/ru/identity.md)).
- **Поддельных запросов.** Проверка — настоящая страница в браузере. Запрос с выдуманным `Origin` записал бы чужой сайт в домены проекта.
- **Настроек чата.** Название, цвета и приветствие меняет владелец, а не код сайта.

## В чём агенты ошибаются
- Тег ставится один раз, в общий шаблон всех страниц. Не в компонент страницы и не дважды.
- У тега только `endpoint` и `project`. Тема, приветствие и кто отвечает приходят с сервера ([атрибуты](https://tolkly.io/docs/ru/widget-attributes.md)).
- Скрипт загружается с endpoint как модуль. Его не копируют в репозиторий и не включают в сборку.
- При Content-Security-Policy в `style-src` ничего добавлять не нужно, `'unsafe-inline'` тоже. Если в политике есть nonce для стилей, тот же `nonce` ставится на тег ([CSP](https://tolkly.io/docs/ru/csp.md)).
- Список разрешённых доменов не нужен, если владелец его не просил: по умолчанию чат работает на любом домене ([домены](https://tolkly.io/docs/ru/domains.md)).