@vgai/editor 0.4.0 → 0.4.1

package/src/workspace-state-persistence.ts

@@ -8,7 +8,7 @@
  * own store (`hierarchy-expansion-state.ts`, §6.1), same key discipline.
  *
  * STORAGE DECISION (recorded): `localStorage`, key
- * `vgai:workspace-state:v8`, holding a map keyed PER PROJECT by
+ * `vgai:workspace-state:v10`, holding a map keyed PER PROJECT by
  * `getCurrentProject().rootPath` (the same project identity
  * `hierarchy-expansion-state.ts` established — it prevents one game's layout
  * leaking into another, and `rootPath` is the durable cross-session
@@ -32,7 +32,8 @@
  *    path). Verified via `projectFileExists()` (storage-first stat, HTTP HEAD
  *    fallback — an existence-only probe; unlike the prefab/scene loaders'
  *    `readProjectTextFile`, this never downloads the asset body just to check
- *    it is still there). Asset-Lab (`asset-lab:entity:*`) and unresolved
+ *    it is still there). Live-entity Asset Editor (`asset-editor:entity:*`,
+ *    with legacy `asset-lab:*` input aliases) and unresolved
  *    online (`online:*`) documents are NOT persisted: a live-entity lab
  *    session and a remote detail view are not truthfully re-resolvable from a
  *    cold boot.
@@ -41,6 +42,8 @@
  *  - tool documents: `openToolDocument` self-verifies against the discovered
  *    tool store (awaited `refreshProjectTools()` first) — unknown ids open
  *    nothing.
+ *  - the Project Tools catalog always reopens; schema-driven fallback runners
+ *    verify their registered callable after an awaited catalog refresh.
  *  - story documents: verified against the story registry after an awaited
  *    `refreshProjectStories()` — module must load ok AND still export the
  *    story name.
@@ -79,6 +82,12 @@ import {
   refreshDataFiles,
 } from './components/data-documents';
 import { openDebuggerPanel } from './components/debugger-panel-state';
