Посібник користувача

Версія продукту: 0.1.0 (CS-Cart 4.18+, перевірено на 4.18.3; PHP 8.1+).

Цей документ описує реально реалізований функціонал P0 MVP.

Ілюстрації екранів доступні на сторінці аддону. Нижче - короткий текстовий опис того, що ви побачите в адмінці.

Формула продукту: Видно. Контрольовано. Виміряно.

1. Що це

RobotsLLM for AI-SEO - аддон CS-Cart, який:

1. Керує доступом AI- і SEO-ботів через розумний robots.txt (пресети, diff, rollback).
2. Веде реєстр 31 бота і може підтягувати diff з відкритого джерела ai-robots-txt (застосування - лише вручну).
3. Генерує /llms.txt і мовні версії як навігаційну карту для AI-агентів (з курацією).
4. Публікує .md-дзеркала категорій, CMS-сторінок і товарів.
5. Захищає crawl budget (критичні шляхи CS-Cart, sitemap, noindex для дзеркал).
6. Показує аналітику AI-ботів і AI-referral замовлень у адмінці.
7. Санітизує контент, сканує PII/секрети, запускає self-audit.

Окремий VPS не потрібен. Це звичайний PHP-аддон + таблиці MySQL + панельний cron.

Важливо про видачу. Готові /llms.txt і *.md лежать під var/ (у CS-Cart цей каталог закритий від прямого веб-доступу). Публічні URL віддає PHP-serve (dispatch=robots_llm.serve): ті самі заголовки Content-Type, X-Robots-Tag: noindex, ETag / Last-Modified, відповідь 304 на умовний запит. Повна статика без PHP - оптимізація майбутніх версій, не поведінка 0.1.0.

Аддон нічого не публікує в robots.txt сам по собі після встановлення. Політика застосовується лише кнопкою Опублікувати.

2. Встановлення (zip через адмінку)

1. Завантажте пакет robots_llm-0.1.0.zip (збірка: build/package.ps1 або build/package.sh).
2. У CS-Cart: Адміністрування → Модулі → Завантажити та встановити модуль (або «Manage add-ons» → Upload).
3. Оберіть zip і підтвердіть установку.
4. Увімкніть модуль RobotsLLM, якщо він не активний.
5. Переконайтесь, що мови UK/EN підхопили langvars (перезавантажте кеш мов/шаблонів за потреби).

Структура пакета (корінь магазину):

app/addons/robots_llm/
design/backend/templates/addons/robots_llm/
var/langs/uk/addons/robots_llm.po
var/langs/en/addons/robots_llm.po

Після інсталяції створюються таблиці ?:robots_llm_*, seed реєстру з 31 ботом, каталоги під var/files/{id}/robots_llm/generated і …/previous (корінь задає fn_get_files_dir_path() CS-Cart). Якщо root .htaccess доступний для запису, аддон вставляє ідемпотентну секцію # BEGIN robots_llm - правила ведуть .md / llms.txt на PHP-serve, а не на статичний файл у var/.

На екрані: список модулів CS-Cart; рядок RobotsLLM for AI-SEO зі статусом Active і описом аддону.

Деінсталяція / відкат

• Відкат robots.txt: Веб-сайт → RobotsLLM → Політика краулінгу - rollback до попередньої версії. При першій публікації зберігається бекап поточного вмісту зі штатного сховища CS-Cart.
• Повне видалення: «Модулі» → Uninstall. Таблиці знімаються uninstall-SQL; згенеровані файли і секція .htaccess прибираються хуком. Перед drop таблиць аддон намагається повернути в штатне сховище CS-Cart бекап першого запуску. Якщо потрібна конкретна пізніша версія - зробіть rollback до uninstall. Фізичний robots.txt у корені аддон не створює і не видаляє.

3. Перший запуск: майстер політики (robots.txt)

Меню: Веб-сайт → RobotsLLM → Політика краулінгу.

Майстер ставить кілька простих питань (AI-пошук / навчання / user-агенти / SEO-tools) і обирає пресет (або Custom). Далі:

1. Перегляньте live-прев’ю згенерованого robots.txt.
2. Перегляньте diff «було → стане».
3. За потреби прогоніть симулятор «що бачить бот X для URL Y».
4. Натисніть Зберегти, потім Опублікувати (запис у штатний robots_data CS-Cart + версія в ledger). Публікація не відбувається при встановленні.

На екрані (майстер): блок питань так/ні, випадаючий список пресету (auto / Growth / Open / Strict / Custom) і підпис поточного пресету.

