create-ailk 0.3.0 → 0.5.0

package/templates/.env.example

@@ -50,16 +50,41 @@ CONTENT_BACKEND=mdx
 # BETTER_AUTH_URL=http://localhost:3000
 # BETTER_AUTH_SECRET=
 
-# ── Single-tenant operator pin (multi-tenant module, apps/api) ───────────────
+# ── Single-tenant operator pin (apps/api) ────────────────────────────────────
+# REQUIRED on a build WITHOUT the multi-tenant module if you want the
+# submissions review dashboard. OPTIONAL with the module.
+#
 # On a single-tenant deployment (the default Workspace exists and is the ONLY
 # Workspace) the FIRST authenticated user to resolve a tenant context is
 # bound as the sole owner (TOFU — trust on first use); every subsequent
-# caller is denied. AILK_OPERATOR_EMAIL is OPTIONAL and pins that binding to
-# one email address instead of "whoever logs in first" — set it when you
-# want to guarantee only a specific operator account can ever become owner.
-# Case-insensitive, trimmed. Leave unset for pure TOFU.
+# caller is denied. AILK_OPERATOR_EMAIL pins that binding to one email
+# address instead of "whoever logs in first". Case-insensitive, trimmed.
+#
+# WITHOUT the multi-tenant module it is MANDATORY and unset fails CLOSED:
+# the review routes (/v1/waitlist-experiments/*, the tenant-scoped
+# /v1/project-listings/*) answer 403 to everyone, including you. That is
+# deliberate. Those routes can widen to an unfiltered, every-site read for an
+# owner of the default Organization, so an unpinned deployment must not seat
+# whoever authenticates first — on a site with public sign-ups that is not
+# necessarily you. The pinned account's email must also be VERIFIED.
+#
+# If your own dashboard returns 403, this variable is the first thing to
+# check. With the multi-tenant module present, resolution comes from the
+# session's active workspace and this stays optional, exactly as before.
 # AILK_OPERATOR_EMAIL=
 #
+# ── Site id (apps/api, apps/web) ─────────────────────────────────────────────
+# The scope captured rows are stamped with. Lead, WaitlistExperiment and
+# ProjectListing carry `siteId`, which defaults to the literal "default"
+# (apps/api/src/lib/site.ts), while tenancy scopes reads by WORKSPACE id.
+# A single-tenant deployment should set this to the default workspace
+# sentinel so the two agree:
+# AILK_SITE_ID=wksp_00000000-0000-7000-8000-000000000001
+#
+# Leaving them disagreeing is why a correctly pinned owner can still open the
+# review dashboard and see nothing: the rows exist, but under a different
+# scope key than the one their session resolves.
+#
 # Belt-and-suspenders: the owner-pin denies any non-operator account at
 # tenant resolution regardless, but for a single-tenant deployment you should
 # also disable open sign-up / configure an OAuth allowlist on your identity
@@ -291,9 +316,9 @@ CONTENT_BACKEND=mdx
 # SCHEDULING_PUBLIC_BASE_URL=https://cal.com
 # SCHEDULING_PROVIDER=cal
 #
-# Which event the /schedule page books, as "<owner>/<event-slug>" (the path of
+# Which event the /meet page books, as "<owner>/<event-slug>" (the path of
 # the provider's own public booking page). Read server-side by apps/web; unset
-# means the /schedule route 404s, exactly as if the scheduling module were not
+# means the /meet route 404s, exactly as if the scheduling module were not
 # installed. Deliberately NOT a NEXT_PUBLIC_ variable — the whole scheduling
 # config surface is server-read.
 # SCHEDULING_CAL_LINK=owner/event-slug

