create-ailk 0.16.0 → 0.18.0

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/app/openapi.json/__tests__/route.test.ts

@@ -15,6 +15,13 @@
 
 import { GET } from "../route";
 
+// The REAL committed seam, for the #8060 hub-only guards: the mock below
+// shadows `TOPOLOGY` per case, but whether a hub-only case runs depends on the
+// render this scaffold carries, not on the topology a case picks.
+const { TOPOLOGY: SEAM_TOPOLOGY } = jest.requireActual<
+  typeof import("../../../lib/topology.generated")
+>("../../../lib/topology.generated");
+
 // The generated topology seam (#7426 D5), mocked so each case picks its
 // topology: the hub cases below run against `"hub"`, exactly as before; the
 // spoke cases (D12) flip it. Mocked rather than imported because the hub
@@ -93,17 +100,21 @@ describe("GET /openapi.json", () => {
     expect(requestedUrl()).toBe("http://api.internal:4000/v1/openapi.json");
   });
 
-  it("falls back to NEXT_PUBLIC_AILK_API_URL, then the local-dev API origin", async () => {
-    apiAnswers(200, JSON.stringify(SPEC));
-    await GET();
-    expect(requestedUrl()).toBe("http://localhost:3001/v1/openapi.json");
-
-    fetchSpy.mockClear();
-    process.env["NEXT_PUBLIC_AILK_API_URL"] = "https://api.example.com/";
-    apiAnswers(200, JSON.stringify(SPEC));
-    await GET();
-    expect(requestedUrl()).toBe("https://api.example.com/v1/openapi.json");
-  });
+  // #8060 — hub-only: a spoke render of the seam does not run this case.
+  (SEAM_TOPOLOGY === "hub" ? it : it.skip)(
+    "falls back to NEXT_PUBLIC_AILK_API_URL, then the local-dev API origin",
+    async () => {
+      apiAnswers(200, JSON.stringify(SPEC));
+      await GET();
+      expect(requestedUrl()).toBe("http://localhost:3001/v1/openapi.json");
+
+      fetchSpy.mockClear();
+      process.env["NEXT_PUBLIC_AILK_API_URL"] = "https://api.example.com/";
+      apiAnswers(200, JSON.stringify(SPEC));
+      await GET();
+      expect(requestedUrl()).toBe("https://api.example.com/v1/openapi.json");
+    },
+  );
 
   // #7874 D12 — the hub case above runs the committed (hub) render of the
   // browser API origin seam unmocked; the spoke render reads no env at all.
@@ -141,23 +152,30 @@ describe("GET /openapi.json", () => {
     expect(response.headers.get("cache-control")).toBe("no-store");
   });
 
