create-ailk 0.11.2 → 0.11.4

package/templates/apps/web/app/.well-known/ai-plugin.json/route.ts

@@ -9,7 +9,8 @@
  *   - logo_url: no asset yet; omitted
  *   - contact_email: no org email configured; omitted
  *   - legal_info_url: no legal page yet; omitted
- *   - api.url: no deployed OpenAPI spec yet; defaults to /openapi.json on same origin
+ *   - api.url: /openapi.json on this same origin, served by `app/openapi.json`,
+ *     which proxies apps/api's `/v1/openapi.json` (#7396)
  *
  * ─── Consumer re-validation expectation ─────────────────────────────────────
  * This manifest is published over a public, cacheable HTTP route. Consumers

package/templates/apps/web/app/.well-known/mcp.json/build-manifest.ts

@@ -16,6 +16,9 @@
  * default) instead of a hardcoded vendor-brand literal.
  * Issue #7136 — the five `feature`-tagged tools are gated on the licence
  * features the route passes in (`heldFeatures`), as registration is.
+ * Issue #7396 — `mcpEndpoint` is the configured MCP HTTP host or absent. It
+ * was `${baseUrl}/api/mcp`, a path apps/web does not serve, so every agent
+ * that followed it got a 404.
  */
 
 import {
@@ -44,8 +47,12 @@ export interface McpManifest {
   name: string;
   /** Human-readable server description. */
   description: string;
-  /** Absolute URL the agent connects to for the MCP protocol session. */
-  mcpEndpoint: string;
+  /**
+   * Absolute URL the agent connects to for the MCP protocol session — the
+   * standalone MCP HTTP host. Omitted when none is configured: the web host
+   * serves no MCP endpoint of its own (#7396).
+   */
+  mcpEndpoint?: string;
   /** Tool catalog — names, descriptions, input schemas, and output schemas. */
   tools: McpToolCatalogEntry[];
   /**
@@ -69,14 +76,13 @@ export interface McpManifest {
 }
 
 export interface BuildMcpManifestOptions {
-  /** Site base URL — used to derive the MCP endpoint. */
-  baseUrl: string;
   /** AILK package version surfaced to discovering agents. */
   ailkVersion: string;
   /**
    * Optional: absolute URL of the standalone MCP HTTP transport
    * (i.e. the URL of apps/mcp when running in HTTP mode).
-   * When set, the manifest advertises this as an additional transport endpoint.
+   * When set, the manifest advertises it as `mcpEndpoint` and as an http
+   * transport descriptor; when not, neither appears.
    * Typically sourced from the MCP_PUBLIC_HTTP_URL env var in the web app.
    */
   mcpHttpUrl?: string;
@@ -103,9 +109,6 @@ export interface BuildMcpManifestOptions {
   featureGate?: McpCatalogOptions["featureGate"];
 }
 
-/** Path the MCP server is mounted at, relative to baseUrl. */
-const MCP_ENDPOINT_PATH = "/api/mcp";
-
 /** MCP HTTP transport version this server implements. */
 const MCP_HTTP_VERSION = "2025-03-26";
 
@@ -131,7 +134,9 @@ export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
     name: SITE_NAME,
     description:
       "AX-first OSS template — ship software with API + MCP as canonical agent surfaces.",
-    mcpEndpoint: `${opts.baseUrl}${MCP_ENDPOINT_PATH}`,
+    // Spread conditional to satisfy exactOptionalPropertyTypes: the key is
+    // absent, not undefined, when no MCP HTTP host is configured.
+    ...(opts.mcpHttpUrl ? { mcpEndpoint: opts.mcpHttpUrl } : {}),
     tools: getMcpToolCatalog({
       addons: { commerce: opts.commerceClaimed === true },
       features: opts.heldFeatures ?? [],

package/templates/apps/web/app/.well-known/mcp.json/route.ts

@@ -4,6 +4,8 @@
  * Per-site MCP discovery manifest. Agents land on a customer site, hit this
  * URL, and discover the MCP endpoint + tool catalog without out-of-band
  * coordination. Issue #209 (initial), #300 (moved to correct URL + CORS).
+ * The endpoint is advertised only when MCP_PUBLIC_HTTP_URL configures one
+ * (#7396) — apps/web serves no MCP endpoint itself.
  *
  * Assembly — no fetch(). The catalog is read in-process from
  * @working-theory/metadata; the AILK version is read from this app's
@@ -29,7 +31,6 @@ import {
   COMMERCE_FEATURE,
   resolveLicenceFeatures,
 } from "../../../src/lib/commerce-claim";
-import { resolveBaseUrl } from "../../../src/lib/routes";
 
 import { buildMcpManifest } from "./build-manifest";
 
@@ -48,13 +49,13 @@ export function OPTIONS(): Response {
 
 export async function GET(): Promise<Response> {
   // MCP_PUBLIC_HTTP_URL advertises the standalone HTTP transport endpoint
-  // (apps/mcp running in HTTP mode). When set, the manifest includes it
-  // as an additional transport descriptor for discovering agents.
+  // (apps/mcp running in HTTP mode). When set, the manifest names it as
+  // `mcpEndpoint` and as an http transport descriptor; when unset, it
+  // advertises no MCP URL at all (#7396).
   const mcpHttpUrlEnv = process.env["MCP_PUBLIC_HTTP_URL"];
   const heldFeatures = await resolveLicenceFeatures();
 
   const manifest = buildMcpManifest({
-    baseUrl: resolveBaseUrl(),
     ailkVersion: packageJson.version,
     commerceClaimed: heldFeatures.includes(COMMERCE_FEATURE),
     heldFeatures,

package/templates/apps/web/app/[locale]/(auth)/__tests__/password-reset.test.tsx

@@ -62,6 +62,8 @@ jest.mock("better-auth/next-js", () => ({
   nextCookies: () => ({ id: "next-cookies" }),
 }));
 
+jest.mock("better-auth/plugins", () => ({ magicLink: () => ({ id: "magic-link" }) }));
+
 /**
  * The signer seam. `buildAuthEmailRequest` has exactly one external
  * dependency — `node:crypto`'s `createHmac` — so a throwing `createHmac` is a

package/templates/apps/web/app/[locale]/(auth)/sign-in/__tests__/page.test.tsx

@@ -18,6 +18,9 @@
  *       (#6018 AC-1). (#6068 repointed that predicate from `isResetAvailable()`
  *       to `resetSendConfigured()`; the mock below binds both to one fn, so
  *       these cases read identically either way.)
+ *   (h) the email sign-in link (#7435): with "magic-link" active the form
+ *       renders beside the providers (or alone); a `?error=` from a failed
+ *       link maps to fixed copy and is never echoed.
  *
  * `next-intl/server` is mocked globally (apps/web/__tests__/setup.ts) against
  * the real en.json, so `signIn` copy is asserted by its real strings.
@@ -58,10 +61,13 @@ jest.mock("better-auth/react", () => ({
 import en from "../../../../../messages/en.json";
 import Page, { generateMetadata } from "../page";
 
-async function renderPage(next?: string): Promise<void> {
+async function renderPage(next?: string, error?: string): Promise<void> {
   const el = await Page({
     params: Promise.resolve({ locale: "en" }),
-    searchParams: Promise.resolve(next === undefined ? {} : { next }),
+    searchParams: Promise.resolve({
+      ...(next === undefined ? {} : { next }),
+      ...(error === undefined ? {} : { error }),
+    }),
   });
   render(el);
 }
@@ -196,3 +202,64 @@ describe("/sign-in page", () => {
     expect(screen.queryByTestId("auth-forgot")).toBeNull();
   });
 });
+
+describe("/sign-in page — the email sign-in link (#7435)", () => {
+  it("(h) renders no email-link form when 'magic-link' is not active", async () => {
+    mockGetActiveProviderIds.mockReturnValue(["google", "email"]);
+    await renderPage("/account");
+    expect(screen.queryByTestId("auth-email-link-form")).toBeNull();
+  });
+
+  it("(h) with google + magic-link: the Google button and 'Email me a sign-in link'", async () => {
+    mockGetActiveProviderIds.mockReturnValue(["google", "magic-link"]);
+    await renderPage("/account");
+    expect(screen.getByTestId("auth-sso-google")).toBeInTheDocument();
+    expect(screen.getByTestId("auth-email-link-submit")).toHaveTextContent(
+      en.signIn.emailLinkSubmit,
+    );
+    expect(en.signIn.emailLinkSubmit).toBe("Email me a sign-in link");
+    expect(screen.getByTestId("auth-email-link-divider")).toBeInTheDocument();
+  });
+
+  it("(h) with magic-link only: the form renders and the not-configured subhead does not", async () => {
+    mockGetActiveProviderIds.mockReturnValue(["magic-link"]);
+    await renderPage();
+    expect(screen.getByTestId("auth-email-link-form")).toBeInTheDocument();
+    expect(screen.queryByText(en.signIn.notConfiguredSubhead)).toBeNull();
+    expect(screen.getByText(en.signIn.subhead)).toBeInTheDocument();
+  });
+
+  it("(h) beside the password form when the password method is active too", async () => {
+    mockGetActiveProviderIds.mockReturnValue(["google", "email", "magic-link"]);
+    await renderPage("/account");
+    expect(screen.getByTestId("auth-password")).toBeInTheDocument();
+    expect(screen.getByTestId("auth-email-link-form")).toBeInTheDocument();
+  });
+
+  it.each(["INVALID_TOKEN", "new_user_signup_disabled"])(
+    "(h) ?error=%s renders the expired-link notice",
+    async (error) => {
+      mockGetActiveProviderIds.mockReturnValue(["google", "magic-link"]);
+      await renderPage("/account", error);
+      expect(screen.getByTestId("sign-in-link-notice")).toHaveTextContent(
+        en.signIn.emailLinkExpired,
+      );
+    },
+  );
+
+  it("(h) any other ?error renders signInFailed and never echoes the value", async () => {
+    mockGetActiveProviderIds.mockReturnValue(["google", "magic-link"]);
+    await renderPage("/account", "<script>alert(1)</script>");
+    expect(screen.getByTestId("sign-in-link-notice")).toHaveTextContent(
+      en.signIn.signInFailed,
+    );
+    expect(document.body.innerHTML).not.toContain("alert(1)");
+    expect(document.body.innerHTML).not.toContain("&lt;script");
+  });
+
+  it("(h) no ?error → no notice", async () => {
+    mockGetActiveProviderIds.mockReturnValue(["google", "magic-link"]);
+    await renderPage("/account");
+    expect(screen.queryByTestId("sign-in-link-notice")).toBeNull();
+  });
+});

package/templates/apps/web/app/[locale]/(auth)/sign-in/__tests__/sign-in-card.test.tsx

@@ -0,0 +1,156 @@
+/**
+ * Tests for `SignInCard`'s email sign-in link flow (#7435 § D8, AC-5).
+ *
+ * The card POSTs to Better Auth's `/sign-in/magic-link` through the shared
+ * client's `$fetch` (not the `magicLinkClient()` plugin, so no ESM-only module
+ * enters the client graph). Pinned here:
+ *   - the request carries the typed email, `callbackURL` = `next`, and the
+ *     `errorCallbackURL`;
+ *   - a success shows the neutral sent state — never the address, never
+ *     AuthCard's English "Follow the link we just sent" default;
+ *   - a 429 lands `rateLimited` on the field; any other error, or a
+ *     rejection, lands `failed`;
+ *   - with `emailLink` false the card renders as before.
+ */
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+const mockFetch = jest.fn();
+jest.mock("better-auth/react", () => ({
+  __esModule: true,
+  createAuthClient: () => ({
+    signIn: { social: jest.fn(), email: jest.fn() },
+    $fetch: (...args: unknown[]) => mockFetch(...args),
+  }),
+}));
+
+import { SignInCard, type SignInCardProps } from "../sign-in-card";
+
+const EMAIL_LINK_LABELS = {
+  sentHeading: "Check your email",
+  sentSubhead: "Look for a message from this site.",
+  sentBody: "If an account uses that address, a sign-in link is on its way.",
+  backToSignIn: "Back to sign in",
+  failed: "We couldn't send a sign-in link. Try again.",
+  rateLimited: "Too many requests. Wait a minute, then try again.",
+};
+
+function props(overrides: Partial<SignInCardProps> = {}): SignInCardProps {
+  return {
+    providers: ["google"],
+    method: "sso",
+    next: "/account",
+    labels: { emailLinkSubmit: "Email me a sign-in link" },
+    notConfiguredSubhead: "Sign-in is not configured.",
+    errorLabels: { signInFailed: "Sign-in failed.", providerFailed: "Nope." },
+    emailLink: true,
+    errorCallbackURL: "/sign-in?next=%2Faccount",
+    signInHref: "/sign-in?next=%2Faccount",
+    emailLinkLabels: EMAIL_LINK_LABELS,
+    ...overrides,
+  };
+}
+
+async function requestLink(email = "member@example.com"): Promise<void> {
+  const user = userEvent.setup();
+  await user.type(screen.getByTestId("auth-email-link-input"), email);
+  await user.click(screen.getByTestId("auth-email-link-submit"));
+}
+
+beforeEach(() => {
+  mockFetch.mockReset().mockResolvedValue({ data: { status: true }, error: null });
+});
+
+describe("SignInCard — email sign-in link (#7435)", () => {
+  it("POSTs /sign-in/magic-link with the email, next and the errorCallbackURL", async () => {
+    render(<SignInCard {...props()} />);
+    await requestLink();
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch).toHaveBeenCalledWith("/sign-in/magic-link", {
+      method: "POST",
+      body: {
+        email: "member@example.com",
+        callbackURL: "/account",
+        errorCallbackURL: "/sign-in?next=%2Faccount",
+      },
+    });
+  });
+
+  it("shows the neutral sent state on success — no address, no AuthCard defaults", async () => {
+    render(<SignInCard {...props()} />);
+    await requestLink();
+    expect(
+      await screen.findByText(EMAIL_LINK_LABELS.sentHeading),
+    ).toBeInTheDocument();
+    expect(screen.getByText(EMAIL_LINK_LABELS.sentSubhead)).toBeInTheDocument();
+    expect(screen.getByText(EMAIL_LINK_LABELS.sentBody)).toBeInTheDocument();
+    const back = screen.getByTestId("auth-footer-link");
+    expect(back).toHaveTextContent(EMAIL_LINK_LABELS.backToSignIn);
+    expect(back).toHaveAttribute("href", "/sign-in?next=%2Faccount");
+    expect(document.body.textContent).not.toContain("member@example.com");
+    expect(document.body.textContent).not.toContain("Follow the link we just sent");
+    expect(screen.queryByTestId("auth-email-link-form")).toBeNull();
+  });
+
+  it("lands rateLimited on the field for a 429", async () => {
+    mockFetch.mockResolvedValue({
+      data: null,
+      error: { status: 429, statusText: "Too Many Requests" },
+    });
+    render(<SignInCard {...props()} />);
+    await requestLink();
+    expect(
+      await screen.findByText(EMAIL_LINK_LABELS.rateLimited),
+    ).toBeInTheDocument();
+    expect(screen.getByTestId("auth-email-link-form")).toBeInTheDocument();
+  });
+
+  it("lands failed on the field for any other error", async () => {
+    mockFetch.mockResolvedValue({
+      data: null,
+      error: { status: 400, statusText: "Bad Request" },
+    });
+    render(<SignInCard {...props()} />);
+    await requestLink();
+    expect(await screen.findByText(EMAIL_LINK_LABELS.failed)).toBeInTheDocument();
+  });
+
+  it("lands failed on the field when the request rejects", async () => {
+    mockFetch.mockRejectedValue(new Error("network"));
+    render(<SignInCard {...props()} />);
+    await requestLink();
+    expect(await screen.findByText(EMAIL_LINK_LABELS.failed)).toBeInTheDocument();
+  });
+
+  it("sends one request for a double submit while the first is in flight", async () => {
+    let resolve!: (v: unknown) => void;
+    mockFetch.mockReturnValue(new Promise((r) => (resolve = r)));
+    const user = userEvent.setup();
+    render(<SignInCard {...props()} />);
+    await user.type(screen.getByTestId("auth-email-link-input"), "member@example.com");
+    await user.click(screen.getByTestId("auth-email-link-submit"));
+    await user.click(screen.getByTestId("auth-email-link-submit"));
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    resolve({ data: { status: true }, error: null });
+    expect(await screen.findByText(EMAIL_LINK_LABELS.sentHeading)).toBeInTheDocument();
+  });
+
+  it("renders the link notice above the card when given one", () => {
+    render(<SignInCard {...props({ linkNotice: "That link expired." })} />);
+    expect(screen.getByTestId("sign-in-link-notice")).toHaveTextContent(
+      "That link expired.",
+    );
+  });
+
+  it("renders the form alone, without the not-configured subhead, when it is the only method", () => {
+    render(<SignInCard {...props({ providers: [] })} />);
+    expect(screen.getByTestId("auth-email-link-form")).toBeInTheDocument();
+    expect(screen.queryByText("Sign-in is not configured.")).toBeNull();
+  });
+
+  it("renders no email-link form when emailLink is false", () => {
+    render(<SignInCard {...props({ emailLink: false, providers: [] })} />);
+    expect(screen.queryByTestId("auth-email-link-form")).toBeNull();
+    expect(screen.getByText("Sign-in is not configured.")).toBeInTheDocument();
+  });
+});

package/templates/apps/web/app/[locale]/(auth)/sign-in/page.tsx

@@ -6,6 +6,11 @@
  * `?next=` return path, and the translated `signIn` labels — then renders the
  * `SignInCard` client island.
  *
+ * Email sign-in link (#7435 § D9): offered when auth-env reports
+ * "magic-link" — the predicate `auth.ts` registers the plugin on. A link that
+ * fails verification lands back here with Better Auth's `?error=`, which maps
+ * to FIXED copy; the raw value is never rendered.
+ *
  * Since #5963 the page lives in the `(auth)` route group — the URL is
  * unchanged (a group contributes no path segment) but the frame is
  * `AuthShell`, not the marketing Nav + Footer. The shell owns the brand mark
@@ -17,7 +22,6 @@
  */
 
 import { localeHref } from "@working-theory/ui";
-import type { AuthCardLabels } from "@working-theory/ui/blocks";
 import type { Metadata } from "next";
 import { getTranslations } from "next-intl/server";
 import type { ReactElement } from "react";
@@ -29,10 +33,32 @@ import {
 
 import { resolveNextPath } from "./next-path";
 import { SignInCard, type SignInProvider } from "./sign-in-card";
+import { resolveSignInCardText, type SignInCardText } from "./sign-in-text";
 
 interface Props {
   params: Promise<{ locale: string }>;
-  searchParams: Promise<{ next?: string | string[] }>;
+  searchParams: Promise<{ next?: string | string[]; error?: string | string[] }>;
+}
+
+/**
+ * Better Auth's magic-link verify redirects a failed link here with
+ * `?error=<code>`. Expired / used / account-gone map to the expired copy;
+ * anything else to the generic failure. Never the value itself.
+ */
+const EXPIRED_LINK_ERRORS: ReadonlySet<string> = new Set([
+  "INVALID_TOKEN",
+  "new_user_signup_disabled",
+]);
+
+function linkNoticeFor(
+  error: string | string[] | undefined,
+  text: SignInCardText,
+): string | undefined {
+  if (error === undefined) return undefined;
+  const code = Array.isArray(error) ? error[0] : error;
+  return code !== undefined && EXPIRED_LINK_ERRORS.has(code)
+    ? text.emailLinkExpired
+    : text.errorLabels.signInFailed;
 }
 
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
@@ -46,7 +72,8 @@ export default async function SignInPage({
   searchParams,
 }: Props): Promise<ReactElement> {
   const { locale } = await params;
-  const t = await getTranslations({ locale, namespace: "signIn" });
+  const { next: rawNext, error } = await searchParams;
+  const text = await resolveSignInCardText(locale);
 
   const active = getActiveProviderIds();
   // Exactly the OAuth providers auth-env reports — never a default set.
@@ -54,23 +81,12 @@ export default async function SignInPage({
     (id): id is SignInProvider => id === "google" || id === "github",
   );
   const method = active.includes("email") ? "password" : "sso";
-  const next = resolveNextPath(
-    (await searchParams).next,
-    localeHref(locale, "/account"),
-  );
-
-  const labels: AuthCardLabels = {
-    signInHeading: t("heading"),
-    signInSubhead: t("subhead"),
-    ssoPrefix: t("ssoPrefix"),
-    google: t("google"),
-    github: t("github"),
-    email: t("email"),
-    password: t("password"),
-    forgot: t("forgot"),
-    signInSubmit: t("submit"),
-    orContinue: t("orContinue"),
-  };
+  const emailLink = active.includes("magic-link");
+  const next = resolveNextPath(rawNext, localeHref(locale, "/account"));
+  // A failed link returns here, keeping the visitor's destination.
+  const signInHref = `${localeHref(locale, "/sign-in")}?next=${encodeURIComponent(next)}`;
+  // Only the email link produces `?error=` here; with it off, today's render.
+  const linkNotice = emailLink ? linkNoticeFor(error, text) : undefined;
 
   return (
     <SignInCard
@@ -86,12 +102,14 @@ export default async function SignInPage({
       // send conjunction, so the flag alone would offer a link to a page
       // rendering its own not-available card (#6068 AC-2).
       forgot={resetSendConfigured() ? "link" : "none"}
-      labels={labels}
-      notConfiguredSubhead={t("notConfiguredSubhead")}
-      errorLabels={{
-        signInFailed: t("signInFailed"),
-        providerFailed: t("providerFailed"),
-      }}
+      labels={text.labels}
+      notConfiguredSubhead={text.notConfiguredSubhead}
+      errorLabels={text.errorLabels}
+      emailLink={emailLink}
+      errorCallbackURL={signInHref}
+      signInHref={signInHref}
+      {...(linkNotice !== undefined ? { linkNotice } : {})}
+      emailLinkLabels={text.emailLinkLabels}
     />
   );
 }

package/templates/apps/web/app/[locale]/(auth)/sign-in/sign-in-card.tsx

@@ -1,4 +1,4 @@
-"use client"; // Better Auth's client calls (signIn.social / signIn.email) + error state
+"use client"; // Better Auth's client calls (signIn.social / signIn.email / $fetch) + error state
 
 /**
  * SignInCard — the /sign-in page's client island (#4984).
@@ -36,6 +36,15 @@
  * `forgot` (#6018 AC-1): the page passes `forgot="none"` when
  * `isResetAvailable()` is false, so the "Forgot password?" link never renders
  * a dead end — AuthCard's own default (`"link"`) assumes reset is wired.
+ *
+ * Email sign-in link (#7435 § D8): with `emailLink` true the card adds
+ * AuthCard's `emailLink="form"` and POSTs the typed address to Better Auth's
+ * `/sign-in/magic-link` through the shared client's `$fetch` — not the
+ * `magicLinkClient()` plugin, so no ESM-only module enters the client graph
+ * every `(auth)` and `(authed)` suite would then have to mock. The answer is
+ * the same for an address with and without an account, so a success swaps to
+ * a sent state that never names the address. The gate composes this card too
+ * (`(authed)/sign-in-gate.tsx`).
  */
 
 import {
@@ -44,13 +53,25 @@ import {
   type AuthSubmitData,
 } from "@working-theory/ui/blocks";
 import { Alert, AlertDescription } from "@working-theory/ui/primitives";
-import type { ReactElement } from "react";
+import { useRef, useState, type ReactElement } from "react";
 
 import { authClient, useAuthCardFlow } from "../use-auth-card-flow";
 
 /** The OAuth providers this page can launch — a subset of AuthCard's. */
 export type SignInProvider = "google" | "github";
 
+/** Translated copy for the email sign-in link flow (#7435 § D10). */
+export interface SignInEmailLinkLabels {
+  sentHeading: string;
+  sentSubhead: string;
+  sentBody: string;
+  backToSignIn: string;
+  /** Any failed request other than a rate limit. */
+  failed: string;
+  /** A 429 from Better Auth's per-IP limit. */
+  rateLimited: string;
+}
+
 export interface SignInCardProps {
   /** Active OAuth providers, exactly as auth-env reports them. */
   providers: SignInProvider[];
@@ -68,6 +89,15 @@ export interface SignInCardProps {
   notConfiguredSubhead: string;
   /** Translated error copy. */
   errorLabels: { signInFailed: string; providerFailed: string };
+  /** Offer "Email me a sign-in link" — `getActiveProviderIds()` has "magic-link". */
+  emailLink: boolean;
+  /** Where a failed link lands (`/sign-in?next=…`); Better Auth appends `?error`. */
+  errorCallbackURL: string;
+  /** The sent state's "Back to sign in" link. */
+  signInHref: string;
+  /** Fixed copy for a failed link (`?error=` mapped by the page), shown above the card. */
+  linkNotice?: string;
+  emailLinkLabels: SignInEmailLinkLabels;
 }
 
 export function SignInCard({
@@ -79,14 +109,25 @@ export function SignInCard({
   labels,
   notConfiguredSubhead,
   errorLabels,
+  emailLink,
+  errorCallbackURL,
+  signInHref,
+  linkNotice,
+  emailLinkLabels,
 }: SignInCardProps): ReactElement {
   const { errors, providerError, launchProvider, submitPassword } =
     useAuthCardFlow(next, {
       providerFailed: errorLabels.providerFailed,
       passwordFailed: errorLabels.signInFailed,
     });
+  const [emailLinkSent, setEmailLinkSent] = useState(false);
+  const [emailLinkError, setEmailLinkError] = useState<string | null>(null);
+  // One request at a time: a double-click would spend two of the per-IP and
+  // per-address sends and mint two live tokens (code review).
+  const emailLinkPending = useRef(false);
 
-  const notConfigured = method === "sso" && providers.length === 0;
+  const notConfigured =
+    method === "sso" && providers.length === 0 && !emailLink;
 
   const providerButtons = providers.map((provider) => ({
     provider,
@@ -103,6 +144,52 @@ export function SignInCard({
     );
   };
 
+  const requestEmailLink = async (email: string): Promise<void> => {
+    if (emailLinkPending.current) return;
+    emailLinkPending.current = true;
+    setEmailLinkError(null);
+    try {
+      const { error } = await authClient.$fetch("/sign-in/magic-link", {
+        method: "POST",
+        body: { email, callbackURL: next, errorCallbackURL },
+      });
+      if (!error) {
+        setEmailLinkSent(true);
+        return;
+      }
+      setEmailLinkError(
+        error.status === 429
+          ? emailLinkLabels.rateLimited
+          : emailLinkLabels.failed,
+      );
+    } catch {
+      setEmailLinkError(emailLinkLabels.failed);
+    } finally {
+      emailLinkPending.current = false;
+    }
+  };
+
+  if (emailLinkSent) {
+    // Every string passed in, so no AuthCard English default — whose "Follow
+    // the link we just sent" would contradict the neutral copy — renders. No
+    // `sentTo`: the state must not confirm the address has an account.
+    return (
+      <div className="flex flex-col gap-4" data-testid="sign-in-page">
+        <AuthCard
+          intent="sent"
+          footer="cross-link"
+          signInHref={signInHref}
+          labels={{
+            sentHeading: emailLinkLabels.sentHeading,
+            sentSubhead: emailLinkLabels.sentSubhead,
+            sentBody: emailLinkLabels.sentBody,
+            backToSignIn: emailLinkLabels.backToSignIn,
+          }}
+        />
+      </div>
+    );
+  }
+
   return (
     /*
      * No page framing of its own (#5963): AuthShell owns the brand row, the
@@ -116,6 +203,11 @@ export function SignInCard({
           <AlertDescription>{providerError}</AlertDescription>
         </Alert>
       ) : null}
+      {linkNotice ? (
+        <Alert variant="error" data-testid="sign-in-link-notice">
+          <AlertDescription>{linkNotice}</AlertDescription>
+        </Alert>
+      ) : null}
       <AuthCard
         intent="sign-in"
         method={method}
@@ -125,8 +217,16 @@ export function SignInCard({
         {...(notConfigured ? { subhead: notConfiguredSubhead } : {})}
         providers={providerButtons}
         onSubmit={handleSubmit}
-        errors={errors}
+        errors={
+          emailLinkError ? { ...errors, emailLink: emailLinkError } : errors
+        }
         labels={labels}
+        {...(emailLink
+          ? {
+              emailLink: "form" as const,
+              onEmailLink: (email: string) => void requestEmailLink(email),
+            }
+          : {})}
       />
     </div>
   );