package/templates/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      # A fresh scaffold ships no pnpm-lock.yaml — it is generated by the
+      # customer's own first `pnpm install`. actions/setup-node's built-in
+      # pnpm cache globs for cache-dependency-path and errors the step
+      # outright when nothing matches, so a PR opened before that first
+      # install would fail here before `pnpm install` below even runs. This
+      # placeholder only stands in for the glob; `pnpm install` still
+      # generates (or refreshes) the real lockfile every run.
+      - run: test -f pnpm-lock.yaml || touch pnpm-lock.yaml
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      # Not --frozen-lockfile: the scaffold ships no pnpm-lock.yaml (it is
+      # generated fresh by the customer's own first `pnpm install`, and the
+      # placeholder step above is a cache-key stand-in, not a real lockfile),
+      # so a --frozen install would fail outright on any PR opened before a
+      # real lockfile has been committed.
+      - run: pnpm install
+
+      # Prisma's generated client (database/generated/) is a build artifact,
+      # not part of the scaffold — type-check/build/test all resolve
+      # `@working-theory/database`'s generated types, and `prisma generate` needs
+      # no DATABASE_URL (it reads only the schema file, no live DB).
+      - run: pnpm db:generate
+
+      - run: pnpm type-check
+
+      - run: pnpm lint
+
+      - run: pnpm test
+
+      - run: pnpm build

package/templates/README.md

@@ -103,7 +103,9 @@ If you need to override a section component, swap its registration in the sectio
 
 ## License & contributing
 
-Your project — `{{PROJECT_NAME}}`, owned by {{COMPANY_NAME}} ({{COMPANY_DOMAIN}}) — is yours. Pick whatever license suits you.
+This is your code — `{{PROJECT_NAME}}`, owned by {{COMPANY_NAME}} ({{COMPANY_DOMAIN}}). The root `package.json`'s `license` field ships set to `UNLICENSED` as a neutral placeholder; it's yours to change to whatever license suits your project (or to remove entirely if the repo is private).
+
+The `LICENSE` files under `apps/*/` and `database/` are the exception — they stay **Apache 2.0** because those directories are snapshots of `@working-theory/*` packages' own source, not code you authored.
 
 The AI Launch Kit framework upstream is **Apache 2.0** — see <https://github.com/working-theory-labs/ai-launch-kit/blob/main/LICENSE>. Contributions are welcome at the upstream repo; start with the [contributing guide](https://github.com/working-theory-labs/ai-launch-kit/blob/main/CONTRIBUTING.md).
 

package/templates/apps/api/CLAUDE.md

