@web-my-money/studio-consumer 2.3.0 → 2.4.0

package/README.md

@@ -1,106 +1,111 @@
-# @web-my-money/studio-consumer
-
-Consumer-side integration for WMM Studio: content, analytics, attribution.
-
-This is a source-only workspace package — no build step, no `dist`. Consumers
-are Next.js apps that already transpile workspace and scoped packages, so
-publishing compiled output here would only add a compile-and-publish cycle
-for no gain.
-
-## Connect a site: one command (2.3.0)
-
-In Studio, open the site, Site settings, **Get the setup command**, then in the
-app's folder:
-
-```bash
-npx @web-my-money/studio-consumer init <code>
-```
-
-It checks the machine, installs this package, writes the routes, wraps
-`next.config` with `withStudio`, links Vercel and sets the env vars, opens Claude
-Code (the `onboard-site` skill shipped here) to wire the layout and choose the
-editable text, verifies, opens a pull request, waits for the deploy and asks
-Studio to sync. Rerun it after any stop; it resumes. `init --explain` shows the
-plan without changing anything.
-
-## Entry points
-
-- `@web-my-money/studio-consumer/analytics`
-- `@web-my-money/studio-consumer/content`
-- `@web-my-money/studio-consumer/attribution`
-- `@web-my-money/studio-consumer/headers`
-- `@web-my-money/studio-consumer/brand` (2.0.0)
-- `@web-my-money/studio-consumer/image` (2.1.0)
-- `@web-my-money/studio-consumer/next` (2.3.0): `withStudio(nextConfig)`
-
-Each entry point exports `PACKAGE_VERSION`, to prove at runtime that a consumer
-is resolving this package rather than a stale copy.
-
-## Brand (2.0.0, breaking)
-
-A site declares its brand theme in code. Every invalid input throws, and this
-runs while the root layout renders, so a site with no brand, a malformed theme
-id, or WMM's own theme fails its build instead of silently inheriting WMM's
-palette.
-
-```ts
-// lib/brand.ts — its own module: Next refuses unknown named exports from a layout file
-import { defineSiteBrand } from "@web-my-money/studio-consumer/brand";
-
-export const brand = defineSiteBrand({ theme: "acme", style: "flat" });
-```
-
-```tsx
-// app/layout.tsx
-import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";
-import { brand } from "@/lib/brand";
-
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return <html lang="en" {...brandRootAttributes(brand)}><body>{children}</body></html>;
-}
-```
-
-```ts
-// app/api/content/manifest/route.ts
-import { brand } from "@/lib/brand";
-
-export const GET = createManifestHandler(getManifest, brand);
-// No `export const dynamic` (2.3.0+): the handler waits for a real request, so the
-// manifest is always live, and cacheComponents apps refuse that export anyway.
-```
-
-`createManifestHandler` now REQUIRES the brand (the breaking change in 2.0.0), so
-Studio records the theme the site ships. Only a WMM site may use a WMM theme
-(`wmm`, `site`, `light`, `dark`), by passing `wmmSite: true`.
-
-## Image focal point (2.1.0)
-
-An image value edited in Studio can carry `focal: { x, y }` (0–1 from the
-top-left): where the subject is. Apply it so responsive crops keep the subject
-in frame. No focal point, or a malformed one, reads as the centre, which is the
-browser default, so existing images render exactly as before.
-
-```tsx
-import { focalObjectPosition } from "@web-my-money/studio-consumer/image";
-
-<img src={value.url} alt={value.alt.en} style={{ objectFit: "cover", objectPosition: focalObjectPosition(value) }} />
-```
-
-## Analytics collector (2.2.0)
-
-`createCollectHandler` only accepts posts from the site's own pages (`Sec-Fetch-Site`,
-falling back to `Origin`), and it decides each event's A/B arm on the server from the
-`wmm_vid` cookie. The browser's own `variant` is always discarded. Pass the content
-client's `getRunningExperiments` so the arm can be resolved:
-
-```ts
-export const POST = createCollectHandler({
-  siteKey: SITE_KEY,
-  ingestUrl: process.env.FUNNEL_INGEST_URL ?? "",
-  ingestKey: process.env.FUNNEL_INGEST_TOKEN ?? "",
-  getRunningExperiments: () => content.getRunningExperiments(),
-});
-```
-
-Without it, events carry no arm and the site stays out of any A/B comparison.
-
+# @web-my-money/studio-consumer
+
+Consumer-side integration for WMM Studio: content, analytics, attribution.
+
+This is a source-only workspace package — no build step, no `dist`. Consumers
+are Next.js apps that already transpile workspace and scoped packages, so
+publishing compiled output here would only add a compile-and-publish cycle
+for no gain.
+
+## Connect a site: one command (2.3.0; new sites 2.4.0)
+
+In Studio, open the site, Site settings, **Get the setup command**, then in the
+app's folder (or, for a brand-new site, in an empty folder):
+
+```bash
+npx @web-my-money/studio-consumer init <code>
+```
+
+It checks the machine, installs this package, writes the routes, wraps
+`next.config` with `withStudio`, links Vercel and sets the env vars, opens Claude
+Code (the `onboard-site` skill shipped here) to wire the layout and choose the
+editable text, verifies, opens a pull request, waits for the deploy and asks
+Studio to sync. Rerun it after any stop; it resumes. `init --explain` shows the
+plan without changing anything.
+
+In an empty folder (2.4.0) it first creates the client's private repository from
+`Web-My-Money/wmm-site-template`, pulls it in and puts the site's key and name in
+place of the template's markers; the Claude step then sets the client's colours
+and first copy instead of wiring a layout.
+
+## Entry points
+
+- `@web-my-money/studio-consumer/analytics`
+- `@web-my-money/studio-consumer/content`
+- `@web-my-money/studio-consumer/attribution`
+- `@web-my-money/studio-consumer/headers`
+- `@web-my-money/studio-consumer/brand` (2.0.0)
+- `@web-my-money/studio-consumer/image` (2.1.0)
+- `@web-my-money/studio-consumer/next` (2.3.0): `withStudio(nextConfig)`
+
+Each entry point exports `PACKAGE_VERSION`, to prove at runtime that a consumer
+is resolving this package rather than a stale copy.
+
+## Brand (2.0.0, breaking)
+
+A site declares its brand theme in code. Every invalid input throws, and this
+runs while the root layout renders, so a site with no brand, a malformed theme
+id, or WMM's own theme fails its build instead of silently inheriting WMM's
+palette.
+
+```ts
+// lib/brand.ts — its own module: Next refuses unknown named exports from a layout file
+import { defineSiteBrand } from "@web-my-money/studio-consumer/brand";
+
+export const brand = defineSiteBrand({ theme: "acme", style: "flat" });
+```
+
+```tsx
+// app/layout.tsx
+import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";
+import { brand } from "@/lib/brand";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang="en" {...brandRootAttributes(brand)}><body>{children}</body></html>;
+}
+```
+
+```ts
+// app/api/content/manifest/route.ts
+import { brand } from "@/lib/brand";
+
+export const GET = createManifestHandler(getManifest, brand);
+// No `export const dynamic` (2.3.0+): the handler waits for a real request, so the
+// manifest is always live, and cacheComponents apps refuse that export anyway.
+```
+
+`createManifestHandler` now REQUIRES the brand (the breaking change in 2.0.0), so
+Studio records the theme the site ships. Only a WMM site may use a WMM theme
+(`wmm`, `site`, `light`, `dark`), by passing `wmmSite: true`.
+
+## Image focal point (2.1.0)
+
+An image value edited in Studio can carry `focal: { x, y }` (0–1 from the
+top-left): where the subject is. Apply it so responsive crops keep the subject
+in frame. No focal point, or a malformed one, reads as the centre, which is the
+browser default, so existing images render exactly as before.
+
+```tsx
+import { focalObjectPosition } from "@web-my-money/studio-consumer/image";
+
+<img src={value.url} alt={value.alt.en} style={{ objectFit: "cover", objectPosition: focalObjectPosition(value) }} />
+```
+
+## Analytics collector (2.2.0)
+
+`createCollectHandler` only accepts posts from the site's own pages (`Sec-Fetch-Site`,
+falling back to `Origin`), and it decides each event's A/B arm on the server from the
+`wmm_vid` cookie. The browser's own `variant` is always discarded. Pass the content
+client's `getRunningExperiments` so the arm can be resolved:
+
+```ts
+export const POST = createCollectHandler({
+  siteKey: SITE_KEY,
+  ingestUrl: process.env.FUNNEL_INGEST_URL ?? "",
+  ingestKey: process.env.FUNNEL_INGEST_TOKEN ?? "",
+  getRunningExperiments: () => content.getRunningExperiments(),
+});
+```
+
+Without it, events carry no arm and the site stays out of any A/B comparison.
+

