@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/skills/helix-world-director/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: helix-world-director
+description: Own a HELIX Instant world end to end — discovery, scaffold, assets, authoring, multiplayer, audio, QA, publish — driving one phase ledger in which no phase reaches "done" without an artifact another agent could open. Use for any request to build, finish, upgrade, polish or resume a HELIX world, and whenever a world job spans more than one of the other helix-* skills.
+---
+
+# HELIX World Director
+
+**Mandatory before any publish, new version, listing or "done": the `helix-gauntlet` loop** (`read_skill({ name: "helix-gauntlet" })`). The director does not declare a world finished without it. Ship only on its PASS.
+
+You are the single accountable owner of this world. Not a dispatcher. You carry it from
+brief to a live play URL, you decide what blocks what, and you are the only one who
+declares it finished.
+
+## The rule that makes this skill worth loading
+
+**A phase is `done` only when its Evidence cell names something a different agent could
+open and check: a file path, a tool result, a metric, a URL, an exit code.** The strings
+"done", "verified", "looks good", "tested" are not evidence. If you cannot fill the cell,
+the phase is `running` or `blocked` — never `done`.
+
+Corollary: **an artifact you wrote by hand is weaker evidence than one a tool wrote.**
+Prefer `helix world inspect <dist> --out qa/snapshot.json` (the CLI writes the file) over
+pasting `inspect_world({ json: true })` output into a file yourself. When you must use the
+weaker route, say so in the Evidence cell — `qa/snapshot.json (hand-copied from MCP
+output)` — so a reviewer knows what they are trusting.
+
+## Vocabulary — say exactly what happened
+
+Borrowed deliberately, because the alternative is a lie that reads like a fact:
+
+- **loaded** — you read a `SKILL.md`, a `read_doc` doc, or a reference file into context.
+  Name the path.
+- **executed** — the work was performed. Under loaded guidance, or under your own
+  judgment; say which.
+- **measured** — a tool produced a number or a file. Name the tool and the file.
+
+Never write "I used helix-assets" when you did not load it. Never write "verified
+placement" when you did not run `inspect_world`.
+
+## Phase ledger
+
+Keep it at `<project>/helix-ledger.md`, updated at every phase transition. It never ships —
+only `public/` and the build output reach `dist/`.
+
+```text
+World: <title> (<slug>)   Genre: <genre>   Target: <single-player | multiplayer N>
+Skills loaded:  build: <path|no> · multiplayer: <path|no|n/a> · assets: <path|no> · qa: <path|no> · publish: <path|no>
+Docs loaded:    <read_doc names + template names, or "none">
+
+| # | Phase                | State                        | Evidence (artifact) |
+|---|----------------------|------------------------------|---------------------|
+| 0 | Brief & genre lock   | pending/running/done/blocked  |                     |
+| 1 | Discovery            | …                            |                     |
+| 2 | Scaffold & pins      | …                            |                     |
+| 3 | Assets               | …                            |                     |
+| 4 | Authoring            | …                            |                     |
+| 5 | Multiplayer          | … / n-a                      |                     |
+| 6 | Audio                | …                            |                     |
+| 7 | Performance          | …                            |                     |
+| 8 | QA                   | …                            |                     |
+| 9 | Publish              | …                            |                     |
+
+Blocked on: <nothing | the specific thing and who owns it>
+```
+
+## The phases
+
+### 0 — Brief & genre lock
+Settle in one pass: genre, camera framing, player count, mobile yes/no, the one sentence
+that says what the player does. Genre is not decoration — it decides which `allow*` gates
+get disabled in phase 4 and which QA checks apply. Lock it before writing code.
+**Evidence:** the filled header block of the ledger.
+
+### 1 — Discovery — never design against memory
+Run **all** of these before designing anything:
+`list_systems` · `list_abilities({ system: "humanoid-character" })` ·
+`get_package_manifest` for every package you intend to pin · `check_for_updates` ·
+`whoami` (find out now whether a login exists, not at publish time).
+For an existing world you did not scaffold this session, `check_for_updates({ projectDir })`
+comes **first**, before any edit — it reports stale pins, missing capabilities and inspect
+wiring. Suggest upgrades to the human and stop; never apply a pin change unasked.
+**Evidence:** the version list you pinned against, and the `check_for_updates` verdict.
+
+### 2 — Scaffold & pins
+`scaffold_world` returns the CLI scaffold command and the applicable recipe. Run it, then `npm install`
+→ `install_world_packages` → `npm run build`. Pick the **lowest** `helixVersion` that has
+what you need (0.1 bare scene · 0.2 character · 0.3 multiplayer).
+**Evidence:** `helix.lock.json` exists with resolved exact versions; `tsc --noEmit` exit 0
+and `npm run build` exit 0.
+
+### 3 — Assets — load `helix-assets`
+Sourcing happens **before** authoring, not after. A scene authored around boxes does not
+get retrofitted with real assets; it gets rebuilt.
+**Evidence:** `public/helix.assets.json` with an `assets[]` provenance row covering every
+shipped media file (or the recorded reason each surface has no sourced asset — see the
+allowed-skip list in `helix-assets`), and `helix assets check-loaders` exit 0.
+
+### 4 — Authoring — load `helix-world-build`
+Scene, character config, lighting, materials, HUD, input, game logic.
+**Evidence:** `qa/snapshot.json` from `helix world inspect`, with findings adjudicated and
+`inspect.baseline.json` written. Touch controls exist, or `supportsMobile` is `false`.
+
+### 5 — Multiplayer — load `helix-multiplayer` (skip only for a genuinely solo world)
+**Evidence:** `validate_world` accepts the `multiplayer` block, plus the two-client
+verification artifact.
+
+### 6 — Audio
+Every player action, pickup, hit, UI press, state change and ambience has a sound.
+A silent world is a defect, not a style. This is its own phase because when it is a
+sub-bullet of "polish" it does not happen.
+**Evidence:** `qa/audio-coverage.txt` from `helix world source-audit` — coverage 100%, and every
+declared cue resolves to a file that exists in `dist/`.
+
+### 7 — Performance — load `helix-world-qa` → G9
+Its own phase for the same reason audio is: as a sub-bullet of QA it becomes a number someone
+prints at the end, and two worlds shipped that way at 39 fps and 11 fps with every other gate
+green. **A frame-time artifact is required to reach done** — this phase cannot be closed by
+looking at a screenshot and deciding it feels smooth.
+
+Measure the **built** world (`npm run build && npm run preview`, or the published play URL),
+never `dev`:
+```bash
+helix world perf-gate \
+     --url "http://localhost:4173/?perf=1" --label "<world> build <n>" \
+     --seconds 20 --dist dist --json qa/perf-gate.json | tee qa/perf-gate.txt
+```
+The budgets are design constraints, not an optimisation pass — 8 punctual lights, 1 shadow
+caster, a 2.6 M pixel drawing-buffer budget. If you are meeting them for the first time here,
+phase 4 was built against the wrong constraints and this phase will be a rebuild, not a tune.
+See `helix-world-build` → "Design inside the budget".
+
+**Evidence:** `qa/perf-gate.json` exit 0, **naming the renderer it was measured on**. A frame
+time without its GPU is not a measurement. `qa/perf-gate.txt` is the human-readable copy.
+
+### 8 — QA — load `helix-world-qa`
+**Evidence:** `qa/world-audit.txt` and `qa/source-audit.txt`, both exit 0 — with
+`source-audit --perf qa/perf-gate.json`, which is what enforces the light-count ceiling
+against the lighting rules that push the other way.
+
+### 9 — Publish — read `read_doc("publishing")`
+Follow the publishing contract from the server docs, then run the creator CLI's live identity
+proof:
+
+```bash
+helix world prove-live \
+  --url "<playUrl returned by publish_world>" \
+  --world-api "<worldUrl returned by publish_world>" \
+  --build "<build returned by publish_world>" \
+  --dist dist --perf qa/perf-gate.json | tee qa/live-proof.txt
+```
+
+**Evidence:** the play URL, and `qa/live-proof.txt` exit 0 — which now requires a proven
+readback (live build number AND/OR the deployed entry document's sha256 matching your bundle),
+not merely a 200.
+
+## Blocking rules
+
+These are the only things that stop a phase from being marked done, and each is checked by
+an artifact, not by your opinion:
+
+1. `validate_world` reports errors → phases 8 and 9 blocked.
+2. `tsc --noEmit` exits non-zero → phases 4–9 blocked. `npm run build` is `vite build` and
+   never typechecks, so a type error ships and fails silently — including the one where the
+   character config sits on the wrong options key and every tuned value is ignored at
+   runtime. See `helix-world-build` → "Typecheck, because `vite build` does not".
+3. `helix world audit` exits non-zero (primitive-dominant, no loaded models, default-material
+   dominant, over budget, a bundled model requiring Draco/meshopt, unrecorded asset
+   provenance) → phase 8 blocked. This is where "the scaffold's box-and-plane world" gets
+   caught.
+4. `helix world source-audit` exits non-zero (ambient-only lighting, unmotivated local light, more
+   punctual lights than the measured ceiling, no tone mapping, audio coverage below 100%, a
+   cue with no file, a genre gate left on, `supportsMobile: true` with no touch controls) →
+   phase 8 blocked.
+5. `helix world perf-gate` exits non-zero (frame p50 over 16.7 ms, p95 over 33.3 ms, over 12 punctual
+   lights, a shadow-casting point light, a drawing buffer over 2.6 M pixels, or a run on a
+   software rasteriser) → phase 7 is not done, and phases 8 and 9 are blocked. **A world with
+   no `qa/perf-gate.json` at all is blocked too** — unmeasured is not the same as fast, and
+   two worlds shipped green on every other gate at 39 fps and 11 fps.
+6. A Draco- or meshopt-compressed model anywhere in the asset tree → phase 3 blocked. The
+   runtime has GLTFLoader + KTX2Loader only; this is a load failure at runtime, never a
+   warning. `helix assets check-loaders` reads both `.glb` and `.gltf`.
+7. `helix world prove-live` exits non-zero, **including when it could not prove anything, and
+   including a missing or stale frame-time artifact** → phase 9 is not done. Reachability is
+   not identity, and a green perf run from three builds ago is not this build's.
+8. `whoami` shows no creator session → phase 9 blocked on the human. This is the one
+   blocker you cannot clear yourself; surface it early (phase 1), not at the end.
+
+## Allowed reasons to skip work — a closed set
+
+An open-ended "I judged it unnecessary" is how a world ends up as grey boxes. A phase or a
+surface may be skipped only for one of these, and the ledger records which:
+
+- The human explicitly scoped it out.
+- A capability probe shows the endpoint or tool does not exist on this lane (record the
+  probe output, not your inference from it).
+- A tool returned a real error — record the call and the error text.
+- The phase is structurally inapplicable (multiplayer for a solo world; character config
+  for a bare scene world).
+
+"Not needed" without one of those four is not a skip, it is an omission.
+
+## Report
+
+Close with: what the world is, the play URL, the ledger table, the QA metrics that were
+measured (not adjectives — the numbers `world-audit` printed), **the frame times and the GPU
+they were measured on**, anything still blocked and who owns it, and — separately — anything
+you changed that the human should look at.
+
+Never claim premium quality with an automatic-failure row unresolved. Never claim a world
+is published without a play URL that `helix world prove-live` returned 0 on.

package/skills/helix-world-qa/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: helix-world-qa
+description: Prove a HELIX world actually plays, and plays at 60 fps, before it ships — mobile first, with the blocking gates (including frame time) computed by script from the world snapshot, the bundle, the source and a real GPU run rather than asserted in prose. Use before publishing, when reviewing someone else's world, when a world "looks flat", "feels unfinished", "runs badly", stutters or drops frames, and whenever a change needs a regression check.
+---
+
+# HELIX World QA
+
+**Mandatory before any publish, new version, listing or "done": the `helix-gauntlet` loop** (`read_skill({ name: "helix-gauntlet" })`). Bar: the named reference art or a comparable published world; renders: the fixed-camera and mobile screenshots this skill produces; your own look at each beside the bar, then a fresh blind critic. Ship only on its PASS.
+
+Before the final GPU gate, call `analyze_scene_performance` with the exact Scene/Package and inspection snapshot. Call it again with the runtime receipt. Keep authored versus submitted triangles, visual/material/Palette counters, GPU versus compressed bytes, and owned/transitive/cold/warm delivery separate. A capped or reduced-resolution capture is not fullscreen proof; compare the same route, camera, exposure, time of day, viewport, DPR, quality, and cap. Full interpretation: `read_doc({ name: "scene-performance" })`.
+
+QA here has one job: produce evidence that would convince someone who does not trust you.
+Not a checklist you ticked — numbers a script printed, files on disk, an exit code.
+
+Run everything from `<project>/`, write everything to `<project>/qa/`. That directory never
+ships (only `public/` and the build output reach `dist/`).
+
+## The gates
+
+Nine gates. Gates 1–6 and **G9** block; a blocking gate that fails means the world is not
+ready, full stop. Gates 7 (beyond its touch check) and 8 are judgment, and are explicitly
+marked as such — a rubric that grades itself is not a gate, and pretending otherwise is how QA
+becomes theatre.
+
+G9 used to be judgment too. It printed a frame rate and never failed on it, which is how two
+worlds shipped that Jack reported as running badly with every gate green.
+
+### G1 — It typechecks, builds and validates *(blocking)*
+```bash
+npx tsc --noEmit                   # exit 0 — run this FIRST
+npm run build                      # exit 0
+```
+**`npm run build` is `vite build`, which never typechecks.** It transpiles and discards
+types, so a type error builds clean, ships, and fails silently at runtime. The scaffold
+already defines `npm run typecheck`; nothing was making anyone run it.
+
+This is not a style gate. The defect it catches is invisible any other way:
+`CharacterMultiplayer.create` takes its tunables on **`character:`**, while
+`Character.create` takes them on **`config:`**. Passing the wrong key is a type error and
+nothing else — the world builds, publishes, and runs with **every tuned value silently
+ignored**, including the genre control gates. A "first-person" world still flips to third
+person on T, and no artifact says why. `source-audit` now flags this exact shape, but `tsc`
+is what catches the whole class.
+
+`validate_world({ directory: "<abs>/dist" })` → **VALID**. Fix every reported problem; the
+validator lists them all at once, so one pass should clear them. Errors here mean publish
+would reject the bundle anyway.
+
+### G2 — It boots *(blocking)*
+```
+capture_world_screenshot({ directory: "<abs>/dist" })
+```
+A successful capture proves the page booted and rendered a frame. **A failed capture is
+still diagnostic** — the timeout message carries the page's boot errors. Look at the
+returned image; do not just note that the call returned.
+
+### G3 — Layout is measured, not eyeballed *(blocking)*
+```bash
+npx -y <lane-cli> world inspect ./dist --out qa/snapshot.json
+```
+Use the CLI so the *tool* writes the file — that is stronger evidence than pasting MCP
+output into a file yourself. `check_for_updates` reports the CLI package name for this lane.
+
+Then adjudicate every finding. **Findings are measurements, not verdicts:** a hovering
+pickup, an embedded ramp, walls overlapping at their corners all warn on good worlds. The
+rule is *a warn that matches what you meant needs no fix; a warn that surprises you is the
+bug.* Never edit geometry to silence a finding.
+
+**Write the baseline. It is the normal first step, not a suggestion.** Once you have checked
+the findings against intent, run `inspect_world({ directory, writeBaseline: true })` and
+record the adjudication alongside it. From then on inspect reports only what **changed**,
+which is what makes "this failure is pre-existing" a checkable claim instead of a convenient
+one. Without a baseline file, "that was already broken" is unfalsifiable, and it is exactly
+the sentence an agent reaches for when it wants to close a task.
+
+Do not ask permission first. On any world whose premise generates findings by construction —
+a floating archipelago, a zero-gravity station, anything where hovering geometry *is* the
+design — the unbaselined report is dozens of warnings that all say "yes, on purpose", and an
+agent reading it learns to skim inspect output instead of reading it. A dogfooded world
+adjudicated **49 findings once**, wrote the baseline, and every run since reports clean; the
+next real change will stand out on its own. Write the adjudication down (which findings, why
+intended) next to the baseline — the baseline records *that* you judged, your note records
+*what* you judged.
+
+### G4 — Composition and budgets *(blocking, scripted)*
+```bash
+helix world audit --snapshot qa/snapshot.json --dist dist \
+     --root world --assets public/helix.assets.json | tee qa/world-audit.txt
+```
+Exits non-zero on: the scaffold signature · zero loaded models · primitive-dominant (>60%
+of visible meshes are built-in geometry) · default-white-dominant primitives · a bundle over
+200 files / 25 MB per file / 50 MB total / a disallowed extension / an illegal path / an
+empty file · platform assets bundled under `helix_modules` · NaN transforms · **any bundled
+`.glb` or `.gltf` requiring Draco or meshopt** · a provenance row **declared, not shipped** ·
+a shipped media file **covered by no provenance row**.
+
+The extension allowlist and the caps mirror `@hypersoniclabs/helix-manifest`'s own
+bundle-rules, including the `.d.ts`-by-suffix exception (system packages ship consumer types
+under `helix_modules/`; an `extname()` check reads `index.d.ts` as `.ts` and fails a file
+publish accepts). The loader check parses both container forms — `.glb`'s binary header and
+plain-JSON `.gltf`, which is what Poly Haven ships.
+
+Put authored geometry under a Group named `world` (see `helix-world-build`) or the audit
+falls back to the whole scene, counts the streamed character body as a loaded model, and
+says so. Read that warning — it means the number is weaker than it looks.
+
+### G5 — Lighting, materials, audio, mobile, controls, authority *(blocking, scripted)*
+```bash
+helix world source-audit --src src --dist dist \
+     --manifest public/helix.json \
+     --genre <first-person|third-person|top-down|side-on|walking-sim> [--multiplayer] \
+     --console qa/playtest/console.txt \
+     --perf qa/perf-gate.json \
+     | tee qa/source-audit.txt
+```
+Exits non-zero on: ambient-only lighting · a `PointLight`/`SpotLight` added to the scene
+root instead of its emitter mesh (a **pooled** light is exempt) · **more punctual lights than
+the ceiling, measured by G9** · no `renderer.toneMapping` · no `scene.environment` /
+PMREM · fewer than 60% of standard materials carrying roughness/metalness/a map · **any**
+interaction site with no sound in its handler · no looping ambience · a cue name that
+resolves to no shipped audio file and is not `synth:`-prefixed · a genre `allow*` gate left
+at its default · **`supportsMobile: true` with no shipped v1 controls contract** · **the character
+config passed on the wrong options key** · an honest fallback that **actually fired** in the
+captured console · an unguarded client-side `teleport`/`respawn` in a multiplayer world.
+
+**Runtime-lit worlds pass the renderer-owned checks by construction.** A world on the default
+lighting lane — it calls `createVisualRuntime` and authors `public/helix.visuals.json` — has
+no `renderer.toneMapping` write, no `scene.environment` assignment and no hand-placed sun *on
+purpose*: the runtime owns all three, and `source-audit` recognises the runtime call and
+treats those checks as satisfied. Do NOT add a decoy tone-mapping line or a second sun to
+quiet the audit — that is exactly the double-lighting the runtime forbids (see
+`read_doc({ name: "lighting-world" })`). The motivated-light rule and the punctual-light
+ceiling still apply in full to world-authored local lights on BOTH lanes.
+
+**The lighting rules here and the count ceiling are one rule, and they only work together.**
+"Attach every local light to the mesh that emits it" is good art direction and, on its own, an
+instruction to give every visible lantern its own real light — which is exactly how a world
+ends up at 21 lights and 11 fps. `--perf` is the counter-pressure: without it the script says
+`lighting.count-not-measured` and tells you nothing is pushing back.
+
+**This script no longer counts lights, and it used to claim it did.** `lighting.census` counted
+`new THREE.PointLight(` *call sites* and reported them as a census: it printed
+`PointLight×4 · SpotLight×1` for a scene holding **18 point lights and 4 spot lights** — four
+constructor sites, all inside loops — and `PointLight×1` for Skyward's 13. The one metric that
+would have caught the defect was wrong by 4.5×, in the direction that passes. What is left is
+labelled `lighting.sites` and says in its own output that it is not a count.
+
+The audio denominator is extracted from the code — `input.wasPressed`, `events.on`,
+`room.onMessage`, `sendAction`, DOM `click`/`pointerdown` handlers — not from a list you
+write. That is the point: you cannot shrink the denominator by forgetting an interaction.
+The window is the brace-matched handler body plus one level of named-callback resolution, so
+`el.addEventListener('pointerdown', namedHandler)` is judged on `namedHandler`'s body.
+
+**This script is static analysis and says so about itself.** Three of its checks read the
+*shape* of your code rather than its effect, and each names the runtime gate that measures
+the outcome: genre gates → G6's control assertion; audio coverage → G6's captured cue log;
+honest fallbacks → the `--console` file from a real run. Where it warns
+`…measured NOTHING`, that is not a pass — copy the line into the report.
+
+**Never restructure code to satisfy a shape check.** A release-half pointer handler is not a
+second interaction needing its own sound, and an earlier version of this gate said it was —
+which taught an agent to move release handling to an event the gate does not watch. That is
+better code and a worse outcome, because the gate was routed around rather than satisfied.
+If a check fires on correct code, report it as a bug in the script.
+
+### G6 — It plays *(blocking when a browser tool is available)*
+A screenshot proves it rendered. Only input proves it plays. Assert a **delta**, not a final
+state — a final-state check passes on a disconnected client.
+
+**A wall-clock delta assertion is invalid under a software rasteriser, and the default
+headless browser is one.** Chromium falls back to SwiftShader unless you force a real GPU;
+a modest scene then renders at ~2 fps. The scaffold clamps `dt` to 0.1 s per frame, so at
+2.3 fps the simulation advances at ~23% of wall-clock and every wall-clock measurement
+under-reads by 4–8×. That is not a small error: it reported 0.7 m/s for a world configured
+at `runSpeed: 6`, and a 1.41 m apex for `jumpHeight: 4.2`, and it nearly got a correct game
+retuned to match a broken measurement.
+
+Three requirements, all of them non-optional:
+
+**1. Force a real GPU, and refuse the software fallback quietly.**
+```js
+const browser = await chromium.launch({ headless: true, args: [
+  '--use-angle=metal', '--enable-gpu', '--ignore-gpu-blocklist',   // macOS; --use-angle=gl elsewhere
+  '--autoplay-policy=no-user-gesture-required', '--mute-audio',
+  '--window-position=-4000,-4000',                                  // never steal focus
+]});
+```
+
+**2. Measure per SIMULATED second, never per wall second.** Expose `simTime` on the probe —
+the accumulated, clamped `dt` your loop actually stepped — and divide by that.
+```js
+await page.waitForFunction(() => (window.__helixProbe?.frame ?? 0) > 12);  // warm up first
+await page.keyboard.down('KeyW');
+await page.waitForTimeout(600);                       // let the ground-accel ramp finish
+const a = await probe(page);
+await page.waitForTimeout(2500);                      // the measured window
+const b = await probe(page);
+await page.keyboard.up('KeyW');
+
+const travelled = Math.hypot(b.player.x - a.player.x, b.player.z - a.player.z);
+const simDt = b.simTime - a.simTime;                  // NOT 2.5
+const speed = travelled / simDt;                      // m per simulated second
+expect(speed).toBeGreaterThan(0.75 * CONFIGURED_RUN_SPEED);
+```
+Sample the sustained run, not the first 700 ms — the spawn drop and the acceleration ramp
+both live in that window. A jump under low gravity needs a 5 s sampling loop, not one tick.
+
+**3. Report the harness's own frame rate in the result line.** `(b.frame - a.frame) / seconds`.
+It is how the next reader knows whether to believe the numbers, and how you notice the GPU
+flags silently stopped working. Under ~15 fps, say the measurement is suspect.
+
+**4. Prove the genre control gates HERE.** `source-audit` can only see that
+`allowModeToggle: false` appears in your source; it cannot see whether the runtime read it
+(a config block on the wrong options key is ignored silently — see G1). Press the control
+and assert the state did not change:
+```js
+const before = await page.evaluate(() => window.__helixProbe.cameraMode);
+await page.keyboard.press('KeyT');                     // the mode toggle
+await page.waitForTimeout(300);
+expect(await page.evaluate(() => window.__helixProbe.cameraMode)).toBe(before);
+```
+Expose whatever the gate governs — `cameraMode`, zoom distance, yaw — on the probe.
+
+**5. Drive the touch controls at a phone viewport**, in a context with
+`hasTouch: true, isMobile: true`, using **only** the on-screen controls: press the stick,
+assert a position delta; tap the jump button, assert an apex. A keyboard press in a mobile
+context proves nothing about a phone. See G7.
+
+**6. Confirm the render state that G5 can only guess at.** `source-audit` sees that
+`renderer.toneMapping = …` appears in your source; only the running renderer knows what it
+ended up as. One line on the probe turns two shape checks into measurements:
+```js
+renderer: { toneMapping: renderer.toneMapping, exposure: renderer.toneMappingExposure,
+            environment: !!scene.environment, pixelRatio: renderer.getPixelRatio() }
+```
+Assert `toneMapping !== 0` (`NoToneMapping`) and `environment === true`.
+
+Expose `window.__helixProbe` behind a query param, the same no-op-during-play pattern
+`world.ready()` and `screenshots.register()` use. Carry at least `frame`, `simTime`,
+`player`, `grounded`, `cameraMode`, `renderer`, and the cues that reached a voice. Capture **all**
+console output (not just errors) to `qa/playtest/console.txt` — `source-audit --console`
+reads it to check whether an honest fallback actually fired. Attach screenshots to
+`qa/playtest/`.
+
+**If no browser tool is available**, say so in the report — "playability was not proven by
+input; boot and render proven by capture" — and never write that you playtested it. An
+honest gap is recoverable; a false claim is not.
+
+### G7 — Mobile *(blocking for the touch gate, judgment for the rest)*
+The platform is mobile-first: most players arrive on a phone. Fresh character worlds mount the
+generated `humanoid-character` touch HUD by default. It renders from registered action metadata and
+provides movement, drag look, two-pointer pinch zoom, jump and contextual buttons. A world configures
+or extends this system; it does not rebuild it from scratch.
+
+- **`supportsMobile: true` requires a shipped controls contract and real touch evidence.**
+  `source-audit` validates `helix.controls.json` in source and dist (platform provider or an explicit
+  equivalent custom provider). That is the floor, not the proof: at both 390×844 and 844×390 with
+  `hasTouch: true`, assert touch-only movement, camera rotation, pinch zoom through first-person and
+  back, jump apex, and one world-specific action. A keyboard press in a mobile context proves nothing.
+- Every gameplay verb is reachable without a keyboard. A keyboard-only binding is a desktop
+  cheat, not a control.
+- The HUD clears the shell's top ~56px chrome bar. Countable: every HUD element's
+  `getBoundingClientRect().top` is ≥64 or it is anchored to a corner/bottom.
+- Rotate portrait ↔ landscape and confirm safe-area/top-offset layout and no stuck virtual state.
+- Re-run keyboard/mouse and a standard-mapped gamepad after touch QA; the HUD must not replace them.
+
+### G8 — Visual scorecard *(judgment — advisory)*
+`references/visual-scorecard.md`. Ten categories, 0–3, with the automatic-failure list.
+**Four of its rows are backed by G4/G5 and therefore actually block; the rest are your
+opinion of your own screenshot and are recorded as such.** Do not present a self-graded
+average as a gate — that is precisely the theatre this skill set exists to avoid.
+
+### G9 — Frame time *(blocking, scripted)*
+```bash
+helix world perf-gate \
+     --url "http://localhost:4173/?perf=1" --label "<world> build <n>" \
+     --seconds 20 --dist dist --json qa/perf-gate.json | tee qa/perf-gate.txt
+```
+Run it on the **built** world — `npm run build && npm run preview`, or the play URL
+`publish_world` returned. Never `dev`.
+
+Exits non-zero on: **frame p50 over 16.7 ms** (60 fps sustained) · **frame p95 over 33.3 ms**
+(30 fps) · more than **12 punctual lights** (point + spot combined; warns over 6) · **any**
+shadow-casting point light · more than one shadow-casting spot or directional light · a shadow
+map over 2048² · a drawing buffer over **2.6 M pixels**, at the tested window *or at a larger
+one* · over 300 draw calls or 500k triangles per frame · a software rasteriser · no light
+census at all. Decoded texture bytes over 256 MB **warn** — that budget is unvalidated, and a
+blocking gate on a number nobody has measured is how agents learn to optimise the wrong thing.
+
+**This gate exists because QA already measured frame rate and threw it away.** Night Market
+shipped at 25.5 ms p50 / 92.7 ms p95 with 26% of frames over 33 ms — 39 fps median, 11 fps
+when the player turned around — and every gate we had passed it. Frame time was an
+informational line. A world could run at 10 fps and be green.
+
+Where the numbers come from and what each limit does and does not mean:
+`references/perf-budgets.md`. The short version:
+
+| Limit | Value | What it is |
+| --- | --- | --- |
+| frame p50 / p95 | 16.7 ms / 33.3 ms | **the outcome.** Everything else is a cause. |
+| punctual lights (point + spot) | warn 6 · fail 12 · target 8 | **the cause.** No light culling in three.js: every light is evaluated per lit pixel, and the cost goes vertical between 12 and 16. The 21st light costs 13× the 4th. |
+| shadow casters | 1 directional · 0 point · ≤1 spot | a shadow-casting point light renders the scene **six times per frame** |
+| shadow map size | ≤2048², 1024² recommended | **a MEMORY limit, not a time limit.** 512 vs 1024 measured as noise. Say so, or someone shrinks it expecting frames back. |
+| drawing-buffer pixels | ≤2.6 M, as a **derived ratio** | the largest single lever (69%) — and a fixed DPR cap silently becomes a cliff on a bigger window |
+| draw calls / triangles | ≤300 · ≤500k per frame | **CPU-submission guards for weaker machines.** 418 calls and 778k triangles measured as costing *nothing* here. Do not mistake these for the thing that matters. |
+| decoded texture bytes | ≤256 MB | **UNVALIDATED** — never observed to cost frame time on unified memory. A memory precaution, not a diagnosis. |
+
+**Measurement discipline, or the numbers lie.** All three are in the script; know why:
+1. **Force a real GPU** (`--use-angle=metal` on macOS, `--use-angle=gl` elsewhere). Headless
+   Chromium falls back to SwiftShader, and the gate **refuses to report** numbers from a
+   software rasteriser rather than printing a frame time for a CPU.
+2. **`gl.finish()` once per frame.** WebGL draw calls are asynchronous; without a sync the CPU
+   runs ahead of the GPU and rAF deltas measure JS. Skyward read **562 fps** when it wasn't.
+3. **Report the renderer string next to the result.** A frame time without the GPU that
+   produced it is not interpretable, and it is how you notice the flags stopped working.
+
+The world should ship the `?perf=1` handle (`references/perf-handle.md`). Without it the gate
+still measures everything at the WebGL level — including the light count, read out of the light
+arrays three.js compiled into its own fragment shader — but shadow-map size and per-light names
+come back `measured NOTHING`.
+
+**Then feed the artifact back into G5:** `helix world source-audit --perf qa/perf-gate.json`. Every
+lighting rule in G5 pushes toward *more* lights; the measured count is the only thing pushing
+back.
+
+**One change, then re-measure the same scenario.** A batch of seven optimisations tells you
+nothing about which one worked, and one of them is usually a regression. To attribute a frame
+to a cause, run an ablation ladder against the `?perf=1` handle — recipe in
+`references/perf-handle.md`.
+
+## Baselines are files, not memory
+
+Every regression claim needs a stored baseline or it is not a claim:
+- Layout → `inspect.baseline.json` (written by `inspect_world({ writeBaseline: true })`).
+- Composition/budgets → the previous `qa/world-audit.txt`, committed.
+- Source gates → the previous `qa/source-audit.txt`, committed.
+- Frame time → the previous `qa/perf-gate.json`, committed. It carries the scenario and the
+  renderer string, so a regression claim can be checked against the same GPU at the same
+  viewport rather than against a number someone remembers.
+
+Diff the new run against the committed one. "Pre-existing" means it appears in the committed
+baseline. Nothing else counts.
+
+## Order of operations that saves a pass
+
+Measure before you look. `inspect_world` answers *where things are* exactly; a screenshot
+measurably cannot, and "is the bench 0.4 m in the air" read off an image is a coin flip.
+Screenshots answer *how it reads* — framing, materials, lighting, mood — and that is the
+closing check, after the numbers are already right. Each capture costs a build plus several
+seconds, so one well-chosen angle beats a burst.
+
+## Report
+
+```text
+QA — <world> (<slug>)
+G1 typecheck+build pass/FAIL   tsc --noEmit exit 0; validate_world: VALID, 47 files, 3.1 MiB
+G2 boot            pass/FAIL   qa/screenshots/hero.png
+G3 layout          pass/FAIL   qa/snapshot.json — 3 findings, all adjudicated (baseline written)
+G4 composition     pass/FAIL   qa/world-audit.txt — 15 meshes, 20% primitive, 12 loaded, 28,806 tris
+G5 source gates    pass/FAIL   qa/source-audit.txt — audio 14/14, 4 lights, 6/7 PBR materials
+G6 playability     pass/FAIL/not-proven   qa/playtest/ — 5.8 m/s over 2.5 s SIMULATED (config 6), harness at 41 fps, T did not change camera mode, 0 console errors
+G7 mobile          pass/FAIL for touch (thumbstick delta + jump apex), notes + screenshot path
+G8 scorecard       average, and the automatic failures still standing
+G9 frame time      pass/FAIL   qa/perf-gate.txt — 2.5 ms p50 (400 fps) / 5.7 ms p95, 6 punctual lights, 1 shadow caster, 2.60 M buffer px, 184 calls / 366k tris, on ANGLE Metal (Apple M1 Pro)
+```
+
+The renderer string is part of the G9 line, not a footnote. "400 fps" means nothing without
+the GPU that produced it.
+
+Numbers, not adjectives. If a gate did not run, write **not-proven** and why — never leave
+the reader to infer that a blank means pass.