@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/skills/grok-multiplayer-p2p/references/signaling-relay.md

@@ -0,0 +1,269 @@
+# Signaling relay and API route (create once)
+
+The relay is **yours**, not part of the kit: copy it as-is or serve the same
+`RtcPollResponse` shape from any store. Only rendezvous traffic (roster +
+SDP/ICE) passes through it; game data flows peer-to-peer.
+
+## Schema — nothing to do by default
+
+The relay below creates its two tables on first use
+(`CREATE TABLE IF NOT EXISTS`, once per process) — nothing ships in
+`migrations/` and the template itself never touches your database. If you'd
+rather own or extend the schema (extra columns, your own migration ordering),
+copy this into one of your app migrations; `IF NOT EXISTS` makes the runtime
+ensure and your migration coexist safely:
+
+```sql
+-- CREATE TABLE IF NOT EXISTS webrtc_peers (
+--   room TEXT NOT NULL,
+--   peer_id TEXT NOT NULL,
+--   name TEXT NOT NULL DEFAULT '',
+--   last_seen TIMESTAMPTZ NOT NULL DEFAULT now(),
+--   PRIMARY KEY (room, peer_id)
+-- );
+-- CREATE TABLE IF NOT EXISTS webrtc_signals (
+--   id BIGSERIAL PRIMARY KEY,
+--   room TEXT NOT NULL,
+--   to_peer TEXT NOT NULL,
+--   from_peer TEXT NOT NULL,
+--   kind TEXT NOT NULL,
+--   payload JSONB NOT NULL,
+--   created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+-- );
+-- CREATE INDEX IF NOT EXISTS webrtc_signals_inbox
+--   ON webrtc_signals (room, to_peer, id);
+```
+
+## `src/lib/multiplayer/signaling.server.ts`
+
+Copy this file as-is (or adapt it — it is yours, not part of the kit):
+
+```ts
+// src/lib/multiplayer/signaling.server.ts
+/**
+ * WebRTC signaling over the app database (Neon deployed, PGLite in preview).
+ * Only rendezvous traffic passes through here — roster + SDP/ICE relay while a
+ * mesh forms; game data then flows peer-to-peer. DB-backed so any serverless
+ * instance can serve any poll. Mount at /api/rtc (see the multiplayer-p2p
+ * skill); the client side lives in `@/lib/multiplayer`.
+ *
+ * The GET poll is the whole peer lifecycle: the first poll (since=0) IS the
+ * join — it registers the peer, returns the roster, and prunes stale rows.
+ * Peer ids are random per mount, so a fresh inbox never has old signals to
+ * skip and no join/cursor handshake is needed.
+ */
+import { z } from "zod";
+import { getSql, type Sql } from "@/lib/db";
+import type { PeerRow, RtcPollResponse, SignalRow } from "./p2p";
+
+const ID = z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/);
+const signalSchema = z.object({
+  op: z.literal("signal"),
+  room: ID,
+  from: ID,
+  to: ID,
+  kind: z.enum(["offer", "answer", "ice"]),
+  // SDP offers are typically 3–10KB; the cap only blocks abuse (payload is
+  // re-serialized at insert — cheap at this size). An absent
+  // payload is rejected here (JSON.stringify(undefined) has no .length).
+  payload: z.unknown().refine((v) => v !== undefined && JSON.stringify(v).length <= 32_768, {
+    message: "payload too large",
+  }),
+});
+const leaveSchema = z.object({ op: z.literal("leave"), room: ID, peer: ID });
+const postSchema = z.discriminatedUnion("op", [signalSchema, leaveSchema]);
+
+
+const PEER_TTL_SECONDS = 30;
+const SIGNAL_TTL_SECONDS = 60;
+
+/**
+ * The kit ships no migration: tables are created on first use (IF NOT EXISTS)
+ * so the app's migrations/ namespace stays fully in the agent's hands. Agents
+ * who want to own/extend the schema can copy the DDL from the multiplayer-p2p
+ * skill into their own migration — both coexist safely. Memoized on globalThis
+ * (the db.ts pattern) so dev HMR never runs two ensures concurrently; a failed
+ * ensure clears the slot so the next request retries.
+ */
+const globalRef = globalThis as typeof globalThis & {
+  __rtcSchemaPromise__?: Promise<void>;
+};
+
+function ensureSchema(sql: Sql): Promise<void> {
+  globalRef.__rtcSchemaPromise__ ??= (async () => {
+    await sql.query(
+      `CREATE TABLE IF NOT EXISTS webrtc_peers (
+         room TEXT NOT NULL,
+         peer_id TEXT NOT NULL,
+         name TEXT NOT NULL DEFAULT '',
+         last_seen TIMESTAMPTZ NOT NULL DEFAULT now(),
+         PRIMARY KEY (room, peer_id)
+       )`,
+    );
+    await sql.query(
+      `CREATE TABLE IF NOT EXISTS webrtc_signals (
+         id BIGSERIAL PRIMARY KEY,
+         room TEXT NOT NULL,
+         to_peer TEXT NOT NULL,
+         from_peer TEXT NOT NULL,
+         kind TEXT NOT NULL,
+         payload JSONB NOT NULL,
+         created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+       )`,
+    );
+    await sql.query(
+      `CREATE INDEX IF NOT EXISTS webrtc_signals_inbox
+         ON webrtc_signals (room, to_peer, id)`,
+    );
+  })().catch((err) => {
+    globalRef.__rtcSchemaPromise__ = undefined;
+    throw err;
+  });
+  return globalRef.__rtcSchemaPromise__;
+}
+
+async function roster(sql: Sql, room: string): Promise<PeerRow[]> {
+  // LIMIT bounds the blast radius of room-stuffing; the mesh caps out ~8.
+  const rows = await sql.query<{ peer_id: string; name: string }>(
+    `SELECT peer_id, name FROM webrtc_peers
+     WHERE room = $1 AND last_seen > now() - make_interval(secs => $2)
+     ORDER BY peer_id LIMIT 32`,
+    [room, PEER_TTL_SECONDS],
+  );
+  return rows.map((r) => ({ id: r.peer_id, name: r.name }));
+}
+
+async function touchPeer(sql: Sql, room: string, peer: string, name: string) {
+  await sql.query(
+    `INSERT INTO webrtc_peers (room, peer_id, name, last_seen)
+     VALUES ($1, $2, $3, now())
+     ON CONFLICT (room, peer_id)
+     DO UPDATE SET last_seen = now(), name = EXCLUDED.name`,
+    [room, peer, name],
+  );
+}
+
+/**
+ * Rows are ephemeral; GC rides the polls instead of a cron: joins (since=0)
+ * always prune, and ~2% of all other polls do too — so a busy room whose
+ * cursors always advance still gets swept, without every heartbeat paying
+ * the two DELETEs.
+ */
+async function prune(sql: Sql) {
+  await Promise.all([
+    sql.query(`DELETE FROM webrtc_signals WHERE created_at < now() - make_interval(secs => $1)`, [
+      SIGNAL_TTL_SECONDS,
+    ]),
+    sql.query(`DELETE FROM webrtc_peers WHERE last_seen < now() - make_interval(secs => $1)`, [
+      PEER_TTL_SECONDS,
+    ]),
+  ]);
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/** GET /api/rtc?room&peer&name&since — join (since=0), heartbeat, and inbox. */
+async function handleGet(url: URL): Promise<Response> {
+  const parsed = z
+    .object({
+      room: ID,
+      peer: ID,
+      name: z.string().max(64).default(""),
+      since: z.coerce.number().int().min(0).default(0),
+    })
+    .safeParse({
+      room: url.searchParams.get("room"),
+      peer: url.searchParams.get("peer"),
+      name: url.searchParams.get("name") ?? "",
+      since: url.searchParams.get("since") ?? 0,
+    });
+  if (!parsed.success) return json({ error: "invalid query" }, 400);
+  const { room, peer, name, since } = parsed.data;
+
+  const sql = await getSql();
+  await ensureSchema(sql);
+  if (since === 0 || Math.random() < 0.02) await prune(sql);
+  await touchPeer(sql, room, peer, name);
+  const rows = await sql.query<{
+    id: number;
+    from_peer: string;
+    kind: SignalRow["kind"];
+    payload: unknown;
+  }>(
+    `SELECT id, from_peer, kind, payload FROM webrtc_signals
+     WHERE room = $1 AND to_peer = $2 AND id > $3
+     ORDER BY id LIMIT 200`,
+    [room, peer, since],
+  );
+  const body: RtcPollResponse = {
+    peers: await roster(sql, room),
+    signals: rows.map((r) => ({
+      id: r.id,
+      from: r.from_peer,
+      kind: r.kind,
+      payload: r.payload,
+    })),
+  };
+  return json(body);
+}
+
+async function handlePost(request: Request): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return json({ error: "invalid JSON" }, 400);
+  }
+  const parsed = postSchema.safeParse(body);
+  if (!parsed.success) return json({ error: "invalid request" }, 400);
+  const msg = parsed.data;
+  const sql = await getSql();
+  await ensureSchema(sql);
+
+  if (msg.op === "signal") {
+    await sql.query(
+      `INSERT INTO webrtc_signals (room, to_peer, from_peer, kind, payload)
+       VALUES ($1, $2, $3, $4, $5)`,
+      [msg.room, msg.to, msg.from, msg.kind, JSON.stringify(msg.payload)],
+    );
+  } else {
+    await sql.query(`DELETE FROM webrtc_peers WHERE room = $1 AND peer_id = $2`, [
+      msg.room,
+      msg.peer,
+    ]);
+  }
+  return json({ ok: true });
+}
+
+/** Request entrypoint for the /api/rtc route (GET poll, POST signal/leave). */
+export async function handleSignaling(request: Request): Promise<Response> {
+  try {
+    if (request.method === "GET") return await handleGet(new URL(request.url));
+    if (request.method === "POST") return await handlePost(request);
+    return json({ error: "method not allowed" }, 405);
+  } catch (error) {
+    console.error("[rtc] signaling error:", error);
+    return json({ error: "signaling failed" }, 500);
+  }
+}
+```
+
+## Mount the API route
+
+
+```ts
+// src/routes/api/rtc.ts
+import { createFileRoute } from "@tanstack/react-router";
+import { handleSignaling } from "@/lib/multiplayer/signaling.server";
+
+const handle = ({ request }: { request: Request }) => handleSignaling(request);
+
+export const Route = createFileRoute("/api/rtc")({
+  server: { handlers: { GET: handle, POST: handle } },
+});
+```

