create-ailk 0.6.0 → 0.7.0

package/templates/DESIGN.md

@@ -0,0 +1,162 @@
+---
+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"
+  surface: "#ffffff"
+  surface-secondary: "#ffffff"
+  border: "#000000"
+  text-muted: "#333333"
+  brand: "#000000"
+  fg-on-brand: "#ffffff"
+  accent: "#000000"
+  bg-dark: "#000000"
+  fg-dark: "#ffffff"
+  border-dark: "#ffffff"
+  brand-dark: "#ffffff"
+typography:
+  display:
+    fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
+    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: "3rem"
+    fontWeight: 700
+    lineHeight: 1.1
+    letterSpacing: "normal"
+  heading-item:
+    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"
+    fontWeight: 400
+    lineHeight: 1.5
+  eyebrow:
+    fontSize: "0.875rem"
+    fontWeight: 600
+    lineHeight: 1.4
+    letterSpacing: "0.05em"
+rounded:
+  button: "0.5rem"
+  card: "0.75rem"
+spacing:
+  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 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.
+
+  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.
+-->
+
+# Standard
+
+## Overview
+
+The foundation reads like a well-made wireframe: nothing on the page but the words, black on white, with rules where other sites use shadows and colour. It is the look of a site whose owner has not chosen a brand yet and does not pretend otherwise — every placeholder reads as a placeholder, and the structure of the argument is what the visitor sees. A brand is applied on top of it; it is not one.
+
+Every page is composed from the AI Launch Kit component library (`@working-theory/ui`). Nothing is hand-built: a page is a list of registered sections, each with a bounded set of variants. Each section is one full-width band with a lot of air around it.
+
+## Colors
+
+### Primary
+
+**Black** (`brand` `#000000`) fills the primary button; its label is white. The secondary button is white with a black hairline and black label.
+
+### Neutral
+
+Pure white ground (`bg` `#ffffff`), pure black ink for headings (`fg` `#000000`), and near-black `#333333` for body copy — well above AA on white. **Borders are black** (`#000000`): card outlines, the rule under the navigation, the rules between sections and the rule above the footer are all 1px black lines. Cards are white, not tinted (`surface-secondary` is white too). There is no accent colour — `accent` is black.
+
+Dark mode inverts: black ground, white ink, white rules, white primary button with black label.
+
+### Named Rules
+
+- **Rules, not fills.** A container is drawn with a black hairline on the white ground. Grey fills are reserved for image placeholders.
+
+## Typography
+
+System sans throughout; no web font.
+
+### Hierarchy
+
+| 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 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
+
+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
+
+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.5rem corners. Secondary: transparent with a black 1px outline and black label. Both are the library `Button`.
+
+### Cards / Containers
+
+White panels with a black 1px outline, 0.75rem corners, `card` (1.5rem) padding. The one exception today: the "how it works" steps render as dark filled cards (see below).
+
+### Navigation
+
+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. The four traits this section used to list as blocked now ship as settings, so the rendered site matches the reference:
+
+| 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
+
+- **Do** keep every page built from registered sections. If a section you need does not exist, request it rather than writing one-off markup.
+- **Do** change colours in `content/_site.mdx` `theme.colors`; they reach every section.
+- **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.

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,77 +33,169 @@ pnpm preflight   # architecture + types + lint + build
 pnpm build       # production build
 ```
 
-> Requires Node.js 20+ and `pnpm`. No vendor API keys are required for first boot — Stripe, Anthropic, and email-provider integrations are opt-in.
+> 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 template, 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                   |
+
+<!-- generated:end -->
+
+A page marked `--template marketing-site-free` is in your site when you scaffolded with that template.
 
 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:
 
-Apply `myTheme` via the provider you use to wrap children. The full extension surface is documented at <https://ailaunchkit.ai/theme>.
+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.
+
+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/pro>. |
-| `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              |
 
-## AI assist (optional)
+<!-- generated:end -->
 
-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.
+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.
 
-## Deploy
+## 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:
 
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/{{COMPANY_NAME}}/{{PROJECT_NAME}})
+| 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`                                                                             |
 
-Or from the project root:
+### One command to get one
 
 ```bash
