create-ailk 0.6.1 → 0.8.0

package/templates/DESIGN.md

@@ -1,6 +1,6 @@
 ---
-name: AI Launch Kit base scaffold
-description: The foundation every AI Launch Kit site starts from — pure white, black ink, black hairline rules, system type, generous pacing.
+name: Standard
+description: The standard design — the black-on-white foundation any shape wears by default: full navigation, a multi-column footer, the document-scroll home.
 colors:
   bg: "#ffffff"
   fg: "#000000"
@@ -18,20 +18,21 @@ colors:
 typography:
   display:
     fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
-    fontSize: "6rem"
-    fontWeight: 400
-    lineHeight: 1
-    letterSpacing: "-0.05em"
+    fontSize: "3.5rem"
+    fontWeight: 700
+    lineHeight: 1.1
+    letterSpacing: "normal"
   heading-section:
     fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
-    fontSize: "2.25rem"
-    fontWeight: 400
-    lineHeight: 1.25
-    letterSpacing: "-0.05em"
+    fontSize: "3rem"
+    fontWeight: 700
+    lineHeight: 1.1
+    letterSpacing: "normal"
   heading-item:
-    fontSize: "1.25rem"
-    fontWeight: 600
+    fontSize: "2rem"
+    fontWeight: 700
     lineHeight: 1.375
+    letterSpacing: "normal"
   body:
     fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
     fontSize: "1.125rem"
@@ -43,33 +44,37 @@ typography:
     lineHeight: 1.4
     letterSpacing: "0.05em"
 rounded:
-  button: "0.25rem"
+  button: "0.5rem"
   card: "0.75rem"
 spacing:
-  section: "4rem"
+  section: "7rem"
+  section-mobile: "4rem"
   card: "1.5rem"
   grid: "1.5rem"
   container: "1280px"
+  measure: "36rem"
 ---
 
 <!--
   Source template: _base (the AI Launch Kit base scaffold)
+  Design: standard
   Version: create-ailk {{CREATE_AILK_VERSION}}
 
-  This file describes the visual system this scaffold ships with. The impeccable
-  design skill reads it at the start of every design session, so an agent
-  building a new page stays on-system.
+  This is the `standard` design's DESIGN.md. Its one authored source is
+  create-ailk's site-templates/designs/standard/DESIGN.md; every template on
+  this design ships a copy of it that differs only in the "Source template"
+  line above, and a template installed with `--template <name>` replaces the
+  base scaffold's DESIGN.md with its own. The impeccable design skill reads
+  it at the start of every design session, so an agent building a new page
+  stays on-system.
+  Edit the canonical file, never a copy — a test holds every copy to it.
 
-  A site template (installed with `--template <name>`) replaces this file with
-  its own DESIGN.md — same path, with a header naming the template it came
-  from. Edit whichever one your site has; the header tells you which.
-
-  The tokens above describe what the scaffold RENDERS today. Colours come from
+  The tokens above describe what the site RENDERS today. Colours come from
   content/_site.mdx (`theme.colors`); type, radius and spacing are platform
   defaults a site cannot override yet — see "Where this is heading" below.
 -->
 
-# AI Launch Kit base scaffold
+# Standard
 
 ## Overview
 
@@ -99,31 +104,31 @@ System sans throughout; no web font.
 
 ### Hierarchy
 
-| Role            | Size     | Weight | Notes                                                                       |
-| --------------- | -------- | ------ | --------------------------------------------------------------------------- |
-| Hero headline   | 6rem     | 400    | Tracking -0.05em, line-height 1                                             |
-| Section heading | 2.25rem  | 400    | Tracking -0.05em — light and tight, not bold                                |
-| Item heading    | 1.25rem  | 600    | Card, feature and step titles                                               |
-| Body            | 1.125rem | 400    | `#333333`, line-height 1.5                                                  |
-| Section label   | 0.875rem | 600    | Uppercase, +0.05em tracking today — the small label above a section heading |
+| Role            | Size     | Weight | Notes                                                                                 |
+| --------------- | -------- | ------ | ------------------------------------------------------------------------------------- |
+| Hero headline   | 3.5rem   | 700    | Normal tracking, line-height 1.1; 2.5rem below 1024px                                 |
+| Section heading | 3rem     | 700    | Normal tracking, line-height 1.1; 2.25rem below 1024px, always under the hero         |
+| Item heading    | 2rem     | 700    | Card, feature and step titles; 1.5rem below 1024px                                    |
+| Body            | 1.125rem | 400    | `#333333`, line-height 1.5; section copy capped at 36rem (about 70 characters a line) |
+| Section label   | 0.875rem | 600    | Uppercase, +0.05em tracking today — the small label above a section heading           |
 
