feat(phase-4a): groups sync + X-Project-Key header substrate

Foundational work for the upcoming group-scoped sharing feature.

Schema (migration 0003_groups.sql + drizzle schema):
  - memory_access enum ('ro' | 'rw') reserved for Agent B's project_shares
  - groups (id, oidc_iss, name, display_name, …) keyed by (oidc_iss, name)
    so different IdPs can both have e.g. "platform" without colliding
  - user_groups (user_id, group_id, synced_at) PK (user_id, group_id)

Auth (auth.ts + lib/auth/sync-groups.ts):
  - jwt callback now syncs `profile.groups` after upserting the user
  - syncUserGroupsFromClaim runs in a single tx: upserts each group,
    inserts new memberships, deletes ones no longer in the claim
  - missing/empty claim → user has zero groups (wipe memberships)
  - EntraID GUID-vs-name edge case: we treat whatever strings the claim
    emits as names verbatim; groups overage (>200 groups → no claim)
    is documented as unsupported in v1

UserContext + JWT (lib/mcp/context.ts, lib/auth/jwt.ts):
  - AuthenticatedClaims.groups surfaced from verified JWT payload
  - UserContext.groups: string[] — live from OIDC token claim, falls
    back to DB snapshot for CLI (HMAC) tokens which carry no claim
  - UserContext.defaultProjectKey: optional, set from header

MCP route (app/api/mcp/route.ts):
  - reads X-Project-Key header, validates against ProjectKey Zod schema,
    400 on invalid; empty/missing leaves defaultProjectKey undefined
  - auto-upserts the header-supplied project so first-use works without
    a separate project.identify call

Tools (lib/mcp/tools.ts):
  - withDefaultProject helper injects ctx.defaultProjectKey when the
    caller omits `project`. Per-tool defaultScope hint avoids breaking
    snippet.put (user-scope default) while making memory.write
    (project-scope default) honor the header
  - applied to memory.write/list/search/update and all snippet.* tools

Web UI:
  - /settings/groups debug page lists current memberships with synced_at
    and a clear empty state pointing at README troubleshooting
  - /settings/tokens grows a "Pin to project" dropdown; selected key is
    baked into the generated `claude mcp add` snippet as
    `--header "X-Project-Key: <key>"`. The JWT itself stays
    identity-only — pinning is purely a UX shortcut
  - settings landing page links to /settings/groups
  - README troubleshooting bullet covers the empty-groups path for
    Authentik / EntraID / Keycloak

Refactor:
  - extracted resolveProjectId + upsertProject from memory-actions.ts
    into lib/projects.ts so the MCP route can reuse upsertProject

Verification:
  - pnpm typecheck clean
  - SKIP_ENV_VALIDATION=true pnpm build clean; /settings/groups in route table

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

apps/web/lib/mcp/context.ts

@@ -1,28 +1,50 @@
 import { db } from "@/lib/db/client";
-import { users } from "@/lib/db/schema";
+import { users, groups, userGroups } from "@/lib/db/schema";
 import { and, eq } from "drizzle-orm";
 import type { AuthenticatedClaims } from "@/lib/auth/jwt";
 
 /**
  * Per-request user context for MCP tool handlers.
  *
- * Resolves (or creates) the internal `users` row from the Authentik OIDC
- * claims so tools work with stable UUID foreign keys rather than raw `sub`
- * strings.
+ * Resolves (or creates) the internal `users` row from the OIDC claims so
+ * tools work with stable UUID foreign keys rather than raw `sub` strings.
  */
 export interface UserContext {
   /** Internal users.id UUID. */
   userId: string;
-  /** OIDC sub claim (stable identifier from Authentik). */
+  /** OIDC sub claim (stable identifier from the IdP). */
   sub: string;
   /** OIDC issuer. */
   iss: string;
   /** Optional profile fields if present in the access token. */
   email: string | null;
   name: string | null;
+  /**
+   * Group *names* the user is a member of. For OIDC bearer tokens these are
+   * the live values from the verified token's `groups` claim. For CLI tokens
+   * (which carry no groups claim), this is the DB snapshot from the user's
+   * last interactive sign-in — necessarily stale, but the only signal we
+   * have without going back to the IdP.
+   */
+  groups: string[];
+  /**
+   * Project key supplied via the `X-Project-Key` request header. Tools that
+   * accept an optional `project` argument use this as a fallback when the
+   * caller didn't pass one explicitly. Always validated upstream against
+   * the same Zod schema as the tool argument.
+   */
+  defaultProjectKey?: string;
 }
 
-export async function userContextFromClaims(claims: AuthenticatedClaims): Promise<UserContext> {
+export interface UserContextOverrides {
+  /** Project key from the X-Project-Key request header (already validated). */
+  defaultProjectKey?: string;
+}
+
+export async function userContextFromClaims(
+  claims: AuthenticatedClaims,
+  overrides: UserContextOverrides = {},
+): Promise<UserContext> {
   const email = (claims.email as string | undefined) ?? null;
   const name = (claims.name as string | undefined) ?? null;
   const picture = (claims.picture as string | undefined) ?? null;
@@ -47,7 +69,7 @@ export async function userContextFromClaims(claims: AuthenticatedClaims): Promis
     })
     .returning({ id: users.id });
 
-  const userId = row[0]?.id;
+  let userId = row[0]?.id;
   if (!userId) {
     // Race against another upsert — fall back to a select.
     const existing = await db
@@ -56,8 +78,32 @@ export async function userContextFromClaims(claims: AuthenticatedClaims): Promis
       .where(and(eq(users.oidcIss, claims.iss), eq(users.oidcSub, claims.sub)))
       .limit(1);
     if (!existing[0]) throw new Error("user upsert failed and not found on re-read");
-    return { userId: existing[0].id, sub: claims.sub, iss: claims.iss, email, name };
+    userId = existing[0].id;
   }
 
-  return { userId, sub: claims.sub, iss: claims.iss, email, name };
+  // OIDC bearer tokens carry a `groups` claim (when the IdP is configured to
+  // emit it). CLI tokens never do — they go through verifyCliToken which
+  // doesn't set claims.groups. In that case fall back to the DB snapshot
+  // from the user's last interactive sign-in.
+  const groupNames =
+    claims.groups ?? (await loadUserGroups(userId));
+
+  return {
+    userId,
+    sub: claims.sub,
+    iss: claims.iss,
+    email,
+    name,
+    groups: groupNames,
+    defaultProjectKey: overrides.defaultProjectKey,
+  };
+}
+
+async function loadUserGroups(userId: string): Promise<string[]> {
+  const rows = await db
+    .select({ name: groups.name })
+    .from(userGroups)
+    .innerJoin(groups, eq(userGroups.groupId, groups.id))
+    .where(eq(userGroups.userId, userId));
+  return rows.map((r) => r.name);
 }