@warpgogol/forge 1.2.2 → 2.1.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.
 

package/README.md

@@ -210,7 +210,7 @@ dotnet --version
 - **"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 `forge create --in-place --profile astro-typescript-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,13 +222,15 @@ 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-site
+   cd my-site
+   forge create --in-place --profile astro-typescript-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-site` 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                           |
    | --------------------------------------- | -------------------------------------- |
@@ -237,7 +239,7 @@ You need to run one command in the terminal to create your project. After that,
    | 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:
 
@@ -267,13 +269,15 @@ 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
+   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:**
 
@@ -294,24 +298,33 @@ 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
+mkdir my-project
+cd my-project
+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-site && cd my-site
+forge create --in-place --profile astro-typescript-turborepo
 
+mkdir my-game && cd my-game
+forge create --in-place --profile phaser-turborepo
+
+mkdir my-godot-game && cd my-godot-game
+forge create --in-place --profile godot-csharp
+
+# Override the project name (derived from folder name by default)
+forge create --in-place --profile forge-shell --name my-custom-name
 ```
 
 If Forge is not installed globally, use `pnpm dlx` instead:
 
 ```sh
-pnpm dlx @warpgogol/forge create --name my-project
+mkdir my-project && cd my-project
+pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
 ```
 
 #### Bring an existing project into Forge
@@ -319,8 +332,9 @@ pnpm dlx @warpgogol/forge create --name my-project
 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
+forge create --in-place --profile forge-shell
 
 # 2. Open the project in Windsurf (tested with forge) or your preferred IDE
 
@@ -396,7 +410,7 @@ forge doctor
 
 The typical forge project lifecycle:
 
-1. **Create** — `forge create` bootstraps a new project with forge.yaml, skills, and docs directories
+1. **Create** — `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

package/README.uk.md

@@ -210,7 +210,7 @@ dotnet --version
 - **«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. Спочатку виконайте `forge create --in-place --profile astro-typescript-turborepo` (або відповідний профіль) у терміналі, потім відкрийте папку в вашому IDE. Команда `forge create` наповнює поточну папку навичками, конфігурацією та `AGENTS.md` — без цього ШІ-агент не може виявити Forge.
 
 ---
 
@@ -222,13 +222,15 @@ dotnet --version
 
 #### Створення нового проєкту з нуля
 
-1. **Створіть проєкт Forge.** Відкрийте термінал (PowerShell на Windows, Термінал на Ubuntu) і виконайте:
+1. **Створіть папку проєкту та згенеруйте каркас Forge на місці.** Відкрийте термінал (PowerShell на Windows, Термінал на Ubuntu) і виконайте:
 
    ```sh
-   forge create --name my-site --profile astro-typescript-turborepo
+   mkdir my-site
+   cd my-site
+   forge create --in-place --profile astro-typescript-turborepo
    ```
 
-   Замініть `my-site` на назву вашого проєкту (малі літери та дефіси). Це створить нову папку з усьом, що потрібно Forge — навичками, конфігурацією та структурою проєкту. Для інших типів проєктів використовуйте інший `--profile`:
+   Назва проєкту визначається з назви папки (`my-site` у цьому прикладі). Ви можете перевизначити її прапорцем `--name`. Це наповнює поточну папку усьом, що потрібно Forge — навичками, конфігурацією та структурою проєкту. Для інших типів проєктів використовуйте інший `--profile`:
 
    | Що ви хочете створити                    | Прапорець профілю                      |
    | ---------------------------------------- | -------------------------------------- |
@@ -237,7 +239,7 @@ dotnet --version
    | Гра Godot (десктоп, мобільний, 2D/3D)    | `--profile godot-csharp`               |
    | Бібліотека або проєкт лише з управлінням | `--profile forge-shell`                |
 
-2. **Відкрийте папку проєкту в вашому IDE.** Відкрийте папку, створену на кроці 1, у Windsurf або вашому IDE.
+2. **Відкрийте папку проєкту в вашому IDE.** Відкрийте папку з кроку 1 у Windsurf або вашому IDE.
 
 3. **Скажіть ШІ-агенту, що ви хочете створити.** Просто напишіть це в чаті своїми словами. Наприклад:
 
@@ -267,13 +269,15 @@ dotnet --version
 
 Якщо ви вже маєте проєкт десь інше і хочете перенести його у Forge:
 
-1. **Створіть проєкт Forge.** Відкрийте термінал і виконайте:
+1. **Створіть проєкт Forge.** Відкрийте термінал, створіть папку і виконайте:
 
    ```sh
