create-ailk 0.5.0 → 0.6.0

package/templates/apps/mcp/src/tools/purchase.ts

@@ -1,92 +1,175 @@
 /**
  * AGENT TOOL — purchase (`start_purchase`)
  *
- * DISABLED AT OSS CATALOG (S15a, 2026-05-12, issue #610).
+ * Starts a purchase for a named offering and returns a **Stripe-hosted
+ * Checkout URL**. Nothing is charged here: the tool builds the payload the
+ * HTTP twin `POST /v1/checkout/sessions` validates, and the buyer completes
+ * payment on Stripe's own page. That hosted handoff is the money boundary
+ * `.claude/rules/vocabulary.md` § Commerce requires — no card data reaches
+ * us, and we are not a Stripe Connect platform.
  *
- * The implementation below is preserved for the eventual Phase 3 re-enable.
- * The MCP catalog at `packages/metadata/src/mcp-tool-catalog.ts` filters this
- * tool out via `OSS_DISABLED_TOOLS`, and `apps/mcp/src/server.ts` applies the
- * same filter defensively so neither the discovery manifest nor the running
- * server advertises it.
+ * VISIBILITY — the commerce add-on claim (#5971, superseding S15a/#610).
+ * This tool carries `addon: "commerce"` in the catalog, and since #5971 that
+ * marker is its visibility gate: it reaches neither the discovery manifest
+ * nor the running server's tool list unless the deployment positively holds
+ * the `commerce` licence claim. Two gates enforce that, deliberately:
  *
- * Re-enablement requires the Phase 3 criteria documented at
- * `docs/internal/roadmaps/phase-3-readiness.md`:
+ *   1. REGISTRATION — `shouldRegister()` in `../server.js` drops the entry.
+ *   2. CALL TIME — the first statement below re-reads the claim.
  *
- *   1. Identity verification confirmed at session level
- *   2. Payment-authorization handshake with Stripe Connect (or equivalent)
- *   3. Threat-model entry M_purchase reclassified from "Disabled" to
- *      "Remediated"
- *   4. Commercial-tier flag gating registered to allow re-enable only on
- *      Pro / Agencies
+ * Gate 2 is not redundant. The HTTP transport's stateless mode builds a fresh
+ * `McpServer` per request, so the gate must be re-read rather than captured;
+ * `ailkPurchase` is an exported function a scaffold or a test can call
+ * directly, bypassing registration entirely; and it gives "calling it by name
+ * on a keyless site" a deterministic, asserted body rather than whatever the
+ * SDK emits for an unregistered name. That body is `notFoundError("Not
+ * found")` — the MCP twin of the checkout route's own
+ * `commerceDisabledResponse()`, same code, same message, no hint that a
+ * licence exists.
  *
- * To re-enable: remove `"start_purchase"` from `OSS_DISABLED_TOOLS` in
- * `packages/metadata/src/mcp-tool-catalog.ts`. The regression tests at
- * `apps/mcp/__tests__/purchase-disabled.test.ts` and
- * `packages/metadata/__tests__/purchase-not-in-catalog.test.ts` will fail
- * loudly, forcing a deliberate review against the criteria above.
+ * REDIRECTS — never caller-supplied on this surface (#6001). An anonymous
+ * caller has no way to prove it controls a redirect target, so
+ * `successUrl` / `cancelUrl` are ALWAYS derived from `AILK_BASE_URL` below,
+ * never accepted from the input, and `allowPromotionCodes` is never accepted
+ * either. This function's own gate is `purchaseMcpInputSchema` — a
+ * `.strict()` `.pick()` of the shared `purchaseInputSchema` exposing exactly
+ * `productCode` + `quantity` — so a DIRECT call to `ailkPurchase` (the
+ * surface this file's own tests exercise, per the note above) carrying any
+ * of the three fails validation outright. A call through the registered SDK
+ * transport has them stripped one layer earlier, by the SDK's own arg parse
+ * against the registered shape, before this function ever runs — they are
+ * simply not part of that shape. Either path is safe: the payload built
+ * below can never carry a caller-supplied redirect. The shared
+ * `purchaseInputSchema` (and the Server Action / API route that use it) is
+ * unaffected: those are not anonymous surfaces and keep accepting a
+ * caller-supplied redirect.
  *
- * --- Original Phase 3 U2 implementation notes ---
+ * The file stays in the BASE tree and is never added to
+ * `MODULE_SLICES.commerce.ownedFiles`: `../server.js` statically imports
+ * `ailkPurchase`, so a slice that deleted it from a keyless scaffold would
+ * produce `ERR_MODULE_NOT_FOUND` inside the server bootstrap. A keyless
+ * scaffold carries the file and registers nothing — exactly how it already
+ * carries `apps/api/src/routes/checkout/sessions.ts`.
  *
- * Proxies POST /api/checkout/sessions and returns the Stripe hosted-checkout
- * URL. Paired with the `purchaseAction` Server Action in apps/web per ADR 0013.
+ * Schemas live in `@working-theory/validation` per ADR 0013. Network calls go
+ * through `@working-theory/api-client` per the architecture invariants (apps
+ * may not import each other; the shared HTTP surface lives in packages/).
  *
- * Schemas live in `@working-theory/validation` per ADR 0013.
- * Network calls go through `@working-theory/api-client` per architecture invariants
- * (apps may not import from each other; shared HTTP surface lives in packages/).
+ * Spec: `docs/specs/5971-start-purchase-hosted-checkout-spec.md`.
  */
 
 import { checkout } from "@working-theory/api-client";
 import {
-  purchaseInputSchema,
-  type PurchaseInput,
+  purchaseMcpInputSchema,
+  type PurchaseMcpInput,
   type PurchaseOutput,
 } from "@working-theory/validation";
 
