**Решение.** В реестр видов добавляется `doc`. Пакет kind `doc`:
- ОБЯЗАН объявлять хотя бы один предмет в `[[documents]]` (D-04), а также
`title` и `abstract` (D-20);
- НЕ МОЖЕТ объявлять `[boot_snippet]`, `[[mcp_server]]`, `[[binary]]`;
- МОЖЕТ объявлять `[[skill]]`, `[translates]`, `[media]` (список переводов
в источнике не хранится — уточнение 2026-09-11, D-18);
- держит страницы под `vibevm/vibespecs/` своего дерева, как любой пакет со
спеками; документы этого пакета относятся к жанру «документация» по признаку
kind содержащего пакета;
- не устанавливается в проект командой `vibe install` (она отказывает с
подсказкой), а прогревается в машинный store командой `vibe cache add`;
локальный читатель и `vibe explain` читают store.
**Почему.** Три требования владельца — локальное чтение, скилл, сайт —
удовлетворяются одним механизмом: пакетом. Локальное чтение — это прогрев
store; скилл — это `[[skill]]` в манифесте; сайт — рендер тех же байтов. Отказ
от материализации в `vibedeps/` держит деревья потребителей тонкими и не даёт
агенту наткнуться на туториалы при grep по зависимостям. Kind, а не жанр
документа, задаёт поведение, потому что kind известен инструментам до чтения
файлов: индекс, гейт публикации, `vibe init`, `vibe list`.
**Известное ограничение.** Прогрев store — машинный, не проектный: теммейт,
клонировавший проект, не получит ту же версию документации автоматически.
Скилл называет команду прогрева; проектного объявления «консультируйся с
такой-то документацией» в этой волне нет.
**Отвергнуто.**
- Документация как бес-kind-овый контент (форма PHASE-G-SPEC): инструменты не
могли бы отличить её от flow и не могли бы запретить boot-сниппет.
- Материализация doc-пакетов в `vibedeps/` по умолчанию: раздувает
коммитимое дерево каждого потребителя.
- Пятый корень раскладки `vibevm/vibedocs/`: ломает закон одного модуля
раскладки (PROP-052) без выигрыша — адресация, сканеры и пивот уже работают
над `vibevm/vibespecs/`.
**Пересмотреть когда.** Появится потребитель, которому документация нужна в
коммитимом дереве проекта или воспроизводимо между машинами команды
(наблюдение: запрос в BACKLOG или отказ `vibe install` в реальном сценарии) —
тогда добавить проектное объявление и режим материализации, не меняя default.
**Решение.** Уровень 0: сайт рендерит любую опубликованную версию любого
пакета из её собственных байтов — манифест как справочная страница, README,
boot-сниппет, спеки с якорями, объявленные скиллы, бинарники и MCP-серверы,
картинки из `[media]`. Уровень 1: расширенная документация — отдельный пакет
kind `doc`, любое количество на предмет. Сайт сшивает уровни на одной странице
пакета.
**Почему.** Уровень 0 бесплатен для автора и покрывает весь реестр сразу, как
rustdoc покрывает каждый крейт. Уровень 1 нужен только там, где кто-то хочет
большего, и не заставляет остальных ничего писать.
**Отвергнуто.** Только уровень 1 — пустой сайт на старте. Только уровень 0 —
нет места туториалам и примерам.
**Пересмотреть когда.** Никогда в рамках этой волны; уровни ортогональны.
**Решение.** Официальная по умолчанию документация предмета `<группа>/<имя>`
называется `<группа>/<имя>-docs`, в той же группе. Документация ядра —
`org.vibevm.core/vibevm-docs`, спутник координаты хоста `org.vibevm.core/vibevm`.
Официальный по умолчанию перевод документации `<группа>/<имя-документации>`
на язык `<lang>` называется `<группа>/<имя-документации>-<lang>`, где `<lang>`
— тег BCP-47 в нижнем регистре (`ru`, `pt-br`, `zh-hans`). Любая другая
документация или перевод носят любое имя в любой группе: соглашение об имени
нужно только для официальности по умолчанию, а отображаемое имя — это `title`
(D-20). В PROP-028 добавляется роль `-docs` как **спутник**: он не участвует в
унисонном версионировании семейства, ведёт собственную линию версий, а
совместимость с предметом выражает ограничением версии в `[[documents]]`.
**Почему.** Суффикс в той же группе — уже действующее правило семейств рядом с
`-lang` и `-mcp`; новой грамматики именования не нужно. Публиковать в группу
предмета может только её владелец, поэтому подделать «официальность» через имя
нельзя. Унисон семейства — закон для «проверенного набора» кода; проза и
переводы меняются в другом ритме.
**Отвергнуто.**
- Подгруппа `org.vibevm.world.docs/<имя>` (форма DefinitelyTyped): копирует
чужое пространство имён по договорённости, не несёт версию предмета, для
сторонних авторов не работает, требует нового закона именования.
- Включить `-docs` в унисон семейства: каждая правка документации бампает
весь код семейства.
- Кодировать язык в группе (`org.vibevm.core.ru/…`): та же ошибка подгруппы.
**Пересмотреть когда.** PROP-028 получит четвёртую кодовую роль, и суффиксов
станет тесно (наблюдение: конфликт стемов в реестре).
**Решение.** Связь объявляется в обе стороны полями манифеста, а не именем.
# в пакете kind = "doc"
[[documents]]
package = "org.vibevm.world/multi-user-planning"
version = "^1.0"
# в предмете, любого kind
[documentation]
primary = "org.vibevm.world/multi-user-planning-docs"
official = ["org.vibevm.world/multi-user-planning-tutorials"]
Правила:
- `[[documents]]` обязателен в doc-пакете, может перечислять несколько
предметов; версия — ограничение semver.
- `[documentation]` в предмете называет координаты **без версии**; `primary`
— не более одной, `official` — сколько угодно.
- **Официальная** документация — та, для которой ребра сходятся: предмет
назвал пакет, пакет объявил предмет. **Community** — есть только ребро от
документации. Только ребро от предмета — «не опубликовано или ошибка»,
сайт показывает предупреждение.
- **Соглашение по умолчанию:** если предмет не объявил `[documentation]`,
пакет `<имя>-docs` в той же группе считается официальным и основным.
Объявленный `[documentation]` заменяет соглашение целиком.
- Для версии предмета V сайт показывает документацию тех версий, чьё
ограничение в `[[documents]]` допускает V, выбирая новейшую.
- Прогрев doc-пакета через `vibe cache add` прогревает и его предметы, чтобы
цитаты `spec://` резолвились офлайн.
- Поля связи попадают в запись индекса реестра, чтобы обратные связи
строились по `primary.jsonl`, а не скачиванием пакетов.
**Почему.** Ребро от предмета снимает опасение владельца: три разных
контрибьютора не смогут спорить за «официальность», потому что её назначает
предмет. Указатель без версии — потому что документация почти всегда выходит
позже кода. Соглашение по умолчанию избавляет от переиздания предмета ради
очевидного случая. Прецедент — поле `documentation` в Cargo.toml.
**Отвергнуто.**
- Capability `docs:<координата>` в `provides`: грамматика capability допускает
только kebab-case в обеих половинах (`crates/vibe-core/src/capability_ref.rs`),
координата туда не помещается.
- Обычная зависимость `requires` на предмет: зависимость не означает
«документирую».
- Пометка официальности в индексе реестра, вне байтов пакета: второй источник
правды, исчезающий в локальном режиме и в приватных реестрах.
- Только соглашение об имени: ноль гарантий.
**Пересмотреть когда.** Появится третий тип связи между пакетами такой же
природы, помимо `documents` и `translates` — тогда обобщить в одну таблицу
отношений, не плодя поля.
**Решение.** Kind `app` допускается в этой же поправке. Граница по механике:
`tool` живёт в проекте и запускается через `vibe bin exec` по lock-файлу; `app`
— самостоятельный продукт со своим профилем деплоя в плоскости build, package,
deploy. Пакет сайта `org.vibevm.doc/web` — kind `app`.
**Почему.** Граница по существующей механике проверяема инструментами; граница
«по впечатлению» — нет.
**Отвергнуто.** Считать сайт `tool`: у сайта нет смысла «выполниться в
проекте по lock-файлу».
**Пересмотреть когда.** Появится второй `app` с другой механикой запуска.
**Решение.** Сайт монтируется под путём `/doc` основного домена. Язык — сегмент
пути после `/doc/`; исходный язык документации не носит префикса. Отображение
адресов детерминированное и без индекса:
spec://<группа>/<имя>@<версия>/<документ>#<якорь>
→ https://vibevm.org/doc/<группа>/<имя>/<версия>/<документ>#<якорь>
spec://<группа>/<имя>/<документ>#<якорь>
→ https://vibevm.org/doc/<группа>/<имя>/latest/<документ>#<якорь>
перевод на ru той же страницы
→ https://vibevm.org/doc/ru/<группа>/<имя>/<версия>/<документ>#<якорь>
Страницы старых версий несут `rel=canonical` на `latest` в пределах своего
языка. Локальный читатель использует ту же схему с другим origin. Адрес
страницы заканчивается слэшем (`…/<документ>/`), проекции лежат рядом как
файлы (`…/<документ>.md`, `…/<документ>.xml`); адрес без слэша получает
редирект 308 и в вебе, и локально (уточнение 2026-09-11 по A0.10:
единственный рабочий режим статического адаптера).
Адрес с номером версии всегда показывает **текущее** содержимое этой версии
в реестре: один номер может быть опубликован десять раз за день, и сайт
показывает последнюю публикацию. Постоянных ссылок на прошлые публикации
нет — их не существует и в реестре (D-27).
Весь домен — один сайт (девятая редакция, D-28): лендинг `vibevm.org/` и
`vibevm.org/ru/` и документация `/doc/…` собираются одной сборкой из одного
пакета. Корневые машинные файлы — `robots.txt`, `llms.txt`, `llms-full.txt`,
`sitemap.xml`, `feed.xml`, ключ-файл IndexNow — генерирует та же сборка,
сохраняя нынешние адреса и содержание лендинга: `robots.txt` один на домен
(ASCII-only, allow-лист краулеров) и несёт `Sitemap:` на `/sitemap.xml` и
`/doc/sitemap.xml`; корневой `llms.txt` открывается абзацем дизамбигуации
имени «VibeVM» и ссылается на `/doc/llms.txt`; документация публикует свои
файлы под `/doc/`: `/doc/sitemap.xml`, `/doc/llms.txt`, `/doc/llms-full.txt`,
`/doc/manifest.json`. Корневой `llms-full.txt` — лендинг, не копия
документации.
**Почему.** Путь под основным доменом делит его авторитет для SEO. Одна и та
же схема в вебе и локально означает, что ссылка в документации работает в обоих
мирах. Язык в пути, а не в параметре, — так его индексируют и цитируют.
Лендинг уже проиндексирован и несёт дизамбигуацию имени «VibeVM» для
AI-краулеров, поэтому его адреса и корневые файлы сохраняются при переезде на
тот же сайт байт в байт, где это возможно, и проверяются тестом паритета
(D-28).
**Отвергнуто.** Поддомен `docs.vibevm.org`; язык в query-параметре; язык в
поддомене; два сайта на одном домене — Astro-лендинг плюс Qwik-документация с
контрактом трёх строк между репозиториями (решение третьей редакции, снято
D-28).
**Пересмотреть когда.** Никогда в рамках волны; смена схемы адресов —
ломающее изменение с редиректами.
**Решение.** У сайта два источника, оба заданы конфигурацией той же формы, что
`[[registry]]` проекта:
- **реестр пакетов** — один, по умолчанию GitHub-организация `vibespecs`;
его индекс — лента изменений: сайт опрашивает `repomd.json` и `primary.jsonl`
(или получает webhook), сравнивает пары «координата, content hash» с
отрендеренным и пересобирает только изменившиеся;
- **репозиторий исходников хоста** — один, по умолчанию `github.com/vibevm/vibevm`;
из него рендерится сам `org.vibevm.core/vibevm` **по текущему состоянию
ветки `main`**: рендерер держит выкладку репозитория на диске (`git pull`
деплоем) и читает её как проект и как project-local реестр in-tree
пакетов — без публикации хоста в реестр и без git-источника пакетов
(уточнение 2026-09-11 по A0.20: корень хоста не пакет). Тегов релизов у
хоста нет (журнал, J-014). Сайт хранит только текущий рендер и
пересобирает его, когда ветка изменилась, с дебаунсом (D-16, D-27).
Рендер ключуется хэшем, идемпотентен и кэшируется. Ошибка рендера показывается
как страница версии. Обратные связи — зависимые, «объяснено в», «переведено
на» — берутся из индекса и карт, которые пакеты несут (`vibe specmap`).
Зеркала и вторые реестры — будущее.
**Почему.** Так устроен docs.rs над индексом crates.io, а у нас дешевле:
версия заморожена по content hash. Хост — не пакет реестра, и заставлять его
им стать ради сайта было бы ложным обобщением; git-источник уже поддержан.
**Отвергнуто.** Полная пересборка по расписанию; публикация хоста в реестр
ради рендера; чтение хоста с зеркала.
**Пересмотреть когда.** Владелец откроет зеркала или второй реестр.
**Решение.** Всё содержательное — в Rust-библиотеке (рабочее имя крейта
`vibe-doc`): HTML-бэкенд пивота, выдающий «остров» страницы; JSON-манифест
страниц; `llms.txt` всех уровней и языков; Markdown- и XML-проекции; проверка
примеров, цитат, переводов и покрытия; генерация плейсхолдеров и превью;
чтение источников (store, lock, реестр, git-источник). Поверхности над ней:
CLI `vibe doc build | serve | check | manifest`, инструменты MCP, HTTP-сервер.
Qwik-оболочка ничего не парсит: она получает остров как готовый HTML и данные
по JTD-контракту с генерируемыми TypeScript-типами.
**Почему.** Закон omnichannel. Если бы сайт заново парсил Markdown, якоря и
факты потеряли бы идентичность, а локальный и публичный рендер разошлись бы.
**Отвергнуто.** Статический генератор на стороне TypeScript, читающий
исходники сам.
**Пересмотреть когда.** Никогда в рамках волны.
**Решение.** `vibe doc serve` поднимает HTTP-сервер **только на 127.0.0.1**,
отдаёт оболочку и на каждый запрос вклеивает остров, отрендеренный из
машинного store, lock-файла текущего проекта или приватного реестра.
Предпочтение языка берётся из `[i18n].preferred` проекта, если он есть. Режим
полностью автономен: никаких обращений к vibevm.org, никаких внешних CDN и
шрифтов, всё в бандле. Сервер отдаёт файлы только из известных корней (store,
оболочка), без обхода путей и без листинга каталогов, с CSP без внешних
источников. Контракт встраивания для webview: относительные адреса и
настраиваемый базовый путь; команда «открой адрес» через URL и postMessage;
обратный сигнал «клик по файлу», чтобы хост-приложение открыло файл в
редакторе; тема — параметром запуска, и хост может переключить её на лету
через postMessage (плагин VS Code следует теме редактора, см. D-22). Локальный
сервер отдаёт `Content-Security-Policy: frame-ancestors` только для origin
хоста, который его запустил — параметром запуска `--frame-ancestor
<origin>`, потому что origin webview меняется от окна к окну; без параметра
`'none'`; CORS-слоя у читателя нет вовсе, а параметры запуска передаются в
страницу неисполняемым блоком `<script type="application/json">` без
`'unsafe-inline'` (уточнение 2026-09-11 по A0.7); публичный сайт во фреймы
не встраивается.
**Почему.** Так читается документация проприетарных пакетов; так плагин
VS Code получает интерфейс через iframe; так контент никогда не покидает
машину и не виден другим пользователям машины.
**Отвергнуто.** Отдельное «локальное приложение» с собственным кодом;
привязка к `0.0.0.0`.
**Пересмотреть когда.** Владелец откроет работу над плагином VS Code и
захочет нативный интерфейс вместо webview.
**Решение.** Диалект XML расширяется словарём жанра «документация»: пять
элементов и один атрибут, легальные только в документах doc-пакетов. У каждого
элемента записана проекция в Markdown и свой проверяющий.
| Элемент |
Назначение |
Проекция в Markdown |
Проверяющий |
| `example` с детьми `run`, `expect` (stdout) и необязательным `stderr`; атрибуты `id`, `fixture`, `lang`, `exit` (по умолчанию `0`), `when` |
команды и ожидаемый вывод; `fixture` называет герметичный проект-фикстуру, которая объявляет правила нормализации и карту «документ `--json` → JTD-схема»; отсутствующий `stderr` — утверждение «stderr пуст» |
два соседних fence, `sh` и `output` (третий — `stderr`, если есть) |
раннер `vibe doc check --examples` против собранного бинарника: точное совпадение после объявленной нормализации, шаблонов `match` нет (уточнение 2026-09-11 по A0.12); расхождение — красный |
| `example ref="<id>"` |
в переводе: ссылка на пример источника вместо собственного |
те же два fence, скопированные из источника при проекции |
существование `id` в источнике |
| `rule ref="spec://…#ЯКОРЬ"` |
точка вставки правила из спеки; сайт показывает **текущий** текст факта на месте, на языке спеки |
ссылка на якорь |
резолвер якорей; ребро `documents` без пина; исчезнувший якорь — ошибка сборки (D-27) |
| `derived kind="cli-help / jtd-schema / manifest-field" ref="…"` |
вставка машинно-выведенного справочника или поля манифеста (например, `abstract`) |
fence с текстом или таблица |
генератор при сборке; расхождение — красный, кроме явного `--accept` |
| `note kind="note / tip / warning"` |
врезка |
цитата с меткой в первой строке |
схема |
| `figure src alt` с ребёнком `caption` |
рисунок с подписью; файл лежит в дереве пакета как исходник |
inline-картинка плюс абзац подписи |
существование файла |
| `prompt id` с телом-заданием и детьми `needs`, `outcome`, `assert*` (седьмой элемент, по слову владельца — D-30) |
задание агенту в голосе пользователя, что агенту нужно, что увидит человек, шелл-команды, обязанные завершиться нулём после работы агента |
fence `prompt`, список «нужно», абзац «результат», список ассертов; в `llms*.txt` — тот же fence |
`vibe doc check --prompts`: прогон настроенным агентом в чистом временном каталоге, затем ассерты; не в панели; на странице сценария ассерт обязателен (линтер стиля) |
| атрибут `when="os:…"` на `example`, `note` и секциях |
платформенные варианты |
подзаголовок с именем платформы |
существующий словарь условий boot-лейна |
Вкладок нет намеренно, их заменяет `when`. Пошаговые процедуры — упорядоченный
список с `example` внутри. Инлайн-содержимое остаётся Markdown. Вывод команд в
`expect` нормализуется: временные пути, разделители, переводы строк, версии,
ANSI-последовательности.
*(Уточнено 2026-09-11 по находке A0.4 — как словарь ложится в пивот
`vibe-specdoc`, не меняя таблицы выше.)*
- **Словарь — параметр читателя.** `Vocabulary::{Spec, Doc}` (умолчание
`Spec`), аддитивные `from_xml_with` и `load_spec_text_with`; отображение
«kind пакета → словарь» делает вызывающая сторона, потому что пивот по
закону отделимости не знает `PackageKind`. Элемент жанра, встреченный в
словаре `Spec`, — громкая ошибка с жанровым сообщением, не игнор.
- **Дискриминатор против коллизии имён.** Имена `example`, `rule`, `derived`,
`run` уже живут в корпусе как именованные секции (`<example title="…">`).
Правило словаря: **блок жанра никогда не несёт `title=`, именованная
секция несёт его всегда**. Поэтому `<example title="…">` — секция в любом
словаре, `<example>` без `title` — блок в словаре `Doc`; писатель от
словаря не зависит.
- **`when` — на любом блоке и на секциях**, не только на `example` и `note`:
в пивоте условие — свойство слота (`BlockNode { when, block }`), а не
рода блока. Значения — закрытый список условий boot-лейна.
- **Проекция в Markdown необратима** для doc-жанра: `md_out` даёт лучшую
проекцию каждого элемента (колонка таблицы), обратный разбор даёт другой
IR; это закон жанра, закреплённый тестом, а не дефект. Авторинг
документации — только XML.
- **Адрес `rule` отбрасывает `~rN`**: пин, случайно попавший в атрибут, не
становится пином ребра (D-18, D-27).
- **Тексты `run`, `expect`, тела `prompt` и `assert`** — дословные, как
`fence`; CDATA в них разрешена явным списком.
- **Раннер примеров** (по макету A0.12): cwd команды — свежая песочница с
копией фикстуры, никогда дерево; изоляция одной переменной
`VIBE_SETTINGS` в нативном написании пути плюс `NO_COLOR`; поведенческие
переменные (`VIBE_OFFLINE`, `VIBE_UNATTENDED`, `VIBE_INVOKED_BY`,
`VIBETERM`, `VIBEFRAME`) вычищаются — флаги стоят в самом примере;
tripwire на неизменность настоящего `~/.vibe` и исходного дерева; stdout
и stderr захватываются раздельно; примеры документируют не-TTY ветку
продукта (интерактивные подсказки описываются прозой); `--json`
разбирается как поток документов, каждый сверяется со схемой по карте
фикстуры, документ без схемы сообщается как непроверенный; валидатор
JTD пишется в `vibe-doc` (в `vibe-wire` его нет — схемы там вход
кодогенерации). Нормализация: `<TMP>`, `<HOME>`, `<REPO>`, слэши, CRLF в
ожидаемых файлах, `vibe <VERSION>` (версии пакетов не трогаются), ANSI,
сортировка блоков по объявленной форме строки, локальные `replace`
фикстуры; порядок — замены путей до унификации слэшей, сортировка после
всех замен.
**Известное ограничение.** README и спеки пакетов других видов не могут нести
проверяемые примеры — словарь включается по kind пакета. Их fence-блоки
рендерятся на уровне 0 как есть, непроверенными.
**Почему.** Владелец выбрал вариант А: именованный тэг самоописателен для
агента, а пример проверяем по построению. Это переоткрытие записанного решения
PROP-045 «диалект — ровно подмножество Markdown»; по закону decision-records
переоткрытие обязано назвать сработавший триггер: появился потребитель,
которому нужна конструкция, невыразимая в Markdown. Триггер назван — жанр
документации.
**Отвергнуто.** Markdown с директивами; соглашения внутри нынешнего диалекта;
элемент вкладок; собственные примеры в переводах.
**Пересмотреть когда.** Два авторских запроса на конструкцию вне этого набора
или на проверяемые примеры в README обычного пакета, записанных в BACKLOG.
**Решение.** В словарь `audience` добавляется значение `agent`. Значения
`user`, `author`, `dev` остаются и соответствуют оператору, автору и
мейнтейнеру из плана DOCS; «новичок» — маршрут внутри `user`. Текст с
`audience="agent"` подчиняется законам агентского текста: бюджет токенов, без
повествования, никогда не в boot-префиксе; сайт отдаёт его в разделе «для
агентов» и первым в `llms.txt`. Аудитории документации не объявляются в
манифесте — выводятся из разметки страниц.
**Почему.** PHASE-G-SPEC предсказал дыру: boot-сниппет и инструкции скилла
читает не человек, а сессия. Разметки `audience` в корпусе почти нет, менять
словарь дёшево сейчас.
**Отвергнуто.** Отдельный жанр вместо аудитории; две оси «кто читает × роль»;
поле аудиторий в манифесте.
**Пересмотреть когда.** Появится текст, которому не хватает ни одного из
четырёх значений.
**Решение.** Сайт — TypeScript под дисциплиной `typescript-ai-native`, Qwik
2.0 beta (next.qwik.dev), версия запинена точно, вместе с версиями Node и
pnpm. Один код оболочки, два адаптера: статический для сервера (пререндер
каждого маршрута, остров вклеен при сборке) и встраиваемый для `vibe`.
**Предложенный механизм встраивания (ждёт подтверждения владельца):**
- Шаг `cargo xtask embed-doc-shell` собирает web-пакет из исходника
(pnpm build со встраиваемым адаптером) и складывает результат — шаблон
маршрута с местом под остров, скрипты, стили — в каталог, который крейт
`vibe-doc-shell` включает в бинарник через `rust-embed` или `include_dir`
за фича-флагом `embedded-shell`.
- Релизная сборка `vibe` включает флаг и падает, если оболочки нет.
Обычная `cargo build` без Node компилируется с запасной оболочкой — голый
HTML без скриптов.
- **Сборка из исходников без Node** (`vibe self install`, `first-run`) не
остаётся с голой оболочкой навсегда: при первом `vibe doc serve` читатель
предлагает скачать оболочку, соответствующую его версии, из релизных
активов, проверяет content hash по пину и кладёт в store версий VVM; при
отказе или офлайн работает запасная оболочка. Скачивание только по явному
согласию, никогда автоматически.
- `vibe doc serve` отдаёт статику оболочки из бинарника или из store версий и
на каждый запрос вклеивает остров, отрендеренный Rust-конвейером.
- Координата и content hash оболочки пинуются в lock-файле рядом с `vibe`;
self-check сверяет встроенную оболочку с пином; `vibe doc serve` умеет
сообщить, что несёт.
- Оболочка собирается с настраиваемым базовым путём и относительными
адресами; внешних скриптов нет.
- Тест паритета: над одним пакетом прогоняются оба адаптера и сравнивают
остров байт в байт.
- Шрифты — самохостинг в бандле оболочки, латиница и кириллица отдельными
подсетами woff2 с `unicode-range` (тот же приём и те же файлы, что у
лендинга); внешних шрифтовых сервисов нет ни в вебе, ни локально.
*(Уточнено 2026-09-11 по находкам A0.10 и A0.11.)* Пины: `@qwik.dev/core`
и `@qwik.dev/router` `2.0.0-beta.43` (линия 2.0 с next.qwik.dev живёт под
npm-тегом `beta`; `latest` — это 1.x и не используется), Vite `8.2.1`, Node
`24.18.0`, pnpm `10.33.2`; статический адаптер — `ssg`
(`@qwik.dev/router/adapters/ssg/vite`). Один сайт собирается с `base: "/"`,
а `/`, `/ru/` и `/doc/…` — каталоги маршрутов; встроенный адаптер —
отдельная конфигурация с `base: "/doc/"` и маршрутами документации в
корне. Адреса страниц заканчиваются слэшем: это единственный рабочий режим
беты (D-06). Встраивание — крейт `include_dir` (MIT, четыре зависимости;
`rust-embed` в отладочной сборке читает с диска), `build.rs` с
`rerun-if-changed` и остановкой при отсутствии `shell/index.html` под
фичей `embedded-shell`, пин — `VIBE_DOC_SHELL_SHA256` константой бинарника.
Оболочка в релизе — **отдельный актив** `vibevm-doc-shell-<версия>.zip` без
цели платформы с отдельным манифестом `DOC-SHELL.json` той же формы, что
`DISTRIBUTIONS.json` (в который поле добавлять нельзя: схема закрыта, и
старые `vibe` потеряли бы `self update`). Скачанная оболочка живёт в общем
контент-адресуемом каталоге `~/.vibe/opt/vibevm/doc-shell/<sha256>/`, не
внутри неизменяемого экземпляра; команда — `vibe doc shell install
[--assume-yes]` с согласием по образцу `install`; без оболочки и без сети
читатель работает на запасной оболочке и предупреждает — никаких
обращений в сеть без согласия.
Провайдер сборки Node в плоскости build нужен только серверной сборке; на
машине читателя Node не требуется. Серверная сборка идёт в Docker по образцу
лендинга: стадия сборки на образе Node собирает оболочку и рендерит
страницы, стадия выдачи — стоковый nginx (D-23).
**Почему.** Владелец выбрал Qwik 2.0 и Б для локального читателя. Бета
допустима по закону «свежая, но хорошо спроектированная библиотека» с точным
пином и триггером пересмотра. Тождество публичного и локального рендера держится
на общем острове, а не на общем JS-рантайме. Пункт 3 закрывает дыру: иначе
каждый, кто ставит vibe из исходников, получал бы урезанный читатель.
**Отвергнуто.**
- SSR Qwik локально через встроенный JS-движок (QuickJS).
- Собранная оболочка рядом с бинарником в релизном zip вместо встраивания.
- Собранные ассеты внутри пакета `org.vibevm.doc/web`: закон P-10.
- Требовать Node для сборки vibe из исходников.
**Пересмотреть когда.** Выход стабильной Qwik 2.0 или ломающее изменение
беты, требующее переписывания.
**Решение.** Публичный сайт ОБЯЗАН:
- отдавать полностью серверно отрендеренный HTML, без содержимого за
скриптами;
- держать одну каноническую страницу на факт и язык: старые версии несут
`rel=canonical` на `latest` своего языка; между языками — `hreflang` на
каждый доступный язык и `x-default` на исходный язык документации;
- публиковать sitemap-индекс по пакетам и языкам с `lastmod` из даты
публикации;
- в `robots.txt` явно разрешать краулеров OpenAI, Anthropic, Google, Perplexity
и других; список имён агентов **проверяется по документации провайдеров при
каждой сборке**, а не переписывается по памяти; `robots.txt` один на домен
и генерируется сборкой сайта вместе с корневыми `llms.txt`, `sitemap.xml`,
`feed.xml` (D-06, D-28); файл держится ASCII-only, как у прежнего лендинга;
домен не за Cloudflare (D-23), поэтому снимать там блокировку AI-краулеров
не нужно;
- отдавать все текстовые форматы с `charset=utf-8` (`charset_types` в
контейнерном nginx, как у лендинга) и все редиректы относительными
(`absolute_redirect off; port_in_redirect off;`) — TLS терминируется вне
контейнера, и абсолютный `Location: http://…` роняет строгих фетчеров в
петлю редиректов, что уже случалось с фетчером Claude на oleg.guru;
- после каждого деплоя с изменением страниц отправлять список изменённых URL
в IndexNow ключом лендинга (ключ-файл в корне домена уже есть);
- нести JSON-LD (`TechArticle` с `headline`, `abstract`, `author`,
`inLanguage`, `keywords`, `datePublished`, `image`; `SoftwareApplication`;
`BreadcrumbList`; `FAQPage` где уместно), Open Graph и Twitter Card
`summary_large_image` с превью из `[media].preview` или сгенерированной
карточкой (D-20);
- публиковать `llms.txt` (индекс с однострочными резюме) и `llms-full.txt`
для базового корпуса, плюс `llms-small.txt` и `llms-medium.txt` под бюджет
токенов, все — выведенные из того же манифеста, что и навигация, а полный
корпус упорядочен по закону слоёв; те же файлы — на каждый язык и на каждый
пакет; реестровый `llms.txt` — каталог документаций в стиле arXiv: заголовок,
звёздочка официальности, издатель, язык, аудитории, аннотация, ссылка;
- отдавать каждую страницу как чистый Markdown по адресу с суффиксом `.md` и
как сырой XML по адресу с суффиксом `.xml`;
- отдавать JSON-манифест страниц со статусами официальности, языками,
аудиториями, жанрами, якорями и резюме, эндпоинт-резолвер `spec://` и,
опционально, MCP-сервер сайта;
- держать плотный внутренний граф ссылок: зависимые, «объяснено в»,
«переведено на», спека ↔ документация;
- строить страницы по одному шаблону: ответ первой фразой, один концепт на
страницу, глоссарий с каноническими терминами, FAQ в форме вопросов, примеры
с ожидаемым выводом; страницы сценариев — промпт сначала, механика потом,
ручные шаги только когда они нужны (D-30).
Локальный режим ничего из этого не публикует и ни к чему внешнему не
обращается.
**Почему.** Слово владельца: максимальное SEO включая LLM SEO. Каждый пункт
либо стандарт, либо следствие закона проекта.
**Отвергнуто.** Блокировать AI-краулеров; ручные описания страниц; превью
ссылки обрезкой баннера; собственный `robots.txt` под `/doc/`.
**Пересмотреть когда.** Появится новый стандарт машинного индекса.
**Решение.** Doc-пакеты входят в include-globs `facts.toml` и в карту
трассируемости, но **не судятся**: их факты не входят в долг судейства, потому
что жанр ненормативен; механизм исключения выбирается спайком. Каждый `rule`
даёт ребро `documents` **без пина**: цитата — живая, страница при каждом
рендере показывает текущий текст факта по адресу; `vibe doc check
--citations` проверяет одно — что якорь существует; исчезнувший якорь без
tombstone роняет сборку. Никаких ревизий, хэшей текста и «спека ушла
вперёд»: такие проверки требовали бы истории, которой в проекте нет по
замыслу (D-27). Устарела ли **проза вокруг** цитаты — вопрос к человеку на
полной сверке (D-26), не к машине. Примеры с `expect` прогоняются в панели self-check как
golden-тесты — единственная техническая связка продукта с документацией;
оставить ли её — вопрос владельцу (§10 п. 12). **Гейт покрытия:** факты спек, помеченные
`actionstage="doc"` с аудиторией, — это обязательства; `vibe doc check
--coverage` требует, чтобы каждое обязательство было процитировано страницей
для той же аудитории; разметка обязательств в корпусе спек — отдельный атом
кампании, тот самый «суд», которого фазе G не хватило. Навигация сайта
выводится из манифеста страниц, а не из этого отчёта.
**Почему.** Односторонняя связь без обратного обнаружения — это тихое гниение.
Покрытие, измеренное гейтом, отвечает на вопрос «всё ли рассказано», на который
навигация не отвечает.
**Отвергнуто.** Ручной список страниц как источник; оглавление из отчёта
обязательств; судейство фактов документации.
**Пересмотреть когда.** Никогда; это следствие P-02 и P-04.
**Решение.** `docs/` переезжает в `docs-legacy/` одним коммитом-переносом
без иных изменений. Новая документация пишется против неё: факт, который был
там и отсутствует в новой, — либо снят с записанной причиной, либо
регрессия. `README.md`, `DEV-GUIDE.md`, `RUNTIME-GUIDE.md` остаются на месте и
обновляются по закону same-commit.
**Почему.** Так постановил PHASE-G-SPEC §2: архив, не удаление.
**Отвергнуто.** Удалить `docs/`; переписать на месте.
**Пересмотреть когда.** Регрессионный список закрыт и владелец подтвердил.
**Решение.** Сам vibevm рендерится из одного настроенного репозитория
исходников, по умолчанию `github.com/vibevm/vibevm`, **по текущему
состоянию ветки `main`** — и только по нему. Тегов релизов у хоста нет
(единственный тег — `pre-cultural-refactor`, не релизный; журнал J-014);
релиз по факту — это то, что сейчас в `main` и что `vibe self install
latest` собирает из исходников. Сайт опрашивает ветку, при изменении
пересобирает рендер с дебаунсом (конфигурация A5.1: не чаще раза в час) и
хранит один текущий рендер плюс предыдущий до успешного завершения нового.
Никакой истории состояний: её нет и в самом репозитории. Зеркала и
дополнительные репозитории — будущее. **Вопрос владельцу переформулирован**
(§10 п. 2): только частота опроса.
*(Уточнено 2026-09-11 по находке A0.20.)* Корень хоста — `[project]`, не
`[package]` (B-031 дал ему полное имя `org.vibevm.core/vibevm`, но не сделал
публикуемым пакетом), поэтому «хост как пакет» не выбирается ни через
git-источник, ни через store. Канал хоста — **выкладка на диске**: деплой
делает `git checkout main && git pull` в каталоге рендерера, и рендерер
читает оттуда сам хост как проект (уровень 0 — `README.md`, `vibevm/vibespecs/**`,
boot-сниппет, манифест) и документацию ядра как in-tree пакет через
project-local реестр (`vibevm/vibepacks`). Клон в кэш пакетов и `vibe cache
add` на сервере не нужны. Перерендер — когда содержимое выкладки изменилось;
сравнение по внутреннему хэшу содержимого, который наружу не показывается
(D-27): у in-tree пакетов номер версии стоит на месте, а содержимое идёт.
**Почему.** Слово владельца: «тот репозиторий, который указали в настройках,
по умолчанию гитхаб». Первая редакция этого вижена прочла это как «реестр»;
вторая и третья — как «по тегам»; шестая пыталась хранить состояния по хэшу
дерева; седьмая, по слову владельца, оставила только текущее: история
переписывается намеренно, и документация не должна притворяться, что помнит
её.
**Отвергнуто.** Публикация хоста в реестр ради рендера; зеркала; рендер по
тегам (их нет); хранение состояний по хэшу дерева или коммита (фича,
требующая истории — D-27).
**Пересмотреть когда.** Владелец откроет зеркала.
**Решение.**
- Поправка реестра видов в `VIBEVM-SPEC.md` §4.1 — рукой владельца; агент
готовит точный дифф.
- `PROP-000`: инвариант словаря и набор видов.
- Новая спека `PROP-057` в `vibevm/vibespecs/common/`: семантика kind `doc` и
`app`, конвенция спутника, поля связи, локализация, обнаруживаемость и
иерархия, карточка, контракт сайта, контракт SEO, локальный режим,
реестровый билдер. С полными записями решений.
- Поправки: `PROP-028` (роль `-docs`), `PROP-045` (словарь жанра
документации), `PROP-043` (значение `agent`), `PROP-003` (переиспользование
тегов и цепочки отката для пакетов-переводов, без sidecar).
- Строка «документация» в таблице жанров хоста.
- `PHASE-G-SPEC.md` получает пометку «замещён PROP-057».
- План стюарда: маршрут `DOCS` расширяется узлами по фазам плана.
- Этот вижен импортируется как design-документ хоста **в XML-диалекте**, по
правилу корпуса, и связывается с PROP-057 двусторонней ссылкой.
**Почему.** Закон two-process: знание, оставшееся только в разговоре, не
переживает сессию.
**Решение.** Перевод документации — отдельный пакет kind `doc`:
[package]
name = "vibevm-docs-ru"
group = "org.vibevm.core"
kind = "doc"
title = "Руководство VibeVM"
abstract = "…"
[i18n]
canonical = "ru" # язык пакета — существующее поле PROP-003, тег BCP-47
[[documents]] # тот же предмет, что у источника
package = "org.vibevm.core/vibevm"
version = "^1.0"
[translates]
package = "org.vibevm.core/vibevm-docs"
version = "^0.3"
*(Уточнено 2026-09-11 по находкам A0.18 и A0.21: язык doc-пакета — уже
существующее поле `[i18n].canonical` (по умолчанию `en`), а не новое поле
`lang`; один факт — один якорь. Обратная таблица `[translations]` в
манифесте источника **не хранится**: какие переводы есть у документации,
сайт и локальный читатель вычисляют из рёбер `translates` при каждом
рендере — так же, как официальность из `documents` и `documentation`
(R-23). `[i18n].available` у doc-пакета пуст по построению.)*
Правила:
- у источника `[i18n].canonical` по умолчанию `en`, как канонический язык
PROP-003; sidecar-раскладка §2.7.1 к doc-пакетам не применяется;
- перевод **зеркалит дерево источника файл в файл**: те же пути, те же якоря,
те же идентификаторы фактов; добавлять или удалять якоря нельзя;
- перевод **не хранит ни ревизии, ни хэша** исходной страницы (D-27:
сравнение «с тех пор» требует истории); `vibe doc check --translations`
проверяет только структуру — те же пути, якоря, число и типы блоков;
отстала ли адаптация по смыслу — вопрос к человеку на полной сверке
(D-26); сайт показывает дату последнего чтения адаптации из
`reviews.toml`;
- перевод не авторит примеры: только `example ref` на пример источника;
вывод команд проверяется один раз, на источнике;
- `documents` перевода обязан совпадать с `documents` источника; `vibe check`
это проверяет;
- **официальный** перевод — тот, что объявил `translates` на источник и
издан **той же группой**, что источник, под именем
`<имя-документации>-<lang>`; всё остальное — перевод сообщества (D-19);
отдельного списка переводов в источнике нет (уточнение 2026-09-11 выше);
- сайт: язык в пути (D-06), селектор на каждой странице, откат на исходный
язык постранично с пометкой, никогда не 404; `hreflang` и `x-default`;
`llms.txt` на язык;
- локальный читатель: то же из store; предпочтение — `[i18n].preferred`
проекта или флаг;
- нормативные спеки остаются на языке спеки: `rule` показывает текст правила
на языке источника с пометкой; перевод нормативного текста в эту волну не
входит.
**Почему.** Цели владельца — разные авторы, разные ритмы, официальность по
языку — это цели владения, а единица владения в проекте — пакет. Правила
зеркалирования и ссылочных примеров берут у sidecar-модели то, что делало её
безопасной: совпадающие якоря, постраничный откат, один источник вывода
команд.
**Отвергнуто.**
- Sidecar-файлы внутри одного пакета (PROP-003 как есть): пакет растёт с
каждым языком, переводчику нужны права на пакет, любая правка перевода
бампает всю документацию, проверка покрытия не видит устаревания.
- Гибрид «официальные как sidecar, сторонние как пакеты»: два механизма.
- Перевод, объявляемый предметом: переиздание предмета на каждый язык.
- Собственные примеры в переводе: расхождение выводов по языкам.
**Пересмотреть когда.** Появится запрос на перевод нормативных спек
(наблюдение: пакет-перевод, пытающийся зеркалить дерево спек, а не
документации).
**Решение.** Сайт находит документацию и переводы **по рёбрам**: все пакеты
kind `doc` из индекса, у которых `documents` или `translates` указывают на
данную координату, из любой группы. Звёздочка появляется только там, где
ребро подтверждено сверху.
| Уровень |
Статус |
Кто подтверждает |
| Документация предмета |
★ основная · ★ официальная · community |
предмет через `[documentation]` или соглашение `<имя>-docs` в своей группе |
| Перевод документации |
★ официальный · community |
исходная документация через `[translations]` или соглашение `<имя-документации>-<lang>` в своей группе |
Четыре сочетания видимы все: официальная документация с официальным
переводом; официальная с переводом сообщества; документация сообщества с
переводом, который её автор назвал официальным; документация сообщества с
переводом сообщества. Звёздочка у перевода означает «назван автором этой
документации», а не «одобрен предметом»; подсказка говорит это словами.
Правила интерфейса:
- три сигнала согласованы: звёздочка, подпись «официальная» или «сообщество»,
порядок «основная, официальные, community»; ни один не противоречит другим;
- издатель всегда виден: группа пакета печатается рядом с названием;
- селектор языка показывает все найденные языки: сначала со звёздочкой, потом
community, у каждого группа издателя и отставание;
- полки на странице пакета повторяют схему для документации; внутри полки —
те же значки для переводов.
Машинное зеркало: манифест страниц несёт статус на обоих уровнях, `primary`,
`official` или `community`, и язык; `llms.txt` помечает официальные элементы,
чтобы агент предпочитал их, но видел и остальные. Индекс несёт поля связи,
`lang`, `title`, `abstract`. Модерации нет: полка community показывает всё,
что нашлось; защита от подмены — издатель на виду; списки исключений —
отложенное.
**Почему.** Слово владельца: неофициальное должно находиться и показываться
как сообщество, а иерархия — быть наглядной. Рёбра дают полноту, назначение
сверху — однозначность, звёздочки и порядок — наглядность.
**Отвергнуто.** Показывать только официальное; пометки официальности в
индексе; модерация в этой волне.
**Пересмотреть когда.** Первый случай злоупотребления полкой community
(наблюдение: жалоба владельцу пакета).
**Решение.** Манифест пакета получает поля карточки; для kind `doc` `title` и
`abstract` обязательны, для остальных видов необязательны, `[media]`
необязателен для всех:
[package]
title = "VibeVM Manual"
description = "The operator's guide to vibe: install, lifecycle, registries, agents."
abstract = """
What it covers, for whom, what it assumes known, what it leaves out.
Three to six sentences, one language — the package's own.
"""
[media]
icon = "media/icon.png" # квадрат, 256–1024 px, PNG/JPEG/WebP, до 256 КБ
banner = "media/banner.jpg" # 3:1, рекомендовано 1500×500, до 1 МБ
preview = "media/preview.png" # 1,91:1, рекомендовано 1200×630, до 1 МБ
Правила:
- `title` — отображаемое имя в полках, селекторе, заголовке страницы и
каталоге; уникальность не проверяется, идентичность остаётся координатой,
издатель виден рядом;
- `description` остаётся однострочным подзаголовком для списков и
мета-описания страницы; `abstract` отвечает на четыре вопроса — что
покрывает, для кого, что предполагает известным, чего не покрывает — и
ограничен примерно тысячей знаков; входная страница не пересказывает
аннотацию, а вставляет её через `derived kind="manifest-field"`;
- аудитории и языки в карточке не объявляются — выводятся из разметки
страниц и связей `translates`;
- картинки — исходник в дереве пакета; форматы PNG, JPEG, WebP; SVG в этой
волне запрещён, потому что умеет нести скрипты, а локальный читатель отдаёт
картинки проприетарных пакетов как есть; `vibe check` и гейт публикации
проверяют существование, сигнатуру формата, пропорции и размер; лимиты малы
намеренно — пакеты обычных видов материализуются и коммитятся у
потребителей;
- `icon` — в шапке страницы пакета и на карточках полок; `banner` — шапка
страницы пакета; `preview` — `og:image`, `twitter:image` с карточкой
`summary_large_image`, `image` в JSON-LD;
- **плейсхолдеры генерируются**, не хранятся: градиент или узор для баннера и
глиф для иконки вычисляются из хэша координаты, так что пакет выглядит
одинаково на сайте и в локальном читателе, а разные пакеты различимы; глиф
зависит от вида — книга для `doc`, свои знаки для остальных видов;
встроенный SVG при рендере, без файлов и без сети;
- превью при отсутствии `preview` собирается при сборке сайта из
плейсхолдера, иконки и заголовка — не обрезкой баннера; в первой волне
превью одно на пакет, карточки с заголовком отдельной страницы — отложенное;
- перевод наследует картинки источника, если не объявил свои;
- сборка сайта копирует картинки под хэшированными именами для кэширования и
никогда не подгружает их с чужих адресов; alt-текст — из `title`.
**Почему.** Слово владельца: карточка как у arXiv и как у профиля в
Twitter. Заголовок и аннотация в манифесте — потому что индекс и полка должны
показывать их без скачивания пакета; отдельное превью — потому что пропорции
баннера и превью ссылки несовместимы; генерируемые плейсхолдеры — закон P-04.
**Отвергнуто.**
- Показывать `description` вместо заголовка; брать заголовок из входной
страницы; аннотация как раздел страницы с копией в индексе.
- Статический набор плейсхолдеров.
- Превью обрезкой баннера; имя поля `og_image` (картинку читают не только
Open Graph).
- SVG в этой волне.
**Пересмотреть когда.** Запрос на SVG-иконки с санацией; запрос на
многоязычные заголовки в одном пакете (наблюдение: BACKLOG).
**Статус.** Рабочая гипотеза, чтобы разработка не ждала дизайнера. Решение
пересматривается на **дизайн-ревью** после первого живого рендера
документации ядра (план, A4.14): владелец смотрит полку, страницу пакета и
страницу документации в обеих темах и решает про шрифты, плотность и тему по
умолчанию. До ревью всё ниже — норма для разработки, после — правится на
месте с датой.
**Решение.** Одна дизайн-система в двух темах, сшитая из двух существующих
источников владельца (§2.5); оба построены на одной терракоте.
- **Светлая тема — токены тёплой дизайн-системы** (`design-system/public/assets/css/anthropic.css`, `:root`):
фон страниц `--ivory-100 #FAF9F5` (`--ivory-50 #FCFBF8` для документации,
как на её странице `/docs`), секции `--ivory-200 #F0EEE6` и `--ivory-300
#E8E5D9`, карточки спек и сводных таблиц `--cream-100 #F1ECDF`, панели
`--tan-100/200/300`; чернила `--ink #141413`, текст `--text #1F1E1B`,
вторичный `--muted #63625B`, подписи `--faint #8E8D85`; границы `--border
#E0DDD2`, `--border-strong #C9C6BA`; акцент `--terracotta #CC785C`,
`--terracotta-deep #C15F3C`, `--terracotta-bright #D97757`,
`--terracotta-soft #EBCBBC`, `--terracotta-bg #F6EDE6`; палитра
иллюстраций (`--olive`, `--periwinkle`, `--blue`, `--sage`, `--beige-illo`);
цвета графиков `--chart-1…6`, `--chart-grid`; радиусы 8/12/16/24/pill; три
тени (`card`, `hover`, `mega`); `--speed 0.18s`.
- **Тёмная тема — токены лендинга** (`vibevm-org/src/styles/global.css`):
фон `--ink #14120E`, поверхности `--ink-raise #1C1A15`, футер `--ink-sink
#100F0B`, текст `--cream #F4F1E8`, вторичный `--dim #A8A197`, подписи
`--faint #6F695E`, акцент `--accent #D97757`, `--accent-hover #E08A6D`,
`--accent-soft rgba(217,119,87,.14)`, границы `--line #2E2A22`,
`--line-strong #3A352B`; тёплый радиальный «ambient wash» фона.
- **Один акцент на обе темы.** `--terracotta-bright` дизайн-системы и
`--accent` лендинга — один и тот же `#D97757`; значит, это одна система в
двух режимах, а не две системы. В оболочке токены **семантические**
(`--bg`, `--bg-raise`, `--bg-sink`, `--text`, `--text-2`, `--text-3`,
`--line`, `--line-strong`, `--accent`, `--accent-hover`, `--accent-soft`,
`--code-bg`, `--selection`) с двумя картами значений под
`:root` / `[data-theme="light"]` / `[data-theme="dark"]` и
`prefers-color-scheme`; сырые имена цветов остаются только в файле палитры
как источник карт. Компонент никогда не пишет цвет литералом.
- **Типографика.** Spectral (display: hero, `h1`, заголовки пакетов; курсив
для акцентного слова, как на лендинге), Inter (текст и интерфейс, с
`font-feature-settings 'cv05' 1, 'ss01' 1`), JetBrains Mono (код, номера
абзацев, eyebrow-метки, мета-строки). Все три уже самохостятся лендингом
раздельными подсетами латиницы и кириллицы (`unicode-range`) — один
шрифтовой конвейер на домен и на бандл оболочки. Manrope + Source Serif 4
дизайн-системы — **резервный вариант для A/B на дизайн-ревью**, не
обязательство. Размеры: текст 16–18px, `line-height` 1.6–1.75, колонка
чтения 740px по умолчанию (шаги ширины — D-22).
- **Компоненты, переносимые из дизайн-системы** (по именам в `anthropic.css`,
переписываются как Qwik-компоненты на семантических токенах, а не
подключаются файлом): `.docs-header` + `.docs-nav` (шапка: бренд, селектор
языка пилюлей, поиск `Ctrl K`, ссылки, тема; строка вкладок разделов),
`.doc-card` (карточки-входы с линейными иконками), `.search-box`, `.toc`
(липкое оглавление, подсветка активного пункта через IntersectionObserver
с `rootMargin '-15% 0px -70% 0px'`, как в `ui.js`), `.toc--numbered`,
`.prose`, `.footnotes`, `.tag` / `.badge`, `.accordion`, `.tab-pills`
(переключатель платформ для `when`), `.data-table` / `.table-scroll` /
`.breakout` (широкие таблицы внутри узкой колонки), `.share-row`,
`.photo-ph` (тёплый градиентный плейсхолдер — основа генерируемых баннеров
D-20), `.fab` (плавающая кнопка: у нас «для агента» — адрес `spec://`,
ссылки `.md`/`.xml`/llms, копирование; **не** ИИ-чат), тёмный
футер-каталог, `.section-head` («Related» + «See all»).
- **Образ страниц из скриншотов** (образ, не копия): `/docs` — шапка,
поиск, вкладки, серифный hero с одной строкой подзаголовка и полем
«спросить», сетка карточек 3×2; статья — центрированная шапка с тегами и
датой, узкая колонка, сноски, «Related»; страница продукта — липкое
оглавление слева 190px, столбец 660px, кнопка действия под оглавлением.
- **Тема по умолчанию** — системная (`prefers-color-scheme`) с ручным
переключателем и запоминанием; embedded-режим следует теме хоста (D-09).
Обе темы проходят **APCA-аудит** скриптом по приёму
`oleg-guru/scripts/audit-contrast.mjs`, но собственной реализацией
опубликованной формулы APCA (библиотека `apca-w3` — AGPL и в дерево не
входит; уточнение 2026-09-11 по A0.23). Пороги по ролям: основной текст
Lc ≥ 75; вторичный и третичный (подписи, eyebrow, мета-строки) ≥ 60;
интерактивные контуры ≥ 45; разделители `--line`/`--line-strong` и номера
абзацев с `opacity .5` — декоративны и из гейта выведены; акцентные цвета —
by design. Аудит A0.23 показал: третичный текст светлой темы и вторичный с
третичным тёмной ниже 60 (предсказание 10 подтверждено, Lc 57.15) — в
палитре чеканятся новые тона на том же хью с суффиксом `-docs`, ближайшие к
исходным, которые проходят порог; точные значения подбирает аудит, не
глаз. Один `--bg` на тему: светлый — `--ivory-100`, как `--page-bg`
источника; отдельного фона страниц документации нет.
- **Движение** только осмысленное (стрелка кнопки, подсветка оглавления,
дорисовка графа на лендинге); `prefers-reduced-motion` отключает всё.
- **Локальный читатель** — те же токены и компоненты; отличия только в
шапке (нет поиска по реестру, есть «источник: store / lock / реестр»).
**Почему.** У владельца уже есть две согласованные вещи: дизайн-система по
эталону «документация, которую любят», и развёрнутый лендинг с тёмной тёплой
палитрой на той же терракоте. Сшить их дешевле и честнее, чем рисовать
третью систему (P-14). Семантические токены — потому что две темы и
embedded-режим иначе размножат CSS. Выбор шрифтов лендинга — потому что они
уже самохостятся с кириллицей и держат бренд между корнем домена и `/doc/`.
**Отвергнуто.** Палитра oleg.guru (холодная тёмная с бирюзой и розовым — не
язык бренда; берутся её фичи, не цвета); Tailwind где бы то ни было на сайте — лендинг тоже переезжает на токены
(D-28); подключение `anthropic.css` целиком; внешние шрифтовые сервисы;
ИИ-чат на сайте.
**Пересмотреть когда.** Дизайн-ревью A4.14; появление дизайнера; A/B
шрифтов.
**Решение.** Страница документации (уровень 1; README и спеки уровня 0 — в
том же ридере) повторяет поведение ридера статей oleg.guru
(`scripts/templates/article.html.tpl`, `podcast-episode.html.tpl`,
`public/js/{theme,lang-fallback,lightbox}.js`) с поправками на документацию.
Десять фич:
- **Нумерованные абзацы** (якоря «по Лебедеву»). Каждый блок пивота —
абзац, заголовок, список, таблица, fence, цитата, `example`, `rule`,
`note`, `figure` — получает порядковый номер и id `pNN` **на сборке**
(Rust-конвейер, не клиентский скрипт, как у oleg.guru): номер — позиция
блока в **текущем** тексте страницы (считается до фильтрации `when`,
так что `p12` означает один и тот же блок в сборке для любой ОС и
агента и в переводе, а пропуски в выводе приняты — уточнение
2026-09-11 по A0.25); он попадает в HTML-остров, в
проекции `.md` и `.xml` (как `[p12]` в начале блока) и в `llms-full.txt`,
поэтому человек и агент цитируют одно и то же место. После правки
страницы старая ссылка `#p12` может указать на соседний блок — как ссылка
на строку файла после правки; это принято, и ничто не пытается это
«помнить» (D-27). Вид: число в левом поле мелким моно с
`opacity .5`, две цифры с ведущим нулём; клик — `#pNN` в адресной строке
через `history.replaceState`, полный URL в буфере, галочка на 1.5 с;
открытие `#pNN` скроллит блок в центр; на узких экранах номер — строкой над
блоком; внутри цитаты сдвинут в поле; переключатель «якоря» прячет номера
(сохраняется). Заголовки сохраняют именованные якоря `{#id}` поверх номера;
именованные якоря живут по R-06, позиционные `pNN` — по текущему тексту;
ссылка «для агента» — адрес страницы и `#pNN`, без версий и хэшей.
- **Переключение перевода с сохранением места.** Селектор языка (D-18, D-19)
ведёт на ту же страницу другого языка **с тем же фрагментом** (`#pNN` или
`#id`). Это возможно, потому что перевод зеркалит блоки один к одному: R-18
расширяется с якорей на блоки, `vibe doc check --translations` сверяет число
и типы блоков. Нет страницы на выбранном языке — сайт отдаёт исходный язык
под адресом выбранного как статически материализованный фоллбэк (`<html
lang>` исходного, `rel=canonical` на исходную страницу, `noindex`),
показывает двуязычную плашку «страница пока только на …» один раз за сессию
(`sessionStorage`) и переписывает внутренние ссылки, чтобы навигация
осталась в выбранном языке (приём `lang-fallback.js`). Выбранный язык
запоминается cookie `lang` на 365 дней — тем же именем, что у лендинга,
поэтому корень домена и `/doc/` помнят один выбор.
- **Настройки чтения.** Шестерёнка справа сверху раскрывает панель: тема
(тёмная / светлая / системная), размер шрифта `A−`/`A+` по шагам 80, 90,
100, 110, 120, 135, 150 %, ширина колонки `W−`/`W+` по шагам 740, 900,
1100, 1400 px (только десктоп), якоря вкл/выкл, «Сброс». Значения — в
`localStorage` (в embedded-режиме — у хоста через postMessage). Защита от
FOUC: инлайн-скрипт в `<head>` ставит `data-theme` до загрузки CSS.
- **Режим чтения.** Когда оглавление или первый заголовок ушёл выше 40 %
высоты окна, у шестерёнки появляются быстрые кнопки: оглавление, якоря,
`A−`/`A+`, «вернуться» — без раскрытия панели.
- **Возврат к месту чтения.** Раз в секунду при прокрутке запоминается
ближайший якорь над верхом экрана (`localStorage`, ключ
`reading-pos:<путь>`); при следующем открытии страницы читатель **не**
скроллится сам — появляется кнопка «вернуться к месту», которая исчезает,
как только он сам прокрутил дальше первого заголовка. Кнопка «оглавление»
сохраняет текущее место и включает ту же кнопку возврата; выбор пункта
оглавления сбрасывает её. `history.scrollRestoration = 'manual'`.
- **Оглавление.** На десктопе — липкое слева (190px, подсветка активного
пункта), на узких экранах — сворачиваемый `<details>` над текстом;
вложенность до h3; у страницы с `rule` — блок «правила, на которые ссылается
страница» (адреса `spec://`).
- **Сноски** с обратными ссылками; **таблицы** в прокручиваемом контейнере с
кнопкой «развернуть» в overlay, зебра, первый столбец жирный; **картинки**
— лайтбокс (overlay `position:fixed; inset:0`, без `backdrop-filter`,
кнопка закрытия под контентом — приёмы `lightbox.js`); **код** — кнопка
копирования и подпись языка; `example` показывает ожидаемый вывод под
кодом; `derived` помечен «сгенерировано из …» с адресом источника.
- **Мета-блок** страницы: издатель, версия пакета и признак `latest`, дата
публикации, у перевода — какой пакет он адаптирует, аудитории, время
чтения (200 слов/мин для ru, 250 для en — как у oleg.guru), ссылки `.md`,
`.xml`, «для агента».
- **Кнопка «для агента»** (`.fab`): показывает адрес `spec://…#pNN` текущего
места, ссылки на `.md`, `.xml`, `llms.txt` пакета; копирует одним кликом.
- **Печать**: стиль печати без панелей, с номерами абзацев и адресами
ссылок в сносках.
**Почему.** Слово владельца: ридер oleg.guru «стоит перенести». Нумерация на
сборке, а не на клиенте, — потому что клиентские номера не попадают в
Markdown, XML и llms-корпус, а нам нужно, чтобы человек и агент цитировали
одно место; позиционные номера — не якоря в смысле R-06, а нумерация
текущего текста, поэтому закон неизменяемых якорей на них не распространяется. Зеркало блоков 1:1
— единственный способ сохранить место при смене языка. Отказ от авто-скролла
— из опыта oleg.guru: он ломает deep-links и раздражает.
**Отвергнуто.** Нумерация на клиенте; авто-скролл к сохранённому месту;
cookie для настроек чтения (у нас одна оболочка, `localStorage` достаточно;
cookie только для `lang`, потому что его читает и лендинг); классы Tailwind в
острове; модалка согласия.
**Пересмотреть когда.** Дизайн-ревью A4.14; запрос на аннотации и подсветку
выделений (отложенное).
**Решение.** Сайт — лендинг и документация вместе (D-28) — живёт на том же
сервере и домене, где сегодня лендинг, по существующему runbook «поднять
сайт» из приватного документа инфраструктуры
`C:\Users\olegc\git\infra\main\main.md`. **Содержимое этого документа —
адреса, порты, схема трафика, VPN — в вижен, план и репозиторий не
переносится**; здесь только форма решения.
- **Два контейнера вместо нынешнего одного.** Выдача: контейнер сайта —
стоковый `nginx:alpine` с томом отрендеренного сайта на весь домен: `/`,
`/ru/`, `/doc/…`, корневые машинные файлы. Рендер: `vibevm-site-renderer`
— образ, в котором `vibe` собран из текущего `main` и собрана оболочка; он
наполняет том командой `vibe doc build-site` (уровень 0 и документация из
реестра и хоста, D-07) и статической сборкой Qwik-сайта. В первой волне
рендерер запускается деплой-скриптом по образцу нынешнего скрипта
лендинга (`git pull` чекаута → `docker compose run --rm
vibevm-site-renderer` → `docker compose up -d <сервис выдачи>`); таймер или
вебхук индекса — вторая волна.
- **Переключение.** До готовности нового сайта домен обслуживает нынешний
Astro-лендинг из `vibevm-org`. Переключение — один шаг: контейнер выдачи
нового сайта занимает место контейнера лендинга — тот же compose-сервис и
тот же порт, чтобы хостовый nginx не трогать, — после зелёного теста
паритета лендинга (план, A4.17) и локальной пробы полного стека. Откат —
вернуть прежний сервис. Ни переключение, ни откат не касаются хостового
nginx, портов, сертификатов, compose-блоков соседей и VPN: это правило
самого runbook и граница директивы о VPN.
- **Контейнерный nginx сайта** наследует `vibevm-org/nginx.conf`: `charset
utf-8` с `charset_types` для текстовых типов, `absolute_redirect off;
port_in_redirect off;` (TLS терминируется снаружи), `expires -1` для HTML и
immutable-кэш для `/_assets/` и `/fonts/`, редирект `/en/` → `/` (301),
`X-Content-Type-Options nosniff`, `Referrer-Policy
strict-origin-when-cross-origin`, `X-Frame-Options SAMEORIGIN`, `error_page
404`, `try_files $uri $uri/ $uri/index.html`.
- **Деплой** — модель «git-чекаут на сервере + `docker compose up -d
--build`»: чекаут — репозиторий vibevm (рендереру нужен `vibe` из
исходников, а пакет сайта лежит в его дереве); образ собирается на
сервере, никуда не пушится; запуск — одной командой по SSH с дев-машины
нативным Windows OpenSSH (Git-Bash-овый `ssh` глотает вывод). После
деплоя: `curl -sI https://vibevm.org/` и `/doc/` → `200`, ни одного
`Location: http://` в редиректах, `/llms.txt` с `charset=utf-8`, IndexNow по
изменённым URL.
- **Кто что коммитит.** `Dockerfile` рендерера и `docker/nginx.conf` — в
пакете `org.vibevm.doc/web` (конфигурация сборки, не артефакт — R-10
соблюдён); compose-сервисы, деплой-скрипт, смена чекаута и запись в
`main.md` — на сервере, рукой владельца или под его явным присмотром; в
`vibevm-org` — только финальный коммит снятия с эксплуатации после
переключения (план, A5.8; слово владельца, §10 п. 15).
- DNS, TLS, порты домена уже есть; ничего нового не выпускается; домен не за
Cloudflare.
**Почему.** Хостинг у владельца есть, задокументирован и работает; один сайт
на домене (D-28) означает один контейнер выдачи и никакого прокси между
контейнерами; рендерер отдельным контейнером — потому что `vibe` (Rust) и
Qwik (Node) не должны жить в образе выдачи; занятие места контейнера
лендинга тем же сервисом и портом — единственный способ переключить домен,
не касаясь хостового nginx, от которого зависит VPN.
**Отвергнуто.** Отдельный домен или поддомен (D-06); сторонний статический
хостинг (авторитет домена, готовая инфраструктура); правки хостового nginx;
два сайта на домене с прокси `/doc/` между контейнерами (третья редакция,
снято D-28); сборка образа на дев-машине с пушем в реестр образов; чекаут
`vibevm-org` как источник сайта после переключения.
**Пересмотреть когда.** Переезд на другой хостинг или CDN; второй сервер или
зеркало.
**Решение.** На публичных страницах документации стоит тот же
самохостинговый тег Umami, что и на лендинге — `<script defer src="/u/s.js"
data-website-id="…" data-host-url="https://vibevm.org">` с website-id домена
— тем же, что стоял на Astro-лендинге (значение переносится из
`BaseLayout.astro` в конфигурацию сайта, план A5.1). Пути `/u/s.js` и `/u/e`
обслуживает домен, сайт их не трогает. Ничего сверх: ни GA, ни
Метрики, ни модалки согласия — Umami без cookie и без персональных данных.
Локальный читатель и embedded-режим — без тега (R-09).
**Почему.** Вторая редакция относила аналитику к не-целям; но тег уже стоит
на домене, стоит одну строку, first-party и даёт цифры по чтению документации,
не нарушая закон «никаких внешних ресурсов».
**Отвергнуто.** Собственный инстанс аналитики; GA и Метрика; события чтения
(какие абзацы читают) — отложенное.
**Пересмотреть когда.** Запрос на события (поиск, копирование адреса для
агента).
**Решение.**
- **Исходный язык — английский.** `org.vibevm.core/vibevm-docs` несёт
`lang = "en"`. Все остальные языки, включая русский, — **адаптации**
отдельными пакетами (D-18): зеркало по блокам, свобода по предложениям,
свои шутки, свой глоссарий терминов. Слово «перевод» в этом документе и в
плане читается как «адаптация»; машинный перевод — только черновик.
- **Норма стиля — `STYLE.md`** в этой же папке; при импорте она становится
`AUTHORING.md` пакета `vibevm-docs` и цитируется из PROP-057. Её суть в
четырёх пунктах.
- **Читатель** — умный, занятой, ничего нашего ещё не читал. Страница
обязана работать как единственная, которую он прочтёт (P-15).
- **Где живёт сложность.** Только в контейнерах: `rule`, таблицы,
`derived`, fence, глоссарий. Повествовательные абзацы — коридоры:
термин вводится до употребления (ссылкой на глоссарий или глоссой в
той же фразе), не больше двух терминов на фразу, одна мысль на абзац,
«см. спецификацию» вместо объяснения запрещено — объяснение полно на
странице, спека цитируется как подтверждение. Понятия идут лестницей:
каждая ступень опирается только на нижние.
- **Технические места — по ASD-STE100.** Одно слово — одно значение,
синонимов у технических существительных нет; одна инструкция на фразу,
повелительное наклонение, настоящее время, действительный залог; до 20
слов в процедурной фразе и 25 в описательной, до 6 фраз в абзаце;
предупреждение до шага; последовательности — нумерованными списками.
- **Регистр — эссе, не мануал**, по образцам Money Stuff (механизм
сначала и простыми словами, остроумие через недосказанность), The
Economist (короткие слова, первая фраза несёт суть), Quanta (лестница
понятий, термин после показа вещи), McPhee (структура до первой фразы,
конкретная деталь), Increment и ACM Queue (честность о компромиссах),
Feynman и Bryson (радость от понятого механизма). Юмор редкий, сухой,
информативный, в местах отдыха; не больше одного на страницу; никогда в
процедурах, предупреждениях, справочниках, ошибках, заголовках;
понятный образованному человеку любой страны без IT-фона.
- **Клаудизмы** — слова, обороты и структуры из `STYLE.md` §3 (английские) и
§10 (русские) — удаляются при виде. Механическая часть проверки —
`vibe doc check --style`: запрещённые слова по языку страницы, длины фраз и
абзацев по видам блоков, термин до его введения, плотность терминов,
отсылка вместо объяснения, заголовки Overview/Summary/Conclusion,
восклицания, эмодзи, жирный в прозе, индекс читаемости в отчёт.
Человеческая часть — самоправка автора по `STYLE.md` §2–§8 и чтение
владельцем трёх страниц вслух на гейте фазы 3.
- **Кто пишет.** Прозу — страницы, первые абзацы, `title` и `abstract`,
глоссарий, FAQ, текст скилла, адаптации — пишет сильнейшая модель в
центральной сессии (владелец назвал Fable, Astra, Sol). Воркерам — код,
фикстуры, ожидаемый вывод, зеркала блоков, оболочка, проверки; воркер по
умолчанию — Opus 5 в режиме High (агент `opus5`), а центральная сессия
работает оркестратором и берёт на себя всё умное и творческое: тексты,
адаптации, смысл дизайн-системы, информационную архитектуру, решения.
Черновик прозы от воркера переписывается, не редактируется.
- **Скелет страницы** дополняет D-13: заголовок — существительное для
понятия или повелительное наклонение для задачи; первый абзац — что это и
когда нужно, без единого термина (он же строка страницы в `llms.txt`);
затем пример с ожидаемым выводом; затем механизм лестницей; затем
граничные случаи с `rule`; вопросы, если они есть; никакого заключения.
**Почему.** Слово владельца (§3): тексты моделей страдают клаудизмами, но
главная беда — неверный баланс и точки притяжения сложности: агент пишет
так, будто читатель уже прочёл все спеки. STE даёт проверяемые правила для
технических мест; эссеистический регистр — для остального; деление на
контейнеры и коридоры делает «где сложно» предсказуемым и проверяемым.
Английский источник — так устроен проект (спеки, код, реестр) и так читают
AI-краулеры; адаптация, а не перевод, — потому что шутки и ритм не
переводятся. Проза — самая дорогая и самая заметная часть работы, и именно
на неё стоит тратить сильную модель; код и фикстуры воркер проверит гейтом,
текст гейтом не проверить.
**Отвергнуто.** Русский как исходный язык; дословный перевод; делегирование
прозы дешёвым моделям ради скорости; инфостиль в чистом виде для русского
(слишком сухо — берётся только борьба с канцеляритом); юмор «как у
разработчиков» с внутренними мемами; крайность Thing Explainer (тысяча слов)
— STE применяется к техническим местам, не к эссе; ИИ-переписывание готовых
страниц «для гладкости».
**Пересмотреть когда.** Стиль-ревью владельца на гейте фазы 3 (план,
A3.16) даст замечания; появится человек-редактор; линтер начнёт мешать
чаще, чем помогать (два ложных срабатывания подряд на одном правиле — запись
в BACKLOG).
**Решение.**
- **Журнал с первого дня.** `JOURNAL.md` (в папке вижена; с фазы 1 — в зоне
кампании; после кампании — в пакете документации) — одна таблица, только
дописывается: дата, тип (`успех`, `неудача`, `находка`, `наблюдение`),
стабильный `J-NNN`, что случилось, свидетельство, **→ регламент**. Запись
делается в том же атоме, где случилось событие; поле «→ регламент» не
остаётся пустым дольше месячной петли; правило регламента без ссылки на
запись — гипотеза. Так каждая находка кампании либо меняет процесс, либо
осознанно помечается «наблюдение без действия».
- **Четыре петли обновления** (`MAINTENANCE.md` §2): **коммита** —
изменение продукта, видное пользователю, несёт документацию в том же
коммите или строку долга `docs:` в `BACKLOG.md`; **недельная** — очередь
`vibe doc todo`, до пяти мелких правок, сортировка долга, сигналы недели,
одна страница вслух, запись в журнал; **месячная** — восемь метрик, аудит
корпуса, аналитика, адаптации, дренаж долга, пополнение списков линтера,
«журнал → регламент», три страницы вслух, релиз пакета документации;
**полная сверка** — не на каждый релиз, а по обещанию команды: раз в
квартал и перед крупной вехой. Продукт выходит по десять раз в день, и
дрейф между сверками принят как риск. На сверке дрейф сводится к нулю
против текущего релиза: пины сдвигаются осознанно после чтения диффов,
`derived` перегенерируются, адаптации перечитываются, каждая перечитанная
страница получает дату чтения в `reviews.toml`, пакет документации
релизится.
- **Замков нет.** Ни один технический гейт не связывает релиз продукта с
документацией: `vibe doc todo` печатает пробелы числом; чекбокс
«документация: обновлена / долг записан / не нужна» в шаблоне pull
request'а — привычка; красной остаётся только внутренняя поломка
документации (пример с `expect` как golden-тест, `derived` не собирается,
исчезнувший якорь цитаты). Страница несёт только две даты: когда
отрендерена и когда её в последний раз читали вслух.
- **Смена версии.** Когда владелец осознанно поднимает номер версии
продукта, разработчики документации запускают `vibe doc diff <старая>
<новая>` по снимкам поверхности (D-27): он называет страницы, которые
надо обновить, и почему. Обновляются только они, записывается снимок новой
версии, пакет документации выходит с новым `[[documents]] version`, а
человеческий changelog для читателей пишется по выводу diff. Это
процедура, не технический гейт релиза (`MAINTENANCE.md` §2.5).
- **Инструменты**: `vibe doc todo` (очередь сопровождения по текущему
состоянию продукта и документации: пробелы покрытия, красные примеры,
неразрешимые цитаты, возраст страниц, долг, статистика линтера),
`vibe doc surface` и `vibe doc diff` (псевдоистория версий, D-27),
`reviews.toml` (дата последнего чтения страницы, порядок «страницы
недели»), `CHANGELOG.md` пакета документации из журнала, долг строками
`docs:` в `BACKLOG.md`.
- **Дисциплина мелких правок**: один коммит на правку; якоря и `derived` не
трогаются; термин вводится на месте; **правило пяти правок** — пятая
мелкая правка страницы с последнего чтения ставит её в очередь чтения;
правка, тянущая другие страницы, — не мелкая.
- **Регламент выводится, а не выдумывается**: в фазе 6 журнал
консолидируется, недельная и месячная петли репетируются на свежей
документации, и только потом регламент переписывается в норму: PROP
(следующий свободный после PROP-057), страница для мейнтейнера в пакете,
чеклисты `maintenance/weekly.md`, `monthly.md`, `release.md`. Каждое
правило нормы ссылается на `J-NNN`.
- **Регламент худеет**: раз в квартал правила, ни разу не сработавшие,
помечаются «спящими» и уходят из чеклистов; метрики, которые никто не
смотрит, снимаются.
**Почему.** Слово владельца (§3): написать документацию — полдела; обновлять
её в мелочах и периодически пересматривать целиком — вторая половина, и
находки кампании должны улучшать именно этот процесс. Механика вижена уже
ловит дрейф продукта (пины цитат, `derived`, примеры), но не ловит дрейф
мира и старение текста — их ловят петли и сигналы. Журнал с полем
«→ регламент» — единственный способ, чтобы находки не терялись в чате и не
превращались в правила «по памяти».
**Отвергнуто.** Регламент, написанный до кампании как готовая норма (он
был бы выдуман); «обновляем, когда руки дойдут»; журнал в чате или в
отчётах воркеров; регламент как flow-пакет уже в этой волне (сначала один
проект должен прожить по нему); **технический гейт «продукт не выходит без
документации»** — отвергнут владельцем 2026-09-10: сто pull request'ов и
десять релизов в день, документация неизбежно дрейфует, риск принят
(журнал, J-013: правило родилось без записи-основания и было гипотезой).
**Пересмотреть когда.** Второй проект захочет тот же ритуал для своих
doc-пакетов — тогда регламент становится flow-пакетом
`org.vibevm.world/docs-maintenance`; появится поиск по сайту (новый
сигнал); квартальный пересмотр покажет лишние петли.
**Решение.**
- **Версия — контракт на поведение, а не замороженный набор файлов.**
«Версия 1 делает то, что должна делать версия 1.» Внутри версии продукт
меняется сколько угодно раз — amend, переписанная история, `vibe self
update --force` сто раз в день, — и это невидимо по замыслу: пользователи и
их пайплайны, построенные на воспроизводимости, видят один номер и один
контракт. Документация версии описывает контракт. Какие файлы внутри —
читателю неважно, и документация об этом молчит.
- **Смена номера — осознанное решение владельца.** Не чексуммы, не хэши
файлов, не история: владелец решил, что контракт изменился, и поднял
`1.0.0` до `2.0.0`. Это **единственное событие**, по которому документация
считает «разницу между версиями».
- **Псевдоистория версий — внутренняя кухня разработчиков документации.**
Документация хранит **снимок поверхности** продукта на каждую объявленную
версию — `maintenance/surface/<версия>.json` в пакете документации:
структурное описание, а не хэш: команды и флаги из `--help`, поля
манифеста и lock-файла, схемы, тексты фактов спек с `actionstage="doc"`,
реестр форматов. Снимок записывает `vibe doc surface --record <версия>`
— в момент смены версии и в конце каждой полной сверки. `vibe doc diff
<старая> <новая>` сравнивает два снимка и через граф цитат `rule`,
источники `derived` и карту покрытия выдаёт **список страниц, которые
надо обновить, с причиной у каждой**: «`vibe deploy` получил флаг
`--dry-run` → how-to/deploy, reference/cli». LLM правит перечисленное, а не
штудирует всю документацию.
- **Наружу ничего не выходит.** Сайт и читатель показывают номер версии как
контракт и ничего из кухни: ни «проверено против», ни «устарело с r7», ни
счётчиков дрейфа, ни отпечатков, ни постоянных ссылок по хэшу, ни
уведомлений «доступна новая версия». Единственные даты на странице — когда
она отрендерена и когда её в последний раз читали вслух. Человеческий
changelog между версиями пишется руками по выводу `vibe doc diff`.
- **Внутри версии** машина сравнивает только текущее с текущим: пробелы
покрытия, красные примеры, неразрешимые цитаты (`vibe doc todo`); `rule`
цитирует текущий текст спеки без пинов; устаревшую прозу читает человек на
полной сверке (D-26). Тот же `vibe doc diff <версия> now` можно запустить
внутри версии как подсказку сверке — внутренняя кухня, не факт для
читателя (вопрос владельцу, §10 п. 14).
- **Остаётся удалённым** после седьмой редакции всё, что требовало истории
или показывало кухню читателю: пины ревизий и хэши у цитат, пометки на
страницах, постоянные ссылки `/doc/@<hash>/…`, состояния хоста по хэшу
дерева, отпечатки блоков `#p12-a3f9`, отставание адаптаций по хэшу.
**Почему.** Слово владельца (§3): разницу между версиями смотреть полезно;
опираться — только на номер версии, который меняется осознанно; данные
нужны разработчикам документации, чтобы алгоритмически знать, что обновлять,
а не перечитывать всё; пользователи видят контракт, не файлы. Шестая
редакция путала контракт с замороженным набором файлов и пыталась отличить
неразличимое (J-016); седьмая вычеркнула вместе с этим и полезное; восьмая
возвращает ровно то, что просил владелец, в его формулировке (J-017).
**Отвергнуто.** Чексуммы, хэши дерева и коммитов, отпечатки как
идентичность продукта; снимки поверхности по каждому изменению вместо
объявленных версий; любые метки состояния на страницах для читателя;
постоянные ссылки на прошлые публикации; уведомления «доступна новая
версия».
**Пересмотреть когда.** Владелец захочет машинно публиковать changelog между
версиями для читателей — тогда вывод `vibe doc diff` получит человеческую
проекцию, но по-прежнему только по объявленным версиям.
**Решение.** Лендинг `vibevm.org/` и `/ru/` переезжает с Astro на Qwik **в
ходе этой кампании** и становится маршрутами того же сайта, что и
документация. Один пакет `org.vibevm.doc/web`, одна pnpm-workspace из двух
частей: `design/` — токены, темы, шрифты и компоненты D-21; `site/` —
Qwik-приложение с маршрутами лендинга (`/`, `/ru/`) и документации
(`/doc/…`), статический адаптер для сервера и встраиваемый адаптер для
`vibe`, в который маршруты лендинга не попадают. Шапка, футер, тема,
селектор языка и шрифты — общие компоненты лендинга и документации, без
копирования.
Содержание лендинга переносится **один к одному**: строки `i18n.ts` (en в
корне, ru под `/ru/`), заголовок с акцентным словом, лид с мандатным
описателем, кнопки GitHub и GitVerse, пилюля Early Access и команда
установки, анимированный граф зависимостей с `prefers-reduced-motion`, три
карточки способностей, футер с копирайтом, `404`, редирект `/en/` → `/`.
Машинные файлы корня домена — `robots.txt` (ASCII-only, allow-лист
краулеров), `llms.txt` с абзацем дизамбигуации имени дословно,
`llms-full.txt`, `sitemap.xml`, `feed.xml`, ключ-файл IndexNow, `og.png`,
шрифты по прежним путям — генерирует та же сборка. Адреса, `canonical`,
`hreflang`, JSON-LD (`SoftwareApplication`, `WebSite`) и тег Umami
сохраняются байт в байт там, где это возможно, и проверяются **тестом
паритета лендинга** (план, A4.17) до переключения домена. Переключение —
один шаг деплоя (D-23); после него репозиторий `vibevm-org` снимается с
эксплуатации (§10 п. 15). Контракт трёх строк и прокси `/doc/` третьей
редакции больше не нужны.
**Почему.** Слово владельца: однообразно и хорошо композируется. Два стека на
одном домене — это две системы компонентов, два шрифтовых конвейера, два
генератора корневых файлов и прокси между контейнерами; один Qwik-сайт на
общей дизайн-системе убирает всё это. Лендинг мал — одна страница на двух
языках, — и цена переноса измеряется днями.
**Отвергнуто.** Два Qwik-приложения с общим npm-пакетом дизайн-системы
(композиция через публикацию пакета — лишний шов для сайта из одной страницы
и документации; вернуться к этому, если лендинг разрастётся); оставить
Astro-лендинг и связать через прокси (третья редакция); редизайн содержания
лендинга по ходу переноса — перенос один к одному, правки содержания
отдельным решением после дизайн-ревью.
**Пересмотреть когда.** Лендинг разрастётся в маркетинговый сайт с
собственным ритмом релизов — тогда его можно выделить во второе приложение
на той же дизайн-системе.
**Решение.** Кампания идёт тремя волнами с разной центральной сессией:
- **Волна A — тексты.** Fable: находки фазы 0 (механика — дешёвыми
моделями), контракт фазы 1 (PROP-057 и поправки пишет Fable), и **вся
проза документации ядра на английском** — до механики, в каркасе пакета,
с реально снятыми `expect`, с проверкой цитат и стиля скриптами вместо
ещё не написанных инструментов, с приёмкой владельцем (три страницы
вслух). Заканчивается пакетом передачи.
- **Волна B — разработка.** Opus 5 в режиме High как центральная сессия:
механика, подключение написанной прозы, сайт, лендинг на Qwik, деплой,
репетиции сопровождения. Прозу Opus не переписывает; замечания линтера и
раннера, которые не чинятся одной-двумя строками, копятся в очередь
«нужен автор». Fable возвращается в четырёх названных точках: после
первого прогона линтера и раннера по прозе, на дизайн-ревью, на
стиль-ревью после механики, и в фазе 6 — регламент сопровождения из
журнала и changelog.
- **Волна C — адаптация.** Fable: русская адаптация документации ядра,
когда всё остальное проверено и работает; плюс всё, что волна B положила
в отложенное для автора.
Английский — единственный язык волн A и B; механика адаптаций в волне B
проверяется на фикстуре из двух страниц, не на боевом пакете.
**Почему.** Слово владельца (§3): сначала все красивые тексты на
английском, потом полностью переключиться на Opus для разработки; русский —
следующей волной после проверки. Это и экономия: Fable тратится на то, что
умеет только она, одним непрерывным куском, а не размазанными по месяцам
правками; Opus получает замороженный контракт и принятую прозу и работает
без оглядки. Русская адаптация после проверки — потому что адаптировать
стоит только то, что уже читается и работает.
**Отвергнуто.** Писать прозу после механики (она ждала бы инструментов,
которые ей не нужны для написания); чередовать Fable и Opus поатомно (дорого
и рвёт контекст обеим); адаптировать параллельно с источником (двойная
правка каждого абзаца).
**Пересмотреть когда.** Волна B покажет, что проза массово требует
переписывания под инструменты — тогда точка возврата F1 становится
полноценной под-волной.
**Решение.** Любое действие в VibeVM делается двумя способами — руками и
агентом, — и второй теперь основной. Страница сценария («как сделать»)
строится в таком порядке:
- **Что это и когда нужно** — первый абзац без терминов, как везде.
- **Промпт** — блок `prompt`: простое задание агенту в голосе пользователя;
самодостаточное (координаты, пути, реестр названы, а не подразумеваются);
одно на результат; без секретов; нейтральное к агенту — работает у
любого агента с установленным скиллом `vibevm`. Рядом `needs` — что
агенту нужно (скилл, MCP, сеть или её отсутствие) — и `outcome` — что
увидит человек, когда получилось.
- **Что произойдёт** — три–шесть фраз механизма: какие команды агент
выполнит, какие файлы появятся или изменятся, чем проверить результат.
Это и есть ответ «как это работает» для тех, кто дальше не пойдёт;
пишется как коридор, не как контейнер.
- **Руками** — нумерованные шаги по STE, только если ручной путь имеет
смысл. Иногда его нет, и раздел отсутствует, а не заполняется для
порядка.
- Граничные случаи с `rule`, вопросы — как везде.
Страницы-объяснения не меняются. Карточка сценария в каталоге и на уровне 0
показывает первую строку промпта.
Механика:
- **Элемент словаря `prompt`** — седьмой, по слову владельца (D-10
пересмотрено): тело — текст задания; дети `needs`, `outcome` и `assert*` —
ноль и больше шелл-команд, обязанных завершиться нулём после работы агента
(`vibe check`, `test -f vibe.toml`, `vibe explain "spec://…"`). В Markdown
— fence `prompt`, список «нужно», абзац «результат», список ассертов; в
`llms*.txt` — тот же fence, чтобы агент-читатель мог взять задание как
есть; в ридере — блок с кнопкой «скопировать», в embedded-режиме — «передать
агенту» (§7.5).
- **Проверка `vibe doc check --prompts`**: каждый промпт прогоняется
настроенным агентом-исполнителем (`[doc.prompts] runner`) в чистом
временном каталоге с фикстурой, затем выполняются ассерты. Текст ответа
агента недетерминирован, ассерты — детерминированы. **В панель не
входит**: дорого и небыстро. Гоняется в фазе P до приёмки прозы, в
месячной петле выборкой, на полной сверке целиком (`MAINTENANCE.md`).
- На странице сценария промпт без ассерта — ошибка линтера стиля (R-30);
промпт-иллюстрация на странице-объяснении помечается `assert="none"`.
- Скилл `vibevm-docs` берёт блок `prompt` как задание, когда пользователь
просит сделать то, что описано страницей (§7.4).
**Почему.** Слово владельца (§3): теперь любое действие делается не только
руками, но и агентом; люди приходят узнать «как это работает» и «какой
промпт запустить»; это отличие от документации прошлого, где всё делалось
руками. Для VibeVM это ещё и предмет: продукт устанавливает контекст агентам,
и документировать его через агента — значит показывать продукт в его среде.
Ассерты — потому что промпт, в отличие от команды, нельзя проверить
golden-выводом, а непроверяемый промпт устаревает молча.
**Отвергнуто.** Промпт как обычный `fence` без проверки; привязка промптов
к одному агенту; ручной путь на каждой странице «для полноты»; прогон
промптов в панели на каждый коммит.
**Пересмотреть когда.** Появится второй способ поручать задачи изнутри
продукта — тогда блок `prompt` получит ещё одну проекцию.