create-ailk 0.17.0 → 0.18.0

package/templates/apps/mcp/src/serverless-app.ts

@@ -0,0 +1,88 @@
+/**
+ * The testable part of the Vercel entry (#8070 D2, D5).
+ *
+ * `src/app.ts` is the thin file Vercel's Node-backend detection finds: it
+ * awaits the boot at module level and default-exports the
+ * {@link serverlessHandler} for the app. A module-level
+ * `await` does not compile under the package's ts-jest CommonJS preset, so
+ * everything app.ts does beyond that lives here, where a test can build the
+ * same app (`__tests__/app-entry.test.ts`).
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { FastifyInstance } from "fastify";
+
+import { httpTransportConfigFromEnv, readStatelessEnv } from "./boot.js";
+import { registerHttpTransport } from "./http-transport.js";
+
+/**
+ * Trust exactly one proxy hop — the immediate peer — and nothing behind it
+ * (D5). Fastify then takes `request.ip` from the LAST `X-Forwarded-For`
+ * entry, the address Vercel's edge saw, and a value a caller writes earlier
+ * in the header cannot move it.
+ *
+ * A function, not `trustProxy: 1`: Fastify 5.12 treats a numeric hop count as
+ * trust-nothing ("hop-count-only trust cannot validate the immediate peer"),
+ * so `1` would silently key every caller on the edge's address. A hop-only
+ * function is safe here for the reason Fastify's warning names: a Vercel
+ * function cannot be reached except through Vercel's edge, so its immediate
+ * peer is always the edge. It would NOT be safe on a host a client can reach
+ * directly — which is why the long-running entry (`buildHttpTransportApp`)
+ * sets no `trustProxy` at all.
+ *
+ * Trusting hop 0 also makes `request.host` and `request.protocol` follow
+ * `X-Forwarded-Host` / `X-Forwarded-Proto`. Nothing in apps/mcp reads either
+ * today; anything that starts to must remember they come from the edge.
+ */
+export function trustOneHop(_address: string, hop: number): boolean {
+  return hop === 0;
+}
+
+/**
+ * The Fastify options the Vercel entry builds its app with: no logger, and
+ * {@link trustOneHop} — so the per-IP rate limit and the daily caps key on
+ * the real caller. That holds for the topology the sites deploy: the MCP host
+ * name points straight at the Vercel project. A second proxy in front
+ * (Cloudflare in proxied mode, a rewrite from another Vercel project) would
+ * make every caller that proxy's address.
+ */
+export const SERVERLESS_FASTIFY_OPTIONS = {
+  logger: false,
+  trustProxy: trustOneHop,
+} as const;
+
+/**
+ * Register the MCP HTTP transport on the Vercel entry's app, from the
+ * environment. Stateless unless `MCP_HTTP_STATELESS` says otherwise (D1): a
+ * stateful transport keeps its sessions in one instance's memory, which a
+ * multi-instance host cannot honour. The port is read and ignored — Vercel
+ * calls the exported {@link serverlessHandler} and nothing listens.
+ */
+export async function configureServerlessApp(
+  app: FastifyInstance,
+): Promise<void> {
+  const { port: _port, ...config } = httpTransportConfigFromEnv();
+  await registerHttpTransport(app, {
+    ...config,
+    stateless: readStatelessEnv(true),
+  });
+}
+
+/**
+ * The `(req, res)` function the Vercel entry default-exports (#8070 D2,
+ * amendment 2). Vercel's Node runtime accepts a request function, an object of
+ * web handlers, or an `http.Server` the module starts listening — a Fastify
+ * instance is none of these, and exporting one answered every request with a
+ * 500. `app.server` is the `http.Server` Fastify builds without listening;
+ * emitting `request` on it is Fastify's own request path, so routing,
+ * `trustProxy` and every hook behave as on a listening server. The app must
+ * already be `ready()`.
+ */
+export function serverlessHandler(
+  app: FastifyInstance,
+): (req: IncomingMessage, res: ServerResponse) => void {
+  return (req, res) => {
+    app.server.emit("request", req, res);
+  };
+}

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

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   getBusinessHoursInputSchema,
   getBusinessHoursOutputSchema,
@@ -24,7 +22,10 @@ import {
   type GetBusinessHoursOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getBusinessHoursInputSchema, getBusinessHoursOutputSchema };