-   forge create --name my-project
+   mkdir my-project
+   cd my-project
+   forge create --in-place --profile forge-shell
    ```
 
-   Потім відкрийте створену папку в вашому IDE.
+   Потім відкрийте папку в вашому IDE.
 
 2. **Скажіть ШІ-агенту:**
 
@@ -294,24 +298,33 @@ dotnet --version
 
 ### Для розробників — CLI-команди
 
-#### Створення нового проєкту
+#### Створення нового проєкту (на місці)
 
 ```sh
-# Створити новий проєкт (каркас + ініціалізація + навички + AGENTS.md однією командою)
-forge create --name my-project
+# Створіть папку проєкту, потім згенеруйте каркас Forge на місці
+mkdir my-project
+cd my-project
+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-site && cd my-site
+forge create --in-place --profile astro-typescript-turborepo
 
+mkdir my-game && cd my-game
+forge create --in-place --profile phaser-turborepo
+
+mkdir my-godot-game && cd my-godot-game
+forge create --in-place --profile godot-csharp
+
+# Перевизначити назву проєкту (за замовчуванням визначається з назви папки)
+forge create --in-place --profile forge-shell --name my-custom-name
 ```
 
 Якщо Forge не встановлено глобально, використовуйте `pnpm dlx`:
 
 ```sh
-pnpm dlx @warpgogol/forge create --name my-project
+mkdir my-project && cd my-project
+pnpm dlx @warpgogol/forge create --in-place --profile forge-shell
 ```
 
 #### Перенесення наявного проєкту у Forge
@@ -319,8 +332,9 @@ pnpm dlx @warpgogol/forge create --name my-project
 CLI-команди для перенесення немає — це інтерактивний процес під керівництвом ШІ:
 
 ```sh
-# 1. Створіть новий порожній проєкт Forge
-forge create --name my-project
+# 1. Створіть новий порожній проєкт Forge (на місці)
+mkdir my-project && cd my-project
+forge create --in-place --profile forge-shell
 
 # 2. Відкрийте проєкт у Windsurf (протестовано з Forge) або вашому IDE
 
@@ -396,7 +410,7 @@ forge doctor
 
 Типовий життєвий цикл проєкту Forge:
 
-1. **Створення** — `forge create` ініціалізує новий проєкт з forge.yaml, навичками та директоріями документації
+1. **Створення** — `forge create --in-place --profile <профіль>` генерує каркас нового проєкту в поточній директорії з forge.yaml, навичками та директоріями документації
 2. **IDE** — відкрийте проєкт у Windsurf (протестовано з Forge) або вашому IDE
 3. **Bootstrap** — запустіть `/forge-bootstrap` для інтерактивного налаштування проєкту. Навичка підтримує два режими:
    - **Greenfield** — створення нового проєкту з нуля: оберіть стек, заповніть прив'язки, ініціалізуйте git

package/package.json

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

package/profiles/astro-typescript-turborepo.yaml

@@ -11,6 +11,9 @@ workspace:
     - packages
     - services
     - scripts
+    - tools
+    - missions
+    - systems-cache
   files:
     - path: pnpm-workspace.yaml
       content: |
@@ -201,6 +204,150 @@ workspace:
         }
 
         console.log(`Cleaned ${toDelete.length} directories.`);
