feat(auth-aware-ssr): scaffold AGENTS.md + rendering-mode matrix + MCP/test fixups

run402-public side of openspec auth-aware-ssr tasks 8.8 + 8.10:

- cli/lib/init-astro.mjs: scaffold emits AGENTS.md template with the
  brutally-small auth.* surface + four Never rules + rendering-mode quick
  map. Save-page example switched from getUser() to auth.requireUser().
  Task 8.8.

- astro/README.md: rendering-mode pattern matrix table (SSR / prerendered /
  server-island / client-hydrate) with copy-pasteable examples for each.
  Task 8.10.

- src/index.ts (MCP deploy_function tool description): swap legacy
  'getUser' bullet for 'auth' so the doctor source scanner stops
  R402_AUTH_UNKNOWN_EXPORT-flagging the MCP descriptor at deploy time.
  Unblocks 5 cli-e2e tests that exercise tier-violation paths.

- sync.test.ts: allowlist auth.fetch() scaffold strings in init-astro.mjs
  and the canonical-fix string in doctor-source-scan.mjs. Also stops
  treating .test.mjs files as production interface files.

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

Author: MajorTal

astro/README.md

@@ -81,6 +81,63 @@ Three options if your SSR route needs request-time config:
 
 The Run402 anon key + service key + project ID + JWT secret + API base ARE auto-injected at deploy time (you'll see `RUN402_ANON_KEY`, `RUN402_SERVICE_KEY`, `RUN402_PROJECT_ID`, `RUN402_JWT_SECRET`, `RUN402_API_BASE` in `process.env` from inside the SSR runtime — those are the platform-managed channel).
 
+### Rendering-mode pattern matrix
+
+Astro supports four rendering modes; `auth.*` calls have different semantics in each. Pick the right mode per page and the rest follows.
+
+| Mode             | How to opt in                                  | When to use                                                       | Auth + cache                                                                                              |
+| ---------------- | ---------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| SSR (default)    | The default in v1.0; no flag needed.           | Personalized pages that read the actor.                          | `auth.user()` returns the actor; `auth.*` helpers taint the response so cache bypasses on Set-Cookie / auth. |
+| Prerendered      | `export const prerender = true;` in the page.  | Pure marketing / docs pages that never see the actor.            | `auth.*` throws `R402_AUTH_PRERENDERED`. The page is built once and served as a static asset.              |
+| Server island    | `<Component server:defer />` inside a page.    | Mostly-static page with a personalized slot (e.g. user dropdown). | `auth.*` is available **inside** the island. The shell is still cacheable.                                  |
+| Client hydrate   | `<SignedIn client:load>…</SignedIn>`.          | Cookie-aware visibility without an SSR pass at all.              | Component fetches `/auth/v1/session` from the browser. No server `auth.*` call.                            |
+
+Pattern picker:
+
+```astro
+---
+// Personalized SSR (default in this scaffold)
+import { auth } from "@run402/functions";
+const user = await auth.requireUser();           // 303 to /auth/sign-in if anonymous
+---
+<h1>Hello, {user.email}</h1>
+```
+
+```astro
+---
+// Prerendered marketing page
+export const prerender = true;
+// Do NOT call auth.user() here — it throws R402_AUTH_PRERENDERED at build time
+---
+<h1>Welcome to the product</h1>
+```
+
+```astro
+---
+// Server-island mix: shell is cacheable, island streams in
+import UserDropdown from "../components/UserDropdown.astro";
+---
+<header>
+  <nav>...</nav>
+  <UserDropdown server:defer>
+    <span slot="fallback">Loading…</span>
+  </UserDropdown>
+</header>
+```
+
+```astro
+---
+// Client-hydrated visibility-only (no SSR auth read)
+import { SignedIn, SignedOut, SignIn, UserButton } from "@run402/astro";
+---
+<SignedIn client:load>
+  <UserButton />
+</SignedIn>
+<SignedOut client:load>
+  <SignIn returnTo="/" />
+</SignedOut>
+```
+
 ## `<Run402Picture>` — runtime CMS images
 
 For images coming from a DB row at SSR time (the common CMS pattern), use `<Run402Picture asset={page.hero_asset}>`. The `asset` prop is the `AssetRef` JSONB that `r.assets.put()` returned at upload time — store the whole object, not just the URL, then render directly.

cli/lib/init-astro.mjs

@@ -215,11 +215,10 @@ const { title, ogImage, canonical } = Astro.props;
 //   2. DB update.
 //   3. cache.invalidate() so the public URL re-renders fresh on next visit.
 import type { APIRoute } from "astro";
-import { db, getUser, cache } from "@run402/functions";
+import { db, auth, cache } from "@run402/functions";
 
 export const POST: APIRoute = async ({ request }) => {
-  const user = await getUser();
-  if (!user) return new Response("Unauthorized", { status: 401 });
+  const user = await auth.requireUser();
 
   const body = (await request.json()) as { slug: string; title: string; html: string };
   if (!body?.slug) return new Response("Missing slug", { status: 400 });
@@ -236,6 +235,96 @@ export const POST: APIRoute = async ({ request }) => {
     headers: { "content-type": "application/json" },
   });
 };
