create-ailk 0.5.0 → 0.6.0

package/templates/apps/api/src/services/revalidation.ts

@@ -0,0 +1,173 @@
+/**
+ * @file revalidation.ts
+ * @description The signed webhook `apps/api` fires at the site's
+ * `/api/revalidate` on publish and unpublish (#5851, roadmap D6). One POST of
+ * `{ workspaceId, type, slug, locale }` to `CONTENT_REVALIDATE_URL`, signed
+ * HMAC-SHA256 over the exact body bytes with `CONTENT_REVALIDATE_SECRET`.
+ *
+ * Either var absent means "revalidation off": one `warn` and return. Both set
+ * means three bounded attempts (500 ms then 2000 ms backoff, 10 s per-attempt
+ * timeout — 32.5 s worst case), every attempt logged, and a final failure
+ * LOGGED rather than thrown. `notifyRevalidate` never rejects, which is what
+ * lets the publish path `await` it and still always complete.
+ *
+ * PII boundary: log lines carry only
+ * `{ event, workspaceId, type, slug, locale, attempt/attempts, status/lastStatus, errName }`.
+ * Never the secret, never the signature, never a response body, never page
+ * content.
+ *
+ * Nothing calls this yet — the publish/unpublish handlers are a sibling child
+ * of Epic #5323, and the receiver is Epic #5324. This module fixes the wire
+ * contract a receiver implements: method POST; the four-key JSON body;
+ * headers `content-type: application/json`, `x-ailk-revalidate-signature:
+ * sha256=<lowercase hex>` and `x-ailk-revalidate-event: publish | unpublish`.
+ * A receiver verifies by recomputing the HMAC over the RAW request body and
+ * comparing in constant time.
+ */
+import { createHmac } from "node:crypto";
+
+import { createLogger } from "@working-theory/observability";
+
+import { config } from "../config/index.js";
+import { outboundFetch } from "../lib/outbound-http.js";
+
+const log = createLogger({ service: "revalidation" });
+
+const SIGNATURE_HEADER = "x-ailk-revalidate-signature";
+const EVENT_HEADER = "x-ailk-revalidate-event";
+
+/**
+ * Backoff before attempt 2 and attempt 3. Three attempts total, no fourth:
+ * 3 × the wrapper's 10 s timeout plus these two sleeps is 32.5 s worst case,
+ * which fits inside the PRD's 60 s publish-to-live budget.
+ */
+const RETRY_BACKOFF_MS = [500, 2000];
+const MAX_ATTEMPTS = RETRY_BACKOFF_MS.length + 1;
+
+export interface RevalidateTarget {
+  workspaceId: string;
+  type: string;
+  slug: string;
+  locale: string;
+}
+
+export interface RevalidateOptions {
+  event: "publish" | "unpublish";
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 429 and 5xx are worth another attempt. Every other non-2xx is terminal — a
+ * 401 from a wrong secret or a 404 from a wrong path will not succeed on a
+ * second try, and retrying it triples the log noise for a misconfiguration.
+ */
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+/**
+ * Tells the site to revalidate one piece of content. Resolves in every case —
+ * success, exhausted retries, or unconfigured — so an `await` in the publish
+ * path can never fail the publish it follows.
+ */
+export async function notifyRevalidate(
+  target: RevalidateTarget,
+  options: RevalidateOptions,
+): Promise<void> {
+  const url = config.CONTENT_REVALIDATE_URL;
+  const secret = config.CONTENT_REVALIDATE_SECRET;
+
+  // The PII-safe key set every line in this module carries.
+  const base = { event: options.event, ...target };
+
+  if (!url || !secret) {
+    // Signing with an empty key would be worse than skipping: every delivery
+    // would be rejected by the receiver with no local signal.
+    const reason = !url ? "url_unset" : "secret_unset";
+    log.warn({ ...base, reason }, "revalidate.skipped");
+    return;
+  }
+
+  // ONE serialization: this exact string is both signed and sent, so a
+  // key-order or whitespace drift between signer and sender is impossible by
+  // construction.
+  const body = JSON.stringify({
+    workspaceId: target.workspaceId,
+    type: target.type,
+    slug: target.slug,
+    locale: target.locale,
+  });
+  const signature = createHmac("sha256", secret)
+    .update(body, "utf8")
+    .digest("hex");
+
+  let attempt = 0;
+  let lastStatus: number | undefined;
+  let errName: string | undefined;
+
+  while (attempt < MAX_ATTEMPTS) {
+    attempt++;
+    let retryable: boolean;
+
+    try {
+      const res = await outboundFetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          [SIGNATURE_HEADER]: `sha256=${signature}`,
+          [EVENT_HEADER]: options.event,
+        },
+        body,
+        // The SSRF gate is waived deliberately and narrowly: this URL comes
+        // from deployment environment, never from a request body or a
+        // database row. Leaving it on would break local development (the site
+        // is http://localhost:3000) and any single-host deployment.
+        allowPrivate: true,
+      });
+
+      if (res.ok) {
+        log.info({ ...base, attempt, status: res.status }, "revalidate.sent");
+        return;
+      }
+
+      lastStatus = res.status;
+      errName = undefined;
+      retryable = isRetryableStatus(res.status);
+    } catch (err) {
+      lastStatus = undefined;
+      errName = err instanceof Error ? err.name : "UnknownError";
+      retryable = true;
+    }
+
+    log.warn(
+      {
+        ...base,
+        attempt,
+        ...(lastStatus !== undefined && { status: lastStatus }),
+        ...(errName !== undefined && { errName }),
+      },
+      "revalidate.failed",
+    );
+
+    if (!retryable) break;
+
+    // Undefined on the last attempt — the schedule has one entry fewer than
+    // MAX_ATTEMPTS, so running out of backoffs IS the "no fourth attempt" bound.
+    const backoffMs = RETRY_BACKOFF_MS[attempt - 1];
+    if (backoffMs === undefined) break;
+    await sleep(backoffMs);
+  }
+
+  log.error(
+    {
+      ...base,
+      attempts: attempt,
+      ...(lastStatus !== undefined && { lastStatus }),
+      ...(errName !== undefined && { errName }),
+    },
+    "revalidate.failed",
+  );
+}

