create-ailk 0.7.0 → 0.8.0

package/templates/.claude/skills/setup-deploy/references/runbook-template.md

@@ -1,12 +1,13 @@
 # `RUNBOOK.md` Template
 
 The `setup-deploy` skill emits this runbook at the consumer's
-project root. It documents pre-deploy steps, the **critical**
-leads-persistence caveat, and the three named upgrade paths.
+project root. It documents pre-deploy steps and where the site's
+leads go — the two lead destinations, **Email (default)** and
+**Lead inbox (setup-database)**.
 
-The skill must verify all three named persistence-section headings
-are present after emit (per SKILL.md Step 6 validation). If any is
-missing, the skill has a bug.
+The skill must verify both lead-destination headings are present
+after emit (per SKILL.md Step 6 validation). If either is missing,
+the skill has a bug.
 
 ## Template
 
@@ -35,109 +36,65 @@ Before you click Deploy in Vercel:
       set in Vercel before deploy.
 - [ ] **Configure your custom domain** if you have one (Vercel
       Project → Settings → Domains). Vercel handles TLS automatically.
-- [ ] **Pick a leads-persistence backend** — see the three named
-      upgrade paths below. **Do not deploy without picking one** if
-      your site captures leads. AILK's default `leads.jsonl`
-      fallback does not persist on Vercel's ephemeral filesystem.
+- [ ] **Pick where leads go** — see "Leads — where messages go"
+      below. With neither an email key nor a database, your contact
+      page shows your contact email instead of the form in
+      production, and no messages are collected.
+- [ ] **On a host other than Vercel**, set `NODE_ENV=production` on
+      the API process — that is how it knows it is in production.
 - [ ] **Register production OAuth callbacks** if you used
       `add-auth` and activated Google or GitHub. Each provider
       needs the prod callback URL added to its OAuth app settings.
 
 ---
 
-## Operations — leads.jsonl persistence
+## Leads — where messages go
 
-> **Critical:** AILK's default lead-capture writes to
-> `apps/api/leads.jsonl`. On Vercel's ephemeral filesystem, this
-> file **does not persist** across cold starts. Leads captured
-> during one container's lifetime are lost when that container
-> shuts down.
+Where a contact-form message goes depends only on what you set on
+the **API** project:
 
-You **must** pick a persistence backend before going live or you
-will lose leads. Pick one of the three sections below based on
-your situation:
+| You set                                   | A message…                                   |
+| ----------------------------------------- | -------------------------------------------- |
+| `DATABASE_URL`                            | lands in your lead inbox at `/leads`         |
+| the three email variables, no database    | is emailed to you                            |
+| neither (production)                      | is not collected — `/contact` shows your contact email instead of the form |
+| neither (`pnpm dev`)                      | is written to a local file, for testing      |
 
-- Cheapest fix, drop-in, native Vercel — **Vercel KV**
-- One provider for db + auth + storage — **Supabase**
-- Already have Postgres elsewhere — **Postgres via `@working-theory/database`**
+A newsletter signup needs the database: without one, `/newsletter`
+offers no signup form. A visitor is never told a message was sent
+when it reached nobody.
 
----
-
-## Persistence upgrade — Vercel KV
+### Email (default)
 
-**When to pick:** you want the cheapest fix, no new infra, and
-you're already on Vercel. Vercel KV is Redis-compatible key-value
-storage, native to the Vercel dashboard.
+**When to pick:** you want messages in your inbox with no database
+to run. This is the default for a new site.
 
 **Setup:**
 