package/cli/claude-step.mjs

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 /**
- * Step 7 of `init`: the edits that need judgement on someone else's code (root
+ * Step 8 of `init`: the edits that need judgement on someone else's code (root
  * layout, proxy/middleware, which text is editable) are done by Claude Code, on
  * the developer's own subscription, through the `onboard-site` skill this
  * package ships. Each edit is shown and approved before it is written.

package/cli/init.mjs

@@ -9,6 +9,7 @@ import { preflight } from "./preflight.mjs";
 import { cliProvisioner } from "./provisioner.mjs";
 import { writeSiteFiles, wrapNextConfig } from "./writers.mjs";
 import { claudeStep } from "./claude-step.mjs";
+import { personalise, pullTemplateRepo, templateKeyProblem } from "./scaffold.mjs";
 
 /**
  * `npx @web-my-money/studio-consumer init <code>`: connect an existing Next.js
@@ -37,7 +38,7 @@ const POLL_TIMES = 60;
  *   cwd: string, ui: Ui, run: Runner, fetchImpl: Fetch, sleep: (ms: number) => Promise<void>,
  *   studioUrl: string, code: string | null, state: OnboardingState | null,
  *   provisioner: AnyProvisioner | null, provisionerScope?: string,
- *   injectedProvisioner: AnyProvisioner | null,
+ *   injectedProvisioner: AnyProvisioner | null, mode?: "new" | "existing",
  * }} Ctx
  */
 
