@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/registry/cms-rust-machine-20260928/migration.sql

@@ -0,0 +1,237 @@
+-- AgentSam CMS / Rust / machine product registry graduation.
+-- Idempotent: stable product slugs + unique relationship edges.
+-- Database: inneranimalmedia-business
+
+INSERT INTO agentsam_products (
+  slug, name, kind, status, description,
+  repository_id, canonical_path, package_name, version, tags, metadata, updated_at
+) VALUES (
+  'cms',
+  'InnerAnimalMedia CMS',
+  'product',
+  'wired',
+  'Independent CMS product identity; portable editor/runtime surfaces inherit AgentSam capabilities.',
+  'github:samprimeaux/inneranimalmedia',
+  'src/core/agentsam/cms',
+  NULL,
+  NULL,
+  '["cms","product","installable"]',
+  '{"origin":"registry.cms-rust-machine-20260928","installable":true,"app_id":"client-cms-editor","install":{"command":"agentsam app scaffold client-cms-editor","paths":["/install/cms"]},"run_targets":["local","cloudflare","tauri"],"persistence":["sqlite","d1","localStorage_cache"],"cli_commands":[],"capabilities":["cms.editor","cms.pages","cms.sections","cms.components","cms.media"]}',
+  unixepoch()
+)
+ON CONFLICT(slug) DO UPDATE SET
+  name=excluded.name,
+  kind=excluded.kind,
+  status=excluded.status,
+  description=excluded.description,
+  repository_id=COALESCE(excluded.repository_id,agentsam_products.repository_id),
+  canonical_path=excluded.canonical_path,
+  package_name=excluded.package_name,
+  version=excluded.version,
+  tags=excluded.tags,
+  metadata=excluded.metadata,
+  updated_at=excluded.updated_at;
+
+INSERT INTO agentsam_products (
+  slug, name, kind, status, description,
+  repository_id, canonical_path, package_name, version, tags, metadata, updated_at
+) VALUES (
+  'client-cms-editor',
+  'AgentSam CMS Editor',
+  'app',
+  'scaffolded',
+  'Canonical reusable CMS editor app; donor-quality remaster is in progress behind adapter boundaries.',
+  'github:samprimeaux/agentsam-sdk',
+  'apps/client-cms-editor',
+  '@inneranimalmedia/client-cms-editor',
+  '0.1.0',
+  '["cms","app","editor","installable"]',
+  '{"origin":"registry.cms-rust-machine-20260928","installable":true,"app_id":"client-cms-editor","product_id":"cms","legacy_slug":"iam-client-cms-editor","install":{"command":"agentsam app scaffold client-cms-editor","paths":["/install/cms","/install/client-cms-editor"]},"run_targets":["local","cloudflare","tauri"],"persistence":["sqlite","d1","localStorage_cache"],"cli_commands":[],"capabilities":["cms.editor","cms.pages","cms.sections","cms.components","cms.media"]}',
+  unixepoch()
+)
+ON CONFLICT(slug) DO UPDATE SET
+  name=excluded.name,
+  kind=excluded.kind,
+  status=excluded.status,
+  description=excluded.description,
+  repository_id=COALESCE(excluded.repository_id,agentsam_products.repository_id),
+  canonical_path=excluded.canonical_path,
+  package_name=excluded.package_name,
+  version=excluded.version,
+  tags=excluded.tags,
+  metadata=excluded.metadata,
+  updated_at=excluded.updated_at;
+
+INSERT INTO agentsam_products (
+  slug, name, kind, status, description,
+  repository_id, canonical_path, package_name, version, tags, metadata, updated_at
+) VALUES (
+  'theme-inneranimals-site',
+  'Inner Animals Site Theme',
+  'theme',
+  'prototype',
+  'Harvested Inner Animals storefront/theme candidate awaiting canonical reusable theme graduation.',
+  NULL,
+  NULL,
+  NULL,
+  NULL,
+  '["cms","theme","harvest","candidate"]',
+  '{"origin":"registry.cms-rust-machine-20260928","installable":false,"candidate":true,"source":"harvest","capabilities":["cms.theme"]}',
+  unixepoch()
+)
+ON CONFLICT(slug) DO UPDATE SET
+  name=excluded.name,
+  kind=excluded.kind,
+  status=excluded.status,
+  description=excluded.description,
+  repository_id=COALESCE(excluded.repository_id,agentsam_products.repository_id),
+  canonical_path=excluded.canonical_path,
+  package_name=excluded.package_name,
+  version=excluded.version,
+  tags=excluded.tags,
+  metadata=excluded.metadata,
+  updated_at=excluded.updated_at;
+
+INSERT INTO agentsam_products (
+  slug, name, kind, status, description,
+  repository_id, canonical_path, package_name, version, tags, metadata, updated_at
+) VALUES (
+  'asrust',
+  'AgentSam Rust/Wasm Edge Lab',
+  'service',
+  'wired',
+  'Live Rust/Wasm Worker capability lab at asrust.inneranimalmedia.com.',
+  NULL,
+  NULL,
+  NULL,
+  NULL,
+  '["rust","wasm","cloudflare","service"]',
+  '{"origin":"registry.cms-rust-machine-20260928","runtime":"rust-wasm","deployment":{"provider":"cloudflare","url":"https://asrust.inneranimalmedia.com","state":"live"},"run_targets":["cloudflare"],"cli_commands":[],"capabilities":["rust.wasm.worker"]}',
+  unixepoch()
+)
+ON CONFLICT(slug) DO UPDATE SET
+  name=excluded.name,
+  kind=excluded.kind,
+  status=excluded.status,
+  description=excluded.description,
+  repository_id=COALESCE(excluded.repository_id,agentsam_products.repository_id),
+  canonical_path=excluded.canonical_path,
+  package_name=excluded.package_name,
+  version=excluded.version,
+  tags=excluded.tags,
+  metadata=excluded.metadata,
+  updated_at=excluded.updated_at;
+
+INSERT INTO agentsam_products (
+  slug, name, kind, status, description,
+  repository_id, canonical_path, package_name, version, tags, metadata, updated_at
+) VALUES (
+  'agentsam-machine',
+  'AgentSam Machine',
+  'service',
+  'prototype',
+  'Deterministic native inspect/catalog engine; native core is present while top-level agentsam machine dispatch remains pending.',
+  'github:samprimeaux/agentsam-sdk',
+  'native/agentsam-machine',
+  NULL,
+  '0.1.0',
+  '["rust","native","machine","inspect"]',
+  '{"origin":"registry.cms-rust-machine-20260928","installable":false,"runtime":"native-rust","run_targets":["local","tauri"],"cli_commands":[],"capabilities":["machine.inspect"],"dispatch":"pending"}',
+  unixepoch()
+)
+ON CONFLICT(slug) DO UPDATE SET
+  name=excluded.name,
+  kind=excluded.kind,
+  status=excluded.status,
+  description=excluded.description,
+  repository_id=COALESCE(excluded.repository_id,agentsam_products.repository_id),
+  canonical_path=excluded.canonical_path,
+  package_name=excluded.package_name,
+  version=excluded.version,
+  tags=excluded.tags,
+  metadata=excluded.metadata,
+  updated_at=excluded.updated_at;
+
+INSERT INTO agentsam_products (
+  slug, name, kind, status, description,
+  repository_id, canonical_path, package_name, version, tags, metadata, updated_at
+) VALUES (
+  'agentsam-rapid-rust',
+  'AgentSam Rapid Rust',
+  'sdk-package',
+  'prototype',
+  'Rust/Wasm Worker scaffolding and local proof tooling shipped inside the AgentSam SDK.',
+  'github:samprimeaux/agentsam-sdk',
+  'packages/agentsam-rapid-rust',
+  '@inneranimalmedia/agentsam-sdk',
+  '0.1.0',
+  '["rust","wasm","sdk","cli","installable"]',
+  '{"origin":"registry.cms-rust-machine-20260928","installable":true,"bundled_in":"@inneranimalmedia/agentsam-sdk","run_targets":["local","cloudflare"],"persistence":[],"cli_commands":["agentsam rust","agentsam wasm"],"capabilities":["rust.scaffold","rust.check","rust.build","rust.dev","rust.deploy"]}',
+  unixepoch()
+)
+ON CONFLICT(slug) DO UPDATE SET
+  name=excluded.name,
+  kind=excluded.kind,
+  status=excluded.status,
+  description=excluded.description,
+  repository_id=COALESCE(excluded.repository_id,agentsam_products.repository_id),
+  canonical_path=excluded.canonical_path,
+  package_name=excluded.package_name,
+  version=excluded.version,
+  tags=excluded.tags,
+  metadata=excluded.metadata,
+  updated_at=excluded.updated_at;
+
+-- CMS product is packaged as the canonical editor app.
+INSERT INTO asset_relationships (
+  source_type, source_id, target_type, target_id, relationship_type, metadata
+)
+SELECT 'agentsam_product', cms.id, 'agentsam_product', editor.id, 'packaged_as',
+       '{"origin":"registry.cms-rust-machine-20260928","role":"editor_app"}'
+FROM agentsam_products cms, agentsam_products editor
+WHERE cms.slug='cms' AND editor.slug='client-cms-editor'
+ON CONFLICT(source_type,source_id,target_type,target_id,relationship_type)
+DO UPDATE SET metadata=excluded.metadata;
+
+-- Preserve the existing legacy product identity as an alias, not a second canonical editor.
+INSERT INTO asset_relationships (
+  source_type, source_id, target_type, target_id, relationship_type, metadata
+)
+SELECT 'agentsam_product', legacy.id, 'agentsam_product', editor.id, 'aliased_as',
+       '{"origin":"registry.cms-rust-machine-20260928","legacy_slug":"iam-client-cms-editor"}'
+FROM agentsam_products legacy, agentsam_products editor
+WHERE legacy.slug='iam-client-cms-editor' AND editor.slug='client-cms-editor'
+ON CONFLICT(source_type,source_id,target_type,target_id,relationship_type)
+DO UPDATE SET metadata=excluded.metadata;
+
+-- Harvested theme candidate belongs to the CMS product family.
+INSERT INTO asset_relationships (
+  source_type, source_id, target_type, target_id, relationship_type, metadata
+)
+SELECT 'agentsam_product', theme.id, 'agentsam_product', cms.id, 'depends_on',
+       '{"origin":"registry.cms-rust-machine-20260928","role":"cms_theme"}'
+FROM agentsam_products theme, agentsam_products cms
+WHERE theme.slug='theme-inneranimals-site' AND cms.slug='cms'
+ON CONFLICT(source_type,source_id,target_type,target_id,relationship_type)
+DO UPDATE SET metadata=excluded.metadata;
+
+-- Rapid Rust exposes the commands that are already mainline and tested.
+INSERT INTO asset_relationships (
+  source_type, source_id, target_type, target_id, relationship_type, metadata
+)
+SELECT 'agentsam_product', p.id, 'cli_command', 'agentsam:rust', 'exposes_command',
+       '{"origin":"registry.cms-rust-machine-20260928","command":"agentsam rust"}'
+FROM agentsam_products p
+WHERE p.slug='agentsam-rapid-rust'
+ON CONFLICT(source_type,source_id,target_type,target_id,relationship_type)
+DO UPDATE SET metadata=excluded.metadata;
+
+INSERT INTO asset_relationships (
+  source_type, source_id, target_type, target_id, relationship_type, metadata
+)
+SELECT 'agentsam_product', p.id, 'cli_command', 'agentsam:wasm', 'exposes_command',
+       '{"origin":"registry.cms-rust-machine-20260928","command":"agentsam wasm"}'
+FROM agentsam_products p
+WHERE p.slug='agentsam-rapid-rust'
+ON CONFLICT(source_type,source_id,target_type,target_id,relationship_type)
+DO UPDATE SET metadata=excluded.metadata;

