create-ailk 0.7.0 → 0.9.0

package/templates/README.md

@@ -29,7 +29,7 @@ Open <http://localhost:3000>. The home page renders from `content/en/HomePage/ho
 To verify everything is wired before committing or deploying:
 
 ```bash
-pnpm preflight   # architecture + types + lint + build
+pnpm preflight   # architecture + CLAUDE.md drift + types + lint + build
 pnpm build       # production build
 ```
 
@@ -39,38 +39,41 @@ pnpm build       # production build
 
 The `content/` directory is locale-prefixed: every page lives at `content/<locale>/<type>/<slug>.mdx`. The default locale is `en` (English); the scaffold ships English content only. Each subdirectory under `content/en/` is a schema-typed page surface, and the filename is the slug.
 
-The pages of the Free template, and where each one's copy lives:
+The pages of the Free `organization-product` shape, and where each one's copy lives:
 
 <!-- generated:begin content -->
 
-| Page                | Content file                                        | Ships in                         |
-| ------------------- | --------------------------------------------------- | -------------------------------- |
-| `/`                 | `content/en/HomePage/home.mdx`                      | every scaffold                   |
-| `/software`         | — (a code route)                                    | every scaffold                   |
-| `/software/[slug]`  | — (a code route)                                    | every scaffold                   |
-| `/use-cases`        | `content/en/UseCasesList/use-cases.mdx`             | `--template marketing-site-free` |
-| `/use-cases/[slug]` | — (a code route)                                    | `--template marketing-site-free` |
-| `/pricing`          | `content/en/Pricing/pricing.mdx`                    | `--template marketing-site-free` |
-| `/about`            | `content/en/AboutPage/about.mdx`                    | every scaffold                   |
-| `/faq`              | `content/en/FAQPage/faq.mdx`                        | every scaffold                   |
-| `/contact`          | `content/en/ContactPage/contact.mdx`                | every scaffold                   |
-| `/glossary`         | `content/en/GlossaryList/glossary.mdx`              | `--template marketing-site-free` |
-| `/newsletter`       | `content/en/NewsletterSignup/newsletter.mdx`        | `--template marketing-site-free` |
-| `/book-a-call`      | `content/en/BookCall/book-call.mdx`                 | `--template marketing-site-free` |
-| `/sign-in`          | — (a code route)                                    | every scaffold                   |
-| `/sign-up`          | — (a code route)                                    | every scaffold                   |
-| `/privacy`          | `content/en/PrivacyPage/privacy.mdx`                | `--template marketing-site-free` |
-| `/terms`            | `content/en/TermsPage/terms.mdx`                    | `--template marketing-site-free` |
-| `/purchase-policy`  | `content/en/PurchasePolicyPage/purchase-policy.mdx` | every scaffold                   |
-| `/blog`             | `content/en/BlogList/blog.mdx`                      | every scaffold                   |
+| Page                | Content file                                                                                                                                                        | Ships in                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| `/`                 | `content/en/HomePage/home.mdx`                                                                                                                                      | every scaffold                 |
+| `/features`         | `content/en/FeaturesList/features.mdx`                                                                                                                              | `--shape organization-product` |
+| `/features/[slug]`  | — (a code route)                                                                                                                                                    | `--shape organization-product` |
+| `/for`              | `content/en/UseCasesList/for.mdx`                                                                                                                                   | `--shape organization-product` |
+| `/for/[slug]`       | — (a code route)                                                                                                                                                    | `--shape organization-product` |
+| `/pricing`          | `content/en/Pricing/pricing.mdx`                                                                                                                                    | `--shape organization-product` |
+| `/about`            | `content/en/AboutPage/about.mdx`                                                                                                                                    | every scaffold                 |
+| `/faq`              | `content/en/FAQPage/faq.mdx`                                                                                                                                        | every scaffold                 |
+| `/contact`          | `content/en/ContactPage/contact.mdx`                                                                                                                                | every scaffold                 |
+| `/glossary`         | `content/en/GlossaryList/glossary.mdx`                                                                                                                              | `--shape organization-product` |
+| `/newsletter`       | `content/en/NewsletterSignup/newsletter.mdx`                                                                                                                        | `--shape organization-product` |
+| `/sign-in`          | — (a code route)                                                                                                                                                    | every scaffold                 |
+| `/sign-up`          | — (a code route)                                                                                                                                                    | every scaffold                 |
+| `/privacy`          | `content/en/PrivacyPage/privacy.mdx`                                                                                                                                | `--shape organization-product` |
+| `/terms`            | `content/en/TermsPage/terms.mdx`                                                                                                                                    | `--shape organization-product` |
+| `/purchase-policy`  | `content/en/PurchasePolicyPage/purchase-policy.mdx`                                                                                                                 | every scaffold                 |
+| `/blog`             | `content/en/BlogList/blog.mdx`                                                                                                                                      | every scaffold                 |
+| `/meet`             | `content/en/LandingPage/meet.mdx`                                                                                                                                   | every scaffold                 |
+| `/meet/[slug]`      | `content/en/BookCall/book-a-call.mdx`, `content/en/BookCall/onsite-estimate.mdx`, `content/en/BookCall/start-project.mdx`, `content/en/BookCall/onsite-service.mdx` | every scaffold                 |
+| `/portfolio`        | `content/en/PortfolioList/portfolio.mdx`                                                                                                                            | `--shape organization-product` |
+| `/portfolio/[slug]` | — (a code route)                                                                                                                                                    | `--shape organization-product` |
 
 <!-- generated:end -->
 
