@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.7

package/packages/theme-shinshu-site/test/theme.test.mjs

@@ -2,10 +2,12 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import { createTheme, createProductRow } from '../src/index.js';
 
-test('shinshu-site theme package exports installable contract', () => {
+test('shinshu-site theme package exports harvested (not installable) contract', () => {
   const theme = createTheme();
   assert.equal(theme.slug, "shinshu-site");
-  assert.equal(theme.installable, true);
+  assert.equal(theme.installable, false);
+  assert.equal(theme.lineage, "shin");
+  assert.equal(theme.family, "consulting-portfolio");
   assert.equal(theme.package, "@inneranimalmedia/theme-shinshu-site");
   assert.ok(Array.isArray(theme.pages));
 });

package/packages/work-graph/package.json

@@ -1,7 +1,6 @@
 {
-  "name": "@inneranimalmedia/work-graph",
-  "version": "0.1.0",
-  "private": true,
+  "name": "@inneranimalmedia/agentsam-work-graph",
+  "version": "2.6.7",
   "description": "Core AgentSam work-graph primitive: one graph model (WorkItem, Dependency, TimelineEvent, Artifact, Evidence, Actor) powering an engineering adapter (git/MCP/tests/deploys) and a business adapter (projects/clients/approvals/milestones), with Gantt/timeline rendering as a pure projection over the graph rather than its own source of truth.",
   "type": "module",
   "main": "./src/index.js",
@@ -15,5 +14,16 @@
   },
   "scripts": {
     "test": "node --test test/*.test.mjs"
-  }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/work-graph"
+  },
+  "files": [
+    "src"
+  ]
 }

package/protocol/FILEMETA_V1.md

@@ -36,7 +36,7 @@ Semantic entries correspond one-for-one with non-directory content entries and r
   "size": 213,
   "mode": 420,
   "hash": "sha256:...",
-  "package": "@inneranimalmedia/agentsam-sdk-identity",
+  "package": "@inneranimalmedia/agentsam-identity",
   "package_root": "packages/identity",
   "package_kind": "library",
   "system": "identity",