package/registry/cms-rust-machine-20260928/receipt.json

@@ -0,0 +1,21 @@
+{
+  "schema": "agentsam.registry.receipt.v1",
+  "database": "inneranimalmedia-business",
+  "applied_at": "2026-09-28",
+  "validated": true,
+  "products": {
+    "cms": "wired",
+    "client-cms-editor": "scaffolded",
+    "theme-inneranimals-site": "prototype",
+    "asrust": "wired",
+    "agentsam-machine": "prototype",
+    "agentsam-rapid-rust": "prototype"
+  },
+  "relationships": [
+    ["cms", "packaged_as", "client-cms-editor"],
+    ["iam-client-cms-editor", "aliased_as", "client-cms-editor"],
+    ["theme-inneranimals-site", "depends_on", "cms"],
+    ["agentsam-rapid-rust", "exposes_command", "agentsam:rust"],
+    ["agentsam-rapid-rust", "exposes_command", "agentsam:wasm"]
+  ]
+}

package/registry/cms-rust-machine-20260928/receipt.sql

@@ -0,0 +1,27 @@
+SELECT slug,kind,status,canonical_path,package_name,
+       json_extract(metadata,'$.app_id') AS app_id,
+       json_extract(metadata,'$.legacy_slug') AS legacy_slug,
+       json_extract(metadata,'$.dispatch') AS dispatch
+FROM agentsam_products
+WHERE slug IN (
+  'cms',
+  'client-cms-editor',
+  'theme-inneranimals-site',
+  'asrust',
+  'agentsam-machine',
+  'agentsam-rapid-rust'
+)
+ORDER BY slug;
+
+SELECT p.slug AS source_slug,
+       ar.relationship_type,
+       CASE WHEN ar.target_type='agentsam_product' THEN tp.slug ELSE ar.target_id END AS target,
+       ar.target_type
+FROM asset_relationships ar
+JOIN agentsam_products p
+  ON ar.source_type='agentsam_product' AND ar.source_id=p.id
+LEFT JOIN agentsam_products tp
+  ON ar.target_type='agentsam_product' AND ar.target_id=tp.id
+WHERE p.slug IN ('cms','iam-client-cms-editor','theme-inneranimals-site','agentsam-rapid-rust')
+  AND ar.relationship_type IN ('packaged_as','aliased_as','depends_on','exposes_command')
+ORDER BY source_slug, ar.relationship_type, target;

