create-ailk 0.23.0 → 0.24.0

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

@@ -469,6 +469,29 @@ function usableCustomerId(raw: string | null | undefined): string | null {
     : null;
 }
 
+/** A Stripe customer id: `cus_` and letters or digits only, no separator. */
+const STRIPE_CUSTOMER_ID = /^cus_[A-Za-z0-9]+$/;
+
+/**
+ * The Stripe Dashboard link to one customer (#9349 DD5). Pure: the caller
+ * reads the mode. `null` unless `customerId` is a well-formed `cus_` id of
+ * at most 255 characters, so a stored value can never add a path segment,
+ * a query or a fragment to the fixed Dashboard host.
+ */
+export function stripeCustomerDashboardUrl(
+  customerId: string,
+  mode: "test" | "live",
+): string | null {
+  if (
+    customerId.length > MAX_CUSTOMER_ID_LENGTH ||
+    !STRIPE_CUSTOMER_ID.test(customerId)
+  ) {
+    return null;
+  }
+  const segment = mode === "test" ? "test/customers" : "customers";
+  return `https://dashboard.stripe.com/${segment}/${customerId}`;
+}
+
 // ─── findOrCreatePerson ───────────────────────────────────────────────────────
 
 /** The one delegate this file writes through — the shared client or a transaction's. */

package/templates/apps/api/src/services/project-listings.ts

