@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/skills/grok-og/references/custom-card.md

@@ -0,0 +1,107 @@
+# Custom card: generate `public/og.jpg`
+
+For prompt-craft, composition, and blind read-back verification, follow the
+`imagine` and `game-asset-core` skills — this file owns the **card-specific**
+contract only (size, lockup, wiring).
+
+1. **Set the canvas with `aspect_ratio: "16:9"`.** The call looks like
+   `{ "prompt": "…", "aspect_ratio": "16:9" }` — ratio words in the prompt do
+   **not** set the canvas. At 2mp, 16:9 renders 1792×1008, so the normalize
+   below cover-crops to 1200×630 trimming only ~3% vertically, which a
+   centered title survives. A narrower canvas is what kills titles: from 3:2
+   the same crop takes **~21% vertically**, straight through the lockup.
+   Paths:
+
+   - **Default — one call with `aspect_ratio: "16:9"`:** `imagine_text_to_image`
+     with the art + baked title. **Check the output dimensions** via
+     `read_file` / Pillow on the returned `file_path`; if the ratio missed, reframe or use
+     the API path.
+   - **Reframe if needed:** pass the prior `file_path` into `imagine_image_to_image`
+     with **`aspect_ratio: "16:9"`** and a prompt like "extend the scenery
+     left and right into a wider frame; keep the title lettering and
+     central subject exactly as they are".
+   - **Optional — true 2:1 via the xAI Images API:** `POST
+     https://api.x.ai/v1/images/generations` with `"aspect_ratio": "2:1"`
+     and `response_format: "b64_json"` using the injected `XAI_API_KEY`
+     (see the `xai-api` skill). 2mp 2:1 is 1984×992; normalize then trims
+     only ~2.4% per side and nothing vertical.
+
+   Build the prompt from the app's theme, palette, and characters. If the
+   app already has a key generated asset (hero sprite, title scene), pass
+   its `file_path` into `imagine_image_to_image` so the card matches in-game art —
+   same 16:9 + check-the-output rule applies.
+   **Last resort only** (no `imagine_text_to_image` and no xAI Images API): stay
+   on whatever canvas you have and keep the entire title block inside the
+   **middle half** of the frame height, with the crop-clipping check in
+   step 6 as the gate.
+2. **Bake the title in like a game cover.** Store-page covers (Stardew Valley,
+   Cuphead) lead with a short stylized logo-type title. Put the exact app name
+   in quotes in the prompt; 1–3 strong words; optional short tagline under the
+   title in smaller lettering (exact words in quotes).
+   - **Stack multi-word titles** into a two-line lockup ("SKY" over "STRIKE").
+   - **Center the block both ways** with generous margins — avoid "upper third"
+     / percentage placement (models hug the edge).
+   - **Bound the width**: lettering spans roughly half to two-thirds of the
+     frame, never border to border.
+   - **Keep comfortable margins anyway.** From a 16:9 canvas the normalize
+     below trims only ~3% vertically; from a 2:1 API canvas it trims
+     nothing vertical and ~2.4% per side. The crop turns destructive when
+     the canvas comes back off-ratio — an edit that pinned to its input's
+     ratio, or a model miss — so **check the raw canvas dimensions before
+     cropping**, and re-ratio first if it isn't ~16:9 or 2:1.
+3. **Verify glyphs *and* layout on read-back** (see `imagine` / `game-asset-core`
+   for the blind-describe loop). On a garble or layout miss, **regenerate with a
+   corrected prompt** — never try to move a logo with `imagine_image_to_image` (frame
+   translation / seams). After two failed attempts, ship the card **artwork-only**
+   (titleless).
+
+   **Intentional exception vs `imagine`'s "rebuild text with code" rule:** the
+   share card is a single static PNG; there is no reliable in-sandbox path to
+   composite crisp code-drawn lettering onto generative art for this asset, so
+   a clean titleless card is the correct fallback after two glyph failures.
+4. **Normalize to exactly 1200×630 JPEG** with the baked-in ffmpeg (cover-crop —
+   from 16:9 this shaves ~3% top/bottom; from 2:1 ~2.4% per side and
+   nothing vertical). **JPEG, not PNG**: the card is
+   photographic generative art, and a PNG of it lands at 1–2 MB — heavy
+   enough that link scrapers (X card previews included) time out or skip the
+   image, so the card silently fails to unfurl. JPEG at this quality is
+   ~150–300 KB with no visible loss at unfurl size:
+
+   ```sh
+   ffmpeg -y -i card-raw.jpg \
+     -vf "scale=1200:630:force_original_aspect_ratio=increase,crop=1200:630" \
+     -q:v 4 /workspace/.grok/og.jpg.tmp
+   node scripts/write-atomic.mjs /workspace/.grok/og.jpg.tmp public/og.jpg
+   ```
+
+5. **Tell the injector the card is custom** — set `"card": "custom"` in
+   `src/lib/og/site.json`, handed over the same way, and keep `public/og.jpg`:
+
+   ```sh
+   node scripts/write-atomic.mjs /workspace/.grok/site.json.tmp src/lib/og/site.json
+   ```
+
+   Bake also infers custom
+   from the file if the flag is missing, but brand-check still requires the
+   field. The injector emits the absolute `https://${host}/og.jpg` URL. Do not
+   add `og:image` to `__root.tsx`.
+6. **Verify before finishing** (Pillow is installed; `ffprobe` is **not**):
+
+   ```sh
+   python3 -c "
+   from PIL import Image; import os
+   im = Image.open('public/og.jpg')
+   kb = os.path.getsize('public/og.jpg') // 1024
+   print(im.size, f'{kb} KB')"
+   # expect: (1200, 630) and under 600 KB (keeps X and other scrapers
+   # reliable; target <= 300 KB — if over, bump -q:v up a step and re-encode)
+   ```
+
+   **Read back the final `public/og.jpg`, not the pre-crop raw** — the crop
+   is where clipping happens. This is a **hard gate, not an impression**:
+   if any title glyph touches a frame edge or is visibly cut, the card is
+   **rejected** — do not ship it, whatever else is right about it. Fix the
+   ratio (step 1) or regenerate with the width bound restated; a shipped
+   decapitated title is worse than the placeholder. Then confirm the card
+   reads like *this* app at thumbnail size — clear subject, correctly
+   spelled title (if any), comfortable margins.

