create-ailk 0.22.0 → 0.24.0

package/templates/apps/mcp/__tests__/search_content.test.ts

@@ -2,15 +2,19 @@
  * Tests for the search_content MCP tool handler.
  *
  * Acceptance criteria verified here:
- * - searchContentInputSchema validates correct inputs (query required, type + limit optional)
- * - searchContentInputSchema rejects query longer than 200 chars
- * - searchContentInputSchema rejects limit > 50
- * - searchContentInputSchema rejects empty query
- * - ailkSearchContent happy path returns results array with correct shape
- * - ailkSearchContent returns empty results for a query with no matches
+ * - contentSearchQuerySchema validates correct inputs (q required, type + limit optional)
+ * - contentSearchQuerySchema rejects q longer than 200 chars
+ * - contentSearchQuerySchema rejects limit > 50
+ * - contentSearchQuerySchema rejects empty q
+ * - ailkSearchContent happy path returns the route's ItemList with items of the correct shape
+ * - ailkSearchContent returns an empty ItemList for a query with no matches
  * - Malformed input causes Zod rejection
- * - #5831: searchContentInputSchema accepts a registry category slug and
+ * - #5831: contentSearchQuerySchema accepts a registry category slug and
  *   rejects one outside the registry; the handler forwards it to the adapter
+ *
+ * #7167 (the operator's decision of 2026-10-19): the tool adopted its route's
+ * arguments (`q`, not `query`) and result (the `ItemList`, not `{ results }`),
+ * so the cases below read the new names.
  */
 
 import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -19,102 +23,108 @@ import { join, resolve } from "node:path";
 
 import {
   ailkSearchContent,
-  searchContentInputSchema,
-  searchContentOutputSchema,
+  contentSearchQuerySchema,
+  contentSearchResultSchema,
 } from "../src/tools/search_content.js";
 
 const REPO_ROOT = resolve(__dirname, "../../..");
 const CONTENT_ROOT = `${REPO_ROOT}/content`;
 