package/skills/grok-neon/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: neon
+description: >
+  Use Neon Postgres (the database) in this TanStack Start app. Use when the app
+  needs to store or query data, persist state, or keep per-user data. Triggers on
+  "database", "Postgres", "Neon", "save data", "store data", "persist", "tables",
+  "SQL", "query", "migrations".
+metadata:
+  short-description: "Neon Postgres (with a local PGLite fallback) for this template"
+user-invocable: false
+---
+
+# Neon Postgres
+
+**The database is opt-in** (AGENTS.md §0.5): use it only when the app needs data
+that outlives a browser session or is shared across devices. Otherwise ship no
+migrations, don't import `@/lib/db`, and keep state in `localStorage` / zustand.
+
+This template ships a ready-made, **dual-mode** database integration:
+
+- **Configured** (env var set, e.g. deployed): real **Neon Postgres**.
+- **Not configured** (sandbox live preview): the DB falls back to a local
+  **PGLite** (embedded WASM Postgres), so the preview always renders. Build
+  against the `@/lib/db` helper; both modes work with the same API.
+
+Packages are **preinstalled** — do not `npm install` them: `pg` (node-postgres,
+the regular Postgres driver) and `@electric-sql/pglite` (local DB fallback).
+
+For **user accounts, sign-in, and reading the current user**, see the separate
+**`auth` skill** — this skill is just the database.
+
+## Turning the database on
+
+Set `deploy.database` to `true` in `.grok/app-env.json`:
+
+```json
+{ "VITE_AUTH_ENABLED": "false", "deploy": { "database": true } }
+```
+
+That is what tells the platform to provision Neon for the deployed app; leave it
+`false` and the deploy gets no `DATABASE_URL`, so the app silently runs on a
+throwaway PGLite that loses its rows. Shipping `migrations/*.sql`, or sign-in,
+provisions one regardless — this flag is for an app that queries `@/lib/db`
+without either. It is not a `VITE_` key and never reaches the browser.
+
+## Env vars — do **not** create a `.env` file
+
+**Never write a `.env` / `.env.local` / `.env.example` for the database.** In
+the sandbox live preview, leave `DATABASE_URL` unset — `@/lib/db` automatically
+uses embedded PGLite. When the app is deployed, the platform injects
+`DATABASE_URL` (Neon); you do not provision or write it yourself.
+
+| Var | Where | Purpose |
+|---|---|---|
+| `DATABASE_URL` | server | Neon connection string when deployed (optional — PGLite fallback if unset) |
+
+Never hardcode it; never expose non-`VITE_` vars to the client.
+
+## Database (server-only)
+
+`@/lib/db` exports `getSql()` and `dbSource`: a **regular Postgres driver**
+(node-postgres, `pg`) against `DATABASE_URL`, or a local **PGLite** fallback when
+unset. Same API either way — a tagged template (and `.query()`) resolving to
+`rows[]`. Call ONLY from a `createServerFn` handler / server loader, never a
+client component. Define schema in `migrations/`, not inline.
+
+```ts
+import { createServerFn } from "@tanstack/react-start";
+import { getSql } from "@/lib/db";
+
+export const listPosts = createServerFn({ method: "GET" }).handler(async () => {
+  const sql = await getSql();
+  // Type the row shape — a server fn's return must be provably serializable.
+  return sql<{ id: number; title: string }>`select id, title from posts order by id desc`;
+  // or: return sql.query<{ id: number; title: string }>("select id, title from posts where id = $1", [id]);
+});
+```
+
+**Per-user data (only once the app has sign-in).** A regular driver has full DB
+access, so scope **every** query to the authenticated user server-side — never
+trust a client-sent id. Use the prewired **`authMiddleware`** to get a verified
+`context.userId`, then filter by it. Full pattern (middleware, calling from
+client code, fail-closed semantics) is in the **`auth` skill**:
+
+```ts
+import { authMiddleware } from "@/lib/auth/middleware";
+
+export const listTodos = createServerFn({ method: "GET" })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    const sql = await getSql();
+    return sql<{ id: number; title: string }>`select id, title from todos where user_id = ${context.userId} order by id desc`;
+  });
+// mutations must scope writes too: `... where id = ${id} and user_id = ${context.userId}`
+```
+
+**Without sign-in (the default), do NOT use `authMiddleware` / `requireUserId`.**
+The dev user they fall back to is a preview-only convenience. A deployed app's
+`VITE_AUTH_ENABLED` is set by the platform, not by this workspace (today the
+deployer always sets it to `"true"`), so deployed, both reject every visitor —
+and an auth-off app ships no sign-in route for them to recover with. A
+database-only app keeps its rows unowned: no `user_id` column, or one literal
+constant. Add the middleware as part of turning sign-in on (the `auth` skill's
+upgrade steps), and re-scope or drop those rows then.
+
+Unowned rows are world-readable and world-writable through your public server
+functions: never persist personal or sensitive data (names, emails, free text
+about a person) in this mode, and leave out destructive bulk mutations
+(delete-all, overwrite-all) — if the app needs them, propose sign-in instead.
+
+## Migrations
+
+`migrations/*.sql` are the single schema source. They apply to **Neon on deploy**
+(`npm run build` runs `db:migrate` against `DATABASE_URL`, so Vercel ships with
+the schema ready) and to the **PGLite** preview **automatically on startup**, so
+dev matches prod.
+
+Neither applier descends into subdirectories, so the Better Auth schema at
+`migrations/auth/0001_auth.sql` is **not** applied unless the app turns sign-in
+on and copies it up (**do not edit** it — see the `auth` skill). Put your app's
+schema in NEW ordered files starting at `0002`:
+
+```sql
+-- migrations/0002_schema.sql — example for a todos app; use YOUR app's tables
+create table if not exists todos (
+  id         serial primary key,
+  user_id    text not null,
+  title      text not null,
+  done       boolean not null default false,
+  created_at timestamptz not null default now()
+);
+create index if not exists todos_user_id_idx on todos (user_id);
+```
+
+Never edit an applied file — it is tracked by name in `_migrations` and will not
+re-run (add a new file instead; new files apply to the running preview on the
+next request). Prefer idempotent statements (`… if not exists`). Tables with
+per-user data should carry a `user_id text not null` column (TEXT, not UUID — the
+preview dev user id is the string `'dev-user'`).
+
+## Preview ↔ production parity
+
+`getSql()` normalizes result types so both backends return identical, JSON-safe
+shapes: `bigint`/`count(*)` → `number`, `date` → `'YYYY-MM-DD'` string,
+`interval` → text, `numeric` → string. Remaining differences to respect:
+
+- **`bigint` past 2^53 loses precision** as a number — cast `::text` if you
+  ever need huge integers (row counts are fine).
+- **Preview DB is in-memory**: wiped on dev-server restart, single-connection
+  (no lock contention or concurrent-write conflicts), and loads **no
+  extensions** — do not `create extension`; stick to core Postgres.
+- **Neon's pooled endpoint keeps no session state** — don't rely on `SET`,
+  `LISTEN/NOTIFY`, or session advisory locks.
+- **Keep `user_id` columns `text`** — preview uses `'dev-user'`, production uses
+  Better Auth's text ids; a `uuid` column breaks preview inserts.
+- Deployed Neon queries traverse the network (and may cold-resume) — avoid
+  N+1 query patterns that feel free against the in-process preview DB.

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

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-neon",
+  "name": "Grok \u00b7 neon",
+  "description": "Neon Postgres (with a local PGLite fallback) for this template",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-neon"
+  },
+  "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-og/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: og
+description: >
+  Share-link previews and app identity for apps on *.grok.me: the injector-owned
+  og:image card, the SVG favicon, and PWA icons for installable apps.
+  Use when scaffolding, renaming, or restyling the app — and for share /
+  unfurl / OG / Twitter card questions. A custom 1200×630 card from the app's
+  own art is the default — games of every kind (DOM board/word games
+  included), whimsical apps, creative tools, and brand-forward pages; only
+  plain utilities keep the placeholder. Always run the brand-asset pass as a
+  `task` subagent and never wait for it.
+  Triggers on "share", "rename", "app name", "OG", "Open Graph",
+  "twitter card", "unfurl", "og:image", "og:type", "x:game:image",
+  "x-banner", "link preview", "social card", "thumbnail", "preview image",
+  "favicon", "app icon", "PWA", "manifest", "installable", "home screen",
+  "SEO", "meta description".
+metadata:
+  short-description: "Brand assets: og.jpg card, X feed banner, SVG favicon, PWA icons — always a non-blocking `task` subagent"
+user-invocable: false
+---
+
+# Share cards, favicon, and app icons
+
+A deployed app (`https://{name}.grok.me`) unfurls with a 1200×630 card; every app (preview included) shows a
+favicon in the tab. **Share-card `<meta>` tags are not authored in `__root.tsx`** — the injector
+(`scripts/grok-pwa-shared.mjs`) overwrites `og:*` and `twitter:card` on every HTML response. Identity data is
+the only thing anyone writes, and the pass writes all of it — dispatching, you seed none of it:
+
+- `src/lib/og/site.json` — not pre-seeded, created only if needed: `{ "title", "type"?: "x:game", "card"?: "custom", "color"?: "RRGGBB" }`; title defaults to the host slug.
+- `public/og.jpg` — custom 1200×630 card (optional; placeholder otherwise)
+- `public/x-banner.jpg` — games only: 50:11 (1200×264) X feed card
+- `public/favicon.svg` — linked from root `head()`; until the pass lands the tab just shows the browser default, which fails nothing
+
+**Extend `__root.tsx`; never replace it wholesale** (auth SSR, redesigns, skill excerpts): dropping the
+favicon link ships a blank tab icon no local check catches.
+
+## Decide: which card this app gets
+
+**Default: a custom card** from the app's own art — games of every kind and rendering tech (Canvas/WebGL *and*
+DOM board, card, word, puzzle, quiz: a tic-tac-toe grid of divs is still a game), whimsical apps, creative
+tools, content- and brand-forward pages. **When in doubt, make the custom card.**
+
+**Plain utility apps only** (converters, CRUD trackers, dashboards, notes/admin — apps whose face is the data)
+keep the default `og.grok.me` placeholder: no `public/og.jpg`. Its URL, the `"color"` knob and the rename
+rule: `references/placeholder-card.md`.
+
+## `og:type` for games
+
+**A game of any kind** carries `"type": "x:game"` in `src/lib/og/site.json` — the pass writes it, owning that
+file. No hostname, never gated on a custom card, never "corrected" to `website`, bare `game`, `twitter:card`
+or an invented `x:type`: X's pipeline keys off that exact value. Non-games omit it. Your check, not your
+edit — missing it, or missing `public/x-banner.jpg` once a custom card exists, is a **BRAND WARNING**.
+
+## Brand-asset pass: always a subagent, never waited for
+
+**Have the `task` tool? Dispatch this pass as a subagent and never generate card art yourself** — inline it
+puts minutes of generation latency in front of the user. As soon as name and palette settle (AGENTS.md §
+"Parallel work"), dispatch this prompt verbatim. It is complete — do not open the references below to
+enrich it; the pass reads them itself:
+
+> You are the brand-asset pass. Follow the `og` skill, which tells you where to start. App `<NAME>`,
+> `og:type` `<TYPE>`, palette `<PALETTE>`. You solely own `public/` brand assets and `src/lib/og/site.json`.
+
+Keep building. Stay sequential only if the user is art-directing or the art to reuse doesn't exist yet.
+
+**Never wait for it.** No `wait_tasks`, and **never `get_task_output` on the brand task**: reading a task's
+output consumes it, and a consumed task sends no completion notification, so the card's result — a failure
+included — would reach nobody. Answer as soon as the app renders; the pass wakes you later, and that turn is
+**one short sentence at most** — one that asks for a republish, since `public/og.jpg` ships in the build
+and a card that lands after a publish never reaches the live app on its own:
+"Added the share card — publish again if you already did." / "The card failed; the default one stands."
+
+While the pass keeps `/workspace/.grok/og-pending` fresh, brand checks say nothing about the card: in flight
+is not a finding. The marker goes stale after 10 minutes, so a very long pass lets the warning through — but
+a brand warning while it runs is never a cue to redo its work.
+
+**No `task` tool? Then you are the pass** — build the assets now; nothing else will. Whoever runs it claims
+that marker, stages files under `/workspace/.grok/` — never inside `public/`, which `vite build` copies
+verbatim into the deployed app — hands it over with `scripts/write-atomic.mjs` so no build reads half a JPEG,
+and self-checks with `node scripts/brand-check.mjs --game`.
+
+## Build the assets — the pass reads these, the parent does not
+
+**Dispatching? Do not open them** — the prompt above is complete. One read carries this procedure in your
+context every later turn while the subagent does the work anyway.
+
+**You are the pass?** Start at `references/brand-pass.md`, then read
+per asset you owe: `references/custom-card.md` for `public/og.jpg`, `references/x-banner.md` for the
+games-only `public/x-banner.jpg`, `references/favicon-and-icons.md` for `public/favicon.svg` plus the PWA
+raster icons — those only when the user asked for installable/PWA, never invent a manifest. **Hand-author
+that SVG, never `imagine_text_to_image`**: it must stay crisp at 16px. Writing `site.json` for a game?
+`references/og-type-contract.md` argues the spellings X rejects.
+
+Regenerate on rename or a material identity change — `APP_NAME`, the `site.json` `title` and the baked-in card
+title move together. Without `imagine_text_to_image` or the xAI Images API, keep the `og.grok.me` card; never
+ship a broken `og:image` URL.
+
+## Not supported
+
+No `/api/og` route, no runtime image renderer, no per-route cards — the card is one static site-wide image
+(`public/og.jpg` or the placeholder service). If you add `robots.txt`, never blanket `Disallow: /`: crawlers
+must fetch `/` to read the tags.

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

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-og",
+  "name": "Grok \u00b7 og",
+  "description": "Brand assets: og.jpg card, X feed banner, SVG favicon, PWA icons \u2014 always a non-blocking `task` subagent",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-og"
+  },
+  "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-og/references/brand-pass.md

