@volter/game-editor 0.5.65

package/template/.volter/tracker/validation/preset.mts

@@ -0,0 +1,186 @@
+// A game-roadmap preset. Each issue is one game-level feature arc with a title,
+// one lifecycle status, and one required Summary description. Acceptance
+// criteria remain parseable for future use but are not scaffolded: the initial
+// roadmap task is the complete playable prototype, proven by the game's
+// autoplay record and analytics/readouts rather than a checklist here.
+//
+// Hard schema = the core fields (id/title/summary/status, id/status/evidence,
+// id) PLUS preset-specific strict fields (a status enum, AC `text`, evidence
+// `commit`). No passthrough, no unknown.
+
+// A STANDALONE preset: imports ONLY the public mechanism from `ztrack/preset-kit`.
+import {
+  z, toMdast, nodeText, type MdNode,
+  check as runCheck, rule, gitWorld,
+  type Context, type IssueColumns, type IssueRecord, type Preset, type VisualizerSpec,
+} from 'ztrack/preset-kit';
+
+// ── the hard schema (core + preset-specific, all strict) ────────────────────
+export const SpecEvidenceSchema = z.object({
+  id: z.string().min(1),                              // core
+  commit: z.string().regex(/^[0-9a-f]{7,40}$/),       // preset: evidence is commit-backed
+}).strict();
+
+export const SpecAcStatusSchema = z.enum(['pending', 'passed', 'failed']); // preset's status vocabulary
+export const SpecAcSchema = z.object({
+  id: z.string().min(1),                              // core
+  status: SpecAcStatusSchema,                          // core (preset narrows the type)
+  evidence: z.array(SpecEvidenceSchema),              // core
+  text: z.string().min(1),                            // preset
+}).strict();
+
+export const SpecIssueStatusSchema = z.enum(['draft', 'in-review', 'done']);
+export const SpecIssueSchema = z.object({
+  id: z.string().min(1),                              // core
+  title: z.string().min(1),                           // core
+  summary: z.string().min(1),                         // core; every roadmap task explains its arc
+  status: SpecIssueStatusSchema,                       // core (narrowed)
+  acceptanceCriteria: z.array(SpecAcSchema),          // core
+}).strict();
+
+export const SpecRootSchema = z.object({ issues: z.array(SpecIssueSchema) }).strict();
+export type SpecRoot = z.infer<typeof SpecRootSchema>;
+
+// ── mdast parse: markdown -> the schema shape (structured, no prose mining) ──
+// MdNode / toMdast / nodeText are rented from the kit (shared mdast mechanism).
+function firstParagraphText(item: MdNode): string {
+  const p = (item.children ?? []).find((c) => c.type === 'paragraph');
+  return p ? nodeText(p).split('\n')[0]!.trim() : '';
+}
+
+// designated-position parses (the AC line, the evidence line) — not free-prose mining.
+function splitAcIdText(line: string): { id: string; text: string } {
+  const m = /^(\S+)\s+(.+)$/.exec(line);
+  return m ? { id: m[1]!, text: m[2]!.trim() } : { id: line, text: line };
+}
+
+function parseSpecIssue(record: IssueRecord): Record<string, unknown> {
+  // id/title/status come STRUCTURED from the record's columns; only summary + ACs are
+  // parsed from the body.
+  const issue: Record<string, unknown> = { id: record.id, title: record.title, status: record.status || 'draft', summary: '', acceptanceCriteria: [] };
+  const tree = toMdast(record.body);
+  let inAc = false;
+
+  for (const node of tree.children ?? []) {
+    if (node.type === 'heading') {
+      inAc = /acceptance criteria/i.test(nodeText(node));
+      continue;
+    }
+    if (node.type === 'paragraph') {
+      const summary = /^Summary:\s*(.+)$/im.exec(nodeText(node))?.[1]?.trim();
+      if (summary) issue.summary = summary;
+      continue;
+    }
+    if (node.type === 'list' && inAc) {
+      const acs: unknown[] = [];
+      for (const item of node.children ?? []) {
+        if (item.type !== 'listItem') continue;
+        const { id, text } = splitAcIdText(firstParagraphText(item));
+        const status = item.checked === true ? 'passed' : 'pending';
+        const evidence: unknown[] = [];
+        const nested = (item.children ?? []).find((c) => c.type === 'list');
+        for (const evItem of nested?.children ?? []) {
+          const commit = /commit:\s*([0-9a-fA-F]+)/.exec(firstParagraphText(evItem))?.[1]?.toLowerCase();
+          if (commit) evidence.push({ id: `${id}/ev${evidence.length + 1}`, commit });
+        }
+        acs.push({ id, status, text, evidence });
+      }
+      issue.acceptanceCriteria = acs;
+    }
+  }
+  return issue;
+}
+
+// The root: each issue's metadata is structured (its record's columns); content from body.
+export function parseSpec(records: IssueRecord[]): unknown {
+  return { issues: records.map(parseSpecIssue) };
+}
+
+// ── serialize: the validated issue -> its STORED form (content body + metadata columns) ──
+// The evidence id is positional (`<acId>/ev<n>`), so it isn't emitted — re-parsing
+// regenerates it. A passed AC is the checked box; pending/failed are unchecked.
+export function serializeSpecIssue(issue: SpecRoot['issues'][number]): { body: string; columns: IssueColumns } {
+  const out: string[] = [];
+  if (issue.summary) out.push(`Summary: ${issue.summary}`, '');
+  if (issue.acceptanceCriteria.length > 0) {
+    out.push('## Acceptance Criteria', '');
+    for (const ac of issue.acceptanceCriteria) {
+      out.push(`- [${ac.status === 'passed' ? 'x' : ' '}] ${ac.id} ${ac.text}`);
+      for (const ev of ac.evidence) out.push(`  - commit: ${ev.commit}`);
+    }
+  }
+  return { body: out.join('\n') + '\n', columns: { title: issue.title, status: issue.status } };
+}
+
+// ── rules: declarative records over the engine's derived model ──────────────
+// Duplicate-id detection is universal, so it arrives on the core model (m.duplicateAcIds
+// / m.duplicateIssueIds) — this preset writes no derive and uses no blocking graph.
+type SpecAC = SpecRoot['issues'][number]['acceptanceCriteria'][number];
+type SpecEvidence = SpecAC['evidence'][number];
+
+const shaMatches = (a: string, b: string) => a.startsWith(b) || b.startsWith(a);
+
+const SPEC_RULES = [
+  rule<SpecRoot, Record<string, never>>({
+    code: 'roadmap_empty',
+    severity: 'warning',
+    select: (m) => (m.root.issues.length === 0 ? [{}] : []),
+    message: () =>
+      'Roadmap is empty. Before coding, add one carefully scoped task for the complete playable prototype, including game-owned autoplay and gameplay analytics.',
+  }),
+  // Evidence is opt-in for a game: a checked box is done, and the real proof lives in the
+  // playtest record. Restore ztrack's `passed_ac_missing_evidence` rule here to require it.
+  rule<SpecRoot, { issueId: string; acId: string; evidenceId: string; ev: SpecEvidence }>({
+    code: 'evidence_commit_not_found', select: (m) => m.evidence,
+    when: ({ ev }, m) => { const c = m.context.git?.existingCommits; return !!c && !c.some((x) => shaMatches(x, ev.commit)); },
+    message: ({ ev }) => `Evidence ${ev.id} cites commit ${ev.commit}, which does not exist.`,
+    subject: ({ ev }) => ev.commit,  // the missing sha — a `ref:` waiver pins to exactly this occurrence
+  }),
+  rule<SpecRoot, { issueId: string; acId: string }>({
+    code: 'duplicate_ac_id', select: (m) => m.duplicateAcIds,
+    message: ({ acId }) => `Duplicate AC id ${acId}.`,
+  }),
+  rule<SpecRoot, { issueId: string }>({
+    code: 'duplicate_issue_id', select: (m) => m.duplicateIssueIds,
+    message: ({ issueId }) => `Duplicate issue id ${issueId}.`,
+  }),
+];
+
+// ── the dashboard's vocabulary (VIZ-2), as plain data ────────────────────────────────────────
+// spec's OWN vocabulary — NOT simple-sdlc's default.tsx vocabulary, which this preset's schema
+// doesn't share: a 3-state lifecycle (no ready/in-progress split), no assignee, no PR, and an AC
+// with just id/text (no version, no proof, no image/acVersion-bearing evidence — see
+// SpecAcSchema/SpecEvidenceSchema above). Only map fields this schema actually has; a mapping
+// this preset can't back with a real field (pr, acProof, acEvidence) is simply omitted. Field
+// references and literal labels ONLY (see `VisualizerSpec`, `ztrack/preset-kit`) — no functions,
+// no markup. Installed into your repo verbatim: edit freely, keeping statusOrder in sync with
+// SpecIssueStatusSchema above (`boilerplates/presets/visualizerVocabulary.test.ts` checks that).
+const SPEC_VISUALIZER: VisualizerSpec = {
+  statusOrder: ['draft', 'in-review', 'done'], // must equal SpecIssueStatusSchema above
+  acUnitLabel: 'Acceptance Criteria',
+  acText: { id: 'id', text: 'text' },          // SpecAcSchema.{id,text} — no `version` field to map
+  // no assignee/pr: SpecIssueSchema has neither. No acProof: SpecAcSchema has no proof field.
+  // No acEvidence: SpecEvidenceSchema is only {id, commit} — no image/acVersion fields to map.
+};
+
+export const SpecPreset: Preset<SpecRoot> = {
+  name: 'spec',
+  schema: SpecRootSchema,
+  visualizer: SPEC_VISUALIZER,
+  // observed facts: commit existence (no PR model in this preset).
+  loadContext: (input) => gitWorld(input.projectRoot, [], { verifyCommits: input.verifyCommits }),
+  parse: parseSpec,
+  serialize: serializeSpecIssue, // issue -> { body, columns }; the inverse of parse
+  rules: SPEC_RULES,
+  // A new task starts with its feature-arc description and one lifecycle status supplied by
+  // the document record. Acceptance criteria are intentionally not invented at this stage.
+  scaffold: (_title) =>
+    'Summary: Describe the complete playable prototype or later major game feature.\n',
+};
+
+export function checkSpec(records: IssueRecord[], ctx?: Context) {
+  return runCheck(SpecPreset, records, ctx);
+}
+
+// The installed entrypoint: the resolver reads the preset off `default`.
+export default SpecPreset;

