docs: add PlayCanvas Stage user manual page

docs/user-manual/engine/developing-with-ai.md

@@ -85,6 +85,7 @@ the evidence that the result works.
 
 Start with only the integrations needed for the task. Before adding a browser MCP server, check whether the selected desktop client's built-in browser or app preview already covers verification. Otherwise, choose one browser tool and add another only when it provides a missing capability.
 
+- **[PlayCanvas Stage](/user-manual/stage/):** Attach to the running app, then point at entities, move them with gizmos and comment on what you see, so the agent gets entity paths and captures instead of descriptions and writes your edits into the source.
 - **[Context7 MCP](https://github.com/upstash/context7):** Retrieve its indexed [PlayCanvas Engine documentation](https://context7.com/playcanvas/engine) when the client benefits from MCP-based lookup. Prefer the official AI-readable documentation above for authoritative content.
 - **[Playwright MCP](https://github.com/microsoft/playwright-mcp):** Launch and operate the application in a browser, exercise user flows, and capture screenshots.
 - **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp):** Use instead of Playwright when console, network, or performance diagnosis is the main task.

docs/user-manual/getting-started/index.md

@@ -16,7 +16,7 @@ PlayCanvas is a collection of open-source products that you can use to build int
 
 ## Start a Code Project
 
-Use [`create-playcanvas`](start-with-create-playcanvas) to scaffold a Vite and TypeScript project for the Engine, React, or Web Components from one of 12 runnable starters. New projects include [PlayCanvas Skills](use-playcanvas-skills), which give compatible AI coding agents PlayCanvas-specific development and verification workflows.
+Use [`create-playcanvas`](start-with-create-playcanvas) to scaffold a Vite and TypeScript project for the Engine, React, or Web Components from one of 12 runnable starters. New projects include [PlayCanvas Skills](use-playcanvas-skills), which give compatible AI coding agents PlayCanvas-specific development and verification workflows. To work on the running app alongside your agent, pointing at entities and moving them with gizmos instead of describing them, use [PlayCanvas Stage](../stage).
 
 ## Coming from Unity
 

docs/user-manual/stage/comments.md

@@ -0,0 +1,61 @@
+---
+title: Comments
+description: Comment on an entity or an area of a PlayCanvas app in Stage, send the thread to your coding agent, and follow it until the agent replies.
+---
+
+Comments are for changes you'd rather describe than drag: a new color, a missing object, a behavior that's wrong. You point at what you mean, and the agent gets enough context to know exactly which thing that is.
+
+## Leave a Comment
+
+Press <kbd>C</kbd> or the **Comment** button to enter comment mode. A playing app pauses. Then:
+
+- click an entity to comment on it, or drag across an area, empty space included
+- <kbd>Shift</kbd>+click adds another object to the open comment, and <kbd>Shift</kbd>+drag adds everything an area covers
+- outside the canvas, any element of the page takes a comment, and a drag that starts on text quotes it
+
+A comment is pinned to the 3D point you placed it at and follows the camera. With it, the agent gets the entity's path, that point and a capture of what you saw.
+
+<video autoPlay muted loop controls src='/video/stage-comment.mp4' style={{width: '100%', height: 'auto'}} />
+
+The comment box opens where you clicked. <kbd>Enter</kbd> posts and <kbd>Shift</kbd>+<kbd>Enter</kbd> adds a line. It has two buttons:
+
+- **Comment** posts the comment.
+- **Send to Agent** posts it and hands the thread to the agent, which reads it, does the work and replies in the thread without you typing anything in the session. Writing `@agent` in the text does the same.
+
+Comment mode stays on until **Done commenting**, <kbd>C</kbd>, or a second <kbd>Esc</kbd>. The first <kbd>Esc</kbd> closes an open draft.
+
+:::tip Show, don't tell
+
+A comment or reply can carry up to 4 reference images. Paste them into its box, drop them onto it, or pick them with its image button. The agent reads them with the thread.
+
+:::
+
+## Follow a Thread
+
+A thread sent to the agent shows where it is:
+
+| Status | Meaning |
+| --- | --- |
+| **Queued for an agent session** | No session has picked it up yet |
+| **Working on it…** | The agent has received it |
+| **Hasn't replied yet** | No reply within 10 minutes |
+
+The sidebar lists every thread. Drag its left edge to resize it, or double-click the edge to reset it.
+
+:::caution Withdrawing a request
+
+Deleting a thread while it is **Working on it…** or **Hasn't replied yet** withdraws it: the agent is told to drop the request, revert the changes it made for it, and not reply. A thread deleted while it is still queued never reaches the agent.
+
+:::
+
+## Who Is Watching
+
+Comments reach only the sessions linked to the stage: a session that opened the stage, or one you paste the stage's URL into. The circle at the right of the header shows who is there:
+
+| Circle | Meaning |
+| --- | --- |
+| Green, **Agent is watching** | Comments reach the agent straight away |
+| Amber | A linked session is open but not watching; comments arrive with your next message there |
+| Hollow, **No agent session** | Comments you send wait until a session links the stage |
+
+How a session hears about new comments depends on the agent. See [Claude Code and Codex](configuration.md#claude-code-and-codex).

docs/user-manual/stage/configuration.md

@@ -0,0 +1,59 @@
+---
+title: Configuration
+description: How PlayCanvas Stage works with Claude Code and Codex, its environment settings, how to stop its local server, and what data and network access it uses.
+---
+
+## Claude Code and Codex
+
+Both agents share one local Stage server and the same set of stages. They differ in how a session hears about comments you send:
+
+- **Claude Code:** the plugin's comment monitor starts the first time the agent loads Stage's `stage-design` skill in a session. It checks for new comments every 2 seconds and wakes an idle session. Without it, as in non-interactive sessions, your next message there carries the comments.
+- **Codex:** on your first message in a session, the plugin starts a watcher that hands each comment you send to `codex queue`, which makes the idle session take a turn. The watcher exits when that Codex process does.
+
+:::caution Codex comment delivery
+
+`codex queue` is experimental in Codex itself, so comment delivery in Codex may change as Codex does.
+
+:::
+
+Codex doesn't tell plugins which folder a session works in, so pass absolute file paths there. Relative paths are refused with an error that says so.
+
+## Settings
+
+Set these environment variables before starting your agent:
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `STAGE_PORT` | `47318` | Viewer and API port |
+| `STAGE_DIR` | `~/.playcanvas-stage` | State directory |
+| `STAGE_AUTO_OPEN` | on | `0` stops opening new stages in the browser |
+| `CHROME_PATH` | auto | Chrome binary for headless previews |
+
+## Stopping the Server
+
+The Stage server starts on the first Stage tool call and keeps running after the session ends, so your stages stay open. Stop it with:
+
+```bash
+kill $(jq .pid ~/.playcanvas-stage/server.json)
+```
+
+## Data and Network Use
+
+:::info
+
+Stage has no telemetry and makes no outbound requests of its own. Scaffolding a new project runs `npx create-playcanvas@latest` from npm, and any other traffic is only what your app and its pages load.
+
+:::
+
+- **Local only.** The server binds to `127.0.0.1` and accepts only `localhost` addresses.
+- **State.** Stages, comments, edits and diagnostics are kept in `~/.playcanvas-stage`.
+- **Access.** The agent's API needs a token kept in `~/.playcanvas-stage/server.json`, readable only by you. Comments can only be written from the viewer.
+- **Dev server.** Only the agent can point a stage at a dev server, and only at `http` on `localhost`, `127.0.0.1` or `[::1]`.
+
+:::warning Keep the token private
+
+`~/.playcanvas-stage/server.json` holds the token that lets an agent read and write your stages. Don't share it or commit it.
+
+:::
+
+The [plugin reference](https://github.com/playcanvas/stage/blob/main/plugins/playcanvas-stage/README.md) on GitHub has every key, tool and trust boundary in full.

docs/user-manual/stage/editing.md

@@ -0,0 +1,64 @@
+---
+title: Editing Scenes
+description: Pause a PlayCanvas app in Stage, select entities, move, rotate and scale them with gizmos, and Apply the edits so the agent writes them into the source.
+---
+
+In Stage you lay out a scene by hand, the same way you would in the PlayCanvas Editor, and the agent writes the result into your code.
+
+## Play and Pause
+
+The toolbar above the app plays and pauses it with <kbd>⌘</kbd>+<kbd>P</kbd> (<kbd>Ctrl</kbd>+<kbd>P</kbd> on Windows and Linux). Pausing stops the app's updates, input and audio, and an editor camera takes over while the game camera stays where the app put it.
+
+| Input | Action |
+| --- | --- |
+| Drag | Orbit |
+| Middle-drag or <kbd>Shift</kbd>+drag | Pan |
+| Scroll | Zoom |
+| Right-drag | Look around |
+| <kbd>W</kbd> <kbd>A</kbd> <kbd>S</kbd> <kbd>D</kbd> <kbd>Q</kbd> <kbd>E</kbd> | Fly |
+| <kbd>F</kbd> | Frame the selection, or the whole scene, and orbit it |
+| <kbd>⌥</kbd>+<kbd>⌘</kbd>+<kbd>P</kbd> | Step the app one frame |
+
+Paused, click an entity to select it. Each camera in the scene shows as an icon, and a selected camera shows what it sees.
+
+<video autoPlay muted loop controls src='/video/stage-select-rotate.mp4' style={{width: '100%', height: 'auto'}} />
+
+## Move, Rotate and Scale
+
+With an entity selected, switch the gizmo with <kbd>1</kbd>, <kbd>2</kbd> and <kbd>3</kbd>. Every toolbar button shows what it does and its key on hover.
+
+| Key | Action |
+| --- | --- |
+| <kbd>1</kbd> | **Move:** drag an arrow or plane of the gizmo |
+| <kbd>2</kbd> | **Rotate:** drag a ring of the gizmo |
+| <kbd>3</kbd> | **Scale:** drag a handle of the gizmo |
+| <kbd>X</kbd> | Switch the gizmo between world and local axes |
+| <kbd>Shift</kbd> | Hold while dragging to snap: move in 0.1 m, turn in 15° and scale in 0.1 steps |
+| <kbd>G</kbd> | Show or hide the ground grid |
+| <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>Z</kbd> | Undo |
+| <kbd>Ctrl</kbd>/<kbd>⌘</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd> | Redo |
+
+<video autoPlay muted loop controls src='/video/stage-move-scale-undo.mp4' style={{width: '100%', height: 'auto'}} />
+
+The ground grid shows to the editor camera only. It never appears in comment captures and can't be selected.
+
+## Apply Edits to the Source
+
+Every edit is saved as you make it, shows in every open view of the stage and survives reloads. Nothing changes in your source until you choose:
+
+- **Apply** sends the edits to the agent, to write into the source.
+- **Discard** puts the edited entities back where the app placed them, and sends nothing. It can be undone.
+
+<video autoPlay muted loop controls src='/video/stage-apply.mp4' style={{width: '100%', height: 'auto'}} />
+
+:::tip
+
+In Claude Code you don't need to switch to the session after pressing **Apply**. The plugin wakes the session, and the agent picks the edits up on its own.
+
+:::
+
+:::note
+
+An edit applies once, when its entity appears. After that, the app's own writes to the entity win, so an entity the app moves while it runs won't hold an edit.
+
+:::

docs/user-manual/stage/index.md

@@ -0,0 +1,96 @@
+---
+title: PlayCanvas Stage
+description: "An editor where you and your coding agent work on PlayCanvas apps together: point at entities instead of describing them, move them with gizmos, and the agent writes your edits into the source. A quick start, where to go next, and how it fits together."
+---
+
+import Link from '@docusaurus/Link';
+
+[PlayCanvas Stage](https://github.com/playcanvas/stage) is an editor where you and your coding agent work on PlayCanvas apps together. Instead of describing where something is, you point at it: pause your app, click an entity, move it with a gizmo or leave a comment on it, and the agent writes the change into your source. It works with Claude Code and Codex, and runs entirely on your machine.
+
+<video controls muted playsInline preload="metadata" poster="/img/user-manual/stage/stage.webp" src="/video/playcanvas-stage.mp4" style={{width: '100%', height: 'auto'}} />
+
+<div className="cta-buttons">
+    <Link className="button button--primary button--lg" to="/user-manual/stage/installation/">Get Started →</Link>
+    <Link className="button button--secondary button--lg" to="https://github.com/playcanvas/stage">View on GitHub</Link>
+</div>
+
+:::important Prerelease
+
+Stage 0.1.0 is a prerelease. Expect rough edges and changes between versions, and [report what you find](https://github.com/playcanvas/stage/issues).
+
+:::
+
+## Your first stage in 5 minutes
+
+1. **Install.** Add the Stage plugin to Claude Code or Codex. See [Installation](installation.md#install-the-plugin).
+2. **Ask.** Ask your agent for a scene ("build my desk in 3D at real scale"), or point it at an app you already have. Stage opens in your browser.
+3. **Pause and select.** Press <kbd>⌘</kbd>/<kbd>Ctrl</kbd>+<kbd>P</kbd> to pause the app, then click an entity. See [Editing Scenes](editing.md).
+4. **Move and Apply.** Drag the gizmo to move, rotate or scale it, then press **Apply**. The agent writes the edit into your source.
+5. **Comment.** Press <kbd>C</kbd>, click an object or drag across an area, type what you want and press **Send to Agent**. See [Comments](comments.md).
+
+## Where do you want to start?
+
+<div className="row path-cards">
+  <div className="col col--6">
+    <Link className="card path-card" to="/user-manual/stage/installation/#start-from-a-new-scene">
+      <div className="card__header"><h3>✨ I'm starting from nothing</h3></div>
+      <div className="card__body"><p>Ask for a scene and the agent scaffolds a PlayCanvas project, starts its dev server and opens it in Stage.</p></div>
+      <div className="card__footer">Start from a new scene →</div>
+    </Link>
+  </div>
+  <div className="col col--6">
+    <Link className="card path-card" to="/user-manual/stage/installation/#attach-an-existing-app">
+      <div className="card__header"><h3>🔌 I have an app</h3></div>
+      <div className="card__body"><p>Attach Stage to any running PlayCanvas app on Engine 2.23 or later, whatever it's built with. Its hot reload keeps working.</p></div>
+      <div className="card__footer">Attach an existing app →</div>
+    </Link>
+  </div>
+  <div className="col col--6">
+    <Link className="card path-card" to="/user-manual/stage/editing/">
+      <div className="card__header"><h3>🎯 I want to lay out a scene</h3></div>
+      <div className="card__body"><p>Pause the app, select entities, move, rotate and scale them with gizmos, and Apply the edits to your source.</p></div>
+      <div className="card__footer">Editing Scenes →</div>
+    </Link>
+  </div>
+  <div className="col col--6">
+    <Link className="card path-card" to="/user-manual/stage/comments/">
+      <div className="card__header"><h3>💬 I want the agent to change something</h3></div>
+      <div className="card__body"><p>Comment on an entity or an area. The agent gets its path, the 3D point and a capture of what you saw, and replies in the thread.</p></div>
+      <div className="card__footer">Comments →</div>
+    </Link>
+  </div>
+</div>
+
+## How it fits together
+
+Stage runs a small server on your machine. It proxies your app's dev server into a viewer in your browser and adds its tools to the page, while your agent talks to the same server through the Stage plugin.
+
+```mermaid
+---
+config:
+  flowchart:
+    curve: step
+---
+flowchart LR
+    you([You, in Stage]) -->|Apply or Send to Agent| agent([Coding agent])
+    agent -->|writes the changes| source([Your source])
+    source -.->|hot reload| you
+```
+
+- **The viewer** shows your app with a toolbar above it, the comments sidebar and the [Inspector](viewer-tools.md#inspector).
+- **The Stage server** keeps your edits and comments, and hands them to the agent when you press **Apply** or **Send to Agent**.
+- **Your agent** reads them, writes the changes into your source, and your dev server's hot reload shows the result.
+
+Stage never starts or stops your dev server, and nothing is added to your source except the edits the agent writes. Close Stage and you have the same app you started with.
+
+:::info Runs on your machine
+
+Stage has no telemetry and makes no outbound requests of its own. Its server binds to `127.0.0.1` only and keeps all state in `~/.playcanvas-stage`. Scaffolding a new project runs `npx create-playcanvas@latest` from npm, and any other traffic is only what your app loads. See [Configuration](configuration.md#data-and-network-use).
+
+:::
+
+:::note Open Source
+
+PlayCanvas Stage is [open-sourced under an MIT license on GitHub](https://github.com/playcanvas/stage).
+
+:::

docs/user-manual/stage/installation.md

@@ -0,0 +1,86 @@
+---
+title: Installation
+description: Install the PlayCanvas Stage plugin for Claude Code or Codex, then open a new scene or an existing PlayCanvas app in Stage.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Stage is a plugin for your coding agent. Install it once, then ask the agent to open a scene or an app in Stage.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) 22.18 or later
+- Chrome or Chromium
+- An app on PlayCanvas Engine 2.23 or later
+- Claude Code 2.1.275 or later, or Codex
+
+## Install the Plugin
+
+<Tabs defaultValue="claude" groupId='stage-agent'>
+<TabItem value="claude" label="Claude Code">
+
+```bash
+claude plugin marketplace add playcanvas/stage
+claude plugin install playcanvas-stage@stage
+```
+
+Or, in a session, run `/plugin install playcanvas-stage --marketplace playcanvas/stage`, then `/reload`.
+
+</TabItem>
+<TabItem value="codex" label="Codex">
+
+```bash
+codex plugin marketplace add playcanvas/stage
+codex plugin add playcanvas-stage@stage
+```
+
+Codex asks before each Stage tool call unless you approve the server's tools.
+
+</TabItem>
+</Tabs>
+
+Start a new session after installing so the agent picks up the plugin.
+
+## Start from a New Scene
+
+Ask your agent for a scene, for example "build my desk in 3D at real scale" or "block out a riverside plaza with a fountain and benches". The agent scaffolds a project with [`create-playcanvas`](/user-manual/getting-started/start-with-create-playcanvas/) in your working directory, starts its dev server, attaches Stage to it and opens it in your browser.
+
+:::tip
+
+Projects created with `create-playcanvas` include the [PlayCanvas Skills](/user-manual/getting-started/use-playcanvas-skills/), so the agent has PlayCanvas-specific context from the first prompt.
+
+:::
+
+## Attach an Existing App
+
+Start your app's dev server as usual, then ask the agent to open the app in Stage. Stage proxies the dev server and adds its tools when the page loads, so:
+
+- it works whatever the app is built with, through the Engine's devtools hook
+- the app's own hot reload keeps working, websockets included
+- a server without hot reload, such as static files or a plain Express server, gets a reload of the view when a file in the project changes
+- nothing is added to your source except the edits the agent writes
+
+:::note Engine bundled into your code?
+
+An app that bundles the Engine into its own code needs one extra line before Stage can find it. The viewer shows you the line to add.
+
+:::
+
+Stage never starts, restarts or stops your dev server. While it isn't answering, the viewer shows a waiting banner and attaches when it comes back.
+
+## Open the Viewer
+
+The first time the agent attaches Stage, it opens the stage in your browser. Every stage is listed in the gallery at `http://localhost:47318/stages`.
+
+:::warning Use Chrome or Firefox
+
+Each stage runs on its own `*.localhost` address, which Safari may not resolve. Open the viewer in Chrome, Chromium or Firefox.
+
+:::
+
+## Next Steps
+
+- [Editing Scenes](editing.md): pause, select and move entities, then Apply the edits
+- [Comments](comments.md): point at what you mean and let the agent do the work
+- [Devices and Inspector](viewer-tools.md): preview on phones and lenses, and inspect the running app