@@ -36,7 +37,7 @@ const DEFAULT_SLUG = "home";
  * get_business_hours handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkGetBusinessHours(
   input: GetBusinessHoursInput,
@@ -44,7 +45,7 @@ export async function ailkGetBusinessHours(
 ): Promise<GetBusinessHoursOutput> {
   getBusinessHoursInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

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

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   getFaqInputSchema,
   getFaqOutputSchema,
@@ -24,7 +22,10 @@ import {
   type GetFaqOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getFaqInputSchema, getFaqOutputSchema };
@@ -36,7 +37,7 @@ const DEFAULT_SLUG = "faq";
  * get_faq handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkGetFaq(
   input: GetFaqInput,
@@ -44,7 +45,7 @@ export async function ailkGetFaq(
 ): Promise<GetFaqOutput> {
   getFaqInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

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

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
 import {
   getLocationsInputSchema,
@@ -25,7 +23,10 @@ import {
   type GetLocationsOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getLocationsInputSchema, getLocationsOutputSchema };
@@ -35,7 +36,7 @@ export type { GetLocationsInput, GetLocationsOutput };
  * get_locations handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkGetLocations(
   input: GetLocationsInput,
@@ -43,7 +44,7 @@ export async function ailkGetLocations(
 ): Promise<GetLocationsOutput> {
   getLocationsInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

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

@@ -21,8 +21,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import { type SchemaOrgType } from "@working-theory/content-adapters";
 import {
   getOfferingsInputSchema,
@@ -31,7 +29,10 @@ import {
   type GetOfferingsOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getOfferingsInputSchema, getOfferingsOutputSchema };
@@ -41,7 +42,7 @@ export type { GetOfferingsInput, GetOfferingsOutput };
  * get_offerings handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkGetOfferings(
   input: GetOfferingsInput,
@@ -49,7 +50,7 @@ export async function ailkGetOfferings(
 ): Promise<GetOfferingsOutput> {
   getOfferingsInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

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

@@ -21,8 +21,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   getPricingInputSchema,
   getPricingOutputSchema,
@@ -30,7 +28,10 @@ import {
   type GetPricingOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getPricingInputSchema, getPricingOutputSchema };
@@ -42,7 +43,7 @@ const DEFAULT_SLUG = "pricing";
  * get_pricing handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkGetPricing(
   input: GetPricingInput,
@@ -50,7 +51,7 @@ export async function ailkGetPricing(
 ): Promise<GetPricingOutput> {
   getPricingInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

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

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   getSiteInfoInputSchema,
   getSiteInfoOutputSchema,
@@ -24,7 +22,10 @@ import {
   type GetSiteInfoOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { getSiteInfoInputSchema, getSiteInfoOutputSchema };
@@ -36,7 +37,7 @@ const DEFAULT_SLUG = "home";
  * get_site_info handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkGetSiteInfo(
   input: GetSiteInfoInput,
@@ -44,7 +45,7 @@ export async function ailkGetSiteInfo(
 ): Promise<GetSiteInfoOutput> {
   getSiteInfoInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

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

@@ -15,8 +15,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   SCHEMA_ORG_TYPES,
   type SchemaOrgType,
@@ -28,7 +26,10 @@ import {
   type ListPagesOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { listPagesInputSchema, listPagesOutputSchema };
@@ -38,8 +39,8 @@ export type { ListPagesInput, ListPagesOutput };
  * list_pages handler.
  *
  * Accepts an optional `contentRoot` override for testing (avoids coupling
- * unit tests to the deployed filesystem layout). When omitted, resolves the
- * content root relative to this file at call time (supports ESM runtime).
+ * unit tests to the deployed filesystem layout). When omitted, resolves it
+ * through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkListPages(
   input: ListPagesInput,
@@ -47,8 +48,8 @@ export async function ailkListPages(
 ): Promise<ListPagesOutput> {
   listPagesInputSchema.parse(input);
 
-  // Default: resolve content/ relative to cwd (works in ESM and jest/commonjs).
-  const root = contentRoot ?? join(process.cwd(), "content");
+  // Default: the one content-root resolver (#8070 D3).
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

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

@@ -20,8 +20,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   readContentInputSchema,
   readContentOutputSchema,
@@ -29,7 +27,10 @@ import {
   type ReadContentOutput,
 } from "@working-theory/validation";
 
-import { getMcpMdxContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpMdxContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { readContentInputSchema, readContentOutputSchema };
@@ -39,8 +40,7 @@ export type { ReadContentInput, ReadContentOutput };
  * read_content handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to this file at call time (supports
- * ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkReadContent(
   input: ReadContentInput,
@@ -48,8 +48,8 @@ export async function ailkReadContent(
 ): Promise<ReadContentOutput> {
   readContentInputSchema.parse(input);
 
-  // Default: resolve content/ relative to cwd (works in ESM and jest/commonjs).
-  const root = contentRoot ?? join(process.cwd(), "content");
+  // Default: the one content-root resolver (#8070 D3).
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
 
   const adapter = getMcpMdxContentAdapter({ contentRoot: root, locale });

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

@@ -20,8 +20,6 @@
  * Session/scope: none — read-only public content.
  */
 
-import { join } from "node:path";
-
 import {
   searchContentInputSchema,
   searchContentOutputSchema,
@@ -29,7 +27,10 @@ import {
   type SearchContentOutput,
 } from "@working-theory/validation";
 
-import { getMcpContentAdapter } from "../lib/content-adapter.js";
+import {
+  getMcpContentAdapter,
+  mcpContentRoot,
+} from "../lib/content-adapter.js";
 import { resolveLocale } from "../lib/resolve-locale.js";
 
 export { searchContentInputSchema, searchContentOutputSchema };
@@ -41,7 +42,7 @@ const DEFAULT_LIMIT = 10;
  * search_content handler.
  *
  * Accepts an optional `contentRoot` override for testing. When omitted,
- * resolves the content root relative to cwd (supports ESM runtime).
+ * resolves it through `mcpContentRoot()` (#8070 D3).
  */
 export async function ailkSearchContent(
   input: SearchContentInput,
@@ -49,7 +50,7 @@ export async function ailkSearchContent(
 ): Promise<SearchContentOutput> {
   searchContentInputSchema.parse(input);
 
-  const root = contentRoot ?? join(process.cwd(), "content");
+  const root = contentRoot ?? mcpContentRoot();
   const locale = resolveLocale(input.locale);
   const adapter = getMcpContentAdapter({ contentRoot: root, locale });
 

package/templates/apps/mcp/tsconfig.json

@@ -4,6 +4,8 @@
     "outDir": "./dist",
     "rootDir": "./src",
     "composite": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "types": ["node"]
   },
   "include": ["src"],

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

@@ -19,6 +19,11 @@
  * Issue #7396 — `mcpEndpoint` is the configured MCP HTTP host or absent. It
  * was `${baseUrl}/api/mcp`, a path apps/web does not serve, so every agent
  * that followed it got a 404.
+ * Issue #8070 — `unservedTools` drops the tools this topology's MCP server
+ * does not register (`create_project` on a spoke).
+ * Issue #8057 — `description` resolves from SITE_DESCRIPTION
+ * (`siteIdentity.description` in _site.mdx → neutral default) instead of the
+ * template's own blurb on every site.
  */
 
 import {
@@ -27,7 +32,7 @@ import {
   type McpToolCatalogEntry,
 } from "@working-theory/metadata";
 
-import { SITE_NAME } from "../../../lib/site-brand";
+import { SITE_DESCRIPTION, SITE_NAME } from "../../../lib/site-brand";
 
 /**
  * Inline transport descriptor shape — mirrors McpTransportDescriptor from
@@ -107,6 +112,14 @@ export interface BuildMcpManifestOptions {
   /** Overrides `MCP_FEATURE_GATE_MODE` — a test seam; `route.ts` never
    * passes it. */
   featureGate?: McpCatalogOptions["featureGate"];
+  /**
+   * Tool names this site's MCP server does not serve (#8070 D7) — the
+   * topology seam's `UNSERVED_MCP_TOOLS`: `create_project` on a spoke, none
+   * on a hub. Dropped from `tools`, so the manifest never advertises a tool
+   * the server will not register. Injected, like `commerceClaimed`. Omitted ⇒
+   * none dropped.
+   */
+  unservedTools?: readonly string[];
 }
 
 /** MCP HTTP transport version this server implements. */
@@ -132,8 +145,7 @@ export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
   return {
     schemaVersion: "1",
     name: SITE_NAME,
-    description:
-      "AX-first OSS template — ship software with API + MCP as canonical agent surfaces.",
+    description: SITE_DESCRIPTION,
     // Spread conditional to satisfy exactOptionalPropertyTypes: the key is
     // absent, not undefined, when no MCP HTTP host is configured.
     ...(opts.mcpHttpUrl ? { mcpEndpoint: opts.mcpHttpUrl } : {}),
@@ -141,7 +153,7 @@ export function buildMcpManifest(opts: BuildMcpManifestOptions): McpManifest {
       addons: { commerce: opts.commerceClaimed === true },
       features: opts.heldFeatures ?? [],
       ...(opts.featureGate ? { featureGate: opts.featureGate } : {}),
-    }),
+    }).filter((tool) => !(opts.unservedTools ?? []).includes(tool.name)),
     transport: {
       type: "http",
       version: MCP_HTTP_VERSION,

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

@@ -26,6 +26,7 @@
  * is appropriate per the MCP discovery spec.
  */
 
+import { UNSERVED_MCP_TOOLS } from "../../../lib/topology.generated";
 import packageJson from "../../../package.json";
 import {
   COMMERCE_FEATURE,
@@ -59,6 +60,8 @@ export async function GET(): Promise<Response> {
     ailkVersion: packageJson.version,
     commerceClaimed: heldFeatures.includes(COMMERCE_FEATURE),
     heldFeatures,
+    // The tools this topology's MCP server does not register (#8070 D7).
+    unservedTools: UNSERVED_MCP_TOOLS,
     // Spread conditional to satisfy exactOptionalPropertyTypes: omit the key
     // entirely when the env var is not set rather than passing undefined.
     ...(mcpHttpUrlEnv ? { mcpHttpUrl: mcpHttpUrlEnv } : {}),

package/templates/apps/web/app/[locale]/(authed)/account/actions.ts

@@ -13,10 +13,24 @@
  * navigation telemetry for a Server Action, which is inherent to any hosted-
  * portal handoff, not something this design avoids).
  *
- * CSRF is already handled: `forwardedCookieInit()` forwards the incoming
- * request's real `Origin` alongside the cookie, and `apps/api`'s
- * `authPreHandler` requires a matching `Origin` on this cookie-authenticated
- * mutating request (D3.1/D5).
+ * CSRF protection depends on the render (`forwardedCookieInit()` branches on
+ * `SIGN_IN_PROVIDER`, `lib/server-api.ts`):
+ *
+ * - Hub render (`SIGN_IN_PROVIDER === "site"`): `forwardedCookieInit()`
+ *   forwards the incoming request's real `Origin` alongside the Better Auth
+ *   cookie, and `apps/api`'s `authPreHandler` requires that `Origin` to be one
+ *   of its trusted origins on this cookie-authenticated mutating request
+ *   (`isOriginAllowed`, `middleware/auth.ts`). The portal-session route also
+ *   accepts only a cookie session (`request.sessionTenant`), never a bearer
+ *   (D3.1/D5).
+ * - Spoke render, sign-in through the hub (`SIGN_IN_PROVIDER === "hub"`):
+ *   there is no cookie and no `Origin` forward. `hubSessionInit()`
+ *   (`lib/hub-session/session.ts`) sends the sealed session's credential as
+ *   `Authorization: Bearer`, and `authPreHandler` skips its origin check for a
+ *   bearer. This action does not complete on a spoke: the hub admits a hub
+ *   credential on four read routes only (`HUB_SESSION_ROUTES`), so
+ *   `POST /v1/subscription/portal-session` is a 404 there, and Settings hides
+ *   the Billing button because `subscription.me()` is a 404 too.
  *
  * `redirect()` throws `NEXT_REDIRECT` by design — called OUTSIDE the
  * try/catch (mirrors `checkout.actions.ts`'s idiom) so the catch never

package/templates/apps/web/lib/__tests__/site-brand.test.ts

@@ -170,6 +170,48 @@ describe("COPYRIGHT_HOLDER (#7796)", () => {
   });
 });
 
+/**
+ * `SITE_DESCRIPTION` — `siteIdentity.description`, else a neutral fallback
+ * that never names the template (#8057).
+ */
+describe("SITE_DESCRIPTION (#8057)", () => {
+  function writeDescription(identityLines: string): void {
+    writeFileSync(
+      join(tmpRoot, "_site.mdx"),
+      `---\nsiteName: Fixture Co\nsiteIdentity:\n  kind: Organization\n  name: Fixture Co\n${identityLines}---\n`,
+    );
+    process.env["AILK_CONTENT_ROOT"] = tmpRoot;
+    delete process.env["NEXT_PUBLIC_SITE_NAME"];
+  }
+
+  it("is siteIdentity.description when the site declares one (folded scalar trimmed)", async () => {
+    writeDescription("  description: >\n    Fixture Co sells widgets.\n");
+    const { SITE_DESCRIPTION } = await loadSiteBrand();
+
+    expect(SITE_DESCRIPTION).toBe("Fixture Co sells widgets.");
+  });
+
+  it("falls back to a neutral description that does not mention the template", async () => {
+    writeDescription("");
+    const { SITE_DESCRIPTION, FALLBACK_SITE_DESCRIPTION } =
+      await loadSiteBrand();
+
+    expect(SITE_DESCRIPTION).toBe(FALLBACK_SITE_DESCRIPTION);
+    expect(SITE_DESCRIPTION).not.toMatch(/template/i);
+    expect(SITE_DESCRIPTION).not.toMatch(/AX-first/);
+  });
+
+  it("falls back when description is blank or _site.mdx is absent", async () => {
+    writeDescription('  description: "   "\n');
+    let mod = await loadSiteBrand();
+    expect(mod.SITE_DESCRIPTION).toBe(mod.FALLBACK_SITE_DESCRIPTION);
+
+    rmSync(join(tmpRoot, "_site.mdx"));
+    mod = await loadSiteBrand();
+    expect(mod.SITE_DESCRIPTION).toBe(mod.FALLBACK_SITE_DESCRIPTION);
+  });
+});
+
 /**
  * `siteLogo()` — the brand triad's logomark (#6820 D5). No `brand:` renders
  * exactly today's element; a declared mark is the one rendered, with its dark

package/templates/apps/web/lib/site-brand.tsx

@@ -36,6 +36,12 @@ import { parse as parseYaml } from "yaml";
 export const FALLBACK_SITE_NAME = "My Site";
 /** Neutral, non-vendor fallback — see module doc comment point 3. */
 export const FALLBACK_BASE_URL = "https://example.com";
+/**
+ * Neutral fallback for the site description (#8057) — says what the site
+ * exposes to agents without naming the template or any vendor.
+ */
+export const FALLBACK_SITE_DESCRIPTION =
+  "A website with an HTTP API and an MCP server for AI agents.";
 
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
 
@@ -49,6 +55,8 @@ interface SiteFrontmatter {
   logomark?: unknown;
   /** `siteIdentity.legalName`, when declared as a non-empty string. */
   legalName?: string | undefined;
+  /** `siteIdentity.description`, when declared as a non-empty string. */
+  description?: string | undefined;
 }
 
 /**
@@ -90,15 +98,15 @@ function readSiteFrontmatter(): SiteFrontmatter | null {
       string,
       unknown
     >;
-    const legalName =
+    const identity =
       siteIdentity && typeof siteIdentity === "object"
-        ? (siteIdentity as Record<string, unknown>).legalName
+        ? (siteIdentity as Record<string, unknown>)
         : undefined;
+    const nonEmpty = (v: unknown): string | undefined =>
+      typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
     return {
-      legalName:
-        typeof legalName === "string" && legalName.trim().length > 0
-          ? legalName.trim()
-          : undefined,
+      legalName: nonEmpty(identity?.legalName),
+      description: nonEmpty(identity?.description),
       siteName: typeof siteName === "string" ? siteName : undefined,
       baseUrl: typeof baseUrl === "string" ? baseUrl : undefined,
       logomark:
@@ -125,6 +133,14 @@ export const SITE_NAME =
 export const SITE_BASE_URL =
   process.env.NEXT_PUBLIC_BASE_URL ?? siteFrontmatter?.baseUrl ?? FALLBACK_BASE_URL;
 
+/**
+ * The site's own description (#8057): `siteIdentity.description` from
+ * `_site.mdx`, else a neutral fallback that never names the template. Surfaced
+ * to agents by `/.well-known/mcp.json`.
+ */
+export const SITE_DESCRIPTION =
+  siteFrontmatter?.description ?? FALLBACK_SITE_DESCRIPTION;
+
 /**
  * The footer copyright holder (#7796): `siteIdentity.legalName` when the site
  * declares one (schema.org's `Organization.legalName` — the owning entity,