create-raredays-app 0.1.12 → 0.3.0

package/README.md

@@ -37,9 +37,11 @@ Presets set the template, modules, and brand color. You can still customise disp
 ## Options
 
 - `--template <name>` -- `full-stack` (default), `client`, or `static`.
-- `--preset <name>` -- `courseware`, `internal-tool`, or `demo`. Overrides `--template` and `--modules`.
-- `--modules <list>` -- comma-separated modules to wire: `billing`, `jobs`, `notifications`, `email`, `telemetry`, `feature-flags`.
-- `--vendors <list>` -- comma-separated vendor preconfiguration: `stripe`, `resend`, `sentry`, `axiom`.
+- `--preset <name>` -- `courseware`, `internal-tool`, or `demo`. **Overrides** `--template`, `--modules`, and `--vendors` (it does not extend them).
+- `--modules <list>` -- comma-separated modules to wire. Discovered dynamically from `scaffold-fragments/`: `billing`, `cms`, `email`, `feature-flags`, `i18n`, `identity`, `jobs`, `notifications`, `organizations`, `telemetry`. Modules apply to `full-stack` and `client` templates only.
+- `--vendors <list>` -- comma-separated **`module:vendor` pairs**, e.g. `billing:stripe,cms:hygraph,email:resend,identity:better-auth`. A bare vendor name (`stripe`) is not a valid pair and is skipped with a warning.
+- `--harness <name>` -- wire `@raredays/mcp` into an MCP-aware IDE: `claude-code`, `cursor`, `windsurf`, or `none` (default). Adds `@raredays/mcp` to devDependencies and writes the IDE config (`.mcp.json` at root for Claude Code; `.cursor/mcp.json` / `.windsurf/mcp.json` otherwise).
+- `--deploy <target>` -- scaffold deploy config: `vercel` or `none` (default). Writes `vercel.json`, `.env.example`, and `docs/DEPLOY.md`.
 - `--remote-url <url>` -- set git remote origin after scaffolding.
 - `--no-git` -- skip `git init`.
 - `--no-install` -- skip `pnpm install`.
@@ -49,27 +51,41 @@ Presets set the template, modules, and brand color. You can still customise disp
 ## What it does
 
 1. Copies `templates/<name>/` into the target directory.
-2. Renames stub files (`_gitignore` -> `.gitignore`, `_github` -> `.github`).
+2. Renames stub files (`_gitignore` -> `.gitignore`, `_npmrc` -> `.npmrc`, `_claude` -> `.claude`, `_github` -> `.github`).
 3. Sets `package.json:name` to the project slug.
 4. Substitutes `__SLUG__` in `site.spec.ts` and applies display name, domain, and brand color.
-5. Loads scaffold fragments for selected modules (imports, config, ports, file overlays).
-6. Composes `app/lib/runtime.ts` with module wiring and `mocks/handlers.ts` with vendor mocks.
-7. Merges fragment dependencies into `package.json`.
-8. Writes `.env.example` if any vendor env vars are needed.
-9. Optionally runs `git init` and `pnpm install`.
+5. Loads scaffold fragments for selected modules (imports, config, ports, file overlays) and applies vendor overlays for each `module:vendor` pair.
+6. Composes `app/lib/runtime.ts` with module wiring and `mocks/handlers.ts` with vendor mocks (skipped for the `static` template, which has no composition root).
+7. Merges fragment + vendor dependencies into `package.json`.
+8. Applies `--harness` (MCP config) and `--deploy` (deploy config) when requested.
+9. Writes `.env.example` **only** if any vendor or deploy env vars are needed.
+10. Optionally runs `git init` and `pnpm install`.
 
 ## Scaffold fragments
 
-The `scaffold-fragments/` directory contains per-module overlays:
-
-- `billing/` -- Stripe billing integration (checkout, portal, webhooks)
-- `email/` -- Resend email provider
-- `feature-flags/` -- Vercel Flags SDK wiring
-- `jobs/` -- Background job processing
-- `notifications/` -- Multi-channel notification delivery
-- `telemetry/` -- Sentry + Axiom telemetry
-
-Each fragment has a `module.json` manifest, runtime slot injections, and optional file overlays.
+The `scaffold-fragments/` directory contains per-module overlays (10 total):
+
+- `billing/` -- billing integration; vendor: `stripe`
+- `cms/` -- CMS integration; vendor: `hygraph`
+- `email/` -- transactional email; vendor: `resend`
+- `feature-flags/` -- feature-flag wiring
+- `i18n/` -- internationalisation
+- `identity/` -- auth/sessions/roles; vendor: `better-auth`
+- `jobs/` -- background job processing
+- `notifications/` -- multi-channel notification delivery
+- `organizations/` -- multi-tenant organizations
+- `telemetry/` -- telemetry; vendors: `sentry`, `axiom`
+
+Each fragment has a `module.json` manifest, runtime slot injections, and optional per-vendor file overlays.
+
+## Keeping template pins current
+
+Every template and fragment pins `@raredays/*` deps and `MCP_VERSION`. These are
+the framework's public surface — a non-`--dev` scaffold installs exactly what
+they pin — and do not move automatically when the workspace releases. Run
+`pnpm --filter create-raredays-app sync-versions` (also run as `prepublishOnly`)
+to refresh them to `^<current workspace version>`. The guard test
+`test/template-workspace-pins.test.ts` fails in CI when a pin drifts out of range.
 
 ## How it fits in the ecosystem
 