+import { mcpCommerceClaim } from "../lib/commerce-claim.js";
+import {
+  notFoundError,
+  validationError,
+  type ErrorBody,
+} from "../lib/errors.js";
+
+/**
+ * The module-disabled body. Identical to what a build without commerce
+ * produces and to the checkout route's own `commerceDisabledResponse()` —
+ * it must not leak that a licence gate is what answered.
+ */
+function commerceDisabledBody(): ErrorBody {
+  return notFoundError("Not found");
+}
+
 /**
  * Export name `ailkPurchase` satisfies the parity-test naming convention
  * (ailk<PascalVerb>) so the harness can discover it.
  *
- * Paired with `purchaseAction` Server Action in apps/web/app/dev/purchase/.
+ * Paired with `purchaseAction` Server Action in
+ * apps/web/app/[locale]/dev/purchase/.
+ *
+ * Returns a typed error BODY rather than throwing on every failure an agent
+ * can act on (FR-2) — MCP tools surface errors as their result body, the
+ * pattern `lib/require-paid-tier.ts` already establishes.
  */
 export async function ailkPurchase(
-  input: PurchaseInput,
-): Promise<PurchaseOutput> {
-  // Validate input before any side effect (security requirement).
-  purchaseInputSchema.parse(input);
+  input: PurchaseMcpInput,
+): Promise<PurchaseOutput | ErrorBody> {
+  // Gate 2 — call time. Before validation, before any side effect.
+  if (mcpCommerceClaim() !== "claimed") {
+    return commerceDisabledBody();
+  }
+
+  // Validate input before any side effect (security requirement). Strict
+  // (#6001): a DIRECT call carrying successUrl, cancelUrl or
+  // allowPromotionCodes fails here — this function never accepts a
+  // caller-supplied redirect. (A call through the registered SDK transport
+  // never reaches this line with those fields present at all — see the
+  // REDIRECTS note above.) Every field this schema DOES accept mirrors the
+  // route's own validation (spec D5), so an input this accepts is an input
+  // the route accepts.
+  const parsed = purchaseMcpInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return validationError("Invalid start_purchase input", {
+      issues: parsed.error.issues.map((issue) => ({
+        path: issue.path as (string | number)[],
+        message: issue.message,
+      })),
+    });
+  }
 
   const baseUrl =
     process.env.AILK_BASE_URL ||
     process.env.NEXT_PUBLIC_BASE_URL ||
     "http://localhost:3000";
 
