@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

package/skills/grok-auth/references/session-ui.md

@@ -0,0 +1,133 @@
+# Reading the user, protecting routes, and preventing flicker
+
+## When sign-in UI may render (hard rules)
+
+- **Connector / owner-data apps: never gate the data fetch behind a session.**
+  When the data comes from the app's connector grants, the fetch runs on the
+  gate-injected connector token — a chain that does not involve the app
+  session. Fetch first; use the session for personalization only (greeting,
+  per-user rows). Requiring sign-in before fetching adds a click that changes
+  nothing.
+- **A sign-in CTA may render only after the session check has RESOLVED to no
+  user** — never while `isPending` is true (no CTA flash on load), and never
+  as a reaction to a data error (the `app-data` skill's error mapping owns
+  those states; only its `login` kind ever shows "Continue with Grok").
+- **In preview, gate identity signs the owner in with zero clicks** — a
+  visible sign-in button for the owner in the preview is a bug to fix, not a
+  style choice (`grok-identity.md`).
+- **Use `<SignInGate>` from `@/lib/auth/gates`** — `{ children, fallback? }`:
+  nothing while pending, `children` when signed in, `fallback` (or the
+  standard provider buttons) only once signed out is known. Do not hand-roll
+  sign-in CTAs from `useCurrentUser()`.
+
+## Reading the user / protecting routes
+
+`@/lib/auth/use-current-user` (with auth on these reflect the REAL session, so a
+preview visitor is signed out until they sign in):
+
+- `useCurrentUser()` → `AppUser | null` — for display. `null` means *loading OR
+  signed out*, so never redirect on it alone.
+- `useCurrentUserState()` → `{ user, isPending }` — for guards: wait for
+  `isPending` to clear before treating `user: null` as signed out, or a hard
+  reload bounces signed-in users to sign-in.
+
+**State components** from `@/lib/auth/gates`: `SignedIn`, `SignedOut`,
+`SignInGate` (`{ children, fallback? }` — nothing while pending, `children`
+signed in, `fallback` or the standard provider buttons only once signed out is
+known; prefer it over hand-rolled sign-in CTAs), `RedirectToSignIn`,
+`UserButton`. (When auth is disabled via `VITE_AUTH_ENABLED=false` they apply
+dev-user semantics so a non-auth app still renders.)
+
+```tsx
+import { useCurrentUser, useCurrentUserState } from "@/lib/auth/use-current-user";
+import { RedirectToSignIn, SignedIn, SignedOut, UserButton } from "@/lib/auth/gates";
+
+function Navbar() {
+  const user = useCurrentUser(); // display only — null may just mean "loading"
+  return (
+    <>
+      <span>{user?.displayName ?? "Guest"}</span>
+      <SignedOut><a href="/login">Sign in</a></SignedOut>
+      <SignedIn><UserButton /></SignedIn>
+    </>
+  );
+}
+
+function AccountPage() {
+  const { user, isPending } = useCurrentUserState();
+  if (isPending) return null;             // session still resolving
+  if (!user) return <RedirectToSignIn />; // client-side Navigate — not window.location
+  return <h1>Welcome, {user.displayName}</h1>;
+}
+```
+
+Sign out with `<UserButton />` or `signOut()` from `@/lib/auth/client`.
+
+Session loading is the **same in live preview and when deployed**: wait for
+`isPending` from `useCurrentUserState()` (backed by `/api/auth/get-session`).
+The only live-preview difference is **how sign-in starts** (popup + bearer hand-off
+instead of a full-page OAuth redirect) — not how guests vs signed-in users are
+detected. Prefer `<RedirectToSignIn />` (TanStack `<Navigate>`) over
+`window.location.href = "/login"` so a signed-out redirect does not full-reload
+the SPA.
+
+## Preventing auth flicker
+
+`useSession()` resolves on the client, so a naive UI flashes signed-out →
+signed-in on load. Rules:
+
+1. **Gate on `isPending`, not `user` alone — and render a same-sized skeleton.**
+   Showing the SAME placeholder while `isPending` (server render + first client
+   paint) makes it one clean swap (skeleton → content) with no flash and no SSR
+   hydration mismatch. Don't return `null` in a slot that then grows — reserve the
+   space:
+
+   ```tsx
+   import { useCurrentUserState } from "@/lib/auth/use-current-user";
+   import { UserButton } from "@/lib/auth/gates";
+
+   function AuthSlot() {
+     const { user, isPending } = useCurrentUserState();
+     if (isPending) return <div className="h-8 w-8 animate-pulse rounded-full bg-black/10" />;
+     return user ? <UserButton /> : <a href="/login">Sign in</a>;
+   }
+   ```
+
+2. **Guard at a layout boundary** (nav / page shell), not in leaf components that
+   mount/unmount — `useSession` is one shared store, so keep one stable consumer
+   per region instead of re-gating everywhere.
+
+3. **Zero-flash when deployed: SSR the session from the cookie.** On a deployed
+   app (and top-level navigations) the session cookie is same-origin, so the server
+   already knows the user on the first request — resolve it in the root route and
+   render the authed shell immediately:
+
+   ```tsx
+   // src/routes/__root.tsx (excerpt)
+   import { createServerFn } from "@tanstack/react-start";
+   import { createRootRoute } from "@tanstack/react-router";
+
+   const fetchSessionUser = createServerFn({ method: "GET" }).handler(async () => {
+     // Cookie path only — works when deployed / on top-level loads.
+     const { getSessionUser } = await import("@/lib/auth/verify.server");
+     const u = await getSessionUser();
+     return u ? { id: u.id, email: u.email } : null;
+   });
+
+   export const Route = createRootRoute({
+     beforeLoad: async () => ({ sessionUser: await fetchSessionUser() }),
+     // Merge into the existing root — keep the existing head().
+     // component: prefer `sessionUser` for the FIRST paint when deployed, then
+     // `useCurrentUserState()` for live in-page updates.
+   });
+   ```
+
+   Sign-in/out navigate, so `beforeLoad` re-runs and the context stays fresh; call
+   `router.invalidate()` if you change auth state without navigating.
+
+   In live preview the session often rides a bearer after popup sign-in, so cookie
+   SSR may still return null until the client `useSession()` runs with the bearer
+   attached — still gate on `isPending`, same as when deployed.
+
+The template already enables Better Auth's `session.cookieCache`, so `/get-session`
+answers from a cookie when one is present (no DB round-trip).