package/bin/index.js

@@ -635,12 +635,14 @@ async function scaffold(opts) {
 // ─── MCP harness wiring ──────────────────────────────────────────────────
 
 const HARNESS_CONFIGS = {
-  "claude-code": ".claude/mcp.json",
+  // Claude Code reads project-scope MCP servers from `.mcp.json` at the repo
+  // root (not `.claude/mcp.json`), as this monorepo's own `.mcp.json` does.
+  "claude-code": ".mcp.json",
   cursor: ".cursor/mcp.json",
   windsurf: ".windsurf/mcp.json",
 };
 
-const MCP_VERSION = "0.0.1";
+const MCP_VERSION = "0.2.0";
 
 async function applyHarness(targetDir, pkg, harness, dev) {
   if (!harness || harness === "none") return;
@@ -944,26 +946,70 @@ async function main() {
         `Unknown preset "${values.preset}". Available presets: ${Object.keys(PRESETS).join(", ")}`,
       );
     }
+    const resolvedTemplate = preset ? preset.template : values.template;
     const requestedModules = preset ? preset.modules : parseCsv(values.modules);
     const availableModules = availableModuleKeys();
     const known = [];
     for (const m of requestedModules) {
-      if (availableModules.includes(m)) {
-        known.push(m);
-      } else {
+      if (!availableModules.includes(m)) {
         console.warn(
           `warning: --modules "${m}" has no scaffold-fragment under scaffold-fragments/${m}/, skipping. Available: ${availableModules.join(", ")}`,
         );
+        continue;
       }
+      // Mirror the interactive path's template-compatibility filter: a module
+      // whose fragment does not declare the resolved template is skipped (its
+      // runtime/files assume a composition root that template lacks).
+      const fragment = allFragments.find((f) => f.key === m);
+      const supported = fragment?.templates ?? ["full-stack"];
+      if (!supported.includes(resolvedTemplate)) {
+        console.warn(
+          `warning: --modules "${m}" is not compatible with the "${resolvedTemplate}" template (supports: ${supported.join(", ")}), skipping.`,
+        );
+        continue;
+      }
+      known.push(m);
+    }
+
+    // Validate --vendors pairs (module:vendor) and warn on unknown ones, the way
+    // the module list already warns. A silently-dropped vendor is worse than a
+    // loud one.
+    const requestedVendors = preset ? preset.vendors : parseCsv(values.vendors);
+    const knownVendors = [];
+    for (const pair of requestedVendors) {
+      const [moduleKey, vendorKey] = pair.split(":");
+      if (!vendorKey) {
+        console.warn(
+          `warning: --vendors "${pair}" is not a "module:vendor" pair (e.g. "billing:stripe"), skipping.`,
+        );
+        continue;
+      }
+      const fragment = allFragments.find((f) => f.key === moduleKey);
+      const vendor = fragment?.vendors?.find((v) => v.key === vendorKey);
+      if (!known.includes(moduleKey)) {
+        console.warn(
+          `warning: --vendors "${pair}" names module "${moduleKey}", which is not in the selected/compatible module set, skipping.`,
+        );
+        continue;
+      }
+      if (!vendor) {
+        const vendorKeys = (fragment?.vendors ?? []).map((v) => v.key);
+        console.warn(
+          `warning: --vendors "${pair}" has no vendor "${vendorKey}" for module "${moduleKey}"${vendorKeys.length ? ` (available: ${vendorKeys.join(", ")})` : ""}, skipping.`,
+        );
+        continue;
+      }
+      knownVendors.push(pair);
     }
+
     opts = {
       projectName: target,
-      template: preset ? preset.template : values.template,
+      template: resolvedTemplate,
       displayName: undefined,
       canonicalDomain: undefined,
       brandPrimary: preset?.brandPrimary ?? undefined,
       selectedModules: known,
-      selectedVendors: preset ? preset.vendors : parseCsv(values.vendors),
+      selectedVendors: knownVendors,
       remoteUrl: values["remote-url"],
       gitInit: !values["no-git"],
       runInstall: !values["no-install"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-raredays-app",
-  "version": "0.1.12",
+  "version": "0.3.0",
   "description": "Scaffold a new RareDays Next.js app.",
   "license": "UNLICENSED",
   "author": "Jeremy Harper <jeremy@raredays.com>",
@@ -22,8 +22,8 @@
   },
   "devDependencies": {
     "typescript": "5.9.3",
-    "vitest": "4.1.9",
-    "@raredays/lint": "0.2.1"
+    "vitest": "4.1.10",
+    "@raredays/lint": "0.2.2"
   },
   "engines": {
     "node": ">=20"
@@ -41,6 +41,8 @@
     "check": "raredays check",
     "test": "vitest run",
     "test:watch": "vitest",
+    "sync-versions": "node scripts/sync-template-versions.mjs",
+    "sync-versions:check": "node scripts/sync-template-versions.mjs --check",
     "dev": "mkdir -p .sandbox && cd .sandbox && node ../bin/index.js",
     "clean": "rm -rf .sandbox"
   }

package/scaffold-fragments/billing/module.json

@@ -3,14 +3,14 @@
   "label": "Billing (subscriptions + webhooks)",
   "description": "Plan registry, subscription state, webhook handler with idempotency + event-bus fan-out.",
   "deps": {
-    "@raredays/billing": "^0.1.0"
+    "@raredays/billing": "^0.3.0"
   },
   "vendors": [
     {
       "key": "stripe",
       "label": "Stripe",
       "deps": {
-        "@raredays/billing-stripe": "^0.1.0"
+        "@raredays/billing-stripe": "^0.1.1"
       },
       "env": [
         "STRIPE_SECRET_KEY",

package/scaffold-fragments/cms/module.json

@@ -3,14 +3,14 @@
   "label": "CMS (headless content + rich text)",
   "description": "Vendor-neutral CMS port. In-memory dev driver for development; swap to Hygraph (or another adapter) for production.",
   "deps": {
-    "@raredays/cms": "^0.1.0"
+    "@raredays/cms": "^0.2.0"
   },
   "vendors": [
     {
       "key": "hygraph",
       "label": "Hygraph",
       "deps": {
-        "@raredays/cms-hygraph": "^0.1.0"
+        "@raredays/cms-hygraph": "^0.1.1"
       },
       "env": [
         "HYGRAPH_ENDPOINT",

package/scaffold-fragments/email/module.json

@@ -3,14 +3,14 @@
   "label": "Transactional email",
   "description": "Vendor-neutral email port. Console adapter for dev; swap to Resend for production.",
   "deps": {
-    "@raredays/email": "^0.1.0"
+    "@raredays/email": "^0.2.0"
   },
   "vendors": [
     {
       "key": "resend",
       "label": "Resend",
       "deps": {
-        "@raredays/email-resend": "^0.1.0"
+        "@raredays/email-resend": "^0.1.2"
       },
       "env": [
         "RESEND_API_KEY"

package/scaffold-fragments/i18n/module.json

@@ -3,7 +3,10 @@
   "label": "Internationalisation (i18n)",
   "description": "Locale resolution, ICU message formatting, date/number/currency formatters, and React hooks.",
   "deps": {
-    "@raredays/i18n": "^0.1.0"
+    "@raredays/i18n": "^1.0.1"
   },
-  "templates": ["full-stack", "client", "static"]
+  "templates": [
+    "full-stack",
+    "client"
+  ]
 }

package/scaffold-fragments/identity/module.json

@@ -3,15 +3,15 @@
   "label": "Identity (auth, sessions, organizations, roles)",
   "description": "Identity port is always wired with an in-memory dev provider. Select a vendor to add the production adapter, env vars, mock handlers, and Next.js auth route stub.",
   "deps": {
-    "@raredays/identity": "^0.1.0"
+    "@raredays/identity": "^0.1.1"
   },
   "vendors": [
     {
       "key": "better-auth",
       "label": "Better Auth (self-hosted)",
       "deps": {
-        "@raredays/identity-better-auth": "^0.1.0",
-        "better-auth": "^1.2.0"
+        "@raredays/identity-better-auth": "^0.2.0",
+        "better-auth": "1.6.11"
       },
       "env": [
         "BETTER_AUTH_SECRET",

package/scaffold-fragments/identity/vendors/better-auth/files/app/lib/auth.ts

@@ -14,7 +14,26 @@
 // See @raredays/identity-better-auth README for the full pattern.
 
 import { betterAuth } from "better-auth";
+import { resolveRedirectorConfig } from "@raredays/identity-better-auth/oauth-redirector";
+
+// Preview-deployment OAuth. Inert unless OAUTH_REDIRECTOR_URL + SECRET are set
+// (Preview env only), so production, staging, and local dev use the direct flow
+// unchanged. When set, previews with dynamic hostnames (per-branch, per-dev)
+// complete OAuth against their OWN database by bouncing through this app's
+// redirector (oauth.<zone>) — the single callback URL you register with the
+// provider (@legoland/project-ops provisions this per project). Set the social
+// provider's `redirectURI` to `redirector.redirectURI` too (see the commented
+// Google block). @raredays/identity-better-auth "Preview OAuth".
+const redirector = resolveRedirectorConfig();
 
 export const auth = betterAuth({
   emailAndPassword: { enabled: true },
+  // socialProviders: {
+  //   google: {
+  //     clientId: process.env.GOOGLE_CLIENT_ID!,
+  //     clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  //     ...(redirector.redirectURI && { redirectURI: redirector.redirectURI }),
+  //   },
+  // },
+  plugins: [...redirector.plugins],
 });

package/scaffold-fragments/jobs/module.json

@@ -3,7 +3,7 @@
   "label": "Background jobs (in-process runner)",
   "description": "Type-safe job definitions, retries, idempotency. In-process runner by default; swap to Inngest/Trigger.dev for durable execution.",
   "deps": {
-    "@raredays/jobs": "^0.1.0"
+    "@raredays/jobs": "^0.2.0"
   },
   "vendors": [],
   "templates": [

package/scaffold-fragments/notifications/module.json

@@ -3,7 +3,7 @@
   "label": "Notifications (multi-channel send)",
   "description": "Notification definitions, channels (email + in-app), user preferences, dedupe, delivery logging.",
   "deps": {
-    "@raredays/notifications": "^0.1.0"
+    "@raredays/notifications": "^0.2.0"
   },
   "vendors": [],
   "templates": [

package/scaffold-fragments/organizations/module.json

@@ -3,7 +3,7 @@
   "label": "Organizations (multi-tenancy)",
   "description": "Domain types + role-based permissions for organizations, memberships, and invitations. Pairs with a postgres provider for storage.",
   "deps": {
-    "@raredays/organizations": "^0.1.0"
+    "@raredays/organizations": "^0.2.0"
   },
   "vendors": [],
   "templates": [

package/scaffold-fragments/telemetry/module.json

@@ -3,14 +3,14 @@
   "label": "Telemetry (logging, errors, metrics, events)",
   "description": "Vendor-neutral observability port. Console adapters for dev; swap to Sentry + Axiom for production.",
   "deps": {
-    "@raredays/telemetry": "^0.1.0"
+    "@raredays/telemetry": "^0.2.0"
   },
   "vendors": [
     {
       "key": "sentry",
       "label": "Sentry (error reporting)",
       "deps": {
-        "@raredays/telemetry-sentry": "^0.1.0"
+        "@raredays/telemetry-sentry": "^0.1.2"
       },
       "env": [
         "SENTRY_DSN"
@@ -24,7 +24,7 @@
       "key": "axiom",
       "label": "Axiom (logging)",
       "deps": {
-        "@raredays/telemetry-axiom": "^0.1.0"
+        "@raredays/telemetry-axiom": "^0.1.1"
       },
       "env": [
         "AXIOM_TOKEN",

package/skillex/private/contribute.md

@@ -1,6 +1,6 @@
 ---
 name: "Contributing to create-raredays-app"
-description: Deep guide to the app scaffolder — CLI flow, CRDA placeholder tokens, composeRuntime/composeHandlers internals, template file trees, customiseSiteSpec regex, fragment loading, env generation, --dev flag.
+description: Deep guide to the app scaffolder — CLI flow, presets, CRDA placeholder tokens, composeRuntime/composeHandlers internals, template file trees, customiseSiteSpec regex, ten fragments + vendor overlays, harness/deploy wiring, env generation, --dev flag, version-pin sync script, and the test suite.
 topics: [scaffolding, contributing]
 tags: [scaffolding, cli, contributing]
 ---
@@ -42,16 +42,18 @@ Prompts in order via `@clack/prompts`:
 
 1. Error if target dir exists
 2. Copy `templates/{template}/` recursively
-3. Rename stub files: `_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`
+3. Rename stub files: `_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`, `_claude` → `.claude`, `_github` → `.github`
 4. Derive slug: trim, lowercase, replace `[^a-z0-9]+` with `-`, strip leading/trailing `-`
 5. Substitute `__SLUG__` in `site.spec.ts`
 6. Apply `customiseSiteSpec()` regex replacements
-7. Load fragments, merge deps, copy fragment `files/` dirs, compose runtime
+7. Load fragments (template-compatibility filtered), merge deps + vendor overlays, copy fragment `files/` dirs, compose runtime
 8. Compose mock handlers if template ≠ `static`
 9. Merge deps into `package.json`, apply `--dev` rewrite if flagged
-10. Write `.env.example` if any env vars collected
-11. `git init --quiet --initial-branch=main` (+ remote if specified)
-12. `pnpm install` with `stdio: "inherit"`
+10. `applyHarness()` (`--harness`) — add `@raredays/mcp` devDep + write the IDE MCP config (`.mcp.json` at root for Claude Code)
+11. `applyDeploy()` (`--deploy vercel`) — write `vercel.json` + `docs/DEPLOY.md`, collect deploy env vars
+12. Write `.env.example` only if any vendor/deploy env vars were collected
+13. `git init --quiet --initial-branch=main` (+ remote if specified)
+14. `pnpm install` with `stdio: "inherit"`
 
 ## CRDA Placeholder Tokens
 
@@ -135,12 +137,12 @@ scaffold-fragments/{key}/
   "key": "billing",
   "label": "Billing (subscriptions + webhooks)",
   "description": "...",
-  "deps": { "@raredays/billing": "0.0.1" },
+  "deps": { "@raredays/billing": "^0.2.0" },
   "vendors": [
     {
       "key": "stripe",
       "label": "Stripe",
-      "deps": { "@raredays/billing-stripe": "0.0.1" },
+      "deps": { "@raredays/billing-stripe": "^0.1.0" },
       "env": ["STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"],
       "mocks": { "package": "@raredays/billing-stripe/mocks", "named": "stripeMocks" }
     }
@@ -149,16 +151,24 @@ scaffold-fragments/{key}/
 }
 ```
 
-### Available Fragments
+### Available Fragments (10)
 
 | Fragment        | Templates          | Vendors       | Env Vars                                     |
 | --------------- | ------------------ | ------------- | -------------------------------------------- |
 | `billing`       | full-stack         | Stripe        | `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET` |
+| `cms`           | full-stack, client | Hygraph       | `HYGRAPH_ENDPOINT`, `HYGRAPH_TOKEN`          |
 | `email`         | full-stack         | Resend        | `RESEND_API_KEY`                             |
+| `feature-flags` | full-stack, client | None          | —                                            |
+| `i18n`          | full-stack, client | None          | —                                            |
+| `identity`      | full-stack, client | Better Auth   | `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`      |
 | `jobs`          | full-stack         | None          | —                                            |
 | `notifications` | full-stack         | None          | —                                            |
+| `organizations` | full-stack         | None          | —                                            |
 | `telemetry`     | full-stack, client | Sentry, Axiom | `SENTRY_DSN`, `AXIOM_TOKEN`, `AXIOM_DATASET` |
 
+Pins in `deps`/`vendors[].deps` are `^<workspace version>` for `@raredays/*`
+packages, kept current by `scripts/sync-template-versions.mjs` (see below).
+
 ## .env.example Generation
 
 Only written if `envVars.length > 0`. Format:
@@ -178,12 +188,31 @@ STRIPE_WEBHOOK_SECRET=
 
 Rewrites every `@raredays/*` in both `dependencies` and `devDependencies` to `workspace:*`. Used for in-repo dogfooding (playground scaffolds).
 
+## Version pins (`scripts/sync-template-versions.mjs`)
+
+Templates + fragments pin `@raredays/*` and `bin/index.js` holds `MCP_VERSION`.
+These are the framework's public surface and do NOT move when the workspace
+releases. Run `pnpm --filter create-raredays-app sync-versions` (also
+`prepublishOnly`) to refresh them to `^<workspace version>`; `sync-versions:check`
+is the CI dry-run. The guard test `test/template-workspace-pins.test.ts` fails
+when a pin's range excludes the current workspace version.
+
 ## Testing
 
-No unit tests. Validated by:
+The package ships Vitest guard/unit tests under `test/`:
+
+- **Template lint guards**: every-import-is-declared, secure next/react floors,
+  pnpm-11 build approvals, registry auth, `.ts`-import specifiers, skill
+  frontmatter (v4), workflow lint, no duplicate migration workflow.
+- **`template-workspace-pins.test.ts`**: `@raredays/*` pins (incl. `MCP_VERSION`)
+  resolve the current workspace version.
+- **`scaffold-smoke.test.ts`**: runs `bin/index.js` into a temp dir
+  (`--no-git --no-install --dev`) and asserts the harness config path, merged
+  deps, and composed runtime.
+- **`compose-allow-builds.test.ts`**: `mergeAllowBuilds` unit tests.
 
-- E2E scenarios in `/e2e/` (scaffold → build → serve → test)
-- Manual: `pnpm playground:reset && pnpm playground`
+Full scaffold-build-serve coverage lives in the e2e scenarios (`/e2e/`); use
+`pnpm playground:reset && pnpm playground` for manual checks.
 
 ## Build and Test
 

package/skillex/public/consumer.md

@@ -1,6 +1,6 @@
 ---
 name: "Consuming create-raredays-app"
-description: How to scaffold new apps — interactive prompts sequence, CLI flags, three templates (full-stack/client/static) with output files, five available modules with vendor options, --dev flag for monorepo dogfooding.
+description: How to scaffold new apps — presets, interactive prompts sequence, CLI flags (including --preset/--harness/--deploy), three templates (full-stack/client/static) with output files, ten available modules with vendor options, --dev flag for monorepo dogfooding.
 topics: [scaffolding, consuming]
 tags: [scaffolding, cli, consuming]
 ---
@@ -13,18 +13,21 @@ tags: [scaffolding, cli, consuming]
 pnpm create raredays-app
 ```
 
-Prompts in order:
+Prompts in roughly this order:
 
-1. **Project name** — directory name and package slug (kebab-case, 1–64 chars)
-2. **Template** — `full-stack`, `client`, or `static`
-3. **Display name** — human-readable (defaults to project name)
-4. **Canonical domain** — optional, hostname only (e.g., `example.com`)
-5. **Brand primary color** — hex value (defaults to `#10b981`)
-6. **Modules** — multiselect (not shown for `static`)
-7. **Vendors** — multiselect for selected modules
-8. **Git remote URL** — optional
-9. **Initialize git?** — default yes
-10. **Run pnpm install?** — default yes
+1. **What are you building?** — pick a preset (courseware / internal-tool / demo) or "custom"
+2. **Project name** — directory name and package slug (kebab-case, 1–64 chars)
+3. **Template** — `full-stack`, `client`, or `static` (skipped when a preset is chosen)
+4. **Display name** — human-readable (defaults to project name)
+5. **Canonical domain** — optional, hostname only (e.g., `example.com`)
+6. **Brand primary color** — hex value (defaults to `#10b981`)
+7. **Modules** — multiselect (not shown for `static` or when a preset is chosen)
+8. **Vendors** — multiselect for selected modules
+9. **Deploy target** — optional (`vercel` / none)
+10. **Git remote URL** — optional
+11. **Initialize git? / Run pnpm install?** — default yes
+
+`--harness` (MCP/IDE wiring) is flag-only today; it is not offered interactively.
 
 ## Non-Interactive Mode
 
@@ -37,15 +40,18 @@ pnpm create raredays-app my-app \
 
 ## CLI Flags
 
-| Flag           | Description                                                           |
-| -------------- | --------------------------------------------------------------------- |
-| `--template`   | `full-stack` (default), `client`, or `static`                         |
-| `--modules`    | Comma-separated module keys                                           |
-| `--vendors`    | Comma-separated `MODULE:VENDOR` selectors                             |
-| `--remote-url` | Git remote origin URL                                                 |
-| `--no-git`     | Skip git initialization                                               |
-| `--no-install` | Skip `pnpm install`                                                   |
-| `--dev`        | Rewrite all `@raredays/*` deps to `workspace:*` (monorepo dogfooding) |
+| Flag           | Description                                                                         |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `--template`   | `full-stack` (default), `client`, or `static`                                       |
+| `--preset`     | `courseware`, `internal-tool`, `demo` — **overrides** template/modules/vendors      |
+| `--modules`    | Comma-separated module keys (ignored when `--preset` is given)                      |
+| `--vendors`    | Comma-separated `MODULE:VENDOR` selectors (a bare vendor is skipped with a warning) |
+| `--harness`    | `claude-code` / `cursor` / `windsurf` / none — wire `@raredays/mcp` into the IDE    |
+| `--deploy`     | `vercel` / none — scaffold deploy config (`vercel.json`, `docs/DEPLOY.md`)          |
+| `--remote-url` | Git remote origin URL                                                               |
+| `--no-git`     | Skip git initialization                                                             |
+| `--no-install` | Skip `pnpm install`                                                                 |
+| `--dev`        | Rewrite all `@raredays/*` deps to `workspace:*` (monorepo dogfooding)               |
 
 ## Templates
 
@@ -89,14 +95,21 @@ Key output files:
 
 ## Available Modules
 
-| Module          | Label                       | Template           | Vendor Options |
+Ten fragments live under `scaffold-fragments/`. Each declares which templates it
+supports (`module.json:templates`); a module incompatible with the chosen
+template is skipped with a warning.
+
+| Module          | Label                       | Templates          | Vendor Options |
 | --------------- | --------------------------- | ------------------ | -------------- |
 | `billing`       | Subscriptions + webhooks    | full-stack         | Stripe         |
 | `cms`           | Headless CMS + rich text    | full-stack, client | Hygraph        |
 | `email`         | Transactional email         | full-stack         | Resend         |
+| `feature-flags` | Feature-flag wiring         | full-stack, client | —              |
+| `i18n`          | Internationalisation        | full-stack, client | —              |
 | `identity`      | Auth, sessions, orgs, roles | full-stack, client | Better Auth    |
 | `jobs`          | Background jobs             | full-stack         | — (in-memory)  |
 | `notifications` | Multi-channel notifications | full-stack         | — (in-memory)  |
+| `organizations` | Multi-tenant organizations  | full-stack         | — (in-memory)  |
 | `telemetry`     | Logging, errors, metrics    | full-stack, client | Sentry, Axiom  |
 
 Identity is always wired with an in-memory dev provider (the template hard-codes
@@ -140,11 +153,13 @@ A fully configured project with:
 
 - `site.spec.ts` — SiteSpec with your name, domain, and brand color substituted
 - `app/lib/runtime.ts` — composition root with selected modules wired via slot injection
-- `app/theme.css` — generated `@theme` overrides from branding config
+- `app/theme.override.css` — build-time `@theme` overrides from branding config
 - `next.config.ts` — wraps `withRaredays()`
 - `postcss.config.mjs` — re-exports from `@raredays/style/postcss`
 - `mocks/` — MSW setup with vendor-specific handlers (client/full-stack)
-- `.env.example` — required env vars for selected vendors
+- `.env.example` — written only when a selected vendor or `--deploy` target needs env vars
+- With `--harness`: `.mcp.json` (Claude Code, at root) / `.cursor/mcp.json` / `.windsurf/mcp.json` + `@raredays/mcp` devDep
+- With `--deploy vercel`: `vercel.json` + `docs/DEPLOY.md`
 
 ## After Scaffolding
 

package/templates/client/app/theme.override.css

@@ -1,5 +1,7 @@
-/*
- * Auto-generated by @raredays/theme-build. Do not edit by hand.
+/**
+ * AUTO-GENERATED — DO NOT EDIT.
+ * Regenerated from site.spec.ts by `pnpm theme:build`.
+ * For per-app CSS overrides, edit app/globals.css instead.
  * Source: site.spec.ts
  * To regenerate: pnpm theme:build
  */

package/templates/client/package.json

@@ -26,11 +26,11 @@
     "check": "raredays check && tsc --noEmit"
   },
   "dependencies": {
-    "@raredays/components": "^0.1.0",
-    "@raredays/core": "^0.1.0",
-    "@raredays/identity": "^0.1.0",
-    "@raredays/mocks": "^0.1.0",
-    "@raredays/style": "^0.1.0",
+    "@raredays/components": "^0.3.0",
+    "@raredays/core": "^0.3.0",
+    "@raredays/identity": "^0.1.1",
+    "@raredays/mocks": "^0.2.0",
+    "@raredays/style": "^0.3.0",
     "lucide-react": "1.14.0",
     "msw": "2.11.5",
     "next": "16.2.9",
@@ -39,12 +39,12 @@
   },
   "devDependencies": {
     "@atheory-ai/skillex": "0.7.2",
-    "@raredays/dev": "^0.1.0",
-    "@raredays/lint": "^0.1.0",
-    "@raredays/site-config": "^0.1.0",
-    "@raredays/skills": "^0.1.0",
-    "@raredays/theme-build": "^0.1.0",
-    "@raredays/typescript": "^0.1.0",
+    "@raredays/dev": "^0.2.0",
+    "@raredays/lint": "^0.2.2",
+    "@raredays/site-config": "^0.3.0",
+    "@raredays/skills": "^0.2.0",
+    "@raredays/theme-build": "^0.3.0",
+    "@raredays/typescript": "^0.3.0",
     "@storybook/react-vite": "10.3.6",
     "@tailwindcss/postcss": "4.2.4",
     "@tailwindcss/vite": "4.2.4",
@@ -52,13 +52,13 @@
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "6.0.1",
-    "@vitest/coverage-v8": "4.1.5",
+    "@vitest/coverage-v8": "4.1.9",
     "happy-dom": "15.11.7",
     "storybook": "10.3.6",
     "tailwindcss": "4.2.4",
     "typescript": "5.9.3",
     "vite": "8.0.10",
-    "vitest": "4.1.5"
+    "vitest": "4.1.9"
   },
   "engines": {
     "node": ">=24"

package/templates/full-stack/app/theme.override.css

@@ -1,5 +1,7 @@
-/*
- * Auto-generated by @raredays/theme-build. Do not edit by hand.
+/**
+ * AUTO-GENERATED — DO NOT EDIT.
+ * Regenerated from site.spec.ts by `pnpm theme:build`.
+ * For per-app CSS overrides, edit app/globals.css instead.
  * Source: site.spec.ts
  * To regenerate: pnpm theme:build
  */

package/templates/full-stack/db/index.ts

@@ -36,8 +36,7 @@ const hasDatabaseUrl = Boolean(process.env.DATABASE_URL);
 // Dev fallback: bootstrap PGlite eagerly so providers can register
 // tables at composition-root eval. In prod, or when DATABASE_URL is
 // set, leave this null and fall through to the lazy Proxy below.
-const eagerPglite: Db | null =
-  !isProduction && !hasDatabaseUrl ? await bootstrapPglite() : null;
+const eagerPglite: Db | null = !isProduction && !hasDatabaseUrl ? await bootstrapPglite() : null;
 
 let cached: Db | undefined = eagerPglite ?? undefined;
 
@@ -60,15 +59,28 @@ async function bootstrapPglite(): Promise<Db> {
   // you need the full migration set in dev, point DATABASE_URL at a
   // local Postgres and run `pnpm db:migrate`.
   const statements: readonly string[] = [
-    `CREATE TABLE IF NOT EXISTS audit_events (
-       id text PRIMARY KEY,
-       organization_id text NOT NULL,
-       actor_id text,
-       action text NOT NULL,
-       resource_type text NOT NULL,
-       resource_id text,
-       payload jsonb NOT NULL DEFAULT '{}'::jsonb,
-       created_at timestamptz NOT NULL DEFAULT now()
+    // Audit substrate — `audit_entries` is the ONE audit table (S2a / D3). The
+    // old `audit_events` table was retired: `@raredays/audit-drizzle` persists
+    // `audit_entries`, which matches the core `AuditProvider` port. If you hold
+    // legacy `audit_events` rows, backfill them into `audit_entries` before
+    // dropping (see the @raredays/postgres CHANGELOG / migration M8-backfill).
+    `DO $$ BEGIN
+       CREATE TYPE audit_actor_type AS ENUM ('user', 'system', 'api-key');
+     EXCEPTION WHEN duplicate_object THEN null; END $$`,
+    `CREATE TABLE IF NOT EXISTS audit_entries (
+       id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+       organization_id uuid NOT NULL,
+       actor_id text NOT NULL,
+       actor_type audit_actor_type NOT NULL,
+       action varchar(255) NOT NULL,
+       target_type varchar(255) NOT NULL,
+       target_id text NOT NULL,
+       metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+       ip_address varchar(45),
+       user_agent text,
+       timestamp timestamptz NOT NULL DEFAULT now(),
+       created_at timestamptz NOT NULL DEFAULT now(),
+       updated_at timestamptz NOT NULL DEFAULT now()
      )`,
     `CREATE TABLE IF NOT EXISTS webhook_deliveries (
        id text PRIMARY KEY,
@@ -82,17 +94,35 @@ async function bootstrapPglite(): Promise<Db> {
        created_at timestamptz NOT NULL DEFAULT now(),
        updated_at timestamptz NOT NULL DEFAULT now()
      )`,
+    // Jobs substrate — append-only log + tenant-scoped dedup markers (S2a / D2).
+    // `job_executions` carries NO unique index (every status transition is an
+    // insert); dedup-of-record lives in `job_dedup_markers`.
+    `DO $$ BEGIN
+       CREATE TYPE job_execution_status AS ENUM
+         ('enqueued', 'running', 'succeeded', 'failed', 'skipped');
+     EXCEPTION WHEN duplicate_object THEN null; END $$`,
     `CREATE TABLE IF NOT EXISTS job_executions (
-       id text PRIMARY KEY,
-       organization_id text NOT NULL,
-       job_name text NOT NULL,
-       status text NOT NULL DEFAULT 'pending',
-       payload jsonb NOT NULL DEFAULT '{}'::jsonb,
-       result jsonb,
-       error text,
-       scheduled_at timestamptz NOT NULL DEFAULT now(),
-       started_at timestamptz,
-       completed_at timestamptz
+       id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+       organization_id uuid NOT NULL,
+       created_at timestamptz NOT NULL DEFAULT now(),
+       updated_at timestamptz NOT NULL DEFAULT now(),
+       job_name varchar(64) NOT NULL,
+       idempotency_key varchar(128),
+       status job_execution_status NOT NULL,
+       attempts integer NOT NULL DEFAULT 0,
+       payload jsonb NOT NULL,
+       metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+       reason text,
+       error text
+     )`,
+    `CREATE TABLE IF NOT EXISTS job_dedup_markers (
+       id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+       organization_id uuid NOT NULL,
+       created_at timestamptz NOT NULL DEFAULT now(),
+       updated_at timestamptz NOT NULL DEFAULT now(),
+       job_name varchar(64) NOT NULL,
+       idempotency_key varchar(128) NOT NULL,
+       CONSTRAINT job_dedup_markers_key_idx UNIQUE (organization_id, job_name, idempotency_key)
      )`,
   ];
   for (const stmt of statements) {

package/templates/full-stack/package.json

@@ -32,14 +32,14 @@
     "check": "raredays check && tsc --noEmit"
   },
   "dependencies": {
-    "@raredays/components": "^0.1.0",
-    "@raredays/core": "^0.1.0",
-    "@raredays/identity": "^0.1.0",
-    "@raredays/mocks": "^0.1.0",
-    "@raredays/postgres": "^0.1.0",
-    "@raredays/postgres-neon": "^0.1.0",
-    "@raredays/postgres-pglite": "^0.1.0",
-    "@raredays/style": "^0.1.0",
+    "@raredays/components": "^0.3.0",
+    "@raredays/core": "^0.3.0",
+    "@raredays/identity": "^0.1.1",
+    "@raredays/mocks": "^0.2.0",
+    "@raredays/postgres": "^0.3.0",
+    "@raredays/postgres-neon": "^0.2.1",
+    "@raredays/postgres-pglite": "^0.2.1",
+    "@raredays/style": "^0.3.0",
     "drizzle-orm": "0.45.2",
     "lucide-react": "1.14.0",
     "msw": "2.11.5",
@@ -49,12 +49,12 @@
   },
   "devDependencies": {
     "@atheory-ai/skillex": "0.7.2",
-    "@raredays/dev": "^0.1.0",
-    "@raredays/lint": "^0.1.0",
-    "@raredays/site-config": "^0.1.0",
-    "@raredays/skills": "^0.1.0",
-    "@raredays/theme-build": "^0.1.0",
-    "@raredays/typescript": "^0.1.0",
+    "@raredays/dev": "^0.2.0",
+    "@raredays/lint": "^0.2.2",
+    "@raredays/site-config": "^0.3.0",
+    "@raredays/skills": "^0.2.0",
+    "@raredays/theme-build": "^0.3.0",
+    "@raredays/typescript": "^0.3.0",
     "@tailwindcss/postcss": "4.2.4",
     "@types/node": "22.19.17",
     "@types/react": "19.2.14",
@@ -62,14 +62,14 @@
     "@storybook/react-vite": "10.3.6",
     "@tailwindcss/vite": "4.2.4",
     "@vitejs/plugin-react": "6.0.1",
-    "@vitest/coverage-v8": "4.1.5",
+    "@vitest/coverage-v8": "4.1.9",
     "drizzle-kit": "0.31.10",
     "happy-dom": "15.11.7",
     "storybook": "10.3.6",
     "tailwindcss": "4.2.4",
     "typescript": "5.9.3",
     "vite": "8.0.10",
-    "vitest": "4.1.5"
+    "vitest": "4.1.9"
   },
   "engines": {
     "node": ">=24"

package/templates/static/app/theme.override.css

@@ -1,5 +1,7 @@
-/*
- * Auto-generated by @raredays/theme-build. Do not edit by hand.
+/**
+ * AUTO-GENERATED — DO NOT EDIT.
+ * Regenerated from site.spec.ts by `pnpm theme:build`.
+ * For per-app CSS overrides, edit app/globals.css instead.
  * Source: site.spec.ts
  * To regenerate: pnpm theme:build
  */

package/templates/static/package.json

@@ -22,9 +22,9 @@
     "check": "raredays check && tsc --noEmit"
   },
   "dependencies": {
-    "@raredays/components": "^0.1.0",
-    "@raredays/core": "^0.1.0",
-    "@raredays/style": "^0.1.0",
+    "@raredays/components": "^0.3.0",
+    "@raredays/core": "^0.3.0",
+    "@raredays/style": "^0.3.0",
     "lucide-react": "1.14.0",
     "next": "16.2.9",
     "react": "19.2.7",
@@ -32,12 +32,12 @@
   },
   "devDependencies": {
     "@atheory-ai/skillex": "0.7.2",
-    "@raredays/dev": "^0.1.0",
-    "@raredays/lint": "^0.1.0",
-    "@raredays/site-config": "^0.1.0",
-    "@raredays/skills": "^0.1.0",
-    "@raredays/theme-build": "^0.1.0",
-    "@raredays/typescript": "^0.1.0",
+    "@raredays/dev": "^0.2.0",
+    "@raredays/lint": "^0.2.2",
+    "@raredays/site-config": "^0.3.0",
+    "@raredays/skills": "^0.2.0",
+    "@raredays/theme-build": "^0.3.0",
+    "@raredays/typescript": "^0.3.0",
     "@storybook/react-vite": "10.3.6",
     "@tailwindcss/postcss": "4.2.4",
     "@tailwindcss/vite": "4.2.4",