-  const successUrl =
-    input.successUrl ?? `${baseUrl}/purchase/success`;
-  const cancelUrl =
-    input.cancelUrl ?? `${baseUrl}/purchase/cancel`;
+  const { productCode, quantity } = parsed.data;
 
+  // successUrl/cancelUrl are ALWAYS derived from baseUrl (#6001) — never
+  // accepted from the caller. allowPromotionCodes is never forwarded: it is
+  // not part of purchaseMcpInputSchema, so it can never be present here.
+  //
+  // #6084 D1 — `successUrl` carries Stripe's own `{CHECKOUT_SESSION_ID}`
+  // template token, substituted into the redirect at completion time. This
+  // is what lets `/purchase/success` read the session back (D1). `cancelUrl`
+  // deliberately carries NO template: that page reads nothing (D4), and
+  // Stripe's substitution contract is documented for `success_url` only.
   const result = await checkout.createSession({
-    productCode: input.priceId,
-    ...(input.quantity !== undefined && { quantity: input.quantity }),
-    successUrl,
-    cancelUrl,
-    ...(input.allowPromotionCodes !== undefined && {
-      allowPromotionCodes: input.allowPromotionCodes,
-    }),
+    productCode,
+    ...(quantity !== undefined && { quantity }),
+    successUrl: `${baseUrl}/purchase/success?session_id={CHECKOUT_SESSION_ID}`,
+    cancelUrl: `${baseUrl}/purchase/cancel`,
   });
 
   if (!result.ok) {
-    throw new Error(
-      `checkout-unavailable: POST /api/checkout/sessions returned ${result.status}`,
+    // An unknown offering is the route's 404 `unknown-product-code`, and
+    // `packages/stripe-client` throws it BEFORE `stripe.checkout.sessions
+    // .create` — so no Checkout Session exists (FR-2).
+    if (result.status === 404) {
+      // Deliberately does NOT echo the caller's productCode. The HTTP twin
+      // states and tests that invariant ("Error responses never echo user
+      // input", apps/api/src/routes/checkout/sessions.ts), and parity means
+      // the pair answers alike.
+      return notFoundError("No offering matches that product code.");
+    }
+    return validationError(
+      `checkout-unavailable: POST /v1/checkout/sessions returned ${result.status}`,
+      { status: result.status },
     );
   }
 
+  // Only `url` is surfaced. The route's `sessionId` is deliberately withheld:
+  // an anonymous agent has no use for it and it is the one field that
+  // identifies a specific buyer's session (spec D5).
   return { url: result.body.url };
 }
 
 // Re-export schemas/types from @working-theory/validation for barrel consumers.
 export {
   purchaseInputSchema,
+  purchaseMcpInputSchema,
   purchaseOutputSchema,
   type PurchaseInput,
+  type PurchaseMcpInput,
   type PurchaseOutput,
 } from "@working-theory/validation";

package/templates/apps/mcp/src/tools/read_content.ts

@@ -1,7 +1,10 @@
 /**
  * read_content — returns a single page's frontmatter + raw MDX body.
  *
- * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Pure read: resolves its adapter through `getMcpMdxContentAdapter()` — the
+ * MDX-narrowed twin of the one resolver seam (#5805, ADR 0011; needed here
+ * for `getPageSource()`'s raw body, which the base `ContentAdapter` contract
+ * doesn't carry), MDX by default.
  * Composes getPageBySlug (frontmatter) + getPageSource (body) into a single
  * output shape. Returns null when the slug is not found — never throws for
  * a missing page.
@@ -10,14 +13,15 @@
  * allowlist; invalid or unknown values silently fall back to the project's
  * default locale (AC-i18n-07). The adapter applies its own fallback chain.
  *
- * Input:  { type: SchemaOrgType, slug: string, locale?: string }
+ * Input:  { type: SchemaOrgType, slug: string, locale?: string } — `type`
+ *         admits the full SchemaOrgType set (#6030 D1), mirrored in
+ *         @working-theory/validation's MCP_SCHEMA_ORG_TYPES.
  * Output: { slug, type, frontmatter, body } | null
  * Session/scope: none — read-only public content.
  */
 
 import { join } from "node:path";
 