package/templates/apps/api/src/services/verified-email.ts

@@ -0,0 +1,71 @@
+/**
+ * @file verified-email.ts
+ * @description The one `User {id, email, emailVerified}` read every
+ * email-keyed authorization path in `apps/api` goes through (#5701 D4).
+ *
+ * `emailVerified` is load-bearing wherever this codebase joins an identity to
+ * data by email. An unverified address is an unproven CLAIM to the identity it
+ * names: the operator pin it might match (`services/default-tenant.ts`), the
+ * anonymous Lead rows it would promote (`services/lead-promotion.ts`,
+ * `services/listing-promotion.ts`), the respondent rows it would read back
+ * (`services/waitlist-signups.ts`, `services/flow-checkouts.ts`). Each of
+ * those five sites wrote the same read and the same refusal by hand, and
+ * "the same read, written six times" is exactly the shape that let #3631
+ * ship a sixth one without the check.
+ *
+ * So the read lives here once, the refusal is inside it rather than at the
+ * call site — a service-level invariant, not a caller obligation, which is
+ * what makes it unbypassable by a wrong call site — and callers receive the
+ * email ONLY when `emailVerified === true`. The two refusals stay distinct
+ * (`user_not_found` vs `email_unverified`) because the callers map them to
+ * different outcomes on the wire.
+ *
+ * `select` names exactly the three fields, so nothing else about the User row
+ * is read on an authorization path; `tools/lint-email-authz.ts` is the
+ * mechanical backstop that fails any NEW `prisma.user` read which selects
+ * `email` for a decision and omits `emailVerified`.
+ *
+ * ONE KNOWN IMPRECISION IN THE CALLERS, deliberate and unchanged by this
+ * helper. `User.email` is `@unique` in Postgres, which is byte-exact, while
+ * every caller that compares the address lowercases both sides — so two
+ * distinct rows (`Operator@x.com` and `operator@x.com`) could both satisfy one
+ * comparison. It is not reachable today: `apps/web/auth.ts` configures social
+ * providers only, so the address is provider-asserted and normalized rather
+ * than caller-chosen. It becomes reachable the moment a credential provider is
+ * enabled, and the durable fix is case-insensitive email uniqueness in the
+ * schema (citext, or lowercase-at-write) so "matches" and "is unique" agree.
+ * Matching case-sensitively instead would be worse: it would lock out an
+ * operator who typed their own address with different capitalisation.
+ */
+
+import { prisma } from "../lib/prisma.js";
+
+/** Why a verified-email read refused. Callers map these to their own outcomes. */
+export type VerifiedEmailRefusal = "user_not_found" | "email_unverified";
+
+export type VerifiedEmailResult =
+  | { ok: true; value: { id: string; email: string } }
+  | { ok: false; reason: VerifiedEmailRefusal };
+
+/**
+ * Read the `User` row for `userId` and return its email ONLY when the address
+ * is verified.
+ *
+ * @param userId the authenticated caller's id — never a request-supplied email.
+ * @returns `{ok: true}` with the verified address, or the refusal reason.
+ */
+export async function findVerifiedEmail(
+  userId: string,
+): Promise<VerifiedEmailResult> {
+  const user = await prisma.user.findUnique({
+    where: { id: userId },
+    select: { id: true, email: true, emailVerified: true },
+  });
+  if (!user) {
+    return { ok: false, reason: "user_not_found" };
+  }
+  if (user.emailVerified !== true) {
+    return { ok: false, reason: "email_unverified" };
+  }
+  return { ok: true, value: { id: user.id, email: user.email } };
+}