-Measured from the rendered scaffold (1440px wide), not transcribed from tokens.
+Measured from the rendered scaffold (1440px and 390px wide), not transcribed from tokens. Bold headings at normal tracking follow the foundation's pinned direction (#6493).
 
 The small label above a section heading is **kept** as part of this foundation's voice (operator-disposed 2026-09-22) and is headed toward the treatment below.
 
 ## Layout
 
-Content sits in a 1280px container. Sections stack at the platform's 4rem rhythm today; a few sections choose a compact (2.5rem) or spacious (6rem) step internally. Card grids gap at 1.5rem. Breakpoints: 320 / 768 / 1024 / 1440.
+Full navigation; a multi-column footer; the default home. The home-only announcement banner is off by default (`layout.announcementBanner`). Every page this site carries is listed in its roster of record, `.ailk-site-manifest.json` at the site root. Shared foundation: a 1280px container, sections at 7rem (4rem below 1024px), card grids at 1.5rem, breakpoints 320 / 768 / 1024 / 1440.
 
 ## Shapes
 
-Two radii today: buttons at 0.25rem, cards and outlined boxes at 0.75rem. Headed toward square corners — see below.
+Square corners everywhere (`theme.corners: square`) — buttons, cards, the auth card, image placeholders; the tokens above are the base foundation's defaults a site overrides.
 
 ## Components
 
 ### Buttons
 
-Primary: black fill, white label, 0.25rem corners. Secondary: transparent with a black 1px outline and black label. Both are the library `Button`.
+Primary: black fill, white label, 0.5rem corners. Secondary: transparent with a black 1px outline and black label. Both are the library `Button`.
 
 ### Cards / Containers
 
@@ -131,20 +136,22 @@ White panels with a black 1px outline, 0.75rem corners, `card` (1.5rem) padding.
 
 ### Navigation
 
