@warpgogol/forge 0.16.0 → 0.17.1

package/README.md

@@ -1,39 +1,310 @@
 # @warpgogol/forge
 
+[Українська](README.uk.md) | English
+
 Portable governance engine for AI-assisted project development. Provides skills, RFC/ADR workflows, naming conventions, spec vendoring, and a CLI — all framework-agnostic and dependency-free (only `yaml` + `zod`).
 
-## Install
+## What you can build with Forge
+
+Forge supports four kinds of projects. You pick one when you start — everything else is automatic.
+
+| Project type | What it is | Example ideas |
+| --- | --- | --- |
+| **Website** | A public website or web app — pages, blog, portfolio, landing page, online store | Photography studio site, restaurant website, SaaS landing page |
+| **Browser game** | An interactive game that runs in a web browser — 2D, arcade, puzzle, adventure | Catch falling stars, tile-matching puzzle, platformer |
+| **Video** | A programmatic video composition — animated logo, intro, product showcase, motion design | Brand intro video, product demo, social media ad clip |
+| **Governance / library** | A code library or governance-only project — no website, no game, no video, just structure and documentation | npm package, internal toolkit, documentation hub |
+
+Each project type gets its own scaffold: the right folder structure, the right dependencies, the right tools. You don't need to know what any of those are — Forge sets them up for you.
+
+---
+
+## Complete installation guide (from zero)
+
+If you've never programmed before, this section takes you from a completely empty computer to a working Forge setup. Follow the steps for your operating system.
+
+### What you need
+
+You need two free programs:
+
+- **Node.js** (version 22 or newer) — lets your computer run JavaScript tools.
+- **pnpm** — the package manager Forge uses to install dependencies. It's built into Node.js and just needs to be switched on.
+
+Both are free. You install Node.js first, then enable pnpm with a single command.
+
+### Ubuntu
+
+#### Step 1 — Install Node.js
+
+1. Open the **Terminal** app (press `Ctrl + Alt + T`, or search for "Terminal" in your applications).
+
+2. Download and install Node.js 22 (LTS) by pasting this command and pressing Enter:
+
+   ```sh
+   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
+   ```
+
+   You'll be asked for your password — type it (you won't see the characters as you type, that's normal) and press Enter.
+
+3. Verify it worked:
+
+   ```sh
+   node --version
+   ```
+
+   You should see a version number like `v22.x.x`, not an error message.
+
+#### Step 2 — Enable pnpm
+
+Node.js includes a tool called **Corepack** that manages package managers. Enable pnpm with:
 
 ```sh
-npm install @warpgogol/forge
-# or
-pnpm add @warpgogol/forge
+corepack enable pnpm
 ```
 