package/templates/apps/api/src/vercel-handler.ts

@@ -3,19 +3,19 @@
  * This file wraps the Fastify server for Vercel's serverless functions
  */
 
-import type { VercelRequest, VercelResponse } from '@vercel/node';
-import { logger } from '@working-theory/observability';
-import type { InjectOptions } from 'fastify';
+import type { VercelRequest, VercelResponse } from "@vercel/node";
+import { logger } from "@working-theory/observability";
+import type { InjectOptions } from "fastify";
 
-import type { build as buildServer } from './server.js';
+import type { build as buildServer } from "./server.js";
 
 type FastifyServer = Awaited<ReturnType<typeof buildServer>>;
 
 // Import the build function from server
 async function getBuildFunction(): Promise<typeof buildServer> {
   try {
-    const srcModule = await import('./server.js');
-    logger.info('[Vercel Handler] Using server from src/server.js');
+    const srcModule = await import("./server.js");
+    logger.info("[Vercel Handler] Using server from src/server.js");
     return srcModule.build;
   } catch (srcError) {
     logger.error(
@@ -23,9 +23,12 @@ async function getBuildFunction(): Promise<typeof buildServer> {
         err: srcError instanceof Error ? srcError.message : String(srcError),
         stack: srcError instanceof Error ? srcError.stack : undefined,
       },
-      '[Vercel Handler] Failed to import server',
+      "[Vercel Handler] Failed to import server",
+    );
+    throw new Error(
+      `Cannot find server module: ${srcError instanceof Error ? srcError.message : String(srcError)}`,
+      { cause: srcError },
     );
-    throw new Error(`Cannot find server module: ${srcError instanceof Error ? srcError.message : String(srcError)}`, { cause: srcError });
   }
 }
 
@@ -45,30 +48,42 @@ const buildPromise = getBuildFunction();
 let serverPromise: Promise<FastifyServer> | null = null;
 
 async function buildServerInstance(): Promise<FastifyServer> {
-  logger.info('[Vercel Handler] Building server instance...');
+  logger.info("[Vercel Handler] Building server instance...");
   const startTime = Date.now();
 
   try {
     const buildTimeout = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error('Server build timeout after 10s')), 10000);
+      setTimeout(
+        () => reject(new Error("Server build timeout after 10s")),
+        10000,
+      );
     });
 
     const build = await Promise.race([buildPromise, buildTimeout]);
-    logger.info('[Vercel Handler] Build function obtained, creating server...');
+    logger.info("[Vercel Handler] Build function obtained, creating server...");
 
     const initTimeout = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error('Server initialization timeout after 10s')), 10000);
+      setTimeout(
+        () => reject(new Error("Server initialization timeout after 10s")),
+        10000,
+      );
     });
 
     const serverInstance = await Promise.race([build(), initTimeout]);
 
     const buildTime = Date.now() - startTime;
