create-ailk 0.8.0 → 0.9.0

package/templates/.claude/skills/upgrade-plan/SKILL.md

@@ -88,12 +88,15 @@ Answer in this order, in plain words:
    second recommendation; you may say what would change it (for example "if
    you add multi-tenant later, that moves you to Pro Plus").
 4. **What happens next.** Link `recommendation.link`. After purchase the
-   licence key arrives by email; set it as `AILK_LICENSE_KEY` in your
-   environment. To install the module(s): run
-   `pnpm dlx create-ailk@latest --help`, and name `add-module` only if that
-   output lists it. Otherwise say: re-run `create-ailk` with
-   `--modules <module>` and the key set, into a new directory, and move your
-   content across.
+   licence key arrives by email. To install a paid module into this site
+   in place, run `AILK_LICENSE_KEY=<key> pnpm create ailk@latest
+   add-module <module>` in the site root, once per module; it leaves
+   every file the site already has as-is except `package.json`
+   dependency/script keys, `next.config.*` and `jest.config.*`, which it
+   patches. `pnpm create ailk@latest license set -` (key on stdin) keeps
+   the key with the site (and, on a site linked to Vercel, sets it there
+   and redeploys). A different design is
+   `pnpm create ailk@latest apply-design <name|path>`.
 
 ## Hard rules
 
@@ -108,8 +111,9 @@ Answer in this order, in plain words:
 - **Unpublished means no prices.** When `pricing.status` is `unpublished`,
   say the pricing page does not publish machine-readable prices yet and link
   https://ailaunchkit.ai/pricing.
-- **Read-only.** Write no file and install nothing. The only outside command
-  besides the helper is the `--help` probe in step 3.
+- **Read-only.** Write no file and install nothing. The helper is the only
+  command you run; `add-module`, `license set` and `apply-design` are named
+  for the owner to run, never run by you.
 - **Never print the licence key.** Report only whether it is set.
 
 ## References

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

@@ -48,6 +48,10 @@ jobs:
       # locally.
       - run: pnpm architecture
 
+      # A hand-edit inside a template-owned section of CLAUDE.md — the same
+      # check `pnpm preflight` runs locally.
+      - run: pnpm claude-md:check
+
       - run: pnpm test
 
       - run: pnpm build

package/templates/.prettierignore

@@ -0,0 +1 @@
+CLAUDE.md

package/templates/CLAUDE.md

@@ -1,22 +1,35 @@
+<!-- ailk:template id="intro" -->
+
 # {{PROJECT_NAME}} — Agent Operating Manual
 
 You are Claude, working in the `{{PROJECT_NAME}}` repo. Read this file at session start.
 
+Sections between `ailk:template` markers come from AI Launch Kit: don't edit
+them. `pnpm claude-md:check` fails on a hand-edit, and
+`pnpm create ailk@latest --sync-claude-md` rewrites them to the current
+template. Your own notes go in **Site notes** at the end; a pasted
+CloudParity block goes just above it.
+<!-- /ailk:template id="intro" -->
+
+<!-- ailk:template id="repo-shape" -->
+
 ## Repo shape
 
 ```
-apps/web/         Next.js 16 app — visitor-facing UX
-apps/api/         Fastify HTTP API — checkout, lead capture, webhooks (optional)
-apps/mcp/         MCP server — agent-callable tools (optional)
-content/          MDX content for typed page surfaces (HomePage, BlogPosting, ...)
-.claude/          Rules, skills, and agent definitions for Claude Code
-docs/             Project notes (ADRs, architecture, planning)
+apps/web/         Next.js app — visitor-facing UX
+apps/api/         Fastify HTTP API — lead capture, checkout, webhooks
+apps/mcp/         MCP server — agent-callable tools
+database/         Prisma schema + migrations
+content/          Site settings (_site.mdx) and MDX pages (en/<TypeName>/)
+.claude/          Rules, skills and agent definitions for Claude Code
+tools/            This repo's own checks (architecture, CLAUDE.md drift)
 ```
 
-You consume `@working-theory/*` packages from npm. Source for those packages is at
-<https://github.com/working-theory-labs/ai-launch-kit>; you don't have it locally.
-Treat each `@working-theory/*` package as a third-party dependency — read its README
-or its types, don't go looking for the source.
+You consume `@working-theory/*` packages from npm. Treat each one as a
+third-party dependency: read its README or its types, not its source.
+<!-- /ailk:template id="repo-shape" -->
+
+<!-- ailk:template id="architecture" -->
 
 ## Architecture invariants
 
@@ -26,44 +39,78 @@ The full rule lives at `.claude/rules/architecture.md`. Summary:
 - `apps/web` does not read the database — it goes through `apps/api` via
   the published HTTP client. The one exception is the Better Auth adapter
   (`apps/web/lib/prisma-for-auth.ts`, typed in `apps/web/auth.ts`).
-- Vendor SDKs (Stripe, Resend, NextAuth, Prisma) are wrapped in their
-  respective `@working-theory/*` packages. Don't import them directly in your code.
-- New page types live under `content/<TypeName>/` and consume the schema
-  builders from `@working-theory/schema`.
+- Vendor SDKs (Stripe, Resend, Prisma) are wrapped in their
+  `@working-theory/*` packages. Don't import them directly.
+- A page is an MDX file under `content/en/<TypeName>/`, typed against
+  `@working-theory/schema`.
 
-Crossing one of these is an architecture decision, not a workaround. If
-you think you need to, stop and write a short note in `docs/` explaining
-why before you change the boundary.
+Crossing one of these is an architecture decision, not a workaround. Stop
+and ask before you change a boundary. `architecture.yaml` records them for
+your module set; `pnpm architecture` enforces it, and a hook in
+`.claude/settings.json` runs it after every edit.
+<!-- /ailk:template id="architecture" -->
 
-`architecture.yaml` records these boundaries for your module set, and
-`pnpm architecture` (`tools/lint-architecture.ts`) enforces it. A
-PostToolUse hook in `.claude/settings.json` runs it after every Edit or
-Write and reports a violation in-session; `pnpm preflight` and CI run it too.
+<!-- ailk:template id="resource-map" -->
 
 ## Resource map
 
-Where to find the rule, surface, or fact you need.
-
-| For…                                           | Look at                                                        |
-| ---------------------------------------------- | -------------------------------------------------------------- |
-| Per-issue workflow (pick → branch → TDD → PR)  | § Workflow, below                                              |
-| Architecture boundaries (the why + escalation) | `.claude/rules/architecture.md`                                |
-| Diff hygiene when editing existing files       | `.claude/rules/preserve-existing-style.md`                     |
-| Skills available to invoke                     | `.claude/skills/README.md`                                     |
-| Domain agents (sample web agent)               | `.claude/agents/web.md`                                        |
-| Code style, testing, security, content schema  | `CONVENTIONS.md`                                               |
-| Environment variables and what they unlock     | `.env.example`                                                 |
-| Per-page-type content shape                    | `content/<TypeName>/*.mdx` frontmatter                         |
-| Deploy targets                                 | `apps/web/vercel.json`, `apps/api/vercel.json`                 |
-| Verification before push                       | `pnpm preflight` (architecture + types + lint + build)         |
-
-If a question doesn't fit any row above, add the answer to this table
-when you find it. Future-you will thank present-you.
+| For…                                           | Look at                                                                                            |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Per-issue workflow (pick → branch → TDD → PR)  | § Workflow, below                                                                                  |
+| Architecture boundaries (the why + escalation) | `.claude/rules/architecture.md`                                                                    |
+| Module set + import boundaries                 | `architecture.yaml` — never hand-edit; regenerate with `create-ailk --sync-architecture <modules>` |
+| What this site is (the roster of record)       | `.ailk-site-manifest.json`                                                                         |
+| The locked look                                | `DESIGN.md`                                                                                        |
+| Change the look                                | `create-ailk apply-design <name\|path>` (keeps `brand:`); at scaffold, `--design <folder>`         |
+| Logos, photos, brand reference                 | `brand_assets/`                                                                                    |
+| Repo identity, labels, hard floors             | `project.yaml`                                                                                     |
+| Diff hygiene when editing existing files       | `.claude/rules/preserve-existing-style.md`                                                         |
+| Code style, testing, security                  | `CONVENTIONS.md`                                                                                   |
+| Environment variables and what they unlock     | `.env.example`                                                                                     |
+| Deploy configuration                           | `apps/api/vercel.json`; the `setup-deploy` skill                                                   |
+| Verification before push                       | `pnpm preflight` (see § Checks)                                                                    |
+
+<!-- /ailk:template id="resource-map" -->
+
+<!-- ailk:template id="skills" -->
+
+## Skills
+
+In `.claude/skills/`; Claude Code finds them at session start.
+
+| Skill            | Use when                                                          |
+| ---------------- | ----------------------------------------------------------------- |
+| `add-page`       | You need a new page, or extra JSON-LD on an existing one          |
+| `update-page`    | A page should live at a different URL, or needs a new title       |
+| `fill-page`      | A page still carries `{placeholder}` copy                         |
+| `check-site`     | You want the site's citation-readiness score and findings         |
+| `setup-database` | Leads should land in a database inbox at `/leads`                 |
+| `setup-deploy`   | You are ready to deploy to Vercel                                 |
+| `add-auth`       | Visitors need to sign in (magic link, Google, GitHub)             |
+| `upgrade-plan`   | You are weighing Free against a paid level or the commerce add-on |
+
+<!-- /ailk:template id="skills" -->
+
+<!-- ailk:template id="checks" -->
+
+## Checks
+
+| Command                | Catches                                                  |
+| ---------------------- | -------------------------------------------------------- |
+| `pnpm preflight`       | The next four and `build`, not `test`. Run before a push |
+| `pnpm architecture`    | An import that crosses a boundary in `architecture.yaml` |
+| `pnpm claude-md:check` | A hand-edit inside a template-owned section of this file |
+| `pnpm type-check`      | Type errors in every workspace                           |
+| `pnpm lint`            | Lint errors in every workspace                           |
+| `pnpm test`            | Failing unit tests                                       |
+| `check-site` skill     | Missing or invalid JSON-LD, weak citation-readiness      |
+
+<!-- /ailk:template id="checks" -->
+
+<!-- ailk:template id="workflow" -->
 
 ## Workflow
 
-The single-developer flow, in full:
-
 1. Pick or open an issue with a `## Acceptance Criteria` section.
 2. Branch from your default branch (typically `main`).
 3. Write tests against the acceptance criteria first (RED).
@@ -71,83 +118,79 @@ The single-developer flow, in full:
 5. Run `pnpm preflight` — must be green before you push.
 6. Open a PR; reference the issue with `Closes #N`.
 
-Skip the test-first step only for: pure documentation, single-line typo
-fixes, or config-only changes already covered by an existing test.
-
-## Project-specific MCP servers
+Skip the test-first step only for documentation, typo fixes, or config
+changes an existing test already covers.
+<!-- /ailk:template id="workflow" -->
 
-Configured in `.claude/settings.json`. This project doesn't ship any MCP
-server connections by default — add the ones you actually use (your
-database, your deployment platform, etc.) and keep the tokens in
-`.env.local`, never in the repo.
+<!-- ailk:template id="content" -->
 
-```json
-// example shape — add only what you have credentials for
-{
-  "mcpServers": {
-    "your-database": { "command": "...", "args": ["..."] }
-  }
-}
-```
+## Content
 
-## Content schema discipline
-
-This project's content is typed against schema.org via `@working-theory/schema`.
-Every MDX file under `content/` has frontmatter that the build validates:
+`content/_site.mdx` holds the site's name, identity entity, `theme:` (the
+design's) and `brand:` (the owner's colours and fonts). Each page is
+`content/en/<TypeName>/<slug>.mdx`: frontmatter names the page type, and
+the page body is a `sections:` list the build validates:
 
 ```yaml
 ---
-type: BlogPosting # one of the supported page types
-slug: my-post # URL-safe identifier
-title: My Post
-description: "Short summary used for the page meta tag and JSON-LD."
+type: HomePage
+slug: home
+title: Your Company
+sections:
+  - id: hero
+    type: hero
+    data:
+      {
+        headline: "{Your headline}",
+        primaryCta: { label: "Contact us", href: "/contact" },
+      }
 ---
 ```
 