-  it("resolves a relative servers[] URL against the public API origin", async () => {
-    process.env["AILK_API_URL"] = "http://api.internal:4000";
-    process.env["NEXT_PUBLIC_AILK_API_URL"] = "https://api.example.com/";
-    apiAnswers(
-      200,
-      JSON.stringify({ ...SPEC, servers: [{ url: "/", description: "x" }] }),
-    );
-
-    const body = (await (await GET()).json()) as typeof SPEC & {
-      servers: Array<{ url: string }>;
-    };
-
-    expect(requestedUrl()).toBe("http://api.internal:4000/v1/openapi.json");
-    expect(body.servers).toEqual([
-      { url: "https://api.example.com", description: "This deployment's API" },
-    ]);
-  });
+  // #8060 — hub-only: a spoke render of the seam does not run this case.
+  (SEAM_TOPOLOGY === "hub" ? it : it.skip)(
+    "resolves a relative servers[] URL against the public API origin",
+    async () => {
+      process.env["AILK_API_URL"] = "http://api.internal:4000";
+      process.env["NEXT_PUBLIC_AILK_API_URL"] = "https://api.example.com/";
+      apiAnswers(
+        200,
+        JSON.stringify({ ...SPEC, servers: [{ url: "/", description: "x" }] }),
+      );
+
+      const body = (await (await GET()).json()) as typeof SPEC & {
+        servers: Array<{ url: string }>;
+      };
+
+      expect(requestedUrl()).toBe("http://api.internal:4000/v1/openapi.json");
+      expect(body.servers).toEqual([
+        {
+          url: "https://api.example.com",
+          description: "This deployment's API",
+        },
+      ]);
+    },
+  );
 
   it("resolves a relative servers[] URL against AILK_API_URL when no public origin is set", async () => {
     process.env["AILK_API_URL"] = "http://localhost:3700";

package/templates/apps/web/lib/__tests__/relay.test.ts

@@ -12,6 +12,7 @@
 
 import { handleRelay, RELAY_ROUTES } from "../relay";
 import { __resetRelayRateLimit, __relayRateLimitBucketCount } from "../relay";
+import { TOPOLOGY } from "../topology.generated";
 
 const HUB = "https://hub.example";
 const SITE = "https://spoke.example";
@@ -516,13 +517,18 @@ describe("hardening — what the site serves, and a missing hub address", () =>
 
     // #7874 D12 — the fallback reads the browser API origin seam. The
     // committed seam is the hub render, so this case runs it unmocked.
-    it("on a hub, NEXT_PUBLIC_AILK_API_URL alone still counts as a hub address", async () => {
-      delete process.env.AILK_API_URL;
-      process.env.NEXT_PUBLIC_AILK_API_URL = HUB;
-      const res = await handleRelay(relayRequest("/v1/leads/submit"));
-      expect(res.status).toBe(201);
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-    });
+    // #8060 — hub-only: a spoke render of the seam reads no
+    // NEXT_PUBLIC_AILK_API_URL, so a spoke scaffold skips this case.
+    (TOPOLOGY === "hub" ? it : it.skip)(
+      "on a hub, NEXT_PUBLIC_AILK_API_URL alone still counts as a hub address",
+      async () => {
+        delete process.env.AILK_API_URL;
+        process.env.NEXT_PUBLIC_AILK_API_URL = HUB;
+        const res = await handleRelay(relayRequest("/v1/leads/submit"));
+        expect(res.status).toBe(201);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+      },
+    );
 
     it("on a spoke (the seam's spoke render), that fallback is skipped", async () => {
       delete process.env.AILK_API_URL;

package/templates/apps/web/lib/__tests__/server-api.test.ts

@@ -11,6 +11,7 @@
  * sets `Origin`.
  */
 import { forwardedCookieInit } from "../server-api";
+import { TOPOLOGY } from "../topology.generated";
 
 const mockCookies = jest.fn();
 const mockHeaders = jest.fn();
@@ -27,35 +28,43 @@ describe("forwardedCookieInit", () => {
     mockHeaders.mockReset();
   });
 
-  it("forwards cookie + origin when the incoming request carries an Origin header", async () => {
-    mockCookies.mockResolvedValue({
-      toString: () => "better-auth.session_token=abc",
-    });
-    mockHeaders.mockResolvedValue(
-      new Headers({ origin: "https://app.example.com" }),
-    );
-
-    const init = await forwardedCookieInit();
-
-    expect(init).toEqual({
-      headers: {
-        cookie: "better-auth.session_token=abc",
-        origin: "https://app.example.com",
-      },
-    });
-  });
+  // #8060 — hub-only: a spoke render of the seam does not run this case.
+  (TOPOLOGY === "hub" ? it : it.skip)(
+    "forwards cookie + origin when the incoming request carries an Origin header",
+    async () => {
+      mockCookies.mockResolvedValue({
+        toString: () => "better-auth.session_token=abc",
+      });
+      mockHeaders.mockResolvedValue(
+        new Headers({ origin: "https://app.example.com" }),
+      );
 
-  it("forwards cookie alone — no origin key at all — when Origin is absent", async () => {
-    mockCookies.mockResolvedValue({
-      toString: () => "better-auth.session_token=abc",
-    });
-    mockHeaders.mockResolvedValue(new Headers());
+      const init = await forwardedCookieInit();
 
-    const init = await forwardedCookieInit();
+      expect(init).toEqual({
+        headers: {
+          cookie: "better-auth.session_token=abc",
+          origin: "https://app.example.com",
+        },
+      });
+    },
+  );
 
-    expect(init).toEqual({
-      headers: { cookie: "better-auth.session_token=abc" },
-    });
-    expect(init.headers).not.toHaveProperty("origin");
-  });
+  // #8060 — hub-only: a spoke render of the seam does not run this case.
+  (TOPOLOGY === "hub" ? it : it.skip)(
+    "forwards cookie alone — no origin key at all — when Origin is absent",
+    async () => {
+      mockCookies.mockResolvedValue({
+        toString: () => "better-auth.session_token=abc",
+      });
+      mockHeaders.mockResolvedValue(new Headers());
+
+      const init = await forwardedCookieInit();
+
+      expect(init).toEqual({
+        headers: { cookie: "better-auth.session_token=abc" },
+      });
+      expect(init.headers).not.toHaveProperty("origin");
+    },
+  );
 });

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