package/skills/grok-og/references/favicon-and-icons.md

@@ -0,0 +1,48 @@
+# Favicon and PWA icons
+
+## Favicon: hand-author `public/favicon.svg`
+
+Every app gets one, and it works in live preview immediately (no host needed).
+
+- **Write the SVG by hand — never `imagine_text_to_image`.** It must stay crisp at 16px:
+  one bold glyph or shape, flat fills from the app's design tokens, a square
+  `viewBox`, a handful of elements at most. For whimsical apps an emoji-text
+  SVG is a fine quick win:
+
+  ```svg
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+    <rect width="100" height="100" rx="20" fill="#1a1b26"/>
+    <text x="50" y="50" font-size="62" text-anchor="middle"
+      dominant-baseline="central">🥕</text>
+  </svg>
+  ```
+
+- Wire it in the root `head()`:
+
+  ```tsx
+  links: [
+    { rel: "icon", type: "image/svg+xml", href: "/favicon.svg" },
+    { rel: "stylesheet", href: appCss },
+  ],
+  ```
+
+- Verify it renders non-blank and legible small (browser tab in a preview
+  screenshot, or read back a rasterized copy). Update it when the app's theme
+  or name changes meaning — it is part of the app's identity, not a set-and-forget.
+
+## PWA icons: only for installable apps
+
+When the app ships a web manifest (the user asked for installable / PWA /
+home-screen behavior — do **not** invent a manifest just to have icons), add
+raster icons derived from the favicon artwork so the identity stays
+consistent:
+
+- `public/icon-192.png` and `public/icon-512.png` — the favicon's glyph on
+  its tile, rasterized at size. Playwright (baked into the sandbox) can
+  screenshot the served `/favicon.svg` at a 192/512 viewport; or redraw the
+  same mark as a flat PNG. Keep it bold and flat — no photographic detail.
+- A maskable variant (`"purpose": "maskable"`) needs the glyph inside the
+  center ~80% safe zone so launcher shapes don't clip it.
+- Wire the manifest `icons` array plus `theme_color` / `background_color`
+  from the app's design tokens, and read the 192 back to confirm it stays
+  legible.

package/skills/grok-og/references/og-type-contract.md

