create-ailk 0.9.0 → 0.11.0

package/templates/CLAUDE.md

@@ -21,7 +21,7 @@ apps/api/         Fastify HTTP API — lead capture, checkout, webhooks
 apps/mcp/         MCP server — agent-callable tools
 database/         Prisma schema + migrations
 content/          Site settings (_site.mdx) and MDX pages (en/<TypeName>/)
-.claude/          Rules, skills and agent definitions for Claude Code
+.claude/          Rules, the agent definition and settings for Claude Code
 tools/            This repo's own checks (architecture, CLAUDE.md drift)
 ```
 
@@ -67,7 +67,7 @@ your module set; `pnpm architecture` enforces it, and a hook in
 | Diff hygiene when editing existing files       | `.claude/rules/preserve-existing-style.md`                                                         |
 | Code style, testing, security                  | `CONVENTIONS.md`                                                                                   |
 | Environment variables and what they unlock     | `.env.example`                                                                                     |
-| Deploy configuration                           | `apps/api/vercel.json`; the `setup-deploy` skill                                                   |
+| Deploy configuration                           | `apps/api/vercel.json`; the `/ailk:setup-deploy` skill                                             |
 | Verification before push                       | `pnpm preflight` (see § Checks)                                                                    |
 
 <!-- /ailk:template id="resource-map" -->
@@ -76,18 +76,34 @@ your module set; `pnpm architecture` enforces it, and a hook in
 
 ## Skills
 
-In `.claude/skills/`; Claude Code finds them at session start.
+The AI Launch Kit skills come from the `ailk` Claude Code plugin, not from
+this repo. `.claude/settings.json` names its marketplace and enables it, so
+Claude Code loads it once you trust this folder. To install it by hand, run
+these two lines in a Claude Code session:
 
-| Skill            | Use when                                                          |
-| ---------------- | ----------------------------------------------------------------- |
-| `add-page`       | You need a new page, or extra JSON-LD on an existing one          |
-| `update-page`    | A page should live at a different URL, or needs a new title       |
-| `fill-page`      | A page still carries `{placeholder}` copy                         |
-| `check-site`     | You want the site's citation-readiness score and findings         |
-| `setup-database` | Leads should land in a database inbox at `/leads`                 |
-| `setup-deploy`   | You are ready to deploy to Vercel                                 |
-| `add-auth`       | Visitors need to sign in (magic link, Google, GitHub)             |
-| `upgrade-plan`   | You are weighing Free against a paid level or the commerce add-on |
+```
+/plugin marketplace add working-theory-labs/claude-plugins
+/plugin install ailk@working-theory
+```
+
+| Skill                  | Use when                                                          |
+| ---------------------- | ----------------------------------------------------------------- |
+| `/ailk:add-page`       | You need a new page, or extra JSON-LD on an existing one          |
+| `/ailk:update-page`    | A page should live at a different URL, or needs a new title       |
+| `/ailk:fill-page`      | A page still carries `{placeholder}` copy                         |
+| `/ailk:check-site`     | You want the site's citation-readiness score and findings         |
+| `/ailk:setup-database` | Leads should land in a database inbox at `/leads`                 |
+| `/ailk:setup-deploy`   | You are ready to deploy to Vercel                                 |
+| `/ailk:add-auth`       | Visitors need to sign in (email, Google, GitHub)                  |
+| `/ailk:upgrade-plan`   | You are weighing Free against a paid level or the commerce add-on |
+
+A repo scaffolded by an earlier create-ailk also carries its own older
+copies of these skills. Once the plugin is installed, delete those copies;
+keep scaffold-commerce, which the commerce module delivers.
+
+For design work, the third-party impeccable plugin is optional:
+`/plugin marketplace add pbakaus/impeccable`, then
+`/plugin install impeccable@impeccable`.
 
 <!-- /ailk:template id="skills" -->
 
@@ -95,15 +111,15 @@ In `.claude/skills/`; Claude Code finds them at session start.
 
 ## Checks
 
-| Command                | Catches                                                  |
-| ---------------------- | -------------------------------------------------------- |
-| `pnpm preflight`       | The next four and `build`, not `test`. Run before a push |
-| `pnpm architecture`    | An import that crosses a boundary in `architecture.yaml` |
-| `pnpm claude-md:check` | A hand-edit inside a template-owned section of this file |
-| `pnpm type-check`      | Type errors in every workspace                           |
-| `pnpm lint`            | Lint errors in every workspace                           |
-| `pnpm test`            | Failing unit tests                                       |
-| `check-site` skill     | Missing or invalid JSON-LD, weak citation-readiness      |
+| Command                  | Catches                                                  |
+| ------------------------ | -------------------------------------------------------- |
+| `pnpm preflight`         | The next four and `build`, not `test`. Run before a push |
+| `pnpm architecture`      | An import that crosses a boundary in `architecture.yaml` |
+| `pnpm claude-md:check`   | A hand-edit inside a template-owned section of this file |
+| `pnpm type-check`        | Type errors in every workspace                           |
+| `pnpm lint`              | Lint errors in every workspace                           |
+| `pnpm test`              | Failing unit tests                                       |
+| `/ailk:check-site` skill | Missing or invalid JSON-LD, weak citation-readiness      |
 
 <!-- /ailk:template id="checks" -->
 

package/templates/README.md

@@ -73,7 +73,7 @@ A page marked `--shape organization-product` is in your site when you scaffolded
 
 To customize the home page, edit [`content/en/HomePage/home.mdx`](./content/en/HomePage/home.mdx). Save and reload the dev server. No build step.
 
-To add a new page, ask Claude Code to run the `add-page` skill — it writes the page's content file and nav link in one confirm-before-write pass, and adds a missing route with `create-ailk add-route` first. See [Skills](#skills).
+To add a new page, ask Claude Code to run the `/ailk:add-page` skill — it writes the page's content file and nav link in one confirm-before-write pass, and adds a missing route with `create-ailk add-route` first. See [Skills](#skills).
 
 > `content/_site.mdx` stays at the top level (not under `content/en/`) — site identity is locale-blind.
 
@@ -200,20 +200,20 @@ Change the ranges by hand. Below 1.0 a caret range (`^0.26.0`) never crosses a m
 
 ## Skills
 
-This project ships Claude Code skills in `.claude/skills/`. Claude Code discovers them at session start — ask for one by name.
+The AI Launch Kit skills come from the `ailk` Claude Code plugin; `.claude/settings.json` names it, and CLAUDE.md § Skills has the two install lines.
 
 <!-- generated:begin skills -->
 
-| Skill            | What it does                                                                                                                                                                                                                       |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `add-page`       | Add a page this site can serve — its content file, structured data and nav link — adding a missing route with `create-ailk add-route` first. Also documents the `schema:` frontmatter override for any page.                       |
-| `update-page`    | Rename a page — give it a new URL and/or a new title — in one plan-then-confirm pass: its content files, its own route folder, exact internal links and the manifest row move together, and the old URL gets a permanent redirect. |
-| `add-auth`       | Activate auth providers — magic-link via Resend, Google OAuth, GitHub OAuth.                                                                                                                                                       |
-| `setup-deploy`   | Emit deploy configuration — `vercel.json`, `.env.example`, and `RUNBOOK.md` — for a Vercel deploy. Asks where leads go (email or a database) and warns when neither is set.                                                        |
-| `setup-database` | Take the site from no database to a working lead inbox: provision Postgres, create the tables, pin the owner, and verify one test message lands in `/leads`.                                                                       |
-| `check-site`     | Run `ailk-audit --json` and explain the score and findings in plain language.                                                                                                                                                      |
-| `fill-page`      | Fill one page's section content from a category profile: labelled sample content (tier 1) or your own first draft from a short intake (tier 2).                                                                                    |
-| `upgrade-plan`   | Compare Free, Pro, Pro Plus, Agency and the commerce add-on side by side, with the prices the public pricing page publishes right now, and recommend one option for this site with a reason.                                       |
+| Skill                  | What it does                                                                                                                            |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `/ailk:add-auth`       | Activate the site's sign-in providers (email-and-password, Google OAuth, GitHub OAuth) and write the env vars for the ones you pick.    |
+| `/ailk:add-page`       | Add a new page — its content file, its structured data and its nav link — in one confirm-before-write pass.                             |
+| `/ailk:check-site`     | Run `ailk-audit` on the site and explain the score and findings in plain language. It never edits files.                                |
+| `/ailk:fill-page`      | Fill one existing page's section content from a category profile: labelled sample content, or your own first draft from a short intake. |
+| `/ailk:setup-database` | Take the site from no database to a working lead inbox, and prove it with one test message that must appear in the inbox.               |
+| `/ailk:setup-deploy`   | Emit deploy configuration — `vercel.json` and `RUNBOOK.md`, plus an env checklist read from the site's own `.env.example`.              |
+| `/ailk:update-page`    | Rename a page — its URL, its title, or both — in one plan-then-confirm pass, with a permanent redirect from the old URL.                |
+| `/ailk:upgrade-plan`   | Explain the AI Launch Kit options side by side, recommend one option for this site, and link the public pricing page for prices.        |
 
 <!-- generated:end -->
 

package/templates/apps/api/jest.config.cjs

@@ -64,6 +64,7 @@ module.exports = {
     '^@working-theory/schema-pack-registry$': '<rootDir>/../../packages/schema-pack-registry/src/index.ts',
     '^@working-theory/schema-validator$': '<rootDir>/../../packages/schema-validator/src/index.ts',
     '^@working-theory/stripe-client$': '<rootDir>/../../packages/stripe-client/src/index.ts',
+    '^@working-theory/metadata$': '<rootDir>/../../packages/metadata/src/index.ts',
     '^@working-theory/validation$': '<rootDir>/../../packages/validation/src/index.ts',
     '^(\\.{1,2}/.*)\\.js$': '$1',
   },

package/templates/apps/api/package.json

@@ -60,6 +60,7 @@
     "@types/node": "^22.20.0",
     "@types/pg": "^8.20.0",
     "@vercel/node": "^5.8.22",
+    "@working-theory/metadata": "workspace:*",
     "jest": "^30.4.2",
     "pdfjs-dist": "^6.3.289",
     "prisma": "^7.8.0",

package/templates/apps/mcp/CLAUDE.md

@@ -25,8 +25,8 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 **Read (9):** `list_pages`, `read_content`, `search_content`, `get_site_info`, `get_business_hours`, `get_locations`, `get_offerings`, `get_pricing`, `get_faq`
 **Conversion-write (3):** `capture_lead`, `subscribe_newsletter`, `request_callback`
 **Maintenance (2):** `audit`, `create_project`
-**Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366): identity-blind and free of any `requirePaidTier()` call like every tool in this list, but registered only when the signal-collectors module is present, the same shape Booking below already has
-**Booking (3):** `list_availability`, `get_event_meta`, `create_booking` — module-gated (`module: "scheduling"`)
+**Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has
+**Booking (3):** `list_availability`, `get_event_meta`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`
 
 ### Why the parity test counts 20 and a keyless server registers 19
 