-Wordmark or logo left, page links, then an outlined and a filled button at the far right. A black hairline separates it from the page. An optional announcement banner sits above it.
+Full navigation: wordmark left, page links, an outlined and a filled button at the far right. A black hairline separates it from the page. Page links are 16px at weight 400. The two buttons are 42px tall on a 44px touch target and keep the 0.5rem button radius; square corners arrive with the platform radius change below, not in the nav alone (#6508). The Product link opens, on hover or keyboard, a 640px two-column panel whose items each show an icon, a title and a one-line description.
 
 ## Where this is heading
 
-The foundation's pinned direction is the pacing of a classic wireframe marketing kit — `standardissue.webflow.io` is the reference for rhythm, type scale, spacing density and section pacing only; no image, copy or code is taken from it. Six parts of that direction cannot be expressed through a site's theme today, so they wait on a platform change rather than being hand-coded. Until they land, this file describes the rendered site above, not these targets.
+The foundation's pinned direction is the pacing of a classic wireframe marketing kit — `standardissue.webflow.io` is the reference for rhythm, type scale, spacing density and section pacing only; no image, copy or code is taken from it. The four traits this section used to list as blocked now ship as settings, so the rendered site matches the reference:
 
-| Target                                            | Reference value                                                                                                                  | Blocked by                                                                                               |
-| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Square corners on buttons, cards and inputs       | radius 0                                                                                                                         | A site's `theme:` block accepts colours only — no radius                                                 |
-| Bold, tighter headings                            | hero ~3.6rem and section headings ~2.9rem, both at weight 700 with tracking about -0.02em (today 6rem and 2.25rem at weight 400) | No per-site type-role override                                                                           |
-| Generous section pacing                           | about 10rem between sections, not 4rem                                                                                           | No per-site section-spacing override; `spacious` (6rem) is not author-selectable                         |
-| Section label in sentence case, bold, no tracking | "Core Features", not "CORE FEATURES"                                                                                             | The eyebrow role bakes in uppercase and tracking                                                         |
-| Whitespace between sections, not rules            | no rule between bands                                                                                                            | Section dividers share the one `border` colour with card outlines, so black outlines make black dividers |
-| Outlined steps in "how it works"                  | three plain outlined columns                                                                                                     | The steps section renders dark filled cards; no outlined variant                                         |
+| Trait                                                  | How it is set                                                                                     |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| Square corners on buttons, cards and inputs            | `theme.corners: square` in `_site.mdx`                                                            |
+| Section label in sentence case, bold, no tracking      | `theme.eyebrowCase: sentence`                                                                     |
+| Solid grey image placeholders, no outline              | `theme.placeholders: fill`                                                                        |
+| Bare check and cross marks, no circle badge            | `theme.checkmarks: plain`                                                                         |
+| Plain, uncarded feature and step items                 | per section: `itemStyle: plain`, and `variant: steps` for an image beside a numbered list         |
+| A left hero whose headline wraps at half the container | `measure: narrow` on the hero (pricing); `gapBelow: tight` where a list follows the hero directly |
+| A three-up post grid on the blog index                 | `blog-list` `variant: grid` (cover · date · read time · title · excerpt · Read more)              |
+| A plans section that leads its page                    | drop the hero; the pricing section owns the `<h1>` (`ownsPageTitle`)                              |
 
 ## Do's and Don'ts
 
@@ -153,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

@@ -7,11 +7,15 @@
     {{PROJECT_NAME}}    — the directory name you scaffolded into
     {{COMPANY_NAME}}    — the legal/marketing name of the entity behind the site
     {{COMPANY_DOMAIN}}  — the canonical domain for the site (e.g. acme.example)
+
+  The tables between `generated:begin` and `generated:end` markers were
+  generated when this scaffold was published. They are yours to edit like the
+  rest of this file.
 -->
 
 # {{PROJECT_NAME}}
 
-Built with [AI Launch Kit](https://ailaunchkit.ai). AI Launch Kit (AILK) is an agent-first OSS template — every page emits clean schema.org JSON-LD, every server action has a matching MCP tool, and every install is one command. This site is yours; you can edit it like any other repo.
+Built with [AI Launch Kit](https://ailaunchkit.ai). AI Launch Kit (AILK) is an agent-first site template — every page emits clean schema.org JSON-LD, the site carries a free MCP tool surface (`apps/mcp`) that agents can call, and every install is one command. This site is yours; you can edit it like any other repo.
 
 ## Run
 
@@ -20,7 +24,7 @@ pnpm install
 pnpm dev
 ```
 
-Open <http://localhost:3000>. The home page renders from `content/en/HomePage/home.mdx` with valid JSON-LD already in the `<head>`.
+Open <http://localhost:3000>. The home page renders from `content/en/HomePage/home.mdx` with valid JSON-LD already in the `<head>`. New here? Start with the [Get started guide](https://ailaunchkit.ai/docs/introduction/get-started).
 
 To verify everything is wired before committing or deploying:
 
@@ -29,62 +33,105 @@ pnpm preflight   # architecture + types + lint + build
 pnpm build       # production build
 ```
 
-> Requires Node.js 20+ and `pnpm` — that is the whole prerequisite list. No database is needed to run or build this site (see [When you need a database](#when-you-need-a-database)), and no vendor API keys are required for first boot — Stripe, Anthropic, and email-provider integrations are opt-in. `pnpm install` generates the Prisma client for you; there is no generator step to remember.
+> Requires Node.js 20+ and `pnpm` — that is the whole prerequisite list. No database is needed to run or build this site (see [When you need a database](#when-you-need-a-database)), and no vendor API keys are required for first boot — Stripe, auth and email-provider integrations are opt-in. `pnpm install` generates the Prisma client for you; there is no generator step to remember.
 
 ## Content
 
-The `content/` directory is locale-prefixed: every page lives at `content/<locale>/<type>/<slug>.mdx`. The default locale is `en` (English); the AILK scaffold ships English content only. Each subdirectory under `content/en/` is a schema-typed page surface — HomePage, AboutPage, ContactPage, FAQPage, Products, Services, Projects, BlogList, BlogPosting, and friends. The filename is the slug.
+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 `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                 |
+| `/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 `--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, copy an existing MDX file in the matching directory and edit the frontmatter (`type`, `slug`, `title`, `description`).
+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).
 
 > `content/_site.mdx` stays at the top level (not under `content/en/`) — site identity is locale-blind.
 
-## Theme
+## Make it your own
 
-Design tokens live in [`packages/theme`](https://www.npmjs.com/package/@working-theory/theme) (consumed from npm; no source edits needed). Components in [`packages/ui`](https://www.npmjs.com/package/@working-theory/ui) read from those tokens.
+Everything that makes this site yours lives in three places. Nothing in `apps/*` or `packages/*` needs to change to rebrand, re-theme or rewrite the site.
 
-To swap the brand color, override the `theme.brand` token at the consumer site by extending the theme in your root layout. Example:
+| To change…                                                   | Edit                                                                                                                    |
+| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| 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`, …)                 |
+| 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`                                                               |
 
-```ts
-// app/layout.tsx (sketch)
-import { theme } from "@working-theory/theme";
+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.
 
-const myTheme = {
-  ...theme,
-  brand: { ...theme.brand, primary: "#0a84ff" },
-};
-```
+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).
+
+## Removing a page
+
+Every page is one MDX file plus, sometimes, one nav entry:
+
+1. Delete `content/en/<Type>/<slug>.mdx`.
+2. Remove its entry from `apps/web/lib/nav-config.ts` (header items and footer columns).
+3. Run `pnpm build`. A route directory under `apps/web/app/[locale]/` whose content is gone renders its empty state; delete the directory too if you want the URL to 404.
 
-Apply `myTheme` via the provider you use to wrap children. The full extension surface is documented at <https://ailaunchkit.ai/theme>.
+Modules (`docs`, `multi-tenant`, `scheduling`, …) are chosen at scaffold time with `--modules`. To drop one, scaffold again without it; there is no in-place module remover.
 
 ## Environment
 
-Copy `.env.example` to `.env` and fill in only what you need. Most variables are optional. A complete reference:
+Copy `.env.example` to `.env`. It sets these variables:
 
-| Variable                           | Purpose                                                                                                                       |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `AILK_LICENSE_KEY`                 | Optional. JWT issued by ailaunchkit.ai; verified locally to unlock Pro features. Get one at <https://ailaunchkit.ai/pricing>. |
-| `NEXT_PUBLIC_STREAMING_AI_ENABLED` | Optional. Set to `true` to enable the opt-in streaming AI assist UI. Off by default.                                          |
-| `ANTHROPIC_API_KEY`                | Required only when `NEXT_PUBLIC_STREAMING_AI_ENABLED=true`. Used by the AI assist surface only.                               |
-| `AILK_LOCAL_LEAD_CAPTURE`          | Optional. When `true`, leads from the contact form are written to a local file instead of an API.                             |
-| `AILK_LEADS_API_URL`               | Optional. Override the upstream that receives lead-capture submissions.                                                       |
+<!-- generated:begin environment -->
 
-See [`.env.example`](./.env.example) for the full template with comments. Per-app overrides (e.g. `apps/api/.env`) are honored alongside the root `.env`.
+| Variable             | Ships set to     | Section of `.env.example`    |
+| -------------------- | ---------------- | ---------------------------- |
+| `AILK_PUBLIC_DOMAIN` | `ailaunchkit.ai` | Marketing / canonical domain |
+| `STEALTH`            | `true`           | Launch posture               |
+| `CONTENT_ADAPTER`    | `mdx`            | Content adapter              |
+
+<!-- generated:end -->
+
+Set `AILK_PUBLIC_DOMAIN` to your own domain. `STEALTH=true` keeps a fresh deploy out of search indexes and link unfurls — set it to `false` when you are ready to launch. Every other variable in `.env.example` ships commented out: each is opt-in and documented in place, next to the feature that reads it. Per-app templates (`apps/web/.env.example`, `apps/api/.env.example`, `apps/mcp/.env.example`) sit alongside their apps.
 
 ## When you need a database
 
 **A free marketing site needs no database at all.** `pnpm install`, `pnpm dev` and `pnpm build` all run green on an empty machine with no Postgres, no `DATABASE_URL` and no `.env` — the pages render from `content/*.mdx`, and the Prisma client is generated for you by `database`'s `postinstall` so the workspace type-checks and builds either way.
 
-You need Postgres once you turn on one of these four:
+You need Postgres once you turn on one of these:
 
-| Surface                                | What it stores                                                                                                    |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| **Auth** (sign-in, sessions, accounts) | users, sessions, accounts                                                                                         |
-| **Flows** — `/save` and `/checkout`    | a visitor's in-progress flow state, so they can resume or pay later                                               |
-| **Lead capture in DB mode**            | submitted leads. The default file mode (`AILK_LOCAL_LEAD_CAPTURE=true`) writes to disk instead and needs nothing. |
-| **`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
 
@@ -107,33 +154,56 @@ pnpm db:migrate:deploy
 
 That is the whole setup. `pnpm db:studio` opens a browser UI over the data, and `pnpm db:seed` loads the sample rows. Turning the database off again is just unsetting the two variables — the marketing pages never read it.
 
-## AI assist (optional)
+## Deploy
 
-The site ships with an opt-in streaming AI assist. It is **off by default**. To turn it on, set `NEXT_PUBLIC_STREAMING_AI_ENABLED=true` in `.env` and provide an `ANTHROPIC_API_KEY`. The assist runs server-side so the API key never reaches the browser. With both unset, the chat UI is hidden and no AI traffic flows.
+Ask Claude Code to run the `setup-deploy` skill. It writes a Vercel deploy configuration at the project root — `vercel.json`, an `.env.example` covering the variables production needs, and a `RUNBOOK.md` with the steps — and asks before overwriting any file you already have. Vercel is the one platform it supports today. `apps/api` already ships its own `vercel.json`.
 
-## Deploy
+The [deploy guide](https://ailaunchkit.ai/docs/guides/deploy-to-production) is where the full production walkthrough will live; until it is published, the skill's `RUNBOOK.md` is the checklist. Remember to set `STEALTH=false` on the hosting platform when you launch.
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/{{COMPANY_NAME}}/{{PROJECT_NAME}})
+## Going Pro
 
-Or from the project root:
+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 with the shape you want — the key sets the level and switches on its modules:
 
 ```bash
-pnpm vercel
+# 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>
 ```
 
-The `vercel.json` files inside `apps/web` and `apps/api` configure each surface as an independent Vercel project. Connect both, set the env vars listed above, and ship.
+`<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
 
-This site consumes versioned `@working-theory/*` packages from npm. To pull upstream changes:
+This site consumes versioned `@working-theory/*` packages from npm. To take a new release:
 
-```bash
-pnpm update '@working-theory/*'
-```
+1. Edit the `@working-theory/*` version ranges in the `package.json` files that list them to the release you want.
+2. Run `pnpm install`.
+3. Run `pnpm create ailk@latest sync-routes` in the site root. It reports the route directories the template gained since you scaffolded; add `--apply` to copy them in. A route you have changed is never overwritten, and nothing is deleted.
+
+Change the ranges by hand. Below 1.0 a caret range (`^0.26.0`) never crosses a minor version, so updating within the ranges you already have silently stays on the old release. There is no `git pull upstream`, no fork-and-merge. Breaking changes are announced in each package's `CHANGELOG.md` in the [upstream repo](https://github.com/working-theory-labs/ai-launch-kit).
+
+## Skills
+
+This project ships Claude Code skills in `.claude/skills/`. Claude Code discovers them at session start — ask for one by name.
+
+<!-- generated:begin skills -->
 
-That's the entire upgrade flow. There is no `git pull upstream`, no codemod, no fork-and-merge. Breaking changes ship in major-version bumps of the relevant `@working-theory/*` package; release notes call them out explicitly.
+| 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.                                          |
 
-If you need to override a section component, swap its registration in the section registry (see <https://ailaunchkit.ai/sections>). Framework code stays out of your tree.
+<!-- generated:end -->
 
 ## License & contributing
 

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

@@ -17,9 +17,10 @@ PORT=3002
 FRONTEND_URL=http://localhost:3000
 
 # =============================================================================
-# Local Database (REQUIRED)
+# Local Database (required in production)
 # =============================================================================
 # For auth only: User, Session, ApiToken, etc.
+# Unset outside production, the API starts and authed routes answer 503.
 DATABASE_URL="postgresql://user:password@localhost:5432/customer_template"
 
 # =============================================================================

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/package.json

@@ -6,7 +6,7 @@
   "license": "Apache-2.0",
   "type": "module",
   "scripts": {
-    "dev": "tsx watch src/cli.ts",
+    "dev": "tsx watch --exclude \"../../node_modules/**\" src/cli.ts",
     "abandon:sweep": "tsx src/bin/abandon-sweep.ts",
     "followup:sweep": "tsx src/bin/followup-sweep.ts",
     "listing-csv:sweep": "tsx src/bin/listing-csv-sweep.ts",