create-ailk 0.16.0 → 0.18.0

package/dist/lib/env-catalog.js

@@ -24,7 +24,7 @@ export const ENV_CATALOG = {
         secret: false,
     },
     AILK_CONTENT_ROOT: {
-        description: "Overrides the on-disk content root; defaults to <repo-root>/content.",
+        description: "Overrides the on-disk content root (absolute, or relative to the working directory). Unset, the MCP server tries <cwd>/content, then <cwd>/../../content; the web app defaults to <repo-root>/content.",
         secret: false,
     },
     AILK_ENABLED_MODULES: {
@@ -143,16 +143,12 @@ export const ENV_CATALOG = {
         description: "The port the MCP HTTP transport binds; defaults to 8080.",
         secret: false,
     },
-    MCP_PUBLIC_HTTP_URL: {
-        description: "The public URL of the MCP HTTP transport, advertised by /.well-known/mcp.json.",
-        secret: false,
-    },
-    MCP_RATE_LIMIT_READ_PER_MIN: {
-        description: "Maximum MCP read-tool requests per minute per IP; defaults to 60.",
+    MCP_HTTP_STATELESS: {
+        description: 'Set to "true" or "1" for an MCP HTTP transport with no sessions, which any instance can answer; "false" or "0" keeps sessions in one process. Unset means stateless on Vercel (src/app.ts) and stateful on a port (src/index.ts).',
         secret: false,
     },
-    MCP_RATE_LIMIT_WRITE_PER_MIN: {
-        description: "Maximum MCP write-tool requests per minute per IP; defaults to 10.",
+    MCP_PUBLIC_HTTP_URL: {
+        description: "The public URL of the MCP HTTP transport, advertised by /.well-known/mcp.json.",
         secret: false,
     },
     MCP_TRANSPORT: {

package/dist/spoke-checkout.d.ts

@@ -24,15 +24,40 @@ export declare function spokeEnvRowOptions(commerce: boolean): Pick<PlanEnvRowsO
  * `site-` and the first 8 hex characters of its SHA-256. Never `AILK_SITE_ID`.
  */
 export declare function spokeCheckoutSite(projectName: string): string;
+/** Where a commerce spoke's end-to-end checkout workflow lives. */
+export declare const SPOKE_CHECKOUT_E2E_WORKFLOW_PATH = ".github/workflows/checkout-e2e.yml";
+/**
+ * The Stripe CLI release the workflow installs, and the SHA-256 of its
+ * `stripe_<v>_linux_x86_64.tar.gz` from that release's own
+ * `stripe-linux-checksums.txt`. Never bump one without re-reading the other.
+ */
+export declare const STRIPE_CLI_VERSION = "1.51.1";
+export declare const STRIPE_CLI_LINUX_X64_SHA256 = "38c8de73a8cab810a4aab8a4015cd4e3398b7b87aa42b6944d09d89ed524ac53";
+/** The Playwright the workflow installs — the monorepo's own pinned version. */
+export declare const E2E_PLAYWRIGHT_VERSION = "1.61.1";
+/**
+ * Every action the workflow uses, pinned to the commit its `v4` tag named
+ * when this was written (SEC-7839-2): `gh api repos/<action>/commits/v4`.
+ */
+export declare const E2E_ACTION_PINS: Readonly<Record<string, string>>;
+/**
+ * The workflow text (D8). Identical for every spoke at one create-ailk
+ * version. Every `${{ … }}` sits in an env-style value, never in a script.
+ */
+export declare const CHECKOUT_E2E_WORKFLOW: string;
 /**
  * The slice for `site`, in order: the two route files, the config, the two
- * pages (D3). Throws `TopologyError` for an invalid stamp (SEC-7838-10).
+ * pages (D3), then the checkout e2e workflow (#7839 D8), which does not
+ * depend on `site`. Throws `TopologyError` for an invalid stamp (SEC-7838-10).
  */
 export declare function renderSpokeCheckoutFiles(site: string): [string, string][];
 /**
  * Write the slice into `targetDir` (D3). A file that already exists is left
  * byte-for-byte and reported `skipped` — the config is the site's once
- * written. Adds the package to `apps/web/package.json` only when absent.
+ * written. Adds the package to `apps/web/package.json` when absent, and
+ * raises a plain pin older than the one it writes (#7839): the generated
+ * checkout e2e workflow runs a command a `^0.2.0` pin never reaches. Any
+ * other range — newer, `workspace:`, a tag — is the site's and is kept.
  * Every refusal (an invalid stamp, a version map without the package, a
  * missing or malformed `apps/web/package.json`) throws before the first write.
  */

package/dist/spoke-checkout.js

@@ -286,9 +286,183 @@ const UNAVAILABLE_PAGE = renderPage({
         "},",
     ],
 });
+// ── #7839 D8 — the checkout e2e workflow ─────────────────────────────────────
+/** Where a commerce spoke's end-to-end checkout workflow lives. */
+export const SPOKE_CHECKOUT_E2E_WORKFLOW_PATH = ".github/workflows/checkout-e2e.yml";
+/**
+ * The Stripe CLI release the workflow installs, and the SHA-256 of its
+ * `stripe_<v>_linux_x86_64.tar.gz` from that release's own
+ * `stripe-linux-checksums.txt`. Never bump one without re-reading the other.
+ */
+export const STRIPE_CLI_VERSION = "1.51.1";
+export const STRIPE_CLI_LINUX_X64_SHA256 = "38c8de73a8cab810a4aab8a4015cd4e3398b7b87aa42b6944d09d89ed524ac53";
+/** The Playwright the workflow installs — the monorepo's own pinned version. */
+export const E2E_PLAYWRIGHT_VERSION = "1.61.1";
+/**
+ * Every action the workflow uses, pinned to the commit its `v4` tag named
+ * when this was written (SEC-7839-2): `gh api repos/<action>/commits/v4`.
+ */
+export const E2E_ACTION_PINS = Object.freeze({
+    "actions/checkout": "11d5960a326750d5838078e36cf38b85af677262",
+    "pnpm/action-setup": "b906affcce14559ad1aafd4ab0e942779e9f58b1",
+    "actions/setup-node": "49933ea5288caeca8642d1e84afbd3f7d6820020",
+    "actions/upload-artifact": "ea165f8d65b6e75b540449e92b4886f43607fa02",
+});
+function uses(action) {
+    return `uses: ${action}@${E2E_ACTION_PINS[action]} # v4`;
+}
+/**
+ * The workflow text (D8). Identical for every spoke at one create-ailk
+ * version. Every `${{ … }}` sits in an env-style value, never in a script.
+ */
+export const CHECKOUT_E2E_WORKFLOW = `# Checkout e2e — GENERATED by create-ailk (#7839). Do not edit: it changes
+# with the ${SPOKE_CHECKOUT_PACKAGE} command it runs.
+#
+# Pays each named offering once through Stripe's hosted Checkout in TEST
+# mode, then checks Stripe's webhook was answered 2xx and this site's
+# fulfilment ran. Start it by hand (Actions > Checkout e2e > Run workflow)
+# after a checkout change and before any live flip. It never runs on a push
+# or a pull request: it needs the network, the Stripe CLI and test-mode state.
+#
+# Setup, once: create the GitHub Environment "checkout-e2e", limit its
+# deployment branches to the default branch, and add to it the secrets
+# STRIPE_TEST_SECRET_KEY (an sk_test_ or rk_test_ key) and AILK_SPOKE_KEY,
+# and the variable AILK_API_URL (https). Each paid session posts one
+# test-mode lead to the hub. Test subscriptions it creates are cancelled.
+name: Checkout e2e
+
+on:
+  workflow_dispatch:
+    inputs:
+      offerings:
+        description: Comma-separated fixed offering slugs from apps/web/lib/checkout-config.ts
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: checkout-e2e
+  cancel-in-progress: false
+
+jobs:
+  checkout-e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    environment: checkout-e2e
+    env:
+      NEXT_PUBLIC_BASE_URL: http://localhost:3000
+      STRIPE_MODE: test
+    steps:
+      - name: Refuse a live key or a missing setting
+        env:
+          STRIPE_SECRET_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
+          AILK_SPOKE_KEY: \${{ secrets.AILK_SPOKE_KEY }}
+          AILK_API_URL: \${{ vars.AILK_API_URL }}
+        run: |
+          case "$STRIPE_SECRET_KEY" in
+            sk_test_*|rk_test_*) ;;
+            *) echo "::error::STRIPE_TEST_SECRET_KEY must be an sk_test_ or rk_test_ key"; exit 2 ;;
+          esac
+          if [ -z "$AILK_SPOKE_KEY" ]; then
+            echo "::error::set the AILK_SPOKE_KEY secret in the checkout-e2e environment"; exit 2
+          fi
+          case "$AILK_API_URL" in
+            https://*) ;;
+            *) echo "::error::AILK_API_URL must be the hub's https origin"; exit 2 ;;
+          esac
+
+      - ${uses("actions/checkout")}
+
+      - ${uses("pnpm/action-setup")}
+
+      - run: test -f pnpm-lock.yaml || touch pnpm-lock.yaml
+
+      - ${uses("actions/setup-node")}
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install
+        run: |
+          if [ -s pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; else pnpm install; fi
+
+      - name: Install the Stripe CLI (pinned, checksum-checked)
+        run: |
+          curl -fsSL -o "$RUNNER_TEMP/stripe.tar.gz" \\
+            https://github.com/stripe/stripe-cli/releases/download/v${STRIPE_CLI_VERSION}/stripe_${STRIPE_CLI_VERSION}_linux_x86_64.tar.gz
+          echo "${STRIPE_CLI_LINUX_X64_SHA256}  $RUNNER_TEMP/stripe.tar.gz" | sha256sum -c -
+          mkdir -p "$RUNNER_TEMP/stripe-cli"
+          tar -xzf "$RUNNER_TEMP/stripe.tar.gz" -C "$RUNNER_TEMP/stripe-cli" stripe
+
+      - name: Install Playwright (pinned) and Chromium
+        run: |
+          npm install --no-save --ignore-scripts --prefix "$RUNNER_TEMP/e2e-deps" playwright@${E2E_PLAYWRIGHT_VERSION}
+          "$RUNNER_TEMP/e2e-deps/node_modules/.bin/playwright" install --with-deps chromium
+
+      - name: Fetch the Stripe CLI's signing secret
+        env:
+          STRIPE_API_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
+        run: |
+          umask 077
+          secret="$("$RUNNER_TEMP/stripe-cli/stripe" listen --print-secret)"
+          echo "::add-mask::$secret"
+          printf '%s' "$secret" > "$RUNNER_TEMP/stripe-whsec"
+
+      - name: Build the site
+        run: pnpm --filter ./apps/web build
+
+      - name: Start the site
+        env:
+          STRIPE_SECRET_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
+          AILK_SPOKE_KEY: \${{ secrets.AILK_SPOKE_KEY }}
+          AILK_API_URL: \${{ vars.AILK_API_URL }}
+        run: |
+          STRIPE_WEBHOOK_SECRET="$(cat "$RUNNER_TEMP/stripe-whsec")"
+          export STRIPE_WEBHOOK_SECRET
+          cd apps/web
+          nohup pnpm exec next start -p 3000 -H localhost > "$RUNNER_TEMP/next.log" 2>&1 &
+          echo $! > "$RUNNER_TEMP/next.pid"
+          for _ in $(seq 1 60); do
+            curl -fsS -o /dev/null http://localhost:3000/checkout/thank-you && exit 0
+            sleep 2
+          done
+          echo "::error::the site did not start on localhost:3000; run it locally with the same settings to see why"
+          exit 1
+
+      - name: Pay each offering
+        working-directory: apps/web
+        env:
+          STRIPE_SECRET_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
+          OFFERINGS: \${{ inputs.offerings }}
+          SPOKE_CHECKOUT_E2E_DEPS: \${{ runner.temp }}/e2e-deps
+          STRIPE_CLI_PATH: \${{ runner.temp }}/stripe-cli/stripe
+        run: |
+          STRIPE_WEBHOOK_SECRET="$(cat "$RUNNER_TEMP/stripe-whsec")"
+          export STRIPE_WEBHOOK_SECRET
+          pnpm exec spoke-checkout-e2e --base-url http://localhost:3000 --offerings "$OFFERINGS" --out "$RUNNER_TEMP/checkout-e2e"
+
+      - name: Stop the site
+        if: always()
+        run: |
+          if [ -f "$RUNNER_TEMP/next.pid" ]; then pkill -P "$(cat "$RUNNER_TEMP/next.pid")" || true; kill "$(cat "$RUNNER_TEMP/next.pid")" || true; fi
+          rm -f "$RUNNER_TEMP/stripe-whsec"
+
+      - name: Keep the report
+        if: always()
+        ${uses("actions/upload-artifact")}
+        with:
+          name: checkout-e2e
+          path: \${{ runner.temp }}/checkout-e2e
+          if-no-files-found: ignore
+          retention-days: 7
+`;
 /**
  * The slice for `site`, in order: the two route files, the config, the two
- * pages (D3). Throws `TopologyError` for an invalid stamp (SEC-7838-10).
+ * pages (D3), then the checkout e2e workflow (#7839 D8), which does not
+ * depend on `site`. Throws `TopologyError` for an invalid stamp (SEC-7838-10).
  */
 export function renderSpokeCheckoutFiles(site) {
     assertSite(site);
@@ -300,6 +474,7 @@ export function renderSpokeCheckoutFiles(site) {
         [SPOKE_CHECKOUT_CONFIG_PATH, renderConfig(site)],
         [thankYouPath, THANK_YOU_PAGE],
         [unavailablePath, UNAVAILABLE_PAGE],
+        [SPOKE_CHECKOUT_E2E_WORKFLOW_PATH, CHECKOUT_E2E_WORKFLOW],
     ];
 }
 const WEB_PACKAGE_JSON = "apps/web/package.json";
@@ -319,10 +494,32 @@ function withDependency(deps, name, version) {
         out[name] = version;
     return out;
 }
+/** A plain `x.y.z`, `^x.y.z` or `~x.y.z` pin's version; null for any other range. */
+function pinnedVersion(range) {
+    const match = /^[\^~]?(\d+)\.(\d+)\.(\d+)$/.exec(range.trim());
+    return match === null
+        ? null
+        : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `current` pins a version strictly older than `wanted` does. */
+function isOlderPin(current, wanted) {
+    const a = pinnedVersion(current);
+    const b = pinnedVersion(wanted);
+    if (a === null || b === null)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
 /**
  * Write the slice into `targetDir` (D3). A file that already exists is left
  * byte-for-byte and reported `skipped` — the config is the site's once
- * written. Adds the package to `apps/web/package.json` only when absent.
+ * written. Adds the package to `apps/web/package.json` when absent, and
+ * raises a plain pin older than the one it writes (#7839): the generated
+ * checkout e2e workflow runs a command a `^0.2.0` pin never reaches. Any
+ * other range — newer, `workspace:`, a tag — is the site's and is kept.
  * Every refusal (an invalid stamp, a version map without the package, a
  * missing or malformed `apps/web/package.json`) throws before the first write.
  */
@@ -345,8 +542,14 @@ export function writeSpokeCheckoutSlice(targetDir, opts) {
         rows.push({ path, action: "written" });
     }
     const deps = pkg.dependencies ?? {};
-    if (!Object.prototype.hasOwnProperty.call(deps, SPOKE_CHECKOUT_PACKAGE)) {
-        pkg.dependencies = withDependency(deps, SPOKE_CHECKOUT_PACKAGE, version);
+    const current = Object.prototype.hasOwnProperty.call(deps, SPOKE_CHECKOUT_PACKAGE)
+        ? deps[SPOKE_CHECKOUT_PACKAGE]
+        : undefined;
+    if (current === undefined || isOlderPin(current, version)) {
+        pkg.dependencies =
+            current === undefined
+                ? withDependency(deps, SPOKE_CHECKOUT_PACKAGE, version)
+                : { ...deps, [SPOKE_CHECKOUT_PACKAGE]: version };
         const after = `${JSON.stringify(pkg, null, 2)}${before.endsWith("\n") ? "\n" : ""}`;
         writeFileSync(pkgPath, after);
         rows.push({

package/dist/topology.d.ts

@@ -122,6 +122,14 @@ export declare function isSpokeExcluded(path: string, opts: IsSpokeExcludedOptio
  * install passes no remap.
  */
 export declare function spokeDestination(destination: string): string;
+/**
+ * The MCP tools a spoke does not serve (#8070 D7). `create_project` spawns
+ * `packages/create-ailk/dist/cli.js` from the MCP host's working directory,
+ * which a spoke does not carry. Both seams carry the list, so the MCP
+ * server's registration and the web discovery manifest agree; a hub's is
+ * empty.
+ */
+export declare const SPOKE_UNSERVED_MCP_TOOLS: readonly string[];
 /**
  * `apps/web/lib/topology.generated.ts` for `topology` (D5) and, on a spoke,
  * its sign-in mode (#7894 D8). The hub render loads `auth.ts` only when a

package/dist/topology.js

@@ -269,13 +269,30 @@ const WEB_SEAM_HEADER = `// topology.generated.ts — how this site reads a sess
 // every scaffold rewrites it. A hub reads the session through Better Auth.
 // A spoke (\`--topology spoke\`) has no database of its own: by default it
 // has no sign-in, so its render reads no session and imports nothing; with
-// \`--hub-sign-in\` (#7894) it reads the sealed hub-session cookie.`;
+// \`--hub-sign-in\` (#7894) it reads the sealed hub-session cookie.
+// UNSERVED_MCP_TOOLS names the MCP tools /.well-known/mcp.json leaves out
+// on this topology (#8070).`;
 const MCP_SEAM_HEADER = `// topology.generated.ts — how this MCP server resolves its workspace store.
 //
 // GENERATED by create-ailk for this site's topology (#7426). Do not edit:
 // every scaffold rewrites it. A hub resolves its workspace through the
 // database; a spoke (\`--topology spoke\`) has none, so its content tools
-// read the spoke's own MDX and its writes go to the hub at AILK_API_URL.`;
+// read the spoke's own MDX and its writes go to the hub at AILK_API_URL.
+// UNSERVED_MCP_TOOLS names the tools this server does not register on this
+// topology (#8070).`;
+/**
+ * The MCP tools a spoke does not serve (#8070 D7). `create_project` spawns
+ * `packages/create-ailk/dist/cli.js` from the MCP host's working directory,
+ * which a spoke does not carry. Both seams carry the list, so the MCP
+ * server's registration and the web discovery manifest agree; a hub's is
+ * empty.
+ */
+export const SPOKE_UNSERVED_MCP_TOOLS = ["create_project"];
+/** The `UNSERVED_MCP_TOOLS` export every web and mcp seam render carries. */
+function unservedToolsExport(topology) {
+    const list = topology === "spoke" ? SPOKE_UNSERVED_MCP_TOOLS : [];
+    return `export const UNSERVED_MCP_TOOLS: readonly string[] = ${JSON.stringify(list)};`;
+}
 const SITE_SESSION_TYPE = `export type SiteSession = {
   user: {
     name?: string | null;
@@ -304,6 +321,7 @@ export function renderWebSeam(topology, signIn = "off") {
         return `${WEB_SEAM_HEADER}
 
 export const TOPOLOGY: "hub" | "spoke" = "hub";
+${unservedToolsExport("hub")}
 ${signInExports({ enabled: true, provider: "site", signInPath: "/sign-in", signUpPath: "/sign-up", signOutEndpoint: null })}
 
 ${SITE_SESSION_TYPE}
@@ -324,6 +342,7 @@ export async function registerSiteStores(): Promise<void> {
 import { readHubSession } from "./hub-session/session";
 
 export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${unservedToolsExport("spoke")}
 ${signInExports({ enabled: true, provider: "hub", signInPath: "/account", signUpPath: null, signOutEndpoint: "/api/hub-session/sign-out" })}
 
 ${SITE_SESSION_TYPE}
@@ -340,6 +359,7 @@ export function registerSiteStores(): Promise<void> {
     return `${WEB_SEAM_HEADER}
 
 export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${unservedToolsExport("spoke")}
 ${signInExports({ enabled: false, provider: "none", signInPath: null, signUpPath: null, signOutEndpoint: null })}
 
 ${SITE_SESSION_TYPE}
@@ -504,6 +524,7 @@ export { registerLicenseKeyStore } from "./license-key-store.js";
 export type { McpWorkspaceResolution };
 
 export const TOPOLOGY: "hub" | "spoke" = "hub";
+${unservedToolsExport("hub")}
 
 export async function initPublicWorkspace(): Promise<void> {
   await initMcpPublicWorkspace();
@@ -523,6 +544,7 @@ export type McpWorkspaceResolution =
   | { kind: "unresolved"; reason: "ambiguous" };
 
 export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${unservedToolsExport("spoke")}
 
 export function initPublicWorkspace(): Promise<void> {
   return Promise.resolve();
@@ -782,8 +804,9 @@ export function renderSpokeHardFloors(opts) {
         "  # Surfaces that always require human review on merge, regardless of",
         "  # automation level. This site is a SPOKE (create-ailk --topology spoke):",
         "  # it has no apps/api, no database and no sign-in of its own. Pricing, the",
-        "  # Stripe webhook route, the checkout route and its price map, and the",
-        "  # sign-in paths are floored so their arrival here is a human merge.",
+        "  # Stripe webhook route, the checkout route, its price map and its e2e",
+        "  # workflow, and the sign-in paths are floored so their arrival here is a",
+        "  # human merge.",
         "  - kind: pricing",
         "  - kind: stripe_live_mode",
         "  - paths:",
@@ -792,7 +815,8 @@ export function renderSpokeHardFloors(opts) {
         "  - paths:",
         '      - "apps/web/app/api/checkout/**"',
         '      - "apps/web/lib/checkout-config.ts"',
-        "    reason: Spoke checkout — the buy route and the price map require human review",
+        '      - ".github/workflows/checkout-e2e.yml"',
+        "    reason: Spoke checkout — the buy route, the price map and the checkout e2e workflow require human review",
         "  - paths:",
         '      - "apps/web/auth.ts"',
         '      - "apps/web/app/api/auth/**"',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,8 +27,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.38.0",
-    "@working-theory/templates": "0.38.0"
+    "@working-theory/templates": "0.38.0",
+    "@working-theory/schema": "0.38.0"
   },
   "repository": {
     "type": "git",

package/templates/apps/mcp/CLAUDE.md

@@ -8,6 +8,50 @@ Inherits root `CLAUDE.md`. This file adds MCP-specific rules.
 - Transport: stdio at launch
 - Discovery: `/.well-known/mcp.json` published from `apps/web`
 
+## Two entrypoints, one boot (#8070)
+
+- **`src/index.ts`** — run locally: stdio (the default), or HTTP on `MCP_HTTP_PORT` with
+  `MCP_TRANSPORT=http`.
+- **`src/app.ts`** — the Vercel entry. A Vercel project whose root directory is `apps/mcp`
+  detects it (it imports Fastify) and calls its default export, `serverlessHandler(app)`: a
+  `(req, res)` function, the shape Vercel's Node runtime runs — a bare Fastify instance is not
+  one and answers every request with a 500. It never listens. There is **no `vercel.json`**: a
+  `functions` pattern for `src/app.ts` is rejected for the `fastify` builder, so the site's
+  `content/` reaches the function by the builder's file tracing, and the 30-second request cap
+  is `export const config = { maxDuration: 30 }` in `app.ts` (a literal object — the builder
+  reads it by static analysis). `tsconfig.json` names `module` and `moduleResolution` itself:
+  Vercel's type-check edits the entry's nearest `tsconfig.json` as raw JSON before `extends`,
+  and without its own `module` it switches `strict` off, which fails 11 narrowing sites.
+- Both call `bootMcp()` in `src/boot.ts` before building a transport, and read the HTTP
+  configuration through `httpTransportConfigFromEnv()` there. Add a boot step to `bootMcp()`,
+  never to one entry. `src/app.ts` stays thin; what a test needs is in `src/serverless-app.ts`.
+- **`MCP_HTTP_STATELESS`** picks the transport mode: `true`/`1` stateless (no sessions; any
+  instance answers), `false`/`0` stateful (sessions in one process's memory). Unset, the
+  Vercel entry is stateless and `src/index.ts` is stateful. Any other value fails the boot.
+  The Vercel entry needs stateless: a session kept in one instance is lost on the next.
+- **Content root.** Every content tool and `audit` take their root from `mcpContentRoot()`
+  (`lib/content-adapter.ts`): `AILK_CONTENT_ROOT`, else `<cwd>/content`, else
+  `<cwd>/../../content`. Never build a content path from `process.cwd()` in a tool.
+- **`create_project`** is not served on a spoke: the generated seam's `UNSERVED_MCP_TOOLS`
+  keeps it out of registration, and the web manifest drops the same list.
+
+### What a spoke's MCP host on Vercel enforces
+
+- **The address is the caller's, behind exactly one proxy.** The Vercel entry trusts one hop
+  (`trustOneHop`, `src/serverless-app.ts`), so the limits key on the address Vercel's edge
+  saw and a caller's own `X-Forwarded-For` cannot move the key. This holds when the MCP host
+  name points straight at the Vercel project; a second proxy in front keys every caller on
+  that proxy. It is a function, not `trustProxy: 1`, because Fastify 5.12 treats a numeric
+  hop count as trusting nothing. The long-running entry trusts no proxy.
+- **Per address, per instance.** 60 requests a minute across reads and writes (the write rate
+  is parsed but not enforced); `capture_lead` 50 a day and `start_purchase` 20 a day.
+  `subscribe_newsletter` and `request_callback` have no daily cap. Each warm instance counts
+  on its own and a cold start resets the counts, so a caller reaching N instances gets up to
+  N times each limit.
+- **At the hub, one shared bucket.** The MCP lead tools forward no visitor address, so the
+  hub's lead limiter counts every MCP lead write from a spoke against the MCP host's egress
+  address (#8073).
+
 ## Identity-blind by design (hard rule)
 
 This rule governs the anonymous surface, `/mcp` (and stdio) — every tool the catalog returns with
@@ -56,14 +100,14 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   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
+  presence alone, and the boot (`bootMcp()`) logs one 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`.
+  `index.ts` and `app.ts` are the transport entry points and export no tools —
+  registration is entirely via `createMcpServer`.
 
 ## The signed-in workspace surface (`/mcp/workspace`, #3591)
 
@@ -118,7 +162,7 @@ here. Spec: `docs/specs/3591-tenant-scoped-agent-auth-secure-spec.md` D13–D16.
   server's tool list, and calling it by name there returns the module-disabled
   `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
+  (`src/lib/commerce-claim.ts`, awaited in `bootMcp()`, `src/boot.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
   (`MCP_ABUSE_START_PURCHASE_DAILY_CAP`, default 20, on its own tracker).
@@ -164,7 +208,9 @@ Example (lead routing):
 - 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-10-04 — #3591 PR-E (#7684): the identity-blind rule is scoped to the anonymous `/mcp`, and the new § The signed-in workspace surface records `/mcp/workspace` — POST-only and stateless, an agent key per request forwarded to each tool's apps/api twin, eleven `surface: "workspace"` catalog rows that are parity `twin`s and never in the discovery manifest — verified against `apps/mcp/src/http-transport.ts`, `apps/mcp/src/workspace-server.ts` and `packages/metadata/src/mcp-tool-catalog.ts`.
+Last updated: 2026-10-10 — #8070 (amendment 2): the Vercel entry exports a handler, no `vercel.json`; § Two entrypoints, one boot — the Vercel entry `src/app.ts`, the shared `src/boot.ts`, `MCP_HTTP_STATELESS`, `mcpContentRoot()`, `create_project` withheld on a spoke, and what a spoke's MCP host enforces — verified against `apps/mcp/src/{app,boot,serverless-app,index,http-transport,server}.ts` and `lib/content-adapter.ts`.
+
+Prior: 2026-10-04 — #3591 PR-E (#7684): the identity-blind rule is scoped to the anonymous `/mcp`, and the new § The signed-in workspace surface records `/mcp/workspace` — POST-only and stateless, an agent key per request forwarded to each tool's apps/api twin, eleven `surface: "workspace"` catalog rows that are parity `twin`s and never in the discovery manifest — verified against `apps/mcp/src/http-transport.ts`, `apps/mcp/src/workspace-server.ts` and `packages/metadata/src/mcp-tool-catalog.ts`.
 
 Prior: 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.