@@ -41,11 +41,21 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   `addon: "commerce"`, so it is the one entry whose presence depends on the
   licence — 19 without the claim, 20 with it.
 - **19 free anonymous tools**: since #5853 retired the three content-write
-  tools, NO registered tool is gated at call time by `requirePaidTier()`, so
-  every registered tool is free and anonymous. The five carrying `tier: "pro"`
+  tools, every registered tool remains anonymous — call-time gating checks a
+  licence claim, never an identity. The five carrying `tier: "pro"`
   (`get_flow`, `submit_flow_step`, `list_availability`, `get_event_meta`,
-  `create_booking`) are MODULE-gated at registration, not payment-gated at
-  call time — the shape the Flow and Booking rows above describe.
+  `create_booking`) are gated at REGISTRATION **and at call time** (#7315):
+  each needs its module, and each catalog row names the licence `feature:`
+  that entitles it. `start_purchase` is gated at call time by both this
+  server-wide gate and its own Gate 2 in `tools/purchase.ts`.
+  `MCP_FEATURE_GATE_MODE` (`packages/metadata`) decides what an unheld
+  feature does. In `"warn"` mode (this release) the five register on module
+  presence alone, and `index.ts` logs one boot warning (stderr) per tool
+  served without its feature. In `"refuse"` mode (the next release) they
+  also need the deployment's licence to hold the feature, and
+  `/.well-known/mcp.json` drops them in step. The claim is resolved at boot
+  and re-read every `MCP_CLAIM_REFRESH_MS` through `checkLicense()`
+  (`lib/commerce-claim.ts`) and fails closed.
   `index.ts` is the transport entry point and exports no tools — registration
   is entirely via `createMcpServer`.
 
@@ -69,7 +79,8 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   `commerce` licence claim, per its `addon: "commerce"` catalog marker. A
   keyless site advertises it in neither the discovery manifest nor the running
   server's tool list, and calling it by name there returns the module-disabled
-  `not_found` body. The claim is resolved once at boot
+  `not_found` body. The claim is resolved at boot and re-read every
+  `MCP_CLAIM_REFRESH_MS`
   (`src/lib/commerce-claim.ts`, awaited in `src/index.ts`) and read
   synchronously by both the registration filter and the handler's own
   re-check. Calls are rate-limited per IP by the AbuseGuard
@@ -111,14 +122,16 @@ Example (lead routing):
 ## What NOT to do
 
 - Don't add identity arguments to OSS tools.
-- Don't expose a Pro tool without its `requirePaidTier()` gate.
+- Don't add a paid tool without a `feature:` marker on its catalog row — registration and the manifest gate on the deployment's claim, never on a caller-supplied key or argument.
 - Don't import `@working-theory/*` from `apps/mcp`.
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-09-17 — #5971: `start_purchase` re-enabled behind the `commerce` licence claim. `OSS_DISABLED_TOOLS` is now empty; the registered count is 19 on a keyless deployment and 20 on a commerce-claimed one; the tool's input field is `productCode` (was `priceId`), matching its HTTP twin; a per-IP daily cap (`MCP_ABUSE_START_PURCHASE_DAILY_CAP`) covers it.
+Last updated: 2026-09-29 — #7136: the five `tier: "pro"` tools name their licence `feature:` (`scheduling`, `flows-deliverables`) and gate on the deployment's own claim under `MCP_FEATURE_GATE_MODE` — `"warn"` this release (served, one boot warning each), `"refuse"` the next. The unused call-time paid-tier guard is deleted.
 
-Prior: 2026-07-09 — corrected the tool-count explanation (18 catalog → 17 registered → 14 free anonymous) and the Pro-tool gating (registered + `requirePaidTier()`-gated, not `OSS_DISABLED_TOOLS`-disabled).
+Prior: 2026-09-17 — #5971: `start_purchase` re-enabled behind the `commerce` licence claim. `OSS_DISABLED_TOOLS` is now empty; the registered count is 19 on a keyless deployment and 20 on a commerce-claimed one; the tool's input field is `productCode` (was `priceId`), matching its HTTP twin; a per-IP daily cap (`MCP_ABUSE_START_PURCHASE_DAILY_CAP`) covers it.
+
+Prior: 2026-07-09 — corrected the tool-count explanation (18 catalog → 17 registered → 14 free anonymous) and the Pro-tool gating (registered + gated by the call-time paid-tier guard, not `OSS_DISABLED_TOOLS`-disabled).
 
 Last updated: 2026-09-17 — doc-sync: tool counts "23 catalog → 22 registered → 19 free anonymous" → "20 in TOOLS → 19 registered → 19 free anonymous", and the Pro-tools section rewritten to record that `create_page`/`update_page`/`delete_page` were RETIRED by #5853 rather than disabled (D7) — derived from `packages/metadata/src/mcp-tool-catalog.ts` and verified against `apps/mcp/src/server.ts`.
 

package/templates/apps/mcp/__tests__/catalog-drift.test.ts

@@ -13,6 +13,10 @@
  *     `start_purchase` visible, so comparing a claimed server against an
  *     unclaimed catalog (or vice versa) would compare unlike surfaces and
  *     report drift that isn't there — or, worse, miss drift that is.
+ *   - …and under every licence-feature state × gate mode (#7136): 2 commerce
+ *     states × {warn, refuse} × 4 held-feature sets = 16. In refuse mode a
+ *     feature's tools are in both surfaces iff the feature is held; in warn
+ *     mode all five are in both.
  *
  * What this does NOT assert:
  *   - inputSchema equality — the server registers Zod schemas; the catalog
@@ -21,14 +25,35 @@
  */
 
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { getMcpToolCatalog } from "@working-theory/metadata";
+import {
+  getMcpToolCatalog,
+  type McpCatalogOptions,
+  type McpToolCatalogEntry,
+} from "@working-theory/metadata";
 
 import {
+  MCP_CLAIM_REFRESH_MS,
   __setMcpCommerceClaimForTest,
+  __setMcpFeatureGateForTest,
+  __setMcpHeldFeaturesForTest,
+  initMcpCommerceClaim,
   resetMcpCommerceClaim,
+  startMcpClaimRefresh,
   type McpCommerceClaim,
 } from "../src/lib/commerce-claim.js";
-import { createMcpServer } from "../src/server.js";
+import { createMcpServer, listRegisteredTools } from "../src/server.js";
+
+/** The injected licence reader — same seam `commerce-claim.test.ts` types. */
+type CheckLicenseSeam = NonNullable<
+  NonNullable<Parameters<typeof initMcpCommerceClaim>[0]>["checkLicense"]
+>;
+
+type LicenseShape = Awaited<ReturnType<CheckLicenseSeam>>;
+
+/** A licence reader that resolves to the given (partial) result. */
+function resolving(result: Partial<LicenseShape>): CheckLicenseSeam {
+  return () => Promise.resolve(result as LicenseShape);
+}
 
 interface RegisteredTool {
   description?: string;
@@ -47,29 +72,70 @@ const PAID_MODULES = "scheduling,content-write,signal-collectors";
  * @modelcontextprotocol/sdk ^1.29.0 — if the SDK renames the field, change it
  * here once rather than at each call site.
  */
-function registeredToolsOf(
-  server: McpServer,
-): Record<string, RegisteredTool> {
+function registeredToolsOf(server: McpServer): Record<string, RegisteredTool> {
   return (
     // eslint-disable-next-line no-restricted-syntax -- #506/#507: the SDK exposes no public accessor; the double assertion is confined to this one helper
-    server as unknown as { _registeredTools: Record<string, RegisteredTool> }
-  )._registeredTools;
+    (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+      ._registeredTools
+  );
 }
 
+type GateMode = NonNullable<McpCatalogOptions["featureGate"]>;
+
+type McpFeature = NonNullable<McpToolCatalogEntry["feature"]>;
+
+/** The five licence-feature tools, by the feature that entitles them. */
+const FEATURE_TOOLS: Record<McpFeature, readonly string[]> = {
+  scheduling: ["list_availability", "get_event_meta", "create_booking"],
+  "flows-deliverables": ["get_flow", "submit_flow_step"],
+};
+
+const HELD_SETS: readonly (readonly McpFeature[])[] = [
+  [],
+  ["scheduling"],
+  ["flows-deliverables"],
+  ["scheduling", "flows-deliverables"],
+];
+
+/** Every claim state: commerce × gate mode × held features (16). */
+const CLAIM_STATES = (["unclaimed", "claimed"] as const).flatMap((claim) =>
+  (["warn", "refuse"] as const).flatMap((mode) =>
+    HELD_SETS.map(
+      (held) =>
+        [claim, mode, held] as [
+          McpCommerceClaim,
+          GateMode,
+          readonly McpFeature[],
+        ],
+    ),
+  ),
+);
+
 /** The catalog options a given claim state implies — the same mapping
  * `server.ts` applies internally, so both surfaces are read like for like. */
-function catalogOptionsFor(claim: McpCommerceClaim) {
-  return { addons: { commerce: claim === "claimed" } };
+function catalogOptionsFor(
+  claim: McpCommerceClaim,
+  mode: GateMode,
+  held: readonly McpFeature[],
+): McpCatalogOptions {
+  return {
+    addons: { commerce: claim === "claimed" },
+    features: held,
+    featureGate: mode,
+  };
 }
 
-describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
-  "MCP catalog ↔ server drift — commerce claim %s",
-  (claim) => {
+describe.each(CLAIM_STATES)(
+  "MCP catalog ↔ server drift — commerce %s, mode %s, held %j",
+  (claim, mode, held) => {
     const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
+    const options = catalogOptionsFor(claim, mode, held);
 
     beforeEach(() => {
       process.env.AILK_ENABLED_MODULES = PAID_MODULES;
       __setMcpCommerceClaimForTest(claim);
+      __setMcpFeatureGateForTest(mode);
+      __setMcpHeldFeaturesForTest(held);
     });
 
     afterEach(() => {
@@ -87,7 +153,7 @@ describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
     it("registered tool names equal catalog tool names", () => {
       const registered = registeredToolsOf(createMcpServer());
       const registeredNames = Object.keys(registered).sort();
-      const catalogNames = getMcpToolCatalog(catalogOptionsFor(claim))
+      const catalogNames = getMcpToolCatalog(options)
         .map((t) => t.name)
         .sort();
       expect(registeredNames).toEqual(catalogNames);
@@ -95,7 +161,7 @@ describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
 
     it("registered tool descriptions equal catalog descriptions", () => {
       const registered = registeredToolsOf(createMcpServer());
-      for (const entry of getMcpToolCatalog(catalogOptionsFor(claim))) {
+      for (const entry of getMcpToolCatalog(options)) {
         expect(registered[entry.name]).toBeDefined();
         expect(registered[entry.name]!.description).toBe(entry.description);
       }
@@ -107,10 +173,87 @@ describe.each<McpCommerceClaim>(["unclaimed", "claimed"])(
 
       expect("start_purchase" in registered).toBe(expected);
       expect(
-        getMcpToolCatalog(catalogOptionsFor(claim)).some(
-          (t) => t.name === "start_purchase",
-        ),
+        getMcpToolCatalog(options).some((t) => t.name === "start_purchase"),
       ).toBe(expected);
     });
+
+    it("each feature's tools appear in both surfaces exactly when the gate lets them", () => {
+      const registered = registeredToolsOf(createMcpServer());
+      const catalogNames = getMcpToolCatalog(options).map((t) => t.name);
+
+      for (const [feature, tools] of Object.entries(FEATURE_TOOLS)) {
+        const expected =
+          mode === "warn" || held.includes(feature as McpFeature);
+        for (const name of tools) {
+          expect(name in registered).toBe(expected);
+          expect(catalogNames.includes(name)).toBe(expected);
+        }
+      }
+    });
   },
 );
+
+describe("MCP catalog ↔ server agreement after a bounded re-read (#7156 AC-1)", () => {
+  const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
+
+  beforeEach(() => {
+    process.env.AILK_ENABLED_MODULES = PAID_MODULES;
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    resetMcpCommerceClaim();
+    jest.useRealTimers();
+    if (priorEnabledModules === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+    }
+  });
+
+  it("a new server and listRegisteredTools() match the catalog once the re-read resolves", async () => {
+    __setMcpFeatureGateForTest("refuse");
+    await initMcpCommerceClaim({
+      checkLicense: resolving({
+        tier: "pro",
+        features: ["scheduling", "flows-deliverables", "commerce"],
+      }),
+    });
+
+    const bootOptions: McpCatalogOptions = {
+      addons: { commerce: true },
+      features: ["scheduling", "flows-deliverables"],
+      featureGate: "refuse",
+    };
+    const bootNames = Object.keys(registeredToolsOf(createMcpServer())).sort();
+    expect(bootNames).toEqual(
+      getMcpToolCatalog(bootOptions)
+        .map((t) => t.name)
+        .sort(),
+    );
+    expect(bootNames).toHaveLength(20);
+
+    startMcpClaimRefresh({ checkLicense: resolving({ features: [] }) });
+    await jest.advanceTimersByTimeAsync(MCP_CLAIM_REFRESH_MS);
+
+    const refreshedOptions: McpCatalogOptions = {
+      addons: { commerce: false },
+      features: [],
+      featureGate: "refuse",
+    };
+    const catalogNames = getMcpToolCatalog(refreshedOptions)
+      .map((t) => t.name)
+      .sort();
+    expect(catalogNames).toHaveLength(14);
+
+    const serverNames = Object.keys(
+      registeredToolsOf(createMcpServer()),
+    ).sort();
+    expect(serverNames).toEqual(catalogNames);
+
+    const listedNames = listRegisteredTools()
+      .map((t) => t.name)
+      .sort();
+    expect(listedNames).toEqual(catalogNames);
+  });
+});

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

@@ -1,5 +1,6 @@
 /**
- * Structural ordering guard for apps/mcp's bootstrap (#5876 spec D4, AC-3).
+ * Structural ordering guard for apps/mcp's bootstrap (#5876 spec D4, AC-3;
+ * #7156 AC-1, AC-2).
  *
  * `apps/mcp/src/index.ts` has real side effects at import time (starts a
  * transport, opens a stdio/HTTP listener) — it cannot safely be imported by
@@ -8,6 +9,9 @@
  */
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import vm from "node:vm";
+
+import * as ts from "typescript";
 
 describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
   const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
@@ -37,3 +41,116 @@ describe("apps/mcp/src/index.ts — bootstrap ordering", () => {
     expect(initIdx).toBeLessThan(catchIdx);
   });
 });
+
+describe("apps/mcp/src/index.ts — the claim refresh loop starts in production (#7156 AC-1)", () => {
+  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+
+  it("starts after the boot read and before the transport branch", () => {
+    const initIdx = src.indexOf("await initMcpCommerceClaim()");
+    const callMatches = [...src.matchAll(/^startMcpClaimRefresh\(\);$/gm)];
+    const transportBranchIdx = src.indexOf('if (transport === "http")');
+
+    expect(initIdx).toBeGreaterThan(-1);
+    expect(callMatches).toHaveLength(1);
+    expect(transportBranchIdx).toBeGreaterThan(-1);
+
+    const callIdx = callMatches[0]!.index!;
+    expect(initIdx).toBeLessThan(callIdx);
+    expect(callIdx).toBeLessThan(transportBranchIdx);
+  });
+});
+
+describe("apps/mcp/src/index.ts — the boot warning cannot stop the server (#7156 AC-2, D2)", () => {
+  const src = readFileSync(resolve(__dirname, "../src/index.ts"), "utf-8");
+
+  /**
+   * The exact behavioural slice AC-2 specifies: from the last `try {` before
+   * the `reportUnlicensedProTools();` call statement, up to `const transport
+   * =`. Transpiled and run in a fresh vm context so a real throw from the
+   * stubbed function proves the guard, not a mock of the guard itself.
+   */
+  function guardedSlice(): string {
+    const callMatches = [
+      ...src.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
+    ];
+    expect(callMatches).toHaveLength(1);
+    const callIdx = callMatches[0]!.index!;
+    const tryIdx = src.lastIndexOf("try {", callIdx);
+    const transportIdx = src.indexOf("const transport =");
+
+    expect(tryIdx).toBeGreaterThan(-1);
+    expect(transportIdx).toBeGreaterThan(callIdx);
+
+    const slice = src.slice(tryIdx, transportIdx);
+    // The extracted try block must be the one that immediately wraps the
+    // call, not an earlier try{}/await pair (code review, #7156): the two
+    // other try blocks in this file each await a boot call, so a regressed
+    // boundary would carry "await" into the slice. Asserting that here
+    // turns a boundary regression into a clear failure instead of an opaque
+    // vm ReferenceError from the un-injected awaited function.
+    expect(slice).not.toContain("await");
+
+    return slice;
+  }
+
+  function runGuardedSlice(
+    reportUnlicensedProTools: () => unknown,
+    errorSpy: jest.Mock,
+  ): void {
+    const slice = guardedSlice();
+    const { outputText } = ts.transpileModule(slice, {
+      compilerOptions: {
+        module: ts.ModuleKind.CommonJS,
+        target: ts.ScriptTarget.ES2020,
+      },
+    });
+    vm.runInNewContext(outputText, {
+      reportUnlicensedProTools,
+      console: { error: errorSpy },
+    });
+  }
+
+  it("a throw is logged to stderr and does not escape", () => {
+    const errorSpy = jest.fn();
+
+    expect(() =>
+      runGuardedSlice(() => {
+        throw new Error("boom");
+      }, errorSpy),
+    ).not.toThrow();
+
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const call = errorSpy.mock.calls[0]!;
+    expect(String(call[0])).toContain("reportUnlicensedProTools");
+    const lastArg = call[call.length - 1];
+    expect(lastArg).toBeInstanceOf(Error);
+    expect((lastArg as Error).message).toBe("boom");
+  });
+
+  it("a successful call is not logged", () => {
+    const errorSpy = jest.fn();
+    const report = jest.fn(() => []);
+
+    runGuardedSlice(report, errorSpy);
+
+    expect(report).toHaveBeenCalledTimes(1);
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it("the call statement occurs exactly once, before the transport branch", () => {
+    const callMatches = [
+      ...src.matchAll(/^\s*reportUnlicensedProTools\(\);$/gm),
+    ];
+    const transportBranchIdx = src.indexOf('if (transport === "http")');
+
+    expect(callMatches).toHaveLength(1);
+    expect(callMatches[0]!.index!).toBeLessThan(transportBranchIdx);
+  });
+
+  it("logs to stderr only — the guarded slice never writes stdout", () => {
+    const slice = guardedSlice();
+
+    expect(slice).toContain("console.error");
+    expect(slice).not.toContain("console.log");
+  });
+});