@warpgogol/forge 1.2.2 → 2.2.0

package/AGENTS.md

@@ -70,6 +70,7 @@ Skills live in `skills/` and are synced to `.agents/skills/` by `create`. Each s
 - **When editing a skill in `packages/forge/skills/`**, the synced copy in `.agents/skills/<name>/SKILL.md` MUST also be committed in the same session — `create` is not run automatically after manual edits. Stale `.agents/skills/` copies cause `doctor` to report drift.
 - **Canonical sync path is flat**: `.agents/skills/<name>/SKILL.md` (e.g. `.agents/skills/fo-idea-implement/SKILL.md`). Both `create` (`init.ts`) and `upgrade` (`upgrade.ts`) sync to this flat path. A nested `.agents/skills/fo/<name>/SKILL.md` path is NOT created or maintained by forge — it is a stale artifact if present and should be removed.
 - **`FORGE_SKILLS[].path` is relative to the forge package root** and already includes the `skills/` prefix — resolve via `path.join(forgeRoot, skill.path)` (see `init.ts`). Never join a `skillsRoot` with `skill.path`: that produces a doubled `skills/skills/` prefix and silently finds nothing.
+- **When renumbering steps in SKILL.md files** (inserting or removing a numbered step), grep for hard-coded step numbers across all `.md` files in the repo. Cross-references to `fo-idea-implement` step numbers exist in `PREFERENCES.md`, `fo-doc-audit/SKILL.md`, and `fo-session-retro/SKILL.md` — these break silently when steps shift. Always update all cross-references in the same commit.
 
 The `concerns` field uses a four-level taxonomy (RFC-0523): `read-only` (no file modifications), `document-only` (modifies `.md` files only), `content-mutation` (modifies content `.md`/`.yaml` but not executable code), `code-mutation` (modifies `.ts`/`.astro` code). `skill.validate` enforces this via SKILL-12.
 
@@ -151,7 +152,7 @@ Stack profiles are YAML documents under `profiles/` describing a supported stack
 - **MUST NOT** scaffold into a non-empty directory — no `--force` flag.
 - **MUST NOT** add stack profiles for stacks forge cannot scaffold end-to-end.
 - **MUST** reference all template files in `profiles/<profile>-templates/` from the profile YAML (`workspaceTypes[].agentsMdTemplate` or `firstWorkspace.files`) or document them in the `agentsMdTemplate` file. Unreferenced template files are orphan artifacts that operators cannot discover.
-- Shipped profiles: `astro-typescript-turborepo`, `phaser-turborepo`, `godot-csharp`, `forge-shell` (minimal — default for `create`).
+- Shipped profiles: `phaser-turborepo`, `godot-csharp`, `forge-shell` (minimal — default for `create`).
 - **MUST** include a `.github/workflows/ci.yml` template in every stack profile's `workspace.files` list. The CI template MUST include `concurrency` (cancel superseded PR runs), `permissions: contents: read` at workflow level, `timeout-minutes` per job, `env: TZ: UTC` per job, `actions/checkout@v5`, and `actions/setup-node@v5` with Node 24. New projects inherit reliable CI from the scaffold — operators should not need to hand-write CI from scratch.
 
 ### Domain fields (RFC-0638)

package/README.md

@@ -6,11 +6,10 @@ Portable governance engine for AI-assisted project development. Provides skills,
 
 ## What you can build with Forge
 
-Forge supports four kinds of projects. You pick one when you start — everything else is automatic.
+Forge supports three 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 |
 | **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 |
 | **Godot game** | A desktop or mobile game built with Godot 4.x and C# — 2D, 3D, platformer, RPG | Top-down adventure, 3D platformer, puzzle game |
@@ -29,21 +28,17 @@ For full project lifecycle management — missions, releases, deployment, certif
 | --- | --- | --- |
 | `@warpgogol/werkstatt` | Runtime engine — missions, releases, Leitstand deployment, certification, Bordbuch, artifact store | All project types with lifecycle management |
 | `@warpgogol/werkstatt-shared` | Shared infrastructure — checks, integration, ontology, passport | Installed automatically with the engine |
