# Документация VibeVM — вижен {#root} @status:spec/done [p01] @fact:companion-line **Explains:** [PROP-057](../common/PROP-057-documentation-packages-and-site.xml) — the documentation packages and site contract; the thirty decision records D-01…D-30 below are its rationale, and PROP-057 wins where they disagree (the spec-genres precedence law). Written in Russian for the owner; the norm it explains is English. @status:spec/done ## 0. Как читать {#how-to-read} - [p02] @fact:how-to-read-1 **Жанр.** Это design-документ: «почему и как мы решили». Он не связывает никого сам по себе. Связывают PROP-документы после переноса нормы (§5.17), а до переноса — решения владельца в §3. При конфликте этого текста с PROP побеждает PROP, и этот текст правится. @status:spec/done - @fact:how-to-read-2 **Решения пронумерованы `D-NN`** и стоят под якорями `#d-NN`. План исполнения (`AGENT-PLAN.md`) ссылается на них по якорю и не пересуждает их. @status:spec/done - @fact:how-to-read-3 **Каждое решение записано четырьмя полями** по закону decision-records проекта: Решение · Почему · Отвергнуто · Пересмотреть когда. @status:spec/done - @fact:how-to-read-4 **Термины** собраны в §9. Идентификаторы проекта (имена файлов, команд, элементов) остаются в оригинале. @status:spec/done - @fact:how-to-read-5 **Журнал редакций** — §11: что изменилось между редакциями и почему. @status:spec/done ## 1. Что строим, в одном экране {#summary} 1. [p03] @fact:summary-1 **Документация — это пакеты.** Вводится kind `doc`. У любого пакета есть бесплатный базовый уровень документации, выводимый из его собственного содержимого. Расширенная документация едет отдельным пакетом-спутником `<группа>/<имя>-docs`, а документация самого инструмента — пакетом `org.vibevm.core/vibevm-docs`. Каждая документация несёт человекочитаемый заголовок, аннотацию и, по желанию, картинки. @status:spec/done 2. @fact:summary-2 **Переводы — тоже пакеты.** Один пакет на язык, зеркалящий дерево источника. Сайт показывает селектор языка и никогда не отвечает 404 на отсутствующую страницу — подставляет исходный язык с пометкой. Первая адаптация, русская, — третья волна: после того как всё остальное проверено и работает (D-29). @status:spec/done 3. @fact:summary-3 **Сайт `vibevm.org/doc` — «docs.rs для реестра vibespecs».** Он рендерит каждую опубликованную версию каждого пакета из её байтов, подписан на индекс реестра как на ленту изменений и пересобирает только то, у чего изменился content hash. Сам vibevm рендерится из своего репозитория исходников. Пакет сайта — `org.vibevm.doc/web`, kind `app`. @status:spec/done 4. @fact:summary-4 **Официальное и сообщество — обе полки видимы.** Официальность на каждом уровне назначается «сверху»: документацию называет предмет, перевод — исходная документация. Всё остальное сайт тоже находит по рёбрам и показывает как community, со звёздочками только у официальных элементов. @status:spec/done 5. @fact:summary-5 **Локальный читатель.** Та же программа запускается на машине пользователя как `vibe doc serve`, читает машинный store, lock-файл проекта и приватные реестры, работает офлайн и встраивается в приложения и плагины через webview. Так читается документация проприетарных пакетов, которых в публичном реестре нет. @status:spec/done 6. @fact:summary-6 **Инфраструктура для агентов.** Стабильные якоря, адрес `spec://` на каждое правило, `llms.txt` и `llms-full.txt` на каждый язык, каждая страница в виде Markdown и XML по стабильному URL, каталог документаций с аннотациями в стиле arXiv, JSON-манифест страниц, резолвер адресов, точечные запросы через CLI и MCP, и скилл, который ведёт агента по петле «ошибка → якорь → правило → объяснение → пример». @status:spec/done 7. @fact:summary-7 **Механика без дрейфа.** Документация цитирует спеки и никогда не пересказывает нормативные значения; примеры исполняются на каждой сборке; справочники выводятся из кода и схем; `rule` цитирует текущий текст спеки, а роняет сборку только исчезнувший якорь; покрытие обязательств измеряется гейтом, а не ощущается. Ничто в документации не требует истории, которую нельзя переписать (D-27). @status:spec/done 8. @fact:summary-8 **Визуальный язык и ридер.** Сайт наследует тёплую дизайн-систему, выработанную по старым страницам Anthropic, в двух темах: светлая — её собственные токены, тёмная — токены лендинга `vibevm.org`; одна терракота на обе. Страница документации — ридер по образцу oleg.guru: нумерованные абзацы со ссылкой на каждый, переключение перевода с сохранением места, настройки чтения, возврат к месту, где остановился, липкое оглавление, сноски, лайтбокс. Раздел о дизайне — заведомо предварительный и пересматривается после первого живого рендера (D-21). @status:spec/done 9. @fact:summary-9 **Один сайт на домене, один хостинг.** Лендинг переезжает с Astro на Qwik в ходе кампании и становится маршрутами `/` и `/ru/` того же сайта, что и документация, на одной дизайн-системе (D-28). Сайт живёт на том же сервере, где сегодня лендинг, по существующему runbook инфраструктуры: один контейнер выдачи на весь домен и контейнер-рендерер; переключение занимает место нынешнего контейнера лендинга, хостовый nginx не трогается. Детали сервера — в приватном документе инфраструктуры и сюда не переносятся (D-23). @status:spec/done 10. @fact:summary-10 **Текст.** Английский — исходный язык документации, все остальные языки, включая русский, — адаптации. Пишем для умного читателя, который ещё ничего нашего не читал: сложность живёт в контейнерах (`rule`, таблицы, `derived`, fence, глоссарий), повествовательные абзацы остаются простыми; технические места — по Simplified Technical English; регистр — эссе для образованного читателя, юмор редок и точен; клаудизмы вырезаются линтером и рукой; прозу пишет сильнейшая модель в центральной сессии, воркеры — код и фикстуры (D-25, `STYLE.md`). @status:spec/done 11. @fact:summary-11 **Сопровождение спроектировано до написания.** Четыре петли обновления: коммита (продукт несёт документацию в том же коммите или строку долга), недельная (очередь `vibe doc todo`, до пяти мелких правок, страница недели вслух), месячная (метрики, аудит корпуса, переписывание, изменения регламента, релиз пакета документации), полная сверка по обещанию команды (раз в квартал и перед вехой, не на каждый релиз: продукт выходит по десять раз в день, дрейф между сверками принят как риск); смена номера версии — осознанное решение владельца, и в этот момент `vibe doc diff` по снимкам поверхности называет страницы, которые надо обновить, — внутренняя кухня разработчиков документации, невидимая читателю (D-27). Кампания ведёт журнал успехов, неудач и находок с полем «→ регламент»; регламент пишется из журнала в фазе 6 после двух репетиций (D-26, `MAINTENANCE.md`, `JOURNAL.md`). @status:spec/done ## 2. Откуда стартуем {#context} ### 2.1 Механика, которая уже есть {#context-mechanics} [p04] @fact:context-mechanics-1 Ничего из перечисленного строить не нужно — на это опирается всё остальное. @status:spec/done - [p05] @fact:context-mechanics-2 **Адресуемость.** Каждый факт в спеке — именованный XML-элемент с идентификатором; адрес `spec://<группа>/<имя>[@версия]/<документ>#<якорь>` резолвится без индекса, один к одному в путь файла. Якоря неизменяемы, снятие — только tombstone. @status:spec/done - @fact:context-mechanics-3 **Карта трассируемости (specmap).** Глаголы рёбер `implements`, `verifies`, `documents`, `deviates`, `informs`; ревизии юнитов с асимметричной инвалидацией; команды `vibe explain`, `vibe query`, `vibe select` и те же инструменты по MCP. Глагол `documents` уже существует в движке (`crates/vibe-trace/src/select/parse.rs`). **Движок specmap вендорится:** его авторская копия живёт в пакете дисциплины, хостовая копия синхронизируется через `cargo xtask sync-engines` и не правится напрямую. @status:spec/done - @fact:context-mechanics-4 **Пивот документов (`vibe-specdoc`).** Один IR, фронтенды Markdown и XML, бэкенды Markdown и XML; преобразование только через IR; диалект закрыт: чужой элемент — громкая ошибка. Зарезервированный словарь блоков: `p`, `list`, `facts`, `table`, `fence`, `quote`. @status:spec/done - @fact:context-mechanics-5 **Интернационализация (PROP-003 §2.7, `crates/vibe-core/src/manifest/i18n.rs`).** Теги BCP-47, блок `[i18n]` с каноническим языком, списком доступных и предпочтением проекта, цепочка отката «точный тег → тег без региона → канонический», sidecar-файлы `README.ru.md` внутри пакета, проверка покрытия в `vibe check`, запись выбранного языка в lock-файл. Грамматика и цепочка отката переиспользуются (§5.18); sidecar-раскладка для документации не используется. @status:spec/done - @fact:context-mechanics-6 **Пакеты и реестр.** Идентичность `(group, name, version, content_hash)`; реестр — репозитории `github.com/vibespecs/<группа>.<имя>`; индекс `vibe-index` — git-репозиторий на организацию с `repomd.json` и JSONL-первичкой, плюс HTTP-сервер на axum с маршрутами `/v1/index/*` и `/v1/packages/*`; машинный store `~/.vibe/cache/` с прогревом `vibe cache add`, который не трогает проект; git-источники пакетов по тегу, ветке или ревизии (PROP-002). @status:spec/done - @fact:context-mechanics-7 **Семейства пакетов (PROP-028).** Стем плюс роли `-lang` и `-mcp` в одной группе; агрегатор без содержимого; члены семейства версионируются в унисон. @status:spec/done - @fact:context-mechanics-8 **Скиллы и MCP.** `[[skill]]` в манифесте, `vibe skill install` проецирует скиллы в Claude Code, OpenCode и Codex; `vibe mcp serve` отдаёт lock-файл, сабскиллы и карту. @status:spec/done - @fact:context-mechanics-9 **Разметка фактов (PROP-043).** Атрибуты `audience` (`user`, `author`, `dev`) и `actionstage`; вид `vibe progress report --view doc --audience …` перечисляет факты спек, помеченные как «должны быть рассказаны этой аудитории». Это перечень обязательств, а не навигация. @status:spec/done - @fact:context-mechanics-10 **Токеномика (PROP-048).** Закон слоёв: редко меняющееся читается первым; STATIC — кэш-стабильный префикс; изменяемое знание — точечный запрос, а не часть префикса. @status:spec/done - @fact:context-mechanics-11 **Условия загрузки.** Предикаты `when="os:…"` и `when="installed:…"` в boot-лейне. @status:spec/done - @fact:context-mechanics-12 **Дисциплина TypeScript** (`typescript-ai-native`) установлена и обязательна для любого TS-кода в проекте; планка качества владельца: production-grade, без «MVP». Есть `cargo xtask add-cell` для заведения новой ячейки по дисциплине. @status:spec/done ### 2.2 Документация сегодня {#context-docs} [p06] | Что | Состояние на 2026-09-09 | | --- | --- | | @fact:context-docs-1 `docs/` @status:spec/done | @fact:context-docs-2 48 Markdown-файлов, 316 КБ; альфа-слой «вариант А» от 2026-08-20, сверен с `--help` бинарника 1.0.0 @status:spec/done | | @fact:context-docs-3 Страниц с устаревшими путями и именами @status:spec/done | @fact:context-docs-4 37 из 51 проверенных: старая раскладка `spec/`, `STATIC.md`, `INLINE.md`, `WAL.md`, ссылки на `.md`-спеки @status:spec/done | | @fact:context-docs-5 Наблюдаемость @status:spec/done | @fact:context-docs-6 `docs/` не входит ни в один include-glob `facts.toml`: не размечена, не судилась, не проверяется @status:spec/done | | @fact:context-docs-7 `CHANGELOG.md` @status:spec/done | @fact:context-docs-8 раздел Unreleased пуст при 839 коммитах после релиза 1.0.0 @status:spec/done | | @fact:context-docs-9 Установленный `vibe 1.0.0` @status:spec/done | @fact:context-docs-10 не знает команд `lifecycle`, `build`, `package`, `deploy`, `scrape`, `extensions`; отладочная сборка из исходников их показывает @status:spec/done | | @fact:context-docs-11 Корневые гайды @status:spec/done | @fact:context-docs-12 `README.md`, `DEV-GUIDE.md`, `RUNTIME-GUIDE.md` — load-bearing, живут по закону same-commit @status:spec/done | | @fact:context-docs-13 Инвентарь для сайта @status:spec/done | @fact:context-docs-14 `docs/SITE-MANIFEST.toml` — ручной, курируемый список страниц @status:spec/done | | @fact:context-docs-15 Язык @status:spec/done | @fact:context-docs-16 существующая документация и спеки — английский; книга redbook — русский @status:spec/done | ### 2.3 Два предыдущих проекта документации {#context-prior} - [p07] @fact:context-prior-1 **`campaigns/packages-2026-09/PHASE-G-SPEC.md` (2026-07-26, не ратифицирован).** Предложил перенос `docs/` в `docs-legacy/`, пакет `org.vibevm.doc/doc`, закон односторонней цитаты, ребро `documents`, оглавления из разметки `audience`, зарезервированный пакет сайта `org.vibevm.doc/web` и строку «документация» в карте жанров. **Что остаётся:** односторонняя цитата, ребро `documents`, `docs-legacy/`, жанровая строка, пакет `web`. **Что меняется:** имя `org.vibevm.doc/doc` уходит — документация ядра становится спутником координаты хоста `org.vibevm.core/vibevm-docs` (§5.3); вводится kind `doc`; разметка `audience` даёт не оглавление, а гейт покрытия (§5.14). @status:spec/done - @fact:context-prior-2 **Маршрут `DOCS` в плане стюарда (r145, 2026-09-09).** Восемь узлов от инвентаризации и заморозки информационной архитектуры до гейта приёмки, с четырьмя аудиториями. **Что остаётся:** все узлы и их критерии приёмки; они отображаются на фазы плана. **Что добавляется:** kind `doc` и `app`, пакеты-спутники, переводы, сайт, локальный читатель, SEO-контракт. @status:spec/done ### 2.5 Пять внешних источников третьей редакции {#context-external} [p08] @fact:context-external-1 Проанализированы 2026-09-10 в режиме только для чтения; ни один не изменялся. Пути — на машине владельца. @status:spec/done [p09] | Источник | Где | Что берём | Что не берём | | --- | --- | --- | --- | | @fact:context-external-2 Скриншоты старого сайта Anthropic @status:spec/done | @fact:context-external-3 `C:\Users\olegc\git\talks\2026.08.08-agents-talk\screenshots\` (1–13; 13 — страница `/docs`) @status:spec/done | @fact:context-external-4 образ страницы документации: шапка с поиском `Ctrl K`, вкладки разделов, серифный hero, карточки-входы, плавающая кнопка «спросить»; статья с центрированной шапкой, тегами, датой; липкое оглавление слева с подсветкой; тёмный футер-каталог @status:spec/done | @fact:context-external-5 тексты, логотипы, продуктовую структуру @status:spec/done | | @fact:context-external-6 Тёплая дизайн-система @status:spec/done | @fact:context-external-7 `C:\Users\olegc\git\talks\2026.08.08-agents-talk\design-system\` (`public/assets/css/anthropic.css` — 19 секций, токены в `:root`; `ui.js`; `docs.html`, `research-paper.html`, `gallery.html` — витрина компонентов) @status:spec/done | @fact:context-external-8 токены светлой темы (палитра слоновой кости, тан, чернила, терракота, цвета графиков, радиусы, тени), компоненты: `.docs-header`, `.docs-nav`, `.doc-card`, `.search-box`, `.toc` (sticky + IntersectionObserver), `.prose`, `.footnotes`, `.tag`, `.badge`, `.accordion`, `.tab-pills`, `.data-table`, `.table-scroll`, `.breakout`, `.fab`, `.share-row`, `.photo-ph` (тёплый градиентный плейсхолдер) @status:spec/done | @fact:context-external-9 шрифты Manrope и Source Serif 4 как обязательные (см. D-21: резерв), мега-меню, карусель цитат, промо-панели @status:spec/done | | @fact:context-external-10 Центральный лендинг @status:spec/done | @fact:context-external-11 `C:\Users\olegc\git\v\vibevm-org\` (Astro 5, Tailwind 3.4, `src/styles/global.css`, `BaseLayout.astro`, `i18n.ts`; развёрнут на `vibevm.org`, remote `github.com/vibevm/vibevm-org-web`) @status:spec/done | @fact:context-external-12 токены тёмной темы (`--ink`, `--ink-raise`, `--cream`, `--dim`, `--faint`, `--accent #D97757`, `--line`), шрифты Spectral + Inter + JetBrains Mono, самохостинг с кириллическими подсетами, i18n `en` в корне и `ru` под `/ru/`, `hreflang`, JSON-LD, `llms.txt` с дизамбигуацией имени, `robots.txt` с явным allow AI-краулеров (ASCII-only), `build-llms-full.mjs` из `dist/`, IndexNow, Dockerfile «node:22-alpine → nginx:alpine», контейнерный `nginx.conf` (charset для текстовых типов, immutable-кэш ассетов, заголовки безопасности), тег Umami @status:spec/done | @fact:context-external-13 сам Astro и Tailwind: лендинг переезжает на Qwik и токены (D-28); содержание и адреса переносятся один к одному @status:spec/done | | @fact:context-external-14 Инфраструктура хостинга @status:spec/done | @fact:context-external-15 `C:\Users\olegc\git\infra\main\main.md` (**приватный**, единый источник правды по серверу) @status:spec/done | @fact:context-external-16 модель деплоя B «git-чекаут на сервере + `docker compose up -d --build`», TLS снаружи контейнера, контейнер слушает `:80`, `absolute_redirect off` обязателен, runbook «поднять сайт», протокол удаления, Umami для новых сайтов, правило «маршрутизацию нового сервиса на существующем домене делать в контейнерном nginx, не в хостовом» @status:spec/done | @fact:context-external-17 **ничего из содержимого не переносится**: адреса, порты, схема трафика, VPN — только ссылка на файл; директива о VPN становится стоп-правилом плана @status:spec/done | | @fact:context-external-18 Ридер статей oleg.guru @status:spec/done | @fact:context-external-19 `C:\Users\olegc\git\oleg-guru\` (`scripts/templates/article.html.tpl`, `podcast-episode.html.tpl`, `build-articles.mjs`, `public/js/{theme,lang-fallback,lightbox}.js`, `CLAUDE.md`) @status:spec/done | @fact:context-external-20 весь набор фич ридера, разобранный в D-22 @status:spec/done | @fact:context-external-21 палитру (холодная тёмная с бирюзой и розовым — не наш язык), Roboto Flex, модалку гражданства, GA/Метрику, нумерацию якорей на клиенте (у нас — на сборке) @status:spec/done | ### 2.4 Аудитории {#context-audiences} [p10] | Аудитория | Кто это | Значение `audience` | | --- | --- | --- | | @fact:context-audiences-1 Новичок @status:spec/done | @fact:context-audiences-2 человек, впервые открывший VibeVM @status:spec/done | @fact:context-audiences-3 маршрут внутри `user`, не отдельное значение @status:spec/done | | @fact:context-audiences-4 Пользователь и оператор @status:spec/done | @fact:context-audiences-5 ставит vibe, ведёт проект, устанавливает пакеты, деплоит @status:spec/done | @fact:context-audiences-6 `user` @status:spec/done | | @fact:context-audiences-7 Автор пакетов и расширений @status:spec/done | @fact:context-audiences-8 пишет flow/feat/stack/tool/mcp/lang/doc/app, провайдеры и расширения, переводы @status:spec/done | @fact:context-audiences-9 `author` @status:spec/done | | @fact:context-audiences-10 Мейнтейнер @status:spec/done | @fact:context-audiences-11 правит код и спеки самого vibevm @status:spec/done | @fact:context-audiences-12 `dev` @status:spec/done | | @fact:context-audiences-13 Сессия агента @status:spec/done | @fact:context-audiences-14 AI-сессия проекта-потребителя, читающая при загрузке или по запросу @status:spec/done | @fact:context-audiences-15 `agent` (новое, §5.11) @status:spec/done | ## 3. Мандат владельца, дословно {#mandate} [p11] @fact:mandate-1 Цитаты — чат 2026-09-09 и 2026-09-10. @status:spec/done > [p12] @fact:mandate-2 «я хочу следующим этапом начать писать документацию. И я хочу понять, как > правильно ее писать, чтобы она а) хорошо анализировалась ИИ агентами > б) идеально читалась людьми.» @status:spec/done > [p13] @fact:mandate-3 «Мы сможем сделать так, чтобы в нем можно было перейти от документов к > спецификациям и прочитать подробные правила? (как часть делают в книгах по > C++, где упрощенное описание в учебной книге ссылается на точные строки > стандарта C++). Еще, мы можем сделать какие-то примеры, чтобы пользователи > могли быстро понять как пользоваться фичей и им не приходилось долго и > сложно думать? Дальше, можем ли мы сделать какую-то специальную > инфраструктуру для агентов, чтобы им было проще исследовать эту документацию > и через веб, и через локальный доступ (если сделать возможность скачать > документацию и читать ее локально - тогда в будущем мы можем сделать "скилл > по использованию vibevm" который будет в случае проблем отсылать не только к > спекам, но и к документации).» @status:spec/done > [p14] @fact:mandate-4 «Я бы сделал основную механику vibevm всегда доступной в виде пакета. При > переходе проекта в продакшен все пакеты из packages будут опубликованы наружу > и лягут в репозиторий, поэтому они в этот пакет не войдут. Но сделать аналог > docs.rs который генерирует документацию для ВСЕГО что лежит в репозитории - > это очень круто и очень хотелось бы сделать так. Но важно, что пакеты в > центральном репозитории vibespecs меняются и технически сайт должен уметь это > всё обновлять у себя. Возможно, опциональная документация должна идти > сопроводительным пакетом типа org.vibevm.world.docs/multi-user-planning (или > выработать еще какую-то конвенцию более правильную, если эта не подходит)» @status:spec/done > [p15] @fact:mandate-5 «1) вводим kind doc 2) пакет org.vibevm.doc/web, сайт vibevm.org/doc 3) было > бы неплохо в будущем сделать этот сайт запускаемым и локально, чтобы потом > сделать приложение для чтения документации (например, плагин для vscode как > встроенный iframe на это локальное приложение) - это нужно для чтения > документации закрытых проприетарных пакетов. которых нет в репозитории 4) всё > должно быть сделано для максимального SEO, включая LLM SEO для того чтобы > краулеры Anthropic и OpenAI находили быстрее: llms.txt, llms-full.txt для > базового корпуса документации, и другие приёмы 5) технически стек для веба - > https://qwik.dev, а точнее - его свежая версия 2.0: https://next.qwik.dev/ > (да, она в бете, это нормально)» @status:spec/done > [p16] @fact:mandate-6 «канал хоста - пока что только тот репозиторий который мы указали в > настройках при запуске/генерации (по умолчанию - гитхаб), зеркала и прочее - > когда-нибудь в будущем» @status:spec/done > [p17] @fact:mandate-7 «я боюсь что если ребро документации будет исходить из самого пакета, то три > разных человека законтрибьютят три разных пакета документации, и непонятно > будет - какой "официальный" пакет показывать на нашем сайте. Может быть, > ребро должно исходить и из самого документируемого пакета тоже? То есть, > пакет указывает свою "официальную" документацию (и там может быть одна штука > выбрана как "основная" документация, и сколько угодно как дополнительные > "официальные"). Но при этом остается возможность самим пакетам с > документацией сделать обратное ребро тоже - и тогда на сайте мы сможем > сделать раздел с "неофициальной" документацией (community docs).» @status:spec/done > [p18] @fact:mandate-8 «2) вариант Б, а приложения и VSCode-плагины будут вставлять в себя этот > интерфейс через webview 3) сразу A, и спланировать самые частые вещи > 5) вариант А, добавить agent 6) Б для локального читателя, А для сборки > публичного сайта на сервере, где Node есть. Но прежде чем подтвержу, скажи > как именно ты собрался встраивать оболочку vibe» @status:spec/done > [p19] @fact:mandate-9 «ты помнишь что бывают локализации? скорей всего, нужно каждую из > локализаций иметь отдельным пакетом, а сайту показывать селектор локализации. > А в пакете иметь официальную ссылку на каждый из пакетов для разных языков.» @status:spec/done > [p20] @fact:mandate-10 «только не забудь, что неофициальные переводы тоже должны искаться сайтом > (просто отображаться как переводы сообщества, а не официальные). Эта > иерархия официальной и неофициальной документации, их официальных и > неофициальных переводов должна как-то понятно и наглядно отражаться в > интерфейсе (например, звездочки на "официальных" элементах)» @status:spec/done > [p21] @fact:mandate-11 «можно сделать, чтобы документация могла иметь собственные названия. > Например, сам автор пакета пишет для нее официальный мануал, а потом > сообщество пишет три неофициальных гайда с новыми названиями. […] Имеется > в виду человекочитаемое имя, таким как оно будет выглядеть в интерфейсе > сайта» @status:spec/done > [p22] @fact:mandate-12 «обычно для библиотеки документации лучше иметь человекочитаемое название и > человекочитаемый абстракт - так же как это делают поисковики по arxiv.org, > например» @status:spec/done > [p23] @fact:mandate-13 «еще я бы советовал сразу добавить возможность сделать большую квадратную > иконку (как аватар в твиттере) или большой горизонтальный баннер (как баннер > профиля в твиттере 1500x500). […] Обе картинки опциональны. В случае если > нет картинки, на аватаре отображается плейсхолдер (например, книга), а > вместо баннера отображается тоже какой-то плейсхолдер в виде красивого > градиента или абстрактного узора» @status:spec/done > [p24] @fact:mandate-14 «картинки для опенграфа я бы сделал отдельной опцией. То есть баннер - это > нечто длинное и узкое что отображается сверху страницы документации в > каталоге, и оно по пропорциям плохо похоже на og:image которую ждут как > "превью веб-страницы"» @status:spec/done [p25] @fact:mandate-15 Что в этом мандате **ещё не подтверждено** владельцем: механизм встраивания оболочки в `vibe` (§5.12 помечено «предложено») и набор ссылок хоста, которые рендерит сайт: только теги релизов или ещё `main` (§5.16). Всё остальное — принятые решения. @status:spec/done > [p26] @fact:mandate-16 «Мы когда-то вырабатывали дизайн-систему. В качестве вдохновения мы брали > старые версии сайта Антропика […]. И даже выработали конкретную дизайн > систему в виде CSS и примерного портала […]. Еще мы сделали центральный > лендинг […] и выложили его на хостинг […]. Кроме того, на моем личном сайте > […] есть просто офигенный интерфейс просмотра статей, который стоит > перенести и на наш сайт тоже. Документы по ссылкам, которые я дал, менять не > нужно. Нужно их аккуратно проанализировать (в том числе подробно понять фичи > ридера статей на oleg.guru типа нумерованых абзацев, переключения между > переводами, свойствами чтения, возвращения к закладке, и так далее) и внести > в наше ТЗ и вижен. Секция визуального языка и дизайн-системы, возможно, > требует дополнительного доисследования и улучшения уже после того, как мы > поймем что у нас получается.» @status:spec/done > [p27] @fact:mandate-17 «Скоро мы будем писать доки, и поэтому важное про стиль. Claude известна > написанием доков с огромной кучей "клаудизмов". Но клаудизмы - полбеды. > Одна из важнейших проблем - неправильный баланс и точки притяжения > сложности. Мы пишем документацию для умных, технологически продвинутых > людей, многие из которых - senior developers или имеют академический > бэкграунд в ИИ. И часто даже они не понимают, что написала Claude. Потому > что агенты Claude обычно пишут исходя из неверного предположения, что > человек вначале прочитал всю документацию и все спеки, и вот теперь агент > может написать сложные информационно плотные абзацы, сплошь состоящие из > терминов спецификации. Как правило это неправда, особенно для > документации. Поэтому технические места лучше описывать словами: > ASD-STE100 Simplified Technical English (STE), открыто и просто говорить > как делаются те или иные вещи (без "посмотрите в спецификацию, прочитайте > все и сами поймете). Но это не отменяет того, что нас читают умные, > образованные люди, и поэтому писать для них нужно как в лучших > научно-популярных журналах - ярко, броско и с юмором, типичным для > образованных людей (не обязательно в сфере IT). Важно, что юмор - это вещь > очень редкая и должна быть применена точно и к месту, ровно как и другие > резкие стилистические приемы. […] Важно: исходный текст английский, все > остальные языки (включая русский!) это адаптации английского. Красивые > тексты пишешь ты сама (Fable, Astra, Sol), маленьких агентов можно > использовать для технических задач типа программирования (все наши > веб-интерфейсы и так далее)» @status:spec/done > [p28] @fact:mandate-18 «Пожалуйста всю работу по программированию делай в режиме оркестратора, > выдавая задачи Opus 5 в режиме High. Все задачи про нечто умное и > творческое (написание статей, перевод на русский, проектирование смысла > дизайн-системы и так далее) - делай сама.» @status:spec/done > [p29] @fact:mandate-19 «Наша задача сэкономить токены так, чтобы Fable использовалась только там, > где Fable действительно нужна. Механическую работу могут сделать и другие > модели.» @status:spec/done > [p30] @fact:mandate-20 «Предлагаю по ходу выполнения задачи собирать журнал успехов, неудач и > главное - интересных находок. И дальше на основании того что у нас > получилось, нужно написать спецификацию с подробным объяснением как > обновлять эту документацию. Потому что написать документацию - полдела, а > вот регулярно обновлять ее в мелочках и периодически например раз в > неделю/месяц - глобальное ревью и улучшение - это другая важная часть. > Продумай сразу как мы будем обновлять доку, чтобы все наши находки по ходу > кампании реализации доков только улучшали этот процесс» @status:spec/done > [p31] @fact:mandate-21 «Единственное что мне не нравится твое правило "продукт не выходит без > обновления документации". Это неправда в нашем случае. Мы можем релизить > новые версии 10 раз в день и мерджить по 100 пулл-риквестов в день. Нет > никаких шансов, что документация не будет дрейфовать. Этот риск мы > принимаем. Мы просто обещаем себе чисто исходя из процессов нашей команды > (не технически) время от времени проводить полную проверку - ту что ты > назвала "релизной" но возможно ее стоит назвать как-то еще, потому что мы > не можем делать ее каждый релиз» @status:spec/done > [p32] @fact:mandate-22 «Я на всякий случай напоминаю тебе, что мы очень редко обновляем версию > Vibe. Узнать что версия изменилась нельзя почти никак, и это фича. Так что > у тебя вполне может быть ситуация, когда спека дрейфует в рамках одной и > той же версии. Например, мы в день выпустили десять версий и все с версией > 2.0.0, в расчете что пользователи будут делать vibe self update --force и > перекачивать текущую версию с сервера. Это аналог git amend в реальной > жизни ))) Мы постоянно делаем trunk based development с переписыванием > истории чтобы увеличить скорость итераций и выпуска релизов (не 1 раз в > месяц, а 10 раз в день). Иногда впрочем номер версии действительно > меняется и там можно что-то показывать.» @status:spec/done > [p33] @fact:mandate-23 «Гляди, мне нравится идея того, что между версиями можно посмотреть > разницу. И ты можешь добавить туда некий Pseudo-history mechanism для > этого. Но я предлагаю тебе не рассчитывать ни на что кроме самого номера > версии. То есть, разница считается между номерами версий. Например, > владелец решил, что 1.0.0 надо поднять до 2.0.0. Вот теперь ты можешь > смотреть разницу между ними. Но эта смена версии происходит не из-за > каких-то хитрых механик с чексуммами, не из постоянства файлов или чего-то > такого. Она происходит из осознанного желания владельца поменять номер > версии.» @status:spec/done > [p34] @fact:mandate-24 «Почему мне нравится твой pseudo-version-mechanism из предыдущих версий. > Потому что он позволяет алгоритмически понять, какую часть документации > надо обновить. Не нужно с помощью LLM штудировать ВСЮ документацию. НО > важно, что эти данные - это всё нужно для разработчиков документации. А > пользователи всей этой внутренней кухни видеть не должны. Они видят версию > 1.0.0 и воспринимают это как контракт "версия 1 делает то, что должна > делать версия 1". Какие там внутри файлы для пользователей обычно не важно. > […] Ты же считаешь сейчас версию не контрактом на поведение, а каким-то > конкретным замороженным набором файлов, это неправильно.» @status:spec/done > [p35] @fact:mandate-25 «В ходе кампании нужно наш лендинг vibevm-org тоже переделать на Qwik > чтобы было однообразно и хорошо композировалось» @status:spec/done > [p36] @fact:mandate-26 «По плану - вначале сделай всю документацию на английском, русский > перевод будет следующей волной, когда все остальное мы проверили и > увидели, что оно хорошо работает» @status:spec/done > [p37] @fact:mandate-27 «Ты можешь так вообще сдвинуть план, чтобы ты вначале написала все > красивые тексты на английском, и дальше мы полностью переключимся на Опус > и будем работать в нем над всей разработческой частью?» @status:spec/done > [p38] @fact:mandate-28 «Еще кажется важная идея: теперь любое действие можно сделать не только > вручную, но и агентом. Поэтому для сценариев имеет смысл вначале писать, > каким простым промптом достичь результата (например, создания пакета > vibevm), и только потом уже разворачивать механику работы без агентов > целиком вручную (если это вообще нужно! иногда не нужно!). […] Зачастую > люди будут заходить в документацию просто чтобы узнать "как это работает" > и "какой промпт запустить чтобы активировать эту механику". […] Это важное > отличие от документации прошлого, где все делалось только руками.» @status:spec/done ## 4. Принципы {#principles} [p39] @fact:principles-1 Это законы проекта, которые документация наследует. Здесь они названы, чтобы решения §5 читались как их следствия, а не как вкусовщина. @status:spec/done - [p40] @fact:P-01 **P-01 Спеки — IPC, документация — жанр поверх них.** Спека обязательна и адресуема; документация объясняет и не требует. Источник: flow `two-process-model`, `addressable-specs`, `spec-genres`. @status:spec/done - @fact:P-02 **P-02 Цитируй, не копируй.** Нормативное значение живёт у одного якоря. Страница документации цитирует адрес и никогда не пересказывает число, флаг, путь или правило. Источник: `addressable-specs`, PHASE-G-SPEC §3.1. @status:spec/done - @fact:P-03 **P-03 Односторонняя связь в источнике, двусторонняя в рендере.** Текст спеки о документации не знает. Обратные ссылки «объяснено в», «переведено на», «зависят от» вычисляются из индекса и карты и никогда не пишутся руками. @status:spec/done - @fact:P-04 **P-04 Выводимое не ведётся руками.** Справочник команд, таблицы полей, навигация, манифесты страниц, `llms.txt`, плейсхолдеры картинок, превью ссылок, обратные связи — генерируются. Источник: `omnichannel`, BACKLOG `ENTRY-PREFER-GENERATED`. @status:spec/done - @fact:P-05 **P-05 Объяснение исполняемо.** Пример, который никто не запускает, — это обещание. Каждый пример прогоняется на сборке, один раз, на исходном языке. Источник: дисциплина ai-native, `manual-tests`. @status:spec/done - @fact:P-06 **P-06 Адресуемость применяется к любому тексту, который читает агент.** Один юнит — одна мысль; юнит понятен без соседей; инварианты в начале или в конце; проверяемое утверждение снаружи fence. Источник: `authoring-rules`. @status:spec/done - @fact:P-07 **P-07 Токеномика.** Документация никогда не попадает в boot-префикс; она читается точечно. Всё, что мутирует, стоит после того, что стабильно. Источник: PROP-048. @status:spec/done - @fact:P-08 **P-08 Логика в библиотеке, поверхности тонкие.** Рендер, манифесты, проверки, плейсхолдеры живут в Rust-библиотеке; CLI, MCP, HTTP и локальный сервер — её проекции. Источник: `omnichannel`, PROP-000 §21. @status:spec/done - @fact:P-09 **P-09 Машинные контракты — JTD.** Любой wire между Rust и TypeScript описывается JTD-схемой, из которой генерируются типы; wire регистрируется в реестре форматов. Источник: PROP-000 §16, PROP-044. @status:spec/done - @fact:P-10 **P-10 Идентичность пакета — исходник.** В пакет не кладутся артефакты сборки. Картинки — исходник. Источник: `tool-design-lessons`, PROP-024 §2.2. @status:spec/done - @fact:P-11 **P-11 Решения записываются с отвергнутыми вариантами и триггером пересмотра.** Источник: `decision-records`. @status:spec/done - @fact:P-12 **P-12 Объём работ не является доводом.** Источник: `vibevm/vibespecs/boot/90-user.xml`, директива владельца 2026-08-09. @status:spec/done - @fact:P-13 **P-13 Официальность назначается сверху, видимость — по рёбрам.** Кто выше в иерархии, тот называет официальное; сайт находит всё, что объявило ребро, и показывает как community. Издатель всегда виден. @status:spec/done - [p41] @fact:P-14 **P-14 Сшивать, не рисовать заново.** Визуальный язык, ридер и хостинг берутся из того, что у владельца уже сделано и работает: дизайн-система по эталону, лендинг, ридер oleg.guru, runbook инфраструктуры. Новое рисуется только там, где источники молчат, и помечается как предварительное до дизайн-ревью на живом рендере. Источник: слово владельца 2026-09-10 (§3), закон «дешевле проверить, чем породить». @status:spec/done - @fact:P-15 **P-15 Страница стоит одна.** Каждая страница читается как единственная, которую читатель когда-либо откроет: термины введены на месте, объяснение полно без спек, спека — подтверждение, не отсылка. Сложность допускается только в контейнерах, которые читатель видит заранее. Источник: слово владельца 2026-09-10 (§3), `STYLE.md` §1–§2. @status:spec/done - @fact:P-16 **P-16 Промпт сначала.** Любое действие в VibeVM делается агентом или руками, и агент — основной путь. Страница сценария сначала даёт задание агенту, затем объясняет, что произойдёт, и только потом — если это вообще нужно — ручные шаги. Это отличие от документации прошлого, где всё делалось руками. Источник: слово владельца 2026-09-10 (§3), D-30. @status:spec/done ## 5. Решения {#decisions} ### D-01 Документация — это пакет; вводится kind `doc` {#d-01} [p42] @fact:D-01-DECISION **Решение.** В реестр видов добавляется `doc`. Пакет kind `doc`: @status:spec/done - [p43] @fact:d-01-2 ОБЯЗАН объявлять хотя бы один предмет в `[[documents]]` (D-04), а также `title` и `abstract` (D-20); @status:spec/done - @fact:d-01-3 НЕ МОЖЕТ объявлять `[boot_snippet]`, `[[mcp_server]]`, `[[binary]]`; @status:spec/done - @fact:d-01-4 МОЖЕТ объявлять `[[skill]]`, `[translates]`, `[media]` (список переводов в источнике не хранится — уточнение 2026-09-11, D-18); @status:spec/done - @fact:d-01-5 держит страницы под `vibevm/vibespecs/` своего дерева, как любой пакет со спеками; документы этого пакета относятся к жанру «документация» по признаку kind содержащего пакета; @status:spec/done - @fact:d-01-6 не устанавливается в проект командой `vibe install` (она отказывает с подсказкой), а прогревается в машинный store командой `vibe cache add`; локальный читатель и `vibe explain` читают store. @status:spec/done [p44] @fact:d-01-why **Почему.** Три требования владельца — локальное чтение, скилл, сайт — удовлетворяются одним механизмом: пакетом. Локальное чтение — это прогрев store; скилл — это `[[skill]]` в манифесте; сайт — рендер тех же байтов. Отказ от материализации в `vibedeps/` держит деревья потребителей тонкими и не даёт агенту наткнуться на туториалы при grep по зависимостям. Kind, а не жанр документа, задаёт поведение, потому что kind известен инструментам до чтения файлов: индекс, гейт публикации, `vibe init`, `vibe list`. @status:spec/done [p45] @fact:d-01-limit **Известное ограничение.** Прогрев store — машинный, не проектный: теммейт, клонировавший проект, не получит ту же версию документации автоматически. Скилл называет команду прогрева; проектного объявления «консультируйся с такой-то документацией» в этой волне нет. @status:spec/done [p46] @fact:d-01-rejected **Отвергнуто.** @status:spec/done - [p47] @fact:d-01-10 Документация как бес-kind-овый контент (форма PHASE-G-SPEC): инструменты не могли бы отличить её от flow и не могли бы запретить boot-сниппет. @status:spec/done - @fact:d-01-11 Материализация doc-пакетов в `vibedeps/` по умолчанию: раздувает коммитимое дерево каждого потребителя. @status:spec/done - @fact:d-01-12 Пятый корень раскладки `vibevm/vibedocs/`: ломает закон одного модуля раскладки (PROP-052) без выигрыша — адресация, сканеры и пивот уже работают над `vibevm/vibespecs/`. @status:spec/done [p48] @fact:d-01-revisit **Пересмотреть когда.** Появится потребитель, которому документация нужна в коммитимом дереве проекта или воспроизводимо между машинами команды (наблюдение: запрос в BACKLOG или отказ `vibe install` в реальном сценарии) — тогда добавить проектное объявление и режим материализации, не меняя default. @status:spec/done ### D-02 Два уровня документации {#d-02} [p49] @fact:D-02-DECISION **Решение.** Уровень 0: сайт рендерит любую опубликованную версию любого пакета из её собственных байтов — манифест как справочная страница, README, boot-сниппет, спеки с якорями, объявленные скиллы, бинарники и MCP-серверы, картинки из `[media]`. Уровень 1: расширенная документация — отдельный пакет kind `doc`, любое количество на предмет. Сайт сшивает уровни на одной странице пакета. @status:spec/done [p50] @fact:d-02-why **Почему.** Уровень 0 бесплатен для автора и покрывает весь реестр сразу, как rustdoc покрывает каждый крейт. Уровень 1 нужен только там, где кто-то хочет большего, и не заставляет остальных ничего писать. @status:spec/done [p51] @fact:d-02-rejected **Отвергнуто.** Только уровень 1 — пустой сайт на старте. Только уровень 0 — нет места туториалам и примерам. @status:spec/done [p52] @fact:d-02-revisit **Пересмотреть когда.** Никогда в рамках этой волны; уровни ортогональны. @status:spec/done ### D-03 Именование спутника и роль в семействе {#d-03} [p53] @fact:D-03-DECISION **Решение.** Официальная по умолчанию документация предмета `<группа>/<имя>` называется `<группа>/<имя>-docs`, в той же группе. Документация ядра — `org.vibevm.core/vibevm-docs`, спутник координаты хоста `org.vibevm.core/vibevm`. Официальный по умолчанию перевод документации `<группа>/<имя-документации>` на язык `` называется `<группа>/<имя-документации>-`, где `` — тег BCP-47 в нижнем регистре (`ru`, `pt-br`, `zh-hans`). Любая другая документация или перевод носят любое имя в любой группе: соглашение об имени нужно только для официальности по умолчанию, а отображаемое имя — это `title` (D-20). В PROP-028 добавляется роль `-docs` как **спутник**: он не участвует в унисонном версионировании семейства, ведёт собственную линию версий, а совместимость с предметом выражает ограничением версии в `[[documents]]`. @status:spec/done [p54] @fact:d-03-why **Почему.** Суффикс в той же группе — уже действующее правило семейств рядом с `-lang` и `-mcp`; новой грамматики именования не нужно. Публиковать в группу предмета может только её владелец, поэтому подделать «официальность» через имя нельзя. Унисон семейства — закон для «проверенного набора» кода; проза и переводы меняются в другом ритме. @status:spec/done [p55] @fact:d-03-rejected **Отвергнуто.** @status:spec/done - [p56] @fact:d-03-4 Подгруппа `org.vibevm.world.docs/<имя>` (форма DefinitelyTyped): копирует чужое пространство имён по договорённости, не несёт версию предмета, для сторонних авторов не работает, требует нового закона именования. @status:spec/done - @fact:d-03-5 Включить `-docs` в унисон семейства: каждая правка документации бампает весь код семейства. @status:spec/done - @fact:d-03-6 Кодировать язык в группе (`org.vibevm.core.ru/…`): та же ошибка подгруппы. @status:spec/done [p57] @fact:d-03-revisit **Пересмотреть когда.** PROP-028 получит четвёртую кодовую роль, и суффиксов станет тесно (наблюдение: конфликт стемов в реестре). @status:spec/done ### D-04 Связь документации с предметом {#d-04} [p58] @fact:D-04-DECISION **Решение.** Связь объявляется в обе стороны полями манифеста, а не именем. @status:spec/done [p59] ```toml # в пакете 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"] ``` [p60] @fact:d-04-2 Правила: @status:spec/done - [p61] @fact:d-04-3 `[[documents]]` обязателен в doc-пакете, может перечислять несколько предметов; версия — ограничение semver. @status:spec/done - @fact:d-04-4 `[documentation]` в предмете называет координаты **без версии**; `primary` — не более одной, `official` — сколько угодно. @status:spec/done - @fact:d-04-5 **Официальная** документация — та, для которой ребра сходятся: предмет назвал пакет, пакет объявил предмет. **Community** — есть только ребро от документации. Только ребро от предмета — «не опубликовано или ошибка», сайт показывает предупреждение. @status:spec/done - @fact:d-04-6 **Соглашение по умолчанию:** если предмет не объявил `[documentation]`, пакет `<имя>-docs` в той же группе считается официальным и основным. Объявленный `[documentation]` заменяет соглашение целиком. @status:spec/done - @fact:d-04-7 Для версии предмета V сайт показывает документацию тех версий, чьё ограничение в `[[documents]]` допускает V, выбирая новейшую. @status:spec/done - @fact:d-04-8 Прогрев doc-пакета через `vibe cache add` прогревает и его предметы, чтобы цитаты `spec://` резолвились офлайн. @status:spec/done - @fact:d-04-9 Поля связи попадают в запись индекса реестра, чтобы обратные связи строились по `primary.jsonl`, а не скачиванием пакетов. @status:spec/done [p62] @fact:d-04-why **Почему.** Ребро от предмета снимает опасение владельца: три разных контрибьютора не смогут спорить за «официальность», потому что её назначает предмет. Указатель без версии — потому что документация почти всегда выходит позже кода. Соглашение по умолчанию избавляет от переиздания предмета ради очевидного случая. Прецедент — поле `documentation` в Cargo.toml. @status:spec/done [p63] @fact:d-04-rejected **Отвергнуто.** @status:spec/done - [p64] @fact:d-04-12 Capability `docs:<координата>` в `provides`: грамматика capability допускает только kebab-case в обеих половинах (`crates/vibe-core/src/capability_ref.rs`), координата туда не помещается. @status:spec/done - @fact:d-04-13 Обычная зависимость `requires` на предмет: зависимость не означает «документирую». @status:spec/done - @fact:d-04-14 Пометка официальности в индексе реестра, вне байтов пакета: второй источник правды, исчезающий в локальном режиме и в приватных реестрах. @status:spec/done - @fact:d-04-15 Только соглашение об имени: ноль гарантий. @status:spec/done [p65] @fact:d-04-revisit **Пересмотреть когда.** Появится третий тип связи между пакетами такой же природы, помимо `documents` и `translates` — тогда обобщить в одну таблицу отношений, не плодя поля. @status:spec/done ### D-05 Kind `app` и граница с `tool` {#d-05} [p66] @fact:D-05-DECISION **Решение.** Kind `app` допускается в этой же поправке. Граница по механике: `tool` живёт в проекте и запускается через `vibe bin exec` по lock-файлу; `app` — самостоятельный продукт со своим профилем деплоя в плоскости build, package, deploy. Пакет сайта `org.vibevm.doc/web` — kind `app`. @status:spec/done [p67] @fact:d-05-why **Почему.** Граница по существующей механике проверяема инструментами; граница «по впечатлению» — нет. @status:spec/done [p68] @fact:d-05-rejected **Отвергнуто.** Считать сайт `tool`: у сайта нет смысла «выполниться в проекте по lock-файлу». @status:spec/done [p69] @fact:d-05-revisit **Пересмотреть когда.** Появится второй `app` с другой механикой запуска. @status:spec/done ### D-06 Сайт `vibevm.org/doc` и схема адресов {#d-06} [p70] @fact:D-06-DECISION **Решение.** Сайт монтируется под путём `/doc` основного домена. Язык — сегмент пути после `/doc/`; исходный язык документации не носит префикса. Отображение адресов детерминированное и без индекса: @status:spec/done [p71] ``` spec://<группа>/<имя>@<версия>/<документ>#<якорь> → https://vibevm.org/doc/<группа>/<имя>/<версия>/<документ>#<якорь> spec://<группа>/<имя>/<документ>#<якорь> → https://vibevm.org/doc/<группа>/<имя>/latest/<документ>#<якорь> перевод на ru той же страницы → https://vibevm.org/doc/ru/<группа>/<имя>/<версия>/<документ>#<якорь> ``` [p72] @fact:d-06-2 Страницы старых версий несут `rel=canonical` на `latest` в пределах своего языка. Локальный читатель использует ту же схему с другим origin. Адрес страницы заканчивается слэшем (`…/<документ>/`), проекции лежат рядом как файлы (`…/<документ>.md`, `…/<документ>.xml`); адрес без слэша получает редирект 308 и в вебе, и локально (уточнение 2026-09-11 по A0.10: единственный рабочий режим статического адаптера). @status:spec/done [p73] @fact:d-06-3 Адрес с номером версии всегда показывает **текущее** содержимое этой версии в реестре: один номер может быть опубликован десять раз за день, и сайт показывает последнюю публикацию. Постоянных ссылок на прошлые публикации нет — их не существует и в реестре (D-27). @status:spec/done [p74] @fact:d-06-4 Весь домен — один сайт (девятая редакция, 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` — лендинг, не копия документации. @status:spec/done [p75] @fact:d-06-why **Почему.** Путь под основным доменом делит его авторитет для SEO. Одна и та же схема в вебе и локально означает, что ссылка в документации работает в обоих мирах. Язык в пути, а не в параметре, — так его индексируют и цитируют. Лендинг уже проиндексирован и несёт дизамбигуацию имени «VibeVM» для AI-краулеров, поэтому его адреса и корневые файлы сохраняются при переезде на тот же сайт байт в байт, где это возможно, и проверяются тестом паритета (D-28). @status:spec/done [p76] @fact:d-06-rejected **Отвергнуто.** Поддомен `docs.vibevm.org`; язык в query-параметре; язык в поддомене; два сайта на одном домене — Astro-лендинг плюс Qwik-документация с контрактом трёх строк между репозиториями (решение третьей редакции, снято D-28). @status:spec/done [p77] @fact:d-06-revisit **Пересмотреть когда.** Никогда в рамках волны; смена схемы адресов — ломающее изменение с редиректами. @status:spec/done ### D-07 Реестровый сайт: источники, лента изменений, сборка по хэшу {#d-07} [p78] @fact:D-07-DECISION **Решение.** У сайта два источника, оба заданы конфигурацией той же формы, что `[[registry]]` проекта: @status:spec/done - [p79] @fact:d-07-2 **реестр пакетов** — один, по умолчанию GitHub-организация `vibespecs`; его индекс — лента изменений: сайт опрашивает `repomd.json` и `primary.jsonl` (или получает webhook), сравнивает пары «координата, content hash» с отрендеренным и пересобирает только изменившиеся; @status:spec/done - @fact:d-07-3 **репозиторий исходников хоста** — один, по умолчанию `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). @status:spec/done [p80] @fact:d-07-4 Рендер ключуется хэшем, идемпотентен и кэшируется. Ошибка рендера показывается как страница версии. Обратные связи — зависимые, «объяснено в», «переведено на» — берутся из индекса и карт, которые пакеты несут (`vibe specmap`). Зеркала и вторые реестры — будущее. @status:spec/done [p81] @fact:d-07-why **Почему.** Так устроен docs.rs над индексом crates.io, а у нас дешевле: версия заморожена по content hash. Хост — не пакет реестра, и заставлять его им стать ради сайта было бы ложным обобщением; git-источник уже поддержан. @status:spec/done [p82] @fact:d-07-rejected **Отвергнуто.** Полная пересборка по расписанию; публикация хоста в реестр ради рендера; чтение хоста с зеркала. @status:spec/done [p83] @fact:d-07-revisit **Пересмотреть когда.** Владелец откроет зеркала или второй реестр. @status:spec/done ### D-08 Контент-конвейер на Rust, оболочка на Qwik {#d-08} [p84] @fact:D-08-DECISION **Решение.** Всё содержательное — в 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-типами. @status:spec/done [p85] @fact:d-08-why **Почему.** Закон omnichannel. Если бы сайт заново парсил Markdown, якоря и факты потеряли бы идентичность, а локальный и публичный рендер разошлись бы. @status:spec/done [p86] @fact:d-08-rejected **Отвергнуто.** Статический генератор на стороне TypeScript, читающий исходники сам. @status:spec/done [p87] @fact:d-08-revisit **Пересмотреть когда.** Никогда в рамках волны. @status:spec/done ### D-09 Локальный читатель и режим встраивания {#d-09} [p88] @fact:D-09-DECISION **Решение.** `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 webview меняется от окна к окну; без параметра `'none'`; CORS-слоя у читателя нет вовсе, а параметры запуска передаются в страницу неисполняемым блоком `