-A page marked `--template marketing-site-free` is in your site when you scaffolded with that template.
+A page marked `--shape organization-product` is in your site when you scaffolded that shape, or an alias of it such as `--template marketing-site-free`. Another shape has its own page set; your site's roster of record is `.ailk-site-manifest.json` at its root.
 
 To customize the home page, edit [`content/en/HomePage/home.mdx`](./content/en/HomePage/home.mdx). Save and reload the dev server. No build step.
 
-To add a new page, ask Claude Code to run the `add-page` skill — it writes the route, the MDX content stub and the page's typed JSON-LD in one confirm-before-write pass. See [Skills](#skills).
+To add a new page, ask Claude Code to run the `add-page` skill — it writes the page's content file and nav link in one confirm-before-write pass, and adds a missing route with `create-ailk add-route` first. See [Skills](#skills).
 
 > `content/_site.mdx` stays at the top level (not under `content/en/`) — site identity is locale-blind.
 
@@ -82,13 +85,17 @@ Everything that makes this site yours lives in three places. Nothing in `apps/*`
 | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
 | Site name, canonical URL, default locale                     | `content/_site.mdx` — `siteName`, `baseUrl`, `defaultLocale`                                                            |
 | Who the site is (the entity answer engines read)             | `content/_site.mdx` — `siteIdentity` (`kind`, `name`, `url`, `logo`, `description`, `sameAs`)                           |
-| Colours, light and dark                                      | `content/_site.mdx` — `theme.colors.light` / `theme.colors.dark` (`bg`, `text`, `primary`, `accent`, …)                 |
+| Your brand colours, light and dark                           | `content/_site.mdx` — `brand.colors.light` / `brand.colors.dark` (`primary`, `primaryFg`, `accent`)                     |
+| Your fonts                                                   | `content/_site.mdx` — `brand.fonts` (`display`, `body`)                                                                 |
+| The design's own colours                                     | `content/_site.mdx` — `theme.colors.light` / `theme.colors.dark` (`bg`, `text`, `primary`, `accent`, …)                 |
 | Corners, section-label case, image placeholders, check marks | `content/_site.mdx` — `theme.corners`, `theme.eyebrowCase`, `theme.placeholders`, `theme.checkmarks`                    |
 | Every page's copy and section order                          | `content/en/<Type>/<slug>.mdx` — the frontmatter `sections[]`; each section's `data` is its copy and its layout options |
 | Header links, footer columns, social links                   | `apps/web/lib/nav-config.ts` — generated at scaffold, yours to edit; labels come from `apps/web/messages/<locale>.json` |
 | Logo and brand assets                                        | `apps/web/public/` and the `logo` field in `siteIdentity`                                                               |
 