-    logger.info({ buildTime }, '[Vercel Handler] Server built successfully');
+    logger.info({ buildTime }, "[Vercel Handler] Server built successfully");
     return serverInstance;
   } catch (error) {
     const buildTime = Date.now() - startTime;
-    logger.error({ err: error, buildTime }, '[Vercel Handler] Failed to build server');
-    throw new Error(`Server build failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    logger.error(
+      { err: error, buildTime },
+      "[Vercel Handler] Failed to build server",
+    );
+    throw new Error(
+      `Server build failed: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
   }
 }
 
@@ -102,27 +117,46 @@ function getServer(): Promise<FastifyServer> {
  */
 export default async function handler(
   req: VercelRequest,
-  res: VercelResponse
+  res: VercelResponse,
 ): Promise<void> {
   const timeout = setTimeout(() => {
     if (!res.headersSent) {
-      logger.error('[Vercel Handler] Request timeout');
+      logger.error("[Vercel Handler] Request timeout");
       res.status(504).json({
-        error: 'Gateway Timeout',
-        message: 'Request took too long to process',
+        error: "Gateway Timeout",
+        message: "Request took too long to process",
       });
     }
   }, 25000);
 
   try {
-    logger.info({ method: req.method, url: req.url }, '[Vercel Handler] Starting request');
-
-    const server = await getServer();
-
-    const url = new URL(req.url || '/', 'http://localhost');
+    // The PATHNAME, never the raw target (#5970 security review round 2, H1).
+    //
+    // This is the production entry point — `vercel.json` routes every request
+    // here — and it logs BEFORE Fastify's own (query-stripped) "incoming
+    // request" line, so it is the first and last word on what reaches the log
+    // drain. `req.url` is the raw target INCLUDING the query string, and a
+    // route may carry its credential there: `GET
+    // /v1/requests/:id/confirm?token=…` does, because a link in an email has
+    // nowhere else to put one. Logging it wrote a live seven-day credential
+    // into the drain on every open.
+    //
+    // The high-entropy redactor in `@working-theory/observability` is NOT the
+    // control here: it is a probabilistic backstop, and a 43-char base64url
+    // token falls under its entropy threshold often enough to leak in full.
+    // Stripping the query is the control; the redactor stays the backstop.
+    //
+    // Derived once, above the first log line, and used by both — the pathname
+    // was already computed below and logged safely there, three lines too late.
+    const url = new URL(req.url || "/", "http://localhost");
     const pathname = url.pathname;
 
-    logger.info({ method: req.method, pathname }, '[Vercel Handler] Processing request');
+    logger.info(
+      { method: req.method, pathname },
+      "[Vercel Handler] Starting request",
+    );
+
+    const server = await getServer();
 
     // Strip content-length/content-encoding before forwarding. Both
     // describe the ORIGINAL byte stream the client sent; req.body here is
@@ -137,13 +171,16 @@ export default async function handler(
     // incoming header names in practice.
     const forwardedHeaders = { ...req.headers } as Record<string, string>;
     for (const key of Object.keys(forwardedHeaders)) {
-      if (key.toLowerCase() === 'content-length' || key.toLowerCase() === 'content-encoding') {
+      if (
+        key.toLowerCase() === "content-length" ||
+        key.toLowerCase() === "content-encoding"
+      ) {
         delete forwardedHeaders[key];
       }
     }
 
     const fastifyRequest = {
-      method: req.method || 'GET',
+      method: req.method || "GET",
       url: pathname,
       headers: forwardedHeaders,
       body: req.body,
@@ -152,7 +189,10 @@ export default async function handler(
 
     const response = await server.inject(fastifyRequest as InjectOptions);
 
-    logger.info({ status: response.statusCode }, '[Vercel Handler] Response status');
+    logger.info(
+      { status: response.statusCode },
+      "[Vercel Handler] Response status",
+    );
 
     clearTimeout(timeout);
 
@@ -161,14 +201,14 @@ export default async function handler(
     Object.entries(response.headers).forEach(([key, value]) => {
       if (value !== undefined && !res.headersSent) {
         const headerValue = Array.isArray(value)
-          ? value.map((v) => String(v)).join(', ')
+          ? value.map((v) => String(v)).join(", ")
           : String(value);
         res.setHeader(key, headerValue);
       }
     });
 
-    if (!res.getHeader('Content-Type') && !res.headersSent) {
-      res.setHeader('Content-Type', 'application/json');
+    if (!res.getHeader("Content-Type") && !res.headersSent) {
+      res.setHeader("Content-Type", "application/json");
     }
 
     if (!res.headersSent) {
@@ -179,20 +219,20 @@ export default async function handler(
       // `rawPayload` is byte-identical to what Fastify sent regardless of
       // content type, so this also covers the JSON case unchanged.
       res.send(response.rawPayload);
-      logger.info('[Vercel Handler] Response sent successfully');
+      logger.info("[Vercel Handler] Response sent successfully");
     }
   } catch (error) {
     clearTimeout(timeout);
 
-    logger.error({ err: error }, '[Vercel Handler] Error handling request');
+    logger.error({ err: error }, "[Vercel Handler] Error handling request");
 
     if (!res.headersSent) {
       // Generic body only (security review on #146): this catch sits above
       // Fastify's error serializer, so error.message could carry hosts,
       // paths, or driver detail. The logger.error above keeps the detail.
       res.status(500).json({
-        error: 'Internal Server Error',
-        message: 'Something went wrong on our end.',
+        error: "Internal Server Error",
+        message: "Something went wrong on our end.",
       });
     }
   }

package/templates/apps/mcp/.env.example

@@ -53,8 +53,25 @@ MCP_CORS_WRITE_ALLOWED_ORIGINS=
 # Maximum number of capture_lead submissions per IP per day.
 MCP_ABUSE_CAPTURE_LEAD_DAILY_CAP=50
 
+# Maximum number of start_purchase calls per IP per day (#5971). Its own
+# budget, never shared with capture_lead's — each call creates a real Stripe
+# hosted Checkout Session, so the default is deliberately lower.
+MCP_ABUSE_START_PURCHASE_DAILY_CAP=20
+
 # Comma-separated list of User-Agent substrings to block (case-insensitive).
 # Built-in list already blocks curl, wget, python-requests, scrapy, etc.
 # Add extra patterns here as needed.
 # Example: BadBot,EvilCrawler
 MCP_ABUSE_BLOCKED_USER_AGENTS=
+
+# ── Content adapter (#5876) ──────────────────────────────────────────────────────
+
+# Which content adapter every content tool resolves: mdx (default, reads
+# /content/*.mdx at the repo root) | projection (compiled manifest) | database
+# (the Artifact store — the server resolves its own single workspace at
+# bootstrap; a deployment that isn't unambiguously one-workspace serves no
+# content rather than guessing).
+# CONTENT_ADAPTER=mdx
+
+# Required ONLY when CONTENT_ADAPTER=database.
+# DATABASE_URL=

package/templates/apps/mcp/CLAUDE.md

@@ -28,38 +28,67 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 **Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366): identity-blind and free of any `requirePaidTier()` call like every tool in this list, but registered only when the signal-collectors module is present, the same shape Booking below already has
 **Booking (3):** `list_availability`, `get_event_meta`, `create_booking` — module-gated (`module: "scheduling"`)
 
-### Why the catalog reports 23 and the server registers 22
-
-- **23 in the catalog / parity test**: the `TOOLS` array in
-  `packages/metadata/src/mcp-tool-catalog.ts` defines 23 tools; the parity
-  test counts that full catalog.
-- **22 registered at runtime**: `createMcpServer` (`apps/mcp/src/server.ts`)
-  registers `getMcpToolRegistrations()` minus `OSS_DISABLED_TOOLS`, whose only
-  entry is `start_purchase` — so 22 tools are registered on the server.
-- **19 free anonymous tools**: of the 22 registered, three are Pro tools
-  (`create_page`, `update_page`, `delete_page`) gated at call time by
-  `requirePaidTier()`, leaving the 19 free anonymous tools above.
+### Why the parity test counts 20 and a keyless server registers 19
+
+- **20 in the `TOOLS` array / parity test**: the `TOOLS` array in
+  `packages/metadata/src/mcp-tool-catalog.ts` defines 20 tools; the parity
+  test counts that full array.
+- **19 registered on a KEYLESS deployment, 20 on a commerce-claimed one**
+  (#5971): `createMcpServer` (`apps/mcp/src/server.ts`) registers
+  `getMcpToolRegistrations()` minus `OSS_DISABLED_TOOLS` (now empty), minus
+  module-gated tools whose module is off, minus any `addon`-tagged tool whose
+  claim this deployment does not hold. `start_purchase` carries
+  `addon: "commerce"`, so it is the one entry whose presence depends on the
+  licence — 19 without the claim, 20 with it.
+- **19 free anonymous tools**: since #5853 retired the three content-write
+  tools, NO registered tool is gated at call time by `requirePaidTier()`, so
+  every registered tool is free and anonymous. The five carrying `tier: "pro"`
+  (`get_flow`, `submit_flow_step`, `list_availability`, `get_event_meta`,
+  `create_booking`) are MODULE-gated at registration, not payment-gated at
+  call time — the shape the Flow and Booking rows above describe.
   `index.ts` is the transport entry point and exports no tools — registration
   is entirely via `createMcpServer`.
 
 ## Pro + disabled tools (not part of the free surface)
 
-- `create_page`, `update_page`, `delete_page` — high-stakes CMS writes,
-  `tier: "pro"`. Registered by `createMcpServer` but gated at call time by
-  `requirePaidTier()` (`apps/mcp/src/lib/require-paid-tier.ts`) — the paid-tier
-  check lives in the handler, never in the tool signature, per the
-  identity-blind rule above.
-- `start_purchase` — transactional, Pro-only; the sole entry in
-  `OSS_DISABLED_TOOLS`, so it is filtered out of catalog registration and the
-  server entirely. Re-enable criteria live at
+- `create_page`, `update_page`, `delete_page` — **RETIRED by #5853**, not
+  merely disabled. Their HTTP twins (the untenanted `/v1/content` writes) were
+  deleted in the same PR, so keeping the tools would have left three MCP tools
+  with no HTTP equivalent — a direct breach of the API↔MCP parity rule. Their
+  replacement is the tenant-guarded
+  `/v1/workspaces/:workspaceId/content` family, which resolves its scope from a
+  session-bound `TenantContext`; an anonymous caller supplying a `workspaceId`
+  is exactly the client-supplied scope that surface exists to refuse, so the
+  identity-blind MCP catalog can never carry it. `OSS_DISABLED_TOOLS` was the
+  wrong instrument: it promises a re-enable path, and there is none until the
+  authed MCP surface (#3591) exists.
+- `start_purchase` — **no longer disabled** (#5971). It returns a
+  Stripe-HOSTED Checkout URL for a named offering and charges nothing in-tool;
+  the buyer pays on Stripe's own page. It left `OSS_DISABLED_TOOLS` — which is
+  now empty — and its visibility is gated instead on the deployment's
+  `commerce` licence claim, per its `addon: "commerce"` catalog marker. A
+  keyless site advertises it in neither the discovery manifest nor the running
+  server's tool list, and calling it by name there returns the module-disabled
+  `not_found` body. The claim is resolved once at boot
+  (`src/lib/commerce-claim.ts`, awaited in `src/index.ts`) and read
+  synchronously by both the registration filter and the handler's own
+  re-check. Calls are rate-limited per IP by the AbuseGuard
+  (`MCP_ABUSE_START_PURCHASE_DAILY_CAP`, default 20, on its own tracker).
+  The disposition of the old Phase 3 re-enable criteria — 1 and 2 retired as
+  inapplicable to a hosted handoff, 3 and 4 met — is recorded at
   `docs/internal/roadmaps/phase-3-readiness.md`.
 
 **Re-derive these counts rather than trusting them here** — the catalog in
 `packages/metadata/src/mcp-tool-catalog.ts` is the source; free anonymous =
-catalog − `OSS_DISABLED_TOOLS` − `tier: "pro"`.
+catalog − `OSS_DISABLED_TOOLS` − `tier: "pro"` − any `addon` whose claim this
+deployment does not hold.
 
-Don't add identity logic to any tool signature. Don't remove `start_purchase`
-from `OSS_DISABLED_TOOLS` without satisfying the Phase 3 re-enable criteria.
+Don't add identity logic to any tool signature. Don't un-gate an `addon`-tagged
+tool — the claim is a DEPLOYMENT property read from the licence, never a
+caller-supplied argument, and every gate fails closed. Don't add a name to
+`OSS_DISABLED_TOOLS` where an entitlement gate is what the tool actually
+needs; and don't remove one from it without the review
+`docs/internal/roadmaps/phase-3-readiness.md` describes.
 
 ## Tool implementation pattern
 
@@ -87,8 +116,12 @@ Example (lead routing):
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-07-09 — corrected the tool-count explanation (18 catalog → 17 registered → 14 free anonymous) and the Pro-tool gating (registered + `requirePaidTier()`-gated, not `OSS_DISABLED_TOOLS`-disabled).
+Last updated: 2026-09-17 — #5971: `start_purchase` re-enabled behind the `commerce` licence claim. `OSS_DISABLED_TOOLS` is now empty; the registered count is 19 on a keyless deployment and 20 on a commerce-claimed one; the tool's input field is `productCode` (was `priceId`), matching its HTTP twin; a per-IP daily cap (`MCP_ABUSE_START_PURCHASE_DAILY_CAP`) covers it.
 
-Last updated: 2026-08-26 — doc-sync: tool-count explanation "18 catalog → 17 registered → 14 free anonymous" → "22 catalog → 21 registered → 18 free anonymous" (derived from `packages/metadata/src/mcp-tool-catalog.ts`: `get_flow`/`submit_flow_step` landed via PR #3973, `list_availability`/`create_booking` landed via PR #4421). Added the Booking category to the free-tool enumeration above. `CLAUDE.md` and `docs/ARCHITECTURE.md` re-verified as non-drift (already correct); `packages/create-ailk/templates/apps/mcp/CLAUDE.md` no longer exists in the scaffolder template tree (structure changed since the count was scoped there).
+Prior: 2026-07-09 — corrected the tool-count explanation (18 catalog → 17 registered → 14 free anonymous) and the Pro-tool gating (registered + `requirePaidTier()`-gated, not `OSS_DISABLED_TOOLS`-disabled).
+
+Last updated: 2026-09-17 — doc-sync: tool counts "23 catalog → 22 registered → 19 free anonymous" → "20 in TOOLS → 19 registered → 19 free anonymous", and the Pro-tools section rewritten to record that `create_page`/`update_page`/`delete_page` were RETIRED by #5853 rather than disabled (D7) — derived from `packages/metadata/src/mcp-tool-catalog.ts` and verified against `apps/mcp/src/server.ts`.
+
+Prior: 2026-08-26 — doc-sync: tool-count explanation "18 catalog → 17 registered → 14 free anonymous" → "22 catalog → 21 registered → 18 free anonymous" (derived from `packages/metadata/src/mcp-tool-catalog.ts`: `get_flow`/`submit_flow_step` landed via PR #3973, `list_availability`/`create_booking` landed via PR #4421). Added the Booking category to the free-tool enumeration above. `CLAUDE.md` and `docs/ARCHITECTURE.md` re-verified as non-drift (already correct); `packages/create-ailk/templates/apps/mcp/CLAUDE.md` no longer exists in the scaffolder template tree (structure changed since the count was scoped there).
 
 Last updated: 2026-08-31 — doc-sync: tool counts 22/21/18 → 23/22/19 and Booking (2) → Booking (3): `get_event_meta` added (#4633), the meta-only scheduling read twinning `GET /v1/schedule/event-meta` — derived from `packages/metadata/src/mcp-tool-catalog.ts`.

package/templates/apps/mcp/__tests__/aeo-cli-parity.test.ts

@@ -25,7 +25,10 @@ import {
   entityMarkup,
   faqHowtoIncentive,
   jsonldValidity,
+  offerOnPricedPage,
+  policiesPresent,
   schemaCoverage,
+  taxCodeWhenStripeTax,
   type Rule,
 } from "@working-theory/aeo";
 
@@ -44,6 +47,9 @@ const RULES: Rule[] = [
   jsonldValidity,
   faqHowtoIncentive,
   entityMarkup,
+  policiesPresent,
+  offerOnPricedPage,
+  taxCodeWhenStripeTax,
 ];
 
 const FIXTURE_SLUG = "home";