-1. Vercel Dashboard → Storage → Create Database → KV.
-2. Connect to your project. Vercel auto-populates
-   `KV_REST_API_URL` and `KV_REST_API_TOKEN` in your project
-   environment.
-3. Pull updated env vars locally: `vercel env pull`.
-4. Switch the lead-capture writer in your code from JSONL to KV
-   (`@working-theory/api`'s lead-capture supports a KV adapter — see its
-   README for the wiring).
-5. Redeploy.
+1. Create an API key at <https://resend.com/api-keys> and verify the
+   domain you will send from (Resend Dashboard → Domains).
+2. On the **API** project in Vercel (Settings → Environment
+   Variables), set:
+   - `RESEND_API_KEY` — the key.
+   - `AILK_LEAD_NOTIFICATION_TO` — the address messages go to (yours).
+   - `AILK_LEAD_NOTIFICATION_FROM` — a sender on your verified domain.
+3. Redeploy the API.
 
-**Trade-offs:** KV is fast and easy but has limits (storage
-ceilings, access patterns). For >10K leads/month or rich querying,
-graduate to Supabase or Postgres.
-
----
+All three are required: a key without both addresses sends nothing.
+If Resend refuses a message, the visitor is told it could not be
+sent, so they can try again or email you directly.
 
-## Persistence upgrade — Supabase
-
-**When to pick:** you want one provider for database, auth, and
-storage. You're not committed to NextAuth (Supabase has its own
-auth), or you're fine running NextAuth + Supabase auth in parallel.
-
-**Setup:**
+### Lead inbox (setup-database)
 
-1. Sign up at <https://supabase.com>.
-2. Create a project.
-3. Go to Settings → API. Copy:
-   - `Project URL` → `NEXT_PUBLIC_SUPABASE_URL`
-   - `anon public` key → `NEXT_PUBLIC_SUPABASE_ANON_KEY`
-   - `service_role` key → `SUPABASE_SERVICE_ROLE_KEY` (server-only)
-4. Set those three env vars in Vercel project settings.
-5. Run the AILK Supabase migration (see `@working-theory/database` Supabase
-   adapter README — the migration creates a `leads` table with the
-   AILK schema).
-6. Switch the lead-capture writer to use the Supabase adapter.
-7. Redeploy.
-
-**Trade-offs:** Supabase is generous on free tier, scales well, and
-its dashboard is excellent. The auth coexistence with NextAuth is
-the only design wrinkle — most consumers either use NextAuth alone
-(treating Supabase as just a Postgres host) or commit to Supabase
-auth and remove NextAuth.
-
----
-
-## Persistence upgrade — Postgres via `@working-theory/database`
-
-**When to pick:** you already have Postgres somewhere — Neon,
-Railway, RDS, self-hosted, anywhere. You don't need a new provider
-relationship.
-
-**Setup:**
+**When to pick:** you want every message kept, searchable, in a
+lead inbox you review signed in — and newsletter signups collected.
 