@@ -0,0 +1,18 @@
+# `og:type` — why `x:game`, and the rejected alternatives
+
+The game signal is written as `"type": "x:game"` in `src/lib/og/site.json`; the
+platform injector turns it into `<meta property="og:type" content="x:game">`.
+This will live forever in every shipped game, so the channel is fixed:
+
+| Option | Verdict |
+| --- | --- |
+| **`site.json` `"type": "x:game"` → injector emits `<meta property="og:type" content="x:game">`** | **Chosen.** You write the field in `src/lib/og/site.json`; the PWA injector emits the standard OG content-type property. Value is a **namespaced type** (`x:game`) so it cannot be confused with a future global OGP `game` type or bare `website`. X's card pipeline keys off this exact emitted value. Do not put the meta tag in `__root.tsx`. Do not shorten to bare `game`. |
+| **`og:type="game"` (no `x:`)** | **Rejected.** Looks like a global OGP type that does not exist on [ogp.me](https://ogp.me/#types); the product contract is the namespaced `x:game` string. |
+| **`twitter:card`** | **Wrong layer for the game signal.** Layout only (`summary_large_image`). The PWA injector always emits it — do not treat the `og` skill as the place that adds it. Never use it as the game type. |
+| **Separate `x:type` / `x:card` meta properties** | **Do not invent.** Extra properties double surface area (agents forget one of two tags). Namespacing inside `og:type`'s content (`x:game`) is enough. |
+
+X (Twitter) uses `og:type="x:game"` when unfurling `*.grok.me` links to present
+the card as a **game** rather than a generic website. This is a product contract
+with X's card pipeline — keep the tag, and do not "correct" it to `website`
+during refactors. Non-games should omit `og:type` or use `website` (the scraper
+default).

package/skills/grok-og/references/placeholder-card.md

@@ -0,0 +1,21 @@
+# The placeholder `og.grok.me` card (plain utility apps)
+
+An app with no `public/og.jpg` unfurls with the hosted placeholder:
+
+```
+https://og.grok.me/v1/card.png?host={VITE_PUBLIC_HOSTNAME}&title={APP_NAME}
+```
+
+The injector builds that URL — do not paste it into `__root.tsx`.
+
+- Optional theme colour: set `"color": "FF4D2E"` in `src/lib/og/site.json`
+  (6-digit hex, `#` optional). The injector appends `&color=` on the placeholder
+  URL; a themed URL written into `__root.tsx` is stripped. Custom cards ignore
+  `color`.
+- On rename, update `APP_NAME` (tab title) **and** `site.json` `title` (share
+  card).
+
+Live preview emits the same tags (the preview `X-Forwarded-Host` is a valid
+image host). On publish the request `Host` is enough — do **not** write a `.env`
+for it. Card pixels and `site.json` reach the unfurl on the **next deploy**
+(identity is baked at `vite build`).

package/skills/grok-og/references/x-banner.md

@@ -0,0 +1,41 @@
+# X feed card: `public/x-banner.jpg` (50:11)
+
+**Games also ship a second, much wider card** that X uses in the feed (the
+link-preview `og.jpg` is still required — this does not replace it). Write
+`public/x-banner.jpg` at **exactly 50:11** (1200×264 — 1200 is the standard
+max card width on the web, same as `og.jpg`). The injector emits
+`x:game:image` (1200×264) from that file when the request has a public host.
+Do **not** invent `x:game:og` or overload `og:image`. Do not add
+`x:game:image` to `__root.tsx`.
+
+Same JPEG / size discipline as `og.jpg` (keep it well under 600 KB).
+**Custom `public/x-banner.jpg` — games only.** Use `imagine_text_to_image`
+(or `imagine_image_to_image`) to generate a custom banner **only when the
+app is a game**. Non-games omit the file — the injector then emits no
+`x:game:image`. Do not paste `og.grok.me/v1/banner.png` (or any
+`x:game:image`) into `__root.tsx`; the injector strips those tags.
+Generate the art at 50:11 (`aspect_ratio: "50:11"` on
+`imagine_text_to_image` — that ratio is on the Imagine schema; do **not**
+substitute 16:9 and crop). Then normalize:
+
+```sh
+ffmpeg -y -i banner-raw.jpg \
+  -vf "scale=1200:264:force_original_aspect_ratio=increase,crop=1200:264" \
+  -q:v 4 /workspace/.grok/x-banner.jpg.tmp
+node scripts/write-atomic.mjs /workspace/.grok/x-banner.jpg.tmp public/x-banner.jpg
+```
+
+**Safe lockup.** Unlike the centered `og.jpg` card, keep title, tagline, and
+other critical content inside the **left-most 50% × top-most 80%** of the
+finished 1200×264. Feed chrome overlays the **right ~25%** and **bottom
+~20%**, so lettering there clashes. Raise the lockup above the midline (do
+not vertically center it); comfortable left and top margins; never
+edge-hug: a 50:11 frame decapitates edge-hugging lettering even faster than
+the 1200×630 card. Scenery and characters may extend into those overlay
+strips. Prompt Imagine in visual language — "title lockup in the left half,
+sitting above the midline, empty strip along the bottom edge" — not
+percentages. Reuse the link-cover art when you can (reframe the same scene
+wider rather than inventing a second identity). Verify the 1200×264 JPEG
+the same way as `og.jpg` (dimensions + under 600 KB + no clipped title).
+Reject if any title or tagline glyph sits in the right half or the bottom
+fifth of the frame.

package/skills/grok-threejs/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: threejs
+description: >
+  Official Three.js API and TSL (Three.js Shading Language) reference for LLM
+  code generation. Load when writing or debugging three.js / WebGL / WebGPU /
+  custom materials / shaders / GLTF / advanced three APIs beyond basic game
+  loop/controls. Prefer building-games for game correctness (loop, WASD,
+  camera, orientation); use this skill for full API/TSL depth. Triggers on
+  "three.js", "threejs", "WebGPU", "TSL", "NodeMaterial", "shader", "GLTF",
+  "MeshStandard", "OrbitControls", "WebGLRenderer".
+metadata:
+  short-description: "Three.js + TSL full API (official llms-full reference)"
+user-invocable: false
+---
+
+# Three.js (official LLM reference)
+
+This skill vendors the **official** Three.js LLM documentation pack so the agent
+can generate correct modern three.js without inventing outdated CDN/r128 APIs.
+
+## Stack adaptation (this app builder)
+
+You are in a **TanStack Start + React** workspace, not a bare HTML page:
+
+| Official doc pattern | Do this here instead |
+| --- | --- |
+| `<script type="importmap">` + CDN three | **`npm install three`** (+ `@types/three` if needed); import from `"three"` / `"three/addons/…"` |
+| Raw HTML canvas bootstrap | Prefer **@react-three/fiber + drei** for games/UI integration (`building-games` + `3d-libs.md`) |
+| Standalone `WebGLRenderer` demo | Fine for a self-contained canvas module; still install three via npm so Vercel build has it |
+| Always “latest” CDN version | Pin via **package.json** so dev and deploy match |
+
+**three is not preinstalled** — add it with npm and leave it in `package.json`.
+
+## When to load what
+
+1. **Game / interactive 3D product** → start with **`building-games`** (loop, controls, orientation, camera, first-run, steer sign).
+2. **R3F / drei / rapier wiring** → `building-games/references/3d-libs.md`.
+3. **Deep three API, TSL, WebGPU, materials, loaders, postprocessing** → load  
+   **`references/llms-full.txt`** (this skill’s full official dump).
+
+Do **not** load `llms-full.txt` for simple 2D canvas games (Pong, tetris, etc.).
+
+## Full reference
+
+**Read on demand:**
+
+```text
+references/llms-full.txt
+```
+
+Source: https://threejs.org/docs/llms-full.txt (pinned copy for offline sandbox use).
+
+Contents include: modern imports, WebGLRenderer vs WebGPURenderer, TSL complete
+reference, NodeMaterial, loaders, post-processing, compute, and API tables.
+
+## Quick defaults for this product
+
+- Prefer **WebGLRenderer** (or R3F default) unless the user needs TSL/WebGPU compute.
+- Cap pixel ratio (`renderer.setPixelRatio(Math.min(devicePixelRatio, 2))` or R3F `dpr={[1,2]}`).
+- Dispose geometries/materials/textures on teardown (three does not GC GPU resources).
+- For games: still obey **`building-games`** control and orientation self-tests.
+
+## Finish check
+
+- three (and R3F stack if used) is in `package.json` and imports resolve.
+- No r128 / cdnjs script-tag patterns.
+- If TSL/WebGPU used: materials and imports match `llms-full` (node materials, `await renderer.init()`).

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

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-threejs",
+  "name": "Grok \u00b7 threejs",
+  "description": "Three.js + TSL full API (official llms-full reference)",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-threejs"
+  },
+  "instructions": {
+    "source": "local_file",
+    "ref": "SKILL.md"
+  },
+  "execution": {
+    "mode": "turn",
+    "tools": [],
+    "operations": [],
+    "capabilities": []
+  },
+  "provenance": {
+    "source": "apps/local-studio/.grok/skills",
+    "vendor": "grok",
+    "status": "imported"
+  }
+}