@@ -37,6 +37,7 @@ 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/leads` (GET, `?cursor=&limit=`) — the leads INBOX read (#5678): the caller's OWN sites' leads, newest first, cursor-paginated (`limit` defaults to 50, max 200; `(createdAt desc, id desc)`; `cursor` is the previous page's last row id, and one that does not resolve within the caller's scope is a 400, never a silent page 1 — the API keeps that contract, and the web inbox deliberately softens it on its own side by re-reading page one when a URL-supplied cursor 400s, which is a rendering choice and not a change to this response). Five fields per row and nothing more — `id`, `name` (lifted from `payload.name` when the site's form captured one), `email`, `source`, `createdAt`; `payload`'s other keys, `siteId`, `promotedUserId` and `promotedAt` are never selected (`src/services/leads-inbox.ts` is the only read path). Registered in `authScope` only (auth, no tenant guard) and — alone in that scope — **unconditionally**, with no `isModuleEnabled()` gate: lead capture is a never-gate surface at every level, so reading a lead back cannot be gated either. Identity is `request.userId`; there is no site, org or workspace parameter, so the scope cannot be widened from the wire. It is resolved from the caller's own memberships by `src/services/owner-workspaces.ts`'s `resolveOwnerWorkspaces` — the ONE site→workspace resolution in this app, shared with `lead-promotion.ts` rather than written a second time — and every read filters `siteId ∈ workspaceIds`. Role floor `owner|admin` (contact PII), the same floor and the same reason as `/v1/waitlist-experiments/*`; the scope is the UNION of every workspace the caller owns or administers, not one active tenant, because this route registers outside the tenant scope. **Two deployment preconditions decide whether it returns anything, and both fail EMPTY rather than wide:** a build with no `multi-tenant` module resolves no workspaces (a deliberate scope limit since #5677, not an absence of anything to resolve), and the `siteId` the leads were WRITTEN under must equal a workspace id. That `siteId` has TWO sources, and `currentSiteId()` is not the one on the primary path: the three POST capture routes read it from the REQUEST BODY (`routes/leads/index.ts`), which the capture sections declare in content and default to `"default"` (`ContactForm`/`Newsletter`/`StepFlow`, `ext.siteId ?? "default"`), while the recommender's capture path (`routes/flows/recommender.ts`) is the one that uses `currentSiteId()` (`lib/site.ts`, `AILK_SITE_ID ?? "default"`). A workspace id is `wksp_<uuidv7>`, so `siteId ∈ workspaceIds` matches only when the content-declared value — and, for recommender leads, `AILK_SITE_ID` — is set to it (the same convention `waitlist-dashboard.ts` already relies on). The rendered `name` is lifted from `payload.name` and truncated at 200 characters: the write side bounds `payload` at 64 keys and no per-value length, and `POST /v1/leads/submit` is anonymous with no ownership check on `siteId`. No MCP twin — identity-bound (#3591 exception, the same shape as `/v1/workspaces/*` and `/v1/billing/*`).
 - `/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`).
@@ -143,7 +144,9 @@ sweep's own DB constraint (never a caller-side lock).
 - 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.
+Last updated: 2026-09-16 — doc-sync: added `GET /v1/leads` (#5678), the owner-scoped leads inbox read, to Endpoint conventions, recording its unconditional registration, its five-field row, its `resolveOwnerWorkspaces` scoping and its no-MCP-twin parity decision — verified against `apps/api/src/routes/leads/list.ts`, `apps/api/src/services/leads-inbox.ts`, `apps/api/src/services/owner-workspaces.ts` and `apps/api/src/server.ts`.
+
+Prior: 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`.
 

package/templates/apps/api/eslint.config.mjs

@@ -0,0 +1,69 @@
+// Self-contained ESLint flat config for this scaffolded package.
+//
+// It deliberately does NOT depend on @working-theory/eslint-config — that
+// package is internal to the AI Launch Kit monorepo and is not published, so
+// it cannot be a dependency of a scaffolded starter. Everything below comes
+// from public npm packages already pinned as devDependencies (see
+// package.json): @eslint/js, globals and typescript-eslint.
+//
+// Source file name (#5556): this file is checked in as `_eslint.config.mjs`,
+// not `eslint.config.mjs` — build-templates.mjs renames it at snapshot time
+// (renameScaffoldLintConfigs()). A file literally named `eslint.config.mjs`
+// anywhere under this monorepo (even one this repo's own root eslint.config.ts
+// lists in its `ignores`) is auto-discovered by ESLint's flat-config nested
+// resolution as a competing config root, which breaks the monorepo's own
+// lint runs (verified live: typescript-eslint's "multiple candidate
+// TSConfigRootDirs" parser error across unrelated packages/create-ailk
+// files). The underscore prefix keeps it invisible to that discovery while
+// it lives in this checkout; only the snapshot in templates/ — which ships
+// to the customer, not this repo — gets the real filename.
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: [
+      "**/.next/**",
+      "**/dist/**",
+      "**/generated/**",
+      "**/node_modules/**",
+    ],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.browser,
+        ...globals.jest,
+      },
+      // Explicit, self-contained root — this scaffold config is never meant
+      // to combine with any sibling scaffold package's config (each ships
+      // standalone), and leaving it unset makes typescript-eslint's
+      // candidate-root disambiguation ambiguous the moment more than one
+      // scaffold package's config resolves in the same ESLint process (e.g.
+      // this monorepo's own `templates/` build, where all four exist
+      // side by side; a real customer scaffold never has that problem,
+      // since it only ever ships and lints ONE of these four at a time).
+      parserOptions: {
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    rules: {
+      // Downgraded rather than off, so both stay visible without failing a
+      // fresh scaffold's lint:
+      //   - unused-vars: most of the source follows the underscore-prefix
+      //     convention for intentionally-unused bindings, which this rule's
+      //     default options don't recognize; a handful of test fixtures also
+      //     carry genuinely-unused locals this minimal config doesn't try to
+      //     triage file-by-file.
+      //   - require-imports: CommonJS require() is the correct form in Jest
+      //     config/mock files and in a few test-only dynamic re-require
+      //     patterns.
+      "@typescript-eslint/no-unused-vars": "warn",
+      "@typescript-eslint/no-require-imports": "warn",
+    },
+  },
+);

package/templates/apps/api/package.json

@@ -20,7 +20,7 @@
     "smoke:dev": "node -e \"const{spawn}=require('child_process');const http=require('http');const PORT=process.env.PORT||'3002';const SLUG=process.env.SMOKE_FLOW_SLUG||'smoke-check';const child=spawn('pnpm',['exec','tsx','watch','src/cli.ts'],{env:process.env,stdio:'ignore'});let done=false;function finish(code){if(done)return;done=true;try{child.kill();}catch(e){}process.exit(code);}function poll(attempt){if(attempt>40){console.error('smoke:dev - timeout waiting for server');finish(1);return;}const req=http.get({host:'127.0.0.1',port:PORT,path:'/v1/flows/'+SLUG},(res)=>{console.log('smoke:dev - GET /v1/flows/'+SLUG+' -> HTTP '+res.statusCode);res.resume();finish(0);});req.on('error',()=>{setTimeout(()=>poll(attempt+1),500);});}child.on('exit',(code)=>{if(!done){console.error('smoke:dev - child exited early with code '+code);finish(1);}});setTimeout(()=>poll(0),500);\"",
     "smoke:build": "node -e \"const{spawn}=require('child_process');const http=require('http');const PORT=process.env.PORT||'3002';const SLUG=process.env.SMOKE_FLOW_SLUG||'smoke-check';const child=spawn('node',['dist/cli.js'],{env:process.env,stdio:'ignore'});let done=false;function finish(code){if(done)return;done=true;try{child.kill();}catch(e){}process.exit(code);}function poll(attempt){if(attempt>40){console.error('smoke:build - timeout waiting for server');finish(1);return;}const req=http.get({host:'127.0.0.1',port:PORT,path:'/v1/flows/'+SLUG},(res)=>{console.log('smoke:build - GET /v1/flows/'+SLUG+' -> HTTP '+res.statusCode);res.resume();finish(0);});req.on('error',()=>{setTimeout(()=>poll(attempt+1),500);});}child.on('exit',(code)=>{if(!done){console.error('smoke:build - child exited early with code '+code);finish(1);}});setTimeout(()=>poll(0),500);\"",
     "smoke": "pnpm run smoke:dev && pnpm run smoke:build",
-    "lint": "tsx ../../scripts/lint-package.ts",
+    "lint": "eslint .",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
@@ -64,6 +64,10 @@
     "prisma": "^7.8.0",
     "ts-jest": "^29.4.11",
     "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "eslint": "^10.6.0",
+    "@eslint/js": "^10.0.1",
+    "globals": "^17.7.0",
+    "typescript-eslint": "^8.62.1"
   }
 }

package/templates/apps/api/src/__tests__/module-exclusion.test.ts

@@ -59,11 +59,15 @@ async function withEnabledModules<T>(
 // caught by the "still registered" assertions below.
 const MODULE_ROUTES: Record<string, { method: 'GET' | 'POST'; url: string }[]> =
   {
+    // /v1/waitlist-experiments and /v1/project-listings are deliberately NOT
+    // listed here since #5677: the review surface registers under EITHER
+    // multi-tenant OR signal-collectors, so excluding multi-tenant alone
+    // leaves them registered by design — the same shape the workspace-settings
+    // routes have. Their matrix is `review-surface-registration.test.ts`,
+    // beside `workspace-module-registration.test.ts`.
     'multi-tenant': [
       { method: 'GET', url: '/v1/workspaces' },
       { method: 'GET', url: '/v1/billing' },
-      { method: 'GET', url: '/v1/waitlist-experiments' },
-      { method: 'GET', url: '/v1/project-listings' },
     ],
     scheduling: [{ method: 'GET', url: '/v1/schedule/availability' }],
     'content-write': [{ method: 'POST', url: '/v1/content/BlogPosting' }],

package/templates/apps/api/src/__tests__/review-surface-registration.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @file review-surface-registration.test.ts
+ * @description The `multi-tenant || signal-collectors` registration matrix for
+ * the review surface (#5677).
+ *
+ * This is the TWO-SIDED check the unit turns on. `signal-collectors` (Pro) is
+ * the module that sells the instruments — flows, deliverables, project
+ * listings, waitlist experiments — so a Pro customer could collect submissions
+ * and not read them, because the review routes registered only inside the
+ * multi-tenant scope. Widening the gate has to make the Pro side work WITHOUT
+ * moving the Pro Plus side, and only exercising both builds shows that.
+ *
+ * It cannot fold into `module-exclusion.test.ts`: that suite's shape is
+ * "excluding module X 404s every route X owns", and these routes register
+ * under EITHER module, so excluding one while the other is on leaves them
+ * registered by design — the same reason `workspace-module-registration.test.ts`
+ * is its own file, whose structure this mirrors.
+ *
+ * "Resolves" is measured as "not Fastify's own 404". An unauthenticated
+ * request to a registered tenant route answers 401, never 404, so the two
+ * states are unambiguous.
+ *
+ * Mirrors `src/__tests__/server.test.ts`'s external-boundary mocks (CORS,
+ * rate-limit, email) — see that file's header for why each is mocked.
+ */
+
+jest.mock('@fastify/cors', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@fastify/rate-limit', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@working-theory/email', () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+import { build } from '../server';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any avoids pulling in the full FastifyInstance type here
+type App = any;
+
+const EXPERIMENT = 'wlx_00000000-0000-7000-8000-0000000000aa';
+
+/** The review surface — registers under EITHER module since #5677. */
+const REVIEW_ROUTES = [
+  { method: 'GET' as const, url: '/v1/waitlist-experiments' },
+  { method: 'GET' as const, url: `/v1/waitlist-experiments/${EXPERIMENT}` },
+  {
+    method: 'GET' as const,
+    url: `/v1/waitlist-experiments/${EXPERIMENT}/signups`,
+  },
+  { method: 'GET' as const, url: '/v1/project-listings' },
+];
+
+/**
+ * Organization/Workspace ADMINISTRATION — deliberately left alone by #5677,
+ * because it is not a site's own submissions. These stay multi-tenant-only.
+ */
+const MULTI_TENANT_ONLY_ROUTES = [
+  { method: 'GET' as const, url: '/v1/workspaces' },
+  { method: 'GET' as const, url: '/v1/billing' },
+];
+
+async function withEnabledModules<T>(
+  enabled: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prior = process.env.AILK_ENABLED_MODULES;
+  process.env.AILK_ENABLED_MODULES = enabled;
+  try {
+    return await fn();
+  } finally {
+    if (prior === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = prior;
+    }
+  }
+}
+
+/** Every (method, path) pair Fastify's router holds, one per line. */
+function routeLines(app: App): string[] {
+  return (app.printRoutes({ commonPrefix: false }) as string)
+    .split('\n')
+    .map((line: string) => line.trim())
+    .filter(Boolean);
+}
+
+describe('review-surface registration matrix (#5677)', () => {
+  let app: App;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    delete process.env.AILK_ENABLED_MODULES;
+  });
+
+  it("with 'signal-collectors' alone (a Pro build), every review route resolves behind the base tenant guard", async () => {
+    app = await withEnabledModules('signal-collectors', () => build());
+
+    for (const { method, url } of REVIEW_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 401 });
+    }
+  });
+
+  it("with 'signal-collectors' alone, Organization/Workspace administration stays unregistered", async () => {
+    app = await withEnabledModules('signal-collectors', () => build());
+
+    for (const { method, url } of MULTI_TENANT_ONLY_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 404 });
+    }
+  });
+
+  it("with 'multi-tenant' alone (a Pro Plus build), every review route resolves exactly as before — the regression floor", async () => {
+    app = await withEnabledModules('multi-tenant', () => build());
+
+    for (const { method, url } of [
+      ...REVIEW_ROUTES,
+      ...MULTI_TENANT_ONLY_ROUTES,
+    ]) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).not.toEqual({ url, status: 404 });
+    }
+  });
+
+  it('with BOTH enabled, each review route registers exactly once', async () => {
+    // build() itself is the first assertion: Fastify throws
+    // FST_ERR_DUPLICATED_ROUTE at registration time, so a double-registration
+    // never reaches the router tree to be counted.
+    app = await withEnabledModules('multi-tenant,signal-collectors', () =>
+      build(),
+    );
+
+    const lines = routeLines(app);
+    const experimentRoutes = lines.filter((line) =>
+      line.includes('waitlist-experiments'),
+    );
+    expect(experimentRoutes.length).toBeGreaterThan(0);
+    expect(new Set(experimentRoutes).size).toBe(experimentRoutes.length);
+
+    for (const { method, url } of [
+      ...REVIEW_ROUTES,
+      ...MULTI_TENANT_ONLY_ROUTES,
+    ]) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).not.toEqual({ url, status: 404 });
+    }
+  });
+
+  it('with NEITHER enabled (a Free build), no review route registers — Free is unaffected', async () => {
+    app = await withEnabledModules('', () => build());
+
+    for (const { method, url } of [
+      ...REVIEW_ROUTES,
+      ...MULTI_TENANT_ONLY_ROUTES,
+    ]) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 404 });
+    }
+  });
+});