@@ -0,0 +1,53 @@
+# Running the brand-asset pass (the pass's own contract)
+
+Read this when you *are* the pass — dispatched as the brand subagent, or
+building the assets inline because no `task` tool exists. The parent keeps
+building and never waits, so everything below is yours to get right unobserved.
+
+## 1. Claim the marker, keep it fresh, always release it
+
+`touch /workspace/.grok/og-pending` before generating and again before each
+`imagine_*` call — while that marker is fresh `brand-check.mjs` suppresses the
+missing-card warnings the parent would otherwise act on, and it goes stale after
+10 minutes so a killed pass cannot silence the check forever.
+`rm -f /workspace/.grok/og-pending` on every exit path, success or not.
+
+## 2. Hand every file over atomically
+
+`public/og.jpg`, `public/x-banner.jpg` and `src/lib/og/site.json` alike. The
+parent may be mid-`npm run build` and would then read a half-written JPEG. Write
+to a staged path under `/workspace/.grok/` — never inside `public/`, which
+`vite build` copies verbatim into the deployed app, and never on another
+filesystem such as `/tmp`, where the hand-over cannot be a rename — then:
+
+```sh
+node scripts/write-atomic.mjs /workspace/.grok/og.jpg.tmp public/og.jpg
+```
+
+`src/lib/og/site.json` is the only file this pass writes under `src/`. Hand it
+over **once**, with the finished card — never a field at a time: its
+`"card": "custom"` flag has to land *with* the card and not before, because the
+bake trusts the flag on its own and would emit an `og:image` URL for a file that
+does not exist.
+
+## 3. Verify your own work, because nobody waits for it
+
+Run the card checks in `custom-card.md`, then `node scripts/brand-check.mjs --game`
+(drop `--game` for non-games), which prints a JSON verdict and exits non-zero
+on any `BRAND WARNING`. That run judges the files on disk and reports
+`"pending": true` — the marker only demotes the parent's gates — and it treats a
+missing `public/og.jpg` as a failure whatever kind of app this is, because
+producing one is what this pass is normally for.
+
+**The one exception**: a pass launched for a plain utility that keeps the
+`og.grok.me` card (favicon, PWA icons, and title only — SKILL.md § "Decide:
+which card this app gets") is not there to produce a card, so it adds
+`--placeholder-ok` and the missing card is then the expected verdict rather than
+a failure:
+
+```sh
+node scripts/brand-check.mjs --placeholder-ok
+```
+
+Use it only for that launch — passing it on a custom-card app hides the one
+thing that pass owes. Report pass or fail in your answer text.