@nitra/cursor 1.29.5 → 1.32.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.32.0] - 2026-05-30
+
+### Added
+
+- **`rules/ci4/js/marksman_config.mjs`** + **`rules/ci4/js/data/marksman_config/marksman.baseline.toml`** — новий JS-концерн `marksman_config` за зразком `test.stryker_config`: при `npx @nitra/cursor fix ci4` копіює canonical `.marksman.toml` baseline у корінь cwd, якщо файлу ще немає. Idempotent через паттерн `ensureBaselineFile` (existsSync → pass+skip vs copyFile → pass+create) — ручні правки користувача між прогонами зберігаються, повторний прогон не перетирає. Baseline містить три ключові опції: `[core] markdown.glfm = true` (GLFM-фічі portable subset — alerts/таблиці/todo), `[completion] wiki.style = "file-stem"` (ADR slug == ім'я файла; стабільний ідентифікатор у AUTOGEN `sources`/manifest/валідаторі — заголовок міняється, посилання не ламається), `[code_action] toc.enable = true` (Insert/Update TOC code action для довгих arc42-сторінок). Дефолти marksman (`title-slug-ref` + вимкнений GLFM) ламали б частину задокументованої навігації. Розміщення в `cwd` (корені репо) робить весь монорепо одним marksman-workspace — README.md і docs/ перехресно навігуються. Тести: `+4` сценарії у `rules/ci4/js/tests/marksman_config.test.mjs` через `withTmpDir` (порожній cwd → файл створюється; idempotency — кастомний контент не перетирається; валідні TOML-секції `[core]`/`[completion]`/`[code_action]`; exit 0 у обох сценаріях). 4/4 PASS через `bunx vitest run rules/ci4/js/tests/marksman_config.test.mjs`.
+
+### Changed
+
+- **`rules/ci4/ci4.mdc`** (`version` 3.1 → 3.2) — у секцію «Viewer/editor: Zed + marksman LSP» додано параграф про авто-створення `.marksman.toml` правилом ci4 з посиланням на canonical baseline і поясненням кожної з трьох ключових опцій (glfm/wiki.style/toc.enable). У frontmatter `description` додано пункт про `.marksman.toml`. Дзеркало `.cursor/rules/n-ci4.mdc` синхронізується наступним прогоном `npx @nitra/cursor`.
+
+## [1.31.0] - 2026-05-30
+
+### Added
+
+- **`rules/ci4/policy/vscode_extensions/`** — нова policy за зразком text/style-lint/rego/ga/js-lint/graphql/nginx-default-tpl/rust/tauri: `vscode_extensions.rego` (deny якщо рекомендація з template-snippet відсутня в `.vscode/extensions.json`) + `vscode_extensions_test.rego` (5 сценаріїв: canonical, missing marksman, empty recommendations, extra recommendations пропускаються, drift-test що канон керується через `data.template`) + `template/extensions.json.snippet.json` (`{"recommendations": ["arr.marksman"]}`) + `target.json` (single `.vscode/extensions.json`). Призначення — контрибʼютори, що працюють у VSCode/Cursor замість Zed, отримують той самий шар marksman-навігації (cmd+click по `[link](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування заголовків) через офіційне розширення marksman LSP. Дзеркальна правка у репо: `.vscode/extensions.json` отримав `arr.marksman` у `recommendations`. Тести: 5/5 PASS через `opa test npm/rules/ci4/policy/vscode_extensions/`.
+
+### Changed
+
+- **`rules/ci4/ci4.mdc`** (`version` 3.0 → 3.1) — у секцію «Viewer/editor: Zed + marksman LSP» додано підсекцію **«VSCode-альтернатива»** з канонічним JSON-блоком `.vscode/extensions.json` (`recommendations: ["arr.marksman"]`) і посиланням на snippet-файл policy (за стилем `text.mdc`); також згадка про marksman-сумісні редактори (Neovim, Helix, Emacs). У frontmatter `description` додано пункт про VSCode-розширення. Дзеркало `.cursor/rules/n-ci4.mdc` синхронізується наступним прогоном `npx @nitra/cursor`.
+
+### Fixed
+
+- **`vitest.config.js`** — git-залежні тести (`rules/changelog/check.test.mjs`, `rules/ga/workflows.test.mjs`) масово таймаутили локально (`23 failed | 13 passed`, 187s; усі фейли — `Test timed out in 5000ms`, не assertion), хоча в CI зелені. Першопричина: глобальний `~/.gitconfig` тестової машини має `trace2.eventtarget=af_unix:stream:~/.git-ai/.../trace2.sock` (tooling `git-ai`), який успадковується tmp-репо в тестах → кожна git-команда під'єднується до Unix-сокета даемона; коли даемон деградований, запис у сокет блокується (~1s/команда не на CPU), а під `pool: 'forks'` десятки паралельних git-операцій × латентність > 5000ms `testTimeout`. Фікс: `env: { GIT_TRACE2_EVENT: '0' }` прибирає trace2-залежність із гарячого шляху тестового git (root-cause), плюс `testTimeout: 20000` як defence-in-depth проти будь-якої залишкової локальної I/O-латентності. Після фіксу `bun run vitest run rules/changelog/` → `36 passed` за ~7s (відтворювано); повний suite — `1248 passed | 2 skipped`. CI не зачеплено (там немає trace2-таргета).
+
+## [1.30.1] - 2026-05-29
+
+### Added
+
+- **`rules/test/coverage/tests/coverage.test.mjs`** — три нові тести `/n-coverage-fix`-ітерації, що вбивають усі чотири вцілілі мутанти на `rules/test/coverage/coverage.mjs`. (1) `opts.fix=false → fixSurvivedMutants НЕ викликається` і (2) `opts.fix=true → fixSurvivedMutants викликається` фіксують умовну гілку `if (opts.fix)` (L189) через лог `'✓ Всі мутанти вбиті — доповнення тестів не потрібне'`, який друкує `fixSurvivedMutants` для порожнього `survived[]`. (3) `source 2-ї стрілки містить fix:false` перевіряє джерело захопленої callback-стрілки 2-го `withLock` через `Function.prototype.toString()`: токени `fix` і `false` мають бути присутні, а `fix: true` — заборонений; це поведінково невловимо (`{}` і `{ fix: false }` дають однаковий falsy `opts.fix`), тому інваріант на рівні джерела.
+
+### Fixed
+
+- **`CHANGELOG.md`** — заголовок секції `[1.30.0]` піднято з `#` на `##` (Keep a Changelog vN.M.M вимагає H2 для версій). Чек `npm-module.mdc` зчитував h1 як «без версії», знаходив `[1.29.5]` першою і скаржився на розбіжність із `package.json#version "1.30.0"`.
+
+## [1.30.0] - 2026-05-29
+
+### Changed
+
+- **`rules/ci4/ci4.mdc`** (`version` 2.1 → 3.0) — viewer-story повністю переписано під **Zed + marksman LSP без site-generator-а**. MkDocs Material і pymdownx-розширення (`!!! note`, `??? engineer`, `=== "tab"`, кастомні audience-CSS) прибрані як рекомендація: їх не рендерить вбудований MD-preview Zed, що ламає принцип «відкрив файл = бачу фінальний вигляд». Collapsible-блоки для змішаної аудиторії — через нативний HTML5 `<details>` / `<summary>`, що рендериться скрізь (Zed preview, GitHub, будь-який майбутній збирач) без розширень парсера. Введено **portable-only subset**: CommonMark + GFM + Mermaid у fenced code + KaTeX + `<details>`; заборонені VitePress containers (`::: tip`), MDX/Astro-компоненти, Hugo shortcodes, AsciiDoc-вкраплення, RST-директиви. Конвенція маркера у `<summary>`: перше слово — аудиторія з фіксованого словника (`Engineer:`/`Ops:`/`Security:`/`Manager:`) → детермінований regex для валідатора. Валідатор отримав чотири нові перевірки: жоден `Engineer:`/`Ops:`/`Security:` блок у manager-only проекціях; кожен `<details>` має оточуючі порожні рядки (інакше `<summary>` рендериться як plain HTML); у `docs/` немає заборонених framework-specific конструкцій; inter-doc посилання працюють для marksman LSP (відносні шляхи або wiki-links). Промпт-скелет LLM-проекцій оновлено — генератор видає `<details>`, не `???`, і дотримується списку заборонених синтаксисів. Subset **forward-compatible**: будь-який збирач (MkDocs, VitePress, Antora) підключається пізніше без переписування контенту. Дзеркало `.cursor/rules/n-ci4.mdc` синхронізується наступним прогоном `npx @nitra/cursor`.
+
 ## [1.29.5] - 2026-05-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.29.5",
+  "version": "1.32.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/ci4/ci4.mdc

@@ -1,7 +1,7 @@
 ---
-description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; MkDocs Material як viewer з collapsible engineer-блоками для змішаної аудиторії
+description: Архітектурна документація продукту — Markdown як джерело істини; рекомендований стек arc42 + Diátaxis + ADR (MADR v4, формат описаний у правилі `adr`) + C4 як набір нотацій; гібридна модель manual + autogen-зон, що регенеруються з accepted ADR; Zed + marksman LSP як viewer без site-generator-а, portable subset (CommonMark + GFM + Mermaid + KaTeX), collapsible engineer-блоки через нативний `<details>`; рекомендоване VSCode-розширення `arr.marksman` для контрибʼюторів поза Zed; `.marksman.toml` авто-створюється у корені проєкту з canonical baseline
 alwaysApply: true
-version: '2.1'
+version: '3.2'
 ---
 
 Архітектурна документація проєкту живе у Markdown поряд із кодом. Це не довідник «для людей із порталу архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops).
@@ -47,7 +47,7 @@ RAG витягує **фрагменти**, не цілі документи. Т
 
 Доповнюємо **під domain**:
 
-- **DDD Context Maps** — коли є >1 bounded context (типово для multi-agent: agents, orchestration, memory, tooling). Одна Mermaid-діаграма в `explanation/architecture.md`, ховається під `??? engineer`.
+- **DDD Context Maps** — коли є >1 bounded context (типово для multi-agent: agents, orchestration, memory, tooling). Одна Mermaid-діаграма в `explanation/architecture.md`, ховається під `<details><summary><strong>Engineer:</strong> Context Map</summary>`.
 - **EventModeling** — для event-driven систем (агентські pipeline, CQRS, Event Sourcing). Структура: trigger → command → event → read model. Читається менеджером як наратив, інженером — як креслення.
 - **Business Capability Map** — верхньорівневий manager-overview. Autogen через семантичну класифікацію accepted ADR за тематикою.
 - **Wardley Map** — стратегічний артефакт для board/інвесторів. Manual, не autogen. Квартальне оновлення. Живе в `explanation/strategy.md`.
@@ -108,7 +108,7 @@ docs/
 
 ## Гібрид manual + autogen
 
-Реальні проєкти мають legacy docs, написані до появи ADR. Розв'язок — **зони** через HTML-коментарі (виживають у Markdown, не рендеряться у MkDocs):
+Реальні проєкти мають legacy docs, написані до появи ADR. Розв'язок — **зони** через HTML-коментарі (виживають у Markdown, не рендеряться у жодному MD viewer — ні в Zed built-in preview, ні на GitHub, ні в будь-якому майбутньому site-generator-і):
 
 ```markdown
 # User Service
@@ -191,61 +191,80 @@ User Service відповідає за автентифікацію та про
 - **Incremental**: LLM отримує поточний doc + новий ADR (або `## Update`) — видає diff. Дешевше, але дрейф накопичується.
 - **Компроміс**: incremental + періодичний full rebuild (раз на місяць або після N нових ADR).
 
-## MkDocs Material: collapsible engineer-блоки
+## Viewer/editor: Zed + marksman LSP
 
-Менеджер читає прозу зверху, інженер клікає `??? engineer` і провалюється глибше. Один документ — дві аудиторії без дублювання.
+Окремого site-generator-а **немає** — каталог `docs/` сам є інтерфейсом читання. Інженер відкриває `.md`-файл у Zed і одразу бачить рендер через built-in preview (`cmd+shift+m`). Між сторінками рухається через **`marksman`** LSP: `cmd+click` по `[link](file.md)` і `[[wiki-link]]`, автокомпліт заголовків, find-references, refactor-перейменування заголовків з оновленням посилань у всьому `docs/`.
 
-`mkdocs.yml`:
+`~/.config/zed/settings.json`:
 
-```yaml
-theme:
-  name: material
-  features:
-    - content.code.copy
-    - navigation.tabs
+```json
+{
+  "languages": {
+    "Markdown": {
+      "language_servers": ["marksman"],
+      "soft_wrap": "editor_width"
+    }
+  }
+}
+```
+
+**`.marksman.toml`** у корені проєкту авто-створюється правилом ci4 при першому `npx @nitra/cursor fix ci4` із canonical baseline ([data/marksman_config/marksman.baseline.toml](./js/data/marksman_config/marksman.baseline.toml)). Ключові опції — `markdown.glfm = true` (потрібен для GFM-alerts/таблиць/todo з portable subset), `[completion] wiki.style = "file-stem"` (ADR slug == ім'я файла, стабільний ідентифікатор у AUTOGEN `sources`/manifest/валідаторі — заголовок змінюється, посилання не ламається), `[code_action] toc.enable = true` (TOC code action для довгих arc42-сторінок). Без явного конфіга marksman використовує `title-slug-ref` і вимкнений GLFM — частина задокументованої навігації працювала б інакше. Ручні правки конфіга не перетираються — `ensureBaselineFile` ідемпотентний.
 
-markdown_extensions:
-  - admonition
-  - pymdownx.details
-  - pymdownx.superfences
-  - pymdownx.tabbed: { alternate_style: true }
-  - attr_list
+**VSCode-альтернатива.** Контрибʼютори, що працюють у VSCode/Cursor замість Zed, отримують той самий шар навігації через офіційне розширення marksman LSP. Канонічний запис у `.vscode/extensions.json`:
 
-extra_css:
-  - stylesheets/audience.css
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["arr.marksman"]
+}
 ```
 
-Синтаксис у документах:
+Канон `recommendations` (substring requirement): [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json). Інші marksman-сумісні редактори (Neovim, Helix, Emacs) налаштовують `marksman` як LSP-сервер за документацією свого редактора — поведінка ідентична (cmd+click по `[link](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування).
+
+**Portable-only синтаксис.** Усе, що пишемо в `docs/`, обмежене **CommonMark + GFM + Mermaid у fenced code (` ```mermaid `) + KaTeX (`$...$`) + нативний HTML5 `<details>`**. Заборонено:
+
+- pymdownx admonitions (`!!! note`, `??? engineer`, `=== "tab"`)
+- VitePress containers (`::: tip`, `::: details`)
+- MDX/Astro-компоненти (`<MyComponent />`)
+- Hugo shortcodes (`{{< youtube id >}}`)
+- AsciiDoc-вкраплення, RST-директиви
+
+Усе вище не рендериться у Zed built-in preview і ламає головний принцип: **«відкрив файл = побачив фінальний вигляд»**. Обмеження **forward-compatible**: portable subset рендериться у GitHub, MkDocs, VitePress, Antora — підключення збирача в майбутньому не потребує переписування контенту.
+
+## Collapsible-блоки для змішаної аудиторії
+
+Менеджер читає прозу зверху, інженер розгортає деталі. Реалізація — нативний HTML5 `<details>` / `<summary>`, що рендериться **скрізь**: Zed preview, GitHub, будь-який майбутній збирач. Жодних розширень парсера не треба.
 
 ```markdown
 User Service автентифікує користувачів і керує профілями.
 Підтримуємо OIDC-логін та email/password.
 
-??? engineer "Технічна реалізація автентифікації"
-    OIDC-сервер на Fastify з PKCE flow [oidc-pkce-flow].
-    Refresh-токени з rotation, TTL 30 днів, Redis storage.
+<details>
+<summary><strong>Engineer:</strong> Технічна реалізація автентифікації</summary>
+
+OIDC-сервер на Fastify з PKCE flow [oidc-pkce-flow].
+Refresh-токени з rotation, TTL 30 днів, Redis storage.
+
+</details>
 
 Профілі зберігаються в основній БД, кешуються в Redis на 5 хв.
 
-??? ops "Деталі кешу та інвалідації"
-    Cache key: `user:profile:{userId}:v2`.
-    Інвалідація — NATS подія `user.profile.updated` [user-profile-events].
+<details>
+<summary><strong>Ops:</strong> Деталі кешу та інвалідації</summary>
+
+Cache key: `user:profile:{userId}:v2`.
+Інвалідація — NATS подія `user.profile.updated` [user-profile-events].
+
+</details>
 ```
 
-`???` = згорнуто за замовчуванням, `???+` = розгорнуто.
+**Конвенція маркера у `<summary>`:** перше слово — аудиторія з фіксованого словника (`Engineer:`, `Ops:`, `Security:`, `Manager:`), далі — описова назва. Це дає валідатору детермінований regex для перевірок типу «жоден `Engineer:`-блок не з'являється в manager-only проекціях».
 
-Кастомні audience-styles у `docs/stylesheets/audience.css`:
+**Технічні нюанси `<details>`:**
 
-```css
-.md-typeset details.engineer > summary {
-  background-color: rgba(84, 110, 122, 0.1);
-  border-color: #546e7a;
-}
-.md-typeset details.ops > summary {
-  background-color: rgba(255, 152, 0, 0.1);
-  border-color: #ff9800;
-}
-```
+- порожній рядок до `<details>` і після `<summary>` обов'язковий — інакше Markdown-парсер не активує блочний рендер усередині
+- за замовчуванням блок згорнутий; `<details open>` — розгорнутий
+- візуальна типізація аудиторій робиться **через текст `<summary>`**, не через CSS — у Zed preview кастомні стилі недоступні
+- `<details>` ≠ HTML-обгортка з правила «жодних `<div>`/`<span>`»: це **семантичний** HTML5-елемент, а не презентаційний; його token-cost мізерний
 
 ## Промпт для LLM-проекцій
 
@@ -259,21 +278,35 @@ User Service автентифікує користувачів і керує п
    як пов'язано з іншими частинами продукту. Без технологій, версій, коду.
 
 2. Технічні деталі — тільки всередині блоків:
-   ??? engineer "Описова назва блоку"
-       Код, конфіги, версії, посилання на ADR.
+   <details>
+   <summary><strong>Engineer:</strong> Описова назва блоку</summary>
+
+   Код, конфіги, версії, посилання на ADR.
+
+   </details>
 
 3. Operational деталі:
-   ??? ops "Що моніторити та як реагувати"
+   <details>
+   <summary><strong>Ops:</strong> Що моніторити та як реагувати</summary>
+
+   Метрики, алерти, runbook-кроки.
+
+   </details>
 
 Правила:
-- Якщо прибрати всі ??? блоки, текст лишається зв'язним менеджерським документом.
-- Кожен факт з ADR маркуй [<slug>] всередині engineer-блоку — slug це ім'я clean ADR
+- Якщо прибрати всі <details>-блоки, текст лишається зв'язним менеджерським документом.
+- Перше слово у <summary> — аудиторія з фіксованого словника
+  (Engineer:/Ops:/Security:/Manager:), далі — описова назва
+  (наприклад «<strong>Engineer:</strong> Чому Percona, а не MariaDB»).
+- Порожній рядок до і після вмісту <details> обов'язковий.
+- Кожен факт з ADR маркуй [<slug>] всередині <details>-блоку — slug це ім'я clean ADR
   без розширення (наприклад `[ланцюжок-запуску-abie]`).
-- Назви блоків — описові («Чому Percona, а не MariaDB»).
 - НЕ виходь за межі <!-- AUTOGEN:start --> ... <!-- AUTOGEN:end -->.
 - ADR без рядка `**Status:** Accepted` ігноруй.
 - Якщо в ADR є `## Update YYYY-MM-DD` секції — враховуй найсвіжіший стан рішення,
   старі формулювання вважай застарілими.
+- Заборонені framework-specific synaxes: !!! note, ??? engineer, ::: tip,
+  MDX-компоненти, Hugo shortcodes — тільки CommonMark + GFM + Mermaid + <details>.
 ```
 
 ## Типові поломки LLM і захист
@@ -293,7 +326,10 @@ User Service автентифікує користувачів і керує п
 - Усі `[<slug>]` посилання вказують на існуючі файли `docs/adr/<slug>.md` із рядком `**Status:** Accepted`
 - Усі `AUTOGEN:start` мають парний `AUTOGEN:end` з тим самим `id`
 - Hash у `manifest.json` відповідає фактичному контенту зон
-- Жоден `??? engineer` блок не з'являється в manager-only проекціях
+- Жоден `<details>`-блок з `<summary>` що починається на `Engineer:` / `Ops:` / `Security:` не з'являється в manager-only проекціях
+- Кожен `<details>` має оточуючі порожні рядки (інакше `<summary>`-вміст рендериться як plain HTML, не collapsible)
+- У `docs/` немає заборонених framework-specific конструкцій: `!!! note`, `??? `, `::: tip`, `::: details`, MDX-теги `<[A-Z][a-zA-Z]*`, Hugo shortcodes `{{< `
+- Усі inter-doc посилання працюють для `marksman` LSP (відносні шляхи `[text](./other.md)` або `[[wiki-link]]`, не absolute URLs усередині `docs/`)
 - Якщо в зоні згадано компонент — він є в `docs/glossary.md`
 - ADR без `**Status:** Accepted` не потрапили у проекцію
 
@@ -317,7 +353,7 @@ ADR (`docs/adr/<slug>.md`) — джерело правди для autogen-про
 
 ## Зв'язок із документацією
 
-Архітектурні артефакти — частина **користувацької документації**, а не закритий артефакт для команди. Контекстна діаграма (C4 рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у проєкт — у `explanation/architecture.md`, не у відокремленій теці «for-architects». MkDocs Material рендерить це з collapsible-блоками, тому менеджер бачить прозу, інженер провалюється в деталі.
+Архітектурні артефакти — частина **користувацької документації**, а не закритий артефакт для команди. Контекстна діаграма (C4 рівень 1) і контейнерна (рівень 2) живуть там, де читач шукає вступ у проєкт — у `explanation/architecture.md`, не у відокремленій теці «for-architects». Нативний `<details>`-блок дає collapsible-вигляд у будь-якому MD-viewer (Zed built-in preview, GitHub web UI, потенційний майбутній site-generator) без залежності від конкретного фреймворку — менеджер бачить прозу, інженер розгортає деталі.
 
 ## Зв'язок із `.cursor/rules`
 
@@ -330,8 +366,11 @@ ADR (`docs/adr/<slug>.md`) — джерело правди для autogen-про
 - **Claude Code** як runner — slash-команда `/regen-docs` або post-commit hook на зміни `docs/adr/**`
 - **capture-decisions.sh** + **normalize-decisions.sh** — Stop-hooks створення ADR (керує правило `adr`)
 - **gray-matter** на Bun — лише для парсингу draft frontmatter; clean ADR парситься regexp по `**Status:**` / `**Date:**`
-- **MkDocs + Material** як viewer
-- **Mermaid** для C4-діаграм, EventModeling, Context Maps у проекціях
+- **Zed** як viewer/editor — built-in MD preview (`cmd+shift+m`) рендерить кожен файл без site-generator-а; `<details>` для collapsible-блоків
+- **marksman** LSP як шар навігації — `cmd+click` по `[text](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування заголовків
+- **Mermaid** для C4-діаграм, EventModeling, Context Maps — рендериться у Zed preview напряму з ` ```mermaid ` fenced code, без розширень
+- **KaTeX** (опційно) — інлайн-математика `$...$` для метрик/формул; рендериться у Zed preview
+- Site-generator (MkDocs Material / VitePress / Antora) — **не використовується**; portable subset гарантує, що його можна підключити пізніше без переписування контенту
 
 ## Query mode як бонус
 

package/rules/ci4/js/data/marksman_config/marksman.baseline.toml

@@ -0,0 +1,27 @@
+# Workspace-маркер marksman LSP. У корені репо робить весь монорепо одним
+# marksman-workspace — README.md і docs/ перехресно навігуються через
+# [text](file.md) і [[wiki-link]]. Файли .mdc не індексуються — marksman
+# дивиться лише на розширення нижче.
+#
+# Створюється правилом ci4 (npx @nitra/cursor fix ci4) із canonical baseline.
+# Ручні правки не перетираються: повторні прогони ідемпотентні (no-op).
+
+[core]
+markdown.file_extensions = ["md", "markdown"]
+
+# GitHub-Flavored Markdown (таблиці, todo, alerts, math) — наш portable subset.
+markdown.glfm = true
+
+[completion]
+# Стиль резолву [[wiki-link]]:
+#   "file-stem"      → [[oidc-pkce-flow]] резолвиться у docs/adr/oidc-pkce-flow.md
+#   "title-slug-ref" → резолв за slugified H1 заголовком
+# Беремо file-stem: ADR-slug == ім'я файла, стабільний ідентифікатор у
+# AUTOGEN sources, manifest, валідаторі. Заголовок може мінятися — посилання
+# не ламається.
+wiki.style = "file-stem"
+
+[code_action]
+# Code action "Insert/Update TOC" — корисно для довгих arc42-сторінок
+# (architecture.md з 12 розділами).
+toc.enable = true

package/rules/ci4/js/marksman_config.mjs

@@ -0,0 +1,52 @@
+/**
+ * Концерн `marksman_config` правила ci4 (ci4.mdc): копіює canonical
+ * `.marksman.toml` baseline у корінь cwd, якщо файлу ще немає.
+ *
+ * Marksman LSP читає `.marksman.toml` для визначення workspace-роота,
+ * GLFM-флага (GitHub-Flavored Markdown), стилю wiki-links і code actions.
+ * Дефолти marksman не вмикають GLFM і використовують `title-slug-ref` —
+ * але portable subset з ci4.mdc вимагає GLFM (alerts/таблиці/todo) +
+ * `file-stem` (ADR slug == ім'я файла). Без явного конфіга частина
+ * marksman-функцій працює інакше, ніж задокументовано у правилі.
+ *
+ * Idempotent: якщо `.marksman.toml` вже існує (навіть з кастомним вмістом)
+ * — не перетирається, тільки рапортується факт існування. Ручні правки
+ * користувача зберігаються між прогонами.
+ *
+ * Файл скопійовано в `cwd`, бо marksman визначає workspace-root за
+ * розташуванням свого `.marksman.toml`. У корені репо марксман бачить
+ * і docs/, і README.md усіх workspaces одним workspace-ом.
+ */
+import { existsSync } from 'node:fs'
+import { copyFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const MARKSMAN_BASELINE_PATH = join(HERE, 'data', 'marksman_config', 'marksman.baseline.toml')
+const MARKSMAN_TARGET_FILENAME = '.marksman.toml'
+
+/**
+ * @param {string} [cwd] корінь проєкту (default: `process.cwd()` — CLI-сумісність)
+ * @returns {Promise<number>} 0 — OK (створено або вже існує), 1 — baseline-файл пакета зламаний
+ */
+export async function check(cwd = process.cwd()) {
+  const reporter = createCheckReporter()
+
+  if (!existsSync(MARKSMAN_BASELINE_PATH)) {
+    reporter.fail(`canonical baseline не знайдено (${MARKSMAN_BASELINE_PATH}) — перевстанови @nitra/cursor`)
+    return reporter.getExitCode()
+  }
+
+  const target = join(cwd, MARKSMAN_TARGET_FILENAME)
+  if (existsSync(target)) {
+    reporter.pass(`${MARKSMAN_TARGET_FILENAME} існує (${relative(cwd, target)})`)
+    return reporter.getExitCode()
+  }
+
+  await copyFile(MARKSMAN_BASELINE_PATH, target)
+  reporter.pass(`${MARKSMAN_TARGET_FILENAME} створено з canonical baseline (${relative(cwd, target)}) (ci4.mdc)`)
+  return reporter.getExitCode()
+}

package/rules/ci4/policy/vscode_extensions/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": ".vscode/extensions.json" }
+}

package/rules/ci4/policy/vscode_extensions/template/extensions.json.snippet.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["arr.marksman"]
+}

package/rules/ci4/policy/vscode_extensions/vscode_extensions.rego

@@ -0,0 +1,12 @@
+# Перевірка `.vscode/extensions.json` для ci4 (ci4.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+package ci4.vscode_extensions
+
+import rego.v1
+
+deny contains msg if {
+	some rec in data.template.snippet.recommendations
+	not rec in {r | some r in object.get(input, "recommendations", [])}
+	msg := sprintf(".vscode/extensions.json: recommendations має містити %q (ci4.mdc)", [rec])
+}