-describe("searchContentInputSchema", () => {
-  it("accepts a valid query", () => {
-    const result = searchContentInputSchema.safeParse({ query: "hello" });
+describe("contentSearchQuerySchema", () => {
+  it("accepts a valid q", () => {
+    const result = contentSearchQuerySchema.safeParse({ q: "hello" });
     expect(result.success).toBe(true);
   });
 
-  it("accepts query with optional type filter", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "hello",
+  it("accepts q with optional type filter", () => {
+    const result = contentSearchQuerySchema.safeParse({
+      q: "hello",
       type: "HomePage",
     });
     expect(result.success).toBe(true);
   });
 
-  it("accepts query with optional limit", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "hello",
+  it("accepts q with optional limit", () => {
+    const result = contentSearchQuerySchema.safeParse({
+      q: "hello",
       limit: 10,
     });
     expect(result.success).toBe(true);
   });
 
-  it("rejects an empty query", () => {
-    const result = searchContentInputSchema.safeParse({ query: "" });
+  it("rejects an empty q", () => {
+    const result = contentSearchQuerySchema.safeParse({ q: "" });
     expect(result.success).toBe(false);
   });
 
-  it("rejects a query longer than 200 chars", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "a".repeat(201),
+  it("rejects a q longer than 200 chars", () => {
+    const result = contentSearchQuerySchema.safeParse({
+      q: "a".repeat(201),
     });
     expect(result.success).toBe(false);
   });
 
-  it("accepts a query exactly 200 chars", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "a".repeat(200),
+  it("accepts a q exactly 200 chars", () => {
+    const result = contentSearchQuerySchema.safeParse({
+      q: "a".repeat(200),
     });
     expect(result.success).toBe(true);
   });
 
   it("rejects limit of 0", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "hello",
+    const result = contentSearchQuerySchema.safeParse({
+      q: "hello",
       limit: 0,
     });
     expect(result.success).toBe(false);
   });
 
   it("rejects limit > 50", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "hello",
+    const result = contentSearchQuerySchema.safeParse({
+      q: "hello",
       limit: 51,
     });
     expect(result.success).toBe(false);
   });
 
   it("accepts limit of 50", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "hello",
+    const result = contentSearchQuerySchema.safeParse({
+      q: "hello",
       limit: 50,
     });
     expect(result.success).toBe(true);
   });
 
+  it("coerces a string limit, as the route's query string parses (#7167 DD1)", () => {
+    const result = contentSearchQuerySchema.safeParse({ q: "hello", limit: "5" });
+    expect(result.success).toBe(true);
+    expect(result.data!.limit).toBe(5);
+  });
+
   it("rejects an unknown type string", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "hello",
+    const result = contentSearchQuerySchema.safeParse({
+      q: "hello",
       type: "NotAType",
     });
     expect(result.success).toBe(false);
   });
 
-  it("rejects missing query (malformed input)", () => {
-    const result = searchContentInputSchema.safeParse({});
+  it("rejects missing q (malformed input)", () => {
+    const result = contentSearchQuerySchema.safeParse({});
     expect(result.success).toBe(false);
   });
 
   it("accepts a category slug from the registry (#5831)", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "roof",
+    const result = contentSearchQuerySchema.safeParse({
+      q: "roof",
       category: "roofing",
     });
     expect(result.success).toBe(true);
   });
 
   it("rejects a category slug outside the registry with an enum error (#5831)", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "roof",
+    const result = contentSearchQuerySchema.safeParse({
+      q: "roof",
       category: "not-a-real-category",
     });
     expect(result.success).toBe(false);
@@ -125,8 +135,8 @@ describe("searchContentInputSchema", () => {
   });
 
   it("rejects a GROUP slug — groups are derived, never tagged (#5831)", () => {
-    const result = searchContentInputSchema.safeParse({
-      query: "roof",
+    const result = contentSearchQuerySchema.safeParse({
+      q: "roof",
       category: "professional-services",
     });
     expect(result.success).toBe(false);
@@ -182,15 +192,15 @@ describe("ailkSearchContent — category filter (#5831)", () => {
 
   it("forwards category to the adapter — only the tagged page comes back", async () => {
     const result = await ailkSearchContent(
-      { query: "roof", category: "roofing" },
+      { q: "roof", category: "roofing" },
       root,
     );
-    expect(result.results.map((r) => r.slug)).toEqual(["roof-replacement"]);
+    expect(result.items.map((r) => r.slug)).toEqual(["roof-replacement"]);
   });
 
   it("returns every match when no category is passed", async () => {
-    const result = await ailkSearchContent({ query: "roof" }, root);
-    expect(result.results.map((r) => r.slug).sort()).toEqual([
+    const result = await ailkSearchContent({ q: "roof" }, root);
+    expect(result.items.map((r) => r.slug).sort()).toEqual([
       "attic-ventilation",
       "roof-replacement",
     ]);
@@ -198,22 +208,26 @@ describe("ailkSearchContent — category filter (#5831)", () => {
 
   it("returns [] for a registry slug nothing is tagged with", async () => {
     const result = await ailkSearchContent(
-      { query: "roof", category: "legal" },
+      { q: "roof", category: "legal" },
       root,
     );
-    expect(result.results).toEqual([]);
+    expect(result.items).toEqual([]);
   });
 });
 
 describe("ailkSearchContent handler", () => {
-  it("returns a results array on a known query", async () => {
-    const result = await ailkSearchContent({ query: "launch" }, CONTENT_ROOT);
-    expect(Array.isArray(result.results)).toBe(true);
+  it("returns the route's ItemList on a known query", async () => {
+    const result = await ailkSearchContent({ q: "launch" }, CONTENT_ROOT);
+    expect(result["@context"]).toBe("https://schema.org");
+    expect(result["@type"]).toBe("ItemList");
+    expect(result.query).toBe("launch");
+    expect(Array.isArray(result.items)).toBe(true);
+    expect(result.totalItems).toBe(result.items.length);
   });
 
   it("result items have required shape fields", async () => {
-    const result = await ailkSearchContent({ query: "launch" }, CONTENT_ROOT);
-    for (const item of result.results) {
+    const result = await ailkSearchContent({ q: "launch" }, CONTENT_ROOT);
+    for (const item of result.items) {
       expect(typeof item.slug).toBe("string");
       expect(typeof item.type).toBe("string");
       expect(typeof item.title).toBe("string");
@@ -222,25 +236,26 @@ describe("ailkSearchContent handler", () => {
     }
   });
 
-  it("returns empty results for a query that matches nothing", async () => {
+  it("returns an empty ItemList for a query that matches nothing", async () => {
     const result = await ailkSearchContent(
-      { query: "xqzxqzxqzxqz_no_match_ever" },
+      { q: "xqzxqzxqzxqz_no_match_ever" },
       CONTENT_ROOT,
     );
-    expect(result.results).toEqual([]);
+    expect(result.items).toEqual([]);
+    expect(result.totalItems).toBe(0);
   });
 
   it("respects limit option", async () => {
     const result = await ailkSearchContent(
-      { query: "a", limit: 1 },
+      { q: "a", limit: 1 },
       CONTENT_ROOT,
     );
-    expect(result.results.length).toBeLessThanOrEqual(1);
+    expect(result.items.length).toBeLessThanOrEqual(1);
   });
 
-  it("output validates against searchContentOutputSchema", async () => {
-    const result = await ailkSearchContent({ query: "launch" }, CONTENT_ROOT);
-    const parsed = searchContentOutputSchema.safeParse(result);
+  it("output validates against contentSearchResultSchema", async () => {
+    const result = await ailkSearchContent({ q: "launch" }, CONTENT_ROOT);
+    const parsed = contentSearchResultSchema.safeParse(result);
     expect(parsed.success).toBe(true);
   });
 });

package/templates/apps/mcp/__tests__/server.test.ts

@@ -231,19 +231,21 @@ describe("create_project on a spoke — the seam's UNSERVED_MCP_TOOLS (#8070 D7,
   });
 });
 
-describe("the five licence-feature tools — one-release warning cycle (#7136)", () => {
+describe("the six licence-feature tools — one-release warning cycle (#7136)", () => {
   const FLOW_PAIR = ["get_flow", "submit_flow_step"];
-  const BOOKING_TRIO = [
+  const BOOKING_TOOLS = [
     "list_availability",
     "get_event_meta",
+    "list_meetings",
     "create_booking",
   ];
-  const FIVE = [...FLOW_PAIR, ...BOOKING_TRIO];
+  const SIX = [...FLOW_PAIR, ...BOOKING_TOOLS];
   const FEATURE_OF: Record<string, string> = {
     get_flow: "flows-deliverables",
     submit_flow_step: "flows-deliverables",
     list_availability: "scheduling",
     get_event_meta: "scheduling",
+    list_meetings: "scheduling",
     create_booking: "scheduling",
   };
 
@@ -271,12 +273,12 @@ describe("the five licence-feature tools — one-release warning cycle (#7136)",
     return Object.keys((createMcpServer() as any)._registeredTools);
   }
 
-  it("warn mode, no feature held: all five still register and serve", () => {
+  it("warn mode, no feature held: all six still register and serve", () => {
     __setMcpHeldFeaturesForTest([]);
 
     const listed = listRegisteredTools().map((t) => t.name);
     const registered = registeredKeys();
-    for (const name of FIVE) {
+    for (const name of SIX) {
       expect(listed).toContain(name);
       expect(registered).toContain(name);
     }
@@ -288,9 +290,9 @@ describe("the five licence-feature tools — one-release warning cycle (#7136)",
 
     const names = reportUnlicensedProTools(warn);
 
-    expect(names.slice().sort()).toEqual(FIVE.slice().sort());
-    expect(warn).toHaveBeenCalledTimes(5);
-    for (const name of FIVE) {
+    expect(names.slice().sort()).toEqual(SIX.slice().sort());
+    expect(warn).toHaveBeenCalledTimes(6);
+    for (const name of SIX) {
       const message = warn.mock.calls
         .map(([m]) => m as string)
         .find((m) => m.includes(`"${name}"`));
@@ -326,7 +328,7 @@ describe("the five licence-feature tools — one-release warning cycle (#7136)",
     expect(warn).toHaveBeenCalledTimes(2);
   });
 
-  it("refuse mode, no feature held: none of the five registers, and nothing is warned", () => {
+  it("refuse mode, no feature held: none of the six registers, and nothing is warned", () => {
     __setMcpFeatureGateForTest("refuse");
     __setMcpHeldFeaturesForTest([]);
     const warn = jest.fn();
@@ -335,7 +337,7 @@ describe("the five licence-feature tools — one-release warning cycle (#7136)",
     expect(warn).not.toHaveBeenCalled();
     const listed = listRegisteredTools().map((t) => t.name);
     const registered = registeredKeys();
-    for (const name of FIVE) {
+    for (const name of SIX) {
       expect(listed).not.toContain(name);
       expect(registered).not.toContain(name);
     }
@@ -346,7 +348,7 @@ describe("the five licence-feature tools — one-release warning cycle (#7136)",
     __setMcpHeldFeaturesForTest(["scheduling"]);
 
     const registered = registeredKeys();
-    for (const name of BOOKING_TRIO) expect(registered).toContain(name);
+    for (const name of BOOKING_TOOLS) expect(registered).toContain(name);
     for (const name of FLOW_PAIR) expect(registered).not.toContain(name);
   });
 

package/templates/apps/mcp/__tests__/start_purchase.test.ts

@@ -32,6 +32,8 @@
  */
 
 import { checkout } from "@working-theory/api-client";
+import { getMcpToolCatalog } from "@working-theory/metadata";
+import { purchaseMcpInputSchema } from "@working-theory/validation";
 
 import {
   __setMcpCommerceClaimForTest,
@@ -72,13 +74,13 @@ describe("start_purchase — parity with the payload POST /v1/checkout/sessions
     createSession.mockResolvedValueOnce(sessionCreated());
 
     await ailkPurchase({
-      productCode: "pro-plan",
+      productCode: "growth_monthly",
       quantity: 2,
     });
 
     expect(createSession).toHaveBeenCalledTimes(1);
     expect(createSession).toHaveBeenCalledWith({
-      productCode: "pro-plan",
+      productCode: "growth_monthly",
       quantity: 2,
       successUrl:
         "https://example.com/purchase/success?session_id={CHECKOUT_SESSION_ID}",
@@ -89,7 +91,7 @@ describe("start_purchase — parity with the payload POST /v1/checkout/sessions
   it("omits quantity entirely when it is not supplied", async () => {
     createSession.mockResolvedValueOnce(sessionCreated());
 
-    await ailkPurchase({ productCode: "pro-plan" });
+    await ailkPurchase({ productCode: "growth_monthly" });
 
     const payload = createSession.mock.calls[0]![0];
     expect(payload).not.toHaveProperty("quantity");
@@ -99,10 +101,10 @@ describe("start_purchase — parity with the payload POST /v1/checkout/sessions
   it("derives both redirect URLs from AILK_BASE_URL — always, not only when omitted (#6001)", async () => {
     createSession.mockResolvedValueOnce(sessionCreated());
 
-    await ailkPurchase({ productCode: "pro-plan" });
+    await ailkPurchase({ productCode: "growth_monthly" });
 
     expect(createSession).toHaveBeenCalledWith({
-      productCode: "pro-plan",
+      productCode: "growth_monthly",
       successUrl:
         "https://example.com/purchase/success?session_id={CHECKOUT_SESSION_ID}",
       cancelUrl: "https://example.com/purchase/cancel",
@@ -114,7 +116,7 @@ describe("start_purchase — FR-1: the hosted Checkout URL", () => {
   it("returns { url } deep-equal to the seam's url, and nothing else", async () => {
     createSession.mockResolvedValueOnce(sessionCreated());
 
-    const result = await ailkPurchase({ productCode: "pro-plan" });
+    const result = await ailkPurchase({ productCode: "growth_monthly" });
 
     expect(result).toEqual({ url: HOSTED_URL });
   });
@@ -122,7 +124,7 @@ describe("start_purchase — FR-1: the hosted Checkout URL", () => {
   it("does NOT surface the route's sessionId (D5 — it identifies a buyer's session)", async () => {
     createSession.mockResolvedValueOnce(sessionCreated());
 
-    const result = await ailkPurchase({ productCode: "pro-plan" });
+    const result = await ailkPurchase({ productCode: "growth_monthly" });
 
     expect(result).not.toHaveProperty("sessionId");
   });
@@ -130,7 +132,7 @@ describe("start_purchase — FR-1: the hosted Checkout URL", () => {
   it("the URL it returns is Stripe-hosted — nothing is charged in-tool", async () => {
     createSession.mockResolvedValueOnce(sessionCreated());
 
-    const result = await ailkPurchase({ productCode: "pro-plan" });
+    const result = await ailkPurchase({ productCode: "growth_monthly" });
 
     expect((result as { url: string }).url).toMatch(
       /^https:\/\/checkout\.stripe\.com\//,
@@ -146,7 +148,7 @@ describe("start_purchase — FR-2: an unknown offering", () => {
       body: { error: "unknown-product-code" },
     });
 
-    const result = await ailkPurchase({ productCode: "no-such-offering" });
+    const result = await ailkPurchase({ productCode: "no-such-offering_monthly" });
 
     // The HTTP twin states and tests "Error responses never echo user input";
     // parity means the pair answers alike (#5971 security review, Low).
@@ -160,7 +162,7 @@ describe("start_purchase — FR-2: an unknown offering", () => {
       body: { error: "unknown-product-code" },
     });
 
-    const result = await ailkPurchase({ productCode: "no-such-offering" });
+    const result = await ailkPurchase({ productCode: "no-such-offering_monthly" });
 
     expect(result).toMatchObject({ error: "not_found" });
   });
@@ -172,7 +174,7 @@ describe("start_purchase — FR-2: an unknown offering", () => {
       body: { error: "unknown-product-code" },
     });
 
-    await ailkPurchase({ productCode: "no-such-offering" });
+    await ailkPurchase({ productCode: "no-such-offering_monthly" });
 
     expect(createSession).toHaveBeenCalledTimes(1);
   });
@@ -184,7 +186,7 @@ describe("start_purchase — FR-2: an unknown offering", () => {
       body: { error: "checkout-unavailable" },
     });
 
-    const result = await ailkPurchase({ productCode: "pro-plan" });
+    const result = await ailkPurchase({ productCode: "growth_monthly" });
 
     expect(result).toMatchObject({ error: "validation_failed" });
   });
@@ -250,3 +252,197 @@ describe("start_purchase — the redirect fix (#6001): a caller-supplied redirec
     expect(createSession).not.toHaveBeenCalled();
   });
 });
+
+// ── #8935 — the full Offerings lookup_key ───────────────────────────────────
+//
+// The tool takes a price by its full lookup_key (contract §3.7) and refuses an
+// ungrammatical one before any HTTP call, with the same not-found body every
+// route 404 maps to (A3, A5). The route decides the workspace and whether the
+// key is shown and org-enabled (A1, #8931); the mocked seam below answers with
+// the route's Offerings-path `201` body, `reply.status(201).send({ sessionId,
+// url })`. Spec: `docs/specs/8935-start-purchase-sells-a-named-spec.md`.
+
+const OFFERINGS_URL = "https://checkout.stripe.com/c/pay/cs_test_offerings";
+
+function offeringsSessionCreated() {
+  return {
+    ok: true as const,
+    body: { sessionId: "cs_test_offerings", url: OFFERINGS_URL },
+  };
+}
+
+const NOT_FOUND = {
+  error: "not_found",
+  message: "No offering matches that product code.",
+};
+
+describe("start_purchase — a shown, org-enabled lookup_key gets the route's hosted URL (#8935 AC-1)", () => {
+  const keys = [
+    "growth_monthly",
+    "growth_yearly",
+    "basic_once",
+    "samhenry-coaching_monthly",
+    `${"a".repeat(40)}_monthly`,
+  ];
+
+  it.each(keys)(
+    "%s reaches the route byte for byte and returns { url } only",
+    async (key) => {
+      createSession.mockResolvedValueOnce(offeringsSessionCreated());
+
+      const result = await ailkPurchase({ productCode: key });
+
+      expect(result).toEqual({ url: OFFERINGS_URL });
+      expect(result).not.toHaveProperty("sessionId");
+      expect(createSession).toHaveBeenCalledTimes(1);
+      // One argument, the payload — no init, so no header of the tool's own.
+      expect(createSession.mock.calls[0]).toHaveLength(1);
+      expect(createSession.mock.calls[0]![0]).toEqual({
+        productCode: key,
+        successUrl:
+          "https://example.com/purchase/success?session_id={CHECKOUT_SESSION_ID}",
+        cancelUrl: "https://example.com/purchase/cancel",
+      });
+    },
+  );
+
+  it("the 48-character key is the longest §3.7 allows", () => {
+    expect(keys[4]).toHaveLength(48);
+  });
+
+  it("forwards quantity alongside the key", async () => {
+    createSession.mockResolvedValueOnce(offeringsSessionCreated());
+
+    await ailkPurchase({ productCode: "growth_monthly", quantity: 2 });
+
+    expect(createSession.mock.calls[0]![0]).toEqual({
+      productCode: "growth_monthly",
+      quantity: 2,
+      successUrl:
+        "https://example.com/purchase/success?session_id={CHECKOUT_SESSION_ID}",
+      cancelUrl: "https://example.com/purchase/cancel",
+    });
+  });
+});
+
+describe("start_purchase — an ungrammatical key is refused before any call, with the route-404 body (#8935 AC-2)", () => {
+  const ungrammatical = [
+    "pro-plan",
+    "Growth_Monthly",
+    "growth_pro_monthly",
+    "wendi_retainer",
+    "growth_quarterly",
+    "growth_",
+    "_monthly",
+    `${"a".repeat(41)}_monthly`,
+  ];
+
+  it.each(ungrammatical)(
+    "%s passes the shared schema but answers not_found with no call and no echo",
+    async (key) => {
+      expect(purchaseMcpInputSchema.safeParse({ productCode: key }).success).toBe(
+        true,
+      );
+
+      const result = await ailkPurchase({ productCode: key });
+
+      expect(result).toEqual(NOT_FOUND);
+      expect(createSession).not.toHaveBeenCalled();
+      expect(JSON.stringify(result)).not.toContain(key);
+    },
+  );
+
+  it("the 49-character key is one past the §3.7 bound", () => {
+    expect(ungrammatical[7]).toHaveLength(49);
+  });
+
+  it.each([
+    ["{ error: unknown-product-code }", { error: "unknown-product-code" }],
+    ["null", null],
+    ["{}", {}],
+  ])(
+    "every route 404 maps to the same body, whatever the route's body (%s)",
+    async (_label, body) => {
+      createSession.mockResolvedValueOnce({
+        ok: false as const,
+        status: 404,
+        body,
+      } as never);
+
+      const result = await ailkPurchase({ productCode: "growth_monthly" });
+
+      expect(result).toEqual(NOT_FOUND);
+      expect(JSON.stringify(result)).not.toContain("growth_monthly");
+    },
+  );
+
+  it("the pre-call refusal and the route-404 mapping are one value", async () => {
+    const refused = await ailkPurchase({ productCode: "pro-plan" });
+    createSession.mockResolvedValueOnce({
+      ok: false as const,
+      status: 404,
+      body: { error: "unknown-product-code" },
+    });
+    const mapped = await ailkPurchase({ productCode: "growth_monthly" });
+
+    expect(refused).toEqual(mapped);
+  });
+
+  it("a code the route's regex refuses still answers validation_failed, with no call", async () => {
+    const result = await ailkPurchase({ productCode: "has spaces" });
+
+    expect(result).toMatchObject({ error: "validation_failed" });
+    expect(createSession).not.toHaveBeenCalled();
+  });
+});
+
+describe("start_purchase — the claim and the strict schema still answer first (#8935 AC-3)", () => {
+  it("an unclaimed site answers the module-disabled body for an ungrammatical key, with no call", async () => {
+    __setMcpCommerceClaimForTest("unclaimed");
+
+    const result = await ailkPurchase({ productCode: "Growth_Monthly" });
+
+    expect(result).toEqual({ error: "not_found", message: "Not found" });
+    expect(createSession).not.toHaveBeenCalled();
+  });
+
+  it.each(["workspaceId", "organizationId", "site", "metadata"])(
+    "a direct call carrying %s fails validation, with no call",
+    async (field) => {
+      const result = await ailkPurchase({
+        productCode: "growth_monthly",
+        [field]: "attacker-chosen",
+      } as never);
+
+      expect(result).toMatchObject({ error: "validation_failed" });
+      expect(createSession).not.toHaveBeenCalled();
+    },
+  );
+
+  it("the input schema has exactly productCode and quantity", () => {
+    expect(Object.keys(purchaseMcpInputSchema.shape)).toEqual([
+      "productCode",
+      "quantity",
+    ]);
+  });
+});
+
+describe("start_purchase — the catalog description names the lookup key (#8935 AC-5)", () => {
+  it("tells an agent to pass the lookupKey get_pricing or get_offerings returns", () => {
+    const entry = getMcpToolCatalog({ addons: { commerce: true } }).find(
+      (tool) => tool.name === "start_purchase",
+    );
+
+    expect(entry?.description).toBe(
+      "Start a purchase for an offering on this site. Provide the price's full lookup key as productCode — the lookupKey that get_pricing or get_offerings returns, such as growth_monthly — and an optional quantity; returns a Stripe-hosted Checkout URL for the buyer to complete payment on. Nothing is charged by this tool.",
+    );
+    for (const phrase of [
+      "lookupKey",
+      "get_pricing",
+      "get_offerings",
+      "Nothing is charged by this tool",
+    ]) {
+      expect(entry?.description).toContain(phrase);
+    }
+  });
+});