package/templates/apps/api/src/__tests__/workspace-module-registration.test.ts

@@ -0,0 +1,173 @@
+/**
+ * @file workspace-module-registration.test.ts
+ * @description The `workspace || multi-tenant` registration matrix (#5371 D2).
+ *
+ * `workspace` cannot be folded into the sibling `module-exclusion.test.ts`:
+ * that suite's shape is "excluding module X 404s every route X owns", and the
+ * three routes here register under EITHER module, so excluding `workspace`
+ * while `multi-tenant` is on leaves them registered by design. That is the
+ * whole point of D2's gate, so it gets its own matrix.
+ *
+ * The three cases §5.1 names:
+ *
+ *   1. workspace only      — the three workspace-settings routes resolve for a
+ *                            single-tenant session; billing / workspace-session
+ *                            / org routes stay unregistered.
+ *   2. multi-tenant only   — everything resolves exactly as it did before this
+ *                            change (the regression floor).
+ *   3. both enabled        — each of workspaceConfigRoutes /
+ *                            workspaceGeneralRoutes / workspaceMembersRoutes
+ *                            registers exactly ONCE; Fastify throws on a
+ *                            duplicate route at build() time, so a successful
+ *                            build IS the assertion, backed by an explicit
+ *                            count over the router tree.
+ *
+ * "Resolves" is measured as "not Fastify's own 404". An unauthenticated
+ * request to a registered tenant route answers 401, never 404, so the two
+ * states are unambiguous — the same signal `module-exclusion.test.ts` uses.
+ *
+ * Mirrors `src/__tests__/server.test.ts`'s external-boundary mocks (CORS,
+ * rate-limit, email) — see that file's header for why each is mocked.
+ */
+
+jest.mock('@fastify/cors', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@fastify/rate-limit', () => {
+  return jest.fn().mockResolvedValue(undefined);
+});
+
+jest.mock('@working-theory/email', () => ({
+  sendLeadNotification: jest.fn().mockResolvedValue({ ok: true }),
+}));
+
+import { build } from '../server';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- server is typed via Fastify generics; explicit any avoids pulling in the full FastifyInstance type here
+type App = any;
+
+const WS = 'wksp_00000000-0000-7000-8000-0000000000aa';
+
+/** The routes the widened gate must serve under EITHER module. */
+const SHARED_TENANT_ROUTES = [
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/theme` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/identity` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/seo` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/general` },
+  { method: 'GET' as const, url: `/v1/workspaces/${WS}/members` },
+];
+
+/**
+ * Routes that must NOT register under `workspace` alone — the gate's other
+ * half. `/v1/waitlist-experiments` is on this list because the review surface
+ * is gated on `multi-tenant || signal-collectors` (#5677), neither of which is
+ * enabled in this file's `workspace`-only cases; it is no longer
+ * multi-tenant-EXCLUSIVE, and its own matrix is
+ * `review-surface-registration.test.ts`.
+ */
+const MULTI_TENANT_ONLY_ROUTES = [
+  { method: 'GET' as const, url: '/v1/workspaces' },
+  { method: 'GET' as const, url: '/v1/billing' },
+  { method: 'GET' as const, url: '/v1/waitlist-experiments' },
+];
+
+async function withEnabledModules<T>(
+  enabled: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prior = process.env.AILK_ENABLED_MODULES;
+  process.env.AILK_ENABLED_MODULES = enabled;
+  try {
+    return await fn();
+  } finally {
+    if (prior === undefined) {
+      delete process.env.AILK_ENABLED_MODULES;
+    } else {
+      process.env.AILK_ENABLED_MODULES = prior;
+    }
+  }
+}
+
+/** Every (method, path) pair Fastify's router holds, one per line. */
+function routeLines(app: App): string[] {
+  return (app.printRoutes({ commonPrefix: false }) as string)
+    .split('\n')
+    .map((line: string) => line.trim())
+    .filter(Boolean);
+}
+
+describe('workspace-settings registration matrix (#5371 D2)', () => {
+  let app: App;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    delete process.env.AILK_ENABLED_MODULES;
+  });
+
+  it("with 'workspace' enabled and 'multi-tenant' disabled, the five settings routes resolve", async () => {
+    app = await withEnabledModules('workspace', () => build());
+
+    for (const { method, url } of SHARED_TENANT_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 401 });
+    }
+  });
+
+  it("with 'workspace' alone, billing / workspace-session / org routes stay unregistered", async () => {
+    app = await withEnabledModules('workspace', () => build());
+
+    for (const { method, url } of MULTI_TENANT_ONLY_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 404 });
+    }
+  });
+
+  it("with 'multi-tenant' enabled and 'workspace' disabled, every route resolves as before", async () => {
+    app = await withEnabledModules('multi-tenant', () => build());
+
+    for (const { method, url } of [
+      ...SHARED_TENANT_ROUTES,
+      ...MULTI_TENANT_ONLY_ROUTES,
+    ]) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).not.toEqual({ url, status: 404 });
+    }
+  });
+
+  it('with BOTH enabled, each shared route registers exactly once', async () => {
+    // build() itself is the first assertion: Fastify throws
+    // FST_ERR_DUPLICATED_ROUTE at registration time, so a double-registration
+    // never reaches the router tree to be counted.
+    app = await withEnabledModules('workspace,multi-tenant', () => build());
+
+    const lines = routeLines(app);
+    for (const segment of ['theme', 'identity', 'seo', 'general', 'members']) {
+      const matches = lines.filter((line) => line.includes(segment));
+      expect({ segment, count: matches.length }).toEqual({
+        segment,
+        count: 1,
+      });
+    }
+
+    for (const { method, url } of [
+      ...SHARED_TENANT_ROUTES,
+      ...MULTI_TENANT_ONLY_ROUTES,
+    ]) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).not.toEqual({ url, status: 404 });
+    }
+  });
+
+  it('with neither enabled, none of the five settings routes registers', async () => {
+    app = await withEnabledModules('', () => build());
+
+    for (const { method, url } of SHARED_TENANT_ROUTES) {
+      const res = await app.inject({ method, url });
+      expect({ url, status: res.statusCode }).toEqual({ url, status: 404 });
+    }
+  });
+});

package/templates/apps/api/src/config/modules.ts

@@ -9,7 +9,7 @@
  * means the same (the OSS-strip build target); a list enables exactly the
  * modules it names.
  *
- * Recognized module keys: `docs`, `multi-tenant`, `scheduling`,
+ * Recognized module keys: `docs`, `multi-tenant`, `workspace`, `scheduling`,
  * `signal-collectors`, `commerce` (the `ModuleName` vocabulary
  * `packages/create-ailk/src/module-architecture.ts` already models via
  * `MODULE_SLICES`) plus `content-write` — the Pro

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -114,6 +114,9 @@ export const prisma = {
     // `findUnique` — used by the deliverable-resend service (#3998) to
     // resolve a grant's stored lead email.
     findUnique: jest.fn(),
+    // `findFirst` — the leads-inbox cursor lookup (#5678), which resolves a
+    // supplied cursor WITHIN the caller's scope before paging from it.
+    findFirst: jest.fn(),
     findMany: jest.fn(),
     updateMany: jest.fn(),
   },