@@ -176,6 +176,14 @@ export function deriveListingSlug(name: string): string {
  */
 const SLUG_COLLISION_SCAN_LIMIT = 200;
 
+/**
+ * The most active rows the anonymous page-render read returns (#9243). No
+ * consumer in this repo names a shelf size, so the bound is the one the other
+ * anonymous listing read already carries — the directory's
+ * `LISTING_DIRECTORY_MAX_ENTRIES` — rather than a second number to keep in step.
+ */
+const PUBLIC_LISTINGS_MAX_ROWS = LISTING_DIRECTORY_MAX_ENTRIES;
+
 /**
  * The first free slug for `base` on this site. Uniqueness is already scoped
  * `@@unique([siteId, slug])`, so the suffix is too: a second "Atlas" on this
@@ -412,10 +420,10 @@ function toResponseRow(
  * Since #5036 D6d the listing stores the experiment's KEY rather than its id,
  * and that key is the same string `WaitlistScore.experimentKey` holds — so the
  * `WaitlistExperiment` read that existed purely to translate one into the
- * other is gone. One `WaitlistScore.count` per DISTINCT key remains, bounded
- * by the small number of distinct experiments a dashboard page carries rather
- * than by row count (`waitlist-dashboard.ts`'s "one read across every returned
- * row" discipline).
+ * other is gone. ONE `WaitlistScore.groupBy` over every DISTINCT key remains
+ * (#9243): one read across every returned row (`waitlist-dashboard.ts`'s
+ * discipline), however many experiments the page carries — the per-key
+ * `count()` fan-out this replaced ran on the anonymous public read.
  */
 async function attachWaitlistCounts(
   siteId: string,
@@ -426,29 +434,28 @@ async function attachWaitlistCounts(
   ];
   if (experimentKeys.length === 0) return new Map();
 
-  const counts = new Map<string, number>();
-  await Promise.all(
-    experimentKeys.map(async (experimentKey) => {
-      // fence: workspaceId === the scope id this query already filters siteId by
-      // (workspace_site_agree CHECK, 20260922120000_tenancy_fence). Filtering the
-      // CONSTRAINED column makes the scope correct by construction; the format
-      // CHECK makes a raw alias match nothing rather than by accident.
-      //
-      // What that id IS depends on the caller, and only two of the six are
-      // route-resolved: `listProjectListings` and `getProjectListing` receive
-      // `tenant.workspaceId`, so for them this is an isolation control.
-      // `listMyProjectListings` and the two `publicProjectListings` call sites
-      // pass a ProjectListing row's OWN `siteId`, so for them it is a
-      // CONSISTENCY control — the count agrees with the row it is reported
-      // against — exactly as `project-listing-decision.ts#waitlistCountFor`
-      // spells out (#6258 § 1.6 / § 5 D8, security review L-2).
-      const count = await prisma.waitlistScore.count({
-        where: { siteId, workspaceId: siteId, experimentKey },
-      });
-      counts.set(experimentKey, count);
-    }),
-  );
-  return counts;
+  // fence: workspaceId === the scope id this query already filters siteId by
+  // (workspace_site_agree CHECK, 20260922120000_tenancy_fence). Filtering the
+  // CONSTRAINED column makes the scope correct by construction; the format
+  // CHECK makes a raw alias match nothing rather than by accident.
+  //
+  // What that id IS depends on the caller, and only two of the six are
+  // route-resolved: `listProjectListings` and `getProjectListing` receive
+  // `tenant.workspaceId`, so for them this is an isolation control.
+  // `listMyProjectListings` and the two `publicProjectListings` call sites
+  // pass a ProjectListing row's OWN `siteId`, so for them it is a
+  // CONSISTENCY control — the count agrees with the row it is reported
+  // against — exactly as `project-listing-decision.ts#waitlistCountFor`
+  // spells out (#6258 § 1.6 / § 5 D8, security review L-2).
+  //
+  // A key with no score rows is absent from a GROUP BY result; `waitlistCountFor`
+  // reads it as 0, the same value the per-key `count()` produced.
+  const grouped = await prisma.waitlistScore.groupBy({
+    by: ["experimentKey"],
+    where: { siteId, workspaceId: siteId, experimentKey: { in: experimentKeys } },
+    _count: { _all: true },
+  });
+  return new Map(grouped.map((g) => [g.experimentKey, g._count._all]));
 }
 
 function waitlistCountFor(
@@ -1902,10 +1909,10 @@ function orderPublicListings<T extends { row: { id: string; decidedAt: Date | nu
 }
 
 /**
- * The page-render read (#4998 AC4, reshaped by #5033): every `active` row for
- * the site, the THREE newest by `decidedAt` first, then the rest by
- * `waitlistCount` desc, then `decidedAt` desc. `founderEmail` never leaves
- * this function.
+ * The page-render read (#4998 AC4, reshaped by #5033, bounded by #9243): the
+ * newest-decided `PUBLIC_LISTINGS_MAX_ROWS` `active` rows for the site, the
+ * THREE newest by `decidedAt` first, then the rest by `waitlistCount` desc,
+ * then `decidedAt` desc. `founderEmail` never leaves this function.
  *
  * Rows whose window has elapsed are returned and read `closed` — computed,
  * per row, against one instant, with no job having run. They are not filtered
@@ -1917,6 +1924,11 @@ export async function publicProjectListings(siteId: string): Promise<ProjectList
   const listingConfig = await listingConfigFor(siteId);
   const rows = await prisma.projectListing.findMany({
     where: { siteId, status: "active" },
+    // Same window as the directory read: with a `take`, the rows kept must be
+    // chosen, and "newest decided first, NULLS LAST" is the order the public
+    // shelf leads with anyway.
+    orderBy: [{ decidedAt: { sort: "desc", nulls: "last" } }, { id: "asc" }],
+    take: PUBLIC_LISTINGS_MAX_ROWS,
     select: PROJECT_LISTING_SELECT,
   });
   const counts = await attachWaitlistCounts(siteId, rows);

package/templates/apps/mcp/CLAUDE.md

@@ -43,8 +43,10 @@ Inherits root `CLAUDE.md`. This file adds MCP-specific rules.
   name points straight at the Vercel project; a second proxy in front keys every caller on
   that proxy. It is a function, not `trustProxy: 1`, because Fastify 5.12 treats a numeric
   hop count as trusting nothing. The long-running entry trusts no proxy.
-- **Per address, per instance.** 60 requests a minute across reads and writes (the write rate
-  is parsed but not enforced); `capture_lead` 50 a day, `start_purchase` 20 a day,
+- **Per address, per instance.** 60 requests a minute across every request
+  (`MCP_RATE_LIMIT_READ_PER_MIN`), plus a tighter 10 a minute on the six anonymous write tools
+  (`MCP_RATE_LIMIT_WRITE_PER_MIN`, #9251), refused with the same 429 shape; `capture_lead` 50 a
+  day, `start_purchase` 20 a day,
   `create_booking` 20 a day and `submit_flow_step` 50 a day, each on its own budget.
   `subscribe_newsletter` and `request_callback` have no daily cap. Each warm instance counts
   on its own and a cold start resets the counts, so a caller reaching N instances gets up to
@@ -73,8 +75,8 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 
 **The HTTP write branch (6).** `WRITE_TOOLS` in `src/http-transport.ts` — `capture_lead`, `subscribe_newsletter`, `request_callback`, `start_purchase`, `create_booking`, `submit_flow_step` — takes the write-origin allow-list and the AbuseGuard (UA, honeypot, email format, per-IP daily cap); every other tool takes the read branch (UA only). A tool that sends caller-chosen data to the hub belongs in it: `__tests__/write-tool-guard.test.ts` fails when a catalog tool that sends a non-GET request through `@working-theory/api-client` is missing, and makes every new catalog tool pick a branch (#8071).
 
-**Read (9):** `list_pages`, `read_content`, `search_content`, `get_site_info`, `get_business_hours`, `get_locations`, `get_offerings`, `get_pricing`, `get_faq`
-**Conversion-write (3):** `capture_lead`, `subscribe_newsletter`, `request_callback`
+**Read (9):** `list_pages`, `read_content`, `search_content`, `get_site_info`, `get_business_hours`, `get_locations`, `get_offerings`, `get_pricing`, `get_faq`. The first three adopted their `apps/api` routes' arguments and results (#7167, #7168, #7169 — the operator's decision of 2026-10-19): `search_content` takes `q` and answers the route's `ItemList` (`query`, `items`, `totalItems`); `list_pages` requires `type`, takes `page`/`pageSize` and answers the paginated `ItemList` (`items`, `pagination`); `read_content` takes `include` and answers the page's JSON-LD at the root with `page`, plus `body` only with `include: "body"` — a miss is the not-found body. Each parses the same `@working-theory/validation` export its route parses with and answers through the same `@working-theory/content-adapters` builder, so the parity guard holds them as `twin`s
+**Conversion-write (3):** `capture_lead`, `subscribe_newsletter`, `request_callback` — each takes the body its `POST /v1/leads/{submit,subscribe,callback}` route parses (`leadSubmitBodySchema`: `source`, `email`, `consent`, `payload`; `leadSubscribeBodySchema`: `email`, `source`; `leadCallbackBodySchema`: `name`, `phone`, `preferredTime`, `payload`) and returns the route's 201 body `{ id, persisted, email }` unchanged (#7171, #7172, #7173 — the operator's decision of 2026-10-19), so the parity guard holds the three as `twin`s. `source` is the agent's to choose — `mcp` unless the operator says otherwise — and a consent-bearing source needs `consent: true`, exactly as a form does; `capture_lead` still spreads the spoke marker `payload.site` from `AILK_LEAD_SITE` last. The AbuseGuard reads the first two's `email` at the top level, else inside `payload` (the route lifts it from there), so a malformed address is refused wherever it sits
 **Maintenance (2):** `audit`, `create_project`
 **Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has. `submit_flow_step` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP`, default 50 — #8071)
 **Booking (4):** `list_availability`, `get_event_meta`, `list_meetings`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`. `create_booking` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_CREATE_BOOKING_DAILY_CAP`, default 20, and an `attendee.email` format check — #8071). `list_meetings` (#8843 D5) twins `GET /v1/schedule/meetings`: it takes no argument and returns the site's Live meetings — slug, visibility, position and whether each can be booked, plus a bookable one's calLink, title, length, description and price; `private` means unlisted, not secret
@@ -223,7 +225,11 @@ 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-10-18 — #9137: the three listing application tools are `list_listing_applications`, `get_listing_application` and `decide_listing_application`, and their pre-rename names stay one release as deprecated aliases — the signed-in workspace surface is eighteen tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
+Last updated: 2026-10-20 — #7171, #7172, #7173: the three lead writes adopted their routes' bodies and 201 results and are parity `twin`s — the Conversion-write line records the adopted shapes — verified against `apps/mcp/src/tools/{capture_lead,subscribe_newsletter,request_callback}.ts`, `packages/validation/src/schemas/leads.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-20 — #7167, #7168, #7169: the three content reads adopted their routes' arguments and results and are parity `twin`s — the Read line records the adopted shapes — verified against `apps/mcp/src/tools/{search_content,list_pages,read_content}.ts`, `packages/validation/src/schemas/content-reads.ts`, `packages/content-adapters/src/content-reads.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 2026-10-18 — #9137: the three listing application tools are `list_listing_applications`, `get_listing_application` and `decide_listing_application`, and their pre-rename names stay one release as deprecated aliases — the signed-in workspace surface is eighteen tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
 
 Prior: 2026-10-18 — #8843 PR A: `list_meetings` twins `GET /v1/schedule/meetings` — Booking is four tools, the counts are 21 in TOOLS, 20 registered keyless and 21 commerce-claimed, and six tools carry `tier: "pro"` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `apps/mcp/src/server.ts` and `tests/parity/api-parity/kinds/site.ts`.
 

package/templates/apps/mcp/__tests__/app-entry.test.ts

@@ -134,9 +134,9 @@ function captureLead(id: number, name: string): object {
     params: {
       name: "capture_lead",
       arguments: {
-        name,
+        source: "mcp",
         email: `${name.toLowerCase()}@example.com`,
-        message: "Interested in your services.",
+        payload: { name, message: "Interested in your services." },
       },
     },
   };

package/templates/apps/mcp/__tests__/http-transport.test.ts

@@ -185,8 +185,9 @@ describe("CORS enforcement on write tools", () => {
       params: {
         name: "capture_lead",
         arguments: {
-          name: "Bot",
+          source: "mcp",
           email: "bot@evil.com",
+          payload: { name: "Bot" },
         },
       },
     };
@@ -214,8 +215,9 @@ describe("CORS enforcement on write tools", () => {
         params: {
           name: "capture_lead",
           arguments: {
-            name: "Jane",
+            source: "mcp",
             email: "jane@example.com",
+            payload: { name: "Jane" },
           },
         },
       };
@@ -297,8 +299,31 @@ describe("Abuse rules", () => {
       params: {
         name: "capture_lead",
         arguments: {
-          name: "Spammer",
+          source: "mcp",
           email: "not-an-email",
+          payload: { name: "Spammer" },
+        },
+      },
+    };
+
+    const res = await mcpPost(port, payload);
+    expect(res.status).toBe(422);
+  });
+
+  // #7171 — `email` is optional at the top level of the route body (the
+  // site's own envelope carries it inside `payload`, and the route lifts it
+  // from there), so the guard reads `payload.email` when the top level has
+  // none: a malformed address cannot be nested past the check.
+  it("rejects capture_lead with a malformed payload.email and no top-level email", async () => {
+    const payload = {
+      jsonrpc: "2.0",
+      id: 23,
+      method: "tools/call",
+      params: {
+        name: "capture_lead",
+        arguments: {
+          source: "mcp",
+          payload: { name: "Spammer", email: "not-an-email" },
         },
       },
     };
@@ -315,9 +340,10 @@ describe("Abuse rules", () => {
       params: {
         name: "capture_lead",
         arguments: {
-          name: "Bot",
+          source: "mcp",
           email: "bot@example.com",
           honeypot: "i-am-a-bot",
+          payload: { name: "Bot" },
         },
       },
     };
@@ -346,7 +372,11 @@ describe("Abuse rules", () => {
           method: "tools/call",
           params: {
             name: "capture_lead",
-            arguments: { name: "Bot", email: "bot@example.com" },
+            arguments: {
+              source: "mcp",
+              email: "bot@example.com",
+              payload: { name: "Bot" },
+            },
           },
         },
         { "user-agent": "EvilBot/1.0" },
@@ -373,7 +403,14 @@ describe("capture_lead forwards the trusted caller address (#8073)", () => {
   beforeEach(async () => {
     submitSpy = jest
       .spyOn(apiClient.leads, "submit")
-      .mockResolvedValue({ ok: true, body: { id: "lead_1", persisted: "db" } });
+      .mockResolvedValue({
+        ok: true,
+        body: {
+          id: "lead_1",
+          persisted: "db",
+          email: { ok: true, messageId: "msg_1" },
+        },
+      });
     app = await buildHttpTransportApp(DEFAULT_CONFIG);
     await app.listen({ host: "127.0.0.1", port: 0 });
     port = (app.server.address() as AddressInfo).port;
@@ -390,7 +427,10 @@ describe("capture_lead forwards the trusted caller address (#8073)", () => {
       jsonrpc: "2.0",
       id,
       method: "tools/call",
-      params: { name: "capture_lead", arguments: { name: "Jane", email } },
+      params: {
+        name: "capture_lead",
+        arguments: { source: "mcp", email, payload: { name: "Jane" } },
+      },
     };
   }
 
@@ -411,6 +451,36 @@ describe("capture_lead forwards the trusted caller address (#8073)", () => {
     });
   });
 
+  // #7171 AC-11, AC-14 — the body reaches the hub as the agent sent it; an
+  // agent's `siteId` is STRIPPED by the SDK's parse against the registered
+  // shape (never refused, as the route strips it), so none is ever posted.
+  it("posts the route body as sent, and strips an agent's siteId rather than refusing it", async () => {
+    delete process.env.AILK_LEAD_SITE;
+
+    const res = await mcpPost(port, {
+      jsonrpc: "2.0",
+      id: 42,
+      method: "tools/call",
+      params: {
+        name: "capture_lead",
+        arguments: {
+          source: "mcp",
+          email: "jane3@example.com",
+          payload: { name: "Jane" },
+          siteId: "evil",
+        },
+      },
+    });
+
+    expect(res.status).toBe(200);
+    expect(submitSpy).toHaveBeenCalledTimes(1);
+    expect(submitSpy.mock.calls[0]?.[0]).toEqual({
+      source: "mcp",
+      email: "jane3@example.com",
+      payload: { name: "Jane" },
+    });
+  });
+
   it("sends no visitor headers (and no second argument) when the key is unset", async () => {
     delete process.env.AILK_VISITOR_FORWARD_KEY;
 
@@ -646,7 +716,7 @@ describe("JSON-RPC batch bodies take the write branch (#5971)", () => {
       method: "tools/call",
       params: {
         name: "capture_lead",
-        arguments: { name: "A", email: "a@example.com" },
+        arguments: { source: "mcp", email: "a@example.com", payload: { name: "A" } },
       },
     });
 
@@ -752,6 +822,9 @@ describe("a non-finite daily cap falls back to the default, never to unlimited (
     });
     app = await buildHttpTransportApp({
       ...DEFAULT_CONFIG,
+      // 21 writes in one minute: lift the per-minute write bucket (#9251) so
+      // the DAILY cap is the limit this test exercises.
+      rateLimits: { readPerMin: 60, writePerMin: 1000 },
       cors: { writeAllowedOrigins: ["*"] as string[] },
       abuse: {
         captureLeadDailyCapPerIp: 50,
@@ -855,12 +928,20 @@ describe("abuse refusal status is keyed on the typed reason code (#5994)", () =>
     // the preHandler, is under test.
     await mcpPost(
       port,
-      captureLeadPayload(40, { name: "First", email: "first@example.com" }),
+      captureLeadPayload(40, {
+        source: "mcp",
+        email: "first@example.com",
+        payload: { name: "First" },
+      }),
     );
 
     const capped = await mcpPost(
       port,
-      captureLeadPayload(41, { name: "Second", email: "second@example.com" }),
+      captureLeadPayload(41, {
+        source: "mcp",
+        email: "second@example.com",
+        payload: { name: "Second" },
+      }),
     );
 
     expect(capped.status).toBe(403);

package/templates/apps/mcp/__tests__/lib/content-adapter-parity.test.ts

@@ -57,9 +57,14 @@ describe("read_content ↔ apps/api adapter parity (CONTENT_ADAPTER=mdx)", () =>
     });
     const viaApi = await apiAdapter.getPageBySlug("HomePage", "home", locale);
 
-    expect(viaMcp).not.toBeNull();
+    // #7169: the tool answers the route's document — the frontmatter sits
+    // under `page` (a HomePage document's root is `@context`/`@graph`/`page`),
+    // and a miss is the not-found body rather than `null`.
+    if (!("page" in viaMcp)) {
+      throw new Error(`read_content answered ${JSON.stringify(viaMcp)}`);
+    }
     expect(viaApi).not.toBeNull();
-    expect(viaMcp!.slug).toBe(viaApi!.slug);
-    expect(viaMcp!.frontmatter.title).toBe(viaApi!.title);
+    expect(viaMcp.page.slug).toBe(viaApi!.slug);
+    expect(viaMcp.page.title).toBe(viaApi!.title);
   });
 });

package/templates/apps/mcp/__tests__/lib/content-adapter.test.ts

@@ -12,9 +12,6 @@
  * - it forwards the caller's resolved `locale` as `defaultLocale`;
  * - it defaults `contentRoot` to `mcpContentRoot()` when the caller passes
  *   none (#8070 D3; the resolver's order is pinned in `content-root.test.ts`);
- * - its MDX-narrowed twin `getMcpMdxContentAdapter()` (which `read_content`
- *   needs for `getPageSource()`) resolves the same way and raises a named
- *   error rather than a TypeError when the selected adapter is not MDX;
  * - on `CONTENT_ADAPTER=mdx` (the default, unset), it passes NO `workspaceId`;
  * - on `CONTENT_ADAPTER=database`, it reads `mcpPublicWorkspace()` (#5876
  *   spec D2/D4/D5/D6): a resolved workspace forwards `workspaceId` + `prisma`
@@ -34,7 +31,6 @@ import type { ArtifactPrismaClient } from "@working-theory/content-adapters";
 
 import {
   getMcpContentAdapter,
-  getMcpMdxContentAdapter,
   mcpContentRoot,
 } from "../../src/lib/content-adapter.js";
 import {
@@ -164,24 +160,3 @@ describe("getMcpContentAdapter — CONTENT_ADAPTER=database", () => {
     await expect(adapter.getPageBySlug("HomePage", "home")).resolves.toBeNull();
   });
 });
-
-describe("getMcpMdxContentAdapter", () => {
-  beforeEach(() => {
-    mockResolveContentAdapter.mockReset();
-  });
-
-  it("returns the resolved adapter when it exposes getPageSource", () => {
-    const mdxish = { getPageSource: jest.fn() };
-    mockResolveContentAdapter.mockReturnValue(mdxish);
-
-    expect(getMcpMdxContentAdapter({ contentRoot: "/fixtures/content" })).toBe(
-      mdxish,
-    );
-  });
-
-  it("throws a named error when the resolved adapter is not MDX-capable", () => {
-    mockResolveContentAdapter.mockReturnValue({ getPageBySlug: jest.fn() });
-
-    expect(() => getMcpMdxContentAdapter()).toThrow(/CONTENT_ADAPTER=mdx/);
-  });
-});

package/templates/apps/mcp/__tests__/lib/fail-closed-tools.test.ts

@@ -78,21 +78,36 @@ describe("every content tool — CONTENT_ADAPTER=database, unresolved workspace"
     expect(stub.artifactVersion.findMany).not.toHaveBeenCalled();
   }
 
-  it("ailkReadContent returns null", async () => {
+  // #7167, #7168, #7169 (the operator's decision of 2026-10-19): the three
+  // content reads answer their routes' shapes — the MCP not-found body for a
+  // missing page, and the routes' empty ItemLists — still with no query.
+  it("ailkReadContent returns the not-found body", async () => {
     const result = await ailkReadContent({ type: "HomePage", slug: "home" });
-    expect(result).toBeNull();
+    expect(result).toEqual({ error: "not_found", message: "Page not found" });
     expectNoQuery();
   });
 
-  it("ailkListPages returns { pages: [] }", async () => {
+  it("ailkListPages returns the empty paginated ItemList", async () => {
     const result = await ailkListPages({ type: "HomePage" });
-    expect(result).toEqual({ pages: [] });
+    expect(result).toEqual({
+      "@context": "https://schema.org",
+      "@type": "ItemList",
+      type: "HomePage",
+      items: [],
+      pagination: { page: 1, pageSize: 20, totalItems: 0, totalPages: 1 },
+    });
     expectNoQuery();
   });
 
-  it("ailkSearchContent returns { results: [] }", async () => {
-    const result = await ailkSearchContent({ query: "anything" });
-    expect(result).toEqual({ results: [] });
+  it("ailkSearchContent returns the empty ItemList", async () => {
+    const result = await ailkSearchContent({ q: "anything" });
+    expect(result).toEqual({
+      "@context": "https://schema.org",
+      "@type": "ItemList",
+      query: "anything",
+      items: [],
+      totalItems: 0,
+    });
     expectNoQuery();
   });