package/skills/grok-auth/references/sign-in-methods.md

@@ -0,0 +1,55 @@
+# Supported sign-in methods (Google, X, email/password — and nothing else)
+
+Use **only** these three — no other method is supported:
+
+- **Google** and **X** — federated through the Grok broker (pre-wired here). The
+  broker federates these two upstreams and nothing else, so do **not** add entries
+  to `GROK_PROVIDERS` beyond them (the broker rejects an unknown `idp`).
+- **Email + password** — this app's OWN Better Auth, persisted in your database
+  (never the broker, never mocked). Better Auth is DB-backed in BOTH modes — real
+  Postgres when deployed and the embedded PGLite in the sandbox preview — so
+  email/password accounts are stored and survive across requests, **in preview
+  too**. It's off by default. Enable it by editing **only**
+  `src/lib/auth/email-password.ts`:
+
+  ```ts
+  // src/lib/auth/email-password.ts
+  export const emailAndPasswordEnabled = true; // was false
+  ```
+
+  **Do not edit or rewrite `src/lib/auth/server.ts`** (or any other file under
+  `src/lib/auth/` except `email-password.ts` for this flag). That file is
+  pre-wired; "fixing" it by regenerating Better Auth config breaks live-preview
+  sign-in.
+
+  The pre-applied schema already has the `account.password` column — no migration
+  needed. Then build sign-up / sign-in forms with `authClient.signUp.email(...)`
+  and `authClient.signIn.email(...)` from `@/lib/auth/client`.
+
+  **Do not** add `emailAndPassword` as a plugin entry (that is a syntax/type
+  error). **Do not** invent a new Better Auth config.
+
+  If sign-up/sign-in returns **"Invalid origin"**, do **not** disable CSRF and
+  do **not** edit `server.ts`. The template's `trustedOrigins` already covers
+  `*.grok-sandbox.com` and local loopback on port 8080 (`localhost` /
+  `127.0.0.1` / `[::1]`). Open the app at one of those origins (not a random
+  host/port).
+
+Do **NOT** add or use anything else: no other social / OAuth providers (GitHub,
+Apple, Discord, Microsoft, Facebook, …), and no magic links, passkeys, one-time
+codes / OTP, phone / SMS, or anonymous sign-in.
+
+## Security model (already handled — don't undo it)
+
+- **Headless broker**: the broker offers the upstream sign-in methods
+  and holds their shared secrets; this app only holds its own per-app client
+  id/secret and names the upstream it wants via each provider's `idp` hint. The
+  broker forwards straight to Google/X. Users never see the broker.
+- **`__Host-` cookies + `trustedOrigins`**: a sibling `*.grok.me` app can't toss a
+  `Domain=.grok.me` cookie, and Better Auth rejects cross-origin `/api/auth`
+  calls.
+- **Sibling isolation**: `authMiddleware` rejects scripted cross-site/same-site
+  requests (Fetch-Metadata), so a sibling can't ride this app's session cookie
+  into its server functions.
+- The upstream Google/X tokens live only on the broker; this app only ever gets a
+  broker-issued identity and mints its own local session.