-pnpm vercel
+docker run --name ailk-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:17
 ```
 
-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.
+Point the app at it in `.env` (both variables, same URL for local work — the second is the direct connection `prisma migrate` uses):
 
-## Upgrading
+```bash
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
+DATABASE_URL_NON_POOLED=postgresql://postgres:postgres@localhost:5432/postgres
+```
 
-This site consumes versioned `@working-theory/*` packages from npm. To pull upstream changes:
+Then create the tables:
 
 ```bash
-pnpm update '@working-theory/*'
+pnpm db:migrate:deploy
 ```
 
-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.
+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.
+
+## Deploy
+
+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`.
+
+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.
+
+## Going Pro
+
+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:
+
+```bash
+AILK_LICENSE_KEY=<your key> pnpm create ailk@latest <dir> --template <paid-template> --modules <modules>
+```
+
+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 take a new release:
+
+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 -->
+
+| 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.                                          |
 
-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/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",

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

@@ -5,10 +5,11 @@ jest.mock('dotenv', () => ({
 
 // Mock the observability logger so assertions don't depend on pino's stdout serialization.
 const mockLoggerError = jest.fn();
+const mockLoggerWarn = jest.fn();
 jest.mock('@working-theory/observability', () => ({
   logger: {
     error: (...args: unknown[]) => mockLoggerError(...args),
-    warn: jest.fn(),
+    warn: (...args: unknown[]) => mockLoggerWarn(...args),
     info: jest.fn(),
     debug: jest.fn(),
   },
@@ -41,8 +42,9 @@ describe('Config', () => {
     expect(dotenv.config).toHaveBeenCalled();
   });
 
-  it('should exit on missing DATABASE_URL', () => {
+  it('should exit on missing DATABASE_URL in production', () => {
     // ARRANGE
+    process.env.NODE_ENV = 'production';
     delete process.env.DATABASE_URL;
 
     const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
@@ -61,6 +63,39 @@ describe('Config', () => {
     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.
+  it.each([
+    ['development', 'development'],
+    ['unset', undefined],
+    ['test', 'test'],
+  ])('should start database-less with DATABASE_URL unset when NODE_ENV is %s', (_label, nodeEnv) => {
+    // ARRANGE
+    if (nodeEnv === undefined) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = nodeEnv;
+    }
+    delete process.env.DATABASE_URL;
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {
+      throw new Error('Process exit called');
+    });
+
+    // ACT
+    const { config } = require('../index');
+
+    // ASSERT
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(config.DATABASE_URL).toBeUndefined();
+    expect(config.NODE_ENV).toBe(nodeEnv ?? 'development');
+    expect(mockLoggerError).not.toHaveBeenCalled();
+    expect(mockLoggerWarn).toHaveBeenCalledTimes(1);
+    expect(mockLoggerWarn.mock.calls[0]?.[1]).toContain('database_not_configured');
+
+    exitSpy.mockRestore();
+  });
+
   it('should not require any external-platform forwarding env vars', () => {
     // ARRANGE — only DATABASE_URL set; legacy forwarding vars explicitly absent
     process.env.DATABASE_URL = 'postgresql://test:test@localhost/test';

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

@@ -15,8 +15,9 @@ export interface Config {
   PORT: number;
   FRONTEND_URL: string;
 
-  // Local Database (for auth: User, Session, ApiToken, etc.)
-  DATABASE_URL: string;
+  // Local Database (for auth: User, Session, ApiToken, etc.). Required in
+  // production; unset elsewhere starts the API database-less (#6482).
+  DATABASE_URL?: string;
 
   // Stripe — consumed by apps/api/src/lib/stripe.ts via @working-theory/stripe-client wrapper
   STRIPE_SECRET_KEY?: string;
@@ -93,10 +94,20 @@ export interface Config {
 
 function validateConfig(): Config {
   const errors: string[] = [];
+  const nodeEnv = (process.env.NODE_ENV || 'development') as Config['NODE_ENV'];
 
-  // Required: Local database for auth
+  // 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).
   if (!process.env.DATABASE_URL) {
-    errors.push('DATABASE_URL is required for authentication');
+    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',
+      );
+    }
   }
 
   // Exit on errors
@@ -106,11 +117,13 @@ function validateConfig(): Config {
   }
 
   return {
-    NODE_ENV: (process.env.NODE_ENV || 'development') as Config['NODE_ENV'],
+    NODE_ENV: nodeEnv,
     PORT: parseInt(process.env.PORT || '3002', 10),
     FRONTEND_URL: process.env.FRONTEND_URL || 'http://localhost:3000',
 
-    DATABASE_URL: process.env.DATABASE_URL!,
+    ...(process.env.DATABASE_URL !== undefined && {
+      DATABASE_URL: process.env.DATABASE_URL,
+    }),
 
     ...(process.env.STRIPE_SECRET_KEY !== undefined && {
       STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,

package/templates/apps/api/src/lib/license-key-store.ts

@@ -0,0 +1,45 @@
+/**
+ * Registers the durable home of a renewed licence key (#6677 DD-6).
+ *
+ * `@working-theory/license` renews the deployment's key before it lapses and
+ * keeps the renewed key in a `LicenseKeyStore`. Its default store is a file,
+ * which a Vercel redeploy wipes — so a redeployed site would fall back to the
+ * older `AILK_LICENSE_KEY` and, past the renewal grace, to free. With a
+ * database configured, this registers the store backed by ONE deployment-wide
+ * `SiteSetting` row, `(DEFAULT_WORKSPACE_ID, "license.renewed_key")`, shared
+ * by this app, apps/mcp and apps/web.
+ *
+ * The row is deployment-wide, not tenant data: the licence is the
+ * deployment's, so it sits under the seeded default workspace in single- and
+ * multi-tenant builds alike (the named tenant-scope exclusion in
+ * architecture.yaml). A DB-less scaffold keeps the file store.
+ */
+
+import { DEFAULT_WORKSPACE_ID } from "@working-theory/database/tenancy";
+import {
+  createSiteSettingLicenseKeyStore,
+  setLicenseKeyStore,
+} from "@working-theory/license";
+import { logger } from "@working-theory/observability";
+
+import { prisma } from "./prisma.js";
+
+/**
+ * Register the SiteSetting-backed store when `DATABASE_URL` is set. An
+ * explicitly set `AILK_LICENSE_STORAGE_PATH` is the operator choosing the
+ * file store, and is honoured. Never throws: a failure logs and leaves the
+ * file store in place.
+ */
+export async function registerLicenseKeyStore(): Promise<void> {
+  if (!process.env.DATABASE_URL || process.env.AILK_LICENSE_STORAGE_PATH) return;
+  try {
+    setLicenseKeyStore(
+      createSiteSettingLicenseKeyStore(prisma.siteSetting, DEFAULT_WORKSPACE_ID),
+    );
+  } catch (err) {
+    logger.warn(
+      { errName: err instanceof Error ? err.name : "UnknownError" },
+      "[license] could not register the SiteSetting licence-key store — the file store stays in place",
+    );
+  }
+}

package/templates/apps/api/src/lib/site.ts

@@ -144,9 +144,11 @@ export async function resolveWorkspaceIdForAlias(
  *  1. **No `DATABASE_URL` configured** — the literal `requireDb()` guard
  *     `apps/api/src/services/flow-engine.ts` uses for the flow services:
  *     presence, not reachability. (`apps/api/src/config/index.ts`'s own
- *     eager `validateConfig()` already refuses a real `apps/api` boot with
- *     `DATABASE_URL` unset before `build()` is ever reached, so this arm is
- *     for any OTHER caller of `build()`.)
+ *     eager `validateConfig()` refuses a **production** `apps/api` boot with
+ *     `DATABASE_URL` unset before `build()` is ever reached; outside
+ *     production a real boot starts database-less (#6482), so this arm is
+ *     reachable from a real dev boot as well as from any other caller of
+ *     `build()`.)
  *  2. **`prisma.workspace.findUnique` is not even a function** — the case
  *     that surfaced this arm: `apps/api`'s shared/global prisma mocks
  *     (`lib/__mocks__/prisma-client.js`, the module-map-level double every