-The `theme` block is the whole design surface. Declare only what you change — an absent colour role or shape knob keeps the platform default — and the build turns it into the CSS custom properties every component reads. There is no token file to fork and no provider to wrap. The [theme and brand guide](https://ailaunchkit.ai/docs/guides/customize-theme-and-brand) is where the full walkthrough will live.
+Two blocks carry the look. `theme:` is the design's — its colours and shape knobs; `brand:` is yours — the logomark, `brand.colors` and `brand.fonts`, set on top of whatever design the site wears. Declare only what you change — an absent colour role or shape knob keeps the default — and the build turns both into the CSS custom properties every component reads. There is no token file to fork and no provider to wrap.
+
+To change the whole look, apply another design: `pnpm create ailk@latest apply-design <name|path>` in the site root, with a shipped design name (`standard`, `minimalism`) or a folder holding a `DESIGN.md`. It rewrites `theme:`, the generated `apps/web/lib/site-chrome.ts` and the look fields of your sections; it never touches your routes, your copy or the `brand:` block. That is why your own colours belong in `brand.colors`, not `theme.colors`: applying a design replaces `theme:` wholesale. A design other than `standard` needs a Pro or Pro Plus key. The [theme and brand guide](https://ailaunchkit.ai/docs/guides/customize-theme-and-brand) is where the full walkthrough will live.
 
 A rebrand touches only the files in this table. If you find yourself editing a component, stop: the trait you want is either a section option (check the section's `data` fields), a theme knob, or a feature request for the [upstream library](https://github.com/working-theory-labs/ai-launch-kit).
 
@@ -124,12 +131,12 @@ Set `AILK_PUBLIC_DOMAIN` to your own domain. `STEALTH=true` keeps a fresh deploy
 
 You need Postgres once you turn on one of these:
 
-| Surface                                                        | What it stores                                                                                                                                  |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Auth** — `/sign-in`, `/sign-up`, `/account`                  | users, sessions, accounts                                                                                                                       |
-| **Lead inbox** — `/leads`                                      | submitted leads, for you to review signed in. Lead capture itself always appends to a local JSONL file (`LEAD_CAPTURE_FILE`) and needs nothing. |
-| **Checkout returns** — `/purchase/success`, `/purchase/cancel` | the paid checkouts the Stripe webhook records. These pages serve only on a site licensed for commerce.                                          |
-| **`CONTENT_ADAPTER=database`**                                 | pages authored in the Artifact store rather than in `content/*.mdx`                                                                             |
+| Surface                                                        | What it stores                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Auth** — `/sign-in`, `/sign-up`, `/account`                  | users, sessions, accounts                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **Lead inbox** — `/leads`                                      | submitted leads, for you to review signed in, and newsletter signups. Without a database, lead capture emails each contact-form message to you instead (`RESEND_API_KEY` + `AILK_LEAD_NOTIFICATION_TO` + `AILK_LEAD_NOTIFICATION_FROM` on the API); with neither in production, `/contact` shows your `_site.mdx` `contactEmail` instead of the form. The `setup-database` skill walks you from no database to a working inbox. |
+| **Checkout returns** — `/purchase/success`, `/purchase/cancel` | the paid checkouts the Stripe webhook records. These pages serve only on a site licensed for commerce.                                                                                                                                                                                                                                                                                                                          |
+| **`CONTENT_ADAPTER=database`**                                 | pages authored in the Artifact store rather than in `content/*.mdx`                                                                                                                                                                                                                                                                                                                                                             |
 
 ### One command to get one
 
@@ -162,13 +169,24 @@ The [deploy guide](https://ailaunchkit.ai/docs/guides/deploy-to-production) is w
 
 Paid levels and the commerce add-on are bought at <https://ailaunchkit.ai/pricing>; your licence key arrives by email.
 
-Today the key is used at scaffold time. Set `AILK_LICENSE_KEY` and scaffold the paid template with the modules it needs:
+For a new site, set `AILK_LICENSE_KEY` and scaffold with the shape you want — the key sets the level and switches on its modules:
+
+```bash
+# Free — no key
+pnpm create ailk@latest <dir> --shape <shape>
+# Paid — the key sets the level and switches on its modules
+AILK_LICENSE_KEY=<your key> pnpm create ailk@latest <dir> --shape <shape>
+```
+
+`<shape>` is one of `organization-product`, `organization-service`, `local-business-service`, `person-service`. `--modules` trims the level's modules, or adds the commerce add-on or the workspace module. `--design minimalism` picks the other look, and `--design <folder>` renders the starter in a design of your own (a folder holding a `DESIGN.md`); either needs a paid key.
+
+To add a paid module to this site in place, set the key and run `add-module` in the site root:
 
 ```bash
-AILK_LICENSE_KEY=<your key> pnpm create ailk@latest <dir> --template <paid-template> --modules <modules>
+AILK_LICENSE_KEY=<your key> pnpm create ailk@latest add-module <module>
 ```
 
-Applying a paid module to an existing site in place is not yet supported. To move this site onto a paid template, scaffold the new one and bring your `content/` directory and `content/_site.mdx` across.
+It writes the module's files the site lacks and never overwrites one you have: a file whose content differs is left as-is and listed for review. It patches only `package.json` dependency and script keys, `next.config.*` and `jest.config.*`, then regenerates `architecture.yaml`. `pnpm create ailk@latest license set <key>` (or `license set -` to read the key from stdin, out of your shell history) keeps the key with the site — in `ailk.key` and `apps/api/.env`, both gitignored — and, when the site is linked to Vercel, sets it there and redeploys.
 
 ## Upgrading
 
@@ -186,14 +204,16 @@ This project ships Claude Code skills in `.claude/skills/`. Claude Code discover
 
 <!-- generated:begin skills -->
 
-| Skill          | What it does                                                                                                                                                                                                                          |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `add-page`     | Generate a new page: App Router route + MDX content stub + typed JSON-LD, in one confirm-before-write pass. Also documents the `schema:` frontmatter override for adding supplementary structured data to a page that already exists. |
-| `add-auth`     | Activate auth providers — magic-link via Resend, Google OAuth, GitHub OAuth.                                                                                                                                                          |
-| `setup-deploy` | Emit deploy configuration — `vercel.json`, `.env.example`, and `RUNBOOK.md` — for a Vercel deploy.                                                                                                                                    |
-| `check-site`   | Run `ailk-audit --json` and explain the score and findings in plain language.                                                                                                                                                         |
-| `fill-page`    | Fill one page's section content from a category profile: labelled sample content (tier 1) or your own first draft from a short intake (tier 2).                                                                                       |
-| `upgrade-plan` | Compare Free, Pro, Pro Plus, Agency and the commerce add-on side by side, with the prices the public pricing page publishes right now, and recommend one option for this site with a reason.                                          |
+| Skill            | What it does                                                                                                                                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `add-page`       | Add a page this site can serve — its content file, structured data and nav link — adding a missing route with `create-ailk add-route` first. Also documents the `schema:` frontmatter override for any page.                       |
+| `update-page`    | Rename a page — give it a new URL and/or a new title — in one plan-then-confirm pass: its content files, its own route folder, exact internal links and the manifest row move together, and the old URL gets a permanent redirect. |
+| `add-auth`       | Activate auth providers — magic-link via Resend, Google OAuth, GitHub OAuth.                                                                                                                                                       |
+| `setup-deploy`   | Emit deploy configuration — `vercel.json`, `.env.example`, and `RUNBOOK.md` — for a Vercel deploy. Asks where leads go (email or a database) and warns when neither is set.                                                        |
+| `setup-database` | Take the site from no database to a working lead inbox: provision Postgres, create the tables, pin the owner, and verify one test message lands in `/leads`.                                                                       |
+| `check-site`     | Run `ailk-audit --json` and explain the score and findings in plain language.                                                                                                                                                      |
+| `fill-page`      | Fill one page's section content from a category profile: labelled sample content (tier 1) or your own first draft from a short intake (tier 2).                                                                                    |
+| `upgrade-plan`   | Compare Free, Pro, Pro Plus, Agency and the commerce add-on side by side, with the prices the public pricing page publishes right now, and recommend one option for this site with a reason.                                       |
 
 <!-- generated:end -->
 

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

@@ -36,7 +36,8 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 # =============================================================================
 # When set, POST /v1/checkout/sessions requires the X-Internal-Auth header
 # to match this value. Unset for OSS standalone deployments (no gate applied).
-# Must match OSS_API_INTERNAL_SECRET in apps-paid/marketing-api/.env.local.
+# Must match OSS_API_INTERNAL_SECRET in apps-paid/marketing-api/.env.local
+# and in apps/web's environment (the /dev/purchase Server Action, #6876).
 # Generate with: openssl rand -hex 32
 # OSS_API_INTERNAL_SECRET=your-shared-secret-here
 

package/templates/apps/api/CLAUDE.md

@@ -36,8 +36,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/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/leads/{submit,subscribe,callback}` — lead capture, newsletter subscription, callback request. Where a lead goes is `src/lib/lead-delivery.ts` (#6730): `DATABASE_URL` set → the database (the inbox); no database but `RESEND_API_KEY` + `AILK_LEAD_NOTIFICATION_TO` + `AILK_LEAD_NOTIFICATION_FROM` → the owner email IS the delivery (`persisted: "email"`, a refused send is `503 delivery_failed`); neither outside production → the local file fallback; neither in production → `503 lead_capture_not_configured` before any write. A newsletter signup needs a database (or the local file). A lead is never reported captured when nothing stored or delivered it.
+- `/v1/leads/capture` (GET) — `{ ok: true, data: { contact, newsletter } }`, two booleans saying whether a submit / a subscribe would be accepted (#6730). The web contact page reads it to show the form or the site's contact email. Never names the delivery mode, an address or an env var. Registered at the top level, outside `leadsScope`'s strict per-IP limit. No MCP twin — a recorded exception on the same footing as the anonymous form-lifecycle routes: an agent needs no preflight, because the three lead-write tools already return the 503 when capture is not accepted.
+- `/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:** on a build with no `multi-tenant` module `resolveOwnerWorkspaces` resolves none (a deliberate scope limit since #5677), so there the scope is the default workspace, granted only through `services/default-tenant.ts`'s `resolveDefaultTenantForOperator` — `AILK_OPERATOR_EMAIL` set, the caller's verified email equal to it, a one-workspace deployment, role `owner|admin` — and every other caller gets the empty page (#6730); 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`). **Three grant classes since #6310**, keyed on `grant.assetId`'s ADR-0031 prefix: `playbook:` (unchanged, the FEAT-074 U4b virtual asset); `asset_` — a workspace `Asset`, resolved through the named boundary `src/lib/deliverable-asset-store.ts`, scoped by `grant.workspaceId` (a serve-time tenancy re-check restored for this class — D15) — served `attachment` with an extension pinned to the stored content type, `nosniff`, a non-raster `Content-Security-Policy` (for EVERY content type, including raster — never `inline`), and `Cache-Control: private, no-store` so a deleted asset stops downloading immediately; `dasset_` — the LEGACY `DeliverableAsset` store (unchanged, tried only when a magnet's `assetKey` does not resolve against `Asset`). Every miss on the `asset_` class — a NULL `workspaceId`, no row, a foreign-workspace row — folds into the SAME uniform 404 as every other class; there is deliberately no redirect to the public `GET /v1/assets/:assetId` (that route's year-long `immutable` cache would defeat deletion as a revocation lever, and would collapse every lead's capability onto one workspace-canonical id — spec #6310 §9 SEC-001/SEC-002).

package/templates/apps/api/src/__tests__/commerce-claim-registration.test.ts

@@ -78,6 +78,8 @@ jest.mock('@working-theory/stripe-client', () => ({
   StripeConfigError: class StripeConfigError extends Error {},
   UnknownProductCodeError: class UnknownProductCodeError extends Error {},
   UnknownSessionError: class UnknownSessionError extends Error {},
+  // #6866 — sessions.ts tests `instanceof UnknownCustomerError`.
+  UnknownCustomerError: class UnknownCustomerError extends Error {},
   WEBHOOK_TOLERANCE_SECONDS: 300,
 }));
 

package/templates/apps/api/src/__tests__/server.test.ts

@@ -469,3 +469,119 @@ describe("#6216 D11 — a lead_… path segment is truncated to 8 characters, cs
     }
   });
 });
+
+// ── #6889 — production startup warns when a checkout protection is unset ─────
+//
+// POST /v1/checkout/sessions admits a caller without X-Internal-Auth when
+// OSS_API_INTERNAL_SECRET is unset, and with FRONTEND_URL unset its redirect
+// lock answers 500 while the CORS/cookie origin checks pin to localhost. Both
+// are optional by design (OSS standalone compat), so startup must never fail
+// on them — but a production boot says so, once per variable. Each case rebuilds the module graph because `config/index.ts`
+// snapshots NODE_ENV at import time.
+
+describe("#6889 — production startup warns on an unset FRONTEND_URL or OSS_API_INTERNAL_SECRET", () => {
+  const ENV_KEYS = [
+    "NODE_ENV",
+    "FRONTEND_URL",
+    "OSS_API_INTERNAL_SECRET",
+    // Cleared so a production boot never trips config's database-module exit.
+    "AILK_ENABLED_MODULES",
+  ] as const;
+  type EnvKey = (typeof ENV_KEYS)[number];
+  const priorEnv = new Map<string, string | undefined>(
+    ENV_KEYS.map((key) => [key, process.env[key]]),
+  );
+  // 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
+  let app: any;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+    for (const [key, value] of priorEnv) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    jest.restoreAllMocks();
+  });
+
+  /** Boot a fresh module graph under `env` and return every warning message. */
+  async function bootWarnings(
+    env: Partial<Record<EnvKey, string>>,
+  ): Promise<string[]> {
+    for (const key of ENV_KEYS) {
+      const value = env[key];
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+    jest.resetModules();
+    const { logger } =
+      require("@working-theory/observability") as typeof import("@working-theory/observability");
+    const warn = jest.spyOn(logger, "warn");
+    const { build: freshBuild } =
+      require("../server") as typeof import("../server");
+    app = await freshBuild();
+    return warn.mock.calls.map((args) =>
+      args
+        .map((arg) => (typeof arg === "string" ? arg : JSON.stringify(arg)))
+        .join(" "),
+    );
+  }
+
+  const naming = (messages: string[], name: string) =>
+    messages.filter((message) => message.includes(name));
+
+  it("warns exactly once naming FRONTEND_URL when it is unset in production", async () => {
+    const messages = await bootWarnings({
+      NODE_ENV: "production",
+      OSS_API_INTERNAL_SECRET: "internal-secret",
+    });
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(1);
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(0);
+  });
+
+  it("warns exactly once naming OSS_API_INTERNAL_SECRET when it is unset in production", async () => {
+    const messages = await bootWarnings({
+      NODE_ENV: "production",
+      FRONTEND_URL: "https://site.example.com",
+    });
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(1);
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(0);
+  });
+
+  it("warns once for each when both are unset in production, and still starts", async () => {
+    const messages = await bootWarnings({ NODE_ENV: "production" });
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(1);
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(1);
+    const health = await app.inject({ method: "GET", url: "/health" });
+    expect(health.statusCode).toBe(200);
+  });
+
+  it("logs no warning for either when both are set in production", async () => {
+    const messages = await bootWarnings({
+      NODE_ENV: "production",
+      FRONTEND_URL: "https://site.example.com",
+      OSS_API_INTERNAL_SECRET: "internal-secret",
+    });
+    expect(naming(messages, "FRONTEND_URL")).toHaveLength(0);
+    expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(0);
+  });
+
+  it.each(["development", "test"])(
+    "logs no warning for either outside production (NODE_ENV=%s), both unset",
+    async (nodeEnv) => {
+      const messages = await bootWarnings({ NODE_ENV: nodeEnv });
+      expect(naming(messages, "FRONTEND_URL")).toHaveLength(0);
+      expect(naming(messages, "OSS_API_INTERNAL_SECRET")).toHaveLength(0);
+      const health = await app.inject({ method: "GET", url: "/health" });
+      expect(health.statusCode).toBe(200);
+    },
+  );
+});

