docs: document tsforge /scaffold → Phaser

AGENTS.md

@@ -45,11 +45,13 @@ Must pass. Fix root causes; do not skip hooks.
 
 ## tsforge
 
-[tsforge](https://tsforge.dev) is the org TypeScript harness. Point it at a fork of this repo; the gate is `bun run check`.
+[tsforge](https://tsforge.dev) is the org TypeScript harness. The gate is `bun run check`.
 
-The **`phaser` rule pack** auto-applies when `phaser` is in package.json: scene SHUTDOWN ownership, no global emitter leaks, no Phaser factories in `update`/`tick`, branded scene/texture keys, no `ignoreDestroy`. This repo's `eslint.config.js` covers a syntactic subset of that pack so `bun run check` stays honest without depending on unpublished tsforge.
+**New game:** `/scaffold` → Phaser (or `tsforge scaffold --archetype phaser --dest ./my-game`). First prompt in that folder plans with a Phaser view-intent schema (scene / feature / content), not SaaS screens. Requires a tsforge with the Phaser adapter (tsforge `main`; next npm release after 0.51.1).
 
-A Phaser **stack adapter** (planner schema, conventions, greenfield clone) is still planned, not shipped. Do **not** add `.tsforge/scaffold-manifest.json` — that file is how tsforge detects the fullstack BoringStack template.
+**This tree:** the **`phaser` rule pack** auto-applies when `phaser` is in package.json (scene SHUTDOWN, no global emitter leaks, no Phaser factories in `update`/`tick`, branded keys, no `ignoreDestroy`). `eslint.config.js` covers a syntactic subset of that pack so `bun run check` stays honest without depending on a published tsforge.
+
+Do **not** add `.tsforge/scaffold-manifest.json` — that file is the fullstack BoringStack env surface. A Phaser scaffold writes `.tsforge/scaffold.json` (receipt); leave it.
 
 ## Deviations
 

BUILD_THE_GAME.md

@@ -1,6 +1,6 @@
 # Build the Game — the AI-First Guide
 
-This document is the end-to-end walkthrough for building a game using this template. It's written for two audiences at once: a human who just clicked **"Use this template"**, and an AI agent that has joined the project mid-flight. Read it front-to-back once; come back for the sections you need.
+This document is the end-to-end walkthrough for building a game using this template. It's written for two audiences at once: a human who just ran tsforge `/scaffold` → Phaser (or clicked **"Use this template"**), and an AI agent that has joined the project mid-flight. Read it front-to-back once; come back for the sections you need.
 
 > **First time making a game?** Read [`docs/learn/`](./docs/learn/README.md) **before** this document. It covers the mental-model shift, AI asset generation, game-design fundamentals, and the solo-dev workflow. This document assumes you already know what a sprite, tilemap, and core loop are. The `learn/` primer will teach you all three in 2.5 hours.
 
@@ -62,9 +62,18 @@ Every non-trivial change walks the same pipeline: specify → clarify → plan 
 
 ## 3. Zero to first commit
 
-### Step 1 — Fork from the template
+### Step 1 — Start from the template
 
-Click **"Use this template"** on the GitHub page. Give your new repo a name. Clone locally.
+**Preferred if you already use tsforge** — same wizard as BoringStack:
+
+```sh
+tsforge scaffold --archetype phaser --dest ./my-game
+cd my-game
+```
+
+Or, in a tsforge session: `/scaffold` → **Phaser** → folder name. That clones this repo, stamps `package.json` `name`, and writes `.tsforge/scaffold.json`. Requires a tsforge with the Phaser adapter (tsforge `main`; next npm release after 0.51.1).
+
+**Otherwise** — click **"Use this template"** on GitHub:
 
 ```sh
 gh repo create my-game --template boringstack-xyz/Phaser-TypeScript-AI-First-Starter --public --clone
@@ -73,6 +82,8 @@ cd my-game
 
 ### Step 2 — Rename
 
+Skip if you used tsforge scaffold (it already set the package name from the folder).
+
 ```sh
 # Update the package name
 sed -i '' 's/"name": "phaser-ts-starter"/"name": "my-game"/' package.json
@@ -334,16 +345,17 @@ Two faster inner loops:
 
 ## 9.5 Using tsforge
 
-[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness. After forking:
+[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness.
+
+To **create** the game, use Step 1 (`/scaffold` → Phaser). Then, from the project folder:
 
 ```sh
-# from the fork
 tsforge
 ```
 
-Point it at this tree. The gate it should run is `bun run check`. The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). This template's ESLint already covers a syntactic subset of that pack.
+The first prompt plans with Phaser view intents (scene / feature / content), not list/detail/form screens. The gate is `bun run check`. The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). This template's ESLint already covers a syntactic subset of that pack.
 
-A dedicated Phaser **adapter** (greenfield clone, planner schema, Phaser conventions instead of React/Elysia) is planned in tsforge and **not shipped**. Do not add `.tsforge/scaffold-manifest.json` here — that file is how tsforge detects the fullstack BoringStack template.
+Do not add `.tsforge/scaffold-manifest.json` here — that file is how tsforge configures the fullstack BoringStack template. After a Phaser scaffold, `.tsforge/scaffold.json` is the receipt that makes tsforge treat this tree as Phaser.
 
 ---
 

README.md

@@ -37,7 +37,7 @@ This repo is part of **[boringstack-xyz](https://github.com/boringstack-xyz)**.
 
 Backend engineer, tech lead, web developer who always wanted to make games? Start with [`docs/learn/`](./docs/learn/README.md) — a 2.5-hour primer that bridges "I can write code" to "I can generate art, design a core loop, and ship on itch.io."
 
-> **Use this as a GitHub template.** Click **"Use this template"** on the repo page, then read [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md).
+> Start a new game with [tsforge](https://tsforge.dev) (`/scaffold` → **Phaser**, or `tsforge scaffold --archetype phaser --dest ./my-game`), or click **"Use this template"** on GitHub. Then read [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md).
 
 ### After forking: one-time repo setup
 
@@ -62,7 +62,7 @@ Everything else (CI, Scorecard, CodeQL, Dependabot) works out of the box. Desire
 | If you are...                             | Read next                                                                                         |
 | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
 | **A programmer who never shipped a game** | [`docs/learn/`](./docs/learn/README.md)                                                           |
-| **A human forking this to build a game**  | [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md)                                                        |
+| **A human starting a game (tsforge or GitHub template)** | [`BUILD_THE_GAME.md`](./BUILD_THE_GAME.md)                                               |
 | **An AI agent in a fresh session**        | [`AGENTS.md`](./AGENTS.md) + [`docs/ai/catalog.md`](./docs/ai/catalog.md)                          |
 | **Just evaluating the architecture**      | [`docs/ai/architecture.md`](./docs/ai/architecture.md)                                            |
 | **Looking for the rules**                 | [`docs/ai/contribution-contract.md`](./docs/ai/contribution-contract.md) + [`.specify/memory/constitution.md`](./.specify/memory/constitution.md) |
@@ -80,9 +80,22 @@ Arrow keys or WASD to move. Walk onto a yellow circle to score. Press **S** to s
 
 ## Using tsforge
 
-[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness. Point it at a fork of this template; the gate is `bun run check`.
+[tsforge](https://tsforge.dev) is the BoringStack TypeScript build harness.
 
-The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). A dedicated Phaser **stack adapter** (planner schema, conventions, greenfield clone) is planned and **not shipped yet**. Do not add a `.tsforge/scaffold-manifest.json` here; that file is how tsforge detects the fullstack template.
+**New game** — same wizard as BoringStack:
+
+```sh
+tsforge scaffold --archetype phaser --dest ./my-game
+# or, in a tsforge session: /scaffold → Phaser → folder name
+cd my-game
+tsforge   # first prompt plans the game (scene / feature / content slices)
+```
+
+No Docker, no `.env`. The clone keeps this template's WASD demo; new work extends it. The gate is `bun run check`. Requires a tsforge build that includes the Phaser adapter (tsforge `main`; the next npm release after 0.51.1).
+
+**Existing clone** — point tsforge at this tree. The **`phaser` rule pack** auto-applies from the `phaser` dependency (scene shutdown, no factories in `update`, branded keys). This repo's `eslint.config.js` covers a syntactic subset of that pack so `bun run check` stays honest without depending on a published tsforge.
+
+Do not add `.tsforge/scaffold-manifest.json` here. That file is how tsforge configures the fullstack BoringStack template. tsforge writes `.tsforge/scaffold.json` (a receipt) after a Phaser scaffold; that is expected.
 
 ## Architecture in 30 seconds
 

docs/ai/architecture.md

@@ -55,7 +55,7 @@ Violations are lint errors (eslint-plugin-boundaries) and dep-cruiser errors in
 - **Scene keys are branded constants** (`asSceneKey` in `src/runtime/phaser/scenes/sceneKeys.ts`), never string literals in `scene.start` / `super()`.
 - **Scenes hook `Phaser.Scenes.Events.SHUTDOWN`** and dispose run-lifetime resources there. Do not set `ignoreDestroy`. Do not construct GameObjects in `update()`.
 
-tsforge's `phaser` pack enforces the engine-API subset of these rules when pointed at a fork.
+tsforge's `phaser` pack enforces the engine-API subset of these rules when pointed at this tree. `/scaffold` → Phaser clones this template; do not add `.tsforge/scaffold-manifest.json`.
 
 ## When the rules feel wrong