+`,
+    },
+    {
+      path: "AGENTS.md",
+      content: `# AGENTS.md
+
+This file documents the brutally-small Run402 surface this Astro project
+uses. Coding agents: read this first. The platform is intentionally small —
+there are no other auth helpers, no other client surfaces, and no other
+hidden APIs.
+
+## The auth surface
+
+\`auth\` is the entire user-auth surface. Import from \`@run402/functions\`:
+
+\`\`\`ts
+import { auth } from "@run402/functions";
+
+// In SSR pages and API routes:
+const user = await auth.user();             // Actor | null
+const user = await auth.requireUser();      // Actor; throws R402_AUTH_REQUIRED
+const { user, role } = await auth.requireRole("admin");
+const { user, membership } = await auth.requireMembership("member");
+await auth.requireFresh({ maxAge: "10m", amr: ["passkey"] });
+
+// CSRF for hosted forms (server-side, in <form> rendering):
+const field = auth.csrfField();
+// → <input type="hidden" name="_csrf" value="..." />
+
+// Cross-origin-safe fetch (auto-forwards actor context to same-origin):
+const res = await auth.fetch("/api/internal");  // relative URLs only
+\`\`\`
+
+## The four Never rules
+
+1. **Never \`try\`/\`catch\` auth errors.** Let them bubble. The platform turns
+   \`R402_AUTH_REQUIRED\` into a 303 to \`/auth/sign-in?return_to=…\` and
+   \`R402_AUTH_INSUFFICIENT_ROLE\` into 403 with a fix-it response. Catching
+   them creates silent-null bugs.
+
+2. **Never \`.eq("user_id", user.id)\`.** \`db()\` propagates the actor to
+   PostgREST so RLS enforces ownership server-side. The redundant filter is
+   a code smell that \`run402 doctor\` flags as
+   \`R402_AUTH_REDUNDANT_USER_FILTER\`.
+
+3. **Never set client-supplied actor headers.** \`x-run402-actor-*\`,
+   \`run402.actor.*\`, \`x-r402-actor-*\` are platform-owned channel headers.
+   The gateway strips inbound spoofing attempts and emits
+   \`R402_AUTH_ACTOR_HEADER_SPOOF\` in strict mode.
+
+4. **Never mint a session from a raw \`userId\`.** Use
+   \`auth.sessions.createResponseFromIdentity({ provider, subject, proof, amr })\`
+   with a verified identity proof. No \`createSessionForUserId(uuid)\` API exists.
+
+## Hosted UI components
+
+For sign-in, sign-up, and sign-out chrome, use the platform's
+\`@run402/astro\` components — they emit forms posting to platform hosted
+routes (\`/auth/v1/sign-in\` etc.) with the CSRF token already wired:
+
+\`\`\`astro
+---
+import { SignIn, SignUp, UserButton, SignedIn, SignedOut } from "@run402/astro";
+---
+
+<SignedIn>
+  <UserButton />
+</SignedIn>
+<SignedOut>
+  <SignIn returnTo="/dashboard" />
+</SignedOut>
+\`\`\`
+
+Do NOT roll your own sign-in form. The hosted routes handle CSRF, returnTo
+validation, OAuth provider bridges, and passkey ceremonies.
+
+## Rendering-mode quick map
+
+\`auth.*\` calls run at request time, so the page must be SSR or a
+server-island. Calling \`auth.user()\` from a prerendered page throws
+\`R402_AUTH_PRERENDERED\`.
+
+| Mode                          | When                                | Auth-aware              |
+| ----------------------------- | ----------------------------------- | ----------------------- |
+| SSR (default)                 | Personalized pages                  | \`auth.user()\` works   |
+| Prerendered                   | Marketing pages, never sees actor   | \`auth.*\` throws       |
+| Server island                 | Prerendered page + personalized slot| \`auth.*\` in the island|
+| Client hydrate                | Visibility-only, no SSR pass        | Component hits session  |
+
+For error-code reference: https://run402.com/errors/#R402_AUTH_REQUIRED
 `,
     },
   ];

