@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.8

package/src/local/runtime-store.js

@@ -43,14 +43,36 @@ export function createRuntimeRunId() {
 export async function startRuntimeRun(value = {}) {
   const id = clean(value.id) || createRuntimeRunId();
   await withStore(value.projectRoot || value.cwd, async (db) => {
+    const activeStep = (!clean(value.plan_id) || !clean(value.todo_id))
+      ? await db.prepare(`
+          SELECT t.id AS todo_id, t.plan_id
+          FROM agentsam_todo t
+          JOIN agentsam_plans p ON p.id = t.plan_id
+          WHERE t.status = 'running' AND p.status = 'active'
+          ORDER BY t.updated_at_unix DESC, t.created_at_unix DESC
+          LIMIT 1
+        `).first()
+      : null;
+    const activePlan = !clean(value.plan_id) && !activeStep?.plan_id
+      ? await db.prepare(`
+          SELECT id AS plan_id FROM agentsam_plans
+          WHERE status = 'active'
+          ORDER BY updated_at_unix DESC, created_at_unix DESC
+          LIMIT 1
+        `).first()
+      : null;
+    const planId = clean(value.plan_id) || clean(activeStep?.plan_id) || clean(activePlan?.plan_id) || null;
+    const todoId = clean(value.todo_id) || clean(activeStep?.todo_id) || null;
     await db.prepare(`
       INSERT INTO agentsam_agent_run (
-        id, account_id, source_client, surface, mode, model_key,
+        id, account_id, plan_id, todo_id, source_client, surface, mode, model_key,
         reasoning_effort, requested_service_tier, status, started_at_unix, updated_at_unix
-      ) VALUES (?, ?, 'agentsam-cli', 'cli', ?, ?, ?, ?, 'running', unixepoch(), unixepoch())
+      ) VALUES (?, ?, ?, ?, 'agentsam-cli', 'cli', ?, ?, ?, ?, 'running', unixepoch(), unixepoch())
     `).bind(
       id,
       clean(value.account_id) || null,
+      planId,
+      todoId,
       clean(value.mode) || 'agent',
       clean(value.model_key) || null,
       clean(value.reasoning_effort) || null,

package/src/local/sqlite.js

@@ -90,6 +90,23 @@ export async function createLocalSqliteDatabase(filePath = '.agentsam/data/agent
         },
       };
     },
+    async batch(statements = []) {
+      database.exec('BEGIN IMMEDIATE');
+      try {
+        const results = [];
+        for (const statement of statements) {
+          if (!statement || typeof statement.run !== 'function') {
+            throw new TypeError('Local SQLite batch entries must expose run()');
+          }
+          results.push(await statement.run());
+        }
+        database.exec('COMMIT');
+        return results;
+      } catch (error) {
+        try { database.exec('ROLLBACK'); } catch {}
+        throw error;
+      }
+    },
     exec(sql) {
       database.exec(sql);
     },

package/src/sam/operations/package-audit.js

@@ -0,0 +1,41 @@
+import { defineSamOperation } from '../define.js';
+import { auditPackages } from '../../commands/package.js';
+
+export const packageAuditOp = defineSamOperation({
+  id: 'package.audit',
+  version: 1,
+  module: 'package',
+  action: 'audit',
+  summary: 'Audit AgentSam package publication intent, registry state, and structural blockers.',
+  purpose:
+    'Establish deterministic package-distribution authority for @inneranimalmedia packages without publishing anything.',
+  outcome:
+    'Return classified package manifests, public-distribution intent, registry state when allowed, and structural blockers.',
+  description:
+    'Discover scoped package manifests, classify public/private intent, optionally query npm registry state, and return a bounded read-only audit.',
+  skill: { id: 'agentsam-progression-guard', help: true },
+  accepts: ['root', 'publicOnly', 'offline'],
+  phases: ['discover_manifests', 'classify_intent', 'resolve_registry_state', 'emit_audit'],
+  execution: {
+    lanes: ['local', 'remote', 'sandbox'],
+    model: 'never',
+    embedding: 'never',
+    network: 'optional',
+    sideEffects: 'none',
+    provider_spend: 'none',
+  },
+  risk: 'read_only',
+  capabilities: ['package.audit'],
+  artifacts: ['package.audit'],
+  cli: { command: [['package', 'audit']] },
+  docs: { section: 'Packages' },
+  status: 'stable',
+  async handler(input = {}, ctx = {}) {
+    const root = input.root || input.cwd || ctx.cwd || process.cwd();
+    return auditPackages({
+      root,
+      publicOnly: input.publicOnly === true || input.public === true,
+      offline: input.offline === true,
+    });
+  },
+});

package/src/sam/seed.js

@@ -8,6 +8,7 @@ import { codebaseindexIngestOp } from './operations/codebaseindex-ingest.js';
 import { planningAstarOp } from './operations/planning-astar.js';
 import { planningGoapOp } from './operations/planning-goap.js';
 import { decisionEvaluateOp } from './operations/decision-evaluate.js';
+import { packageAuditOp } from './operations/package-audit.js';
 
 export const SEED_OPERATIONS = [
   repositoryInspect,
@@ -19,6 +20,7 @@ export const SEED_OPERATIONS = [
   planningAstarOp,
   planningGoapOp,
   decisionEvaluateOp,
+  packageAuditOp,
 ];
 
 let seeded = false;

package/skills/grok-auth/SKILL.md

@@ -1,110 +0,0 @@
----
-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

@@ -1,25 +0,0 @@
-{
-  "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

@@ -1,64 +0,0 @@
-# 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

@@ -1,49 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-# 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`.

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

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

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

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