package/template/.volter/tracker/visualizer/.extension.base.tsx

@@ -0,0 +1,14 @@
+// Your repo-owned dashboard extension (see docs/VISUALIZER.md). It compiles into the served
+// board automatically — no config, no restart. Every member below is optional; this file ships
+// as a no-op, so the stock board is what you get until you fill one in.
+//
+// import { defineVisualizerExtension } from 'ztrack/visualizer-kit';
+//
+// export default defineVisualizerExtension({
+//   issuePanels: (issue) => <section className="panel">...</section>,
+//   acText: (ac) => ac.id,
+// });
+
+import { defineVisualizerExtension } from 'ztrack/visualizer-kit';
+
+export default defineVisualizerExtension({});

package/template/.volter/tracker/visualizer/extension.tsx

@@ -0,0 +1,14 @@
+// Your repo-owned dashboard extension (see docs/VISUALIZER.md). It compiles into the served
+// board automatically — no config, no restart. Every member below is optional; this file ships
+// as a no-op, so the stock board is what you get until you fill one in.
+//
+// import { defineVisualizerExtension } from 'ztrack/visualizer-kit';
+//
+// export default defineVisualizerExtension({
+//   issuePanels: (issue) => <section className="panel">...</section>,
+//   acText: (ac) => ac.id,
+// });
+
+import { defineVisualizerExtension } from 'ztrack/visualizer-kit';
+
+export default defineVisualizerExtension({});