src/index.ts

@@ -357,7 +357,7 @@ server.tool(
 
 server.tool(
   "deploy_function",
-  "Deploy a serverless function (Node 22) to a project. Handler signature: export default async (req: Request) => Response. The function can `import { db, adminDb, getUser, email, ai } from '@run402/functions'` — auto-bundled by the platform. Additional npm packages are bundled at deploy time when listed in `deps` (bare names resolve to latest; pinned/range specs are honored verbatim; `@run402/functions` and `run402-functions` rejected; max 30 entries; native binaries rejected). The response includes `runtime_version` (the bundled `@run402/functions` version — surface as 'Functions runtime version', never bare 'runtime'), `deps_resolved` (map of dep name → installed concrete version), and an optional top-level `warnings` array (sibling to the function record).",
+  "Deploy a serverless function (Node 22) to a project. Handler signature: export default async (req: Request) => Response. The function can `import { db, adminDb, auth, email, ai } from '@run402/functions'` — auto-bundled by the platform. Additional npm packages are bundled at deploy time when listed in `deps` (bare names resolve to latest; pinned/range specs are honored verbatim; `@run402/functions` and `run402-functions` rejected; max 30 entries; native binaries rejected). The response includes `runtime_version` (the bundled `@run402/functions` version — surface as 'Functions runtime version', never bare 'runtime'), `deps_resolved` (map of dep name → installed concrete version), and an optional top-level `warnings` array (sibling to the function record).",
   deployFunctionSchema,
   async (args) => handleDeployFunction(args),
 );

sync.test.ts

@@ -896,6 +896,15 @@ describe("CLI/MCP SDK-boundary guard", () => {
       ["cli/lib/init.mjs", [/\bfetch\(TEMPO_RPC\b/]], // Tempo faucet/RPC
       ["cli/lib/ci.mjs", [/\bfetch\(`https:\/\/api\.github\.com\/repos\//]], // GitHub repository lookup
       ["src/tools/init.ts", [/\bfetch\(TEMPO_RPC\b/]], // Tempo faucet/RPC
+      // doctor-source-scan.mjs documents the canonical fix string for
+      // browser-bearer scans — the string itself contains "auth.fetch()"
+      // as the recommended replacement, not a real fetch call.
+      ["cli/lib/doctor-source-scan.mjs", [/Use auth\.fetch\(\) for same-origin/]],
+      // init-astro.mjs emits scaffold *strings* that get written into the
+      // user's generated project. `auth.fetch("/api/internal")` is the
+      // recommended SDK pattern shown in the template — it is template
+      // text, not a CLI-runtime fetch.
+      ["cli/lib/init-astro.mjs", [/auth\.fetch\("\/api\/internal"\)/, /Cross-origin-safe fetch/]],
     ]);
 
     const violations: string[] = [];
@@ -927,7 +936,7 @@ function productionInterfaceFiles(): string[] {
   const srcTools = join(__dirname, "src/tools");
   return [
     ...readdirSync(cliLib)
-      .filter((name) => name.endsWith(".mjs"))
+      .filter((name) => name.endsWith(".mjs") && !name.endsWith(".test.mjs"))
       .map((name) => join(cliLib, name)),
     ...readdirSync(srcTools)
       .filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"))