@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/skills/grok-building-games/references/threejs-foundational.md

@@ -1,148 +0,0 @@
-# Browser Game Best Practices — Three.js / Babylon.js / Phaser (controls, camera, orientation, loop, assets, perf)
-
-Consolidated from official docs, well-regarded tutorials, and engine forums (see Sources at bottom). Focus: what an AI builder needs to get **browser games that feel right and don't have the usual bugs.**
-
----
-
-## 1. Game loop & timing (the #1 correctness issue)
-
-**Rules:**
-- Drive the loop with **`renderer.setAnimationLoop(fn)`** in Three.js (internally uses `requestAnimationFrame`, plays nicely with WebXR) or the engine's built-in loop (Phaser `update(time, delta)`, Babylon `scene.onBeforeRenderObservable` / `engine.runRenderLoop`). Avoid `setTimeout`/`setInterval` and `Date.now()`.
-- **Scale ALL movement/animation by delta time** (seconds since last frame) so speed is frame-rate independent (30fps laptop vs 144Hz monitor). e.g. `mesh.position.x += speed * delta`.
-- **Cap delta** to avoid huge jumps after a backgrounded tab: `delta = Math.min(delta, 0.1)`.
-- **Compute delta exactly once per frame** and reuse it everywhere.
-  - Three.js gotcha: `THREE.Clock.getDelta()` mutates state — calling it more than once per frame returns ~0 on later calls (very common bug). Newer `THREE.Timer` (Clock deprecated ~r183) has an explicit `.update()` so delta can be read multiple times safely.
-- **For physics/gameplay stability use a fixed timestep + accumulator** ("Fix Your Timestep"): run `fixedUpdate(FIXED_STEP)` (e.g. 1/60) in a `while (accumulator >= FIXED_STEP)` loop, render at display rate, optionally interpolate. Variable delta is fine for purely visual demos.
-- **Modularize**: give objects a `.update(delta)`/`.tick(delta)` method and iterate an "updatables" list; keep the top-level loop lean.
-- **On-demand rendering**: if nothing is animating, stop the loop / render only on change to save battery (Three.js `setAnimationLoop(null)`; R3F `frameloop="demand"`).
-
-**Reference pattern (Three.js, Timer + capped delta + fixed step):**
-```js
-const timer = new THREE.Timer();
-let accumulator = 0; const FIXED = 1/60;
-function animate() {
-  timer.update();
-  let delta = Math.min(timer.getDelta(), 0.25);
-  accumulator += delta;
-  while (accumulator >= FIXED) { fixedUpdate(FIXED); accumulator -= FIXED; } // physics/AI
-  updateVisuals(delta);
-  renderer.render(scene, camera);
-}
-renderer.setAnimationLoop(animate);
-```
-
----
-
-## 2. First-person / WASD + mouse-look controls (Three.js)
-
-The canonical reference is the official `misc_controls_pointerlock` example (https://threejs.org/examples/misc_controls_pointerlock.html).
-
-**Key facts & rules:**
-- **`PointerLockControls` only handles the Pointer Lock API + mouse-look (yaw/pitch). It does NOT include WASD movement — you implement keyboard + translation yourself.**
-- Add **`controls.getObject()`** (the yaw container) to the scene, not the camera directly; the camera is a child for pitch.
-- Track keys with **boolean state flags** set in `keydown`/`keyup` (support both `KeyW`/`ArrowUp`, etc.). Do NOT move on the keydown event itself.
-- Move with **velocity + delta time** (acceleration + friction/damping), not a fixed distance per press — feels far better.
-- Use **`controls.moveForward()` / `controls.moveRight()`** — they respect current yaw (local XZ plane). Do NOT modify `camera.rotation`/`camera.position` directly for horizontal movement.
-- Pointer lock **requires a user gesture**: always show a "Click to play" blocker overlay; call `controls.lock()` on click; handle `'lock'`/`'unlock'` events and `pointerlockerror`; provide escape-to-unlock and a crosshair.
-- **Avoid the deprecated `FirstPersonControls`** (behaves like fly controls).
-- For real collisions/slopes/stairs, integrate a physics character controller: **Rapier.js `KinematicCharacterController`** (currently favored), or cannon-es (`PointerLockControlsCannon`), Ammo.js. Sync the body to `controls.getObject()`.
-- Encapsulate as a `FirstPersonController` class with `update(delta)`, `lock()`, `dispose()`, and tunable `speed`/`jumpHeight`. Add sprint (Shift), crouch, head-bob for feel.
-- R3F: use drei `<PointerLockControls />` + `useKeyboardControls` + `useFrame`.
-
-**Other camera rigs:**
-- **Orbit / product inspection:** Three.js `OrbitControls`; Babylon `ArcRotateCamera` (set `lower/upperRadiusLimit`, `lower/upperBetaLimit`, `inertia`, `panningSensibility`).
-- **Third-person follow:** lerp camera toward a target offset behind the player each frame; `camera.lookAt(player)`; Babylon has `FollowCamera`.
-- Keep the far plane / `camera.maxZ` (Babylon) as small as practical — improves culling, overdraw, and depth precision.
-
----
-
-## 3. 3D orientation & coordinate conventions (a top source of "why is my model sideways/backwards" bugs)
-
-- **Three.js is right-handed, +Y up:** +X right, +Y up, +Z toward the viewer. Default camera sits at +Z looking toward −Z. (Differs from Unreal's Z-up, etc.) Changing global up (`Object3D.DefaultUp`) is discouraged — it affects helpers/grids.
-- **Forward-axis gotcha:**
-  - Most `Object3D` (Mesh/Group): **local forward is +Z** `(0,0,1)`. Model/rotate so the "front" aligns with +Z.
-  - **Camera** (and some lights): forward is **local −Z** `(0,0,-1)`. This is the classic "camera looks backwards" gotcha.
-- Many primitives (`ConeGeometry`, `CylinderGeometry`) point along **+Y** by default → rotate before use, e.g. `geo.rotateX(Math.PI/2)` to make +Y → +Z (align an arrow/cone's tip with forward).
-- **`object.lookAt(target)`** rotates in **world space** so the forward axis points at the target (uses `.up`, quaternions internally; does not move the object). For nested targets, first `target.getWorldPosition(v)`. To face a *direction* vector: `obj.lookAt(obj.position.clone().add(dir))`.
-- Imported glTF/GLB models may need an initial rotation to match +Z-forward. glTF/Blender export is right-handed Y-up, consistent with Three.js.
-- Debug with `AxesHelper` and `ArrowHelper` to visualize orientation quickly.
-
----
-
-## 4. Performance (Three.js-centric, principles apply broadly)
-
-**The #1 killer is draw calls** (`renderer.info.render.calls`). Target **<100/frame** for smooth 60fps on most hardware; 500+ stutters; mobile is stricter.
-
-- **Share materials** aggressively (reuse one material instance across meshes).
-- **Instancing (`InstancedMesh`)** for many *identical* objects (trees, crowds, bullets) → one draw call; update via `setMatrixAt` + `instanceMatrix.needsUpdate`. Note: default frustum culling applies to the whole instanced mesh.
-- **`BatchedMesh`** (r156+) for *varied* geometries sharing one material, with per-object visibility + `perObjectFrustumCulled`.
-- **Merge geometries** (`BufferGeometryUtils.mergeGeometries`) for fully static scenery sharing a material (loses per-object culling — one bounding volume).
-- **Frustum culling** is automatic (`mesh.frustumCulled`); after modifying geometry call `computeBoundingBox()`/`computeBoundingSphere()`. Reduce `camera.far` where possible.
-- **Dispose GPU resources manually** — Three.js does NOT GC them. On removing objects/switching levels: `geometry.dispose()`, `material.dispose()`, and dispose all textures. Watch `renderer.info.memory`. Use **object pooling** for particles/enemies instead of create/destroy churn.
-- **Avoid allocations in the hot loop** (no `new Vector3()`/`new Matrix4()` per frame; reuse temporaries; Babylon has `TmpVectors` and `xxxToRef()`).
-- **LOD** (`THREE.LOD`) — swap lower-poly at distance. Compress geometry (Draco) and textures (**KTX2/Basis**); prefer texture atlases.
-- Limit lights; bake lighting/AO where possible; keep shadow maps small (and `RENDER_ONCE` refresh for static lights).
-- Add **Stats.js**/FPS counter during dev; profile with Spector.js / engine inspector; profile on target devices.
-
-**Babylon.js specifics:** prefer WebGPU w/ fallback + `powerPreference:"high-performance"`; `scene.performancePriority` (Intermediate/Aggressive); `scene.autoClear=false` when meshes cover viewport; `scene.skipPointerMovePicking=true` if no hover-picking; **thin instances** for static crowds; `mesh.freezeWorldMatrix()`, `material.freeze()`, `scene.freezeActiveMeshes()` for static content; `engine.setHardwareScalingLevel(2)` on low-end/mobile; `SceneOptimizer` to auto-degrade quality to hit a target FPS; keep `camera.maxZ` low. Camera "Behaviors" (Framing/Bouncing/AutoRotation) give polish for free.
-
-**Phaser specifics:** heavy **object pooling** (Groups with `maxSize`, recycle via `active/visible=false`), process only active objects, texture atlases (Texture Packer), destroy tweens/emitters on `SHUTDOWN`, smaller canvas + CSS upscaling, lazy-load per-level assets.
-
----
-
-## 5. Engine / stack choice
-
-- **2D games → Phaser** (Phaser 3/4): scenes, Arcade/Matter physics, Scale Manager, huge ecosystem, great mobile support. Best default for 2D.
-- **3D games → Three.js** (most control, largest community) or **Babylon.js** (batteries-included: inspector, physics, WebGPU, camera behaviors, SceneOptimizer). **PlayCanvas** if you want a full editor/engine.
-- Physics: 2D → Arcade (simple) / Matter (rigid bodies); 3D → **Rapier.js** (fast, WASM, popular) / cannon-es / Ammo.js.
-- Tooling: **Vite + TypeScript**; PWA (manifest + service worker) for installable/offline mobile.
-
-**Phaser architecture (from best-practice write-ups):** one file per Scene extending `Phaser.Scene`; a scene stack of Boot → Preload (progress bar) → Menu → Game → parallel UI/HUD (`scene.launch`) → Pause/GameOver. Lifecycle: `init(data)` → `preload()` → `create(data)` → `update(time,delta)`; clean up on `SHUTDOWN`. Constants file for all string keys. Decouple scenes via an EventEmitter "EventsCenter" or `registry`, not direct references. Prefabs (custom GameObject subclasses) + FSM/ECS for complex logic instead of a giant `update()`.
-
----
-
-## 6. Assets: generate vs. code vs. link
-
-- **Generate real images** for sprites/textures/backgrounds/UI where the builder can (matches Lovable/v0 philosophy: no placeholder images in the final product). For pixel art request specific specs ("clean 32×32 side-view run cycle, 8 frames, sprite sheet, transparent background").
-- **Don't hand-draw complex SVG/geometry** for illustrations or maps — use real assets or a library (echoes v0/Claude anti-slop rules).
-- **Optimize for the browser:** compressed textures (KTX2/Basis/WebP), power-of-two, atlases, keep total download small (aim <20–50MB). Draco/Meshopt for glTF.
-- **Placeholder > bad attempt** (Claude): if a good asset can't be produced, use a clean placeholder rather than an ugly hand-rolled one.
-- Set **`crossOrigin='anonymous'`** on images drawn to `<canvas>`/textures to avoid CORS taint (v0 rule).
-- 3D model pipeline: glTF/GLB (Y-up, right-handed) with Draco/Meshopt/KTX2; verify forward-axis orientation on import.
-
----
-
-## 7. Mobile / responsive / touch
-
-- Distinguish the **canvas drawing buffer** (`canvas.width/height`) from **CSS display size**; account for `devicePixelRatio` to avoid blurry/tiny output. Rendering at a smaller internal resolution + CSS upscale is a valid perf win; `image-rendering: pixelated` for pixel art.
-- Choose a **base design resolution** + aspect ratio; **letterbox (FIT)** to avoid stretching. Phaser: `scale: { mode: Phaser.Scale.FIT, autoCenter: CENTER_BOTH, width, height }` and handle the `resize` event; listen for `orientationchange`.
-- Viewport meta: `width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no`; CSS `touch-action: none` and `preventDefault()` on touch to stop scroll/zoom.
-- **Touch controls:** virtual joystick (e.g. **nipplejs**, `mode:'static'` or `'dynamic'`), split screen (left = move, right = actions/aim), normalize input to −1..1 and apply with delta time, visual feedback on active. **Minimum touch/hit target 44px** (Claude/Apple HIG). Unify keyboard + touch + Gamepad API into one input state.
-- Test on real iOS Safari (audio unlock on gesture, WebGL context loss, touch coalescing) and low-end Android.
-
----
-
-## 8. Common browser-game bugs to prevent (checklist)
-- Movement tied to frame rate (no delta) → runs too fast/slow on different displays.
-- `Clock.getDelta()` called multiple times per frame → things freeze/jitter.
-- Model faces wrong way → forgot +Z-forward convention / camera −Z; fix geometry rotation or `lookAt`.
-- Pointer lock never engages → missing user-gesture click / blocker overlay.
-- Memory leak / crash after level reload → geometries/materials/textures not disposed.
-- Frame drops → too many draw calls (needs instancing/batching/atlases), per-frame allocations, uncompressed textures.
-- Blurry or misaligned on mobile/retina → not handling devicePixelRatio / canvas resize.
-- CORS-tainted canvas → missing `crossOrigin='anonymous'`.
-- Physics tunneling/instability → variable timestep instead of fixed step.
-- Audio doesn't play on mobile → not unlocked on first user gesture.
-
----
-
-## Sources
-- Three.js official: PointerLock example (https://threejs.org/examples/misc_controls_pointerlock.html), docs for `Timer`, `Object3D.lookAt`, `InstancedMesh`, `BatchedMesh` (https://threejs.org/docs/).
-- "Discover three.js" — animation loop / Loop class (https://discoverthreejs.com/book/first-steps/animation-loop/).
-- Three.js Discourse (Clock→Timer r183, setAnimationLoop vs RAF, coordinate-system threads) — https://discourse.threejs.org/.
-- Three.js perf write-ups: utsubo.com "100 tips" (https://www.utsubo.com/blog/threejs-best-practices-100-tips), threejsroadmap.com draw calls.
-- StackOverflow / Medium tutorials on PointerLock WASD and Rapier character controllers (https://medium.com/javascript-alliance/creating-a-first-person-character-controller-in-three-js-5d96534edfd8).
-- Babylon.js: official optimization guide (https://doc.babylonjs.com/features/featuresDeepDive/scene/optimize_your_scene), SceneOptimizer, camera input docs; 2025 forum best-practices thread (https://forum.babylonjs.com/t/best-practices-for-optimizing-babylon-js-scenes-not-just-on-lower-end-devices/58688); Babylon 9.0 notes.
-- Phaser: docs.phaser.io (Scenes, Arcade Physics), Phaser Discourse best-practices threads, franzeus.medium.com "How I optimized my Phaser 3 action game in 2025".
-- Mobile/touch: nipplejs (https://github.com/yoannmoinet/nipplejs), joshmorony.com Phaser scaling guide.
-- Fix Your Timestep (Gaffer On Games) — classic fixed-timestep reference.

package/skills/grok-controls/SKILL.md

@@ -1,274 +0,0 @@
----
-name: controls
-description: >
-  Player-facing input signs for browser games: WASD, vehicles, flight, FPS
-  mouse-look, and the #1 failure mode (inverted A/D). Mandatory control
-  self-tests and a tiny test interface so you can verify A turns left before
-  shipping. Load for ANY game with movement, steering, flying, driving, tanks,
-  boats, mechs, drones, planes, karts, third-person follow cams — not only
-  racing. Triggers on "controls", "WASD", "inverted", "steer", "flight",
-  "airplane", "kart", "vehicle", "yaw", "roll", "pitch", "mouse look", "A/D".
-metadata:
-  short-description: "Control signs, inverted A/D fix, vehicle/flight maps, mandatory self-test"
-user-invocable: false
----
-
-# Controls (player-visible signs — do not ship inverted)
-
-**Read this end-to-end before writing movement/steer/flight code** for any game
-that uses WASD, arrows, a chase camera, or a flying craft. Do **not** skip this
-and only open `racing-kart` or `fps` — those genre files assume you already
-know these signs. Inverted A/D is the most common ship-blocker in vehicle and
-flight demos.
-
-Pair with **`building-games`** (loop, camera, 3D orientation) and
-**`building-games/references/input.md`** (keydown state, gamepad, touch). This
-skill owns **what left/right/up mean to the player** and **how you prove it**.
-
----
-
-## 0. Hard rules (fail the build if broken)
-
-1. **Player-visible left/right is law.** From a **chase / behind** camera while
-   the craft moves **forward**:
-   - **A / ←** → nose (or bank) turns **left on screen**
-   - **D / →** → nose (or bank) turns **right on screen**
-2. **Never reuse FPS strafe as vehicle steer.** FPS “D → +right vector” is
-   **position** on the ground plane. Vehicle A/D is **yaw (or roll) rate**, not
-   a strafe offset. Mixing them is the #1 cause of inverted A/D.
-3. **You must run a control self-test (§5) before saying done.** Screenshot-only
-   QA is not enough. If A turns right, **flip the steer/roll sign**, retest,
-   then ship — do not invent a new coordinate story.
-
----
-
-## 1. Shared 3D basis (use this everywhere)
-
-three.js: right-handed, **+Y up**, meshes face **+Z**, cameras look **−Z**.
-
-**Yaw-only heading on XZ** (ground vehicles, walkers, most arcade craft):
-
-```
-// yaw = 0 faces world −Z; +yaw is CCW about +Y (nose moves toward −X)
-forward = (-sin(yaw), 0, -cos(yaw))
-right   = ( cos(yaw), 0, -sin(yaw))   // = normalize(cross(forward, worldUp))
-```
-
-With a chase cam **behind** the craft (camera near `position - forward * dist`):
-
-| Player sees | World (this basis) | Input |
-|-------------|--------------------|--------|
-| Nose left   | **+yaw**           | **A / ←** must produce **+yaw** (or equivalent bank-left for planes) |
-| Nose right  | **−yaw**           | **D / →** must produce **−yaw** |
-
-If your basis differs, keep **one** consistent pair — but the **player-visible**
-row above is mandatory.
-
----
-
-## 2. Genre maps
-
-### 2a. FPS / on-foot (strafe, not steer)
-
-```
-W = +forward, S = −forward, D = +right, A = −right   // position, not yaw
-mouse: yaw -= movementX * sens; pitch -= movementY * sens; clamp pitch
-```
-
-Body yaw for look; **movement uses yaw only** (do not apply pitch to walk).
-
-### 2b. Ground / water vehicle (kart, bike, jetski, boat, tank, rover, snowmobile)
-
-Arcade body with `heading`/`yaw` and forward `speed`:
-
-```js
-// Input (held keys → actions once per frame)
-let steer = 0; // -1..+1, player-visible
-if (keys.has('KeyA') || keys.has('ArrowLeft'))  steer += 1;  // LEFT
-if (keys.has('KeyD') || keys.has('ArrowRight')) steer -= 1;  // RIGHT
-// Optional: steer = clamp(steer + gamepadX, -1, 1) with same sign convention
-
-// Integrate (speedFactor ~ 0..1 from |speed|)
-const reverse = speed >= 0 ? 1 : -1; // wheel-left still feels left in reverse
-yaw += steer * turnRate * speedFactor * reverse * dt;
-
-// Move along heading
-const fx = -Math.sin(yaw), fz = -Math.cos(yaw);
-position.x += fx * speed * dt;
-position.z += fz * speed * dt;
-```
-
-**Canonical bug (do not copy):**
-
-```js
-// WRONG — this is what ships inverted A/D in the wild
-if (KeyA) steer -= 1;
-if (KeyD) steer += 1;
-yaw += steer * turnRate * dt;  // A → −yaw → nose RIGHT on chase cam
-```
-
-If you already wrote `KeyA → steer--`, either **swap the key mapping** or
-**negate once at integrate** (`yaw += -steer * …`) — then run §5. Do not flip
-twice (keys + integrate + bank mesh).
-
-### 2c. Fixed-wing flight (airplane, glider, RC plane)
-
-| Input | Action | Player expectation |
-|-------|--------|--------------------|
-| **A / ←** | **Roll left** (aileron) | Left wing down / bank left |
-| **D / →** | **Roll right** | Right wing down / bank right |
-| **W / ↑** | Pitch (pick one scheme and label HUD) | Usually nose down *or* pull-up — be consistent |
-| **S / ↓** | Opposite pitch | |
-| **Q / E** | Yaw / rudder (optional) | Q left, E right |
-
-- **A/D are not strafe** and not “ground steer with FPS signs.”
-- Apply roll in the craft’s **local forward axis** with a sign that matches
-  **bank left on A**. If the mesh banks the wrong way, flip **one** sign on the
-  roll apply (or on the A/D → roll mapping), not the whole basis.
-- Coordinated turn: positive bank should produce a turn that matches the bank
-  direction under the chase/external cam.
-
-### 2d. Heli / drone / 6DOF
-
-Document the scheme on a start overlay. Minimum:
-
-- Throttle/altitude on discrete keys must **not** stick “always up” after one
-  press (use held state or explicit up/down).
-- Strafe/yaw: **A left, D right** in the craft’s horizontal frame (player-visible).
-
-### 2e. 2D side-scroller / platformer
-
-**D / →** moves **right on screen**; **A / ←** moves **left**. Gravity only
-inverted if the genre is explicitly upside-down.
-
----
-
-## 3. Camera must agree
-
-- Chase cam: `desired = craftPos + up*height + forward*(-followDist)`; lerp;
-  `lookAt(craft)`.
-- Compute `forward` **once** for both movement and camera — do not rebuild with
-  opposite yaw sign in the camera path.
-- Debug order: (1) keys register → (2) signs correct (§5) → (3) camera agrees.
-
----
-
-## 4. Input plumbing (brief)
-
-- Track keys with a `Set` on `keydown`/`keyup` using **`event.code`**; clear on
-  `blur` / `visibilitychange`. Move in the game loop with **dt**, not in the
-  key handler.
-- Unify keyboard + touch + gamepad into **actions** (`throttle`, `steer`,
-  `pitch`, `roll`, …). See `building-games/references/input.md`.
-- Touch: left stick = move/steer, right = actions; ≥44px targets.
-
----
-
-## 5. Mandatory control self-test (before “done”)
-
-Screenshot-only is **not** enough for any craft with A/D.
-
-### 5a. Player-visible checklist (every vehicle / flight build)
-
-While **moving forward** (speed > small epsilon), chase cam behind:
-
-| Hold | Must observe within ~0.5s |
-|------|---------------------------|
-| **A** | Nose or bank moves **left** on screen |
-| **D** | Nose or bank moves **right** on screen |
-| **W** (ground) | Speed increases / moves along facing |
-| **S** (ground) | Brakes or reverse (as designed) |
-
-If A fails: flip steer/roll sign **once**, retest both A and D.
-
-### 5b. Minimal test interface (implement this)
-
-Expose a tiny hook so you (and automated QA) can prove signs without guessing
-private closures:
-
-```js
-// e.g. src/game/controlsTest.ts — dev/QA only is fine
-export type ControlsProbe = {
-  getYaw: () => number;       // radians; or getHeading()
-  getSpeed: () => number;
-  /** Inject held actions instead of real keys; both stay applied until you
-   *  change them, so §5c can hold a key across frames and clear at the end. */
-  setSteer?: (v: number) => void; // -1..1, same sign as production
-  setKeys?: (codes: string[]) => void; // held until the next call; `[]` clears
-};
-
-declare global {
-  interface Window {
-    __controlsTest?: ControlsProbe;
-  }
-}
-```
-
-Wire `window.__controlsTest` from the game loop when `import.meta.env.DEV` or a
-`?qa=1` flag is set.
-
-### 5c. Automated smoke (run it)
-
-Drive the §5b probe with the preinstalled **`agent-browser`** CLI — that is the
-first move, not a hand-written script. **A thrown `eval` exits non-zero; a
-merely falsy one does not**, so assert by throwing. Run it as one `batch` — one
-CLI call, not one per verb — taking JSON on stdin; `--bail` stops at the first
-failing step and exits non-zero.
-
-```bash
-agent-browser batch --bail <<'JSON'   # find's label is case-sensitive: copy it from `snapshot -i`
-[["open","http://127.0.0.1:8080/"],
- ["find","text","Start","click"],
- ["eval","if (!window.__controlsTest?.setKeys) throw Error('no §5b probe: add setKeys')"],
- ["eval","__controlsTest.setKeys(['KeyW'])"],
- ["wait","600"],
- ["eval","if (__controlsTest.getSpeed() <= 0.1) throw Error('W: no move')"],
- ["eval","(async () => { const t = __controlsTest, y0 = t.getYaw(); t.setKeys(['KeyW','KeyA']); await new Promise(r => setTimeout(r, 300)); t.setKeys(['KeyW']); const d = t.getYaw() - y0, w = Math.atan2(Math.sin(d), Math.cos(d)); if (w < -0.05) throw Error('A turns RIGHT — inverted, got ' + w.toFixed(2)); if (w <= 0.05) throw Error('A barely turned (' + w.toFixed(2) + ') — hold longer or check the sim is running'); return 'A ok' })()"],
- ["eval","__controlsTest.setKeys([])"],
- ["screenshot","/workspace/screenshots/controls.png"],
- ["close"]]
-JSON
-```
-
-**Hold keys through the probe, not with `keydown`** — `agent-browser keydown`
-does not reach §4's `Set`, so a correct game reads as broken. No `setKeys` on
-your probe? Add it (§5b), or dispatch the key event yourself — the browser-QA
-reference's **Keys** note has the mechanism and the form.
-
-The hold sits **inside** one `eval`: spread across commands it lasts however
-long they take, and the ±π wrap in `Math.atan2(Math.sin(d), Math.cos(d))`
-reads a craft that turned more than π as one turning the other way. The IIFE is
-what keeps the step re-runnable — a bare `const d = …` fails the second time
-with "already declared" — and `async` is what lets the hold run in page time.
-Repeat for **D** with `'KeyD'` and both comparisons mirrored (`w > 0.05` is
-inverted, `w >= -0.05` is barely), single-quoted so the JSON needs no escapes;
-for planes assert **roll**: A ⇒ bank left.
-
-**`A turns RIGHT`** is the sign error: flip **one** sign and re-run.
-**`A barely turned`** is not — the craft moved the right way, just less than
-0.05 rad in 300 ms, which a boat or a heavy rover will do; raise the hold, or
-check the sim is running, and flip nothing. Any other non-zero exit — no probe,
-a wedged daemon — means the check never ran: read the message first. Read the
-browser-QA reference `AGENTS.md` links before your first flow — verbs, argument
-shapes and the fallback are there.
-
-### 5d. What not to do
-
-- Do **not** only test “D increases some internal variable.”
-- Do **not** use FPS “D → +X when facing −Z” as the vehicle pass condition.
-- Do **not** flip mesh bank, camera, and steer all at once when fixing — change
-  **one** sign, retest.
-
----
-
-## 6. Finish criteria (controls)
-
-- [ ] Opened **this** skill before writing movement/steer/flight.
-- [ ] Genre map chosen (§2) and start-screen / HUD labels match it.
-- [ ] Chase-cam A/D player-visible test **passed** (§5a).
-- [ ] `window.__controlsTest` (or equivalent) available in dev/QA and used once.
-- [ ] No inverted bank mesh relative to roll/steer input.
-- [ ] Keys are held-state + dt-scaled; no sticky thrust from a single Space tap
-      unless intentional and labeled.
-
-If any box is unchecked, the game is **not** done.

package/skills/grok-controls/agentsam.skill.json

@@ -1,25 +0,0 @@
-{
-  "schema": "agentsam.skill.v1",
-  "id": "grok-controls",
-  "name": "Grok \u00b7 controls",
-  "description": "Control signs, inverted A/D fix, vehicle/flight maps, mandatory self-test",
-  "icon": "skill",
-  "slash": {
-    "suggested": "/grok-controls"
-  },
-  "instructions": {
-    "source": "local_file",
-    "ref": "SKILL.md"
-  },
-  "execution": {
-    "mode": "turn",
-    "tools": [],
-    "operations": [],
-    "capabilities": []
-  },
-  "provenance": {
-    "source": "apps/local-studio/.grok/skills",
-    "vendor": "grok",
-    "status": "imported"
-  }
-}

package/skills/grok-design-ui/SKILL.md

@@ -1,122 +0,0 @@
----
-name: design-ui
-description: >
-  Design and build polished, non-generic UI for this TanStack Start + React +
-  Tailwind v4 + shadcn/Radix app. Use whenever you create or restyle any
-  interface surface — pages, landing pages, dashboards, forms, modals, nav, and
-  game overlays (start screens, HUD, menus). Covers design tokens, layout,
-  typography, color, spacing, motion, and the anti-"AI-slop" rules that keep
-  output from looking generic. Triggers on "design", "UI", "make it look good",
-  "polish", "landing page", "theme", "style", "redesign", "ugly", "clean up".
-metadata:
-  short-description: "Polished, non-generic UI: tokens, layout, type, color, motion, anti-slop"
-user-invocable: false
----
-
-# Design & UI
-
-Make interfaces that look intentional and premium, not template-generic. This is
-the single biggest quality lever in the app builder. Apply it to **DOM / overlay
-UI** — pages, chrome, HUD, menus, forms. (For a 3D game's gameplay canvas, see
-the `building-games` skill; this skill governs the DOM UI layered over it.)
-
-**Read `references/` for depth** (loaded on demand — don't inline it all):
-- `references/refined-ui.md` — the full product-chrome/overlay design system.
-- `references/typography.md` — type scale, pairing, rhythm.
-- `references/surfaces.md` — elevation, borders, shadows, layering.
-- `references/animations.md` — motion, easing, transitions.
-- `references/performance.md` — keep UI smooth (60fps, no jank).
-
----
-
-## 1. Design-system-first (do this before styling anything)
-
-Define the system once, then compose from it. **Never** sprinkle ad-hoc values.
-
-- **Tokens in CSS (Tailwind v4 is CSS-first).** Put the palette, radii, and fonts
-  in `src/styles.css` under `@theme` as CSS variables; consume them as Tailwind
-  utilities. One source of truth.
-  ```css
-  @import "tailwindcss";
-  @theme {
-    --color-bg: #0b0b0f;      --color-surface: #16161d;
-    --color-fg: #e7e7ea;      --color-muted: #a0a0ab;
-    --color-primary: #14b8a6; --color-border: #26262f;
-    --radius: 0.75rem;        --font-sans: "Inter", system-ui, sans-serif;
-  }
-  ```
-- **Use shadcn/ui components** (Radix primitives + `cva` variants + `tailwind-merge`)
-  for buttons, dialogs, dropdowns, inputs, etc. They're accessible and consistent.
-  Generate them into `src/components/ui`; style via tokens, not inline hex.
-- **Tailwind v4 base fix — buttons need a pointer cursor.** v4's Preflight makes
-  `<button>` use `cursor: default`, which feels broken. Add this once in
-  `src/styles.css` so buttons/clickable roles show a pointer:
-  ```css
-  @layer base {
-    button:not(:disabled),
-    [role="button"]:not(:disabled) { cursor: pointer; }
-  }
-  ```
-- **Ban ad-hoc styling:** no raw hex in JSX, no `text-white`/`bg-black` literals,
-  no arbitrary values like `p-[16px]` or `text-[13px]`. If you need a value,
-  it becomes a token or a scale step.
-
-## 2. The quantified rubric (cheap rules that prevent "ugly")
-
-- **≤ 3–5 colors total** (one primary + neutrals + at most one accent). No random
-  extra hues. Don't default to purple unless asked.
-- **≤ 2 font families** (often one). Pair a display/heading with a body, or use one.
-- **Line-height 1.4–1.6** for body; tighter for large headings.
-- **When you override a background color, override the foreground/text color too**
-  (contrast must hold — check both light and dark).
-- **Mobile-first**: design the ~390px layout first, then scale up. No horizontal
-  overflow; tap targets ≥ 44px.
-- **Consistent spacing scale** (4/8-based). Generous whitespace beats cramming.
-- **One accent, used sparingly** for primary actions — not everywhere.
-
-## 3. Anti-AI-slop (the tells that make output look generic — avoid)
-
-- **No gradient-blob filler**, no giant hero gradients as a substitute for content.
-- **No emoji as icons** — use a real icon set (`lucide-react`).
-- **No hand-drawn SVG** illustrations/maps/charts — use real libraries (`recharts`
-  for charts) or real generated images.
-- **No placeholder images / lorem-gray boxes** in the final product — generate
-  real images or use real content; set `crossOrigin="anonymous"` on canvas images.
-- **Avoid the overused-font look** (default system-only, or Comic Sans-tier picks).
-- **Every element earns its place.** Cut decorative noise. Establish a system,
-  then vary with intent — not randomness.
-- **Match the existing UI when editing** an app in place; don't introduce a second
-  visual language.
-
-## 4. Layout & hierarchy
-
-- Clear visual hierarchy: one primary action per view; size/weight/color express
-  importance. See `references/typography.md` and `references/surfaces.md`.
-- Use real layout structure (grid/flex, container max-widths), not absolute-position
-  hacks. Align to a consistent grid.
-- Empty states, loading states, and error states are part of the design — don't
-  ship blank/janky intermediate states.
-
-## 5. Motion (subtle, purposeful)
-
-- Short, eased transitions (150–250ms) on hover/press/enter; respect
-  `prefers-reduced-motion`. Details in `references/animations.md`.
-- Never animate layout in a way that causes jank; prefer transform/opacity.
-
-## 6. Game overlays (when this pairs with `building-games`)
-
-The gameplay canvas is owned by `building-games`. This skill styles the **DOM
-overlay**: start/"click to play" screen, HUD, score, menus, pause, mobile
-controls. Keep overlay readable over the canvas (backdrop, contrast), and keep it
-out of the pointer-lock/gameplay input path.
-
----
-
-## Finish checklist (before you call UI done)
-- Tokens defined in `@theme`; no ad-hoc hex / arbitrary values in JSX.
-- ≤ 5 colors, ≤ 2 fonts, consistent spacing scale.
-- Contrast holds; foreground overridden wherever background is.
-- Mobile (~390px) has no overflow; targets ≥ 44px.
-- Real icons/images/charts — none of the anti-slop tells.
-- Loading/empty/error states handled; motion subtle and reduced-motion-safe.
-- Rendered and eyeballed in a browser (see AGENTS.md verification), not just curl.

package/skills/grok-design-ui/agentsam.skill.json

@@ -1,25 +0,0 @@
-{
-  "schema": "agentsam.skill.v1",
-  "id": "grok-design-ui",
-  "name": "Grok \u00b7 design-ui",
-  "description": "Polished, non-generic UI: tokens, layout, type, color, motion, anti-slop",
-  "icon": "skill",
-  "slash": {
-    "suggested": "/grok-design-ui"
-  },
-  "instructions": {
-    "source": "local_file",
-    "ref": "SKILL.md"
-  },
-  "execution": {
-    "mode": "turn",
-    "tools": [],
-    "operations": [],
-    "capabilities": []
-  },
-  "provenance": {
-    "source": "apps/local-studio/.grok/skills",
-    "vendor": "grok",
-    "status": "imported"
-  }
-}