create-ailk 0.22.0 → 0.24.0

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

@@ -14,13 +14,35 @@
  * offering fields on its own frontmatter answer instead — a listing that
  * declares `price` + `priceCurrency` yields one tier named for the page. A
  * listing with neither an authored offer nor a price still returns `null`: no
- * price means no tier, never a fabricated zero.
+ * price means no tier, never a fabricated zero. `getPricingTiers`
+ * (`@working-theory/content-adapters`) documents the mapping.
+ *
+ * HTTP twin (#7178): `GET /v1/content/pricing` in `apps/api` takes the same
+ * arguments and answers through the same `getPricingTiers` — the shared seam
+ * the pair proves parity at. The tool still reads content locally, so it
+ * needs no API to answer.
+ *
+ * Offerings (#8933, spec D8): when the site sells through its connected
+ * Stripe catalog and `slug` is omitted or `pricing`, the tool answers the
+ * workspace's Offerings shown set instead — read over HTTP by
+ * `lib/shown-offerings.ts` (D6: only on a `claimed` host, at most
+ * `MCP_SHOWN_SET_BUDGET_MS`) and mapped by `pricingTiersFromShownSet`, the
+ * function the twin route answers through too, so each tier also carries
+ * `interval` and the full `lookupKey`. Names, descriptions and prices are
+ * seller-provided data returned as plain JSON values (T5). Any other slug, an
+ * unclaimed host, a workspace with no current set, a failed read or a mapping
+ * that throws answers the page content below, unchanged.
  *
  * Input:  { slug?: string, locale?: string }
- * Output: { tiers: Array<{ name, price, priceCurrency, description? }> } | null
+ * Output: { tiers: Array<{ name, price, priceCurrency, description?, interval?, lookupKey? }> } | null
  * Session/scope: none — read-only public content.
  */
 
+import {
+  getPricingTiers,
+  pricingTiersFromShownSet,
+  shownSetAnswersPricing,
+} from "@working-theory/content-adapters";
 import {
   getPricingInputSchema,
   getPricingOutputSchema,
@@ -33,12 +55,14 @@ import {
   mcpContentRoot,
 } from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
+import {
+  mcpCurrentShownSet,
+  reportMappingFailure,
+} from "../lib/shown-offerings.js";
 
 export { getPricingInputSchema, getPricingOutputSchema };
 export type { GetPricingInput, GetPricingOutput };
 
-const DEFAULT_SLUG = "pricing";
-
 /**
  * get_pricing handler.
  *
@@ -51,44 +75,20 @@ export async function ailkGetPricing(
 ): Promise<GetPricingOutput> {
   getPricingInputSchema.parse(input);
 
+  if (shownSetAnswersPricing(input.slug)) {
+    const shownSet = await mcpCurrentShownSet();
+    if (shownSet !== null) {
+      try {
+        return pricingTiersFromShownSet(shownSet);
+      } catch (err) {
+        reportMappingFailure(err);
+      }
+    }
+  }
+
   const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 
-  const slug = input.slug ?? DEFAULT_SLUG;
-  const data = await adapter.extractStructuredData("Product", slug, locale);
-
-  const schema = (data ?? {}) as Record<string, unknown>;
-
-  // Support both a top-level `offers` array and a single offer object.
-  const offersRaw = schema["offers"];
-  const offersArr: Record<string, unknown>[] = Array.isArray(offersRaw)
-    ? (offersRaw as Record<string, unknown>[])
-    : offersRaw && typeof offersRaw === "object"
-      ? [offersRaw as Record<string, unknown>]
-      : [];
-
-  if (offersArr.length === 0) {
-    const page = await adapter.getPageBySlug("Product", slug, locale);
-    if (!page || page.price === undefined) return null;
-    return getPricingOutputSchema.parse({
-      tiers: [
-        {
-          name: page.title,
-          price: page.price,
-          priceCurrency: page.priceCurrency ?? "USD",
-          ...(page.summary !== undefined && { description: page.summary }),
-        },
-      ],
-    });
-  }
-
-  const tiers = offersArr.map((offer) => ({
-    name: (offer["name"] as string) ?? "",
-    price: (offer["price"] as string | number) ?? "",
-    priceCurrency: (offer["priceCurrency"] as string) ?? "USD",
-    description: offer["description"] as string | undefined,
-  }));
-
-  return getPricingOutputSchema.parse({ tiers });
+  return getPricingTiers(adapter, { slug: input.slug, locale });
 }

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

@@ -13,27 +13,29 @@ export {
 } from "./purchase.js";
 
 export {
-  listPagesInputSchema,
-  listPagesOutputSchema,
+  contentListParamsSchema,
+  contentListQuerySchema,
+  contentListResultSchema,
   ailkListPages,
   type ListPagesInput,
-  type ListPagesOutput,
+  type ContentListResult,
 } from "./list_pages.js";
 
 export {
-  readContentInputSchema,
-  readContentOutputSchema,
+  contentPageParamsSchema,
+  contentPageQuerySchema,
+  contentPageResultSchema,
   ailkReadContent,
   type ReadContentInput,
-  type ReadContentOutput,
+  type ContentPageResult,
 } from "./read_content.js";
 
 export {
-  searchContentInputSchema,
-  searchContentOutputSchema,
+  contentSearchQuerySchema,
+  contentSearchResultSchema,
   ailkSearchContent,
   type SearchContentInput,
-  type SearchContentOutput,
+  type ContentSearchResult,
 } from "./search_content.js";
 
 export {
@@ -92,28 +94,27 @@ export {
   type AuditOutput,
 } from "./audit.js";
 
+// #7171, #7172, #7173 — the three lead writes take their routes' body
+// exports and share one output schema (the route's 201 body or the tool's
+// error), re-exported once from capture_lead.
 export {
-  submitLeadInputSchema,
-  submitLeadOutputSchema,
+  leadSubmitBodySchema,
+  leadWriteOutputSchema,
   ailkCaptureLead,
-  type SubmitLeadInput,
-  type SubmitLeadOutput,
+  type LeadSubmitBody,
+  type LeadWriteOutput,
 } from "./capture_lead.js";
 
 export {
-  subscribeNewsletterInputSchema,
-  subscribeNewsletterOutputSchema,
+  leadSubscribeBodySchema,
   ailkSubscribeNewsletter,
-  type SubscribeNewsletterInput,
-  type SubscribeNewsletterOutput,
+  type LeadSubscribeBody,
 } from "./subscribe_newsletter.js";
 
 export {
-  requestCallbackInputSchema,
-  requestCallbackOutputSchema,
+  leadCallbackBodySchema,
   ailkRequestCallback,
-  type RequestCallbackInput,
-  type RequestCallbackOutput,
+  type LeadCallbackBody,
 } from "./request_callback.js";
 
 export {

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

@@ -1,29 +1,35 @@
 /**
- * list_pages — returns published content pages, optionally filtered by type.
+ * list_pages — returns one page of the published content pages of a type.
  *
  * Pure read: resolves its adapter through `getMcpContentAdapter()` — the one
- * resolver seam (#5805, ADR 0011), MDX by default.
+ * resolver seam (#5805, ADR 0011), MDX by default — and answers through
+ * `listPagesItemList` (`@working-theory/content-adapters`).
  * No auth, no side effects, no network. The adapter reads from the filesystem.
  *
+ * HTTP twin (#7168): `GET /v1/content/:type` in `apps/api` parses the same
+ * `contentListParamsSchema` + `contentListQuerySchema` and answers through
+ * the same builder — the tool adopted the API, arguments and results: `type`
+ * is required, and `page` (default 1) / `pageSize` (default 20, at most 100)
+ * pick the window.
+ *
  * Phase 3 S3: optional `locale` parameter. Validated against `readLocales()`
  * allowlist; invalid or unknown values silently fall back to the project's
  * default locale (AC-i18n-07). Lists are locale-scoped — pages must exist in
  * the requested locale's directory to be enumerated.
  *
- * Input:  { type?: SchemaOrgType, locale?: string }
- * Output: { pages: Array<{ slug, type, title, description? }> }
+ * Input:  { type: SchemaOrgType, page?: number, pageSize?: number, locale?: string }
+ * Output: { "@context", "@type": "ItemList", type, items: ContentPage[],
+ *           pagination: { page, pageSize, totalItems, totalPages } }
  * Session/scope: none — read-only public content.
  */
 
+import { listPagesItemList } from "@working-theory/content-adapters";
 import {
-  SCHEMA_ORG_TYPES,
-  type SchemaOrgType,
-} from "@working-theory/content-adapters";
-import {
-  listPagesInputSchema,
-  listPagesOutputSchema,
+  contentListParamsSchema,
+  contentListQuerySchema,
+  contentListResultSchema,
+  type ContentListResult,
   type ListPagesInput,
-  type ListPagesOutput,
 } from "@working-theory/validation";
 
 import {
@@ -32,8 +38,12 @@ import {
 } from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
-export { listPagesInputSchema, listPagesOutputSchema };
-export type { ListPagesInput, ListPagesOutput };
+export {
+  contentListParamsSchema,
+  contentListQuerySchema,
+  contentListResultSchema,
+};
+export type { ListPagesInput, ContentListResult };
 
 /**
  * list_pages handler.
@@ -45,30 +55,14 @@ export type { ListPagesInput, ListPagesOutput };
 export async function ailkListPages(
   input: ListPagesInput,
   contentRoot?: string,
-): Promise<ListPagesOutput> {
-  listPagesInputSchema.parse(input);
+): Promise<ContentListResult> {
+  const { type } = contentListParamsSchema.parse(input);
+  const { page, pageSize } = contentListQuerySchema.parse(input);
 
   // Default: the one content-root resolver (#8070 D3).
   const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 
-  const types: readonly SchemaOrgType[] = input.type
-    ? [input.type]
-    : SCHEMA_ORG_TYPES;
-
-  const perType = await Promise.all(
-    types.map((type) => adapter.listPages(type, locale)),
-  );
-
-  const pages: ListPagesOutput["pages"] = perType.flatMap((results) =>
-    results.map((page) => ({
-      slug: page.slug,
-      type: page.type,
-      title: page.title,
-      ...(page.description !== undefined && { description: page.description }),
-    })),
-  );
-
-  return listPagesOutputSchema.parse({ pages });
+  return listPagesItemList(adapter, { type, page, pageSize, locale });
 }

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

@@ -57,11 +57,24 @@
  * through `@working-theory/api-client` per the architecture invariants (apps
  * may not import each other; the shared HTTP surface lives in packages/).
  *
- * Spec: `docs/specs/5971-start-purchase-hosted-checkout-spec.md`.
+ * THE KEY — the full Offerings lookup_key (#8935). `productCode` is a price's
+ * full lookup_key (contract §3.7), the `lookupKey` `get_pricing` and
+ * `get_offerings` return. After the claim and the strict schema, the one
+ * §3.7 parser, `parseLookupKey`, refuses an ungrammatical key before any HTTP
+ * call, with the same not-found body every route 404 maps to (A3, A5). The
+ * workspace stays the server's (A1): the api-client attaches the
+ * deployment's own spoke key, and the route alone decides whether the key is
+ * shown and org-enabled. A spoke whose Organization has no Stripe connection
+ * gets the route's same 404, never a session on the hub's own env key, so
+ * this tool refuses it as the web buy route does (#9126).
+ *
+ * Spec: `docs/specs/5971-start-purchase-hosted-checkout-spec.md`,
+ * `docs/specs/8935-start-purchase-sells-a-named-spec.md`.
  */
 
 import { checkout } from "@working-theory/api-client";
 import {
+  parseLookupKey,
   purchaseMcpInputSchema,
   type PurchaseMcpInput,
   type PurchaseOutput,
@@ -83,6 +96,15 @@ function commerceDisabledBody(): ErrorBody {
   return notFoundError("Not found");
 }
 
+/**
+ * The one not-found body for an offering (#8935 D2, A5): an ungrammatical key
+ * refused before the call and every route 404 answer this same value, and
+ * neither echoes the caller's key.
+ */
+function offeringNotFoundBody(): ErrorBody {
+  return notFoundError("No offering matches that product code.");
+}
+
 /**
  * Export name `ailkPurchase` satisfies the parity-test naming convention
  * (ailk<PascalVerb>) so the harness can discover it.
@@ -127,6 +149,12 @@ export async function ailkPurchase(
 
   const { productCode, quantity } = parsed.data;
 
+  // #8935 D2 — a key outside the §3.7 grammar can never sell, so it is
+  // refused here, before the route spends a rate-limit token on it.
+  if (parseLookupKey(productCode) === null) {
+    return offeringNotFoundBody();
+  }
+
   // 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.
@@ -152,7 +180,7 @@ export async function ailkPurchase(
       // 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 offeringNotFoundBody();
     }
     return validationError(
       `checkout-unavailable: POST /v1/checkout/sessions returned ${result.status}`,

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

@@ -1,40 +1,58 @@
 /**
- * read_content — returns a single page's frontmatter + raw MDX body.
+ * read_content — returns a single page's document: its schema.org JSON-LD at
+ * the root, its frontmatter under `page`, and the raw MDX body on request.
  *
- * 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.
+ * Pure read: resolves its adapter through `getMcpContentAdapter()` — the one
+ * resolver seam (#5805, ADR 0011), MDX by default — and answers through
+ * `readContentDocument` (`@working-theory/content-adapters`), over the
+ * deployment's `_site.mdx` (`lib/site-config.ts`). A missing page is the MCP
+ * not-found body (`lib/errors.ts`), carrying the route's 404 message — never
+ * a throw.
+ *
+ * HTTP twin (#7169): `GET /v1/content/:type/:slug` in `apps/api` parses the
+ * same `contentPageParamsSchema` + `contentPageQuerySchema` and answers
+ * through the same builder — the tool adopted the API, arguments and results:
+ * `body` is served only with `include: "body"`, from ONE `getPageSource`
+ * read (#5927). The builder's own capability check replaces the retired
+ * MDX-narrowed resolver twin this tool used to call: every adapter the
+ * resolver returns carries `getPageSource`, the fail-closed empty one
+ * included (#5876 D5).
  *
  * Phase 3 S3: optional `locale` parameter. Validated against `readLocales()`
  * 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 } — `type`
- *         admits the full SchemaOrgType set (#6030 D1), mirrored in
- *         @working-theory/validation's MCP_SCHEMA_ORG_TYPES.
- * Output: { slug, type, frontmatter, body } | null
+ * Input:  { type: SchemaOrgType, slug: string, locale?: string,
+ *           include?: "body" } — `type` admits the full SchemaOrgType set
+ *         (#6030 D1), mirrored in @working-theory/validation's
+ *         MCP_SCHEMA_ORG_TYPES.
+ * Output: { ...jsonLd, page, body? } | { error: "not_found", message }
  * Session/scope: none — read-only public content.
  */
 
+import { readContentDocument } from "@working-theory/content-adapters";
 import {
-  readContentInputSchema,
-  readContentOutputSchema,
+  contentPageParamsSchema,
+  contentPageQuerySchema,
+  contentPageResultSchema,
+  type ContentPageResult,
   type ReadContentInput,
-  type ReadContentOutput,
 } from "@working-theory/validation";
 
 import {
-  getMcpMdxContentAdapter,
+  getMcpContentAdapter,
   mcpContentRoot,
 } from "../lib/content-adapter.js";
+import { notFoundError, type ErrorBody } from "../lib/errors.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
+import { readSiteConfig } from "../lib/site-config.js";
 
-export { readContentInputSchema, readContentOutputSchema };
-export type { ReadContentInput, ReadContentOutput };
+export {
+  contentPageParamsSchema,
+  contentPageQuerySchema,
+  contentPageResultSchema,
+};
+export type { ReadContentInput, ContentPageResult };
 
 /**
  * read_content handler.
@@ -45,31 +63,19 @@ export type { ReadContentInput, ReadContentOutput };
 export async function ailkReadContent(
   input: ReadContentInput,
   contentRoot?: string,
-): Promise<ReadContentOutput> {
-  readContentInputSchema.parse(input);
+): Promise<ContentPageResult | ErrorBody> {
+  const { type, slug } = contentPageParamsSchema.parse(input);
+  const { include } = contentPageQuerySchema.parse(input);
 
   // Default: the one content-root resolver (#8070 D3).
   const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
+  const adapter = getMcpContentAdapter({ contentRoot: root, 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({
-    // 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,
-  });
+  const document = await readContentDocument(
+    adapter,
+    { type, slug, locale, include },
+    readSiteConfig(root),
+  );
+  return document ?? notFoundError("Page not found");
 }

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

@@ -1,32 +1,35 @@
 /**
- * request_callback — schedule a callback request.
+ * request_callback — request a callback: the body `POST /v1/leads/callback`
+ * takes.
  *
- * Validates input via Zod, forwards to POST /api/leads/callback via
- * @working-theory/api-client, and shapes the response into the MCP output schema.
- * No business logic — orchestration lives in apps/api B6.
+ * The tool adopted the API, arguments and results (#7173 — the operator's
+ * decision of 2026-10-19). Its input IS the route's `leadCallbackBodySchema`
+ * (`{ name, phone, preferredTime?, payload? }`; the catalog registers the
+ * same shape, so the SDK has already parsed the arguments against it — the
+ * `safeParse` here keeps the stdio path and the `invalid_input` branch
+ * honest), the parsed body is posted as the agent sent it — no `siteId`, no
+ * stamped `payload: {}` — and the route's 201 body `{ id, persisted, email }`
+ * comes back unchanged. No business logic — orchestration lives in apps/api.
  *
- * Input:  { name, phone, preferredTime? }
- * Output: { ok: true, id, persisted } | { ok: false, error: { kind, ... } }
  * Session/scope: none — anonymous write, no auth required.
  */
 
 import { apiClient } from "@working-theory/api-client";
 import {
-  requestCallbackInputSchema,
-  requestCallbackOutputSchema,
-  type RequestCallbackInput,
-  type RequestCallbackOutput,
+  leadCallbackBodySchema,
+  type LeadCallbackBody,
+  type LeadWriteOutput,
 } from "@working-theory/validation";
 
 import { visitorForwardHeadersForThisCall } from "../request-context.js";
 
-export { requestCallbackInputSchema, requestCallbackOutputSchema };
-export type { RequestCallbackInput, RequestCallbackOutput };
+export { leadCallbackBodySchema };
+export type { LeadCallbackBody };
 
 export async function ailkRequestCallback(
-  input: RequestCallbackInput,
-): Promise<RequestCallbackOutput> {
-  const parsed = requestCallbackInputSchema.safeParse(input);
+  input: LeadCallbackBody,
+): Promise<LeadWriteOutput> {
+  const parsed = leadCallbackBodySchema.safeParse(input);
   if (!parsed.success) {
     return {
       ok: false,
@@ -34,26 +37,16 @@ export async function ailkRequestCallback(
     };
   }
 
-  const { name, phone, preferredTime } = parsed.data;
-  const siteId = process.env.AILK_SITE_ID ?? "default";
-  const body = {
-    siteId,
-    name,
-    phone,
-    ...(preferredTime !== undefined && { preferredTime }),
-    payload: {},
-  };
-
   // #8073 — forward the address the transport trusted (never an identity
   // argument on this tool's own schema) so the hub counts the write in that
   // visitor's own rate-limit bucket rather than this MCP host's.
   const headers = visitorForwardHeadersForThisCall();
   const res = headers
-    ? await apiClient.leads.callback(body, { headers })
-    : await apiClient.leads.callback(body);
+    ? await apiClient.leads.callback(parsed.data, { headers })
+    : await apiClient.leads.callback(parsed.data);
   if (!res.ok) {
     return { ok: false, error: { kind: "api_error", status: res.status } };
   }
 
-  return { ok: true, id: res.body.id, persisted: res.body.persisted };
+  return res.body;
 }

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

@@ -2,9 +2,14 @@
  * search_content — full-text search across published content pages.
  *
  * 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).
+ * resolver seam (#5805, ADR 0011), MDX by default — and answers through
+ * `searchContentItemList` (`@working-theory/content-adapters`), which scores by
+ * title/description/body match through `adapter.searchPages`.
+ *
+ * HTTP twin (#7167): `GET /v1/content/search` in `apps/api` parses the same
+ * `contentSearchQuerySchema` and answers through the same builder — the tool
+ * adopted the API, arguments and results. Limit defaults to 10; max 50. The
+ * search string `q` is capped at 200 chars (enforced by Zod).
  *
  * Phase 3 S3: optional `locale` parameter. Search is locale-scoped — only the
  * requested locale's content directory is searched. Invalid or unknown values
@@ -14,17 +19,19 @@
  * 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,
+ * Input:  { q: string, type?: SchemaOrgType, category?: CategorySlug,
  *           limit?: number, locale?: string }
- * Output: { results: Array<{ slug, type, title, snippet, score }> }
+ * Output: { "@context", "@type": "ItemList", query, items: Array<{ slug, type,
+ *           title, snippet, score }>, totalItems }
  * Session/scope: none — read-only public content.
  */
 
+import { searchContentItemList } from "@working-theory/content-adapters";
 import {
-  searchContentInputSchema,
-  searchContentOutputSchema,
+  contentSearchQuerySchema,
+  contentSearchResultSchema,
+  type ContentSearchResult,
   type SearchContentInput,
-  type SearchContentOutput,
 } from "@working-theory/validation";
 
 import {
@@ -33,10 +40,8 @@ import {
 } from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
-export { searchContentInputSchema, searchContentOutputSchema };
-export type { SearchContentInput, SearchContentOutput };
-
-const DEFAULT_LIMIT = 10;
+export { contentSearchQuerySchema, contentSearchResultSchema };
+export type { SearchContentInput, ContentSearchResult };
 
 /**
  * search_content handler.
@@ -47,21 +52,12 @@ const DEFAULT_LIMIT = 10;
 export async function ailkSearchContent(
   input: SearchContentInput,
   contentRoot?: string,
-): Promise<SearchContentOutput> {
-  searchContentInputSchema.parse(input);
+): Promise<ContentSearchResult> {
+  const { q, type, category, limit } = contentSearchQuerySchema.parse(input);
 
   const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.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,
-  };
-
-  const rawResults = await adapter.searchPages(input.query, options);
-
-  return searchContentOutputSchema.parse({ results: rawResults });
+  return searchContentItemList(adapter, { q, type, category, limit, locale });
 }