+import {
+  openProjectToolDocument,
+  openProjectToolsDocument,
+  PROJECT_TOOL_DOCUMENT_PREFIX,
+  PROJECT_TOOLS_DOCUMENT_ID,
+} from './components/project-tool-documents';
 import {
   openStoryDocsDocument,
   openStoryDocument,
@@ -94,8 +103,9 @@ import {
   subscribeHarnessChatLayout,
 } from './harness-chat-layout';
 import { getCurrentProject } from './project-manager';
+import { refreshProjectTools } from './project-tools';
 import { getProjectStoryModules, refreshProjectStories } from './stories/story-registry';
-import { refreshProjectTools } from './tool-loader';
+import { refreshProjectToolContributions } from './tool-loader';
 import {
   activateWorkspaceDocument,
   activeWorkspaceDocumentId,
@@ -113,7 +123,10 @@ import {
 // world-surface/resource tab-family seam. A v7 layout cannot name those
 // panels and can restore center documents into a navigator group, so reset
 // that physical layout once instead of guessing at user intent.
-const STORAGE_KEY = 'vgai:workspace-state:v8';
+// v9 removes the old UI-only tool document shape in favor of distinct
+// registered project-tool runners. v10 adds package-registered editor
+// contributions as independently restorable documents.
+const STORAGE_KEY = 'vgai:workspace-state:v10';
 const WRITE_DEBOUNCE_MS = 300;
 /** Bound on the document-restore verification before write-through installs
  *  anyway (module header's "wait is BOUNDED" rule). */
@@ -124,7 +137,8 @@ const LEGACY_PROFILER_DOCUMENT_ID = 'workspace:profiler';
 export type PersistedDocument =
   | { readonly t: 'asset'; readonly id: string; readonly path: string; readonly assetKind: string }
   | { readonly t: 'data'; readonly id: string; readonly path: string }
-  | { readonly t: 'tool'; readonly id: string; readonly toolId: string }
+  | { readonly t: 'tool-contribution'; readonly id: string; readonly contributionId: string }
+  | { readonly t: 'project-tool'; readonly id: string; readonly name: string }
   | {
       readonly t: 'story';
       readonly id: string;
@@ -210,8 +224,14 @@ export function persistableDocument(doc: {
       return id === DATA_ASSETS_DOCUMENT_ID
         ? { t: 'static', id }
         : { t: 'data', id, path: id.slice('data:'.length) };
-    case 'tool':
-      return { t: 'tool', id, toolId: id.slice('tool:'.length) };
+    case 'tool-contribution':
+      return { t: 'tool-contribution', id, contributionId: id.slice('tool:'.length) };
+    case 'project-tool':
+      if (id === PROJECT_TOOLS_DOCUMENT_ID) return { t: 'static', id };
+      if (id.startsWith(PROJECT_TOOL_DOCUMENT_PREFIX)) {
+        return { t: 'project-tool', id, name: id.slice(PROJECT_TOOL_DOCUMENT_PREFIX.length) };
+      }
+      return null;
     case 'story': {
       const state = storyDocumentState(id);
       if (!state) return null;
@@ -271,6 +291,7 @@ function restoreStoryDocument(
 
 function restoreStaticDocument(store: WorkspaceStateStore, id: string): void {
   if (id === LEGACY_PROFILER_DOCUMENT_ID) openDebuggerPanel('profiler');
+  else if (id === PROJECT_TOOLS_DOCUMENT_ID) openProjectToolsDocument(store);
   else if (id === DATA_ASSETS_DOCUMENT_ID) openDataAssetsDocument(store);
   else if (id === BUILD_PROFILES_DOCUMENT_ID && getEditorMode() === 'server')
     openBuildProfilesDocument(store);
@@ -286,8 +307,11 @@ async function restoreOneDocument(
     case 'data':
       if (loadedDataFiles().some((f) => f.path === doc.path)) openDataDocument(store, doc.path);
       return;
-    case 'tool':
-      openToolDocument(store, doc.toolId); // self-verifying (false = no-op)
+    case 'tool-contribution':
+      openToolDocument(store, doc.contributionId); // self-verifying (false = no-op)
+      return;
+    case 'project-tool':
+      openProjectToolDocument(store, doc.name); // self-verifying (false = no-op)
       return;
     case 'story':
       restoreStoryDocument(store, doc);
@@ -315,7 +339,9 @@ export async function restoreWorkspaceDocuments(
     return;
   }
   if (docs.open.some((d) => d.t === 'data')) await refreshDataFiles().catch(() => {});
-  if (docs.open.some((d) => d.t === 'tool')) await refreshProjectTools().catch(() => {});
+  if (docs.open.some((d) => d.t === 'project-tool')) await refreshProjectTools().catch(() => {});
+  if (docs.open.some((d) => d.t === 'tool-contribution'))
+    await refreshProjectToolContributions().catch(() => {});
   if (docs.open.some((d) => d.t === 'story')) {
     const project = getCurrentProject();
     if (project) await refreshProjectStories(project).catch(() => {});

package/template/.claude/skills/editor/SKILL.md

@@ -157,11 +157,21 @@ npm run vgai -- helpers on       # Show all helpers (lights, cameras, colliders,
 npm run vgai -- helpers off      # Hide all helpers
 npm run vgai -- stats on         # Show performance stats overlay
 npm run vgai -- stats off        # Hide stats
-npm run vgai -- shading solid    # Standard shading
-npm run vgai -- shading wireframe # Wireframe mode
-npm run vgai -- shading unlit    # Unlit/flat shading
+npm run vgai -- shading solid     # Native authored materials and lighting
+npm run vgai -- shading unlit     # Authored color/texture without lighting
+npm run vgai -- shading wireframe # Topology view
+npm run vgai -- shading normals   # Surface-normal orientation view
+npm run vgai -- shading overdraw  # Additive overlap-density view
 ```
 
+Shading is temporary, render-only editor state: it never rewrites scene or
+game materials and is not saved into a scene. Scene and Game remember separate
+session-local modes; `shading` targets whichever viewport is active. Game
+shading applies to compatible first-party Three.js roots, while React/Pixi and
+other adapter-owned layers continue rendering natively. The Scene helper menu
+also exposes independent lights, cameras, colliders, skeletons, audio, and
+bounds toggles; use `setHelperType()` through the SDK when you need one category.
+
 ### State
 
 ```bash

package/template/AGENTS.md

@@ -84,7 +84,21 @@ the real product surface.
    to pin a specific port for this project, so an old tab left open from a
    different project doesn't get mistaken for this session (see the
    `/editor` skill's CLI Reference for `--port` and `vgai sessions`).
-1. **Choose explicit adapter roots before authoring.** Every v2 manifest has
+1. **Autoplay from first playability.** Do not build most of the game and save
+   autoplay for final QA. After the ROADMAP identifies the first playable
+   behavior, adapt `scripts/playtest.ts` as the first game-specific verification
+   edit. Implement only the minimum state provider plus honest player interaction
+   needed to make that behavior playable, then stop and run `npm run playtest`
+   before expanding the game. A first run may be red; that is useful evidence,
+   not a reason to postpone the loop. For every later playable behavior, repeat:
+   edit → autoplay in the live editor → inspect state, logs, and screenshot → fix.
+   The bot must drive the real input/DOM path described under "Autoplay bots";
+   fixture commands may arrange setup but never prove the behavior. Once the
+   interaction is green, graduate it into `tests/acceptance/` and run
+   `npm run vgai -- probe` before calling the feature done. "Autoplay first"
+   means from the first honest playable seam onward—not before a behavior exists,
+   and not after the whole game has already been assembled.
+2. **Choose explicit adapter roots before authoring.** Every v2 manifest has
    a non-empty `roots` array. Each root declares its adapter directly:
    `"adapter": "react"` for DOM/layout UI and board/card/menu games,
    `"adapter": "pixijs"` for sprite/canvas gameplay, and
@@ -100,9 +114,9 @@ the real product surface.
    only game also does **not** add a Three.js/PixiJS root merely to obtain an
    `InputManager`: its real input path is the DOM, driven in playtests through
    `game.page(async (page) => page.keyboard.press(...))` or locator clicks.
-2. **Read an example.** A plain scaffold ships only a minimal default scene — no example content. The worked implementations (FPS, vehicle, third-person, RTS, multiplayer arena, IK, one-concept tutorials — see the Examples Catalog below) are standalone projects in the vgai monorepo's `examples/<id>/`. Scaffold one directly to read/copy its code: `npx create-vgai-project <name> --example <id>` (e.g. `--example third-person`) makes a correctly-rewritten standalone copy of that example, `vgai.game.json` and all. You can also open any of them live in the hosted editor at `https://vgai-editor.pages.dev/?project=<id>` (read-only — scaffold to keep edits). Otherwise, build gameplay from the Components section below.
-3. **Read the schema.** Scene format is defined by the engine's Zod schemas; the generated JSON Schema is `schemas/vscn.schema.json` inside the engine package (your tsconfig `paths` / vite alias points at the engine — the schema sits next to its `src/`). Read it before writing or editing any `.vscn.json` file. Wrong field names (e.g. `type` instead of `bodyType` in physics) silently break things. Do **not** author fields the runtime doesn't read: `gamepad_axis_pair`/`mouse_move` input bindings — these (like dead `.vscn` fields) **throw at parse** — the engine ships Zod schemas for every fetched asset format (`inputmap.schema.json` sits beside `vscn.schema.json` in the engine package). Discrete character animation (idle/walk/run/jump) is an XState machine + `bindXStateAnimation` in your own component code, not a `.vscn` field — see the engine's `packages/engine/src/animation/xstate-animation-binding.ts` and a scaffolded `--example third-person`'s `src/components.ts`.
-4. **Read `src/scripts/registry.ts`.** Every component used in a scene must be registered here. Unregistered components fail with "Component not found in registry".
+3. **Read an example.** A plain scaffold ships only a minimal default scene — no example content. The worked implementations (FPS, vehicle, third-person, RTS, multiplayer arena, IK, one-concept tutorials — see the Examples Catalog below) are standalone projects in the vgai monorepo's `examples/<id>/`. Scaffold one directly to read/copy its code: `npx create-vgai-project <name> --example <id>` (e.g. `--example third-person`) makes a correctly-rewritten standalone copy of that example, `vgai.game.json` and all. You can also open any of them live in the hosted editor at `https://vgai-editor.pages.dev/?project=<id>` (read-only — scaffold to keep edits). Otherwise, build gameplay from the Components section below.
+4. **Read the schema.** Scene format is defined by the engine's Zod schemas; the generated JSON Schema is `schemas/vscn.schema.json` inside the engine package (your tsconfig `paths` / vite alias points at the engine — the schema sits next to its `src/`). Read it before writing or editing any `.vscn.json` file. Wrong field names (e.g. `type` instead of `bodyType` in physics) silently break things. Do **not** author fields the runtime doesn't read: `gamepad_axis_pair`/`mouse_move` input bindings — these (like dead `.vscn` fields) **throw at parse** — the engine ships Zod schemas for every fetched asset format (`inputmap.schema.json` sits beside `vscn.schema.json` in the engine package). Discrete character animation (idle/walk/run/jump) is an XState machine + `bindXStateAnimation` in your own component code, not a `.vscn` field — see the engine's `packages/engine/src/animation/xstate-animation-binding.ts` and a scaffolded `--example third-person`'s `src/components.ts`.
+5. **Read `src/scripts/registry.ts`.** Every component used in a scene must be registered here. Unregistered components fail with "Component not found in registry".
 
 ### Procedural humanoids and character animation
 
@@ -126,7 +140,7 @@ with `skinToHumanoid` and `attachToBone`. The engine intentionally does not
 prescribe what that style should be.
 
 Before choosing runtime generation for a persistent player/NPC, inspect the
-project command catalog with `npm run vgai -- run --list --json`. Installed
+project tools catalog with `npm run vgai -- run --list --json`. Installed
 libraries may advertise ordinary author-time commands through their own
 `package.json`; the engine's humanoid package contributes a bake command that
 can produce a normal GLB + `.prefab.json` + provenance, with optional
@@ -163,13 +177,45 @@ For gameplay animation, preserve these contracts:
 - Acceptance evidence samples the animation state while honest input is held
   and captures representative moving poses; a screenshot taken after release
   proves only the return-to-idle frame.
-- Keep provenance beside any copied clip asset: source, author/license where
+- Commit copied clip assets through the catalog acquisition/project-output
+  boundary so `.vgai/provenance.json` records source, author/license where
   applicable, exact upstream path or catalog ID, and a content hash.
 
 The full API and retargeting policy are in the engine checkout's
 `docs/PROCEDURAL-HUMANOID.md`. The rules above intentionally do not prescribe
 a particular humanoid design or game concept.
 
+### Generative assets
+
+Generation is author-time project automation, not an engine subsystem. Use the
+provider API an ordinary developer already knows: `@fal-ai/client` for Fal and
+documented HTTP `fetch` for Tripo. Do not add a generation provider interface,
+generated-asset object model, runtime component, domain-specific editor protocol, or
+`vgai.game.json` field.
+
+- Select deterministic mock, direct/BYOK, or VGAI-managed execution in the
+  Node tool that makes the provider call. Mock first while developing;
+  never silently replace a real provider call.
+- Install provider/compatibility packages only in projects that need them;
+  they are author-time development dependencies, not default game runtime
+  dependencies.
+- Keep the useful implementation as ordinary TypeScript. Register it in
+  `package.json#vgai.tools` with a thin `src/tools/*.tool.ts` definition only
+  when agents or humans should discover and invoke it externally.
+- Download and validate output with its production reader, then commit the
+  complete accepted batch once through `ctx.projectOutputs.write(...)`.
+  Persistent tools do not write directly into `public/`.
+- Never create per-asset provenance sidecars or manually pass provider task
+  facts. The tool host records a single request or ordered task chain in
+  `.vgai/provenance.json` atomically with the ordinary project files.
+- Author through native code and files. Use the editor afterward to inspect,
+  place, and play-verify the result; editor control is observation, not the
+  generation language.
+
+See `src/tools/README.md` for the registered-tool contract and use the
+`vgai-generative-assets` skill for provider selection, cost/security, Tripo
+task chains, and media-specific validation.
+
 ## Commands
 
 ```bash
@@ -240,12 +286,8 @@ src/
   main.ts          Entry point — creates game runtime
   runtime/         Scaffold-owned standalone host wiring; game roots do not edit this
   data/            Data assets: <name>.schema.ts + emitted .schema.json + .data.json
-                   (tuning.* ships as the worked example; see src/data/README.md)
-  operations/      Project automation: <name>.operation.ts thin wrappers around ordinary
-                   functions — Node-discovered, schema-validated, never auto-bundled
-  tools/           Project tools: <name>.tool.tsx editor panels (center document or
-                   inspector section) — editor-only, never bundled
-                   (example.tool.tsx + spin.tool.tsx ship; see src/tools/README.md)
+  tools/           Registered ordinary callables plus optional React surfaces
+                   (`package.json#vgai.tools`; see src/tools/README.md)
   scripts/
     registry.ts    Component registry (GameComponent classes)
     components/    Custom GameComponent classes
@@ -301,41 +343,28 @@ The project has a small set of fundamental concepts, each with one home:
   inspector (and designers, and VS Code) edit — shared/global definitions and
   tuning, as opposed to per-entity component config. See "Tunable values → a
   data asset" under One Canonical Way.
-- **Tools** — *how you tune it*: project-authored React panels
-  (`src/tools/*.tool.tsx`) the editor discovers automatically. Placements:
-  `placement: 'document'` (a center workspace document, opened from the
-  command palette — `'dock'` is a deprecated alias — project-global
-  dashboards), `placement: 'utility'` (a bottom utility tab for transient
-  output), and `placement: 'inspector'` with a
-  `match: (node, adapter) => boolean` predicate (a ⚙ section in the Inspector
-  for matching selections). Each tool file exports `tool = defineTool({...})`
-  (from `@engine/tools/define-tool`) plus a default React component; build
-  the panel from `@editor/widgets` (the editor's own widget kit + THEME
-  tokens) so it looks native. `src/tools/example.tool.tsx` (document) and
-  `spin.tool.tsx` (inspector) ship as worked examples — both live-tune
-  `src/data/tuning.data.json` through `useData`/`writeData`
-  (`@engine/react/use-data`) and the running game follows via HMR. An
-  inspector tool can also read the selected entity's OWN component config —
-  `useSelection()` (`@engine/react/use-selection`) returns the selected node,
-  its attached components, and each component's authored config, live.
-  Tools are editor-only dev surfaces, stripped from shipped games by
-  construction: `npm run build` bundles only what `index.html` →
-  `src/main.ts` imports, and nothing in game code imports `src/tools/`.
-- **Operations** — *how reusable project automation becomes discoverable*:
-  ordinary JS/TS functions remain the implementation and may be imported
-  directly by game code. A thin `src/operations/*.operation.ts` module exports
-  `operation = defineOperation({...})` from `@vgai/sdk/registry`, declaring
-  Zod input/result schemas, host, mutation, and permission metadata. No manual
-  registry or manifest entry exists: the editor scans the folder and exposes a
-  Project Commands catalog plus a default JSON/schema runner. Agents use `npm run vgai -- run --list --json`
-  to discover capabilities and `npm run vgai -- run <name>` to invoke one
-  (add `--input <file>` and `--yes` when needed). Keep the wrapper free of
-  React/editor imports; a custom interface is an optional
-  `src/tools/*.tool.tsx` that calls it through `@vgai/editor-sdk`. Files it
-  persists under `public/` are ordinary project assets and refresh the Assets
-  navigator after a successful mutation; the tool itself is not an asset. A
-  generator is simply an operation whose native function generates content,
-  not a new engine kind. See `src/operations/README.md`.
+- **Tools** — ordinary JS/TS functions that need external discovery or
+  invocation. Register callable modules explicitly in
+  `package.json#vgai.tools`; each exports `tool = defineTool({...})` from
+  `@vgai/sdk/tools`, declaring Zod input/result schemas, host, mutation, and
+  permission metadata around an ordinary directly importable implementation.
+  Every registration appears in the editor's Project Tools catalog and
+  schema-driven fallback form, `vgai run`, and `@vgai/live`'s
+  `tools.list()`/`tools.call()`. A registration may list ordinary React modules
+  under `contributions`; each default component receives `{tool, client}`,
+  calls the same registered tool through `client.runProjectTool(tool.name,
+  ...)`, and never owns a second implementation. Contribution points are
+  `workspace.document`, `workspace.utility`, and selection-scoped
+  `selection.inspector` (which also exports `match(node, adapter)`). Prefer a
+  focused custom contribution for a substantial workflow. Build it with React
+  directly for layout and state, and use `@editor/widgets` for shared editor
+  controls so focus, disabled, density, and theme behavior stay native. Editor
+  SDK hooks remain optional helpers. The starter's
+  `project.tuning` and `project.autoplay` are deliberately unconfigured real
+  tools: replace their schemas and ordinary implementations for this game.
+  Files a tool persists under `public/` are ordinary project assets; the tool
+  itself is not an asset. Generators, autoplay, tuning, and validation all use
+  this same thin registered-callable boundary. See `src/tools/README.md`.
 
 ## Components
 
@@ -437,11 +466,10 @@ For each common job there is exactly ONE recommended approach. Use it — compet
   ```
   Read `tuning.get()` live where the value is used (e.g. each frame) — don't
   copy fields out at init, or HMR edits won't reach them. `subscribe(fn)` fires
-  on every hot edit. **This project ships the pattern working**: the trio in
-  `src/data/` (`tuning.schema.ts` / emitted `tuning.schema.json` /
-  `tuning.data.json`), the handle (`src/data/tuning.ts`), and a consumer
-  (`DataSpinner` on the default scene's Box — press ▶, edit the JSON, watch it
-  change live). Add a data asset by copying that trio AND registering it in
+  on every hot edit. The starter's tuning schema and registered tuning tool
+  are intentionally empty stubs: define game-specific fields, consume them
+  through the existing handle, and replace the tool's input/UI before claiming
+  tuning works. Add a data asset by copying that trio AND registering it in
   `src/data/assets.ts` (the one shared list); after every schema change run
   `npm run emit-schemas` (commits the emitted `.schema.json` so VS Code
   validates the data file with no dev server). Rows in table-shaped assets
@@ -655,7 +683,7 @@ a level-3 spec before calling the feature done.
 
 ### Level 2 — inner-loop autoplay with `@vgai/live`
 
-`@vgai/live` is `{ editor, game, page }` over the SAME session wire `vgai
+`@vgai/live` is `{ editor, game, page, tools }` over the SAME session wire `vgai
 probe --in-editor` uses (and, since probe now defaults to that transport
 whenever a session is open, the same wire `vgai probe` uses by default too)
 — a plain node/tsx script, not a test file, not a fixture, no config. It
@@ -663,18 +691,12 @@ never starts a session; it only ATTACHES to one already running (`vgai edit`
 — you likely have this open already), and every method rejects with a
 "run `vgai edit` first" error if none exists.
 
-```ts
-// scripts/playtest.ts (see the worked copy already in this project)
-import { editor, game } from '@vgai/live';
-
-await editor.play();                                       // enters play mode; waits for the game's full async setup
-await game.command('spinner.reset');                        // fixture (declared cheat) — jump to a known state
-await game.input.whileHeld('attack', async () => {           // proof + evidence while input is active
-  await game.waitFor((s) => (s('spinner') as { speed: number }).speed > 2,
-    { simSeconds: 10 });
-  await game.screenshot('during-boosted-spin');
-});
-```
+`scripts/playtest.ts` invokes the same ordinary `runAutoplay()` implementation
+as the registered `project.autoplay` tool. Implement that function with
+`editor`, `game`, and `page` from `@vgai/live`; agents may then run the exact
+same callable through `tools.call('project.autoplay')`. It deliberately throws
+`TOOL_NOT_CONFIGURED` in a fresh scaffold so an untouched placeholder can
+never masquerade as acceptance evidence.
 
 Run it with `npx tsx scripts/playtest.ts`. No browser of its own boots, no
 Vite cold start, no watchdog racing a fresh game boot — it rides the tab
@@ -812,25 +834,21 @@ Disambiguation: `vgai doctor` asks "does this project mount in the editor?";
    a bare test `Game` may not carry a registry; a real runtime always does):
    ```ts
    init(ctx: GameContext) {
-     ctx.debug?.registerStateProvider('spinner', () => ({ laps: this.laps }));
-     // Fixture, never a proof (D16) — a declared cheat for test setup:
-     ctx.debug?.registerCommand('spinner.reset', { description: 'Reset laps.', locus: 'client' },
-       () => { this.laps = 0; });
-   }
-   update(dt: number, ctx: GameContext) {
-     if (lapJustCompleted) ctx.debug?.emit('spin-lap', { laps: this.laps });
+     ctx.debug?.registerStateProvider('session', () => ({ phase: this.phase }));
+     // Fixtures are allowed for setup, never as proof of behavior:
+     ctx.debug?.registerCommand('session.reset',
+       { description: 'Reset the session.', locus: 'client' }, () => this.reset());
    }
    ```
-   Worked example: `src/scripts/components/data-spinner.ts`. Two built-in
-   providers exist with zero game code: `time` (`{ simSeconds, tick }`) and
+   Two built-in providers exist with zero game code: `time` (`{ simSeconds, tick }`) and
    `input.actions`. Once the project declares a Colyseus room, every command
    must declare `locus: 'client' | 'server'` — server-locus commands run on
    the authoritative copy, not client prediction. In a react world or HUD
    component, use the hooks instead: `useDebugProvider(name, fn)` /
    `useDebugCommand(name, spec, fn)` / `const emit = useDebugEmit()` directly
    from `@engine/react/game-state` — the same game-scoped registry, with
-   providers/commands auto-unregistered on unmount. Emit events with
-   `emit('spin-lap', { laps })`; never import or reach through the internal
+   providers/commands auto-unregistered on unmount. Emit game-owned events
+   through that hook; never import or reach through the internal
    debug registry from game code.
 2. **Copy `tests/acceptance/example.spec.ts`** and swap in your own
    provider/command/action names. (If it's missing, `vgai probe --init`
@@ -893,13 +911,12 @@ A spec is plain Playwright with one import:
 ```ts
 import { test, expect } from '@vgai/probe';
 
-test('boosting the spinner completes a lap', async ({ game }) => {
-  await game.command('spinner.reset');                     // fixture (declared cheat)
-  await game.input.hold('attack', { simSeconds: 4 });      // proof: the honest input path
-  await game.waitFor((s) => (s('spinner') as { laps: number }).laps >= 1,
-    { simSeconds: 10 });
-  await game.events.expect(['spin-lap']);                  // ordered subsequence since test start
-  await game.screenshot('after-boosted-spin');
+test('the primary interaction changes observable game state', async ({ game }) => {
+  await game.command('session.reset');                    // fixture only
+  await game.input.tap('primary');                        // proof: honest input path
+  await game.waitFor((s) =>
+    (s('session') as { phase: string }).phase === 'active', { simSeconds: 10 });
+  await game.screenshot('primary-interaction');
 });
 ```
 

package/template/package.json

@@ -4,6 +4,22 @@
   "private": true,
   "version": "0.1.0",
   "type": "module",
+  "vgai": {
+    "tools": [
+      {
+        "entry": "./src/tools/tuning.tool.ts",
+        "contributions": [
+          {
+            "id": "tuning",
+            "point": "workspace.document",
+            "title": "Tuning",
+            "entry": "./src/tools/tuning.document.tsx"
+          }
+        ]
+      },
+      "./src/tools/autoplay.tool.ts"
+    ]
+  },
   "engines": {
     "node": ">=22.0.0"
   },

package/template/public/scenes/default.vscn.json

@@ -35,8 +35,7 @@
       "mesh": { "type": "box", "args": [1, 1, 1] },
       "material": { "type": "standard", "color": "#4488ff" },
       "transform": { "position": [0, 0.5, 0] },
-      "shadow": { "enabled": true },
-      "components": { "DataSpinner": { "spinScale": 1 } }
+      "shadow": { "enabled": true }
     },
     {
       "id": "af6855d6-9bf9-47f3-bcb1-d5e6843c97bd",

package/template/scripts/playtest.ts

@@ -1,40 +1,10 @@
 /**
- * Inner-loop autoplay (see AGENTS.md's "Autoplay bots" — Level 2). A plain
- * `@vgai/live` script: no test runner, no Playwright config, no fixture, no
- * second browser. It ATTACHES to the live `vgai edit` session/tab you
- * already have open (run `vgai edit .` first if you don't) and drives it
- * with the SAME `GameClient` vocabulary `tests/acceptance/example.spec.ts`
- * uses — compare the two side by side; the difference in ceremony is the
- * whole point.
- *
- * Run: `npm run playtest` (or `npx tsx scripts/playtest.ts`). Nothing here
- * is committed evidence — it's scratch space for "does my game work right
- * now". Once an interaction proves a feature, graduate it into a spec under
- * `tests/acceptance/` (`vgai probe --init` scaffolds the first one).
- *
- * Drives the template's shipped example component, `DataSpinner`
- * (`src/scripts/components/data-spinner.ts`) — replace this with your own
- * provider/command/action names as your first real edit.
+ * The npm shortcut invokes the same implementation as project.autoplay.
+ * Replacing `runAutoplay` is the first game-specific verification edit; run
+ * it at first playability and do not wait until the rest of the game exists.
  */
+import { runAutoplay } from '../src/tools/autoplay';
 
-import { editor, game } from '@vgai/live';
-
-await editor.play(); // enters play mode; the ack waits for the game's full async setup
-
-// Fixture (declared cheat, D16) — jump to a known state. Never a substitute
-// for the honest-input proof below.
-await game.command('spinner.reset');
-
-// Proof: the same honest input path a human's keys hit (see
-// public/inputmaps/default.inputmap.json's 'attack' binding).
-await game.input.hold('attack', { simSeconds: 4 });
-
-await game.waitFor((s) => (s('spinner') as { lapsCompleted: number }).lapsCompleted >= 1, {
-  simSeconds: 10,
-});
-
-const spinner = (await game.state('spinner')) as { lapsCompleted: number };
-console.log(`spinner lapsCompleted: ${spinner.lapsCompleted}`);
-
-const shot = await game.screenshot('playtest-after-boosted-spin');
-console.log(`screenshot: ${shot}`);
+const result = await runAutoplay();
+// biome-ignore lint/suspicious/noConsole: this executable npm script reports its structured result to the caller
+console.log(JSON.stringify(result, null, 2));

package/template/server/rooms/game-room.ts

@@ -60,8 +60,8 @@ let nextOrbId = 0;
 
 /**
  * The `locus: 'server'` debug-command table (Task 4.2) — one worked example,
- * `give-score`, mirroring the client-side `DataSpinner.spinner.reset` fixture
- * (`src/scripts/components/data-spinner.ts`): mutates the AUTHORITATIVE
+ * `give-score`, demonstrating the same declared-fixture rule as client-side
+ * debug commands: mutates the AUTHORITATIVE
  * (server) copy of state, never client prediction. Gated by
  * `allowDebugCommands` — see `onCreate` — so a production `npm run server`
  * boot never accepts these unless explicitly opted in.

package/template/src/data/README.md

@@ -3,8 +3,9 @@
 Designer-tunable values live here: `<name>.data.json` (the values, with a
 `"$schema"` line) governed by `<name>.schema.ts` (Zod, engineer-owned) and its
 emitted `<name>.schema.json` (`npm run emit-schemas`, committed). `tuning.*` +
-`tuning.ts` (the engine `defineData` handle) are the shipped worked example —
-copy that trio for each new asset and register it in `assets.ts` (one list,
+`tuning.ts` (the engine `defineData` handle) are an intentionally empty starter
+contract—define real fields and consumers for this game, then register each
+new asset in `assets.ts` (one list,
 feeding both `npm run emit-schemas` and the build-time check that fails
 `npm run build` loud on invalid data or a dangling `"file#key"` ref; `vgai
 doctor <folder>` runs the same checks). Never hardcode a tunable as a constant in

package/template/src/data/tuning.data.json

@@ -1,5 +1,3 @@
 {
-  "$schema": "./tuning.schema.json",
-  "boxSpinSpeed": 0.8,
-  "boxColor": "#4488ff"
+  "$schema": "./tuning.schema.json"
 }

package/template/src/data/tuning.schema.json

@@ -2,18 +2,6 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "boxSpinSpeed": {
-      "default": 0.8,
-      "description": "Demo box spin speed, radians/sec — edit tuning.data.json while playing to see live tuning",
-      "type": "number",
-      "minimum": -5,
-      "maximum": 5
-    },
-    "boxColor": {
-      "default": "#4488ff",
-      "description": "Demo box color (hex)",
-      "type": "string"
-    },
     "$schema": {
       "type": "string"
     }

package/template/src/data/tuning.schema.ts

@@ -21,14 +21,7 @@
  */
 import { z } from 'zod';
 
-export const TuningSchema = z.object({
-  boxSpinSpeed: z
-    .number()
-    .min(-5)
-    .max(5)
-    .default(0.8)
-    .describe('Demo box spin speed, radians/sec — edit tuning.data.json while playing to see live tuning'),
-  boxColor: z.string().default('#4488ff').describe('Demo box color (hex)'),
-});
+// Intentionally empty: define this game's actual tuning contract before use.
+export const TuningSchema = z.object({});
 
 export type Tuning = z.infer<typeof TuningSchema>;

package/template/src/data/tuning.ts

@@ -13,7 +13,7 @@
  *
  * Consume with `tuning.get()` INSIDE your update loop every frame (never
  * cache fields across frames, or live tuning silently stops working for that
- * field) — see `src/scripts/components/data-spinner.ts` for the worked use.
+ * field).
  */
 import { defineData } from '@engine/data/data-asset';
 import raw from './tuning.data.json';

package/template/src/scripts/registry.ts

@@ -15,12 +15,10 @@
 
 import type { GameComponentClass } from '@engine/ecs/game-component';
 import type { ComponentRegistry } from '@engine/scene/component-registry';
-import { DataSpinner } from './components/data-spinner';
 import { SceneCamera } from './components/scene-camera';
 
 export const componentRegistry = {
   // GameComponent classes (OOP components with true HMR)
-  DataSpinner,
   SceneCamera,
 } satisfies ComponentRegistry;
 
@@ -41,6 +39,5 @@ export function getComponent(name: ComponentName): GameComponentClass {
 
 /** GameComponent classes for true HMR. Keyed by class name. */
 export const gameComponents: Record<string, GameComponentClass> = {
-  DataSpinner,
   SceneCamera,
 };