package/scripts/build_rapid_rust_cli.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Build/install/smoke-test AgentSam Rapid Rust native CLI.
+
+Nothing here deploys a Worker. --bootstrap only installs local Rust/Wasm build
+prerequisites. --smoke scaffolds disposable projects and cargo-checks them.
+"""
+from __future__ import annotations
+import argparse, json, os, shutil, subprocess, sys, tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+MANIFEST = ROOT / "packages" / "agentsam-rapid-rust" / "Cargo.toml"
+BINARY = ROOT / "packages" / "agentsam-rapid-rust" / "target" / "release" / "agentsam-rapid-rust"
+WORKER_BUILD_VERSION = "0.8.7"
+TEMPLATES = ("api", "shared-core", "crypto-auth", "data-processor")
+
+def run(cmd, *, cwd=ROOT, check=True):
+    print("→", " ".join(map(str, cmd)))
+    return subprocess.run(list(map(str, cmd)), cwd=cwd, check=check)
+
+def have(cmd):
+    return shutil.which(cmd) is not None
+
+def bootstrap():
+    if not have("rustup") or not have("cargo"):
+        raise RuntimeError("Rust/rustup/cargo are required")
+    installed = subprocess.check_output(["rustup", "target", "list", "--installed"], text=True)
+    if "wasm32-unknown-unknown" not in installed.splitlines():
+        run(["rustup", "target", "add", "wasm32-unknown-unknown"])
+    if not have("worker-build"):
+        run(["cargo", "install", "worker-build", "--version", WORKER_BUILD_VERSION, "--locked"])
+
+def build():
+    run(["cargo", "fmt", "--manifest-path", MANIFEST, "--", "--check"])
+    run(["cargo", "test", "--manifest-path", MANIFEST])
+    run(["cargo", "build", "--release", "--manifest-path", MANIFEST])
+
+def install(dest: Path):
+    if not BINARY.exists():
+        build()
+    dest.mkdir(parents=True, exist_ok=True)
+    target = dest / "agentsam-rapid-rust-native"
+    tmp = dest / ".agentsam-rapid-rust-native.tmp"
+    shutil.copy2(BINARY, tmp)
+    tmp.chmod(0o755)
+    os.replace(tmp, target)
+    print("installed:", target)
+    return target
+
+def smoke(binary: Path):
+    bootstrap()
+    with tempfile.TemporaryDirectory(prefix="agentsam-rapid-rust-") as td:
+        root = Path(td)
+        for template in TEMPLATES:
+            name = "fixture-" + template
+            run([binary, "new", name, "--template", template, "--out", root])
+            project = root / name
+            run([binary, "check", "--cwd", project])
+
+def main():
+    ap=argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--bootstrap", action="store_true")
+    ap.add_argument("--build", action="store_true")
+    ap.add_argument("--install", action="store_true")
+    ap.add_argument("--install-dir", type=Path, default=Path.home()/".agentsam"/"bin")
+    ap.add_argument("--smoke", action="store_true")
+    ap.add_argument("--json", action="store_true")
+    args=ap.parse_args()
+    if not any((args.bootstrap,args.build,args.install,args.smoke)):
+        args.build=True
+    if args.bootstrap: bootstrap()
+    if args.build or args.install or args.smoke: build()
+    installed=None
+    if args.install: installed=install(args.install_dir.expanduser())
+    if args.smoke: smoke(installed or BINARY)
+    result={"ok":True,"binary":str(BINARY),"installed":str(installed) if installed else None,"smoke":args.smoke}
+    if args.json: print(json.dumps(result,indent=2))
+    return 0
+
+if __name__ == '__main__':
+    try: raise SystemExit(main())
+    except (RuntimeError, subprocess.CalledProcessError) as exc:
+        print("ERROR:", exc, file=sys.stderr); raise SystemExit(2)

package/skills/grok-auth/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: auth
+description: >
+  Add user accounts and sign-in to this TanStack Start app. Use when the app
+  needs authentication, sign-in, user accounts, protected routes, or per-user
+  data. Triggers on "auth", "login", "log in", "sign in", "sign up", "account",
+  "users", "authentication", "protected", "who is logged in", "current user",
+  "per-user".
+metadata:
+  short-description: "Auth via the Grok broker (Google, X) or local email/password — no other methods supported"
+user-invocable: false
+---
+
+# Auth
+
+This app runs its **own** [Better Auth](https://better-auth.com) at
+`/api/auth/*`, federating to the shared **Grok auth broker** (`auth.grok.me`)
+via the `genericOAuth` plugin. This template wires **Google** and **X**.
+
+**Supported sign-in methods — use ONLY these three; nothing else is supported:
+Google, X, and email/password.** No other social/OAuth provider (GitHub, Apple,
+Discord, …), no magic links, passkeys, OTP, phone/SMS, or anonymous sign-in. Do
+not add entries to `GROK_PROVIDERS`. Method detail and the email/password switch
+(edit **only** `src/lib/auth/email-password.ts`): `references/sign-in-methods.md`.
+**Exception — gate viewers are signed in already; NEVER render login/re-auth
+buttons for them. Connector / app-data apps: ONLY gate "Continue with Grok",
+no Google/X buttons**: `references/grok-identity.md`.
+
+**Sign-in is OFF by default** — the template ships `.grok/app-env.json` with
+`{"VITE_AUTH_ENABLED": "false"}`, so only add accounts when the ask calls for
+them (AGENTS.md §0.5). Switching it on is "Turning sign-in on" below.
+
+**Once on, sign-in is REAL — including in the sandbox live preview.** Do **NOT**
+scaffold demo/mock/hardcoded users. Preview: popup + baked preview client;
+deployed: per-app client + `DATABASE_URL` + zero-click gate sign-in
+(`references/prewired-and-env.md`).
+
+**While OFF** (`VITE_AUTH_ENABLED=false`) a **dev user** is returned so a
+non-auth app renders without a signed-in visitor — dev and preview only.
+Deployed, the flag is the platform's (always `"true"`), so `requireUserId`
+rejects every visitor — auth-off apps use neither it nor `authMiddleware`.
+
+Everything is **preinstalled and pre-wired in `src/lib/auth/`** — do not
+`npm install` anything; `better-auth` is the only auth package (never
+`@neondatabase/*`, `@stackframe/*`, or `@clerk/*`). **Do not edit or rewrite any
+file under `src/lib/auth/`** — `server.ts` least of all — except
+`email-password.ts` for its one flag. Per-file map:
+`references/prewired-and-env.md`.
+
+**`/auth/popup` is already handled by the template Vite plugin**
+(`vite.config.ts` → `popup.server.ts`): it never paints the React app. **Do NOT
+create `src/routes/auth/popup.tsx`** (or any React page / client OAuth at that
+path) — that shows the full app inside the popup, the common failure mode.
+
+**Never write a `.env` / `.env.local` / `.env.example`** in this sandbox: live
+preview needs **zero** env configuration and a deployed app gets its vars
+injected by the platform. The knobs that exist are in
+`references/prewired-and-env.md` — never expose a non-`VITE_` var to the client.
+
+`migrations/auth/0001_auth.sql` is the Better Auth schema — **do not edit**. It
+sits outside the globbed `migrations/` directory (neither applier descends), so
+it is not applied to apps without sign-in; "Turning sign-in on" copies it up.
+
+## Turning sign-in on
+
+Do all of this — the routes alone render the disabled branch:
+
+1. **Flag:** delete the `VITE_AUTH_ENABLED` key from `.grok/app-env.json` and
+   **restart the dev server**. Vite reads env at startup, so HMR will not pick
+   it up. `npm run dev`, `npm run build` and `npm run preview` all read that
+   file through `scripts/with-app-env.mjs`, so preview and the built output flip
+   together — never start Vite directly.
+2. **Schema:** `cp migrations/auth/0001_auth.sql migrations/0001_auth.sql`, then
+   restart so it applies. It is tracked by basename in `_migrations`, so a
+   database that already has it will not re-run it.
+3. **Routes:** add `src/routes/api/auth/$.ts` + `src/routes/login.tsx` — copy
+   both from `references/wiring.md` (the catch-all API route is what makes
+   `/api/auth/*` and the broker callback work).
+4. **Sign out:** a login with no way out is not done — render `<UserButton />`
+   from `@/lib/auth/gates` (wires `signOut()`; hides sign-out for gate sessions).
+5. **Existing data:** wrap the app's server functions in `authMiddleware` (an
+   auth-off app must not have been using it — see the `neon` skill). Rows from
+   before sign-in existed are **development data**: drop and recreate them
+   unless the user says otherwise — don't hand them to whoever signs in first.
+
+## Building on it once it's on
+
+- **Sign in / out:** `signIn(providerId)` and `signOut()` from
+  `@/lib/auth/client`; `GROK_PROVIDERS` renders the buttons. The popup,
+  bearer-token hand-off, and request attachment are internal — leave them alone.
+  Prefer `<UserButton />` (it handles the pending and failure states); `signOut()`
+  rejects when deployed if the server never confirms — catch it. Never
+  `authClient.signOut()`: it leaves the preview bearer token attached to every
+  later request, so the visitor stays signed in.
+- **Reading the user:** `useCurrentUser()` is display-only (`null` means
+  *loading OR signed out*, so never redirect on it alone); guard on
+  `useCurrentUserState()`'s `isPending` instead. Gates (`SignedIn`, `SignedOut`,
+  `SignInGate`, `RedirectToSignIn`, `UserButton`) live in `@/lib/auth/gates`.
+  CTA hard rules, skeleton, and cookie-SSR zero-flash: `references/session-ui.md`.
+- **Per-user data (mandatory):** every server function that touches per-user data
+  must use the prewired `authMiddleware` and scope every read **and** write to
+  `context.userId` — a Postgres driver has full DB access, so nothing else limits
+  the query. Keep `user_id` columns `TEXT`; never trust a client-supplied user id;
+  signed out, the middleware throws `UnauthorizedError` (401). Code and
+  disabled-mode semantics: `references/per-user-data.md`.
+- **Security model:** headless broker, `__Host-` cookies + `trustedOrigins`, and
+  Fetch-Metadata sibling isolation are already wired — never weaken them to make
+  an error go away (`references/sign-in-methods.md` covers the model and the
+  "Invalid origin" fix).
+

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

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-auth",
+  "name": "Grok \u00b7 auth",
+  "description": "Auth via the Grok broker (Google, X) or local email/password \u2014 no other methods supported",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-auth"
+  },
+  "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-auth/references/grok-identity.md

@@ -0,0 +1,64 @@
+# Sign in with Grok (deployed apps — zero clicks)
+
+Behind the edge gate, every proxied request from a signed-in Grok viewer
+carries an unforgeable `x-grok-identity` JWT (EdDSA, minted per request; the
+gate strips any client-supplied copy). The pre-wired `gateIdentitySessions`
+plugin (`src/lib/auth/gate-session.server.ts`) verifies it against the gate's
+JWKS (`/__gate/identity-key`, via `src/lib/auth/gate-identity.server.ts`) and,
+when the app has no session yet, materializes the Better Auth session for that
+viewer automatically — no sign-in button, no redirect, no broker round-trip.
+`useSession` / `useCurrentUser` simply return the Grok user.
+
+The broker OAuth flow is the **fallback** for anonymous/public viewers and for
+contexts without the gate. The live preview gets the same zero-click identity
+from the in-VM preview proxy at `http://127.0.0.1:6014` (preview tokens carry
+audience `preview`); the popup mechanism remains the fallback there.
+
+## Never render sign-in or re-auth UI to a gate viewer
+
+A gate-authenticated viewer is **already signed in**, and the gate refreshes
+connector tokens on every proxied request — **the platform has no re-auth
+concept**. Never render "Re-auth with Grok", "Sign in again", "Refresh
+session", or a standing "Continue with Grok" button: sign-in UI may appear
+only in the `app-data` skill's `login` error state, after a connector call
+actually returned `loginRequired: true`.
+
+The live preview gets the same zero-click session, so a sign-in button visible
+to the owner in the preview indicates a bug (a CTA rendered while the session
+check was still pending, or rendered in reaction to a data error) — fix it,
+don't restyle it. For any fallback sign-in surface use `<SignInGate>` from
+`@/lib/auth/gates`: it renders sign-in UI only after the session check resolved
+to no user, never during loading and never from a data error.
+
+Sign-out is also a no-op for a gate session — the next request re-materializes
+it from `x-grok-identity`, an instant sign-back-in loop. `<UserButton />`
+already hides its sign-out control for gate sessions; never build a custom
+sign-out (or any sign-out route/handler) for gate viewers.
+
+## Files (pre-wired — do not edit)
+
+| File | Role |
+|---|---|
+| `gate-identity.server.ts` | Verifies the gate's `x-grok-identity` viewer JWT (EdDSA vs the gate JWKS; fail-closed). Server-only. |
+| `gate-session.server.ts` | Better Auth plugin that turns a verified gate identity into the app session with zero clicks. Already registered in `server.ts`. |
+
+## Env (deployer-injected)
+
+| Var | Scope | Meaning |
+|---|---|---|
+| `GROK_PROJECT_ID` | server | deployed apps: enables "Sign in with Grok" (`x-grok-identity` audience check `app:<project_id>`) |
+| `GROK_GATE_ORIGIN` | server | gate public origin override (JWKS + issuer pin); unset → preview mode (no `GROK_PROJECT_ID`) defaults to the in-VM proxy `http://127.0.0.1:6014` (audience `preview`), deployed mode derives it from the inbound host |
+
+Deployed behavior: gate-authenticated viewers are signed in automatically from
+`x-grok-identity`; the deployer also injects a per-app broker client +
+`DATABASE_URL`, so the fallback sign-in persists identities in Postgres.
+
+## Connector / app-data apps: gate sign-in only
+
+When the `app-data` skill applies, the login page offers ONLY "Continue with
+Grok" via the gate sign-in — the zero-click `x-grok-identity` session above, or
+the gate-built `loginUrl` returned by a connector call. Do not wire Google/X
+buttons for these apps: a broker login can mint an identity that is not the
+gate viewer the connector data belongs to. The three-method rule applies to
+apps without connector data. Still no new `GROK_PROVIDERS` entries, still never
+edit `src/lib/auth/`.

package/skills/grok-auth/references/per-user-data.md

@@ -0,0 +1,49 @@
+# Per-user data (server-side — mandatory)
+
+Pair auth with the DB (see the `neon` skill). A regular Postgres driver has full
+DB access, so **every** server function that touches per-user data must verify
+the caller and scope rows to them. Use the prewired **`authMiddleware`**: it
+resolves the same-origin session to a verified `context.userId` (and rejects
+scripted cross-site/sibling requests) — no token threading:
+
+```ts
+import { createServerFn } from "@tanstack/react-start";
+import { getSql } from "@/lib/db";
+import { authMiddleware } from "@/lib/auth/middleware";
+
+export const listTodos = createServerFn({ method: "GET" })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    const sql = await getSql();
+    // Type the row shape — a server fn's return must be provably serializable.
+    return sql<{ id: number; title: string; done: boolean }>`select id, title, done from todos where user_id = ${context.userId} order by id desc`;
+  });
+
+// Inputs go through `.validator()` (the current API); the client passes `{ data }`:
+export const addTodo = createServerFn({ method: "POST" })
+  .validator((title: string) => title.trim())
+  .middleware([authMiddleware])
+  .handler(async ({ context, data: title }) => {
+    if (!title) return;
+    const sql = await getSql();
+    await sql`insert into todos (user_id, title) values (${context.userId}, ${title})`;
+  });
+// mutations must scope writes too: `... where id = ${id} and user_id = ${context.userId}`
+```
+
+Call these from **client code** (effects, event handlers, React Query) — that's
+where `Sec-Fetch-Site: same-origin` holds:
+
+```ts
+useEffect(() => { listTodos().then(setTodos).catch(() => setTodos([])); }, []);
+```
+
+Semantics: signed out → the middleware throws `UnauthorizedError` (message
+`"Unauthorized"`, `status` 401 — match it to send the visitor to sign-in), in the
+live preview too (real auth). With auth disabled (`VITE_AUTH_ENABLED=false`) it
+resolves the dev user (`"dev-user"`) in dev and preview only — the deployed flag
+comes from the deployer (today always `"true"`), so deployed it rejects every
+visitor — which is why an app without sign-in must not use the middleware at all
+(see the `neon` skill). Keep `user_id` columns
+`TEXT` (Better Auth uses text ids; the disabled dev user is `'dev-user'`). Never
+trust a client-supplied user id — only the middleware / `requireUserId()` result.