+    - path: tools/kernel.config.ts
+      content: |
+        import { defineKernelConfig } from "@warpgogol/werkstatt/kernel/types";
+        import { werkstattSitePlugin } from "@warpgogol/werkstatt-site";
+
+        export default defineKernelConfig({
+          name: "__PROJECT_NAME__",
+          description: "__PROJECT_NAME__ workshop",
+          moduleLoaders: {
+            "forge-core": async () => (await import("@warpgogol/forge/os/core")).forgeCoreModule,
+            "forge-rfc": async () => (await import("@warpgogol/forge/os/rfc-module")).forgeRfcModule,
+            "forge-adr": async () => (await import("@warpgogol/forge/os/adr-module")).forgeAdrModule,
+            "forge-plan": async () => (await import("@warpgogol/forge/os/plan-module")).forgePlanModule,
+            "forge-audit": async () => (await import("@warpgogol/forge/os/audit-module")).forgeAuditModule,
+            "forge-compass": async () => (await import("@warpgogol/forge/os/compass")).forgeCompassModule,
+            "forge-naming": async () => (await import("@warpgogol/forge/os/naming-module")).forgeNamingModule,
+            "forge-workflow": async () => (await import("@warpgogol/forge/os/workflow-module")).forgeWorkflowModule,
+            "forge-session": async () => (await import("@warpgogol/forge/os/session-module")).forgeSessionModule,
+            "forge-mission": async () => (await import("@warpgogol/forge/os/mission-module")).forgeMissionModule,
+            "forge-spec": async () => (await import("@warpgogol/forge/os/spec-module")).forgeSpecModule,
+            "forge-exploration": async () => (await import("@warpgogol/forge/os/exploration")).forgeExplorationModule,
+            "forge-program": async () => (await import("@warpgogol/forge/os/program")).forgeProgramModule,
+            "forge-werkstatt": async () => (await import("@warpgogol/forge/os/werkstatt")).forgeWerkstattModule,
+            mission: async () => (await import("@warpgogol/werkstatt/mission-module")).createMissionModule(),
+            sternsystem: async () => (await import("@warpgogol/werkstatt/sternsystem-module")).createSternsystemModule(),
+            bordbuch: async () => (await import("@warpgogol/werkstatt/bordbuch-module")).createBordbuchModule(),
+            "artifact-store": async () => (await import("@warpgogol/werkstatt/artifact-store-module")).createArtifactStoreModule(),
+            release: async () => (await import("@warpgogol/werkstatt/release-module")).createReleaseModule(),
+            leitstand: async () => (await import("@warpgogol/werkstatt/leitstand-module")).createLeitstandModule(),
+            notausgang: async () => (await import("@warpgogol/werkstatt/notausgang-module")).createNotausgangModule(),
+            evidence: async () => (await import("@warpgogol/werkstatt/evidence-module")).createEvidenceModule(),
+            "werkstatt-plugin": async () => (await import("@warpgogol/werkstatt/os/werkstatt-plugin-module")).forgeWerkstattPluginModule,
+            "werkstatt-autonomy": async () => (await import("@warpgogol/werkstatt/os/werkstatt-autonomy-module")).werkstattAutonomyModule,
+            "__PROJECT_NAME__-plugin": async () => werkstattSitePlugin,
+          },
+        });
+    - path: .npmrc
+      content: |
+        # @warpgogol scoped registry — replace YOUR_NPM_TOKEN with a valid npm read token
+        @warpgogol:registry=https://registry.npmjs.org/
+        //registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN
+    - path: eslint.config.js
+      content: |
+        export default [
+          {
+            rules: {},
+          },
+        ];
+    - path: .prettierrc.mjs
+      content: |
+        export default {
+          semi: true,
+          singleQuote: false,
+          trailingComma: "all",
+          printWidth: 100,
+          tabWidth: 2,
+        };
+    - path: .gitattributes
+      content: |
+        # Git LFS patterns for site stack media
+        *.mp4 filter=lfs diff=lfs merge=lfs -text
+        *.webm filter=lfs diff=lfs merge=lfs -text
+        *.png filter=lfs diff=lfs merge=lfs -text
+        *.jpg filter=lfs diff=lfs merge=lfs -text
+        *.jpeg filter=lfs diff=lfs merge=lfs -text
+        *.webp filter=lfs diff=lfs merge=lfs -text
+    - path: hooks/pre-commit
+      content: |
+        #!/bin/sh
+        # Platform-scope pre-commit guard
+        # Runs werkstatt autonomy and plugin validation before commits
+        echo "Pre-commit: running platform checks..."
+        pnpm exec werkstatt run werkstatt.autonomy.validate || exit 1
+        pnpm exec werkstatt run werkstatt.plugin.validate || exit 1
+    - path: systems-cache/.gitkeep
+      content: |
+        # Sternsystem cache directory (RFC-0790)
+        # Per-system config and state files live in systems-cache/<id>/
+    - path: missions/.gitkeep
+      content: ""
+    - path: .forge/pinned.yaml
+      content: |
+        # Pinned foundation files (DNA-62, RFC-0733)
+        # Protect mode: warns on delete/move. Freeze mode: blocks modify too.
+        entries:
+          - path: tools/kernel.config.ts
+            mode: protect
+          - path: forge.yaml
+            mode: protect
+          - path: pnpm-workspace.yaml
+            mode: protect
+          - path: turbo.json
+            mode: protect
+          - path: tsconfig.base.json
+            mode: protect
+          - path: systems-cache/.gitkeep
+            mode: protect
+    - path: README.md
+      content: |
+        # __PROJECT_NAME__
+
+        A Warpgogol workshop powered by the Werkstatt engine and the @warpgogol/werkstatt-site plugin.
+
+        ## Prerequisites
+
+        - Node.js 24+
+        - pnpm 10+
+        - Git LFS
+
+        ## Setup
+
+        ### 1. Configure npm token
+
+        This workshop depends on private @warpgogol packages. Edit `.npmrc` and replace `YOUR_NPM_TOKEN` with a valid npm read token:
+
+        ```sh
+        sed -i 's/YOUR_NPM_TOKEN/your_actual_token/' .npmrc
+        ```
+
+        ### 2. Install dependencies
+
+        ```sh
+        pnpm install
+        ```
+
+        ### 3. Verify the workshop
+
+        ```sh
+        pnpm exec werkstatt run forge.doctor
+        pnpm exec werkstatt run werkstatt.plugin.validate
+        pnpm exec werkstatt run werkstatt.autonomy.validate
+        ```
+
+        ## Create your first project
+
+        ```sh
+        pnpm exec werkstatt run onboarding.scaffold --system my-first-project --title "My First Project"
+        ```
+
+        ## Stack
+
+        - Engine: @warpgogol/werkstatt
+        - Plugin: @warpgogol/werkstatt-site
+        - Stack profile: astro-typescript-turborepo
 install:
   - pnpm add -D typescript turbo @warpgogol/forge @warpgogol/werkstatt @warpgogol/werkstatt-shared @warpgogol/werkstatt-site prettier
 firstWorkspace:

