@warpgogol/forge 4.1.6 → 4.2.2

package/README.uk.md

@@ -2,598 +2,192 @@
 
 Українська | [English](README.md)
 
-Портативний рушій управління для розробки проєктів за допомогою ШІ. Надає навички, RFC/ADR робочі процеси, угоди про найменування, вендоринг специфікацій та CLI — все незалежне від фреймворку та без зайвих залежностей (тільки `yaml` + `zod`).
+**ШІ може писати код. Forge тримає проєкт інженерним.**
+
+Репозиторіо-нативний шар управління для розробки за допомогою ШІ. Рішення, правила, навички та перевірки залишаються з проєктом — незалежно від агента, який з ним працює.
 
 > Розроблено в [Warpgogol](https://warpgogol.com) · Опубліковано як open source.
 
+[![npm version](https://img.shields.io/npm/v/@warpgogol/forge.svg)](https://www.npmjs.com/package/@warpgogol/forge) [![npm downloads](https://img.shields.io/npm/dm/@warpgogol/forge.svg)](https://www.npmjs.com/package/@warpgogol/forge) [![CI](https://github.com/syrokomskyi/forge/actions/workflows/ci.yml/badge.svg)](https://github.com/syrokomskyi/forge/actions) [![Node](https://img.shields.io/badge/Node-24%2B-green.svg)](https://nodejs.org) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+
 ---
 
-## Почніть прямо зараз
+## Почни зараз
 
-Створіть нову папку, відкрийте її у вашому ШІ-IDE (Windsurf, Cursor або будь-якому IDE з підтримкою ШІ-агентів) і вставте це:
+Створіть нову папку, відкрийте її у вашому ШІ-IDE (Windsurf, Cursor, Claude Code, Codex CLI або будь-якому IDE з підтримкою ШІ-агентів) і вставте це:
 
 ```
-Install https://npmjs.com/package/@warpgogol/forge in this folder and set up my project. I want to build: [опишіть ваш проєкт]
+Install https://npmjs.com/package/@warpgogol/forge in this folder and set up my project. I want to build: [describe your project]
 ```
 
-Замініть `[опишіть ваш проєкт]` на вашу ідею — гра, бібліотека, база знань, будь-що. ШІ-агент встановить Forge, згенерує каркас проєкту та налаштує живий перегляд. Далі ви просто розмовляєте: описуєте, що хочете, і агент будує це. Жодного програмування, жодного терміналу, жодних команд.
+Замініть `[describe your project]` своєю ідеєю — гра, бібліотека, база знань, будь-що. ШІ-агент встановить Forge, створить структуру проєкту і налаштує живий прев'ю. Далі ви просто говорите: описуєте, що хочете, і агент будує. Без програмування, без терміналу, без команд.
 
-### Після виконання промпту — навичка Bootstrap
+### Після завершення промпту — Bootstrap skill
 
-Коли ШІ-агент встановить Forge і згенерує каркас проєкту, він запустить навичку `/forge-bootstrap`. Це обов'язковий крок, який інтерактивно налаштовує ваш проєкт:
+Коли ШІ-агент встановить Forge і створить структуру проєкту, він запустить навичку `/forge-bootstrap`. Це обов'язковий крок, який інтерактивно налаштовує ваш проєкт:
 
 - Мову, якою ШІ спілкується з вами
 - Мову документації проєкту (RFC, ADR, README) — за замовчуванням англійська
 - Ваш стиль роботи — діловий або творчий
-- Ваше ім'я та форму звертання
-- Конфігурацію стеку (або міграцію наявного проєкту)
-
-Навичка ставить кілька простих запитань у чаті, а потім налаштовує все. Після завершення ви готові творити — просто скажіть ШІ-агенту, що ви хочете створити.
-
----
-
-## Що можна створити за допомогою Forge
-
-Forge підтримує п'ять типів проєктів. Ви обираєте один на старті — все інше відбувається автоматично.
+- Ваше ім'я та форму звернення
+- Вашу конфігурацію стеку (або міграцію існуючого проєкту)
 
-| Тип проєкту | Що це | Приклади |
-| --- | --- | --- |
-| **Браузерна гра** | Інтерактивна гра, що працює в браузері — 2D, аркада, головоломка, пригода | Лови зірки, головоломка з плитками, платформер |
-| **Управління / бібліотека** | Бібліотека коду або проєкт лише з управлінською структурою — без сайту, без гри, без відео, лише структура та документація | npm-пакет, внутрішній інструмент, центр документації |
-| **Гра Godot** | Десктопна або мобільна гра на Godot 4.x з C# — 2D, 3D, платформер, RPG | Пригода з виглядом зверху, 3D-платформер, головоломка |
-| **Система знань** | База знань з підтримкою доказів — структуровані набори даних, де твердження підтверджені зареєстрованими джерелами | База знань гри, доменна онтологія, куратований довідковий набір даних |
-| **Бібліотека TypeScript** | Універсальний TypeScript монорепозиторій з валідаторами найкращих практик — tsconfig, межі імпортів, фантомні залежності, експорти пакетів, strict mode, безпека barrel-експортів | Внутрішній інструмент, спільна бібліотека, TypeScript монорепозиторій |
-
-Кожен тип проєкту отримує власний каркас: правильну структуру папок, правильні залежності, правильні інструменти. Вам не потрібно знати, що це таке — Forge налаштує все за вас.
+Навичка ставить кілька простих запитань у чаті, потім усе налаштовує. Після завершення ви готові творити — просто скажіть ШІ-агенту, що хочете побудувати.
 
 ---
 
-## Forge та рушій Werkstatt
-
-Forge — це **шар управління**: навички, RFC/ADR робочі процеси, угоди про найменування, вендоринг специфікацій та CLI. Він незалежний від фреймворку та не має Runtime-залежностей (тільки `yaml` + `zod`).
-
-Для повного управління життєвим циклом проєкту — місії, релізи, розгортання, сертифікація, перевірки якості, генерація контенту — Forge підключається до **рушія Werkstatt** та **плагінів специфічних для стеку**. Це окремі npm-пакети, які встановлюються разом з Forge, коли потрібні можливості runtime понад управління.
-
-| Пакет | Призначення | Потрібен для |
-| --- | --- | --- |
-| [`@warpgogol/werkstatt`](https://github.com/syrokomskyi/werkstatt) | Рушій runtime — місії, релізи, розгортання Leitstand, сертифікація, Bordbuch, сховище артефактів | Усі типи проєктів з управлінням життєвим циклом |
-| [`@warpgogol/werkstatt-shared`](https://github.com/syrokomskyi/werkstatt-shared) | Спільна інфраструктура — перевірки, інтеграція, онтологія, паспорт | Встановлюється автоматично з рушієм |
-| [`@warpgogol/werkstatt-phaser-game`](https://github.com/syrokomskyi/werkstatt-phaser-game) | Плагін Phaser-гри — валідатори phaser, збірка Vite, адаптери розгортання | Проєкти браузерних ігор (`phaser-turborepo`) |
-| [`@warpgogol/werkstatt-godot-game`](https://github.com/syrokomskyi/werkstatt-godot-game) | Плагін Godot — валідатори сцен, збірка dotnet, розгортання itch.io, навички Godot | Проєкти ігор Godot (`godot-csharp`) |
-| [`@warpgogol/werkstatt-knowledge`](https://github.com/syrokomskyi/werkstatt-knowledge) | Плагін системи знань — прив'язка джерел, канонічна верифікація, екстракція, матеріалізація, перевірки релізу | Проєкти систем знань (`knowledge-typescript-turborepo`) |
-| [`@warpgogol/werkstatt-typescript`](https://github.com/syrokomskyi/werkstatt-typescript) | Плагін TypeScript — tsconfig, межі імпортів, фантомні залежності, експорти пакетів, strict mode, barrel-валідатори | Проєкти TypeScript TurboRepo (`typescript-turborepo`) |
-
-### Коли потрібні ці пакети
-
-- **Проєкти лише з управлінням** (RFC, ADR, навички, центри документації) — Forge сам по собі достатній.
-- **Ігри, проєкти Godot, системи знань** — встановіть `@warpgogol/werkstatt` (рушій) плюс відповідний плагін стеку. Навичка `forge-bootstrap` налаштовує прив'язки автоматично; самі пакети потрібно встановити як devDependencies.
-
-### Встановлення пакунків рушія
+## Швидкий старт (термінал)
 
 ```sh
-# Проєкт браузерної гри
-pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-phaser-game
-
-# Проєкт гри Godot
-pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-godot-game
-
-# Проєкт системи знань
-pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-knowledge
-
-# Проєкт TypeScript TurboRepo
-pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-typescript
+pnpm dlx @warpgogol/forge@latest create --in-place --profile typescript-turborepo
 ```
 
-> **Примітка для агентів:** Після створення проєкту командою `forge create` завжди встановлюйте рушій та відповідний плагін стеку. Прив'язки в `forge.yaml` посилаються на команди з цих пакунків (напр. `pnpm exec werkstatt run rfc.validate`), і вони не працюватимуть, якщо пакунки не встановлені.
-
----
-
-## Повний посібник зі встановлення (з нуля)
-
-Якщо ви ніколи раніше не програмували, цей розділ проведе вас від абсолютно порожнього комп'ютера до робочого налаштування Forge. Виконайте кроки для вашої операційної системи.
-
-### Що вам потрібно
-
-Потрібні дві безкоштовні програми:
-
-- **Node.js** (версія 24 або новіша) — дозволяє вашому комп'ютеру запускати JavaScript-інструменти.
-- **pnpm** — менеджер пакетів, який Forge використовує для встановлення залежностей. Він вбудований у Node.js і його лише треба увімкнути.
-
-Обидві програми безкоштовні. Спочатку встановлюєте Node.js, потім вмикаєте pnpm однією командою.
-
-### Ubuntu
-
-#### Крок 1 — Встановлення Node.js
+Потім відкрийте проєкт у вашому ШІ-IDE (Windsurf, Cursor, Claude Code, Codex CLI або будь-якому IDE з підтримкою ШІ-агентів) і скажіть агентові, що ви хочете створити.
 
-1. Відкрийте програму **Термінал** (натисніть `Ctrl + Alt + T` або знайдіть «Термінал» у ваших програмах).
+Одна команда. Далі — робота через агента.
 
-2. Завантажте та встановіть Node.js 24 (LTS), вставивши цю команду та натиснувши Enter:
+### Профілі стеку
 
-   ```sh
-   curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash - && sudo apt-get install -y nodejs
-   ```
+Forge не залежить від типу проєкту. Профілі стеку — готові стартові точки.
 
-   Вас попросять ввести пароль — введіть його (символи не відображатимуться під час введення, це нормально) і натисніть Enter.
-
-3. Перевірте, чи все працює:
-
-   ```sh
-   node --version
-   ```
-
-   Ви маєте побачити номер версії, наприклад `v22.x.x`, а не повідомлення про помилку.
-
-#### Крок 2 — Увімкнення pnpm
-
-Node.js містить інструмент **Corepack**, який керує менеджерами пакетів. Увімкніть pnpm командою:
-
-```sh
-corepack enable pnpm
-```
-
-Перевірте:
+| Профіль                          | Призначення                                 |
+| -------------------------------- | ------------------------------------------- |
+| `forge-shell`                    | Лише управління, бібліотеки, не-веб проєкти |
+| `typescript-turborepo`           | TypeScript монорепозиторій з валідаторами   |
+| `phaser-turborepo`               | Браузерні ігри, інтерактивні досвіди        |
+| `godot-csharp`                   | Десктопні/мобільні ігри на Godot 4.x + C#   |
+| `knowledge-typescript-turborepo` | Бази знань з підтримкою доказів             |
 
 ```sh
-pnpm --version
+# Перелічити доступні профілі
+pnpm exec forge profile.validate
 ```
 
-Ви маєте побачити номер версії, наприклад `10.x.x`.
-
-#### Крок 3 — Встановлення IDE зі штучним інтелектом
-
-Forge працює через розмову з ШІ-агентом. Вам потрібне IDE, що підтримує ШІ-агентів. Рекомендуємо **Windsurf** (протестовано з Forge):
-
-1. Перейдіть на [windsurf.com](https://windsurf.com) та завантажте версію для Linux.
-2. Відкрийте завантажений файл і дотримуйтесь інструкцій установника.
-3. Запустіть Windsurf.
-
-Можете також використовувати **Cursor** ([cursor.com](https://cursor.com)) або будь-яке IDE, що підтримує навички ШІ-агентів.
-
-### Windows
-
-#### Крок 1 — Встановлення Node.js
-
-1. Відкрийте [nodejs.org](https://nodejs.org) у вашому браузері.
-2. Завантажте **LTS-версію** (на ній буде написано «LTS» та «Recommended for Most Users»). Версія має бути 22.x або новіша.
-3. Запустіть завантажений установник (файл `.msi`). Прийміть усі стандартні параметри, натискаючи **Next** на кожному екрані, потім **Install**. Якщо Windows попросить дозвіл, натисніть **Yes**.
-
-4. Перевірте, чи все працює. Відкрийте **PowerShell** (знайдіть «PowerShell» у меню Пуск) і введіть:
-
-   ```sh
-   node --version
-   ```
-
-   Ви маєте побачити номер версії, наприклад `v22.x.x`, а не повідомлення про помилку.
-
-#### Крок 2 — Увімкнення pnpm
-
-Node.js містить інструмент **Corepack**, який керує менеджерами пакетів. Увімкніть pnpm командою:
-
-```sh
-corepack enable pnpm
-```
+---
 
-Перевірте:
+## Архітектура
 
-```sh
-pnpm --version
 ```
-
-Ви маєте побачити номер версії, наприклад `10.x.x`.
-
-#### Крок 3 — Встановлення IDE зі штучним інтелектом
-
-Forge працює через розмову з ШІ-агентом. Вам потрібне IDE, що підтримує ШІ-агентів. Рекомендуємо **Windsurf** (протестовано з Forge):
-
-1. Перейдіть на [windsurf.com](https://windsurf.com) та завантажте версію для Windows.
-2. Запустіть завантажений установник і дотримуйтесь майстра налаштування.
-3. Запустіть Windsurf.
-
-Можете також використовувати **Cursor** ([cursor.com](https://cursor.com)) або будь-яке IDE, що підтримує навички ШІ-агентів.
-
-### Додатково — Встановлення Godot та .NET (лише для проєктів ігор Godot)
-
-Якщо ви плануєте створювати **ігри Godot** (профіль `godot-csharp`), вам потрібні два додаткові інструменти:
-
-- **Godot 4.x** (з підтримкою .NET) — ігровий рушій. Завантажте його з [godotengine.org/download](https://godotengine.org/download). Обов'язково оберіть версію ".NET" (не стандартну версію).
-- **.NET SDK 8+** — runtime C# та інструменти збірки. Завантажте з [dotnet.microsoft.com/download](https://dotnet.microsoft.com/download).
-
-Перевірте, що обидва встановлені:
-
-```sh
-godot --version
-dotnet --version
+IDE / АГЕНТ / МОДЕЛЬ
+       ↓
+┌──────────────────────────────────┐
+│             FORGE                 │
+│                                   │
+│ Контракт проєкту      forge.yaml  │
+│ Рішення                RFC / ADR   │
+│ Поведінка агента      Skills      │
+│ Перевірка             Validators  │
+│ Еволюція              Upgrade     │
+└──────────────────────────────────┘
+       ↓
+ВАШ РЕПОЗИТОРІЙ
 ```
 
-### Усунення проблем
-
-- **«command not found» після встановлення Node.js** — Закрийте та знову відкрийте термінал (Ubuntu) або PowerShell (Windows). Системі потрібно перезавантажити список доступних команд.
-- **«corepack: command not found»** — Ваша версія Node.js занадто стара. Встановіть Node.js 24+ за кроками вище.
-- **ШІ-агент не знає про Forge** — Ви відкрили порожню папку, але ШІ-агент не має контексту Forge. Спочатку виконайте `pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo` (або відповідний профіль) у терміналі, потім відкрийте папку в вашому IDE. Команда `forge create` наповнює поточну папку навичками, конфігурацією та `AGENTS.md` — без цього ШІ-агент не може виявити Forge.
+Агенти можуть змінюватися. Моделі можуть змінюватися. IDE можуть змінюватися. Інженерні правила залишаються з проєктом.
 
 ---
 
-## Швидкий старт
-
-### Для креативних операторів — одна команда, потім просто розмовляйте
-
-Потрібно виконати одну команду в терміналі для створення проєкту. Після цього все працює через розмову з ШІ-агентом — більше команд не потрібно.
-
-#### Створення нового проєкту з нуля
-
-1. **Створіть папку проєкту та згенеруйте каркас Forge на місці.** Відкрийте термінал (PowerShell на Windows, Термінал на Ubuntu) і виконайте:
-
-   ```sh
-   mkdir my-game
-   cd my-game
-   pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo
-   ```
-
-   Назва проєкту визначається з назви папки (`my-game` у цьому прикладі). Ви можете перевизначити її прапорцем `--name`. Це наповнює поточну папку усьом, що потрібно Forge — навичками, конфігурацією та структурою проєкту. Для інших типів проєктів використовуйте інший `--profile`:
-
-   | Що ви хочете створити                    | Прапорець профілю                          |
-   | ---------------------------------------- | ------------------------------------------ |
-   | Браузерна гра (2D, аркада, головоломка)  | `--profile phaser-turborepo`               |
-   | Гра Godot (десктоп, мобільний, 2D/3D)    | `--profile godot-csharp`                   |
-   | Система знань (з підтримкою доказів)     | `--profile knowledge-typescript-turborepo` |
-   | Бібліотека або проєкт лише з управлінням | `--profile forge-shell`                    |
-
-2. **Відкрийте папку проєкту в вашому IDE.** Відкрийте папку з кроку 1 у Windsurf або вашому IDE.
-
-3. **Скажіть ШІ-агенту, що ви хочете створити.** Просто напишіть це в чаті своїми словами. Наприклад:
-
-   > Я хочу зробити гру на Godot, де ловиш зірки, що падають.
-
-   Або:
-
-   > Я хочу створити браузерну гру, де ловиш зірки, що падають.
-
-   Або:
-
-   > Я хочу створити TypeScript-бібліотеку для розрахунку астрологічних карт.
+## Що контролює Forge
 
-   Це все. ШІ-агент зробить усе інше:
-   - Налаштує структуру проєкту залежно від того, що ви описали (гра, бібліотека тощо)
-   - Налаштує мовні вподобання та параметри проєкту
-   - Запустить живий попередній перегляд, щоб ви бачили свою роботу (для ігор)
-   - Скаже вам URL для відкриття в браузері
-
-4. **Дивіться попередній перегляд.** Для ігор ШІ-агент дасть вам посилання localhost. Натисніть його — ваш проєкт уже запущений. Коли ви описуєте зміни, агент оновлює проєкт, а попередній перегляд оновлюється автоматично.
-
-   Для проєктів управління та бібліотек візуального попереднього перегляду немає — агент налаштує структуру проєкту та скаже, коли все готово.
-
-5. **Створюйте разом.** Далі ви просто розмовляєте. Хочете інший колір? Хочете додати сцену? Хочете додати нову функцію до бібліотеки? Просто скажіть. Агент виконає всю технічну роботу.
-
-#### Перенесення наявного проєкту у Forge
-
-Якщо ви вже маєте проєкт десь інше і хочете перенести його у Forge:
-
-1. **Створіть проєкт Forge.** Відкрийте термінал, створіть папку і виконайте:
-
-   ```sh
-   mkdir my-project
-   cd my-project
-   pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
-   ```
-
-   Потім відкрийте папку в вашому IDE.
-
-2. **Скажіть ШІ-агенту:**
-
-   > Я хочу перенести свій наявний проєкт у Forge. Він знаходиться за шляхом /path/to/my/project.
-
-   Агент:
-   - Визначить, який це тип проєкту (гра, бібліотека тощо)
-   - Перемістить усі ваші файли у новий проєкт Forge — включно з прихованими файлами на кшталт `.env`
-   - За бажанням перенесе вашу історію git
-   - Перевірить, чи все коректно збирається
-   - Запустить живий попередній перегляд (для візуальних типів проєктів)
-
-#### Що робити, якщо щось пішло не так?
-
-Просто скажіть ШІ-агенту. Він може перевірити стан проєкту, виправити проблеми та пояснити, що сталося — все простою мовою. Вам ніколи не потрібно відкривати термінал або вводити команди самостійно.
+| Площина              | Що управляє                                         |
+| -------------------- | --------------------------------------------------- |
+| **Намір**            | RFC, архітектурна ДНК, критерії приймання           |
+| **Рішення**          | ADR, журнали рішень, відстежуваність                |
+| **Поведінка агента** | Локальні навички та робочі процеси                  |
+| **Перевірка**        | Doctor, валідатори, контракти, детерміновані гейти  |
+| **Еволюція**         | Профілі, вендоринг специфікацій, адитивні оновлення |
 
 ---
 
-### Для розробників — CLI-команди
+## Без Forge / З Forge
 
-#### Створення нового проєкту (на місці)
+| Розробка з ШІ без Forge                | З Forge                                          |
+| -------------------------------------- | ------------------------------------------------ |
+| Правила живуть у промптах              | Правила живуть у репозиторії                     |
+| Архітектура неявна                     | Рішення стають RFC та ADR                        |
+| Поведінка агента залежить від сесії    | Локальні навички визначають відтворювані процеси |
+| «Готово» означає, що агент так каже    | Валідатори дають детерміновані перевірки         |
+| Новий агент починає з нуля             | Контракт проєкту подорожує з кодом               |
+| Оновлення ризикує перезаписати рішення | Оновлення адитивне та ідемпотентне               |
+| Конвенції специфічні для інструменту   | Агент- та IDE-незалежний шар проєкту             |
 
-```sh
-# Створіть папку проєкту, потім згенеруйте каркас Forge на місці
-# pnpm dlx завантажує Forge тимчасово — глобальне встановлення не потрібне
-mkdir my-project
-cd my-project
-pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
-
-# З конкретним профілем стеку
-mkdir my-game && cd my-game
-pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo
-
-mkdir my-godot-game && cd my-godot-game
-pnpm dlx @warpgogol/forge create --in-place --profile godot-csharp
-
-# Перевизначити назву проєкту (за замовчуванням визначається з назви папки)
-pnpm dlx @warpgogol/forge create --in-place --profile forge-shell --name my-custom-name
-```
+---
 
-Після створення каркаса Forge встановлюється як локальна devDependency. Використовуйте `pnpm exec forge` для всіх наступних команд у проєкті:
+## Forge Є / Forge Не Є
 
-#### Перенесення наявного проєкту у Forge
+**Forge Є**
 
-CLI-команди для перенесення немає — це інтерактивний процес під керівництвом ШІ:
+- Репозиторіо-нативний шар управління
+- Агент-незалежна інфраструктура проєкту
+- Детерміноване доповнення до ймовірнісних ШІ-агентів
+- Портативний контракт проєкту
 
-```sh
-# 1. Створіть новий порожній проєкт Forge (на місці)
-mkdir my-project && cd my-project
-pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
-
-# 2. Відкрийте проєкт у Windsurf (протестовано з Forge) або вашому IDE
-
-# 3. Запустіть навичку /forge-bootstrap і оберіть режим "transplant"
-#    Навичка:
-#    - Запитає шлях до вашого наявного коду
-#    - Автоматично визначить стек (Phaser, Godot тощо)
-#    - Перенесе всі файли (включно з .env та git-ігнорованими)
-#    - За бажанням перенесе історію git
-#    - Перевірить збірку
-```
+**Forge Не Є**
 
-#### Діагностика та перевірка
+- Ще однією ШІ-моделлю
+- Ще одним агентом-кодером
+- IDE
+- Хостованою платформою
+- Заміною Git
+- Магічною обгорткою «vibe coding»
 
-```sh
-# Перевірити стан проєкту
-pnpm exec forge doctor
+---
 
-# Валідувати RFC
-pnpm exec forge rfc.validate
+## Що ви отримуєте
 
-# Список доступних навичок
-pnpm exec forge skill.list
-```
+- **37 навичок** — пайплайн ідея→RFC, grilling, preferences, авторинг навичок
+- **RFC робочий процес** — створення, валідація, перелік, граф, архівування, acceptance probes
+- **ADR робочий процес** — легкі записи архітектурних рішень
+- **Вендоринг специфікацій** — вендоринг зовнішніх специфікацій як незмінних снапшотів
+- **Конвенції найменування** — kebab-case linting
+- **Linting робочих процесів** — валідація frontmatter `.agents/workflows/`
+- **Скаффолдинг стеку** — pnpm + Turborepo монорепозиторій з профілю
+- **Контракт прив'язок** — деконкретизація команд проєкту через `forge.yaml`
+- **Doctor** — перевірка здоров'я проєкту
+- **Upgrade** — адитивна, ідемпотентна синхронізація навичок та конфігурації
 
 ---
 
 ## Робота з вашим ШІ-агентом
 
-Forge працює з будь-яким ШІ-агентом — Windsurf, Cursor, Claude Code, Codex CLI або будь-яким IDE, що підтримує навички агентів. Налаштування однакове; важлива лише розмова. Ось патерни, які дають найбільший ефект.
-
-### Починайте з питань, а не з команд
-
-Найефективніша звичка: перед тим, як просити агента писати код, запитайте його про кодову базу. Агент може читати файли, шукати в історії git та запускати CLI-команди Forge — дайте йому спочатку дослідити.
-
-Добрі питання для початку сесії:
-
-- "Як структурований цей проєкт?"
-- "Які навички доступні і що вони роблять?"
-- "Проведи мене через RFC робочий процес у цьому проєкті."
-- "Що ми змінили цього тижня?" (агент читає git log)
-- "Чому ця функція має 15 параметрів? Перевір історію git."
-
-Це працює і для онбордингу — нові члени команди можуть швидко ввійти в курс справи, запитуючи агента, замість того, щоб вручну читати код. Агент читає все локально; нічого не завантажується та не тренується на вашому коді.
-
-### AGENTS.md — постійна пам'ять вашого проєкту
-
-Forge генерує файли `AGENTS.md` в корені проєкту та в кожній директорії робочого простору. Агент читає їх автоматично на початку кожної сесії — сприймайте їх як інструкції, які зберігаються між розмовами.
-
-**Що писати в AGENTS.md:**
-
-- Команди збірки та тестування (`pnpm test`, `pnpm run build:check`)
-- Угоди стилю коду ("використовуйте 2 пробіли, а не таби")
-- Архітектурні рішення ("пакет гри володіє всією логікою сцен")
-- Правила "роби X, а не Y" ("використовуйте `resolveImage()` для всіх image-пропів, ніколи сирий `src`")
-- Типові помилки, яких слід уникати
-
-**Коли агент помиляється**, скажіть йому оновити AGENTS.md, щоб він не повторював помилку. З часом AGENTS.md накопичує здобуті командою знання.
-
-Forge генерує AGENTS.md з `forge.yaml` через `forge.agents.generate`. Написані вручну AGENTS.md (без згенерованого маркера) зберігаються. Згенеровані файли регенеруються при запуску `forge upgrade` або `forge.agents.generate` — тому кладіть свої правила в `forge.yaml` або в написаний вручну AGENTS.md, а не в згенерований.
-
-### Описуйте результат, а не кроки
-
-Агент — автономний працівник, а не друкарська машинка. Скажіть йому, що ви хочете, а не як це зробити.
-
-**Погано** (занадто детально):
-
-> Відкрий src/game/player.ts, додай функцію calculateScore, яка приймає масив чисел, сумує його, повертає результат. Потім відкрий src/game/player.test.ts і додай тест.
-
-**Добре** (орієнтовано на результат):
-
-> Додай систему підрахунку очок, яка обчислює загальні бали за зібрані предмети.
-
-Для складних задач просіть агента спочатку спланувати:
-
-> Я хочу додати багатокористувацький режим. Спочатку склади план, покажи мені, і чекай на моє схвалення перед реалізацією.
-
-Навичка Forge `/fo-idea` формалізує це: ідея → аудит → план → реалізація → рев'ю. Ви можете викликати її явно, або агент буде слідувати цьому патерну, коли задача достатньо складна.
-
-### Дайте агенту дослідити
-
-Не пояснюйте занадто детально. Агент вміє читати файли, шукати в коді, перевіряти історію git та запускати команди. Замість того, щоб вказувати на конкретні файли, опишіть, що ви хочете зрозуміти або змінити:
-
-**Замість:** "Подивись у папці src/game файл player.ts і перевір, чи є там функція move."
-
-**Скажіть:** "Як працює рух гравця?"
-
-Агент знайде відповідні файли, простежить ланцюг викликів і пояснить вам. Якщо йому потрібен буде додатковий контекст, він запитає.
-
-### Паралельна робота
+Forge працює з будь-яким ШІ-агентом — Windsurf, Cursor, Claude Code, Codex CLI або будь-яким IDE, що підтримує навички агентів. Налаштування однакове; важлива лише розмова.
 
-Ви можете запускати кілька сесій агента одночасно — в різних вікнах IDE, вкладках терміналу або git worktrees. Кожна сесія працює незалежно.
+**Починайте з питань, а не з команд.** Перед тим, як просити агента писати код, запитайте його про кодову базу. Агент може читати файли, шукати в історії git та запускати CLI-команди Forge — дайте йому спочатку дослідити.
 
-Це корисно для:
+**Описуйте результат, а не кроки.** Скажіть агенту, що ви хочете, а не як це зробити. Для складних задач просіть агента спочатку спланувати.
 
-- Написання RFC в одній сесії, паралельно з реалізацією іншої функції в іншій
-- Дослідження двох дизайн-підходів паралельно перед вибором одного
-- Запуску тривалої валідації в одній сесії, продовжуючи роботу в іншій
+**Дозвольте агенту перевіряти власну роботу.** Дайте критерії «готовно» і дозвольте агенту перевірити себе: «Запусти тести після завершення.» «Валідуй RFC перед комітом.» «Перевір здоров'я проєкту через `forge doctor`.»
 
-Якщо ви використовуєте рушій Werkstatt, його система місій ізолює роботу — кожна місія має власну директорію workpiece, тому паралельні сесії не конфліктують.
-
-### Дозвольте агенту перевіряти власну роботу
-
-Дайте агенту критерії "готово" і дозвольте йому перевірити себе:
-
-- "Запусти тести після завершення."
-- "Валідуй RFC перед комітом."
-- "Перевір стан проєкту через `forge doctor`."
-
-Forge надає інструменти — `forge doctor`, `forge rfc.validate`, `forge skill.list`, тест-ранери. Скажіть агенту використовувати їх. Агент може запускати команди, читати вивід та виправляти проблеми без вашої втручання.
+**AGENTS.md — постійна пам'ять вашого проєкту.** Forge генерує файли `AGENTS.md`, які агент читає на початку кожної сесії. Кладіть туди команди збірки, стиль коду, архітектурні рішення та правила «роби X, а не Y».
 
 ---
 
-## Пакети навичок
-
-Пакети навичок (skill packs) дозволяють створювати навички проєкту під власним префіксом, окремо від портативних `fo-` навичок Forge. Це корисно, коли ваш проєкт має домен-специфічні робочі процеси, які не належать до портативного набору Forge.
-
-### Оголошення пакету
-
-Додайте запис `skillPacks` у `forge.yaml`:
-
-```yaml
-skillPacks:
-  - prefix: wg
-    dir: packages/my-skills/skills
-```
-
-- `prefix` — короткий ідентифікатор, що використовується як префікс імені навички (наприклад `wg-deploy`, `wg-content-check`). Не може бути `fo` (зарезервовано для Forge).
-- `dir` — директорія, що містить навички вашого пакету. Кожна навичка — піддиректорія з файлом `SKILL.md`.
-
-### Маніфест пакету (`forge.plugin.yaml`)
-
-Кожна директорія пакету повинна містити маніфест `forge.plugin.yaml`:
-
-```yaml
-id: my-pack
-version: 1.0.0
-```
-
-- `id` — ідентифікатор пакету в kebab-case.
-- `version` — рядок версії у форматі semver.
-
-`forge init` автоматично створює цей маніфест, якщо він відсутній. Ви також можете створити його вручну.
-
-### Структура навичок
-
-Навички мають ту саму структуру, що й навички Forge:
-
-```
-packages/my-skills/skills/
-  forge.plugin.yaml          # маніфест пакету
-  wg-deploy/
-    SKILL.md                 # визначення навички з frontmatter
-  wg-content-check/
-    SKILL.md
-```
-
-Кожен `SKILL.md` має стандартизований frontmatter (name, description, category, concerns, dependsOn) — той самий формат, що й у `fo-` навичок Forge.
-
-### Команди валідації
+## CLI
 
 ```sh
-# Валідувати всі маніфести пакетів
-pnpm exec forge plugin.validate
-
-# Перелічити виявлені пакети
-pnpm exec forge plugin.discover
+# Перевірити здоров'я проєкту
+pnpm exec forge doctor
 
-# Валідувати окремі навички (включно з навичками пакетів)
-pnpm exec forge skill.validate
+# Валідувати RFC
+pnpm exec forge rfc.validate
 
-# Перелічити всі навички (навички пакетів позначені pack:<prefix>)
+# Перелічити доступні навички
 pnpm exec forge skill.list
-```
-
-### Точки розширення (блоки Compass-контракту)
-
-Пакети можуть оголошувати власні блоки Compass-контракту — маркери у вихідних файлах, які `compass.validate` перевіряє. Це дозволяє вашому пакету визначати власні `<MY_CONTRACT>` блоки з обов'язковими тегами:
-
-```yaml
-id: my-pack
-version: 1.0.0
-extensionPoints:
-  compass:
-    contract:
-      blocks:
-        - blockId: api-contract
-          requiredFor:
-            - "packages/my-pack/**/*.ts"
-          requiredTags:
-            - name: purpose
-              minWords: 3
-```
-
-`compass.validate` видаватиме `COMPASS-PLUGIN-01` (відсутній блок), `COMPASS-PLUGIN-02` (відсутній обов'язковий тег) та `COMPASS-PLUGIN-03` (тег з меншою кількістю слів) для файлів, що відповідають `requiredFor`, але не містять блок.
-
-### Правила
-
-- Імена навичок пакету повинні починатися з префіксу пакету (наприклад `wg-deploy` для префіксу `wg`).
-- Навички пакету не можуть використовувати префікс `fo-` (зарезервовано для Forge).
-- Навички пакету не можуть посилатися на ідентифікатори платформених RFC/ADR або назви платформи.
-- Навички пакету можуть залежати від навичок Forge, але навички Forge не можуть залежати від навичок пакету (зберігає портативність).
-- Якщо ім'я навички пакету конфліктує з іменем навички Forge, навичка пакету пропускається під час синхронізації.
-
----
-
-## Профілі стеку
 
-Профіль стеку визначає каркас проєкту: структуру директорій, залежності, конфігурацію CI та перший робочий простір. Оберіть профіль прапорцем `--profile` під час створення проєкту.
-
-| Профіль | Тип проєкту | Опис | Перший робочий простір | Призначення |
-| --- | --- | --- | --- | --- |
-| `forge-shell` | Управління / бібліотека | Мінімальний каркас Forge (за замовчуванням) | — | Проєкти лише з управлінням, бібліотеки, невеб-проєкти |
-| `phaser-turborepo` | Браузерна гра | Phaser + TypeScript + pnpm + Turborepo | `games/my-game` | Браузерні ігри, інтерактивні досвіди |
-| `godot-csharp` | Гра Godot | Godot 4.x + C# + pnpm + Turborepo | `games/my-game` | Десктопні/мобільні ігри, інтерактивні проєкти на Godot |
-| `knowledge-typescript-turborepo` | Система знань | TypeScript + pnpm + Turborepo | `knowledge/my-kb` | Бази знань з підтримкою доказів, структуровані набори даних з джерельною простежуваністю |
-| `typescript-turborepo` | Бібліотека TypeScript | TypeScript + pnpm + Turborepo | — | Універсальний TypeScript TurboRepo монорепозиторій з валідаторами найкращих практик |
-
-```sh
-# Список доступних профілів (після встановлення)
-pnpm exec forge profile.validate
-```
-
-Коли ви переносите наявний проєкт через режим `/forge-bootstrap` transplant, Forge автоматично визначає відповідний профіль, перевіряючи файли-маркери (`phaser.config.*`, `project.godot` тощо).
-
-## Процес оновлення
-
-Коли публікується нова версія `@warpgogol/forge`, споживачі оновлюються адитивно:
-
-```sh
-# 1. Оновити Forge до останньої версії (локальна devDependency)
-pnpm update @warpgogol/forge
-
-# 2. Синхронізувати навички та стандартні прив'язки з встановленої версії
+# Синхронізувати навички та конфігурацію
 pnpm exec forge upgrade
 
-# 3. Перевірити стан проєкту
-pnpm exec forge doctor
+# Перевірити консистентність публічної поверхні
+pnpm exec forge public-surface.validate
 ```
 
-`forge upgrade` — адитивний: він ніколи не перезаписує прив'язки, встановлені оператором, ніколи не видаляє файли та є ідемпотентним. Він оновлює `forge.syncedVersion` у `forge.yaml`, щоб відстежувати останню синхронізовану версію. Використовуйте `--dry-run` для попереднього перегляду змін.
+Повний довідник CLI: [docs/reference/cli.md](docs/reference/cli.md)
 
-## Що дає Forge
-
-- **37 навичок** (fo-pipeline, grilling, preferences, написання навичок) — розгортаються у `.agents/skills/` командою `forge create`
-- **RFC робочий процес** — створення, валідація, список, граф, архівування, acceptance-зондування, журнали рішень, DNA-трасування
-- **ADR робочий процес** — легковісні архітектурні записи рішень
-- **Вендоринг специфікацій** — вендоринг зовнішніх пакетів специфікацій як незмінних знімків з маніфестами цілісності
-- **Угоди про найменування** — linting kebab-case
-- **Linting робочих процесів** — валідація frontmatter та посилань у `.agents/workflows/`
-- **Каркаси стеків** — створення нового pnpm + Turborepo монорепозиторію з профілю
-- **Контракт прив'язок** — декодування специфічних для проєкту команд/шляхів із навичок через `forge.yaml`
-
-## Життєвий цикл
-
-Типовий життєвий цикл проєкту Forge:
-
-1. **Створення** — `pnpm dlx @warpgogol/forge create --in-place --profile <профіль>` генерує каркас нового проєкту в поточній директорії з forge.yaml, навичками та директоріями документації
-2. **IDE** — відкрийте проєкт у Windsurf (протестовано з Forge) або вашому IDE
-3. **Bootstrap** — запустіть `/forge-bootstrap` для інтерактивного налаштування проєкту. Навичка підтримує два режими:
-   - **Greenfield** — створення нового проєкту з нуля: оберіть стек, заповніть прив'язки, ініціалізуйте git
-   - **Transplant** — перенесення наявного коду у Forge: визначення стеку, міграція коду (включно з git-ігнорованими файлами на кшталт `.env`), за бажанням перенесення історії git, перевірка збірки
-4. **Оновлення** — коли публікується нова версія `@warpgogol/forge`, запустіть `pnpm exec forge upgrade` для адитивної синхронізації навичок та стандартних прив'язок
+---
 
 ## forge.yaml
 
-Єдине джерело істини для конфігурації проєкту. Створюється командою `forge create`:
+Єдине джерело істини для конфігурації проєкту:
 
 ```yaml
 schema: forge/config@1
@@ -617,6 +211,10 @@ bindings:
     invariants: DNA
 ```
 
+Повний довідник: [docs/reference/forge-yaml.md](docs/reference/forge-yaml.md)
+
+---
+
 ## Програмний API
 
 ```ts
@@ -628,64 +226,59 @@ import {
   FORGE_SKILLS,
 } from "@warpgogol/forge";
 
-// Завантажити конфігурацію
 const config = loadForgeConfig(process.cwd());
-
-// Розв'язати прив'язку
 const cmd = resolveBinding(config, "commands.validateRfc", { id: "RFC-0001" });
 
-// Зареєструвати модулі у вашому реєстрі
 const registry = /* ваш ForgeModuleRegistry */;
 await forgeCoreModule.register(registry);
 await forgeRfcModule.register(registry);
 ```
 
-## Архітектура
+Повний API: [docs/reference/programmatic-api.md](docs/reference/programmatic-api.md)
+
+---
+
+## Структура
 
 | Директорія | Призначення |
 | --- | --- |
-| `src/` | Портативне ядро — типи, конфігурація, реєстр навичок, валідатори, онбординг. Нуль імпортів `@warpgogol/*`. |
-| `os/` | Реєстрації ForgeModule. `compass` та `werkstatt` повністю автономні (RFC-0556) — всі обробники вбудовані, без імпортів `@warpgogol/*`. |
+| `src/` | Портативне ядро — типи, конфіг, реєстр навичок, валідатори, онбординг. Нуль `@warpgogol/*` імпортів. |
+| `os/` | Реєстрації ForgeModule. `compass` та `werkstatt` — повністю автономні. |
 | `bin/` | Точка входу CLI (команда `forge`). |
-| `skills/` | 44 визначення навичок (36 fo + 5 спільних + 3 мета) з frontmatter SKILL.md. |
-| `scripts/` | Перевірка гігієни публікації (`publish-check.mjs`), запускається `prepublishOnly`. |
-| `profiles/` | Профілі стеків для `scaffold`. |
-
-## Публікація в npm
+| `skills/` | 37 визначень навичок (29 fo + 5 спільних + 3 мета) з SKILL.md frontmatter. |
+| `profiles/` | Профілі стеку для `scaffold`. |
 
-Цей пакет публікується в реєстр npm як `@warpgogol/forge`. Нижче описано, як опублікувати нову версію.
-
-### Передумови
-
-- Обліковий запис npm з правами публікації в організації `@warpgogol`.
-- Встановлені Node.js та pnpm локально.
-
-### Створення токена доступу
-
-1. Увійдіть на [npmjs.com](https://www.npmjs.com/).
-2. Перейдіть до **Access Tokens** (аватар → Access Tokens).
-3. Натисніть **Generate New Token** → оберіть **Classic Token** → тип **Publish**.
-4. Скопіюйте згенерований токен — він показується лише один раз.
-
-### Публікація нової версії
+---
 
-Виконайте такі команди з директорії `packages/forge`:
+## Оновлення
 
 ```sh
-# 1. Автентифікація в npm (інтерактивно — запитає username, password, OTP)
-npm login
+pnpm update @warpgogol/forge
+pnpm exec forge upgrade
+pnpm exec forge doctor
+```
 
-# 2. Зберегти auth-токен для реєстру (використайте токен з попереднього кроку)
-npm config set //registry.npmjs.org/:_authToken=<TOKEN>
+`forge upgrade` — адитивний: ніколи не перезаписує прив'язки, встановлені оператором, ніколи не видаляє файли, ідемпотентний. Використовуйте `--dry-run` для попереднього перегляду.
 
-# 3. Підняти patch-версію (оновлює package.json + створює git commit + tag)
-npm version patch
+---
 
-# 4. Опублікувати пакет публічно
-npm publish --access public
-```
+## Документація
+
+- [Початок роботи](docs/getting-started.md)
+- [Чому Forge?](docs/concepts/why-forge.md)
+- [Контракт проєкту](docs/concepts/project-contract.md)
+- [Модель управління](docs/concepts/governance-model.md)
+- [Перенесення наявного проєкту](docs/guides/existing-project.md)
+- [Оновлення](docs/guides/upgrading.md)
+- [Навички](docs/guides/skills.md)
+- [RFC та ADR робочі процеси](docs/guides/rfc-adr.md)
+- [Довідник CLI](docs/reference/cli.md)
+- [Довідник forge.yaml](docs/reference/forge-yaml.md)
+- [Профілі](docs/reference/profiles.md)
+- [Програмний API](docs/reference/programmatic-api.md)
+- [Публікація](docs/maintainers/publishing.md)
 
-Після публікації перевірте нову версію на [npmjs.com/package/@warpgogol/forge](https://www.npmjs.com/package/@warpgogol/forge).
+---
 
 ## Ліцензія
 
@@ -693,8 +286,8 @@ Apache-2.0
 
 ## Відкрита інженерія
 
-Цей пакет походить із виробничої інженерної роботи в [Warpgogol](https://warpgogol.com), інженерній студії в Німеччині.
+Цей пакет походить з виробничої інженерної роботи [Warpgogol](https://warpgogol.com), інженерної студії в Німеччині.
 
-Ми публікуємо багаторазові частини нашої інфраструктури, коли вони можуть бути корисними поза нашими власними проєктами. Він публікується незалежно від будь-якого комерційного сервісу Warpgogol. Використання цього пакету не створює жодної залежності від Warpgogol.
+Ми публікуємо багаторазово використовувані частини нашої інфраструктури, коли вони можуть бути корисні поза нашими власними проєктами. Пакет публікується незалежно від будь-якого комерційного сервісу Warpgogol. Використання цього пакету не створює залежності від Warpgogol.
 
-Створено для реальних систем. Поширюється відкрито.
+Створено для реальних систем. Поділяємо відкрито.