+Verify:
+
+```sh
+pnpm --version
+```
+
+You should see a version number like `10.x.x`.
+
+#### Step 3 — Install Forge globally
+
+Installing Forge globally means the `forge` command is available everywhere on your computer, not just inside one project:
+
+```sh
+pnpm add -g @warpgogol/forge
+```
+
+Verify:
+
+```sh
+forge --version
+```
+
+You should see a version number. Forge is now installed and ready.
+
+#### Step 4 — Install an AI-powered IDE
+
+Forge works through conversation with an AI agent. You need an IDE that supports AI agents. We recommend **Windsurf** (tested with Forge):
+
+1. Go to [windsurf.com](https://windsurf.com) and download the Linux version.
+2. Open the downloaded file and follow the installer.
+3. Launch Windsurf.
+
+You can also use **Cursor** ([cursor.com](https://cursor.com)) or any IDE that supports AI agent skills.
+
+### Windows
+
+#### Step 1 — Install Node.js
+
+1. Go to [nodejs.org](https://nodejs.org) in your web browser.
+2. Download the **LTS version** (it will say "LTS" and "Recommended for Most Users"). It should be version 22.x or newer.
+3. Run the downloaded installer (`.msi` file). Accept all default options by clicking **Next** through each screen, then **Install**. If Windows asks for permission, click **Yes**.
+
+4. Verify it worked. Open **PowerShell** (search for "PowerShell" in the Start menu) and type:
+
+   ```sh
+   node --version
+   ```
+
+   You should see a version number like `v22.x.x`, not an error message.
+
+#### Step 2 — Enable pnpm
+
+Node.js includes a tool called **Corepack** that manages package managers. Enable pnpm with:
+
+```sh
+corepack enable pnpm
+```
+
+Verify:
+
+```sh
+pnpm --version
+```
+
+You should see a version number like `10.x.x`.
+
+#### Step 3 — Install Forge globally
+
+Installing Forge globally means the `forge` command is available everywhere on your computer, not just inside one project:
+
+```sh
+pnpm add -g @warpgogol/forge
+```
+
+Verify:
+
+```sh
+forge --version
+```
+
+You should see a version number. Forge is now installed and ready.
+
+#### Step 4 — Install an AI-powered IDE
+
+Forge works through conversation with an AI agent. You need an IDE that supports AI agents. We recommend **Windsurf** (tested with Forge):
+
+1. Go to [windsurf.com](https://windsurf.com) and download the Windows version.
+2. Run the downloaded installer and follow the setup wizard.
+3. Launch Windsurf.
+
+You can also use **Cursor** ([cursor.com](https://cursor.com)) or any IDE that supports AI agent skills.
+
+### Optional — Install FFmpeg (only for video projects)
+
+If you're planning to create **video** projects (the `editframe` profile), you need **FFmpeg** — a free tool for processing video and audio.
+
+**Ubuntu:**
+
+```sh
+sudo apt-get install -y ffmpeg
+ffmpeg -version
+```
+
+**Windows:**
+
+1. Go to [ffmpeg.org/download.html](https://ffmpeg.org/download.html) in your browser.
+2. Download a Windows build (look for "Windows builds" — the gyan.dev or BtbN builds are good choices).
+3. Extract the downloaded `.zip` file to a folder, e.g. `C:\ffmpeg`.
+4. Add FFmpeg to your system PATH:
+   - Open the Start menu, search for "Environment Variables", and click "Edit the system environment variables".
+   - Click **Environment Variables**.
+   - Under "System variables" (or "User variables"), find **Path**, select it, and click **Edit**.
+   - Click **New** and type `C:\ffmpeg\bin` (or wherever you extracted FFmpeg, in the `bin` subfolder).
+   - Click **OK** on all three windows.
+5. Close and reopen PowerShell, then verify:
+
+   ```sh
+   ffmpeg -version
+   ```
+
+You should see version information, not an error.
+
+### Troubleshooting
+
+- **"command not found" after installing Node.js** — Close and reopen your terminal (Ubuntu) or PowerShell (Windows). The system needs to reload the list of available commands.
+- **"EACCES permission denied" on Ubuntu when installing Forge globally** — Run `sudo pnpm add -g @warpgogol/forge` instead.
+- **"corepack: command not found"** — Your Node.js version is too old. Install Node.js 22+ using the steps above.
+- **Windsurf can't find `forge`** — Close and reopen Windsurf after installing Forge. IDEs need to restart to pick up new global commands.
+- **AI agent doesn't know about Forge** — You opened an empty folder, but the AI agent has no Forge context. Run `forge create my-project --profile editframe` (or the appropriate profile) in a terminal first, then open the created folder in your IDE. The `forge create` command populates the folder with skills, configuration, and `AGENTS.md` — without it, the AI agent can't discover Forge.
+
+---
+
 ## Quick start
 
-### Create a new project
+### For creative operators — one command, then just talk
+
+You need to run one command in the terminal to create your project. After that, everything works through conversation with an AI agent — no more commands.
+
+#### Start a new project from scratch
+
+1. **Create a Forge project.** Open a terminal (PowerShell on Windows, Terminal on Ubuntu) and run:
+
+   ```sh
+   forge create my-brand-video --profile editframe
+   ```
+
+   Replace `my-brand-video` with your project name (lowercase letters and hyphens). This creates a new folder with everything Forge needs — skills, configuration, and project structure. For other project types, use a different `--profile`:
+
+   | What you want to build                    | Profile flag                           |
+   | ----------------------------------------- | -------------------------------------- |
+   | Video (brand video, intro, motion design) | `--profile editframe`                  |
+   | Website (landing page, blog, portfolio)   | `--profile astro-typescript-turborepo` |
+   | Browser game (2D, arcade, puzzle)         | `--profile phaser-turborepo`           |
+   | Library or governance-only project        | `--profile forge-shell`                |
+
+2. **Open the project folder in your AI IDE.** Open the folder that was created in step 1 in Windsurf or your preferred IDE.
+
+3. **Tell the AI agent what you want to build.** Just type it in the chat, in your own words. For example:
+
+   > I want to create a brand video for my coffee shop. It should have an animated logo, a short intro, and a product showcase.
+
+   Or:
+
+   > I want to build a website for my photography studio.
+
+   Or:
+
+   > I want to make a browser game where you catch falling stars.
+
+   Or:
+
+   > I want to create a TypeScript library for calculating astrology charts.
+
+   That's it. The AI agent will do everything else:
+   - Set up the project structure based on what you described (video, website, game, library, etc.)
+   - Configure language preferences and project settings
+   - Start a live preview so you can see your work (for websites, games, and videos)
+   - Tell you the URL to open in your browser
+
+4. **Watch the preview.** For websites, games, and videos, the AI agent will give you a localhost link. Click it — your project is already running. As you describe changes, the agent updates the project and the preview refreshes automatically.
+
+   For governance and library projects, there's no visual preview — the agent will set up the project structure and tell you when it's ready.
+
+5. **Create together.** From here on, you just talk. Want a different color? Want to add a scene? Want to change the music? Want to add a new function to your library? Just say it. The agent handles all the technical work.
+
+#### Bring an existing project into Forge
+
+If you already have a project somewhere else and want to move it into Forge:
+
+1. **Create a Forge project.** Open a terminal and run:
+
+   ```sh
+   forge create my-project
+   ```
+
+   Then open the created folder in your AI IDE.
+
+2. **Tell the AI agent:**
+
+   > I want to bring my existing project into Forge. It's located at /path/to/my/project.
+
+   The agent will:
+   - Detect what kind of project it is (website, video, game, library, etc.)
+   - Move all your files into the new Forge project — including hidden files like `.env`
+   - Optionally bring your git history
+   - Verify everything builds correctly
+   - Start a live preview (for visual project types)
+
+#### What if something goes wrong?
+
+Just tell the AI agent. It can check the project's health, fix issues, and explain what happened — all in plain language. You never need to open a terminal or run commands yourself.
+
+---
+
+### For developers — CLI commands
+
+#### Create a new project
 
 ```sh
 # Create a new project (scaffold + init + skills + AGENTS.md in one command)
-npx forge create my-project
+forge create my-project
 
 # With a specific stack profile
-npx forge create my-site --profile astro-typescript-turborepo
-npx forge create my-game --profile phaser-turborepo
-npx forge create my-video --profile editframe
+forge create my-site --profile astro-typescript-turborepo
+forge create my-game --profile phaser-turborepo
+forge create my-video --profile editframe
+forge create my-library --profile forge-shell
 
-# With a non-default package manager
-npx forge create my-project --package-manager npm
 ```
 
-### Bring an existing project into Forge
+If Forge is not installed globally, use `pnpm dlx` instead:
+
+```sh
+pnpm dlx @warpgogol/forge create my-project
+```
+
+#### Bring an existing project into Forge
 
 There is no CLI command for transplant — it is an interactive, AI-guided process:
 
 ```sh
 # 1. Create a new empty Forge project
-npx forge create my-project
+forge create my-project
 
 # 2. Open the project in Windsurf (tested with forge) or your preferred IDE
 
@@ -46,33 +317,35 @@ npx forge create my-project
 #    - Verify the build
 ```
 
-### Diagnose and validate
+#### Diagnose and validate
 
 ```sh
 # Check project health
-npx forge doctor
+forge doctor
 
 # Validate RFCs
-npx forge rfc.validate
+forge rfc.validate
 
 # List available skills
-npx forge skill.list
+forge skill.list
 ```
 
 ## Stack profiles
 
 A stack profile defines the project scaffold: directory structure, dependencies, CI config, and first workspace. Choose a profile with `--profile` when creating a new project.
 
-| Profile | Description | First workspace | Use case |
-| --- | --- | --- | --- |
-| `forge-shell` | Minimal Forge shell (default) | — | Governance-only projects, libraries, non-web projects |
-| `astro-typescript-turborepo` | Astro + TypeScript + pnpm + Turborepo | `sites/my-site` | Websites, web apps, content-driven sites |
-| `phaser-turborepo` | Phaser + TypeScript + pnpm + Turborepo | `games/my-game` | Browser games, interactive experiences |
-| `editframe` | Editframe React + Vite + TailwindCSS | `compositions/my-first-video` | Video compositions, brand videos, motion design |
+| Profile | Project type | Description | First workspace | Use case |
+| --- | --- | --- | --- | --- |
+| `forge-shell` | Governance / library | Minimal Forge shell (default) | — | Governance-only projects, libraries, non-web projects |
+| `astro-typescript-turborepo` | Website | Astro + TypeScript + pnpm + Turborepo | `sites/my-site` | Websites, web apps, content-driven sites |
+| `phaser-turborepo` | Browser game | Phaser + TypeScript + pnpm + Turborepo | `games/my-game` | Browser games, interactive experiences |
+| `editframe` | Video | Editframe React + Vite + TailwindCSS | `compositions/my-first-video` | Video compositions, brand videos, motion design |
+
+The `editframe` profile also supports an **HTML template** (instead of React) for users who prefer web components over JSX. Choose between the two during project setup.
 
 ```sh
 # List available profiles (after install)
-npx forge profile.validate
+forge profile.validate
 ```
 
 When you bring an existing project through the `/forge-bootstrap` transplant mode, Forge detects the matching profile automatically by checking for marker files (`astro.config.*`, `phaser.config.*`, `editframe.config.*`, etc.).
@@ -83,13 +356,13 @@ When a new version of `@warpgogol/forge` is published, consumers upgrade additiv
 
 ```sh
 # 1. Install the latest version
-npm install @warpgogol/forge@latest
+pnpm add -g @warpgogol/forge@latest
 
 # 2. Sync skills and binding defaults from the installed version
-npx forge upgrade
+forge upgrade
 
 # 3. Check project health
-npx forge doctor
+forge doctor
 ```
 
 `forge upgrade` is additive — it never overwrites operator-set bindings, never deletes files, and is idempotent. It updates `forge.syncedVersion` in `forge.yaml` to track the last synced version. Use `--dry-run` to preview changes.

package/README.uk.md

@@ -0,0 +1,490 @@
+# @warpgogol/forge
+
+Українська | [English](README.md)
+
+Портативний рушій управління для розробки проєктів за допомогою ШІ. Надає навички, RFC/ADR робочі процеси, угоди про найменування, вендоринг специфікацій та CLI — все незалежне від фреймворку та без зайвих залежностей (тільки `yaml` + `zod`).
+
+## Що можна створити за допомогою Forge
+
+Forge підтримує чотири типи проєктів. Ви обираєте один на старті — все інше відбувається автоматично.
+
+| Тип проєкту | Що це | Приклади |
+| --- | --- | --- |
+| **Вебсайт** | Публічний сайт або вебзастосунок — сторінки, блог, портфоліо, лендінг, інтернет-магазин | Сайт фотостудії, сайт ресторану, лендінг SaaS |
+| **Браузерна гра** | Інтерактивна гра, що працює в браузері — 2D, аркада, головоломка, пригода | Лови зірки, головоломка з плитками, платформер |
+| **Відео** | Програмна відеокомпозиція — анімований логотип, інтро, презентація продукту, motion-дизайн | Брендове інтро, демо продукту, реклама для соцмереж |
+| **Управління / бібліотека** | Бібліотека коду або проєкт лише з управлінською структурою — без сайту, без гри, без відео, лише структура та документація | npm-пакет, внутрішній інструмент, центр документації |
+
+Кожен тип проєкту отримує власний каркас: правильну структуру папок, правильні залежності, правильні інструменти. Вам не потрібно знати, що це таке — Forge налаштує все за вас.
+
+---
+
+## Повний посібник зі встановлення (з нуля)
+
+Якщо ви ніколи раніше не програмували, цей розділ проведе вас від абсолютно порожнього комп'ютера до робочого налаштування Forge. Виконайте кроки для вашої операційної системи.
+
+### Що вам потрібно
+
+Потрібні дві безкоштовні програми:
+
+- **Node.js** (версія 22 або новіша) — дозволяє вашому комп'ютеру запускати JavaScript-інструменти.
+- **pnpm** — менеджер пакетів, який Forge використовує для встановлення залежностей. Він вбудований у Node.js і його лише треба увімкнути.
+
+Обидві програми безкоштовні. Спочатку встановлюєте Node.js, потім вмикаєте pnpm однією командою.
+
+### Ubuntu
+
+#### Крок 1 — Встановлення Node.js
+
+1. Відкрийте програму **Термінал** (натисніть `Ctrl + Alt + T` або знайдіть «Термінал» у ваших програмах).
+
+2. Завантажте та встановіть Node.js 22 (LTS), вставивши цю команду та натиснувши Enter:
+
+   ```sh
+   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
+   ```
+
+   Вас попросять ввести пароль — введіть його (символи не відображатимуться під час введення, це нормально) і натисніть Enter.
+
+3. Перевірте, чи все працює:
+
+   ```sh
+   node --version
+   ```
+
+   Ви маєте побачити номер версії, наприклад `v22.x.x`, а не повідомлення про помилку.
+
+#### Крок 2 — Увімкнення pnpm
+
+Node.js містить інструмент **Corepack**, який керує менеджерами пакетів. Увімкніть pnpm командою:
+
+```sh
+corepack enable pnpm
+```
+
+Перевірте:
+
+```sh
+pnpm --version
+```
+
+Ви маєте побачити номер версії, наприклад `10.x.x`.
+
+#### Крок 3 — Глобальне встановлення Forge
+
+Глобальне встановлення означає, що команда `forge` доступна скрізь на вашому комп'ютері, а не лише в одному проєкті:
+
+```sh
+pnpm add -g @warpgogol/forge
+```
+
+Перевірте:
+
+```sh
+forge --version
+```
+
+Ви маєте побачити номер версії. Forge встановлено та готовий до роботи.
+
+#### Крок 4 — Встановлення 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 — Глобальне встановлення Forge
+
+Глобальне встановлення означає, що команда `forge` доступна скрізь на вашому комп'ютері, а не лише в одному проєкті:
+
+```sh
+pnpm add -g @warpgogol/forge
+```
+
+Перевірте:
+
+```sh
+forge --version
+```
+
+Ви маєте побачити номер версії. Forge встановлено та готовий до роботи.
+
+#### Крок 4 — Встановлення IDE зі штучним інтелектом
+
+Forge працює через розмову з ШІ-агентом. Вам потрібне IDE, що підтримує ШІ-агентів. Рекомендуємо **Windsurf** (протестовано з Forge):
+
+1. Перейдіть на [windsurf.com](https://windsurf.com) та завантажте версію для Windows.
+2. Запустіть завантажений установник і дотримуйтесь майстра налаштування.
+3. Запустіть Windsurf.
+
+Можете також використовувати **Cursor** ([cursor.com](https://cursor.com)) або будь-яке IDE, що підтримує навички ШІ-агентів.
+
+### Додатково — Встановлення FFmpeg (лише для відеопроєктів)
+
+Якщо ви плануєте створювати **відеопроєкти** (профіль `editframe`), вам потрібен **FFmpeg** — безкоштовний інструмент для обробки відео та аудіо.
+
+**Ubuntu:**
+
+```sh
+sudo apt-get install -y ffmpeg
+ffmpeg -version
+```
+
+**Windows:**
+
+1. Відкрийте [ffmpeg.org/download.html](https://ffmpeg.org/download.html) у браузері.
+2. Завантажте збірку для Windows (шукайте «Windows builds» — збірки gyan.dev або BtbN — хороші варіанти).
+3. Розпакуйте завантажений `.zip` файл у папку, наприклад `C:\ffmpeg`.
+4. Додайте FFmpeg до системної змінної PATH:
+   - Відкрийте меню Пуск, знайдіть «Environment Variables» і натисніть «Edit the system environment variables».
+   - Натисніть **Environment Variables**.
+   - У розділі «System variables» (або «User variables») знайдіть **Path**, виберіть його та натисніть **Edit**.
+   - Натисніть **New** і введіть `C:\ffmpeg\bin` (або туди, куди ви розпакували FFmpeg, у підпапку `bin`).
+   - Натисніть **OK** у всіх трьох вікнах.
+5. Закрийте та знову відкрийте PowerShell, потім перевірте:
+
+   ```sh
+   ffmpeg -version
+   ```
+
+Ви маєте побачити інформацію про версію, а не помилку.
+
+### Усунення проблем
+
+- **«command not found» після встановлення Node.js** — Закрийте та знову відкрийте термінал (Ubuntu) або PowerShell (Windows). Системі потрібно перезавантажити список доступних команд.
+- **«EACCES permission denied» в Ubuntu під час глобального встановлення Forge** — Виконайте `sudo pnpm add -g @warpgogol/forge`.
+- **«corepack: command not found»** — Ваша версія Node.js занадто стара. Встановіть Node.js 22+ за кроками вище.
+- **Windsurf не бачить `forge`** — Закрийте та знову відкрийте Windsurf після встановлення Forge. IDE потрібно перезапустити, щоб підхопити нові глобальні команди.
+- **ШІ-агент не знає про Forge** — Ви відкрили порожню папку, але ШІ-агент не має контексту Forge. Спочатку виконайте `forge create my-project --profile editframe` (або відповідний профіль) у терміналі, потім відкрийте створену папку в вашому IDE. Команда `forge create` наповнює папку навичками, конфігурацією та `AGENTS.md` — без цього ШІ-агент не може виявити Forge.
+
+---
+
+## Швидкий старт
+
+### Для креативних операторів — одна команда, потім просто розмовляйте
+
+Потрібно виконати одну команду в терміналі для створення проєкту. Після цього все працює через розмову з ШІ-агентом — більше команд не потрібно.
+
+#### Створення нового проєкту з нуля
+
+1. **Створіть проєкт Forge.** Відкрийте термінал (PowerShell на Windows, Термінал на Ubuntu) і виконайте:
+
+   ```sh
+   forge create my-brand-video --profile editframe
+   ```
+
+   Замініть `my-brand-video` на назву вашого проєкту (малі літери та дефіси). Це створить нову папку з усьом, що потрібно Forge — навичками, конфігурацією та структурою проєкту. Для інших типів проєктів використовуйте інший `--profile`:
+
+   | Що ви хочете створити                        | Прапорець профілю                      |
+   | -------------------------------------------- | -------------------------------------- |
+   | Відео (брендове відео, інтро, motion-дизайн) | `--profile editframe`                  |
+   | Вебсайт (лендінг, блог, портфоліо)           | `--profile astro-typescript-turborepo` |
+   | Браузерна гра (2D, аркада, головоломка)      | `--profile phaser-turborepo`           |
+   | Бібліотека або проєкт лише з управлінням     | `--profile forge-shell`                |
+
+2. **Відкрийте папку проєкту в вашому IDE.** Відкрийте папку, створену на кроці 1, у Windsurf або вашому IDE.
+
+3. **Скажіть ШІ-агенту, що ви хочете створити.** Просто напишіть це в чаті своїми словами. Наприклад:
+
+   > Я хочу створити брендове відео для своєї кав'ярні. Воно має мати анімований логотип, коротке інтро та презентацію продукту.
+
+   Або:
+
+   > Я хочу зробити вебсайт для своєї фотостудії.
+
+   Або:
+
+   > Я хочу створити браузерну гру, де ловиш зірки, що падають.
+
+   Або:
+
+   > Я хочу створити TypeScript-бібліотеку для розрахунку астрологічних карт.
+
+   Це все. ШІ-агент зробить усе інше:
+   - Налаштує структуру проєкту залежно від того, що ви описали (відео, вебсайт, гра, бібліотека тощо)
+   - Налаштує мовні вподобання та параметри проєкту
+   - Запустить живий попередній перегляд, щоб ви бачили свою роботу (для вебсайтів, ігор та відео)
+   - Скаже вам URL для відкриття в браузері
+
+4. **Дивіться попередній перегляд.** Для вебсайтів, ігор та відео ШІ-агент дасть вам посилання localhost. Натисніть його — ваш проєкт уже запущений. Коли ви описуєте зміни, агент оновлює проєкт, а попередній перегляд оновлюється автоматично.
+
+   Для проєктів управління та бібліотек візуального попереднього перегляду немає — агент налаштує структуру проєкту та скаже, коли все готово.
+
+5. **Створюйте разом.** Далі ви просто розмовляєте. Хочете інший колір? Хочете додати сцену? Хочете змінити музику? Хочете додати нову функцію до бібліотеки? Просто скажіть. Агент виконає всю технічну роботу.
+
+#### Перенесення наявного проєкту у Forge
+
+Якщо ви вже маєте проєкт десь інше і хочете перенести його у Forge:
+
+1. **Створіть проєкт Forge.** Відкрийте термінал і виконайте:
+
+   ```sh
+   forge create my-project
+   ```
+
+   Потім відкрийте створену папку в вашому IDE.
+
+2. **Скажіть ШІ-агенту:**
+
+   > Я хочу перенести свій наявний проєкт у Forge. Він знаходиться за шляхом /path/to/my/project.
+
+   Агент:
+   - Визначить, який це тип проєкту (вебсайт, відео, гра, бібліотека тощо)
+   - Перемістить усі ваші файли у новий проєкт Forge — включно з прихованими файлами на кшталт `.env`
+   - За бажанням перенесе вашу історію git
+   - Перевірить, чи все коректно збирається
+   - Запустить живий попередній перегляд (для візуальних типів проєктів)
+
+#### Що робити, якщо щось пішло не так?
+
+Просто скажіть ШІ-агенту. Він може перевірити стан проєкту, виправити проблеми та пояснити, що сталося — все простою мовою. Вам ніколи не потрібно відкривати термінал або вводити команди самостійно.
+
+---
+
+### Для розробників — CLI-команди
+
+#### Створення нового проєкту
+
+```sh
+# Створити новий проєкт (каркас + ініціалізація + навички + AGENTS.md однією командою)
+forge create my-project
+
+# З конкретним профілем стеку
+forge create my-site --profile astro-typescript-turborepo
+forge create my-game --profile phaser-turborepo
+forge create my-video --profile editframe
+forge create my-library --profile forge-shell
+
+```
+
+Якщо Forge не встановлено глобально, використовуйте `pnpm dlx`:
+
+```sh
+pnpm dlx @warpgogol/forge create my-project
+```
+
+#### Перенесення наявного проєкту у Forge
+
+CLI-команди для перенесення немає — це інтерактивний процес під керівництвом ШІ:
+
+```sh
+# 1. Створіть новий порожній проєкт Forge
+forge create my-project
+
+# 2. Відкрийте проєкт у Windsurf (протестовано з Forge) або вашому IDE
+
+# 3. Запустіть навичку /forge-bootstrap і оберіть режим "transplant"
+#    Навичка:
+#    - Запитає шлях до вашого наявного коду
+#    - Автоматично визначить стек (Astro, Phaser, Editframe тощо)
+#    - Перенесе всі файли (включно з .env та git-ігнорованими)
+#    - За бажанням перенесе історію git
+#    - Перевірить збірку
+```
+
+#### Діагностика та перевірка
+
+```sh
+# Перевірити стан проєкту
+forge doctor
+
+# Валідувати RFC
+forge rfc.validate
+
+# Список доступних навичок
+forge skill.list
+```
+
+## Профілі стеку
+
+Профіль стеку визначає каркас проєкту: структуру директорій, залежності, конфігурацію CI та перший робочий простір. Оберіть профіль прапорцем `--profile` під час створення проєкту.
+
+| Профіль | Тип проєкту | Опис | Перший робочий простір | Призначення |
+| --- | --- | --- | --- | --- |
+| `forge-shell` | Управління / бібліотека | Мінімальний каркас Forge (за замовчуванням) | — | Проєкти лише з управлінням, бібліотеки, невеб-проєкти |
+| `astro-typescript-turborepo` | Вебсайт | Astro + TypeScript + pnpm + Turborepo | `sites/my-site` | Вебсайти, вебзастосунки, контентні сайти |
+| `phaser-turborepo` | Браузерна гра | Phaser + TypeScript + pnpm + Turborepo | `games/my-game` | Браузерні ігри, інтерактивні досвіди |
+| `editframe` | Відео | Editframe React + Vite + TailwindCSS | `compositions/my-first-video` | Відеокомпозиції, брендові відео, motion-дизайн |
+
+Профіль `editframe` також підтримує **HTML-шаблон** (замість React) для користувачів, які віддають перевагу веб-компонентам замість JSX. Оберіть між ними під час налаштування проєкту.
+
+```sh
+# Список доступних профілів (після встановлення)
+forge profile.validate
+```
+
+Коли ви переносите наявний проєкт через режим `/forge-bootstrap` transplant, Forge автоматично визначає відповідний профіль, перевіряючи файли-маркери (`astro.config.*`, `phaser.config.*`, `editframe.config.*` тощо).
+
+## Процес оновлення
+
+Коли публікується нова версія `@warpgogol/forge`, споживачі оновлюються адитивно:
+
+```sh
+# 1. Встановити останню версію
+pnpm add -g @warpgogol/forge@latest
+
+# 2. Синхронізувати навички та стандартні прив'язки з встановленої версії
+forge upgrade
+
+# 3. Перевірити стан проєкту
+forge doctor
+```
+
+`forge upgrade` — адитивний: він ніколи не перезаписує прив'язки, встановлені оператором, ніколи не видаляє файли та є ідемпотентним. Він оновлює `forge.syncedVersion` у `forge.yaml`, щоб відстежувати останню синхронізовану версію. Використовуйте `--dry-run` для попереднього перегляду змін.
+
+## Що дає Forge
+
+- **44 навички** (fo-pipeline, grilling, preferences, написання навичок, Editframe відеокомпозиція) — розгортаються у `.agents/skills/` командою `forge create`
+- **RFC робочий процес** — створення, валідація, список, граф, архівування, acceptance-зондування, журнали рішень, DNA-трасування
+- **ADR робочий процес** — легковісні архітектурні записи рішень
+- **Вендоринг специфікацій** — вендоринг зовнішніх пакетів специфікацій як незмінних знімків з маніфестами цілісності
+- **Угоди про найменування** — linting kebab-case
+- **Linting робочих процесів** — валідація frontmatter та посилань у `.agents/workflows/`
+- **Каркаси стеків** — створення нового pnpm + Turborepo монорепозиторію з профілю
+- **Контракт прив'язок** — декодування специфічних для проєкту команд/шляхів із навичок через `forge.yaml`
+
+## Життєвий цикл
+
+Типовий життєвий цикл проєкту Forge:
+
+1. **Створення** — `forge create` ініціалізує новий проєкт з forge.yaml, навичками та директоріями документації
+2. **IDE** — відкрийте проєкт у Windsurf (протестовано з Forge) або вашому IDE
+3. **Bootstrap** — запустіть `/forge-bootstrap` для інтерактивного налаштування проєкту. Навичка підтримує два режими:
+   - **Greenfield** — створення нового проєкту з нуля: оберіть стек, заповніть прив'язки, ініціалізуйте git
+   - **Transplant** — перенесення наявного коду у Forge: визначення стеку, міграція коду (включно з git-ігнорованими файлами на кшталт `.env`), за бажанням перенесення історії git, перевірка збірки
+4. **Оновлення** — коли публікується нова версія `@warpgogol/forge`, запустіть `forge upgrade` для адитивної синхронізації навичок та стандартних прив'язок
+
+## forge.yaml
+
+Єдине джерело істини для конфігурації проєкту. Створюється командою `forge create`:
+
+```yaml
+schema: forge/config@1
+project:
+  name: my-project
+  stack: [typescript]
+  packageManager: pnpm
+paths:
+  rfcsDir: docs/rfcs
+  adrsDir: docs/adrs
+  skillsDir: .agents/skills
+bindings:
+  schema: forge/bindings@1
+  commands:
+    validateRfc: "forge rfc.validate {id} --json"
+    typecheck: "pnpm run build:check"
+    test: "pnpm test"
+  paths:
+    invariantsFile: docs/architecture-dna.md
+  terminology:
+    invariants: DNA
+```
+
+## Програмний API
+
+```ts
+import {
+  forgeCoreModule,
+  forgeRfcModule,
+  loadForgeConfig,
+  resolveBinding,
+  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);
+```
+
+## Архітектура
+
+| Директорія | Призначення |
+| --- | --- |
+| `src/` | Портативне ядро — типи, конфігурація, реєстр навичок, валідатори, онбординг. Нуль імпортів `@warpgogol/*`. |
+| `os/` | Реєстрації ForgeModule. `compass` та `werkstatt` динамічно імпортують `@warpgogol/site-kernel-*` (м'яка деградація в автономному режимі). |
+| `bin/` | Точка входу CLI (команда `forge`). |
+| `skills/` | 44 визначення навичок (36 fo + 5 спільних + 3 мета) з frontmatter SKILL.md. |
+| `scripts/` | Перевірка гігієни публікації (`publish-check.mjs`), запускається `prepublishOnly`. |
+| `profiles/` | Профілі стеків для `forge.scaffold`. |
+
+## Публікація в npm
+
+Цей пакет публікується в реєстр 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
+
+# 2. Зберегти auth-токен для реєстру (використайте токен з попереднього кроку)
+npm config set //registry.npmjs.org/:_authToken=<TOKEN>
+
+# 3. Підняти patch-версію (оновлює package.json + створює git commit + tag)
+npm version patch
+
+# 4. Опублікувати пакет публічно
+npm publish --access public
+```
+
+Після публікації перевірте нову версію на [npmjs.com/package/@warpgogol/forge](https://www.npmjs.com/package/@warpgogol/forge).
+
+## Ліцензія
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",