package/template/.volter/tracker-config.json

@@ -0,0 +1,17 @@
+{
+  "backend": "markdown",
+  "local": {
+    "teamKey": "LOCAL"
+  },
+  "board": "shared",
+  "validation": {
+    "entrypoint": ".volter/tracker/validation/preset.mts",
+    "installedFrom": "spec"
+  },
+  "sources": [
+    {
+      "path": "ROADMAP.md",
+      "format": "document"
+    }
+  ]
+}

package/template/AGENTS.md

@@ -0,0 +1,176 @@
+# AGENTS.md — VGAI Game Project
+
+A standalone game built with VGAI — work here, not in the engine repo.
+The editor is the authoring and verification surface.
+
+## Route the request first
+
+| Intent | First action |
+| --- | --- |
+| Build or change this game | This file + the relevant `.agents/references/project-manual.md` section |
+| Open, play, or verify it | `.agents/skills/editor/SKILL.md` |
+| Model or revise a game prop with Blender | `.agents/skills/vgai-3d-models/SKILL.md` |
+| The game needs a 3D asset placed, rigged, or baked | `.agents/skills/vgai-3d-assets/SKILL.md` |
+| Other craft (2D/3D art, animation, humanoids, generated assets) | The matching `.agents/skills/vgai-*/SKILL.md` |
+| Import an existing web game | Read-only compatibility report; never rewrite its source |
+| Browse or modify an example | Read-only, or scaffold a copy; user games never go in `examples/` |
+
+`.agents/` is canonical; `.claude/skills/` and `.github/skills/` are
+generated projections (never edit); `CLAUDE.md` and
+`.github/copilot-instructions.md` only point here.
+
+**Capabilities are this project's standard libraries, and they are ADDED.**
+Before writing reusable plumbing, run
+bare `npm run --silent vgai -- add` (lists), inspect the match, and `add <id>` it —
+the installed source is project-owned and editable. A doc naming
+`src/lib/<x>` describes what that capability installs.
+
+## Before writing code
+
+1. Read the brief; write the initial `ROADMAP.md` task first (shape:
+   the ROADMAP rule below).
+2. Read `vgai.project.json` — each root's `adapter` owns its document
+   and lifecycle; read the root entry files and any data schema before
+   editing. `src/main.ts` registers each root's adapter (`three`, `dom`).
+3. Start the editor now (`npm run dev`); tell the user the URL in your
+   FIRST visible message. Keep it running and narrate as you build. The
+   editor IS the Code-OSS workbench this machine declares in
+   `.vgai/workbench.json` (the product's `create --workbench <dir>` writes it); with
+   no declaration `npm run dev` refuses and prints the exact JSON to write —
+   write it, do not work around it.
+4. Multiplayer: every SEAT is a person — an INSTANCE in one editor,
+   played by its resident tester (`game.instance(id)` → the running
+   `tester-station.ts` module's `hireTester`) or a human via handoff; never a
+   second browser or synthetic player.
+
+Everything else is in the project manual; read only the sections the
+request needs.
+
+## Non-negotiable rules
+
+- **Author in playable slices, playtested LIVE by two people: you are
+  the DEVELOPER, the bot is your QA TESTER.** All in-game action is the
+  tester's honest input at sim speed, directed by calling `hireTester` on the
+  running `src/bot/tester-station.ts` module,
+  never by sending inputs yourself. The playtest is INTERACTIVE; its
+  receipt is the play log — never a script.
+- **A control is done when ITS OWN CLICK visibly changes something.**
+  Acceptance for any face control is driving the control itself in the live
+  session (a DOM click through `game.run`) and seeing a change a human would
+  see—never merely calling the function it wraps. An action whose success can
+  be invisible (for example, a goal completing before the next paint) must
+  narrate itself in the face.
+- **Development panels are game-specific.** The `game` starter includes required
+  Inspector, Data and Analytics stubs; replace them with useful fields and controls.
+  The `prototype` starter omits them. Any panels you add must use game vocabulary,
+  not raw JSON or generic event lists. The editor already provides session playback.
+- **Every mechanic ships its debug function and readout in the same slice.**
+  Export them beside the mechanic for the REPL and tester; provide setup helpers
+  for situations that are costly to reach through normal play.
+- **Keep game data in typed `src/data/` modules named for the mechanic or content.**
+  Editor panels read that data; they do not determine its storage shape.
+- Use the real audio adapter even when the game is silent.
+- Contributions live in `src/contributions/`. Use `use-game-modules.ts` for live
+  state and the selected Gameplay Session for Analytics. Implementation details
+  are in the project manual's Studio surfaces section.
+- **Game-level feature arcs live in `ROADMAP.md` — one file.** Task one
+  is the complete playable prototype from the brief — mechanics,
+  rendering, UI, tooling, readouts are parts of it, not peer tasks; later
+  entries are only major features of comparable scope. One `Summary:` and
+  one lifecycle `status:` each; no acceptance criteria yet; never a
+  second task file; never done before a DEVLOG'd live playtest proves
+  the arc (`ztrack check` verifies structure).
+- **`DEVLOG.md` is the development journal, not a second tracker.** One
+  entry per arc: what changed, why, decisions, playtest outcome, what
+  remains — with reviewed screenshots (a clip when motion matters)
+  promoted from `.vgai/` history into `media/`; inspect every artifact
+  you attach, never the latest blindly.
+- **Record through the eval door**: Play running →
+  `eval 'return editor.recording.start({ fps: 30 })'`, drive via
+  `game.*`, `eval 'return editor.recording.stop()'` → WebM under
+  `.vgai/recordings/`. Inspect/trim with ordinary `ffmpeg`; no wrappers.
+- **Keep Three source modular:** thin `src/world.tsx`; compositions in
+  `src/scenes/*Scene.tsx` (no stories); placeables in `src/prefabs/` with
+  stories; support in `src/components/`. Owned parts stay inside their
+  owner; independent entities never hide in scenery; no monoliths, no
+  prefab-per-primitive. E10/E11 enforce declared classifications and W10
+  warns when a Three project silently loses all prefabs. Characters are ALWAYS rigged models
+  authored in Blender (`vgai-3d-models`), never primitive stacks.
+- Use Three.js, PixiJS, React, Rapier, and Colyseus directly — no
+  wrappers, no parallel ECS or mirror tree.
+- The world node is the entity. On a TSX root, behavior is a React
+  component calling `useFrame`; physics is `@react-three/rapier` JSX.
+  Debug state is ordinary exported functions in the game's own modules —
+  reached via `game.run` and the contributions the game writes. Static
+  scenery, lights, and UI stay native objects.
+- The source is the document: TSX for a Three root, JSX for React; an
+  unrecognized manifest key is rejected. Never call `createRoot`,
+  `hydrateRoot`, or `ReactDOM.render` from project code.
+- One component, one concern.
+- A player HUD is a `dom` root, never drei `Html` (invisible in
+  captures).
+- Never fabricate first-party data, modify imported game source without
+  consent, or author schema fields with no runtime reader. The game's
+  numbers and tables are plain typed literals under `src/data/`.
+- Preserve existing user edits and unrelated files.
+- Generated assets: provider-native APIs + `ctx.projectOutputs.write(...)`;
+  load the generative-assets skill before spending funds.
+- Keep reference images and motion studies in `references/`; Content shows
+  them without shipping them. Put assets the game loads in `public/`.
+- Repeatable sequences: flat scripts in `scripts/<task>/steps/` (README
+  per step); intermediates in `.vgai/tmp/<task>/`. Helpers in
+  `src/lib/<domain>/` only when reusable and purely mechanical; no
+  runners, task graphs, or auto-judges.
+- Editor control is observation and verification; write through source
+  edits, not UI automation. `npm run dev:standalone` serves EXPORTED
+  builds only — until exported it refuses; the editor is the one surface.
+
+## Verification contract — after every slice
+
+**Never write automated tests — no vitest, no `tests/` (E12 enforces).**
+Games are fundamentally unpredictable; pre-written assertions enter an
+endless rewrite cycle. Playtest live; the play log is the receipt.
+
+1. Run `check-idioms`, `typecheck`, `validate`, and `validate-manifest`.
+   **`npm run typecheck` is the gate, never bare `tsc`** (bare `tsc`
+   skips `src/tools`).
+2. The ONLY approved slice test is LIVE: a REPL-style manual session in
+   the editor-owned tab — set up, enter Play, advance sim time, inspect,
+   act one step at a time. Keep the probe disposable (never a spec,
+   script, or harness). After init-time edits, `restart`.
+3. `npx volter-game-editor status` must show `connected: true`; it tails the session
+   journal (`logs/editor-*.jsonl`). Read the play logs. Any
+   `UNRESOLVED CONSOLE SET` is remaining work; `npx volter-game-editor console` silent is
+   the only all-clear.
+4. Enter Play and look. Capture a legible screenshot; **a hidden tab
+   captures t≈0** — drive `game.waitSimTime` first.
+5. Drive the game with `npm run --silent vgai -- eval '<js>'` — the one general
+   door (`{ editor, game, page, tools, session }`). Never synthetic
+   keys, rAF loops, wall-clock sleeps, or `window.__vgai*` reads.
+6. Repeat for the few varied situations that could expose the change;
+   the observations and screenshots ARE the proof.
+7. Inspect the live hierarchy against the taxonomy above; every prefab
+   appears in Content; collapse repeated primitives.
+8. **Commit NOW, one commit per slice**, message naming the mechanic. A
+   single end-of-build commit is a process failure.
+9. Arc complete → update `DEVLOG.md` (rule above).
+10. Before handoff, report what was tested and which optional harnesses
+    were absent; remaining major arcs go in `ROADMAP.md`.
+
+## Commands
+
+```bash
+npm run dev                   # open/reuse this project's editor (the workbench .vgai/workbench.json names)
+npm run --silent vgai -- status        # require connected: true
+npm run --silent vgai -- play          # editor Play mode
+npm run --silent vgai -- restart       # remount after init-time edits
+npm run --silent vgai -- screenshot    # visible evidence
+npm run --silent vgai -- eval '<js>'   # THE door onto the running game
+npm run check-idioms          # every slice
+npm run validate              # manifest/files + React design states
+npm run typecheck             # THE gate: src + src/tools + server
+npm run dev:standalone        # EXPORTED builds only
+```
+
+Always `npm run --silent vgai -- <verb>`, never a bare `vgai` (a global one may
+belong to another checkout).

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/DEVLOG.md

@@ -0,0 +1,20 @@
+# Development Log
+
+This is the project's internal development journal. It records the reasoning
+that source history and playtest receipts cannot: what changed, why that path
+was chosen, what was learned, and what remains.
+
+Add one entry when a coherent workstream or feature arc finishes—not after
+every small edit. Put the newest entry first and cover:
+
+- what changed and why;
+- important decisions, rejected alternatives, and lessons;
+- the playtest outcome and anything still unresolved;
+- links to the best representative screenshots and, when motion matters, a
+  short gameplay clip.
+
+Evidence linked here is durable project material. Review the actual candidate
+captures, reject unclear or unrepresentative frames, and watch each selected
+clip from beginning to end. Copy only the chosen media out of the bounded
+`.vgai/` run history into `media/screenshots/` or `media/clips/` before linking
+it here. Never cite an unreviewed capture merely because it is the latest one.

package/template/IDIOMS.md

@@ -0,0 +1,118 @@
+# IDIOMS.md — project architecture checks
+
+`AGENTS.md` is the working contract. This page is the compact map of what
+`npm run check-idioms` can enforce mechanically and what still requires live
+judgment.
+
+Legend: **ERROR** fails every run; **WARN** prints but fails only with
+`--strict`; **LOOK** is judged in the live editor and recorded in `DEVLOG.md`.
+
+## Source and roots
+
+- The source is the document. Three roots are ordinary R3F TSX, Canvas roots
+  are ordinary Pixi/React source, and DOM roots are ordinary React. The world
+  node is the entity; no mirror ECS, registration layer, or vgai runtime API
+  belongs in gameplay components. **LOOK**
+- A DOM HUD is a manifest `dom` root and reads the project's own React
+  context/store. A timer repeatedly copying game state into React state is a
+  manual polling pump. **WARN W1**
+- A positive `useFrame(callback, priority)` priority takes over rendering;
+  use zero/negative values for ordering unless that callback actually calls
+  `render`. **WARN W8**
+- Display names are editable presentation, not gameplay identity. Trigger
+  logic comparing `.name` can silently break after an editor rename. **WARN
+  W4**
+
+## Scenes, prefabs, and supporting components
+
+- `src/world.tsx` is thin: root-wide providers/instruments and the active scene
+  swap slot. Complete compositions live as `src/scenes/*Scene.tsx`; support
+  that is not a scene belongs in `src/components/`. Stories inside
+  `src/scenes/`, or helper-shaped files there, are misclassification. **ERROR
+  E11**
+- A prefab is one independently placeable/duplicable/reusable object under
+  `src/prefabs/`. Its colocated portable story names it as `meta.component`;
+  that story is its Content registration. A module claiming prefab residence
+  without that registration is incomplete. **ERROR E10**
+- Owned construction pieces remain inside their owner; do not create a prefab
+  per mesh/primitive. Conversely, independent entities do not hide inside
+  scenery or one scene monolith. The template demonstrates the contrast with
+  `HeroBox` (prefab) and `Ground` (support).
+- A Three project with no correctly story-backed prefab is suspicious. Fully
+  procedural or wholly simulation-owned games can be honest exceptions, but
+  ordinary games should not silently lose the architecture when replacing the
+  starter subject. **WARN W10**
+- R3F placeables forward ordinary `ThreeElements[...]` props to one native
+  outer root and every spatial instance has a meaningful `name`; runtime
+  motion belongs on an inner child so it cannot fight authored placement.
+  The editor's own `R3F00x` analyzer supplies the finding. **WARN E9**
+
+## Mechanics, tester, and studio surfaces
+
+- Every mechanic exports the functions and readings needed to arrange and
+  judge it. The developer calls the running instance directly through
+  `game.run(({ modules }) => ...)`; contributions read the same instances
+  through `src/tools/use-game-modules.ts`. There is no command registry or
+  prescribed vocabulary. **LOOK**
+- The resident QA tester is game code. It receives intent-level goals, runs at
+  simulation speed, and actuates only the game's normal input store. Setup
+  functions may arrange an expensive situation; they do not perform the
+  behavior being judged. The tester's repertoire grows in the slice that adds
+  each mechanic. **LOOK**
+- `src/tools/` is literal contribution TSX. The unfinished Tester/Data/Analytics stubs
+  emit `VGAI_STUB_UNIMPLEMENTED`; replacing or honestly deleting the relevant
+  stub is required before completion. **ERROR E6**
+- Tester holds live QA state, controller ownership, goals/mind, setup cheats,
+  and judgment readings. Analytics holds historical session data. Data holds
+  authored typed literals and derived views. A HUD number does not earn an
+  inspector row merely because it exists. **LOOK**
+- Analytics receives a durable Gameplay Session and cursor, not a live `play`
+  handle. Every chart derives from the selected `logs/play-*.jsonl` session so
+  it survives Stop and reload. A raw event listing does not fulfill Analytics;
+  supply game-specific analysis using the editor's existing playback shell. **LOOK**
+
+## Live proof
+
+- Playtesting is interactive: arrange, direct the tester, advance sim time,
+  observe, read the log, redirect. No committed route, test file, test-runner
+  dependency, or test script belongs in a game project. **ERROR E12**
+- Do not boot a private Playwright harness, reach through `window.__vgai`, or
+  add `?bot=` boot plumbing. Use the editor-owned session and the game's
+  running modules. **ERROR E1–E4**
+- Gameplay source must not accumulate for many commits before the first Play
+  receipt. `logs/play-*.jsonl` is written by the editor and cannot be replaced
+  by an assertion that somebody intended to play. **WARN W9**
+- At handoff, read `npx volter-game-editor console`, inspect the live hierarchy and Content
+  gallery, look at several relevant situations, and promote only reviewed
+  screenshots/clips into `media/`. **LOOK**
+
+## Native libraries
+
+- Call Three, Rapier, React, Pixi, XState, and Colyseus directly. A helper that
+  returns the library's own object is fine; a wrapper or registry that becomes
+  a second programming model is not. **LOOK**
+- Dynamically import the Colyseus client so a single-player bundle does not
+  pay for it. **WARN W3**
+- If this project's manifest explicitly claims seeded determinism, raw
+  gameplay `Math.random()` or wall-clock reads violate that claim. **ERROR
+  E5**
+- Every owner releases what it creates: listeners, timers, bodies, scene
+  objects, and GPU resources. Play→Stop must leave `npx volter-game-editor console` silent.
+  **LOOK**
+
+## Run the scanner
+
+```bash
+npm run check-idioms
+npm run check-idioms -- --strict
+```
+
+A heuristic false positive may be suppressed on the relevant source line with
+a real reason:
+
+```ts
+setTimeout(closeSdkToast, 250); // idioms-ignore W1 one-shot SDK transition, not a state pump
+```
+
+Project-wide warnings such as W10 accept the same comment anywhere under
+`src/`. An empty or missing reason does not suppress a finding.

package/template/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Volter AI, Inc.
+
+This MIT license covers the vgai game-project template (this directory) — the
+starter code scaffolded into your project. It is intentionally permissive so that
+the game you build with vgai, and anything you generate from this template, is
+YOURS, free of any obligations to us. You may relicense your generated game
+under any terms you choose.
+
+(The vgai engine and tooling — everything outside this directory — are licensed
+per component: Apache-2.0 core, AGPL-3.0 editor. See the repository LICENSE.md.)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.