-| `@warpgogol/werkstatt-site` | Astro site plugin — build pipeline, content checks, codegen, deploy adapters | Website projects (`astro-typescript-turborepo`) |
 | `@warpgogol/werkstatt-game` | Phaser game plugin — game validators, Vite build, deploy adapters | Browser game projects (`phaser-turborepo`) |
 | `@warpgogol/werkstatt-godot` | Godot plugin — scene validators, dotnet build, itch.io deploy, Godot skills | Godot game projects (`godot-csharp`) |
 
 ### When you need these packages
 
 - **Governance-only projects** (RFCs, ADRs, skills, documentation hubs) — Forge alone is sufficient.
-- **Websites, games, Godot projects** — install `@warpgogol/werkstatt` (the engine) plus the matching stack plugin. The `forge-bootstrap` skill configures bindings automatically; the packages themselves must be installed as devDependencies.
+- **Games, Godot projects** — install `@warpgogol/werkstatt` (the engine) plus the matching stack plugin. The `forge-bootstrap` skill configures bindings automatically; the packages themselves must be installed as devDependencies.
 
 ### Installing engine packages
 
 ```sh
-# Website project
-pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-site
-
 # Browser game project
 pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-game
 
@@ -106,23 +101,7 @@ 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
+#### Step 3 — 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):
 
@@ -164,23 +143,7 @@ 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
+#### Step 3 — 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):
 
@@ -207,10 +170,8 @@ dotnet --version
 ### 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 24+ 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 --name my-project --profile astro-typescript-turborepo` (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.
+- **AI agent doesn't know about Forge** — You opened an empty folder, but the AI agent has no Forge context. Run `pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo` (or the appropriate profile) in a terminal first, then open the folder in your IDE. The `forge create` command populates the current folder with skills, configuration, and `AGENTS.md` — without it, the AI agent can't discover Forge.
 
 ---
 
@@ -222,26 +183,27 @@ You need to run one command in the terminal to create your project. After that,
 
 #### Start a new project from scratch
 
-1. **Create a Forge project.** Open a terminal (PowerShell on Windows, Terminal on Ubuntu) and run:
+1. **Create a project folder and scaffold Forge in-place.** Open a terminal (PowerShell on Windows, Terminal on Ubuntu) and run:
 
    ```sh
-   forge create --name my-site --profile astro-typescript-turborepo
+   mkdir my-game
+   cd my-game
+   pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo
    ```
 
-   Replace `my-site` 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`:
+   The project name is derived from the folder name (`my-game` in this example). You can override it with `--name`. This populates the current 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                           |
-   | --------------------------------------- | -------------------------------------- |
-   | Website (landing page, blog, portfolio) | `--profile astro-typescript-turborepo` |
-   | Browser game (2D, arcade, puzzle)       | `--profile phaser-turborepo`           |
-   | Godot game (desktop, mobile, 2D/3D)     | `--profile godot-csharp`               |
-   | Library or governance-only project      | `--profile forge-shell`                |
+   | What you want to build              | Profile flag                 |
+   | ----------------------------------- | ---------------------------- |
+   | Browser game (2D, arcade, puzzle)   | `--profile phaser-turborepo` |
+   | Godot game (desktop, mobile, 2D/3D) | `--profile godot-csharp`     |
+   | 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.
+2. **Open the project folder in your AI IDE.** Open the folder from 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 build a website for my photography studio.
+   > I want to build a Godot game where you catch falling stars.
 
    Or:
 
@@ -252,12 +214,12 @@ You need to run one command in the terminal to create your project. After that,
    > 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 (website, game, library, etc.)
+   - Set up the project structure based on what you described (game, library, etc.)
    - Configure language preferences and project settings
-   - Start a live preview so you can see your work (for websites and games)
+   - Start a live preview so you can see your work (for games)
    - Tell you the URL to open in your browser
 
-4. **Watch the preview.** For websites and games, 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.
+4. **Watch the preview.** For games, 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.
 
@@ -267,20 +229,22 @@ You need to run one command in the terminal to create your project. After that,
 
 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:
+1. **Create a Forge project.** Open a terminal, create a folder, and run:
 
    ```sh
-   forge create --name my-project
+   mkdir my-project
+   cd my-project
+   pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
    ```
 
-   Then open the created folder in your AI IDE.
+   Then open the 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, game, library, etc.)
+   - Detect what kind of project it is (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
@@ -294,40 +258,43 @@ Just tell the AI agent. It can check the project's health, fix issues, and expla
 
 ### For developers — CLI commands
 
-#### Create a new project
+#### Create a new project (in-place)
 
 ```sh
-# Create a new project (scaffold + init + skills + AGENTS.md in one command)
-forge create --name my-project
+# Create a project folder, then scaffold Forge in-place
+# pnpm dlx downloads Forge temporarily — no global install needed
+mkdir my-project
+cd my-project
+pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
 
 # With a specific stack profile
-forge create --name my-site --profile astro-typescript-turborepo
-forge create --name my-game --profile phaser-turborepo
-forge create --name my-godot-game --profile godot-csharp
-forge create --name my-library --profile forge-shell
-
-```
+mkdir my-game && cd my-game
+pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo
 
-If Forge is not installed globally, use `pnpm dlx` instead:
+mkdir my-godot-game && cd my-godot-game
+pnpm dlx @warpgogol/forge create --in-place --profile godot-csharp
 
-```sh
-pnpm dlx @warpgogol/forge create --name my-project
+# Override the project name (derived from folder name by default)
+pnpm dlx @warpgogol/forge create --in-place --profile forge-shell --name my-custom-name
 ```
 
+After scaffolding, Forge is installed as a local devDependency. Use `pnpm exec forge` for all subsequent commands within the 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
-forge create --name my-project
+# 1. Create a new empty Forge project (in-place)
+mkdir my-project && cd my-project
+pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
 
 # 2. Open the project in Windsurf (tested with forge) or your preferred IDE
 
 # 3. Run the /forge-bootstrap skill and choose "transplant" mode
 #    The skill will:
 #    - Ask for the path to your existing codebase
-#    - Detect the stack automatically (Astro, Phaser, Godot, etc.)
+#    - Detect the stack automatically (Phaser, Godot, etc.)
 #    - Migrate all files (including .env and git-ignored files)
 #    - Optionally transfer git history
 #    - Verify the build
@@ -337,13 +304,13 @@ forge create --name my-project
 
 ```sh
 # Check project health
-forge doctor
+pnpm exec forge doctor
 
 # Validate RFCs
-forge rfc.validate
+pnpm exec forge rfc.validate
 
 # List available skills
-forge skill.list
+pnpm exec forge skill.list
 ```
 
 ## Stack profiles
@@ -353,30 +320,29 @@ A stack profile defines the project scaffold: directory structure, dependencies,
 | 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 |
 | `godot-csharp` | Godot game | Godot 4.x + C# + pnpm + Turborepo | `games/my-game` | Desktop/mobile games, Godot-based interactive projects |
 
 ```sh
 # List available profiles (after install)
-forge profile.validate
+pnpm exec 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.*`, `project.godot`, etc.).
+When you bring an existing project through the `/forge-bootstrap` transplant mode, Forge detects the matching profile automatically by checking for marker files (`phaser.config.*`, `project.godot`, etc.).
 
 ## Upgrade flow
 
 When a new version of `@warpgogol/forge` is published, consumers upgrade additively:
 
 ```sh
-# 1. Install the latest version
-pnpm add -g @warpgogol/forge@latest
+# 1. Update Forge to the latest version (local devDependency)
+pnpm update @warpgogol/forge
 
 # 2. Sync skills and binding defaults from the installed version
-forge upgrade
+pnpm exec forge upgrade
 
 # 3. Check project health
-forge doctor
+pnpm exec 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.
@@ -396,12 +362,12 @@ forge doctor
 
 The typical forge project lifecycle:
 
-1. **Create** — `forge create` bootstraps a new project with forge.yaml, skills, and docs directories
+1. **Create** — `pnpm dlx @warpgogol/forge create --in-place --profile <profile>` scaffolds a new project in the current directory with forge.yaml, skills, and docs directories
 2. **IDE** — open the project in Windsurf (tested with forge) or your preferred IDE
 3. **Bootstrap** — run `/forge-bootstrap` to configure the project interactively. The skill supports two modes:
    - **Greenfield** — start a new project from scratch: pick a stack, fill in bindings, init git
    - **Transplant** — bring an existing codebase into Forge: detect the stack, migrate code (including git-ignored files like `.env`), optionally transfer git history, verify the build
-4. **Upgrade** — when a new `@warpgogol/forge` version is published, run `forge upgrade` to sync skills and binding defaults additively
+4. **Upgrade** — when a new `@warpgogol/forge` version is published, run `pnpm exec forge upgrade` to sync skills and binding defaults additively
 
 ## forge.yaml
 

package/README.uk.md

@@ -6,11 +6,10 @@
 
 ## Що можна створити за допомогою Forge
 
-Forge підтримує чотири типи проєктів. Ви обираєте один на старті — все інше відбувається автоматично.
+Forge підтримує три типи проєктів. Ви обираєте один на старті — все інше відбувається автоматично.
 
 | Тип проєкту | Що це | Приклади |
 | --- | --- | --- |
-| **Вебсайт** | Публічний сайт або вебзастосунок — сторінки, блог, портфоліо, лендінг, інтернет-магазин | Сайт фотостудії, сайт ресторану, лендінг SaaS |
 | **Браузерна гра** | Інтерактивна гра, що працює в браузері — 2D, аркада, головоломка, пригода | Лови зірки, головоломка з плитками, платформер |
 | **Управління / бібліотека** | Бібліотека коду або проєкт лише з управлінською структурою — без сайту, без гри, без відео, лише структура та документація | npm-пакет, внутрішній інструмент, центр документації |
 | **Гра Godot** | Десктопна або мобільна гра на Godot 4.x з C# — 2D, 3D, платформер, RPG | Пригода з виглядом зверху, 3D-платформер, головоломка |
@@ -29,21 +28,17 @@ Forge — це **шар управління**: навички, RFC/ADR робо
 | --- | --- | --- |
 | `@warpgogol/werkstatt` | Рушій runtime — місії, релізи, розгортання Leitstand, сертифікація, Bordbuch, сховище артефактів | Усі типи проєктів з управлінням життєвим циклом |
 | `@warpgogol/werkstatt-shared` | Спільна інфраструктура — перевірки, інтеграція, онтологія, паспорт | Встановлюється автоматично з рушієм |
-| `@warpgogol/werkstatt-site` | Плагін Astro-сайту — конвеєр збірки, перевірки контенту, codegen, адаптери розгортання | Вебсайт-проєкти (`astro-typescript-turborepo`) |
 | `@warpgogol/werkstatt-game` | Плагін Phaser-гри — валідатори гри, збірка Vite, адаптери розгортання | Проєкти браузерних ігор (`phaser-turborepo`) |
 | `@warpgogol/werkstatt-godot` | Плагін Godot — валідатори сцен, збірка dotnet, розгортання itch.io, навички Godot | Проєкти ігор Godot (`godot-csharp`) |
 
 ### Коли потрібні ці пакети
 
 - **Проєкти лише з управлінням** (RFC, ADR, навички, центри документації) — Forge сам по собі достатній.
-- **Вебсайти, ігри, проєкти Godot** — встановіть `@warpgogol/werkstatt` (рушій) плюс відповідний плагін стеку. Навичка `forge-bootstrap` налаштовує прив'язки автоматично; самі пакети потрібно встановити як devDependencies.
+- **Ігри, проєкти Godot** — встановіть `@warpgogol/werkstatt` (рушій) плюс відповідний плагін стеку. Навичка `forge-bootstrap` налаштовує прив'язки автоматично; самі пакети потрібно встановити як devDependencies.
 
 ### Встановлення пакунків рушія
 
 ```sh
-# Проєкт вебсайту
-pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-site
-
 # Проєкт браузерної гри
 pnpm add -D @warpgogol/werkstatt @warpgogol/werkstatt-game
 
@@ -106,23 +101,7 @@ pnpm --version
 
 Ви маєте побачити номер версії, наприклад `10.x.x`.
 
-#### Крок 3 — Глобальне встановлення Forge
-
-Глобальне встановлення означає, що команда `forge` доступна скрізь на вашому комп'ютері, а не лише в одному проєкті:
-
-```sh
-pnpm add -g @warpgogol/forge
-```
-
-Перевірте:
-
-```sh
-forge --version
-```
-
-Ви маєте побачити номер версії. Forge встановлено та готовий до роботи.
-
-#### Крок 4 — Встановлення IDE зі штучним інтелектом
+#### Крок 3 — Встановлення IDE зі штучним інтелектом
 
 Forge працює через розмову з ШІ-агентом. Вам потрібне IDE, що підтримує ШІ-агентів. Рекомендуємо **Windsurf** (протестовано з Forge):
 
@@ -164,23 +143,7 @@ pnpm --version
 
 Ви маєте побачити номер версії, наприклад `10.x.x`.
 
-#### Крок 3 — Глобальне встановлення Forge
-
-Глобальне встановлення означає, що команда `forge` доступна скрізь на вашому комп'ютері, а не лише в одному проєкті:
-
-```sh
-pnpm add -g @warpgogol/forge
-```
-
-Перевірте:
-
-```sh
-forge --version
-```
-
-Ви маєте побачити номер версії. Forge встановлено та готовий до роботи.
-
-#### Крок 4 — Встановлення IDE зі штучним інтелектом
+#### Крок 3 — Встановлення IDE зі штучним інтелектом
 
 Forge працює через розмову з ШІ-агентом. Вам потрібне IDE, що підтримує ШІ-агентів. Рекомендуємо **Windsurf** (протестовано з Forge):
 
@@ -207,10 +170,8 @@ dotnet --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 24+ за кроками вище.
-- **Windsurf не бачить `forge`** — Закрийте та знову відкрийте Windsurf після встановлення Forge. IDE потрібно перезапустити, щоб підхопити нові глобальні команди.
-- **ШІ-агент не знає про Forge** — Ви відкрили порожню папку, але ШІ-агент не має контексту Forge. Спочатку виконайте `forge create --name my-project --profile astro-typescript-turborepo` (або відповідний профіль) у терміналі, потім відкрийте створену папку в вашому IDE. Команда `forge create` наповнює папку навичками, конфігурацією та `AGENTS.md` — без цього ШІ-агент не може виявити Forge.
+- **ШІ-агент не знає про Forge** — Ви відкрили порожню папку, але ШІ-агент не має контексту Forge. Спочатку виконайте `pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo` (або відповідний профіль) у терміналі, потім відкрийте папку в вашому IDE. Команда `forge create` наповнює поточну папку навичками, конфігурацією та `AGENTS.md` — без цього ШІ-агент не може виявити Forge.
 
 ---
 
@@ -222,26 +183,27 @@ dotnet --version
 
 #### Створення нового проєкту з нуля
 
-1. **Створіть проєкт Forge.** Відкрийте термінал (PowerShell на Windows, Термінал на Ubuntu) і виконайте:
+1. **Створіть папку проєкту та згенеруйте каркас Forge на місці.** Відкрийте термінал (PowerShell на Windows, Термінал на Ubuntu) і виконайте:
 
    ```sh
-   forge create --name my-site --profile astro-typescript-turborepo
+   mkdir my-game
+   cd my-game
+   pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo
    ```
 
-   Замініть `my-site` на назву вашого проєкту (малі літери та дефіси). Це створить нову папку з усьом, що потрібно Forge — навичками, конфігурацією та структурою проєкту. Для інших типів проєктів використовуйте інший `--profile`:
+   Назва проєкту визначається з назви папки (`my-game` у цьому прикладі). Ви можете перевизначити її прапорцем `--name`. Це наповнює поточну папку усьом, що потрібно Forge — навичками, конфігурацією та структурою проєкту. Для інших типів проєктів використовуйте інший `--profile`:
 
-   | Що ви хочете створити                    | Прапорець профілю                      |
-   | ---------------------------------------- | -------------------------------------- |
-   | Вебсайт (лендінг, блог, портфоліо)       | `--profile astro-typescript-turborepo` |
-   | Браузерна гра (2D, аркада, головоломка)  | `--profile phaser-turborepo`           |
-   | Гра Godot (десктоп, мобільний, 2D/3D)    | `--profile godot-csharp`               |
-   | Бібліотека або проєкт лише з управлінням | `--profile forge-shell`                |
+   | Що ви хочете створити                    | Прапорець профілю            |
+   | ---------------------------------------- | ---------------------------- |
+   | Браузерна гра (2D, аркада, головоломка)  | `--profile phaser-turborepo` |
+   | Гра Godot (десктоп, мобільний, 2D/3D)    | `--profile godot-csharp`     |
+   | Бібліотека або проєкт лише з управлінням | `--profile forge-shell`      |
 
-2. **Відкрийте папку проєкту в вашому IDE.** Відкрийте папку, створену на кроці 1, у Windsurf або вашому IDE.
+2. **Відкрийте папку проєкту в вашому IDE.** Відкрийте папку з кроку 1 у Windsurf або вашому IDE.
 
 3. **Скажіть ШІ-агенту, що ви хочете створити.** Просто напишіть це в чаті своїми словами. Наприклад:
 
-   > Я хочу зробити вебсайт для своєї фотостудії.
+   > Я хочу зробити гру на Godot, де ловиш зірки, що падають.
 
    Або:
 
@@ -252,12 +214,12 @@ dotnet --version
    > Я хочу створити TypeScript-бібліотеку для розрахунку астрологічних карт.
 
    Це все. ШІ-агент зробить усе інше:
-   - Налаштує структуру проєкту залежно від того, що ви описали (вебсайт, гра, бібліотека тощо)
+   - Налаштує структуру проєкту залежно від того, що ви описали (гра, бібліотека тощо)
    - Налаштує мовні вподобання та параметри проєкту
-   - Запустить живий попередній перегляд, щоб ви бачили свою роботу (для вебсайтів та ігор)
+   - Запустить живий попередній перегляд, щоб ви бачили свою роботу (для ігор)
    - Скаже вам URL для відкриття в браузері
 
-4. **Дивіться попередній перегляд.** Для вебсайтів та ігор ШІ-агент дасть вам посилання localhost. Натисніть його — ваш проєкт уже запущений. Коли ви описуєте зміни, агент оновлює проєкт, а попередній перегляд оновлюється автоматично.
+4. **Дивіться попередній перегляд.** Для ігор ШІ-агент дасть вам посилання localhost. Натисніть його — ваш проєкт уже запущений. Коли ви описуєте зміни, агент оновлює проєкт, а попередній перегляд оновлюється автоматично.
 
    Для проєктів управління та бібліотек візуального попереднього перегляду немає — агент налаштує структуру проєкту та скаже, коли все готово.
 
@@ -267,20 +229,22 @@ dotnet --version
 
 Якщо ви вже маєте проєкт десь інше і хочете перенести його у Forge:
 
-1. **Створіть проєкт Forge.** Відкрийте термінал і виконайте:
+1. **Створіть проєкт Forge.** Відкрийте термінал, створіть папку і виконайте:
 
    ```sh
-   forge create --name my-project
+   mkdir my-project
+   cd my-project
+   pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
    ```
 
-   Потім відкрийте створену папку в вашому IDE.
+   Потім відкрийте папку в вашому IDE.
 
 2. **Скажіть ШІ-агенту:**
 
    > Я хочу перенести свій наявний проєкт у Forge. Він знаходиться за шляхом /path/to/my/project.
 
    Агент:
-   - Визначить, який це тип проєкту (вебсайт, гра, бібліотека тощо)
+   - Визначить, який це тип проєкту (гра, бібліотека тощо)
    - Перемістить усі ваші файли у новий проєкт Forge — включно з прихованими файлами на кшталт `.env`
    - За бажанням перенесе вашу історію git
    - Перевірить, чи все коректно збирається
@@ -294,40 +258,43 @@ dotnet --version
 
 ### Для розробників — CLI-команди
 
-#### Створення нового проєкту
+#### Створення нового проєкту (на місці)
 
 ```sh
-# Створити новий проєкт (каркас + ініціалізація + навички + AGENTS.md однією командою)
-forge create --name my-project
+# Створіть папку проєкту, потім згенеруйте каркас Forge на місці
+# pnpm dlx завантажує Forge тимчасово — глобальне встановлення не потрібне
+mkdir my-project
+cd my-project
+pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
 
 # З конкретним профілем стеку
-forge create --name my-site --profile astro-typescript-turborepo
-forge create --name my-game --profile phaser-turborepo
-forge create --name my-godot-game --profile godot-csharp
-forge create --name my-library --profile forge-shell
-
-```
+mkdir my-game && cd my-game
+pnpm dlx @warpgogol/forge create --in-place --profile phaser-turborepo
 
-Якщо Forge не встановлено глобально, використовуйте `pnpm dlx`:
+mkdir my-godot-game && cd my-godot-game
+pnpm dlx @warpgogol/forge create --in-place --profile godot-csharp
 
-```sh
-pnpm dlx @warpgogol/forge create --name my-project
+# Перевизначити назву проєкту (за замовчуванням визначається з назви папки)
+pnpm dlx @warpgogol/forge create --in-place --profile forge-shell --name my-custom-name
 ```
 
+Після створення каркаса Forge встановлюється як локальна devDependency. Використовуйте `pnpm exec forge` для всіх наступних команд у проєкті:
+
 #### Перенесення наявного проєкту у Forge
 
 CLI-команди для перенесення немає — це інтерактивний процес під керівництвом ШІ:
 
 ```sh
-# 1. Створіть новий порожній проєкт Forge
-forge create --name my-project
+# 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"
 #    Навичка:
 #    - Запитає шлях до вашого наявного коду
-#    - Автоматично визначить стек (Astro, Phaser, Godot тощо)
+#    - Автоматично визначить стек (Phaser, Godot тощо)
 #    - Перенесе всі файли (включно з .env та git-ігнорованими)
 #    - За бажанням перенесе історію git
 #    - Перевірить збірку
@@ -337,13 +304,13 @@ forge create --name my-project
 
 ```sh
 # Перевірити стан проєкту
-forge doctor
+pnpm exec forge doctor
 
 # Валідувати RFC
-forge rfc.validate
+pnpm exec forge rfc.validate
 
 # Список доступних навичок
-forge skill.list
+pnpm exec forge skill.list
 ```
 
 ## Профілі стеку
@@ -353,30 +320,29 @@ forge skill.list
 | Профіль | Тип проєкту | Опис | Перший робочий простір | Призначення |
 | --- | --- | --- | --- | --- |
 | `forge-shell` | Управління / бібліотека | Мінімальний каркас Forge (за замовчуванням) | — | Проєкти лише з управлінням, бібліотеки, невеб-проєкти |
-| `astro-typescript-turborepo` | Вебсайт | Astro + TypeScript + pnpm + Turborepo | `sites/my-site` | Вебсайти, вебзастосунки, контентні сайти |
 | `phaser-turborepo` | Браузерна гра | Phaser + TypeScript + pnpm + Turborepo | `games/my-game` | Браузерні ігри, інтерактивні досвіди |
 | `godot-csharp` | Гра Godot | Godot 4.x + C# + pnpm + Turborepo | `games/my-game` | Десктопні/мобільні ігри, інтерактивні проєкти на Godot |
 
 ```sh
 # Список доступних профілів (після встановлення)
-forge profile.validate
+pnpm exec forge profile.validate
 ```
 
-Коли ви переносите наявний проєкт через режим `/forge-bootstrap` transplant, Forge автоматично визначає відповідний профіль, перевіряючи файли-маркери (`astro.config.*`, `phaser.config.*`, `project.godot` тощо).
+Коли ви переносите наявний проєкт через режим `/forge-bootstrap` transplant, Forge автоматично визначає відповідний профіль, перевіряючи файли-маркери (`phaser.config.*`, `project.godot` тощо).
 
 ## Процес оновлення
 
 Коли публікується нова версія `@warpgogol/forge`, споживачі оновлюються адитивно:
 
 ```sh
-# 1. Встановити останню версію
-pnpm add -g @warpgogol/forge@latest
+# 1. Оновити Forge до останньої версії (локальна devDependency)
+pnpm update @warpgogol/forge
 
 # 2. Синхронізувати навички та стандартні прив'язки з встановленої версії
-forge upgrade
+pnpm exec forge upgrade
 
 # 3. Перевірити стан проєкту
-forge doctor
+pnpm exec forge doctor
 ```
 
 `forge upgrade` — адитивний: він ніколи не перезаписує прив'язки, встановлені оператором, ніколи не видаляє файли та є ідемпотентним. Він оновлює `forge.syncedVersion` у `forge.yaml`, щоб відстежувати останню синхронізовану версію. Використовуйте `--dry-run` для попереднього перегляду змін.
@@ -396,12 +362,12 @@ forge doctor
 
 Типовий життєвий цикл проєкту Forge:
 
-1. **Створення** — `forge create` ініціалізує новий проєкт з forge.yaml, навичками та директоріями документації
+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`, запустіть `forge upgrade` для адитивної синхронізації навичок та стандартних прив'язок
+4. **Оновлення** — коли публікується нова версія `@warpgogol/forge`, запустіть `pnpm exec forge upgrade` для адитивної синхронізації навичок та стандартних прив'язок
 
 ## forge.yaml