package/templates/apps/api/src/config/__tests__/index.test.ts

@@ -42,31 +42,49 @@ describe('Config', () => {
     expect(dotenv.config).toHaveBeenCalled();
   });
 
-  it('should exit on missing DATABASE_URL in production', () => {
-    // ARRANGE
+  // #6730 security review (M1): a production build whose enabled modules keep
+  // their state in the database still refuses to boot without DATABASE_URL —
+  // a missing database there is a broken deploy (e.g. a commerce licence read
+  // as absent would ack-and-drop signed Stripe events), not a Free site.
+  it.each(['commerce', 'content-write', 'multi-tenant', 'scheduling', 'signal-collectors', 'workspace'])(
+    'should exit on missing DATABASE_URL in production when the %s module is enabled',
+    (moduleName) => {
+      process.env.NODE_ENV = 'production';
+      process.env.AILK_ENABLED_MODULES = `marketing,${moduleName}`;
+      delete process.env.DATABASE_URL;
+      const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+        throw new Error('Process exit called');
+      });
+
+      expect(() => require('../index')).toThrow('Process exit called');
+      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(mockLoggerError).toHaveBeenCalled();
+
+      exitSpy.mockRestore();
+    },
+  );
+
+  it('should start database-less in production with only non-database modules enabled', () => {
     process.env.NODE_ENV = 'production';
+    process.env.AILK_ENABLED_MODULES = 'marketing,docs-blog';
     delete process.env.DATABASE_URL;
-
     const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
       throw new Error('Process exit called');
     });
