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);
 }

apps/web/lib/mcp/tools.ts

@@ -73,6 +73,42 @@ async function resolveProjectId(
   return row[0]?.id ?? null;
 }
 
+/**
+ * If the args object has no explicit `project` key, inject the request-
+ * scoped `defaultProjectKey` from the `X-Project-Key` header (when set).
+ * This lets a client pin every call to one project without restating it
+ * per tool invocation. Returns a new object — the original is untouched.
+ *
+ * The injection rule is: inject when the caller plausibly intends a
+ * project scope. Concretely we inject when EITHER:
+ *
+ *   * `scope` is explicitly `'project'`, OR
+ *   * `scope` is omitted AND the tool's natural default IS project-scope
+ *     (memory.write defaults to project; snippet.put defaults to user).
+ *
+ * We never inject when `scope === 'user'` is explicit — the schemas refine
+ * `(scope='user', project=<anything>)` as invalid. An explicit `project`
+ * argument always wins and we never overwrite it.
+ *
+ * `defaultScope` is the tool's own default (e.g. 'project' for memory.*,
+ * 'user' for snippet.*). For filter tools that have no scope default
+ * (memory.list, memory.search, snippet.list), pass 'project' — those
+ * cases treat the header as a project filter and benefit from injection.
+ */
+function withDefaultProject(
+  args: unknown,
+  ctx: UserContext,
+  defaultScope: "project" | "user" = "project",
+): unknown {
+  if (!ctx.defaultProjectKey) return args;
+  if (args === null || typeof args !== "object" || Array.isArray(args)) return args;
+  const obj = args as Record<string, unknown>;
+  if (obj.project !== undefined) return args;
+  if (obj.scope === "user") return args;
+  if (obj.scope === undefined && defaultScope === "user") return args;
+  return { ...obj, project: ctx.defaultProjectKey };
+}
+
 // ---------- tools ----------
 
 const projectIdentify: ToolDef = {
@@ -150,7 +186,7 @@ const memoryWrite: ToolDef = {
     required: ["content"],
   },
   async handler(args, ctx) {
-    const parsed = MemoryWriteInput.safeParse(args);
+    const parsed = MemoryWriteInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const scope = parsed.data.scope;
@@ -213,7 +249,7 @@ const memoryList: ToolDef = {
     },
   },
   async handler(args, ctx) {
-    const parsed = MemoryListInput.safeParse(args);
+    const parsed = MemoryListInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const where = [eq(memories.userId, ctx.userId), isNull(memories.deletedAt)];
@@ -343,7 +379,7 @@ const memoryUpdate: ToolDef = {
     required: ["id"],
   },
   async handler(args, ctx) {
-    const parsed = MemoryUpdateInput.safeParse(args);
+    const parsed = MemoryUpdateInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const existingRows = await db
@@ -456,7 +492,7 @@ const memorySearch: ToolDef = {
     required: ["query"],
   },
   async handler(args, ctx) {
-    const parsed = MemorySearchInput.safeParse(args);
+    const parsed = MemorySearchInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const { query, scope, tags, limit } = parsed.data;
@@ -549,7 +585,9 @@ const snippetPut: ToolDef = {
     required: ["name", "body"],
   },
   async handler(args, ctx) {
-    const parsed = SnippetPutInput.safeParse(args);
+    // snippet.put defaults to user-scope, so a header-supplied project key
+    // is only honored when the caller explicitly says `scope='project'`.
+    const parsed = SnippetPutInput.safeParse(withDefaultProject(args, ctx, "user"));
     if (!parsed.success) return err(parsed.error.message);
 
     if (parsed.data.scope === "project") {
@@ -620,7 +658,7 @@ const snippetGet: ToolDef = {
     required: ["name"],
   },
   async handler(args, ctx) {
-    const parsed = SnippetGetInput.safeParse(args);
+    const parsed = SnippetGetInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const snippet = await getSnippet(ctx.userId, {
@@ -669,7 +707,7 @@ const snippetList: ToolDef = {
     },
   },
   async handler(args, ctx) {
-    const parsed = SnippetListInput.safeParse(args);
+    const parsed = SnippetListInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const rows = await listSnippets(ctx.userId, {
@@ -708,7 +746,7 @@ const snippetDelete: ToolDef = {
     required: ["name"],
   },
   async handler(args, ctx) {
-    const parsed = SnippetDeleteInput.safeParse(args);
+    const parsed = SnippetDeleteInput.safeParse(withDefaultProject(args, ctx));
     if (!parsed.success) return err(parsed.error.message);
 
     const deleted = await softDeleteSnippet(ctx.userId, {