>

На екрані (diff): два блоки - прев’ю повного тексту robots.txt і уніфікований diff «активна версія → нова».

>

На екрані (симулятор): вибір бота, поле шляху, кнопка прогону і мітка Allowed / Blocked.

3.1. Пресети - чесна таблиця класів ботів

Custom - ручні перемикачі по класах (purpose) + overrides по окремих ботах у реєстрі.

Важливо (компілятор, RFC 9309):

• Для бота з власною групою критичні Disallow дублюються в його секцію (власна група ігнорує *).
• Google-Extended / Applebot-Extended - control tokens: повний Disallow: / або відсутність групи.
• Існуючі ручні правила мерчанта імпортуються як manual-блок і не видаляються мовчки.
• Наприкінці додається Sitemap:.

3.2. Фізичний robots.txt у корені

Якщо в корені вітрини лежить фізичний файл robots.txt, CS-Cart віддає саме його - запис у БД (і політика аддону) не стануть публічними. Аддон пише лише в штатне сховище і не перезаписує / не видаляє цей файл. Перед тим як очікувати живу політику на /robots.txt, перейменуйте або приберіть фізичний файл (збережіть копію).

4. Реєстр ботів

Веб-сайт → RobotsLLM → Реєстр ботів.

• Seed 31 бота при інсталяції.
• Колонки: ім’я, провайдер, мета (purpose), рекомендація, рішення мерчанта (allow / block / default) per storefront.
• Синк з ai-robots-txt (GitHub): diff → pending_review; застосування тільки кнопкою. Фейл синку не ламає магазин.

На екрані (реєстр): селектор вітрини і таблиця ботів (ім’я, провайдер, purpose, рекомендація, ваше рішення, джерело, статус).

>

На екрані (синк): статус idle / pending_review / error, дата перевірки, лічильники added / changed / removed і кнопки «Перевірити зараз» / «Застосувати».

5. Курація llms.txt (AI Discovery)

Веб-сайт → RobotsLLM → AI Discovery.

Генеруються:

• /llms.txt - кореневий мовний індекс;
• /{lang}/llms.txt - файл на кожну активну мову вітрини.

Структура: заголовок → опис → мета (мова, ринок, валюта, updated, дисклеймер цін) → секції (категорії / допомога / політики / Optional).

Курація в UI:

• pin / unpin / exclude / порядок (вгору-вниз);
• token budget (дефолт 15 000, оцінка ≈ length/4);
• max URLs;
• «Згенерувати зараз» + прев’ю тексту;
• автовиключення: noindex, hidden, disabled; out-of-stock → Optional.

Усі URL - абсолютні canonical. Мови не змішуються в одному файлі.

Чесно: llms.txt - навігаційна карта для AI-агентів, не «кнопка в ChatGPT». Головні важелі видимості - правильні дозволи search/user-ботів + чисті дані.

На екрані (курація): бюджет токенів, max URLs, лічильник черги і таблиці кандидатів із кнопками pin / exclude / ↑ / ↓.

>

На екрані (прев’ю): статус останньої генерації (idle/ok + hash) і згенерований текст llms.txt після «Згенерувати зараз».

6. Markdown-дзеркала і rewrite

6.1. Що генерується

• URL-схема: {seo_path}.md (наприклад /akumulyatory.md, мовні префікси за схемою магазину).
• Файли на диску: var/files/{id}/robots_llm/generated/{storefront_id}/{lang}/... (не публічний веб-каталог).
• Обсяг P0: категорії, CMS-сторінки (політики), товари (назва, бренд, SKU, анонімна ціна + дисклеймер, наявність, характеристики, sanitized-опис, canonical).

Publisher: tmp → валідація безпеки → atomic rename → registry documents → 1 покоління previous/.

Critical-знахідка (секрет / приватний PII / B2B-ціна) блокує публікацію; лишається last-known-good. Телефон/email у публічному описі товару - попередження, не блок (секрети лишаються блокуючими).

6.2. Видача (PHP-serve, не «чиста статика»)

CS-Cart закриває var/ від веб-доступу (Require all denied). Тому rewrite не віддає файл напряму з диска.