-When in doubt, copy an existing file in the same folder, then change the
-slug and the body. Don't invent a new `type` value without first
-checking what `@working-theory/schema` exports.
-
-## Hard floors
-
-These are non-negotiable in this repo. Don't ask, don't try to route
-around them.
-
-- **No live Stripe keys in code.** The runtime guard is an ALLOW-LIST, not
-  a list of banned prefixes: it accepts only recognized test-mode keys
-  (`sk_test_`, `pk_test_`, `rk_test_`) and refuses everything else. Every
-  live key is therefore refused — a restricted key (`rk_live_`) and any
-  prefix Stripe introduces later included — because it is absent from the
-  allow-list, not because someone remembered to ban it. Live keys belong
-  in the deployment platform's secrets store, never in `.env`, source
-  files, or commit messages. Use Stripe sandbox keys for everything in
-  source.
-- **No secrets in commits.** API keys, license keys, database URLs — all
-  go through `.env.local` (gitignored) for local dev and the deployment
-  platform's secrets store for prod.
-- **Validate every webhook.** Stripe sends signed payloads; reject any
-  request whose HMAC doesn't match before you do any work on it.
-- **No production database access from a dev session.** If you need to
-  inspect prod, do it through your hosting platform's read-only console,
-  not from your laptop with a copied connection string.
+Copy an existing file in the same folder, then change it. Text in `{braces}`
+is placeholder copy. Don't invent a `type` that `@working-theory/schema`
+doesn't export.
+<!-- /ailk:template id="content" -->
 