-    mockLoggerError.mockClear();
 
-    // ACT & ASSERT
-    expect(() => {
-      require('../index');
-    }).toThrow('Process exit called');
-
-    expect(exitSpy).toHaveBeenCalledWith(1);
-    expect(mockLoggerError).toHaveBeenCalled();
+    const { config } = require('../index');
 
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(config.DATABASE_URL).toBeUndefined();
     exitSpy.mockRestore();
   });
 
-  // #6482 — outside production a missing DATABASE_URL starts the API
-  // database-less (one warning) instead of exiting, so a fresh scaffold's
-  // `pnpm dev` keeps its "no database needed" promise.
+  // #6482 — a missing DATABASE_URL starts the API database-less (one
+  // warning) instead of exiting, so a fresh scaffold's `pnpm dev` keeps its
+  // "no database needed" promise. #6730 (operator decision (a)) extends that
+  // to production: a Free site delivers leads by email with no Postgres.
   it.each([
+    ['production', 'production'],
     ['development', 'development'],
     ['unset', undefined],
     ['test', 'test'],
@@ -130,3 +148,86 @@ describe('Config', () => {
     expect(config.FRONTEND_URL).toBe('http://localhost:3000');
   });
 });
+
+// #6730 (operator decision (a)) — the REAL server boots in production with
+// no database: an email-only Free site must be able to run its API, answer
+// `GET /v1/leads/capture`, and refuse authenticated routes with a 503 rather
+// than exit at startup.
+describe('production boot without a database (#6730)', () => {
+  const originalEnv = process.env;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the Fastify instance comes from an isolated require; its generics add nothing here
+  let app: any;
+
+  const EMAIL_ENV = {
+    RESEND_API_KEY: 're_test',
+    AILK_LEAD_NOTIFICATION_TO: 'owner@example.com',
+    AILK_LEAD_NOTIFICATION_FROM: 'noreply@example.com',
+  };
+
+  // External boundaries only, as src/__tests__/server.test.ts mocks them.
+  beforeAll(() => {
+    jest.doMock('@fastify/cors', () => jest.fn().mockResolvedValue(undefined));
+    jest.doMock('@fastify/rate-limit', () => jest.fn().mockResolvedValue(undefined));
+    jest.doMock('@working-theory/email', () => ({
+      sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: 'm' }),
+      sendRequestConfirmEmail: jest.fn(),
+      sendRequestPaidLinkEmail: jest.fn(),
+    }));
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+    app = undefined;
+    process.env = originalEnv;
+  });
+
+  async function bootProduction(extra: Record<string, string> = {}) {
+    jest.resetModules();
+    const env: NodeJS.ProcessEnv = { ...originalEnv, NODE_ENV: 'production', ...extra };
+    delete env.DATABASE_URL;
+    delete env.DATABASE_URL_NON_POOLED;
+    delete env.RESEND_API_KEY;
+    delete env.AILK_LEAD_NOTIFICATION_TO;
+    delete env.AILK_LEAD_NOTIFICATION_FROM;
+    Object.assign(env, extra);
+    process.env = env;
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+    try {
+      const { build } = require('../../server');
+      app = await build();
+    } finally {
+      expect(exitSpy).not.toHaveBeenCalled();
+      exitSpy.mockRestore();
+    }
+    return app;
+  }
+
+  it('with only the email vars, starts and reports contact accepted, newsletter not', async () => {
+    const server = await bootProduction(EMAIL_ENV);
+
+    const res = await server.inject({ method: 'GET', url: '/v1/leads/capture' });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, data: { contact: true, newsletter: false } });
+  });
+
+  it('with nothing configured, starts and reports nothing accepted', async () => {
+    const server = await bootProduction();
+
+    const res = await server.inject({ method: 'GET', url: '/v1/leads/capture' });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ ok: true, data: { contact: false, newsletter: false } });
+  });
+
+  it('refuses an authenticated route with 503 database_not_configured', async () => {
+    const server = await bootProduction(EMAIL_ENV);
+
+    const res = await server.inject({ method: 'GET', url: '/v1/leads' });
+
+    expect(res.statusCode).toBe(503);
+    expect(res.json()).toEqual({ error: 'database_not_configured' });
+  });
+});

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

