create-ailk 0.1.1 → 0.3.0

package/dist/parse-args.d.ts

@@ -7,7 +7,7 @@
  * composition is downstream work, so the default (`marketing`) reproduces
  * today's fixed-tree scaffold exactly.
  */
-export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs", "multi-tenant", "scheduling"];
+export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs-blog", "multi-tenant", "scheduling", "signal-collectors", "commerce"];
 export type ModuleName = (typeof RECOGNIZED_MODULES)[number];
 export interface CliOptions {
     /** Positional target directory (the dir to scaffold into). Optional only
@@ -16,7 +16,7 @@ export interface CliOptions {
     install: boolean;
     help: boolean;
     version: boolean;
-    /** Selected modules (recognized: marketing, docs, multi-tenant, scheduling).
+    /** Selected modules (recognized: marketing, docs-blog, multi-tenant, scheduling).
      *  Defaults to ['marketing'] when the flag is absent. */
     modules: string[];
     /** Explicitly requested route surfaces (`--surfaces`). Empty when the flag is

package/dist/parse-args.js

@@ -20,9 +20,11 @@ import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
  */
 export const RECOGNIZED_MODULES = [
     "marketing",
-    "docs",
+    "docs-blog",
     "multi-tenant",
     "scheduling",
+    "signal-collectors",
+    "commerce",
 ];
 /** The default module selection when `--modules` is absent (reproduces today's scaffold). */
 const DEFAULT_MODULES = ["marketing"];

package/dist/programmatic.d.ts

@@ -29,7 +29,8 @@ export interface ScaffoldOptions {
      */
     preset?: string;
     /**
-     * Selected modules (recognized: marketing, docs, multi-tenant). Defaults to
+     * Selected modules (recognized: marketing, docs-blog, multi-tenant,
+     * scheduling). Defaults to
      * ['marketing']. The scaffolder does NOT yet vary the copied template tree by
      * module (per-module template composition is downstream work), so the copied
      * files are today's fixed-tree scaffold — BUT the derived `architecture.yaml`

package/dist/programmatic.js

@@ -134,11 +134,17 @@ export async function scaffold(opts) {
         ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
     });
     const result = scaffoldSync(opts);
+    // Threaded to extractModuleBundle for `package.json` patch targets'
+    // `workspace:*` substitution (spec 5418 § 3 D2) — the same version map
+    // `scaffoldSync` already reads for `copyTemplate`, re-read here since
+    // `scaffold()` doesn't share `scaffoldSync`'s call frame.
+    const versions = readVersionMap();
     for (const [moduleName, bytes] of bundles) {
         await extractModuleBundle({
             bytes,
             targetDir: result.targetDir,
             moduleName,
+            versions,
         });
     }
     return result;
@@ -194,10 +200,15 @@ export function syncArchitectureSync(opts) {
  * stats paths and returns strings, and never writes or deletes.
  *
  * Routes only, deliberately. A surface's content directories are informational
- * (`Surface.content`), not drift: `apps/web/content/<locale>/{blog,docs}` must
- * exist in EVERY scaffold — `source.config.ts` resolves those paths at build
- * time whether or not the route is mounted — so sweeping content here would
- * tell every operator to delete directories the build requires.
+ * (`Surface.content`), not drift, so sweeping content here would tell an
+ * operator to delete directories that merely hold their own copy.
+ *
+ * This used to rest on a stronger claim — that `apps/web/content/<locale>/
+ * {blog,docs}` must exist in EVERY scaffold, because `source.config.ts`
+ * resolved those paths at build time whether or not the route mounted. D-46
+ * retired it: `source.config.ts` leaves with the docs + blog module (#5365 D3),
+ * so a Free scaffold defines no Fumadocs collection and carries neither
+ * directory.
  */
 function findUndeclaredSurfacePaths(targetAbs, enabled) {
     return excludedRoutePaths(enabled)

package/dist/surfaces.d.ts

@@ -1,36 +1,3 @@
-/**
- * Route-surface registry — which public routes a scaffolded site carries.
- *
- * A SURFACE is one public route surface of the presentation tier (see
- * architecture.yaml `composition_model`): a hub route plus the detail route and
- * content directories that feed it. The registry is the single source of the
- * surface vocabulary, in the same spirit as `module-architecture.ts` is the
- * single source of the module→architecture-slice mapping — a code registry, not
- * N hand-maintained template trees.
- *
- * Two tiers:
- *
- *   - CORE_SURFACE_PATHS — the routes every AILK site has regardless of what
- *     the business is (`/`, `/about`, `/contact`, `/faq`, `/thanks/{slug}`).
- *     Always scaffolded, never gateable.
- *   - GATEABLE_SURFACES — everything else. A surface is scaffolded ONLY when
- *     the declared architecture carries it; otherwise its route directories are
- *     skipped by `copyTemplate` and the routes are ABSENT from the scaffold,
- *     not present-and-placeholdering (spec #4154 D1).
- *
- * The default (`--modules marketing`) enables NO gateable surface: every one of
- * them is a claim about the business that the scaffolder cannot make. The path
- * from there is the `suggest-site-pages` → `scaffold-page` skill pair that
- * already ships in `templates/.claude/skills/`.
- *
- * Zero runtime dependencies — create-ailk is a published, standalone CLI.
- *
- * Deliberately imports nothing from `parse-args.ts`: that module imports THIS
- * one (for the `--surfaces` vocabulary in its help text), so a back-import
- * would close a cycle. The module vocabulary is re-stated here as the keys of
- * `MODULE_SURFACES`, and `__tests__/surface-gating.test.ts` asserts those keys
- * equal `RECOGNIZED_MODULES` so the two cannot drift.
- */
 /**
  * Route paths (site-relative, for the record written into `architecture.yaml`)
  * that every scaffold carries.
@@ -88,9 +55,18 @@ export declare const RECOGNIZED_SURFACES: readonly string[];
  * Surfaces each recognized module contributes.
  *
  * `marketing` (the default) contributes NONE — a default scaffold is core-only.
- * `docs` mounts the Fumadocs presentation surface; `multi-tenant` brings the
- * flow-stepper surface with its API-backed engine; `scheduling` brings the
- * booking page and the confirmation page the module owns.
+ * `docs-blog` mounts BOTH Fumadocs presentation surfaces: D-46 made docs and
+ * blog one Pro module, so `/blog` is no longer a Free surface that any scaffold
+ * can turn on. `multi-tenant` contributes no surface of its own — it USED to
+ * carry `flows`, but D-48 reassigns that surface to `signal-collectors`
+ * (#5366), which now brings the flow-stepper surface with its API-backed
+ * engine; `scheduling` brings the booking page and the confirmation page the
+ * module owns.
+ *
+ * A surface named here is MODULE-GATED: `resolveSurfaces` refuses it as an
+ * explicit `--surfaces` value unless the module that owns it was selected
+ * (#5365 FR5). Without that, `--surfaces blog` on a keyless scaffold would
+ * declare a surface whose route files the starter no longer contains.
  */
 export declare const MODULE_SURFACES: Record<string, readonly string[]>;
 /** Thrown on an unrecognized surface id. Mirrors parse-args' ParseError shape. */

package/dist/surfaces.js

@@ -230,15 +230,26 @@ export const RECOGNIZED_SURFACES = GATEABLE_SURFACES.map((s) => s.id);
  * Surfaces each recognized module contributes.
  *
  * `marketing` (the default) contributes NONE — a default scaffold is core-only.
- * `docs` mounts the Fumadocs presentation surface; `multi-tenant` brings the
- * flow-stepper surface with its API-backed engine; `scheduling` brings the
- * booking page and the confirmation page the module owns.
+ * `docs-blog` mounts BOTH Fumadocs presentation surfaces: D-46 made docs and
+ * blog one Pro module, so `/blog` is no longer a Free surface that any scaffold
+ * can turn on. `multi-tenant` contributes no surface of its own — it USED to
+ * carry `flows`, but D-48 reassigns that surface to `signal-collectors`
+ * (#5366), which now brings the flow-stepper surface with its API-backed
+ * engine; `scheduling` brings the booking page and the confirmation page the
+ * module owns.
+ *
+ * A surface named here is MODULE-GATED: `resolveSurfaces` refuses it as an
+ * explicit `--surfaces` value unless the module that owns it was selected
+ * (#5365 FR5). Without that, `--surfaces blog` on a keyless scaffold would
+ * declare a surface whose route files the starter no longer contains.
  */
 export const MODULE_SURFACES = {
     marketing: [],
-    docs: ["docs"],
-    "multi-tenant": ["flows"],
+    "docs-blog": ["docs", "blog"],
+    "multi-tenant": [],
     scheduling: ["schedule"],
+    "signal-collectors": ["flows"],
+    commerce: [],
 };
 /** Thrown on an unrecognized surface id. Mirrors parse-args' ParseError shape. */
 export class SurfaceError extends Error {
@@ -290,14 +301,33 @@ export function resolveSurfaces(modules = ["marketing"], explicit = []) {
         for (const s of contributed)
             set.add(s);
     }
+    const selected = new Set(modules.map((m) => m.trim().toLowerCase()));
     for (const s of explicit) {
         if (!RECOGNIZED_SURFACES.includes(s)) {
             throw new SurfaceError(`unknown surface "${s}". Recognized: ${RECOGNIZED_SURFACES.join(", ")}`);
         }
+        // A surface a module OWNS cannot be declared without that module (#5365
+        // FR5/D12). The starter no longer carries the route files, so a bare
+        // `--surfaces blog` would declare a surface that serves 404 with no error
+        // anywhere — the silent-wrong-result this refusal closes. Keyed on
+        // MODULE_SURFACES, never on a surface id, so every module inherits it.
+        const owner = moduleOwningSurface(s);
+        if (owner !== undefined && !selected.has(owner)) {
+            throw new SurfaceError(`surface "${s}" is delivered by the "${owner}" module — add it with ` +
+                `--modules ${owner} (a paid module also needs AILK_LICENSE_KEY).`);
+        }
         set.add(s);
     }
     return [...set].sort();
 }
+/** The module that owns a gateable surface, or undefined if no module does. */
+function moduleOwningSurface(surface) {
+    for (const [moduleName, contributed] of Object.entries(MODULE_SURFACES)) {
+        if (contributed.includes(surface))
+            return moduleName;
+    }
+    return undefined;
+}
 /**
  * The template-relative route directories to SKIP when copying the template —
  * every gateable surface not in `enabled`.

package/dist/sync-routes.js

@@ -35,6 +35,18 @@ import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
+/**
+ * `<surface id>/<entry name>` pairs that live directly under a GATEABLE
+ * surface's top-level directory but belong to a DIFFERENT module (#5366).
+ * `projects/apply` (#5048) is signal-collectors' own owned file
+ * (`ListingApplicationClient.tsx`, D-48) — its module bundle restores it
+ * whenever signal-collectors is selected, independent of the unrelated
+ * "projects" content surface's own selection. See the doc comment on
+ * `syncRoutes`'s `carried` computation.
+ */
+const NESTED_FOREIGN_MODULE_ENTRIES = new Set([
+    "projects/apply",
+]);
 /**
  * The template's route directories, ROUTE_ROOT-relative and sorted.
  *
@@ -120,12 +132,30 @@ export function syncRoutes(opts) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
     // Presence of any of a surface's route dirs means the site carries it.
+    // A surface's directory containing ONLY entries in
+    // `NESTED_FOREIGN_MODULE_ENTRIES` does not count as present (#5366): a
+    // DIFFERENT module can own a companion sub-route nested under an unrelated
+    // content surface's URL segment — `projects/apply` (#5048) is
+    // signal-collectors' own owned file (D-48), and its module bundle restores
+    // it whenever signal-collectors is selected, regardless of whether the
+    // unrelated "projects" CONTENT surface is separately requested. Without
+    // this exclusion, a signal-collectors-only scaffold would falsely read as
+    // "carries projects" the moment its bundle lands that one file.
     const carried = new Set();
     const skippedSurfaces = [];
     for (const surface of GATEABLE_SURFACES) {
         const present = surface.routes.some((r) => {
             const p = join(targetAbs, r);
-            return existsSync(p) && statSync(p).isDirectory();
+            if (!existsSync(p) || !statSync(p).isDirectory())
+                return false;
+            const entries = readdirSync(p);
+            // An ancestor dir left empty by a consumer-side deletion (AC-2's
+            // "ancestor also missing" case) still counts as carried — only a
+            // NON-empty directory whose entries are entirely foreign (the
+            // `projects`/`apply` case above) does not.
+            if (entries.length === 0)
+                return true;
+            return entries.some((name) => !NESTED_FOREIGN_MODULE_ENTRIES.has(`${surface.id}/${name}`));
         });
         if (present)
             carried.add(surface.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -30,18 +30,6 @@
   "bugs": {
     "url": "https://github.com/working-theory-labs/ai-launch-kit/issues"
   },
-  "scripts": {
-    "lint": "tsx ../../scripts/lint-package.ts",
-    "build": "tsc -b",
-    "type-check": "tsc --noEmit",
-    "test": "tsc -b && node scripts/build-templates.mjs && jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "build-templates": "node scripts/build-templates.mjs",
-    "build-catalog": "node scripts/build-component-catalog.mjs",
-    "check-catalog": "node scripts/build-component-catalog.mjs --check",
-    "prepublishOnly": "node scripts/build-templates.mjs && node scripts/build-component-catalog.mjs && tsc -b"
-  },
   "engines": {
     "node": ">=20.0.0"
   },
@@ -51,5 +39,16 @@
     "create-ailk",
     "ai-launch-kit"
   ],
-  "license": "Apache-2.0"
-}
+  "license": "Apache-2.0",
+  "scripts": {
+    "lint": "tsx ../../scripts/lint-package.ts",
+    "build": "tsc -b",
+    "type-check": "tsc --noEmit",
+    "test": "tsc -b && node scripts/build-templates.mjs && jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "build-templates": "tsc -b && node scripts/build-templates.mjs",
+    "build-catalog": "node scripts/build-component-catalog.mjs",
+    "check-catalog": "node scripts/build-component-catalog.mjs --check"
+  }
+}

package/templates/.claude/agents/web.md

@@ -72,9 +72,8 @@ Run `pnpm preflight` before opening a PR.
   speak to the API via `@working-theory/api-client`.
 - Importing `@working-theory/database` — `apps/web` does not touch the DB;
   route through `apps/api`.
-- Importing `stripe`, `resend`, `@react-email/*` directly — wrap
-  through `@working-theory/stripe-client` or `@working-theory/email`, server-side via
-  `apps/api`.
+- Importing `resend`, `@react-email/*` directly — wrap through
+  `@working-theory/email`, server-side via `apps/api`.
 - Adding a `utils.ts`, `helpers.ts`, `common.ts`, or `misc.ts` file
   — use a descriptive name.
 - Reformatting unrelated lines. Diff is the contract.

package/templates/.claude/rules/architecture.md

@@ -28,10 +28,10 @@ other.
 - Need database access? Only `apps/api` and `apps/mcp` import
   `@working-theory/database`. `apps/web` never reads the database directly — it
   goes through the HTTP API.
-- Cross-cutting integrations (auth, payments, email, analytics) go
-  through their wrapper packages: `@working-theory/auth-client`,
-  `@working-theory/stripe-client`, `@working-theory/email`, `@working-theory/analytics`. Never
-  import `next-auth`, `stripe`, `resend`, etc. directly.
+- Cross-cutting integrations (auth, email, analytics) go through their
+  wrapper packages: `@working-theory/auth-client`, `@working-theory/email`,
+  `@working-theory/analytics`. Never import `next-auth`, `resend`, etc.
+  directly.
 
 ## What you can verify, what you can't
 
@@ -62,5 +62,5 @@ These never appear in source code:
   by being named on a ban-list. Live keys live in your deployment
   platform's secrets store, never in source files or `.env`.
 - Direct vendor SDK imports outside the wrapper packages
-  (`import 'stripe'` outside `@working-theory/stripe-client`, etc.).
+  (`import 'resend'` outside `@working-theory/email`, etc.).
 - Hardcoded production database URLs in committed files.

package/templates/.claude/skills/README.md

@@ -17,12 +17,13 @@ local project's issues.
 | -------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
 | `suggest-site-pages` | Generic page-type suggestions by category              | coming soon — issue #361 (working-theory-labs/ai-launch-kit) |
 | `scaffold-page`      | Generate a page with the appropriate schema.org type   | coming soon — issue #362 (working-theory-labs/ai-launch-kit) |
-| `scaffold-commerce`  | Sell stuff: external store link or direct payments     | coming soon — issue #363 (working-theory-labs/ai-launch-kit) |
 | `scaffold-auth`      | Wire up an auth flow against `@working-theory/auth-client`       | coming soon — issue #364 (working-theory-labs/ai-launch-kit) |
 | `audit-site`         | Run `ailk audit` and explain the results               | coming soon — issue #365 (working-theory-labs/ai-launch-kit) |
 | `add-schema`         | Add Product / Service / FAQ schema to an existing page | coming soon — issue #366 (working-theory-labs/ai-launch-kit) |
 | `provision-config`   | Generate `vercel.json` and environment templates       | coming soon — issue #367 (working-theory-labs/ai-launch-kit) |
 
+`scaffold-commerce` is delivered with the commerce module (`--modules commerce`, licensed).
+
 ## How a skill ships
 
 When a skill is built upstream, this directory will contain a

package/templates/.env.example

@@ -98,11 +98,20 @@ CONTENT_BACKEND=mdx
 # default.
 # RESEND_AUDIENCE_ID=
 #
-# The public base URL this API is reachable at — used ONLY to build the
-# deliverable-delivery download link (#3961 D5):
-# `${AILK_PUBLIC_API_URL}/v1/deliverables/:grantId`. Unset means a relative
-# link (base ""), which is not usable from an email client — set this in any
-# deployment that uses the `deliverables` block.
+# The public base URL this API is reachable at, e.g. https://api.example.com
+# (no trailing slash). This is the API's OWN origin — distinct from
+# FRONTEND_URL (the site the browser loads) and from `_site.mdx`'s `baseUrl`
+# (the site's public web origin). A deployment typically serves the site from
+# example.com and this API from api.example.com, so neither of the other two
+# can stand in for it. Two consumers:
+#
+#   1. The deliverable-delivery download link (#3961 D5):
+#      `${AILK_PUBLIC_API_URL}/v1/deliverables/:grantId`. Unset means a
+#      relative link (base ""), which is not usable from an email client — set
+#      this in any deployment that uses the `deliverables` block.
+#   2. The OpenAPI `servers` block (#5306). Unset degrades to a single
+#      document-relative server (`/`), which an agent resolves against the
+#      origin it fetched the spec from — correct, just less explicit.
 # AILK_PUBLIC_API_URL=
 #
 # The apps/api origin @working-theory/api-client calls from
@@ -313,11 +322,14 @@ CONTENT_BACKEND=mdx
 # apps/api's origin as seen from apps/web's SERVER process — the api-client's
 # base URL (getApiBase(), packages/api-client/src/http.ts) for every flow
 # Server Action call (flows.get / submitStep / save / checkout). AILK_API_URL
-# wins; NEXT_PUBLIC_API_URL is the fallback; both unset resolves to
+# wins; NEXT_PUBLIC_AILK_API_URL (apps/web/.env.example) is the fallback, and
+# is also what getApiBase() resolves in the BROWSER, where only a
+# NEXT_PUBLIC_-prefixed name is inlined (#5397); NEXT_PUBLIC_API_URL is still
+# read after it as a DEPRECATED fallback for deployments that set it under the
+# old behaviour — do not set it in a new one. All unset resolves to
 # http://localhost:3001 (local dev only — off-localhost every save / checkout
-# call fails as `network`). Distinct from NEXT_PUBLIC_AILK_API_URL
-# (apps/web/.env.example), which BROWSER-side blocks post to directly. Set on
-# every apps/web deployment whose API is not on localhost.
+# call fails as `network`). Set AILK_API_URL on every apps/web deployment whose
+# API is not on localhost.
 # AILK_API_URL=http://localhost:3001
 #
 # NEXT_PUBLIC_ENABLED_LOCALES — do NOT set by hand. Baked at build time by

package/templates/CONVENTIONS.md

@@ -174,13 +174,12 @@ Vendor SDKs are imported only inside their `@working-theory/*` wrapper. The
 wrapper exports a typed, project-flavored interface; your code imports
 from the wrapper.
 
-| Vendor              | Wrapper package       | Where you use it             |
-| ------------------- | --------------------- | ---------------------------- |
-| Stripe              | `@working-theory/stripe-client` | `apps/api` checkout/webhooks |
-| NextAuth            | `@working-theory/auth-client`   | `apps/api`, `apps/web`       |
-| Resend / Nodemailer | `@working-theory/email`         | `apps/api`                   |
-| Analytics           | `@working-theory/analytics`     | `apps/web`, `apps/api`       |
-| Prisma              | `@working-theory/database`      | `apps/api`, `apps/mcp`       |
+| Vendor              | Wrapper package               | Where you use it       |
+| ------------------- | ----------------------------- | ---------------------- |
+| NextAuth            | `@working-theory/auth-client` | `apps/api`, `apps/web` |
+| Resend / Nodemailer | `@working-theory/email`       | `apps/api`             |
+| Analytics           | `@working-theory/analytics`   | `apps/web`, `apps/api` |
+| Prisma              | `@working-theory/database`    | `apps/api`, `apps/mcp` |
 
 The wrapper is where retries, signature verification, error mapping,
 and config defaults live. Don't reinvent them per consumer.

package/templates/apps/api/.env.example

@@ -58,6 +58,15 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # (#4288) lands as a second value here with no change to the section.
 # SCHEDULING_PROVIDER=cal
 
+# =============================================================================
+# Paid modules (D-44, #5368)
+# =============================================================================
+# Comma-separated allowlist of installed paid modules, e.g.
+# "multi-tenant,scheduling". Unset (the default) or "" means NO paid modules
+# — installed modules enable themselves explicitly. Recognized keys: docs,
+# multi-tenant, scheduling, content-write. Must match apps/mcp's value.
+# AILK_ENABLED_MODULES=
+
 # ── Project listings — site addressing (#5048 D2) ───────────────────────────
 # AILK_SITE_ID is this deployment's own site identifier. Unset means "default".
 # It is read SERVER-SIDE only; no request body carries a site identifier.

package/templates/apps/api/CLAUDE.md

@@ -8,6 +8,26 @@ Inherits root `CLAUDE.md`. This file adds API-specific rules.
 - Persistence: configurable adapter (default DB; file fallback so OSS works without DB config)
 - Email: operator-notification stub at OSS; routing pipeline at Pro (in `@working-theory/*`)
 
+## Deploy path
+
+**The supported deploy path is plain `tsc` output, traced and compiled by `@vercel/node`.** `vercel.json` sets `framework: null` and routes every request to `/api/index.ts`; `build:vercel` runs `prisma generate` and two package builds and does NOT compile `apps/api` — Vercel's own builder does, through `nodeFileTrace`. That tracer is what decides which files ship.
+
+**Bundling `apps/api` is NOT a supported deploy path** (#5334). This is a property of the analysers, not a policy:
+
+- Paid-module slices are loaded through an indirect dynamic `import()`, because a string literal at the call site would make `tsc` resolve a path the OSS strip removes (#5182).
+- esbuild bundles a dynamic `import()` **only** when its argument is a string literal at the call site — the same predicate `tsc` resolves on. So no expression shape satisfies both the strip and a bundler.
+- In a bundled build the specifier therefore survives verbatim and Node resolves it against the **bundle's output directory** rather than its source module's: `"./list.js"`, written in `src/routes/project-listings/index.ts`, becomes `dist/list.js` and does not exist. esbuild emits no warning. The throw lands inside `build()`, which is construction, so **every route 500s rather than one** — measured in production, nine hours of total API outage on a consuming site.
+
+If a dependency is forcing you toward a bundler (an extensionless relative import in a published `dist`, say), fix the dependency's packaging — don't bundle `apps/api`. If you bundle anyway, `loadSlice()` (`src/lib/slice-load.ts`) makes the failure say so at boot instead of failing mute; it does not make bundling work.
+
+Three gates hold this together. Run them from the repo root, with `apps/api/dist` built:
+
+```bash
+pnpm slice-reachability:check   # every slice specifier is reachable to @vercel/nft
+pnpm artifact-boots:check       # the traced artifact boots and answers /health 200
+pnpm bundled-build:check        # a bundled build fails, and says why
+```
+
 ## API ↔ MCP parity (hard rule)
 
 Every endpoint here has a 1:1 MCP tool in `apps/mcp`. When you add, change, or remove an endpoint, update the MCP tool in the same PR. CI enforces — broken parity fails the build.
@@ -17,8 +37,9 @@ Every endpoint here has a 1:1 MCP tool in `apps/mcp`. When you add, change, or r
 Routes are versioned under `/v1/*`:
 
 - `/v1/leads/{submit,subscribe,callback}` — lead capture, newsletter subscription, callback request
-- `/v1/flows/:slug` (GET), `/v1/flows/:slug/steps` (POST) — serve a flow config + submit a step's answers; server-side per-step partial-state persistence (#3956)
-- `/v1/flows/:slug/aggregate` (GET) — anonymous, site-scoped per-question response counts across all completed respondents for the results reveal (#4771): respondents are completed `FlowSession` rows (not `Lead` rows — a recommending-mode respondent has no Lead until the email moment), question metadata + the chart flag come from the `WaitlistExperiment` register, and only `resultsReveal`-flagged `single`/`multi` questions are returned (`src/services/flow-aggregate.ts`). No individual answer, email, name, session id, or score in the response; no auth. No MCP twin — recorded exception (an agent walking a flow already gets everything it needs from `submit_flow_step`'s own response; "how everyone else answered" changes none of it).
+- `/v1/flows/:slug` (GET), `/v1/flows/:slug/steps` (POST) — serve a flow config + submit a step's answers; server-side per-step partial-state persistence (#3956). Module: `signal-collectors` (D-48, #5366) — registers only when the module is enabled; MCP twins `get_flow`/`submit_flow_step` carry the same `module` tag (D7).
+- `/v1/flows/:slug/aggregate` (GET) — anonymous, site-scoped per-question response counts across all completed respondents for the results reveal (#4771): respondents are completed `FlowSession` rows (not `Lead` rows — a recommending-mode respondent has no Lead until the email moment), question metadata + the chart flag come from the `WaitlistExperiment` register, and only `resultsReveal`-flagged `single`/`multi` questions are returned (`src/services/flow-aggregate.ts`). No individual answer, email, name, session id, or score in the response; no auth. Module: `signal-collectors`. No MCP twin — recorded exception (an agent walking a flow already gets everything it needs from `submit_flow_step`'s own response; "how everyone else answered" changes none of it).
+- `/v1/deliverables/:grantId` (GET) — the capability-token download route for gated PDFs and reports, including client deliverables (#3961 D5); the token itself is the sole gate, no auth preHandler applies (`src/routes/deliverables/index.ts`). Module: `signal-collectors` (D-48, #5366). No MCP twin — identity-bound capability-link download (#3591 exception, the same shape as `/v1/waitlist-signups/me`).
 - `/v1/flows/:slug/save` (POST), `/v1/flows/:slug/checkout` (POST) — the recommender's email moment (#4841): `save` creates the FlowSession + Lead (+ the T+0 DeliverableGrant) for the permalink's answers; `checkout` does the same, records the `FlowCheckout` buyer row at a SERVER-recomputed `price()` (the body carries no amount — `flowCheckoutInputSchema` is strict), and opens a Stripe TEST-mode Checkout Session whose metadata carries the permalink + offer key (`src/routes/flows/recommender.ts`, `src/services/recommender-capture.ts`, `packages/stripe-client`'s `createQuotedCheckoutSession`). Anonymous, rate-limited; a non-`sk_test_` key is refused before any side effect. No MCP twin — recorded exception: an agent walking a flow has no email to give and no card to pay with; the anonymous MCP surface is identity-blind.
 - `/v1/content/{types,:type,:type/:slug}` — public content reads
 - `/v1/auth/tokens`, `/v1/user/{profile,data/:key}` — local auth + user data
@@ -28,8 +49,11 @@ Routes are versioned under `/v1/*`:
 - `/v1/schedule/availability` (GET), `/v1/schedule/event-meta` (GET), `/v1/schedule/book` (POST) — anonymous scheduling proxy behind the provider seam (`src/services/scheduling/`); Cal.com v2 today, a self-hosted engine later, same three calls. `event-meta` is the meta-only read (title · duration · description · price) so rendering an event's facts never fetches an availability window (#4633). `CAL_API_KEY` is read server-side only. MCP twins: `list_availability` / `get_event_meta` / `create_booking` (#4416, #4633)
 - `/v1/aeo/score` (POST), `/v1/aeo/score/example` (GET) — anonymous instant AEO score for a respondent-supplied URL, and the bundled pre-launch example, both fed by the SSRF-guarded crawler at `@working-theory/aeo/fetch` and the pure scorer at `@working-theory/aeo` (`src/services/aeo-score.ts`, #4666). No MCP twin — recorded exception, brief D7 (exposing an arbitrary-URL crawler to anonymous agents is a security-posture decision; `apps/mcp/src/tools/audit.ts` deliberately stays same-origin-locked instead).
 - `/v1/waitlist-experiments` (GET), `/v1/waitlist-experiments/:experimentId` (GET), `/v1/waitlist-experiments/:experimentId/signups` (GET), `/v1/waitlist-experiments/:experimentId/signups/:leadId` (GET) — the operator-dashboard read API for Parallel Waitlist Validation (#4665 D7, B0): tenant-scoped list + rollup, per-waitlist comparison, paginated signups, and a signup drill-down over A1's `WaitlistExperiment` / `WaitlistScore` / `Lead` rows (`src/services/waitlist-dashboard.ts`, #4671). Role floor `owner|admin` (signup PII); the platform-operator scope (`isSentinel(organizationId) && role === "owner"`, ALSO requiring `AILK_OPERATOR_EMAIL` to be set — fail-closed, PR #4687) sees every site, an ordinary owner/admin sees only its own `siteId`. No MCP twin — identity-bound tenant routes (#3591 exception, same shape as `/v1/billing/*`).
-- `/v1/waitlist-signups/me` (GET, `?experimentKey=<slug>`) — the respondent read (#4731): a signed-in, **email-verified** user's OWN newest signup for one experiment (`experimentKey`, `waitlistKey`, `completedAt`, `tier`, `score`, `aeoScore`, `answers.q3` — seven fields, nothing more; `src/services/waitlist-signups.ts` is the only read path). Registered in `authScope` only (auth, no tenant guard — a respondent has no workspace). Identity is `request.userId`; the email is the `User`'s, never a parameter; `emailVerified !== true` → 403 `email_unverified` before any `Lead` read; no match → 404 `signup_not_found`; every read scoped to `currentSiteId()`. No MCP twin — identity-bound (#3591 exception).
+- `/v1/waitlist-signups/me` (GET, `?experimentKey=<slug>`) — the respondent read (#4731): a signed-in, **email-verified** user's OWN newest signup for one experiment (`experimentKey`, `waitlistKey`, `completedAt`, `tier`, `score`, `aeoScore`, `answers.q3` — seven fields, nothing more; `src/services/waitlist-signups.ts` is the only read path). Registered in `authScope` only (auth, no tenant guard — a respondent has no workspace). Identity is `request.userId`; the email is the `User`'s, never a parameter; `emailVerified !== true` → 403 `email_unverified` before any `Lead` read; no match → 404 `signup_not_found`; every read scoped to `currentSiteId()`. Module: `signal-collectors` (D-48, #5366). No MCP twin — identity-bound (#3591 exception).
 - `/v1/flow-checkouts/me` (GET) — the respondent purchases read (#4984, FEAT-022 M2): a signed-in, **email-verified** user's OWN `FlowCheckout` rows, newest first, `[]` when none (`id`, `flowSlug`, `experimentKey`, `offerKey`, `status`, `amountMinor`, `currency`, `period`, `completedAt`, `createdAt` — ten fields, nothing more; `src/services/flow-checkouts.ts` is the only read path). Registered in `authScope` only, beside `/v1/waitlist-signups/me`. Identity is `request.userId`; rows are joined through the promotion link (`Lead.promotedUserId = userId`, `src/services/lead-promotion.ts`) — never by an email, and no query parameter is read; `emailVerified !== true` → 403 `email_unverified` before any `Lead` read; every read scoped to `currentSiteId()`. No MCP twin — identity-bound (#3591 exception).
+- `/v1/project-listings/me` (GET) — the FOUNDER'S OWN listings read (#5295): a signed-in user's own `ProjectListing` rows, newest first, `[]` when none. Registered in `authScope` only, beside `/v1/flow-checkouts/me` — a founder is not a workspace member, so the tenant guard's default-deny would answer 403 for their own submission. Identity is `request.userId`; rows are joined through the owner link (`ProjectListing.ownerUserId = userId`, stamped by `src/services/listing-promotion.ts`) — **never** by `founderEmail`, at any stage, and no query parameter is read. `founderEmail` is an unverified string typed into an anonymous form, so a read-time email match would hand one of two people sharing an address the other's submission. The row shape is `projectListingDraftSchema` (the founder-facing shape the anonymous draft read already uses — no `siteId`, `leadId`, `decidedBy`, `issueUrl`, or `experimentKey`). The route is ADDITIVE: `PROJECT_LISTING_ROLES` stays `owner|admin` and the tenant-scoped list/get/patch routes are unchanged. Module: `signal-collectors` (D-48, #5366) — not severable from the anonymous listing-application routes below (same static barrel, D4). No MCP twin — identity-bound (#3591 exception).
+- `/v1/project-listings/{start,submit}` (POST), `/v1/project-listings/:id` (PATCH, draft), `/v1/project-listings/public` (GET) — the anonymous founder's-application lifecycle (#4998, reshaped by #5036): draft start/patch/submit plus the public shelves read, identity-blind and rate-limited alongside the leads routes. Module: `signal-collectors`. No MCP twin — anonymous form-lifecycle routes, not agent-facing.
+- `/v1/slack/actions` (POST) — the project-listing operator decision (Slack Approve/Reject, #4999): verifies the Slack signature, applies the decision via `src/services/project-listing-decision.ts`. Module: `signal-collectors`. No MCP twin — a Slack-signed webhook, not agent-facing.
 
 The workspace site-config routes are **identity-bound tenant routes** (guarded by the tenant preHandler; the write scope is the caller's active workspace, never a body-supplied id). Like the sibling `/v1/workspaces/*` routes they have **no anonymous MCP twin** — the OSS MCP surface is identity-blind (`apps/mcp/CLAUDE.md`), so the "1:1 MCP tool" rule above does not apply to them; the tenant-scoped authed MCP surface is tracked in #3591. The `/v1/billing/*` and `/v1/waitlist-experiments/*` routes are the same shape — identity-bound tenant routes, admin/settings-facing rather than agent-facing, no MCP twin.
 
@@ -117,8 +141,15 @@ sweep's own DB constraint (never a caller-side lock).
 - Don't return 200 with `{ ok: false }`.
 - Don't read MDX directly — use `@working-theory/content-adapters`.
 - Don't put session state in `apps/api`. It's stateless.
+- Don't bundle `apps/api` (esbuild, rollup, webpack). Slice specifiers cannot survive it — see `## Deploy path`.
+
+Last updated: 2026-09-14 — doc-sync: signal-collectors module extraction (D-48, #5366) — added the `module: signal-collectors` note to the flows/waitlist-signups-me/project-listings-me endpoints, added the previously-undocumented `/v1/deliverables/:grantId`, `/v1/project-listings/{start,submit,:id,public}` and `/v1/slack/actions` rows — verified against `apps/api/src/server.ts` and each route's own header.
+
+Prior: 2026-09-12 — doc-sync: added the `## Deploy path` section and the matching `## What NOT to do` line (#5334), recording that bundling `apps/api` is not a supported deploy path and naming the three gates — verified against `apps/api/vercel.json`, `apps/api/src/lib/slice-load.ts` and `scripts/check-bundled-build-diagnoses.ts`.
+
+Prior: 2026-09-12 — doc-sync: added `GET /v1/project-listings/me` (#5295), the auth-scoped founder read joined on the owner link, to Endpoint conventions — verified against `apps/api/src/routes/project-listings/me.ts` and `apps/api/src/server.ts`.
 
-Last updated: 2026-09-07 — doc-sync: added `listing-csv:sweep` (#5001), the weekly founder-CSV sweep, to `## Scheduled sweeps (external cron)` — verified against `apps/api/src/bin/listing-csv-sweep.ts` and `apps/api/package.json`.
+Prior: 2026-09-07 — doc-sync: added `listing-csv:sweep` (#5001), the weekly founder-CSV sweep, to `## Scheduled sweeps (external cron)` — verified against `apps/api/src/bin/listing-csv-sweep.ts` and `apps/api/package.json`.
 
 Prior: 2026-09-04 — doc-sync: added the `## Scheduled sweeps (external cron)` section documenting `abandon:sweep` and `followup:sweep` (#4732 AC-6) — verified against `apps/api/package.json` and `apps/api/src/bin/`.
 

package/templates/apps/api/package.json

@@ -46,7 +46,6 @@
     "@working-theory/observability": "workspace:*",
     "@working-theory/schema": "workspace:*",
     "@working-theory/site-config": "workspace:*",
-    "@working-theory/stripe-client": "workspace:*",
     "@working-theory/validation": "workspace:*",
     "dotenv": "^17.4.2",
     "fastify": "^5.12.1",