@@ -70,7 +70,7 @@ A package may declare stable package-level semantics without tagging every file:
 
 ```json
 {
-  "name": "@inneranimalmedia/agentsam-sdk-identity",
+  "name": "@inneranimalmedia/agentsam-identity",
   "agentsam": {
     "system": "identity",
     "kind": "library",

package/protocol/capabilities/manifest.json

@@ -481,7 +481,7 @@
       "version": 1,
       "domain": "theme",
       "runtime": "node",
-      "package": "@inneranimalmedia/heuristic-theme",
+      "package": "@inneranimalmedia/theme-heuristic",
       "export": "createStorefrontShellTheme",
       "description": "Resolve the stock AgentSam CMS storefront shell theme contract.",
       "deterministic": true,

package/protocol/database/agentsam.schema-pack.v1.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.dev/protocol/database/agentsam.schema-pack.v1.schema.json",
+  "title": "AgentSam schema pack family manifest",
+  "description": "Generic reusable contract for product schema packs (Identity, CMS, CAD, …). Packs own their manifests; this schema is protocol authority.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema", "id", "version", "components"],
+  "properties": {
+    "schema": { "const": "agentsam.schema-pack.v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "version": { "type": "string", "minLength": 1 },
+    "pack_family": { "type": "string", "minLength": 1 },
+    "components": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "component_dependencies": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string" }
+      }
+    },
+    "adapters": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "sql": {
+      "type": "object",
+      "properties": {
+        "portable_dir": { "type": "string" },
+        "files": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "apply_order_fresh": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "apply_order_upgrade_v1_to_v2": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "optional_after_core": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "tables": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string" }
+      }
+    },
+    "table_patterns": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "seed_policy": { "type": "string" },
+    "compatibility": { "type": "object" },
+    "recovery": { "type": "object" },
+    "owner": { "type": "string" },
+    "notes": { "type": "string" }
+  }
+}

package/protocol/presets/catalog.json

@@ -54,7 +54,7 @@
         "composer": "agentsam.mini-composer"
       },
       "packages": {
-        "theme": "@inneranimalmedia/heuristic-theme",
+        "theme": "@inneranimalmedia/theme-heuristic",
         "composer": "@inneranimalmedia/agentsam-workbench",
         "analytics": "@inneranimalmedia/commerce-analytics"
       },
@@ -128,7 +128,7 @@
       "capabilities": [
         "theme.storefront.shell"
       ],
-      "description": "Stock storefront theme selection — default package @inneranimalmedia/heuristic-theme (theme.storefront.shell). Theme is a projection of Brand, not brand authority."
+      "description": "Stock storefront theme selection — default package @inneranimalmedia/theme-heuristic (theme.storefront.shell). Theme is a projection of Brand, not brand authority."
     },
     "brand": {
       "id": "brand",

package/protocol/theme-refinery/lineage-registry.json

@@ -0,0 +1,105 @@
+{
+  "schema": "agentsam.theme-refinery.lineage.v1",
+  "note": "Donor evidence stays private. Package identity uses lineage codes until remaster gates pass. installable=false until PACKAGE-READY.",
+  "lineages": {
+    "fnf": {
+      "display": "FNF",
+      "family": "editorial-commerce",
+      "donor": "fuelnfreetime",
+      "donor_display": "Fuel & Free Time",
+      "package_current": "@inneranimalmedia/theme-fuelnfree-site",
+      "package_target": "@inneranimalmedia/theme-ember",
+      "gallery_slug": "fuelnfree-site",
+      "status": "needs_normalization",
+      "installable": false,
+      "canonical_id": "ember"
+    },
+    "afm": {
+      "display": "AFM",
+      "family": "service-gallery",
+      "donor": "anything-floors",
+      "donor_display": "Anything Floors & More",
+      "package_current": "@inneranimalmedia/theme-floors-site",
+      "package_target": "@inneranimalmedia/theme-grove",
+      "gallery_slug": "floors-site",
+      "status": "needs_normalization",
+      "installable": false,
+      "canonical_id": "grove"
+    },
+    "phs": {
+      "display": "PHS",
+      "family": "trade-services",
+      "donor": "primeaux-handyman",
+      "donor_display": "Primeaux Handyman Services",
+      "package_current": "@inneranimalmedia/theme-handyman-site",
+      "package_target": "@inneranimalmedia/theme-forge",
+      "gallery_slug": "handyman-site",
+      "status": "needs_normalization",
+      "installable": false,
+      "canonical_id": "forge"
+    },
+    "nic": {
+      "display": "NIC",
+      "family": "community-faith",
+      "donor": "new-iberia-church",
+      "donor_display": "New Iberia Church of Christ",
+      "package_current": "@inneranimalmedia/theme-church-site",
+      "package_target": "@inneranimalmedia/theme-cypress",
+      "gallery_slug": "church-site",
+      "status": "needs_normalization",
+      "installable": false,
+      "canonical_id": "cypress"
+    },
+    "coc": {
+      "display": "COC",
+      "family": "nonprofit-campaign",
+      "donor": "companions-of-caddo",
+      "donor_display": "Companions of Caddo",
+      "package_current": "@inneranimalmedia/theme-companions-site",
+      "package_target": "@inneranimalmedia/theme-violet",
+      "gallery_slug": "companions-site",
+      "status": "needs_normalization",
+      "installable": false,
+      "canonical_id": "violet"
+    },
+    "cci": {
+      "display": "CCI",
+      "family": "professional-leadgen",
+      "donor": "chrystal-clear-insurance",
+      "donor_display": "Chrystal Clear Insurance",
+      "package_current": "@inneranimalmedia/theme-insurance-site",
+      "package_target": "@inneranimalmedia/theme-harbor",
+      "gallery_slug": "insurance-site",
+      "status": "needs_normalization",
+      "installable": false,
+      "canonical_id": "harbor"
+    },
+    "shin": {
+      "display": "SHIN",
+      "family": "consulting-portfolio",
+      "donor": "shinshu-solutions",
+      "donor_display": "Shinshu Solutions",
+      "package_current": "@inneranimalmedia/theme-shinshu-site",
+      "package_target": "@inneranimalmedia/theme-summit",
+      "gallery_slug": "shinshu-site",
+      "status": "needs_normalization",
+      "installable": false,
+      "canonical_id": "summit"
+    }
+  },
+  "stages": [
+    "raw",
+    "harvested",
+    "needs_normalization",
+    "normalized",
+    "remastered",
+    "package_ready",
+    "published"
+  ],
+  "pipeline": [
+    "agentsam-machine (inventory/types/parse/literal edges/assets/cache)",
+    "agentsam-brand (tokens/ingest/optimize/receipts)",
+    "theme-scenes + CMS contracts (shell/sections/pages)",
+    "refinery UI (keep / use primitive / ignore)"
+  ]
+}

package/protocol/theme-refinery/product-metadata.schema.json

@@ -11,7 +11,27 @@
     "harvest_batch": { "type": "string" },
     "normalization_state": {
       "type": "string",
-      "enum": ["fingerprinted", "portable", "portable-preview", "normalized", "wired", "promoted"]
+      "enum": [
+        "fingerprinted",
+        "harvested",
+        "needs_normalization",
+        "scaffolded",
+        "portable",
+        "portable-preview",
+        "normalized",
+        "remastered",
+        "package_ready",
+        "wired",
+        "promoted"
+      ]
+    },
+    "lineage": {
+      "type": "string",
+      "description": "Short remaster codename (fnf, afm, phs, …). Not the customer/donor product name."
+    },
+    "family": {
+      "type": "string",
+      "description": "Generic reusable family (editorial-commerce, service-gallery, …)."
     },
     "source_hash": { "type": "string" },
     "app_manifest": { "type": "string" },

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.

package/skills/grok-auth/references/prewired-and-env.md

@@ -0,0 +1,54 @@
+# What's pre-wired, and the env vars
+
+## `src/lib/auth/`
+
+| File | Use it for |
+|---|---|
+| `client.ts` | Browser client. `signIn(providerId)`, `signOut()`, `authEnabled`, `GROK_PROVIDERS`. |
+| `server.ts` | The Better Auth instance (server-only). **Do not edit or rewrite.** Import only from `/api/auth/$`. |
+| `email-password.ts` | **Only** place to enable local email/password (`emailAndPasswordEnabled = true`). |
+| `popup.server.ts` | Live-preview popup handler (server-only). Already wired by the Vite plugin — do not create a route for it. |
+| `providers.ts` | `GROK_PROVIDERS` — the fixed broker upstream list (Google and X only; don't add others). |
+| `use-current-user.ts` | `useCurrentUser()` / `useCurrentUserState()` React hooks. |
+| `gates.tsx` | `SignedIn`, `SignedOut`, `RedirectToSignIn`, `UserButton`. |
+| `middleware.ts` | `authMiddleware` for server functions → verified `context.userId`. |
+| `verify.server.ts` | `requireUserId()` / `getSessionUser()` (server-only) for manual wiring. |
+
+## How each mode gets its credentials
+
+- **Live preview** (`*.grok-sandbox.com`): the app is an embedded iframe, so
+  sign-in opens a **popup** (a top-level redirect to the broker can't work inside
+  the iframe) and federates via a baked shared **preview client**
+  (`src/lib/auth/preview.ts`). The handler 302s straight to the broker/upstream
+  login; on return the popup posts the session bearer back in a tiny HTML page.
+  Sessions (and email/password users) persist in the app's embedded PGLite DB —
+  the SAME DB as app data — and, since the iframe's cookies are partitioned,
+  ride that bearer token; all of it lives in `src/lib/auth`.
+  Restarting the preview resets the DB.
+- **Deployed**: the deployer injects a per-app client + `DATABASE_URL`, so
+  sign-in persists identities in Postgres.
+
+## Env vars — do **not** create a `.env` file
+
+**Never write a `.env` / `.env.local` / `.env.example` for auth (or anything
+else) in this sandbox.** Live preview sign-in works out of the box with **zero**
+env configuration: the server falls back to the baked preview client in
+`src/lib/auth/preview.ts`, derives the `*.grok-sandbox.com` origin per-request,
+mints a process-stable session secret, and persists sessions in embedded
+PGLite. Deployed apps get `GROK_AUTH_*` / `BETTER_AUTH_*` / `DATABASE_URL`
+injected by the platform — still not something you write into a file.
+
+Optional process-env knobs (platform / rare overrides only — **do not** put
+these in a file you create):
+
+| Var | Where | Purpose |
+|---|---|---|
+| `VITE_AUTH_ENABLED` | client | `"false"` in the shipped `.grok/app-env.json` (dev user); drop the key to turn sign-in ON. Only client-visible auth flag |
+| `BETTER_AUTH_URL` | server | app's own public origin; unset in preview (origin is derived per-request) |
+| `BETTER_AUTH_SECRET` | server | signs this app's own sessions (process-stable fallback in preview; survives HMR) |
+| `GROK_AUTH_ISSUER` | server | the shared broker (defaults to `https://auth.grok.me`) |
+| `GROK_AUTH_CLIENT_ID` / `GROK_AUTH_CLIENT_SECRET` | server | per-app client (falls back to the preview client) |
+| `DATABASE_URL` | server | when deployed, Better Auth persists here (preview persists to the embedded PGLite — same DB as app data) |
+
+Never expose a non-`VITE_` var to the client. The preview client id/secret live
+server-only in `src/lib/auth/preview.ts`.