package/skills/grok-auth/references/wiring.md

@@ -0,0 +1,71 @@
+# Wiring the routes (do this once)
+
+**Live-preview popup is PRE-WIRED — do not create it.**
+`signIn` opens `/auth/popup`; the template Vite plugin
+(`authPopupPlugin` in `vite.config.ts`) serves it via `popup.server.ts`.
+**Never** add `src/routes/auth/popup.tsx` (or any React page / client OAuth at
+that path). Doing so loads the full app shell in the popup ("the app opened
+instead of Google") — that is always wrong.
+
+**1. Mount Better Auth** — create the catch-all API route (this is what makes
+`/api/auth/*` work; the broker's OAuth callback lands here):
+
+```ts
+// src/routes/api/auth/$.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { auth } from "@/lib/auth/server";
+
+export const Route = createFileRoute("/api/auth/$")({
+  server: {
+    handlers: {
+      GET: ({ request }) => auth.handler(request),
+      POST: ({ request }) => auth.handler(request),
+    },
+  },
+});
+```
+
+**2. Add a sign-in page** — buttons that kick off the broker flow. Import from
+`@/lib/auth/client`. With the flag on, `authEnabled` is true in preview and
+deployed, so the buttons show and work in the live preview; the `else` branch
+shows while auth is still disabled (`VITE_AUTH_ENABLED=false`):
+
+```tsx
+// src/routes/login.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { GROK_PROVIDERS, authEnabled, signIn } from "@/lib/auth/client";
+
+export const Route = createFileRoute("/login")({ component: Login });
+
+function Login() {
+  return (
+    <main className="grid min-h-screen place-items-center p-6">
+      <div className="w-full max-w-sm space-y-3">
+        <h1 className="text-xl font-semibold">Sign in</h1>
+        {authEnabled ? (
+          GROK_PROVIDERS.map((p) => (
+            <button
+              key={p.providerId}
+              type="button"
+              onClick={() => signIn(p.providerId, { callbackURL: "/" })}
+              className="w-full cursor-pointer rounded-md border border-neutral-300 px-4 py-2 hover:bg-neutral-100 dark:border-neutral-700 dark:hover:bg-neutral-900"
+            >
+              Continue with {p.label}
+            </button>
+          ))
+        ) : (
+          <p className="text-sm text-neutral-500">Sign-in is disabled.</p>
+        )}
+      </div>
+    </main>
+  );
+}
+```
+
+`RedirectToSignIn` sends signed-out users to `/login` by default (override with
+`<RedirectToSignIn to="/somewhere" />`). Style the page however you like — see
+the `design-ui` skill.
+
+That's it — call `signIn(providerId)` from your sign-in buttons. The popup,
+bearer-token hand-off, and request attachment are all inside `src/lib/auth` +
+the Vite plugin; leave them alone.

package/skills/grok-building-games/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: building-games
+description: >
+  Build browser games and interactive/canvas/3D experiences in this TanStack
+  Start + React app. Use for any game, simulation, or WebGL/Canvas experience —
+  2D or 3D, single-player. Covers the game loop & timing, 3D orientation/camera
+  conventions, collision, performance, assets, audio, save, game feel, and
+  per-genre playbooks. For WASD / vehicle / flight **input signs and inverted
+  A/D**, open the **`controls`** skill — do not rely on this file or racing-kart
+  alone. Triggers on "game", "minecraft", "fps", "platformer", "racing",
+  "tetris", "snake", "shooter", "3d", "three.js", "canvas", "voxel", "physics".
+metadata:
+  short-description: "Browser games: loop, 3D orientation, camera, perf, assets, genres"
+user-invocable: false
+---
+
+# Building Games
+
+Build a **playable, correct** browser game — not a static screenshot. A game is
+just a React route with a `<canvas>` (or `<Canvas>` for R3F) plus DOM overlay UI.
+Style the overlay (start screen, HUD, menus) with the **`design-ui`** skill; this
+skill owns the gameplay loop and world.
+
+**Controls / inverted A/D:** open **`.grok/skills/controls/SKILL.md`** **before**
+writing WASD, steering, or flight input. Vehicle/flight demos often ship with
+A/D flipped if you only read this file or a single genre playbook.
+
+**Scope note — single-player, bots, or small P2P co-op:**
+- Ship **single-player** or **single-player + AI/bots** by default.
+- **2–8 player co-op / casual realtime** (shared cursors, party games, casual
+  action among friends) is supported — use the **`multiplayer-p2p` skill**
+  (WebRTC mesh, signaled at `/api/rtc`). Read its trust model first.
+- P2P is the only supported multiplayer right now. Do not half-build sockets
+  that can’t connect.
+
+**References (load on demand):**
+- **`controls` skill** (`../controls/`) — **required** for movement/steer/flight:
+  player-visible A/D, inverted-steer anti-pattern, flight ailerons, mandatory
+  self-test + `window.__controlsTest`. Not optional for vehicles/planes.
+- `references/threejs-foundational.md` — the deep 3D/loop/perf reference. Read for 3D.
+- `references/3d-libs.md` — three.js + @react-three/fiber + drei + rapier usage.
+- **`threejs` skill** (`../threejs/`) — official full Three.js + TSL API dump
+  (`llms-full.txt`). Load for advanced materials/shaders/WebGPU/loaders; not for
+  simple 2D canvas games.
+- `references/babylon.md` — Babylon.js, the batteries-included 3D engine alternative.
+- `references/phaser.md` — Phaser 3, the default engine for 2D games.
+- `references/ecs-architecture.md` — entity-component-system structure for larger games.
+- `references/genres/*.md` — per-genre playbooks (fps, platformer-2d, racing-kart,
+  puzzle-match3-tetris, voxel-minecraft, endless-runner, topdown-twin-stick,
+  tower-defense, board-card-chess). Genre files **do not** replace **`controls`**.
+- `references/game-feel-juice.md`, `input.md`, `audio.md`, `collision-physics.md`,
+  `save-persistence.md`, `procedural-generation.md`, `ai-pathfinding.md`.
+- **`game-asset-core`** (+ `game-animation-frames` / `game-tilesets` /
+  `game-character-consistency` / `game-ui-icons`) — engine-ready 2D art defaults
+  and verification when generating sprites, sheets, tiles, or UI (see §6).
+
+Pick the specific genre/topic reference for the build; this file is the universal
+core for loop/world. **Input signs → `controls`.** **2D game art → `game-asset-core`.**
+
+---
+
+## 1. Game loop & timing (the #1 correctness issue)
+
+- Drive the loop with the engine's RAF loop (`renderer.setAnimationLoop`, R3F
+  `useFrame`, or `requestAnimationFrame` for 2D canvas). **Never** `setInterval`/
+  `setTimeout`/`Date.now()` for game timing.
+- **Scale ALL movement/animation by delta time** (seconds) so speed is frame-rate
+  independent (60Hz vs 144Hz). Compute delta **once per frame** and reuse it.
+  - three.js: use `THREE.Timer` (not `Clock` — `Clock.getDelta()` returns ~0 on a
+    second call in the same frame, a classic freeze bug).
+- **Cap delta** (`min(delta, 0.1)`) so a backgrounded tab doesn't teleport things.
+- **Fixed timestep for physics/gameplay:** accumulate delta and step simulation at
+  a fixed rate (e.g. 1/60) while rendering at display rate — prevents tunneling and
+  non-determinism.
+
+## 2. Controls (delegate to the `controls` skill)
+
+**Open `.grok/skills/controls/SKILL.md` before implementing any WASD / steer /
+flight code.** That skill is the source of truth for:
+
+- Player-visible **A = left / D = right** (chase cam, while moving forward)
+- Why **`KeyA → steer−` + `yaw += steer * +rate` inverts** (most common bug)
+- Vehicle vs FPS (strafe ≠ steer), fixed-wing ailerons, heli/drone notes
+- Mandatory self-test + `window.__controlsTest` probe
+
+Do **not** treat `genres/racing-kart.md` as the only place steer signs live —
+planes, jetskis, and mechs never open it.
+
+**Short reminder (full detail in `controls`):**
+
+```
+// Vehicle yaw body (chase cam): A must increase yaw with this basis
+forward = (-sin(yaw), 0, -cos(yaw))
+// KeyA → steer = +1;  yaw += steer * turnRate * speedFactor * dt
+// WRONG (ships inverted): KeyA → steer = -1; yaw += steer * turnRate * dt
+```
+
+- **Pointer lock:** mouse-look only — implement WASD yourself; click-to-play
+  overlay; dismiss on lock.
+- Track keys with held state + **dt**; unify devices via `references/input.md`.
+- **Finish:** run the `controls` skill checklist. Screenshot-only is insufficient
+  for vehicles/flight.
+
+## 3. 3D orientation & world objects (the "sideways/backwards" bugs)
+
+- three.js is **right-handed, +Y up**: +X right, +Y up, +Z toward viewer. **Meshes
+  face +Z; cameras look −Z** (the classic "camera backwards" gotcha).
+- Primitives like `Cone`/`Cylinder` point **+Y** by default → rotate to align a
+  tip with forward (`geo.rotateX(Math.PI/2)`).
+- **Orienting a mesh to face `forward`** (meshes face **+Z**): simplest correct way
+  is `mesh.lookAt(mesh.position.clone().add(forward))`. To build the basis by hand,
+  set the **+Z column to `forward`** and choose the x-axis that keeps it a *proper*
+  right-handed rotation (`det = +1`):
+  `xAxis = normalize(cross(up, forward))`, then `makeBasis(xAxis, up, forward)`.
+  Note this is `cross(up, forward)` — **not** the movement `right = cross(forward, up)`
+  from §2. Targeting +Z (instead of a camera's −Z) flips the x-axis sign so that
+  `xAxis × up = forward`; the frame stays right-handed (no mirroring). Do **not** use
+  `makeBasis(xAxis, up, -forward)` for a mesh — that targets −forward (the *camera*
+  convention) so the mesh faces **backwards**.
+- **Orienting a camera** to look along `forward` (cameras look **−Z**): set the +Z
+  column to `-forward` — `xAxis = normalize(cross(forward, up))`, then
+  `makeBasis(xAxis, up, -forward)` (or just `camera.lookAt(target)`).
+- Keep a consistent world `up` so objects stay upright; only rotate flat primitives
+  to stand up.
+- Verify glTF import orientation; debug with `AxesHelper`/`ArrowHelper`. Upright
+  self-test: characters stand on the ground plane, not lying/sunk.
+
+## 4. Camera must agree with movement
+
+- Keep a **dedicated `moveForward`/`moveRight`** for movement, computed once and
+  never mutated by camera code (aliasing a shared temp vector makes camera and
+  movement disagree — a real repro bug).
+- Third-person follow: `desired = playerPos + up*height + moveForward*(-followDist)`;
+  lerp the camera toward it (use exp-based smoothing, delta-scaled), `lookAt(player)`.
+- Isolate-the-layer debug order: (1) keys register → (2) movement signs correct →
+  (3) camera agrees. Fix in that order.
+
+## 5. Performance
+
+- **Minimize draw calls** (`renderer.info.render.calls`, target <100): share
+  materials, `InstancedMesh`/`BatchedMesh` for repeated objects, atlases.
+- **Dispose GPU resources yourself** (`geometry/material/texture.dispose()`) on
+  level change — three.js does not GC them. **Pool** bullets/enemies/particles.
+- No per-frame allocations (reuse temp vectors). Compress textures; LOD for distance.
+
+## 6. Assets (avoid the generated-photo trap)
+
+- **Interactive 3D elements** (weapon viewmodels, characters, props, projectiles)
+  → build from **3D geometry / glTF**, not a generated image. A flat photorealistic
+  JPG of a gun-in-hands used as an FPS viewmodel looks wrong, can't animate, and
+  (JPG has **no alpha**) renders as a black box. Parent a real 3D viewmodel to the
+  camera as an overlay render layer.
+- Reserve image generation for **flat 2D** assets only (textures, sky/menu
+  backgrounds, 2D sprites, UI art). **Never** use a generated photo as a 3D mesh,
+  viewmodel, or character substitute — build those in 3D geometry / glTF.
+  Set `crossOrigin="anonymous"` on images drawn to canvas/textures.
+  See the **`imagine`** skill (2D only — image tools cannot produce real 3D).
+- **Engine-ready game art doctrine** → open **`game-asset-core`**
+  (`../game-asset-core/`) for defaults + blind verify + retry discipline, then the
+  matching specialist: **`game-animation-frames`** (loop / motion laws),
+  **`game-tilesets`**, **`game-character-consistency`**, **`game-ui-icons`**.
+  These are **QC/doctrine**, not the export pipeline. Do not ship stick-figure
+  placeholders when real art is expected.
+- **2D game sprites / animation sheets** → run **`generate2dsprite`**
+  (`.grok/skills/generate2dsprite/SKILL.md`): solid **`#FF00FF`** magenta
+  `imagine_text_to_image` sheets + chroma postprocess scripts (magenta is required for the
+  processor). Wire transparent PNGs/GIFs into Canvas/Phaser. Still apply
+  **`game-asset-core`** (+ animation/character specialists when relevant).
+- **2D maps / levels / prop packs** → open **`generate2dmap`**
+  (`.grok/skills/generate2dmap/SKILL.md`). Prefer foundation-only base + separate
+  props/collision for playable maps. Browser default: `raw_canvas` / Phaser.
+  Tileable ground/walls → also **`game-tilesets`** for 2×2 seam checks.
+- **Optional denser locomotion** → run **`video2dsprite`** (Grok
+  `imagine_image_to_video` + sandbox scripts; magenta base). Prefer `generate2dsprite`
+  for crisp production heroes. Use **`game-animation-frames`** for loop/flip-test
+  laws; prefer **`video2dsprite`** over ad-hoc ffmpeg-only harvest in this
+  sandbox.
+
+## 7. Audio, save, feel
+- **Audio**: unlock `AudioContext` on the first user gesture (tap-to-start) or iOS
+  is silent; re-resume on `visibilitychange`. (`references/audio.md`)
+- **Save**: `localStorage`/IndexedDB with a `version` field + migrations.
+- **Juice**: screen shake, hit-stop, eased tweens, particles — cheap, huge
+  perceived-quality lift. Keep presentation separate from simulation.
+
+## 8. Mobile
+- Distinguish canvas buffer size from CSS size; respect `devicePixelRatio`.
+- `touch-action: none`, letterbox-fit to a base resolution, handle orientation.
+- Touch controls (virtual joystick + action buttons), ≥44px targets.
+
+---
+
+## Stack / engine choice
+- **3D → three.js**, ideally via **@react-three/fiber + drei** (fits the React
+  app; drei gives pointer-lock/controls/loaders) + **@react-three/rapier** for
+  physics/character controllers. See `references/3d-libs.md`.
+- **2D →** native Canvas 2D is enough for snake/tetris/flappy/platformer; reach for
+  Phaser only when the genre needs it.
+- These game deps are **not preinstalled** — `npm install` them (and make sure they
+  land in `package.json` so the Vercel build has them).
+
+## Finish criteria (before "done")
+- Loads with **no console errors**; visible gameplay (not a blank canvas).
+- **`controls` skill self-test passed** (A = left / D = right from chase cam
+  while moving forward; flip one sign if inverted). Not screenshot-only.
+- 3D upright & camera-agrees self-tests pass (§3, §4).
+- Runs on mobile viewport with touch controls.
+- Production build (`npm run build`) renders the built output, not just dev.
+- **Share / X card:** open the **`og`** skill — custom `public/og.jpg` **and**
+  `"type": "x:game"` in `src/lib/og/site.json`. X uses `og:type="x:game"`
+  to present the unfurl as a game card; do not use `twitter:card` or invent
+  `x:type` for this. `browser-smoke` / `brand-check` warn when canvas apps omit
+  the `site.json` field.

package/skills/grok-building-games/agentsam.skill.json

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-building-games",
+  "name": "Grok \u00b7 building-games",
+  "description": "Browser games: loop, 3D orientation, camera, perf, assets, genres",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-building-games"
+  },
+  "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-building-games/references/3d-libs.md

@@ -0,0 +1,64 @@
+# 3D libraries for this stack (three.js + React Three Fiber + drei + rapier)
+
+The app is React/TanStack. The idiomatic way to do 3D here is **React Three
+Fiber (R3F)** — write three.js as React components inside a `<Canvas>` on a
+route. It deploys like any other page.
+
+> These are **not preinstalled**. Install and confirm they land in `package.json`:
+> `npm i three @react-three/fiber @react-three/drei @react-three/rapier`
+> (+ `npm i -D @types/three`). If the deploy build has no three, the game is blank.
+
+## When to use what
+- **three.js** — the engine. Raw three is fine for a self-contained canvas; prefer
+  R3F when the game has React UI/state around it.
+- **@react-three/fiber** — renders three as React; `useFrame((state, delta) => …)`
+  is your game loop (delta is seconds — scale movement by it, see SKILL §1).
+- **@react-three/drei** — helpers so you don't hand-roll bug-prone code:
+  `<PointerLockControls/>`, `useKeyboardControls`, `<OrbitControls/>`,
+  `useGLTF`, `<Environment/>`, `<Instances/>`, `<Stats/>`.
+- **@react-three/rapier** — physics + **character controller** (capsule +
+  autostep + snap-to-ground). Use for FPS/platformer movement and collisions
+  instead of hand-rolled raycasts. `<Physics>`, `<RigidBody>`, `useRapier`.
+
+## Minimal R3F shape
+```tsx
+import { Canvas, useFrame } from "@react-three/fiber";
+import { PointerLockControls, useKeyboardControls } from "@react-three/drei";
+
+function Player() {
+  useFrame((_, delta) => {
+    const d = Math.min(delta, 0.1);       // cap delta (SKILL §1)
+    // move with a dedicated moveForward/moveRight basis (SKILL §2/§4)
+  });
+  return null;
+}
+
+export default function Game() {
+  return (
+    <Canvas camera={{ position: [0, 1.7, 5], fov: 75 }} shadows dpr={[1, 2]}>
+      {/* scene */}
+      <PointerLockControls />   {/* mouse-look ONLY — implement WASD yourself */}
+      <Player />
+    </Canvas>
+  );
+}
+```
+
+## Gotchas (map to the SKILL universals)
+- **Controls:** drei `PointerLockControls` is mouse-look only — WASD is yours
+  (SKILL §2). Gate `.lock()` behind a "click to play" overlay and dismiss it on lock.
+- **Orientation:** meshes face +Z, camera looks −Z; right-handed +Y up (SKILL §3).
+- **Delta:** `useFrame` delta is seconds; cap it; fixed-step physics via rapier's
+  own stepping. Don't read `THREE.Clock.getDelta()` twice a frame.
+- **Perf:** `<Instances>`/`InstancedMesh` for repeats; dispose on unmount (R3F
+  auto-disposes objects it created, but not manual textures/loaders — dispose those).
+  Set `dpr={[1, 2]}` to cap retina cost.
+- **Mobile:** R3F sets pixel ratio via `dpr`; still add touch controls + `touch-action:none`.
+
+## Alternatives
+- **Babylon.js** (`references/babylon.md`) — batteries-included 3D (Havok physics,
+  inspector, SceneOptimizer). Viable if you want an all-in-one engine, but it's a
+  separate paradigm from React; default to three/R3F for consistency with the app.
+
+Sources: R3F docs (https://r3f.docs.pmnd.rs), drei (https://github.com/pmndrs/drei),
+react-three-rapier (https://github.com/pmndrs/react-three-rapier), three.js docs.