-## When to stop and ask
+<!-- ailk:template id="hard-floors" -->
 
-You have wide latitude on most things, but stop and surface the question
-when:
+## Hard floors (non-negotiable)
+
+- **Stripe test keys only in source.** The guard is an allow-list: it
+  refuses every live key.
+- **No secrets in commits.** Keys and database URLs go in `.env.local`
+  (gitignored) locally and the platform's secrets store in production.
+- **Validate every webhook.** Reject any request whose signature doesn't
+  match before you do any work on it.
+- **No production database access from a dev session.**
+
+<!-- /ailk:template id="hard-floors" -->
+
+<!-- ailk:template id="when-to-stop" -->
+
+## When to stop and ask
 
 - An architecture invariant would have to bend.
-- A change to a shared `@working-theory/*` package would be needed (file an issue
-  upstream at <https://github.com/working-theory-labs/ai-launch-kit>; don't fork).
-- You're about to delete or move >5 files at once.
+- A change to a `@working-theory/*` package would be needed.
+- You're about to delete or move more than 5 files at once.
 - The acceptance criteria contradict each other or the existing code.
 
-A 30-second clarifying question beats two hours of work down the wrong
-branch.
+A 30-second question beats two hours down the wrong branch. Global rules
+in `~/.claude/rules/` still apply; this file wins only where it says so.
+<!-- /ailk:template id="when-to-stop" -->
+
+<!-- ailk:template id="help" -->
+
+## Help
+
+- Documentation: <https://ailaunchkit.ai/docs>
+- File an issue: <https://github.com/working-theory-labs/ai-launch-kit/issues>
+
+<!-- /ailk:template id="help" -->
+
+<!-- ailk:site -->
 
-## Inherited rules
+## Site notes
 
-If you have global rules in `~/.claude/rules/` they still apply. This
-file describes only what's specific to `{{PROJECT_NAME}}`. Where the two
-disagree, the global rule wins unless you're explicitly editing this
-file to override it.
+Yours. `--sync-claude-md` and `pnpm claude-md:check` never read or change
+anything from the marker above to the end of the file.

package/templates/DESIGN.md

@@ -1,6 +1,6 @@
 ---
 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.
+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"
@@ -15,6 +15,19 @@ colors:
   fg-dark: "#ffffff"
   border-dark: "#ffffff"
   brand-dark: "#ffffff"
+  text-muted-dark: "#cccccc"
+treatments:
+  corners: square
+  eyebrowCase: sentence
+  placeholders: fill
+  checkmarks: plain
+layout:
+  nav: full
+  footer: columns
+  announcementBanner: false
+  home: default
+copy:
+  density: standard
 typography:
   display:
     fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
@@ -69,9 +82,12 @@ spacing:
   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.
+  The tokens above describe what the site RENDERS today. The design's own
+  colours and shape knobs live in content/_site.mdx `theme:`, which
+  `create-ailk apply-design` replaces wholesale; the owner's brand colours and
+  fonts live beside it in `brand.colors` and `brand.fonts`, which applying a
+  design never rewrites. Radius and spacing are platform defaults a site
+  cannot override yet — see "Where this is heading" below.
 -->
 
 # Standard
@@ -84,6 +100,27 @@ Every page is composed from the AI Launch Kit component library (`@working-theor
 
 ## Colors
 
+<!-- generated:begin colors -->
+
+| Key                 | Value     | Compiles to                                                                                                    |
+| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
+| `bg`                | `#ffffff` | `light.bg`                                                                                                     |
+| `fg`                | `#000000` | `light.text`                                                                                                   |
+| `surface`           | `#ffffff` | `light.surface`                                                                                                |
+| `surface-secondary` | `#ffffff` | `light.bgMuted`                                                                                                |
+| `border`            | `#000000` | `light.border`                                                                                                 |
+| `text-muted`        | `#333333` | `light.textMuted`                                                                                              |
+| `brand`             | `#000000` | `light.primary`                                                                                                |
+| `fg-on-brand`       | `#ffffff` | `light.primaryFg`                                                                                              |
+| `accent`            | `#000000` | `light.accent`                                                                                                 |
+| `bg-dark`           | `#000000` | `dark.bg`, `dark.bgMuted` (fallback of L1), `dark.surface` (fallback of L2), `dark.primaryFg` (fallback of L4) |
+| `fg-dark`           | `#ffffff` | `dark.text`                                                                                                    |
+| `border-dark`       | `#ffffff` | `dark.border`                                                                                                  |
+| `brand-dark`        | `#ffffff` | `dark.primary`, `dark.accent` (fallback of L5)                                                                 |
+| `text-muted-dark`   | `#cccccc` | `dark.textMuted`                                                                                               |
+
+<!-- generated:end -->
+
 ### Primary
 
 **Black** (`brand` `#000000`) fills the primary button; its label is white. The secondary button is white with a black hairline and black label.
@@ -100,6 +137,18 @@ Dark mode inverts: black ground, white ink, white rules, white primary button wi
 
 ## Typography
 
+<!-- generated:begin typography -->
+
+| Role              | Family                                                                   | Size       | Weight | Line height | Tracking |
+| ----------------- | ------------------------------------------------------------------------ | ---------- | ------ | ----------- | -------- |
+| `display`         | `system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif` | `3.5rem`   | 700    | 1.1         | `normal` |
+| `heading-section` | `system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif` | `3rem`     | 700    | 1.1         | `normal` |
+| `heading-item`    | —                                                                        | `2rem`     | 700    | 1.375       | `normal` |
+| `body`            | `system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif` | `1.125rem` | 400    | 1.5         | —        |
+| `eyebrow`         | —                                                                        | `0.875rem` | 600    | 1.4         | `0.05em` |
+
+<!-- generated:end -->
+
 System sans throughout; no web font.
 
 ### Hierarchy
@@ -118,10 +167,53 @@ The small label above a section heading is **kept** as part of this foundation's
 
 ## Layout
 
+<!-- generated:begin layout -->
+
+| Knob                 | Value     |
+| -------------------- | --------- |
+| `nav`                | `full`    |
+| `footer`             | `columns` |
+| `announcementBanner` | `false`   |
+| `home`               | `default` |
+
+| Spacing          | Value    |
+| ---------------- | -------- |
+| `section`        | `7rem`   |
+| `section-mobile` | `4rem`   |
+| `card`           | `1.5rem` |
+| `grid`           | `1.5rem` |
+| `container`      | `1280px` |
+| `measure`        | `36rem`  |
+
+<!-- generated:end -->
+
 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.
 
+## Copy
+
+<!-- generated:begin copy -->
+
+Copy density: standard — pages carry the ordinary amount of body copy for their section.
+<!-- generated:end -->
+
 ## Shapes
 
+<!-- generated:begin shapes -->
+
+| Rounded  | Value     |
+| -------- | --------- |
+| `button` | `0.5rem`  |
+| `card`   | `0.75rem` |
+
+| Treatment                 | Value      |
+| ------------------------- | ---------- |
+| `treatments.corners`      | `square`   |
+| `treatments.eyebrowCase`  | `sentence` |
+| `treatments.placeholders` | `fill`     |
+| `treatments.checkmarks`   | `plain`    |
+
+<!-- generated:end -->
+
 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
@@ -156,8 +248,8 @@ The foundation's pinned direction is the pacing of a classic wireframe marketing
 ## 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.
+- **Do** set your brand colours (`primary`, `primaryFg`, `accent`, per mode) in `content/_site.mdx` `brand.colors` and your fonts (`display`, `body`) in `brand.fonts`; they reach every section and survive applying another design, which replaces `theme:`.
+- **Don't** add a colour accent. The foundation's one idea is black on white; a brand pass adds colour deliberately, through `brand.colors`.
 - **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.