package/profiles/forge-shell.yaml

@@ -8,6 +8,9 @@ workspace:
   dirs:
     - docs
     - scripts
+    - tools
+    - missions
+    - systems-cache
   files:
     - path: .gitignore
       content: |
@@ -149,6 +152,122 @@ workspace:
           console.log("deleted", p.replace(repoRoot + "/", ""));
         }
 
-        console.log(`Cleaned ${toDelete.length} directories.`);
+        console.log(`Cleaned ${toDelete.length} directories.`)
+    - path: tools/kernel.config.ts
+      content: |
+        import { defineKernelConfig } from "@warpgogol/werkstatt/kernel/types";
+
+        export default defineKernelConfig({
+          name: "__PROJECT_NAME__",
+          description: "__PROJECT_NAME__ workshop",
+          moduleLoaders: {
+            "forge-core": async () => (await import("@warpgogol/forge/os/core")).forgeCoreModule,
+            "forge-rfc": async () => (await import("@warpgogol/forge/os/rfc-module")).forgeRfcModule,
+            "forge-adr": async () => (await import("@warpgogol/forge/os/adr-module")).forgeAdrModule,
+            "forge-plan": async () => (await import("@warpgogol/forge/os/plan-module")).forgePlanModule,
+            "forge-audit": async () => (await import("@warpgogol/forge/os/audit-module")).forgeAuditModule,
+            "forge-compass": async () => (await import("@warpgogol/forge/os/compass")).forgeCompassModule,
+            "forge-naming": async () => (await import("@warpgogol/forge/os/naming-module")).forgeNamingModule,
+            "forge-workflow": async () => (await import("@warpgogol/forge/os/workflow-module")).forgeWorkflowModule,
+            "forge-session": async () => (await import("@warpgogol/forge/os/session-module")).forgeSessionModule,
+            "forge-mission": async () => (await import("@warpgogol/forge/os/mission-module")).forgeMissionModule,
+            "forge-spec": async () => (await import("@warpgogol/forge/os/spec-module")).forgeSpecModule,
+            "forge-exploration": async () => (await import("@warpgogol/forge/os/exploration")).forgeExplorationModule,
+            "forge-program": async () => (await import("@warpgogol/forge/os/program")).forgeProgramModule,
+            "forge-werkstatt": async () => (await import("@warpgogol/forge/os/werkstatt")).forgeWerkstattModule,
+          },
+        });
+    - path: .npmrc
+      content: |
+        # @warpgogol scoped registry — replace YOUR_NPM_TOKEN with a valid npm read token
+        @warpgogol:registry=https://registry.npmjs.org/
+        //registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN
+    - path: eslint.config.js
+      content: |
+        export default [
+          {
+            rules: {},
+          },
+        ];
+    - path: .prettierrc.mjs
+      content: |
+        export default {
+          semi: true,
+          singleQuote: false,
+          trailingComma: "all",
+          printWidth: 100,
+          tabWidth: 2,
+        };
+    - path: .gitattributes
+      content: |
+        # No LFS patterns for this stack
+    - path: hooks/pre-commit
+      content: |
+        #!/bin/sh
+        # Platform-scope pre-commit guard
+        # Runs forge validation before commits
+        echo "Pre-commit: running platform checks..."
+        pnpm exec forge run forge.validate || exit 1
+    - path: systems-cache/.gitkeep
+      content: |
+        # Sternsystem cache directory (RFC-0790)
+        # Per-system config and state files live in systems-cache/<id>/
+    - path: missions/.gitkeep
+      content: ""
+    - path: .forge/pinned.yaml
+      content: |
+        # Pinned foundation files (DNA-62, RFC-0733)
+        # Protect mode: warns on delete/move. Freeze mode: blocks modify too.
+        entries:
+          - path: tools/kernel.config.ts
+            mode: protect
+          - path: forge.yaml
+            mode: protect
+          - path: pnpm-workspace.yaml
+            mode: protect
+          - path: turbo.json
+            mode: protect
+          - path: tsconfig.base.json
+            mode: protect
+          - path: systems-cache/.gitkeep
+            mode: protect
+    - path: README.md
+      content: |
+        # __PROJECT_NAME__
+
+        A Warpgogol workshop powered by the Forge engine.
+
+        ## Prerequisites
+
+        - Node.js 24+
+        - pnpm 10+
+
+        ## Setup
+
+        ### 1. Configure npm token
+
+        This workshop depends on private @warpgogol packages. Edit `.npmrc` and replace `YOUR_NPM_TOKEN` with a valid npm read token:
+
+        ```sh
+        sed -i 's/YOUR_NPM_TOKEN/your_actual_token/' .npmrc
+        ```
+
+        ### 2. Install dependencies
+
+        ```sh
+        pnpm install
+        ```
+
+        ### 3. Verify the workshop
+
+        ```sh
+        pnpm exec forge run forge.doctor
+        pnpm exec forge run forge.validate
+        ```
+
+        ## Stack
+
+        - Engine: @warpgogol/forge
+        - Stack profile: forge-shell
 install:
   - pnpm add -D @warpgogol/forge prettier vitest