1. Apache / LiteSpeed (секція # BEGIN robots_llm): *.md, /llms.txt, /{lang}/llms.txt → index.php?dispatch=robots_llm.serve&rllm_path=….
2. Контролер robots_llm.serve читає файл із PHP-доступного var/files/…, виставляє заголовки і тіло.
3. Заголовки успішної відповіді: Content-Type (text/markdown; charset=utf-8 для .md, text/plain; charset=utf-8 для llms.txt), X-Robots-Tag: noindex, ETag, Last-Modified, Cache-Control: public, max-age=300.
4. Умовний запит з тим самим If-None-Match / свіжим If-Modified-Since → 304 (кешування працює).
5. Промах: якщо документ є в реєстрі - один enqueue у чергу; відповідь 404 без кешу «валідного» порожнього файлу.

Аддон генерує ідемпотентну секцію між маркерами:

# BEGIN robots_llm
# RobotsLLM: .md / llms.txt via PHP serve (do not edit by hand)
… RewriteRule → index.php?dispatch=robots_llm.serve …
# END robots_llm

На екрані: у root .htaccess - позначена секція # BEGIN robots_llm … # END robots_llm з правилами на robots_llm.serve (не шлях до файлу в var/).

Nginx: у коді HtaccessSectionGenerator::nginxSnippet() є фрагмент для vhost (окремо, не в design/). Типовий зміст: location для *.md і llms.txt → rewrite на той самий dispatch=robots_llm.serve. Не використовуйте try_files у var/ - веб-сервер отримає 403.

Після установки перевірте, що секція реально потрапила в root .htaccess / vhost (на shared hosting інколи потрібна ручна вставка).

6.3. Черга змін

Хуки на оновлення/видалення товарів, категорій, сторінок, цін, залишків → dirty_queue.

Cron job=queue (кожні 5 хв): батч 100, ліміт ~55 с.

У коді також є job=reconcile (hash-звірка з диском) - не входить у рекомендований панельний розклад 0.1.0; запускайте лише за потреби.

Full rebuild - кнопка на Дашборді / Discovery або job=rebuild (стрімінгово, checkpoint у job_state).

7. Налаштування cron (панельні команди)

Рекомендований спосіб - панельний cron хостингу, який викликає CLI адмін-скрипта CS-Cart. Точна назва скрипта у кожного магазину своя (часто це перейменований admin.php). Підставте свій шлях до PHP 8.1+ і свій адмін-скрипт.

Формат:

/usr/bin/php8.1 /шлях/до/ВАШ_АДМІН.php --dispatch=robots_llm.cron job=JOB

У режимі консолі пароль cron не потрібен. Якщо запускаєте через HTTP, потрібен пароль Налаштування → Security → Cron password і cron_password= у запиті - для панелі зручніший CLI.

Приклад crontab (підставте PHP і адмін-скрипт):

*/5  * * * * /usr/bin/php8.1 /path/to/YOUR_ADMIN.php --dispatch=robots_llm.cron job=queue
*/15 * * * * /usr/bin/php8.1 /path/to/YOUR_ADMIN.php --dispatch=robots_llm.cron job=logparse
30   2 * * * /usr/bin/php8.1 /path/to/YOUR_ADMIN.php --dispatch=robots_llm.cron job=aggregate
45   2 * * * /usr/bin/php8.1 /path/to/YOUR_ADMIN.php --dispatch=robots_llm.cron job=llms
0    3 * * * /usr/bin/php8.1 /path/to/YOUR_ADMIN.php --dispatch=robots_llm.cron job=audit
10   3 * * * /usr/bin/php8.1 /path/to/YOUR_ADMIN.php --dispatch=robots_llm.cron job=registry_sync

У Hosting Ukraine / інших панелях створіть ті самі шість завдань як «команда PHP», не як URL.

За потреби (не в обов’язковому розкладі): job=rebuild - повна перегенерація; job=reconcile - hash-звірка документів.

На екрані (налаштування аддону): інфо-блок «Cron-завдання» з підказкою інтервалів і імен job-ів; поле шляху access.log.

>

На екрані (панель хостингу): список cron-рядків з вашим PHP, вашим адмін-скриптом і job=queue / logparse / aggregate / audit / llms / registry_sync.

8. Дашборд аналітики

Веб-сайт → RobotsLLM → Дашборд.

Показує (за наявності даних після cron):

• запити ботів по днях (до 30 днів);
• топ ботів (verified / unverified);
• розбивка за purpose;
• топ URL;
• AI-referrals: сесії / замовлення / дохід за джерелами (utm / referrer: ChatGPT, Perplexity, Claude, Gemini, Copilot…).

Джерела даних:

• PHP-логер (UA з реєстру на frontend) - бачить запити, які проходять через PHP, зокрема /llms.txt і *.md через serve;
• Access-log парсер - те, що PHP не бачить (інша статика / пропуски логера); потрібен шлях до логу в налаштуваннях. Якщо лог недоступний, працює лише PHP-логер (чесно показано в UI).

Верифікація: IP у офіційних діапазонах провайдера (кеш) або rDNS для Googlebot/Bingbot; інакше unverified.

GA4: у P0 - поле property id + інструкція звірки (повна API-інтеграція - поза MVP).

На екрані (дашборд): картки «запити за 30 днів», % verified, AI-сесії / замовлення / дохід; SVG-графік запитів; таблиця топ-ботів.

>

На екрані (referrals): таблиця джерел (ChatGPT, Perplexity, Claude, Gemini, Copilot…) із сесіями, замовленнями та сумою.

9. Self-audit і безпека контенту

Веб-сайт → RobotsLLM → Self-audit.

• DOM-санітайзер (не regex): script/style/iframe/form/hidden → чистий текст/markdown.
• PII/secret-сканер: email/телефон (крім офіційних з налаштувань), ключі (AKIA, sk-, …), injection-евристики.
• Critical → не публікувати файл.
• Self-audit: HTTP (200, MIME, charset, ETag, 304, не login-HTML), content (структура, absolute URL), parity (ціна .md vs anonymous на семплі).

На екрані: кнопка «Запустити зараз», фільтр critical/warning/info, таблиця прогонів і список знахідок (код перевірки, об’єкт, повідомлення).

10. Налаштування аддону (коротко)

11. FAQ (факти)

Чи зміниться мій robots.txt одразу після встановлення?

Ні. Аддон нічого не публікує без вашої дії. Політика потрапляє в штатне сховище CS-Cart лише кнопкою Опублікувати, після diff; є rollback. Якщо у корені є фізичний robots.txt - він має пріоритет над БД; приберіть або перейменуйте його, інакше жива вітрина не покаже політику аддону.

Чи потрібен окремий VPS?

Ні. PHP-аддон + MySQL-черга + панельний cron.

Чи зламає SEO?

Не повинно, якщо користуватись diff і rollback. Перед публікацією robots - diff «було → стане»; rollback однією дією; бекап ручного robots при першому запуску. .md / llms.txt йдуть з noindex, щоб не створювати дублі в Google.

Скільки ресурсів?

Орієнтир: ~5-20 МБ диска на ~5000 товарів; генерація при змінах (черга), не на кожен хіт. Публічна видача /llms.txt і *.md іде через PHP-serve (дешеве читання файлу + ETag/304). Повна статика без PHP - не в 0.1.0.

Сумісність

CS-Cart 4.18+, перевірено на 4.18.3. PHP 8.1+.

Як відкотити?

1. Політика краулінгу → rollback robots.
2. Відновити файл з var/files/…/robots_llm/previous/… (last-known-good дзеркал).
3. Або uninstall аддону (спробує повернути бекап першого запуску в штатне сховище).

Чи гарантує llms.txt цитати в ChatGPT?

Ні. Це карта для агентів. Не обіцяємо «+N% видимості» і не стверджуємо, що llms.txt піднімає позиції Google.

Free / Pro

v0.1.0 / v1.0 MVP - один безкоштовний пакет з усім P0. Окрема монетизація - пізніше.

12. Сім модулів (карта для підтримки)

1. AI Crawl Policy - пресети, компілятор RFC 9309, diff, rollback, симулятор.
2. Bot Registry - seed 31, overrides, sync pending_review з ai-robots-txt.
3. AI Discovery - llms.txt + курація + token budget.
4. Markdown Mirrors - рендерери, publisher, черга, rewrite на PHP-serve.
5. SEO Robots Tweaks - критичні шляхи, sitemap, noindex дзеркал.
6. AI Analytics - logger, logparse, verify, referrals, dashboard.
7. Security & Self-Audit - DOM-санітайзер, блок секретів, audit runner.

13. Відкриті пункти (чесно)

• Знімки екранів у цьому файлі не вбудовані - дивіться сторінку аддону.
• Окремого UI-блокера «знайдено фізичний robots.txt» у 0.1.0 немає: пріоритет файлу - поведінка CS-Cart; прибрати файл треба вручну.
• Nginx-rewrite зазвичай вставляють у vhost вручну.
• Інфо-блок cron у налаштуваннях аддону може ще згадувати HTTP/cron_password і додаткові job-и; орієнтир для панелі - таблиця в §7.

Документ узгоджено з docs/marketing-foundation.md і фактичною поведінкою коду 0.1.0 (стенд CS-Cart 4.18.3).