-1. Get a Postgres connection string from your provider. Format:
-   `postgres://user:password@host:5432/dbname`.
-2. Set `DATABASE_URL` in Vercel project settings.
-3. Install `@working-theory/database`: `pnpm add @working-theory/database`.
-4. Run the migration:
-   `pnpm --filter @working-theory/database run migrate:deploy` (or your
-   provider's equivalent).
-5. The `@working-theory/database` package exposes a Prisma client tied to the
-   AILK schema; switch the lead-capture writer to use it.
-6. Redeploy.
-
-**Trade-offs:** most flexible, most setup. You manage the database
-yourself (backups, connection pooling, scaling). For consumers who
-already have Postgres in their stack, this is the natural fit.
+**Setup:** run the `setup-database` skill ("set up the database"). It
+walks you through provisioning Postgres, setting `DATABASE_URL`,
+running migrations, pinning you as the owner
+(`AILK_OPERATOR_EMAIL`), and sending one test message that must
+appear in `/leads` before it reports done. If the email variables
+are also set, you still get an email for each new lead.
 
 ---
 
@@ -204,9 +161,9 @@ You do **not** need to redeploy after:
 
 ## Troubleshooting
 
-- **"My leads disappeared"** → you skipped the leads-persistence
-  upgrade. Pick one of Vercel KV / Supabase / Postgres above and
-  migrate the writer.
+- **"My contact page shows an email address instead of the form"**
+  → the API has no lead destination. Set the three email variables,
+  or run `setup-database` (see "Leads — where messages go").
 - **"OAuth login redirects to localhost in production"** → you
   haven't added the production callback URL to the OAuth app
   (see above).
@@ -219,15 +176,14 @@ You do **not** need to redeploy after:
 
 ## Section headings the validation must find
 
-After emit, the skill must grep for these three headings (verbatim
-match). All three must be present:
+After emit, the skill must grep for these two headings (verbatim
+match). Both must be present:
 
-- `## Persistence upgrade — Vercel KV`
-- `## Persistence upgrade — Supabase`
-- `## Persistence upgrade — Postgres via `@working-theory/database\``
+- `### Email (default)`
+- `### Lead inbox (setup-database)`
 
-If any is missing, the template was edited in a way that broke the
-contract. Surface the failure to the consumer (not silent).
+If either is missing, the template was edited in a way that broke
+the contract. Surface the failure to the consumer (not silent).
 
 ## Merge logic
 
@@ -235,8 +191,8 @@ If the consumer already has `RUNBOOK.md`, the skill (per SKILL.md
 Step 3) offers merge / overwrite / skip. Merge logic:
 
 1. Read the existing file.
-2. Check whether each of the three named persistence section
-   headings is already present.
+2. Check whether the "Leads — where messages go" section and its two
+   lead-destination headings are already present.
 3. Headings already present → not modified.
 4. Headings missing → append at the end of the existing file under:
    ```

package/templates/DESIGN.md

@@ -160,3 +160,8 @@ The foundation's pinned direction is the pacing of a classic wireframe marketing
 - **Don't** add a colour accent. The foundation's one idea is black on white; a brand pass adds colour deliberately, through the theme.
 - **Don't** replace a black rule with a shadow or a grey fill.
 - **Don't** hard-code the "heading toward" values above into a page. They arrive through the platform, or not at all.
+
+## Revisions
+
+- **2026-09-24 — tile hover is outline-only (operator ruling, /build-starter live pass, #6687).** A comparison tile (`items` in `variant: tile`) hovers by shifting its border to the accent only — no lift, no glow — matching the Positionary `/alternatives` ruling of 2026-08-29. Expressed as the bounded `tileHover: "outline"` option (Card `wash-outline`); the library default `lift` is unchanged for every other site.
+- **2026-09-25 — the before-after section's rulings (operator, /build-starter live pass, #6687).** One layout, not two variants: a panel body is an image or rows of content under the same label bar. The label bar is the tone's fill (brand → black bar, white text) at the heading-4 role; a `neutral` panel keeps a white bar. The view selector is underline tabs with the underline under the current tab only (no full-width baseline), active black, inactive muted, black on hover. The pager is a ghost "‹ Previous" at the left edge and "Next ›" at the right edge. The catalyst column carries no icon tile — it starts at the arrow, or at an image when one is set. No back-to-all link and no tag chips on the seed pages.

package/templates/README.md

@@ -39,34 +39,36 @@ 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` |
+| `/use-cases`        | `content/en/UseCasesList/use-cases.mdx`             | `--shape organization-product` |
+| `/use-cases/[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` |
+| `/book-a-call`      | `content/en/BookCall/book-call.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                 |
+| `/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.
 
@@ -124,12 +126,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,12 +164,17 @@ 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:
+Today the key is used at scaffold time. Set `AILK_LICENSE_KEY` and scaffold with the shape you want — the key sets the level and switches on its modules:
 
 ```bash
-AILK_LICENSE_KEY=<your key> pnpm create ailk@latest <dir> --template <paid-template> --modules <modules>
+# 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 needs a paid key.
+
 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.
 
 ## Upgrading
@@ -186,14 +193,15 @@ 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`       | 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. 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/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/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 {