@@ -48,7 +49,8 @@ const STEPS = [
     title: "Check your setup",
     why: "Makes sure Node, GitHub, Vercel and this app are ready before anything changes.",
     async run(ctx) {
-      await preflight({ cwd: ctx.cwd, run: ctx.run, ui: ctx.ui, resuming: ctx.state !== null });
+      const r = await preflight({ cwd: ctx.cwd, run: ctx.run, ui: ctx.ui, resuming: ctx.state !== null });
+      ctx.mode = r.mode;
     },
   },
   {
@@ -89,13 +91,61 @@ const STEPS = [
       ctx.ui.info(`Connected to ${ctx.state.siteName} (${ctx.state.siteKey}). Modules: ${ctx.state.modules.join(", ")}.`);
     },
   },
+  {
+    id: "create",
+    title: "Create the site from WMM's template",
+    why: "For a new site: makes the client's own repository from WMM's site template and puts it in this folder.",
+    async run(ctx) {
+      const s = need(ctx);
+      // Saved state wins over this run's preflight: once the template is checked
+      // out the folder looks like an existing app, but it still needs finishing.
+      if (ctx.mode !== "new" && s.mode !== "new") {
+        return ctx.ui.info("This is an existing app, so there is nothing to create.");
+      }
+      const problem = templateKeyProblem(s.siteKey);
+      if (problem) ctx.ui.stop(problem);
+      const repo = `Web-My-Money/${s.siteKey}`;
+      if (!s.repoCreated) {
+        const ok = await ctx.ui.confirm(`Create the private repository ${repo} from WMM's site template, in this folder?`);
+        if (!ok) ctx.ui.stop("A new site needs its repository. Run this again when you are ready.");
+        try {
+          await provisioner(ctx).createRepoFromTemplate(s.siteKey);
+          ctx.ui.info(`Created ${repo}.`);
+        } catch (e) {
+          if (!(e instanceof Error && /already exists/i.test(e.message))) throw e;
+          // Most often an earlier run created it and stopped before saving that.
+          const mine = await ctx.ui.confirm(
+            `${repo} already exists on GitHub. Is it this site's repository, made from WMM's template (for example by an earlier run of this command)? Pull it into this folder?`,
+          );
+          if (!mine) {
+            ctx.ui.stop(
+              `${repo} already exists, so this command will not create it again. If it is this site, clone it and run this command inside it.`,
+              `gh repo clone ${repo}`,
+            );
+          }
+        }
+        // Remembered at once: a rerun after a later stop must neither create
+        // the repository twice nor forget that this is a new site.
+        s.repoCreated = true;
+        s.mode = "new";
+        saveState(ctx.cwd, s);
+      }
+      const pulled = await pullTemplateRepo({ cwd: ctx.cwd, run: ctx.run, sleep: ctx.sleep, name: s.siteKey });
+      if (!pulled.ok) ctx.ui.stop(pulled.message, pulled.nextCommand);
+      const changed = await personalise({ cwd: ctx.cwd, run: ctx.run, siteKey: s.siteKey, siteName: s.siteName });
+      // The template's colours are scoped to the site key, so it is the theme.
+      s.mode = "new";
+      s.theme = s.siteKey;
+      ctx.ui.info(`Made the template ${s.siteName}'s (${changed.length} files).`);
+    },
+  },
   {
     id: "install",
     title: "Install the package",
     why: "Adds WMM Studio's package to this app.",
     async run(ctx) {
-      const r = await ctx.run("npm", ["install", "--install-links", "@web-my-money/studio-consumer@^2.3"], { cwd: ctx.cwd });
-      if (r.code !== 0) ctx.ui.stop("npm could not install the package.", "npm install --install-links @web-my-money/studio-consumer@^2.3");
+      const r = await ctx.run("npm", ["install", "--install-links", "@web-my-money/studio-consumer@^2.4"], { cwd: ctx.cwd });
+      if (r.code !== 0) ctx.ui.stop("npm could not install the package.", "npm install --install-links @web-my-money/studio-consumer@^2.4");
     },
   },
   {
@@ -104,7 +154,7 @@ const STEPS = [
     why: "Writes the small files Studio talks to, and lets Studio show this site inside its editor.",
     async run(ctx) {
       const s = need(ctx);
-      if (s.modules.includes("content")) {
+      if (s.modules.includes("content") && s.mode !== "new") {
         s.theme = await ctx.ui.ask(
           "Brand theme id for this site (the client's theme in WMM's design system)",
           s.theme ?? s.siteKey,

package/cli/preflight.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { isOwnGitignore } from "./state.mjs";
 
 /**
  * Step 1 of the onboarding command: check the machine and the app BEFORE
@@ -11,6 +12,9 @@ import path from "node:path";
 /** @typedef {import("./run.mjs").Runner} Runner */
 /** @typedef {import("./ui.mjs").Ui} Ui */
 
+/** Not content: git, a stopped run's progress, and files the operating system drops in folders. */
+const IGNORED = new Set([".git", ".wmm-onboarding", ".DS_Store", "Thumbs.db", "desktop.ini"]);
+
 /** @param {string} version */
 function majorOf(version) {
   const m = /(\d+)/.exec(version);
@@ -18,8 +22,11 @@ function majorOf(version) {
 }
 
 /**
+ * `new`: an empty folder, where the site is created from WMM's template.
+ * `existing`: a Next.js app, wired in place.
+ *
  * @param {{ cwd: string, run: Runner, ui: Ui, resuming?: boolean }} ctx
- * @returns {Promise<{ mode: "existing", nextMajor: number | null }>}
+ * @returns {Promise<{ mode: "new" | "existing", nextMajor: number | null }>}
  */
 export async function preflight({ cwd, run, ui, resuming = false }) {
   const node = majorOf(process.versions.node) ?? 0;
@@ -29,13 +36,16 @@ export async function preflight({ cwd, run, ui, resuming = false }) {
 
   const pkgPath = path.join(cwd, "package.json");
   if (!existsSync(pkgPath)) {
-    const entries = readdirSync(cwd).filter((f) => f !== ".git");
-    if (entries.length === 0) {
-      ui.stop(
-        "This folder is empty, so it would be a new site from WMM's template. That path opens once the template is upgraded to Next.js 16; for now, run this inside an existing Next.js app.",
-      );
+    // A stopped first run leaves its progress folder behind; that is still empty.
+    const entries = readdirSync(cwd).filter(
+      (f) => !IGNORED.has(f) && !(f === ".gitignore" && isOwnGitignore(cwd)),
+    );
+    if (entries.length > 0) {
+      ui.stop("Run this inside the app's folder (the one that has package.json), or in an empty folder to start a new site.");
     }
-    ui.stop("Run this inside the app's folder: the one that has package.json.");
+    // A new site: no app and no repository yet, only the accounts that create them.
+    await signedIn(cwd, run, ui);
+    return { mode: "new", nextMajor: null };
   }
 
   const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
@@ -49,13 +59,7 @@ export async function preflight({ cwd, run, ui, resuming = false }) {
     );
   }
 
-  const gh = await run("gh", ["auth", "status"], { cwd });
-  if (gh.code === 127) ui.stop("The GitHub CLI is not installed.", "Install it from https://cli.github.com");
-  if (gh.code !== 0) ui.stop("You are not signed in to GitHub.", "gh auth login");
-
-  const vercel = await run("vercel", ["whoami"], { cwd });
-  if (vercel.code === 127) ui.stop("The Vercel CLI is not installed.", "npm install -g vercel");
-  if (vercel.code !== 0) ui.stop("You are not signed in to Vercel.", "vercel login");
+  await signedIn(cwd, run, ui);
 
   const git = await run("git", ["status", "--porcelain"], { cwd });
   if (git.code !== 0) ui.stop("This folder is not a git repository yet.", "git init");
@@ -67,12 +71,33 @@ export async function preflight({ cwd, run, ui, resuming = false }) {
     );
   }
 
+  return { mode: "existing", nextMajor };
+}
+
+/**
+ * GitHub and Vercel sign-ins (the command acts through them), plus a warning
+ * when Claude Code is missing.
+ *
+ * @param {string} cwd
+ * @param {Runner} run
+ * @param {Ui} ui
+ */
+async function signedIn(cwd, run, ui) {
+  const git = await run("git", ["--version"], { cwd });
+  if (git.code === 127) ui.stop("Git is not installed.", "Install it from https://git-scm.com");
+
+  const gh = await run("gh", ["auth", "status"], { cwd });
+  if (gh.code === 127) ui.stop("The GitHub CLI is not installed.", "Install it from https://cli.github.com");
+  if (gh.code !== 0) ui.stop("You are not signed in to GitHub.", "gh auth login");
+
+  const vercel = await run("vercel", ["whoami"], { cwd });
+  if (vercel.code === 127) ui.stop("The Vercel CLI is not installed.", "npm install -g vercel");
+  if (vercel.code !== 0) ui.stop("You are not signed in to Vercel.", "vercel login");
+
   const claude = await run("claude", ["--version"], { cwd });
   if (claude.code !== 0) {
     ui.info(
-      "Heads up: Claude Code is not installed. You will need it at step 7, where it helps wire your layout and choose the editable text. Install: https://claude.com/claude-code",
+      "Heads up: Claude Code is not installed. You will need it later, where it helps wire your layout and choose the editable text. Install: https://claude.com/claude-code",
     );
   }
-
-  return { mode: "existing", nextMajor };
 }

package/cli/provisioner.mjs

@@ -48,14 +48,15 @@ export function cliProvisioner({ cwd, run, scope }) {
 
   return {
     async createRepoFromTemplate(name) {
+      // No --clone: it would clone into ./<name>, and this folder already holds
+      // the command's progress. The command pulls the repository in itself.
       await must("gh", [
         "repo",
         "create",
         `Web-My-Money/${name}`,
         "--private",
         "--template",
-        "Web-My-Money/wmm-app-template",
-        "--clone",
+        "Web-My-Money/wmm-site-template",
       ]);
     },
     async createRepoFromSource(name) {

package/cli/scaffold.mjs

@@ -0,0 +1,155 @@
+// @ts-check
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isOwnGitignore } from "./state.mjs";
+
+/**
+ * A new site from WMM's template (spec 2026-10-09 §3.2): pull the repository
+ * GitHub created from `Web-My-Money/wmm-site-template` into the developer's
+ * folder, then make it this site's.
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+
+/** The only two strings in the template that become this site's (see its README). */
+export const MARKERS = { key: "wmm-template-site", name: "WMM Template Site" };
+
+const FETCH_TRIES = 10;
+const FETCH_WAIT_MS = 3000;
+
+/**
+ * GitHub copies a template into the new repository in the background, so for a
+ * few seconds the repository has no `main`. That case is waited out; any other
+ * failure (usually git not signed in to GitHub) stops at once with the fix.
+ *
+ * @param {{ cwd: string, run: Runner, sleep: (ms: number) => Promise<void>, name: string }} ctx
+ * @returns {Promise<{ ok: true } | { ok: false, message: string, nextCommand?: string }>}
+ */
+export async function pullTemplateRepo({ cwd, run, sleep, name }) {
+  const url = `https://github.com/Web-My-Money/${name}.git`;
+  if (!existsSync(path.join(cwd, ".git"))) {
+    const init = await run("git", ["init", "-b", "main"], { cwd });
+    if (init.code !== 0) return { ok: false, message: `git could not start a repository here: ${lastLine(init)}` };
+  }
+  const origin = await run("git", ["remote", "get-url", "origin"], { cwd });
+  if (origin.code !== 0) {
+    const add = await run("git", ["remote", "add", "origin", url], { cwd });
+    if (add.code !== 0) return { ok: false, message: `git could not add the new repository: ${lastLine(add)}` };
+  } else {
+    // A folder already tied to some other repository would fetch the wrong one forever.
+    const current = origin.stdout.trim();
+    const ours = new RegExp(`github\\.com[/:]Web-My-Money/${name}(\\.git)?$`, "i");
+    if (!ours.test(current)) {
+      return {
+        ok: false,
+        message: `This folder's git remote points at ${current}, not at Web-My-Money/${name}. Point it at the new site's repository, then run this again.`,
+        nextCommand: `git remote set-url origin ${url}`,
+      };
+    }
+  }
+
+  for (let i = 0; i < FETCH_TRIES; i++) {
+    const r = await run("git", ["fetch", "origin", "main"], { cwd });
+    if (r.code === 0) {
+      // The progress file's one-line .gitignore would block checking out the
+      // template's own (which already ignores the progress folder).
+      if (isOwnGitignore(cwd)) rmSync(path.join(cwd, ".gitignore"));
+      const co = await run("git", ["checkout", "-B", "main", "origin/main"], { cwd });
+      if (co.code !== 0) return { ok: false, message: `git could not check out the new site: ${lastLine(co)}` };
+      return { ok: true };
+    }
+    if (!/couldn't find remote ref/i.test(r.stderr)) {
+      return {
+        ok: false,
+        message: `git could not download the new repository: ${lastLine(r)}. If git is not signed in to GitHub, this fixes it; then run this again.`,
+        nextCommand: "gh auth setup-git",
+      };
+    }
+    if (i < FETCH_TRIES - 1) await sleep(FETCH_WAIT_MS);
+  }
+  return { ok: false, message: "GitHub is still preparing the repository. Run this again in a minute; it continues from here." };
+}
+
+// The same rule and reserved ids as defineSiteBrand (src/brand/index.ts): in a
+// template site the key IS the theme id, so it must be a valid client theme.
+const THEME_ID = /^[a-z][a-z0-9-]{0,40}$/;
+const WMM_THEMES = ["wmm", "site", "light", "dark"];
+
+/**
+ * Why a site key cannot be used for a site made from the template, or null.
+ * Checked before anything is created, so a bad key never leaves a repository behind.
+ *
+ * @param {string} siteKey
+ * @returns {string | null}
+ */
+export function templateKeyProblem(siteKey) {
+  if (THEME_ID.test(siteKey) && !WMM_THEMES.includes(siteKey)) return null;
+  return `The site key "${siteKey}" cannot be used for a site made from WMM's template: it becomes the brand theme id, so it must start with a letter, use only lowercase letters, digits and dashes, be at most 41 characters, and not be one of ${WMM_THEMES.join(", ")}. Add the site again in Studio with a key like that.`;
+}
+
+/** @param {{ stdout: string, stderr: string }} r */
+function lastLine(r) {
+  return (r.stderr || r.stdout).trim().split(/\r?\n/).slice(-1)[0] ?? "";
+}
+
+/**
+ * Replace the template's markers in every tracked file, escaped for where they
+ * land, and swap the template's README for one about this site.
+ *
+ * @param {{ cwd: string, run: Runner, siteKey: string, siteName: string }} ctx
+ * @returns {Promise<string[]>} the files that changed
+ */
+export async function personalise({ cwd, run, siteKey, siteName }) {
+  const problem = templateKeyProblem(siteKey);
+  if (problem) throw new Error(problem);
+  const listed = await run("git", ["ls-files"], { cwd });
+  const files = listed.stdout.split(/\r?\n/).map((f) => f.trim()).filter(Boolean);
+
+  /** @type {string[]} */
+  const changed = [];
+  for (const rel of files) {
+    const abs = path.join(cwd, rel);
+    if (!existsSync(abs)) continue;
+    if (rel === "README.md") {
+      writeFileSync(abs, siteReadme(siteName));
+      changed.push(rel);
+      continue;
+    }
+    const body = readFileSync(abs, "utf8");
+    if (body.includes("\0")) continue; // binary
+    if (!body.includes(MARKERS.key) && !body.includes(MARKERS.name)) continue;
+    const next = body.replaceAll(MARKERS.key, siteKey).replaceAll(MARKERS.name, nameFor(rel, siteName));
+    writeFileSync(abs, next);
+    changed.push(rel);
+  }
+  return changed;
+}
+
+/**
+ * The display name, escaped for the file it lands in: inside a JSON or code
+ * string it must not end the string; inside a CSS comment it must not end the
+ * comment.
+ *
+ * @param {string} rel
+ * @param {string} name
+ */
+function nameFor(rel, name) {
+  if (/\.(json|[cm]?[jt]sx?)$/.test(rel)) return JSON.stringify(name).slice(1, -1);
+  if (rel.endsWith(".css")) return name.replaceAll("*/", "");
+  return name;
+}
+
+/** @param {string} name */
+function siteReadme(name) {
+  return `# ${name}
+
+${name}'s website, built from WMM's site template and connected to WMM Studio.
+
+- Copy: \`dictionaries/en.json\` and \`es.json\` (same keys in both).
+- Brand colours: \`app/client-theme.css\`.
+- What the client can edit in Studio: \`lib/content-manifest.ts\`.
+- Rules for working on this site: \`CLAUDE.md\`.
+
+Before every push: \`npm run verify\`.
+`;
+}

package/cli/state.mjs

@@ -10,12 +10,24 @@ import path from "node:path";
  * @typedef {{
  *   siteKey: string, siteName: string, studioUrl: string, manifestUrl: string,
  *   revalidateUrl: string, modules: string[], readyToken: string, done: string[],
- *   theme?: string, scope?: string, baseBranch?: string, siteHasKey?: boolean
+ *   theme?: string, scope?: string, baseBranch?: string, siteHasKey?: boolean,
+ *   mode?: "new" | "existing", repoCreated?: boolean
  * }} OnboardingState
  */
 
 const DIR = ".wmm-onboarding";
 
+/**
+ * True when `.gitignore` is the one-line file saveState wrote into a folder that
+ * had none: the command's own file, safe to treat as absent.
+ *
+ * @param {string} cwd
+ */
+export function isOwnGitignore(cwd) {
+  const file = path.join(cwd, ".gitignore");
+  return existsSync(file) && readFileSync(file, "utf8").trim() === `${DIR}/`;
+}
+
 /** @param {string} cwd @returns {OnboardingState | null} */
 export function loadState(cwd) {
   const file = path.join(cwd, DIR, "state.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-my-money/studio-consumer",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
   "license": "UNLICENSED",
   "repository": {

package/skills/onboard-site/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard-site
-description: Finish connecting this Next.js app to WMM Studio after `npx @web-my-money/studio-consumer init` has run. Wires the root layout and the proxy/middleware, then proposes which text should be editable in Studio and writes the content manifest once the developer approves. Use when the init command opens Claude Code on /onboard-site.
+description: Finish connecting this Next.js app to WMM Studio after `npx @web-my-money/studio-consumer init` has run. Wires the root layout and the proxy/middleware, then proposes which text should be editable in Studio and writes the content manifest once the developer approves. For a new site made from WMM's template, sets the client's colours and first copy instead. Use when the init command opens Claude Code on /onboard-site.
 ---
 
 # Finish connecting this app to WMM Studio
@@ -21,6 +21,35 @@ Read `.wmm-onboarding/state.json` first: it lists the modules this site uses
 (`content`, `analytics`, `forms`, `attribution`, `ab`, …). Skip anything for a module
 that is not listed.
 
+## 0. A new site from WMM's template (`"mode": "new"` in state.json)
+
+The site was just created from `Web-My-Money/wmm-site-template`, so sections 1 and 2 are
+already done: the layout (`app/[lang]/layout.tsx`) has the brand attributes, the editor
+overlay and analytics, and `proxy.ts` sets the visitor cookie. Check they are there, say so in
+one line, and skip to the client's details. Read `CLAUDE.md` for the site's rules.
+
+1. Ask the developer, one question at a time:
+   - the business name exactly as the client writes it, and one sentence on what they do and
+     for whom;
+   - the brand's primary and accent colours as hex codes (from the client's logo or brand
+     guide; "not yet" is a fine answer: leave the magenta placeholder and say so);
+   - which language visitors should land in by default (English or Spanish);
+   - where the main button should go (the client's booking calendar or form link), if known.
+2. Then propose, as one diff per file, and write only after a yes:
+   - `app/client-theme.css`: the colours (`--primary`, `--accent`, and a readable
+     `--primary-foreground`: white on a dark primary, near-black on a light one);
+   - `dictionaries/en.json` and `es.json`: `meta`, `hero` and `services` from what the
+     developer told you, in both languages (Spanish neutral, no regional slang). Keep every
+     key; the two files must keep identical keys;
+   - `lib/i18n.ts`: `DEFAULT_LOCALE`, only if it changes;
+   - the main button's link in `app/[lang]/page.tsx` (the `TODO` on the closing banner).
+3. **Never invent reviews, results, prices or credentials.** Leave the review placeholders
+   and the FAQ answers you do not know, and list them as "still needed from the client".
+4. Section 3 below is a review here, not a rebuild: `lib/content-manifest.ts` already makes
+   the home page's marketing text editable. Show the list of slots, ask whether anything should
+   be added or removed, and change it only on a yes.
+5. Go to section 4.
+
 ## 1. Root layout (`app/layout.tsx`, or the layout that renders `<html>`)
 
 - **Brand (content):** `import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";`

package/src/analytics/index.ts

@@ -1,5 +1,5 @@
 /** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.3.0";
+export const PACKAGE_VERSION = "2.4.0";
 
 export {
   resolveVariant,

package/src/attribution/index.ts

@@ -1,5 +1,5 @@
 /** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.3.0";
+export const PACKAGE_VERSION = "2.4.0";
 
 export {
   getAttribution,

package/src/brand/index.ts

@@ -16,7 +16,7 @@
  * Pure on purpose: no `server-only`, no Next imports, safe in any component.
  */
 
-export const PACKAGE_VERSION = "2.3.0";
+export const PACKAGE_VERSION = "2.4.0";
 
 /** Theme ids owned by WMM in the tokens package (themes.json `owner: "wmm"`). */
 export const WMM_THEMES = ["wmm", "site", "light", "dark"] as const;

package/src/content/index.ts

@@ -1,5 +1,5 @@
 /** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.3.0";
+export const PACKAGE_VERSION = "2.4.0";
 
 export {
   createContentClient,

package/src/image/index.ts

@@ -1,5 +1,5 @@
 /** Pure; safe in client components. */
-export const PACKAGE_VERSION = "2.3.0";
+export const PACKAGE_VERSION = "2.4.0";
 
 /**
  * CSS `object-position` for a Studio image value's focal point (spec §6.2).

package/src/next/index.d.mts

@@ -1,13 +1,13 @@
-// Hand-maintained alongside index.mjs.
-
-type HeaderRule = { source: string; headers: { key: string; value: string }[] };
-
-/**
- * Wrap a site's next.config so Studio can edit it: transpiles this package,
- * sets `frame-ancestors 'self' <studio>` (spliced into an existing CSP), and
- * refuses X-Frame-Options. Wrapping twice is the same as once.
- */
-export declare function withStudio<T extends object>(
-  config: T,
-  opts?: { studioOrigins?: string[] },
-): T & { transpilePackages: string[]; headers: () => Promise<HeaderRule[]> };
+// Hand-maintained alongside index.mjs.
+
+type HeaderRule = { source: string; headers: { key: string; value: string }[] };
+
+/**
+ * Wrap a site's next.config so Studio can edit it: transpiles this package,
+ * sets `frame-ancestors 'self' <studio>` (spliced into an existing CSP), and
+ * refuses X-Frame-Options. Wrapping twice is the same as once.
+ */
+export declare function withStudio<T extends object>(
+  config: T,
+  opts?: { studioOrigins?: string[] },
+): T & { transpilePackages: string[]; headers: () => Promise<HeaderRule[]> };