@@ -7,6 +7,8 @@
 import { logger } from '@working-theory/observability';
 import * as dotenv from 'dotenv';
 
+import { isModuleEnabled } from './modules.js';
+
 dotenv.config();
 
 export interface Config {
@@ -92,28 +94,45 @@ export interface Config {
   CAL_WEBHOOK_SECRET?: string;
 }
 
+/** Enabled modules whose state lives in the database (see validateConfig). */
+const DATABASE_MODULES = [
+  'commerce',
+  'content-write',
+  'multi-tenant',
+  'scheduling',
+  'signal-collectors',
+  'workspace',
+] as const;
+
 function validateConfig(): Config {
-  const errors: string[] = [];
   const nodeEnv = (process.env.NODE_ENV || 'development') as Config['NODE_ENV'];
 
-  // Local database for auth: required in production. Elsewhere a fresh
-  // scaffold runs with no .env, so start database-less and let the auth
-  // preHandler answer 503 database_not_configured (#6482).
+  // No database is a supported shape in every environment, production
+  // included (#6730 operator decision (a)): a Free site delivers leads by
+  // email and needs no Postgres. Start database-less and let the auth
+  // preHandler answer 503 database_not_configured (#6482) — it reads
+  // DATABASE_URL per request, whatever NODE_ENV says, so no authenticated
+  // route runs without a database.
+  //
+  // Except a production build whose ENABLED modules keep their state in the
+  // database. There a missing DATABASE_URL is a broken deploy, not a Free
+  // site: e.g. a commerce site's licence lives in the database-backed store,
+  // so booting without it would read the site as unlicensed and ack-and-drop
+  // every signed Stripe event (#6730 security review, M1). Those builds keep
+  // the loud startup failure.
   if (!process.env.DATABASE_URL) {
-    if (nodeEnv === 'production') {
-      errors.push('DATABASE_URL is required for authentication');
-    } else {
-      logger.warn(
-        { nodeEnv },
-        '⚠️ DATABASE_URL not set — starting database-less; authenticated routes answer 503 database_not_configured',
+    const needsDatabase = DATABASE_MODULES.filter((m) => isModuleEnabled(m));
+    if (nodeEnv === 'production' && needsDatabase.length > 0) {
+      logger.error(
+        { modules: needsDatabase },
+        '❌ DATABASE_URL is required in production when these modules are enabled',
       );
+      process.exit(1);
     }
-  }
-
-  // Exit on errors
-  if (errors.length > 0) {
-    logger.error({ errors }, '❌ Configuration validation failed');
-    process.exit(1);
+    logger.warn(
+      { nodeEnv },
+      '⚠️ DATABASE_URL not set — starting database-less; authenticated routes answer 503 database_not_configured',
+    );
   }
 
   return {