-import { createMdxAdapter } from "@working-theory/content-adapters";
 import {
   readContentInputSchema,
   readContentOutputSchema,
@@ -25,6 +29,7 @@ import {
   type ReadContentOutput,
 } from "@working-theory/validation";
 
+import { getMcpMdxContentAdapter } from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { readContentInputSchema, readContentOutputSchema };
@@ -47,14 +52,23 @@ export async function ailkReadContent(
   const root = contentRoot ?? join(process.cwd(), "content");
   const locale = resolveLocale(input.locale);
 
-  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+  const adapter = getMcpMdxContentAdapter({ contentRoot: root, locale });
 
   const source = await adapter.getPageSource(input.type, input.slug, locale);
   if (source === null) return null;
 
   return readContentOutputSchema.parse({
-    slug: source.frontmatter.slug,
-    type: source.frontmatter.type,
+    // Prefer the stored frontmatter's slug/type; fall back to the
+    // request-validated input (#5876 spec D9). On the MDX path the
+    // frontmatter always carries both — required, non-optional fields of
+    // FrontmatterSchema — so this is inert there and the mdx payload stays
+    // byte-identical. The fallback matters for cross-adapter identity: the
+    // Epic #5324 AC-WCE-04 comparison needs `read_content`'s payload to be
+    // identical across adapters, which a request-validated value guarantees
+    // and a stored-bookkeeping value only guarantees if the write path
+    // agrees.
+    slug: source.frontmatter.slug ?? input.slug,
+    type: source.frontmatter.type ?? input.type,
     frontmatter: source.frontmatter as Record<string, unknown>,
     body: source.body,
   });

package/templates/apps/mcp/src/tools/search_content.ts

@@ -1,7 +1,8 @@
 /**
  * search_content — full-text search across published content pages.
  *
- * Pure read: imports the MDX adapter from @working-theory/content-adapters (ADR 0011).
+ * Pure read: resolves its adapter through `getMcpContentAdapter()` — the one
+ * resolver seam (#5805, ADR 0011), MDX by default.
  * Delegates to adapter.searchPages which scores by title/description/body match.
  * Limit defaults to 10; max 50. Query capped at 200 chars (enforced by Zod).
  *
@@ -9,14 +10,18 @@
  * requested locale's content directory is searched. Invalid or unknown values
  * silently fall back to the project's default locale (AC-i18n-07).
  *
- * Input:  { query: string, type?: SchemaOrgType, limit?: number, locale?: string }
+ * #5831: optional `category` parameter — a leaf slug from the site-category
+ * registry. Unlike `locale`, an unrecognised value is a validation error, not
+ * a silent fallback: the registry is closed, so a bad slug is a caller mistake.
+ *
+ * Input:  { query: string, type?: SchemaOrgType, category?: CategorySlug,
+ *           limit?: number, locale?: string }
  * Output: { results: Array<{ slug, type, title, snippet, score }> }
  * Session/scope: none — read-only public content.
  */
 
 import { join } from "node:path";
 
-import { createMdxAdapter } from "@working-theory/content-adapters";
 import {
   searchContentInputSchema,
   searchContentOutputSchema,
@@ -24,6 +29,7 @@ import {
   type SearchContentOutput,
 } from "@working-theory/validation";
 
+import { getMcpContentAdapter } from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { searchContentInputSchema, searchContentOutputSchema };
@@ -45,11 +51,12 @@ export async function ailkSearchContent(
 
   const root = contentRoot ?? join(process.cwd(), "content");
   const locale = resolveLocale(input.locale);
-  const adapter = createMdxAdapter({ contentRoot: root, defaultLocale: locale });
+  const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 
   const options = {
     limit: input.limit ?? DEFAULT_LIMIT,
     ...(input.type !== undefined && { type: input.type }),
+    ...(input.category !== undefined && { category: input.category }),
     locale,
   };
 

package/templates/apps/web/.env.example

@@ -5,16 +5,25 @@
 # overrides apps/web reads at runtime.
 
 # =============================================================================
-# Content backend
+# Content adapter
 # =============================================================================
 # Which content adapter apps/web uses.
 #   mdx             — reads /content/<Type>/<slug>.mdx (default)
-#   pro-cms         — separate adapter, not bundled with the OSS template
-CONTENT_BACKEND=mdx
+#   projection      — compiled build-time manifest
+#   database        — the Artifact store (needs a workspaceId)
+CONTENT_ADAPTER=mdx
+# CONTENT_BACKEND is deprecated — read for one release, then removed.
 
 # Override the on-disk content root. Defaults to <repo-root>/content.
 # AILK_CONTENT_ROOT=
 
+# The shared secret /api/revalidate verifies apps/api's publish webhook
+# against — the SAME value as the API's CONTENT_REVALIDATE_SECRET (#5877).
+# Needed when CONTENT_ADAPTER=database. Unset means the route returns 503 and
+# the site is not push-revalidated: a publish changes nothing user-visible
+# until a rebuild.
+# CONTENT_REVALIDATE_SECRET=
+
 # =============================================================================
 # apps/api base URL (browser-side lead-capture forms) — #3965
 # =============================================================================
@@ -46,9 +55,22 @@ CONTENT_BACKEND=mdx
 # =============================================================================
 # Better Auth (apps/web)
 # =============================================================================
-# Base URL Better Auth uses for OAuth callback construction.
+# Base URL Better Auth uses for OAuth callback construction — and, since #5962,
+# the ORIGIN the password-reset link is built on and the sole member of the
+# trustedOrigins allow-list.
+#
+# REQUIRED for password reset, and not as a convenience: with this unset Better
+# Auth recomputes both the base URL and the allow-list PER REQUEST from the
+# request itself, so `Host: evil.tld` plus `redirectTo: https://evil.tld/x`
+# passes its own origin check and the emailed reset link is built on the
+# attacker's host. It is a conjunct of resetSendConfigured(), so a deployment
+# that has not pinned its origin does not offer reset at all.
 # BETTER_AUTH_URL=http://localhost:3000
-# Secret used to sign session cookies. REQUIRED in production.
+#
+# Secret used to sign session cookies AND the email-verification tokens.
+# REQUIRED in production: apps/web/auth.ts now THROWS at boot without it rather
+# than falling back to a development string that is published in this
+# repository. Also a conjunct of resetSendConfigured().
 # BETTER_AUTH_SECRET=
 #
 # OAuth provider env vars — set both id + secret to activate a provider.
@@ -57,6 +79,50 @@ CONTENT_BACKEND=mdx
 # GOOGLE_CLIENT_SECRET=
 # GITHUB_CLIENT_ID=
 # GITHUB_CLIENT_SECRET=
+#
+# Auth-surface flags (#5963) — what the (auth) pages OFFER, read through
+# apps/web/lib/auth-env.ts. Both default OFF, which is what a scaffold is:
+# auth.ts does not enable emailAndPassword, so there is no public sign-up and
+# no password-reset flow to advertise. Set to "1" or "true" once the
+# server-side flow is wired.
+# Open public sign-up: /sign-up renders the form instead of the invitation copy.
+# AILK_AUTH_SIGNUP_OPEN=
+# Password reset available: /forgot-password and /reset-password render their
+# forms instead of the not-available state.
+# AILK_AUTH_PASSWORD_RESET=
+#
+# -----------------------------------------------------------------------------
+# Password reset — the server-side flow (#5962)
+# -----------------------------------------------------------------------------
+# Shared secret for the signed hop to apps/api's /v1/auth/transactional-email,
+# which is what actually sends auth mail: architecture.yaml forbids apps/web
+# from importing packages/email, so apps/web signs a body and POSTs it. Must
+# match AUTH_EMAIL_WEBHOOK_SECRET on the apps/api deployment. Deployment-only —
+# never NEXT_PUBLIC_, and never committed.
+#
+# Reset is offered only when ALL FIVE of these hold — AILK_AUTH_PASSWORD_RESET,
+# the password method (AUTH_EMAIL_SERVER + AUTH_EMAIL_FROM), this secret plus
+# AUTH_EMAIL_FROM, BETTER_AUTH_URL, and BETTER_AUTH_SECRET. Fail closed: a site
+# must never tell a visitor "check your email" for mail nothing can send.
+# AUTH_EMAIL_WEBHOOK_SECRET=
+#
+# Comma-separated CIDRs of YOUR edge/proxy, for Better Auth's rate-limit IP key.
+#
+# Unset is the honest default — this repo cannot know your deployment's edge
+# topology — but read both failure modes before leaving it that way:
+#
+#   * Multi-hop X-Forwarded-For with this UNSET: Better Auth resolves the
+#     client IP to null and every caller collapses into ONE SHARED BUCKET for
+#     the whole deployment (keyed on the constant "no-trusted-ip"). Because a
+#     shared bucket turns a long window into a site-wide lockout anyone can
+#     hold open, apps/web does NOT apply its widened reset windows in this
+#     state — it falls through to Better Auth's own defaults for those paths
+#     (60 s / 3) so an outage recovers by itself. Set this variable to get the
+#     stricter per-caller limits (5 per 900 s on the reset request).
+#   * Single-hop X-Forwarded-For with this UNSET: the client's own header is
+#     trusted, so an attacker mints a fresh rate-limit bucket per request.
+#
+# AILK_AUTH_TRUSTED_PROXIES=
 
 # =============================================================================
 # Observability

package/templates/apps/web/CLAUDE.md

@@ -66,6 +66,50 @@ Don't ship a page after one render. The expected per-page loop:
    - Fix mismatches. Be specific in self-review: "heading is 32px, reference shows 24px", not "looks off."
    - Repeat until no visible differences and no responsive issues at any of the four breakpoints.
 
+## The `(auth)` route group — which predicate an affordance keys on
+
+`lib/auth-env.ts` exports two reset predicates, and they are not
+interchangeable. Picking the wrong one is how this surface has broken twice
+(#6018, then #6061 — the follow-up #6068 documents the rule here so there is
+no third time).
+
+| Predicate | Question it answers | Keys |
+| --- | --- | --- |
+| `isResetAvailable()` | *Does the operator INTEND to offer reset?* — the `AILK_AUTH_PASSWORD_RESET` flag, alone | nothing user-visible |
+| `resetSendConfigured()` | *Can this deployment actually COMPLETE a reset?* — that flag AND the password method AND a send seam AND `BETTER_AUTH_URL` AND `BETTER_AUTH_SECRET` | every user-visible reset affordance |
+
+**The rule: every user-visible reset affordance keys on
+`resetSendConfigured()`.** That is the `/forgot-password` and `/reset-password`
+page branches, the "Forgot password?" link on `/sign-in`, and anything added
+later that offers a visitor a reset step. The flag alone is a real deployment
+state — intent set, transport missing — and a flag-keyed affordance in that
+state is a link to a page that renders its own not-available card, or a form
+whose only possible outcome is the error state. Whether an affordance is a link
+or a whole page makes no difference to the rule.
+
+**Server callbacks are not affordances, and one is deliberately outside the
+predicate.** `sendResetPassword` IS gated — a defined callback under a page
+that denies the flow exists would be a live anonymous mail-sending surface.
+`auth.ts`'s `onPasswordReset` is NOT, and must stay that way: Better Auth
+registers the `/reset-password` POST on `emailAndPassword.enabled`, so a token
+minted before an operator removed a conjunct stays consumable for its whole
+hour, and gating the callback would make exactly those resets the ones that
+skip sibling-token invalidation and the password-changed notice. Offering a
+step is predicated; cleaning up after one that already happened is not.
+
+**Anything `onPasswordReset` calls must not be able to reject it.** It runs
+AFTER the password has changed and the presented token has been consumed, so a
+rejection is not a failed reset — it is a 500 shown to someone whose password
+DID change, over a token they cannot retry with. Both halves of that callback
+are guarded at the call site, and `lib/auth-email.ts` guards its own signing
+and transport steps (#6068).
+
+**Mocking `lib/auth-env` in a test?** The suites under `(auth)` use PARTIAL
+module mocks, so a member the factory omits is `undefined` rather than the real
+function — the page under test throws instead of taking a branch. Declare
+every predicate the pages call, binding the two reset ones to the same
+`jest.fn()` when the case does not need them to disagree.
+
 ## Conversational intake (contact page)
 
 The contact page (`apps/web/app/[locale]/contact/`) consumes

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

@@ -16,7 +16,10 @@
  * default) instead of a hardcoded vendor-brand literal.
  */
 
-import { getMcpToolCatalog, type McpToolCatalogEntry } from "@working-theory/metadata";
+import {
+  getMcpToolCatalog,
+  type McpToolCatalogEntry,
+} from "@working-theory/metadata";
 
 import { SITE_NAME } from "../../../lib/site-brand";
 
@@ -74,6 +77,17 @@ export interface BuildMcpManifestOptions {
    * Typically sourced from the MCP_PUBLIC_HTTP_URL env var in the web app.
    */
   mcpHttpUrl?: string;
+  /**
+   * Whether this deployment holds the `commerce` add-on licence claim
+   * (#5971). Add-on-gated tools — today only `start_purchase` — are advertised
+   * only when it does, so the discovery manifest and the running MCP server
+   * agree about what this site offers.
+   *
+   * Injected rather than resolved here: this builder is PURE (same input →
+   * same output), a property its own suite asserts. `route.ts` resolves the
+   * claim and passes it in. Omitted ⇒ false, the fail-closed default.
+   */
+  commerceClaimed?: boolean;
 }
 
 /** Path the MCP server is mounted at, relative to baseUrl. */
@@ -105,7 +119,9 @@ export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
     description:
       "AX-first OSS template — ship software with API + MCP as canonical agent surfaces.",
     mcpEndpoint: `${opts.baseUrl}${MCP_ENDPOINT_PATH}`,
-    tools: getMcpToolCatalog(),
+    tools: getMcpToolCatalog({
+      addons: { commerce: opts.commerceClaimed === true },
+    }),
     transport: {
       type: "http",
       version: MCP_HTTP_VERSION,

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

@@ -5,8 +5,14 @@
  * URL, and discover the MCP endpoint + tool catalog without out-of-band
  * coordination. Issue #209 (initial), #300 (moved to correct URL + CORS).
  *
- * Pure assembly — no fetch(). The catalog is read in-process from
- * @working-theory/metadata; the AILK version is read from this app's package.json.
+ * Assembly — no fetch(). The catalog is read in-process from
+ * @working-theory/metadata; the AILK version is read from this app's
+ * package.json; the `commerce` add-on claim is read locally through
+ * `checkLicense()` (#5971) so an add-on-gated tool is advertised on exactly
+ * the deployments whose MCP server registers it. Without that, a KEYED site
+ * would register `start_purchase` while hiding it from its own manifest —
+ * the surface disagreement `apps/mcp/__tests__/catalog-drift.test.ts` exists
+ * to make impossible.
  *
  * Mirrors /.well-known/ai-plugin.json conventions: Response.json with a
  * conservative cache-control header.
@@ -17,6 +23,7 @@
  */
 
 import packageJson from "../../../package.json";
+import { resolveCommerceClaim } from "../../../src/lib/commerce-claim";
 import { resolveBaseUrl } from "../../../src/lib/routes";
 
 import { buildMcpManifest } from "./build-manifest";
@@ -34,7 +41,7 @@ export function OPTIONS(): Response {
   });
 }
 
-export function GET(): 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.
@@ -43,6 +50,7 @@ export function GET(): Response {
   const manifest = buildMcpManifest({
     baseUrl: resolveBaseUrl(),
     ailkVersion: packageJson.version,
+    commerceClaimed: await resolveCommerceClaim(),
     // Spread conditional to satisfy exactOptionalPropertyTypes: omit the key
     // entirely when the env var is not set rather than passing undefined.
     ...(mcpHttpUrlEnv ? { mcpHttpUrl: mcpHttpUrlEnv } : {}),