create-smoodly-app 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laniakea Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# create-smoodly-app
+
+    npx create-smoodly-app my-site
+
+A fresh Next.js app with the Smoodly admin mounted at `/admin`, a Supabase
+project holding the schema, `.env.local` written, and a first editor who can
+sign in. Spec: `docs/superpowers/specs/2026-09-04-create-smoodly-app-design.md`.
+
+## What it asks
+
+1. Project name (also the positional argument).
+2. Where content lives: a **local Supabase stack** (`supabase init` +
+   `supabase start` inside the app; needs the Supabase CLI and Docker) or a
+   **hosted project** (URL, publishable key, secret key; then an offer to
+   `supabase link` + `supabase db push`).
+3. The first editor: pick an existing Auth user or create one (email +
+   password). The `editors` row is written with role `owner`.
+
+Every prompt has a flag, so CI can run it: `--supabase local|hosted`, `--url`,
+`--publishable-key`, `--secret-key`, `--editor-email` (password from
+`SMOODLY_EDITOR_PASSWORD`), `--skip-link`, `--yes`. `--help` lists them.
+A hidden `--smoodly-dep <spec>` overrides the `smoodly` dependency written into
+`package.json`; CI points it at the packed tarball.
+
+## How it is built
+
+`templates/next/` is generated by `scripts/build-template.ts` from
+`examples/site` — an allow-list of copied files plus a generated
+`package.json` (with `smoodly` pinned to this package's version), `tsconfig`,
+`next.config`, README and the one migration (`coreTablesSQL` + the starter
+collections' views). It is git-ignored and rebuilt by `npm run build`.
+
+`src/plan.ts` turns answers into steps; `src/run.ts` executes them with
+injected `exec`, fs and Supabase client so the sequence and every fallback
+message are unit-tested. `src/prompts.ts` is the only interactive code.
+The CLI has no runtime dependency on `smoodly`.
+
+    npm test          # unit tests (template build, planner, runner, editor)
+    npm run build     # template + esbuild bundle → dist/index.js
+
+## Follow-ups (logged 2026-09-04)
+
+- Windows: `exec` passes `shell: true` on win32 (needed for the `.cmd` shims)
+  but does not quote arguments, so a project name or path containing a space
+  or `&` breaks. Quote the args when the shell is on, or resolve the `.cmd`
+  path and drop `shell`. Untested on Windows.
+- Hosted mode has not been run against a real hosted Supabase project with a
+  new-format `sb_secret_` key; CI and the local smoke run both use legacy JWT
+  keys. One manual run before the first customer install.
+- `listUsers` reads one page of 200 Auth users when offering an existing user
+  to make the first editor. Fine for a fresh project, wrong for a populated one.
+- `supabase link` runs without `--project-ref`, so the CLI re-asks for the
+  project even though it is derivable from the URL already typed.
+- The `--yes` flag defaults to local mode; with the Supabase CLI absent that
+  stops with the install message rather than falling through to hosted.
+- Captured `exec` output is stdout only; stderr streams straight through, so
+  `git init` hints and the Supabase CLI's update notice appear between the
+  prompt lines.
+- CI never runs local mode, and never applies the template's migration to a
+  fresh database: the e2e uses hosted mode against a stack whose schema came
+  from the repo's own migration. Add a local-mode e2e step — the runner's stack
+  uses ports 643xx and a fresh `supabase init` defaults to 543xx, so both can
+  run at once.
+- The "Local" option is still offered in the select when the Supabase CLI is
+  absent, and only bails afterwards; the spec wants the check before the prompt.

package/dist/index.js

@@ -0,0 +1,402 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import * as p2 from "@clack/prompts";
+import { rm, writeFile as writeFile2 } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+// src/args.ts
+import { parseArgs } from "node:util";
+function parseFlags(argv) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      supabase: { type: "string" },
+      url: { type: "string" },
+      "publishable-key": { type: "string" },
+      "secret-key": { type: "string" },
+      "editor-email": { type: "string" },
+      "smoodly-dep": { type: "string" },
+      "skip-link": { type: "boolean", default: false },
+      yes: { type: "boolean", short: "y", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    }
+  });
+  if (positionals.length > 1) throw new Error("Only one project name is accepted.");
+  const supabase = values.supabase;
+  if (supabase !== void 0 && supabase !== "local" && supabase !== "hosted") {
+    throw new Error(`--supabase must be "local" or "hosted", got "${supabase}"`);
+  }
+  return {
+    name: positionals[0],
+    supabase,
+    url: values.url,
+    publishableKey: values["publishable-key"],
+    secretKey: values["secret-key"],
+    editorEmail: values["editor-email"],
+    skipLink: values["skip-link"] ?? false,
+    yes: values.yes ?? false,
+    help: values.help ?? false,
+    smoodlyDep: values["smoodly-dep"]
+  };
+}
+var HELP = `create-smoodly-app \u2014 a fresh Next.js site with Smoodly installed
+
+Usage: npx create-smoodly-app [name] [options]
+
+Options:
+  --supabase local|hosted   Where content lives (asked when omitted; local needs the Supabase CLI)
+  --url <url>               Hosted: the Supabase project URL
+  --publishable-key <key>   Hosted: the anon / publishable key
+  --secret-key <key>        Hosted: the service-role / secret key
+  --editor-email <email>    The first editor (password from SMOODLY_EDITOR_PASSWORD)
+  --skip-link               Hosted: do not run supabase link / db push
+  -y, --yes                 Accept every default
+  -h, --help                This text
+`;
+
+// src/editor.ts
+import { createClient } from "@supabase/supabase-js";
+async function ensureEditor(client, ask) {
+  const existing = await client.listUsers();
+  const choice = await ask(existing);
+  const user = choice.kind === "pick" ? choice.user : await client.createUser(choice.email, choice.password);
+  await client.upsertEditor(user.id);
+  return user;
+}
+function clientFor(keys) {
+  const secret = keys.secretKey.startsWith("sb_secret_");
+  return createClient(keys.url, secret ? keys.secretKey : keys.publishableKey, {
+    global: { headers: secret ? {} : { Authorization: `Bearer ${keys.secretKey}` } },
+    auth: { persistSession: false, autoRefreshToken: false }
+  });
+}
+function supabaseEditorClient(keys) {
+  const db = clientFor(keys);
+  const fail = (what, message) => new Error(`${what}: ${message}`);
+  return {
+    async listUsers() {
+      const res = await db.auth.admin.listUsers({ perPage: 200 });
+      if (res.error) throw fail("listing Auth users", res.error.message);
+      return res.data.users.map((u) => ({ id: u.id, email: u.email ?? null }));
+    },
+    async createUser(email, password2) {
+      const res = await db.auth.admin.createUser({ email, password: password2, email_confirm: true });
+      if (res.error) throw fail("creating the Auth user", res.error.message);
+      return { id: res.data.user.id, email: res.data.user.email ?? null };
+    },
+    async upsertEditor(userId) {
+      const res = await db.from("editors").upsert({ user_id: userId, role: "owner" }, { onConflict: "space_id,user_id" });
+      if (res.error) throw fail("inserting the editors row", res.error.message);
+    }
+  };
+}
+
+// src/exec.ts
+import { spawn } from "node:child_process";
+var exec = (cmd, args, opts) => new Promise((resolve2, reject) => {
+  const child = spawn(cmd, args, {
+    cwd: opts.cwd,
+    stdio: [opts.stdin ?? "inherit", opts.capture ? "pipe" : "inherit", "inherit"],
+    shell: process.platform === "win32"
+  });
+  let stdout = "";
+  child.stdout?.on("data", (chunk) => stdout += chunk);
+  child.on("error", reject);
+  child.on(
+    "close",
+    (code) => code === 0 ? resolve2({ stdout }) : reject(new Error(`\`${cmd} ${args.join(" ")}\` exited with code ${code}`))
+  );
+});
+async function hasCommand(cmd, run2, cwd) {
+  try {
+    await run2(cmd, ["--version"], { cwd, capture: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/prompts.ts
+import * as p from "@clack/prompts";
+import { resolve } from "node:path";
+
+// src/scaffold.ts
+import { cp, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+function validName(name) {
+  if (!name) return "The name is empty.";
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(name)) return "Use lowercase letters, digits, dots, dashes and underscores (it becomes the package name).";
+  return null;
+}
+async function isEmptyOrMissing(dir) {
+  try {
+    return (await readdir(dir)).length === 0;
+  } catch (e) {
+    const code = e.code;
+    if (code === "ENOENT") return true;
+    if (code === "ENOTDIR") return false;
+    throw e;
+  }
+}
+async function scaffold(opts) {
+  await cp(opts.templateDir, opts.dir, { recursive: true });
+  await rename(join(opts.dir, "_gitignore"), join(opts.dir, ".gitignore"));
+  const pkgPath = join(opts.dir, "package.json");
+  const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  pkg.name = opts.name;
+  if (opts.smoodlyDep) pkg.dependencies.smoodly = opts.smoodlyDep;
+  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+// src/prompts.ts
+function bail(message) {
+  p.cancel(message);
+  process.exit(1);
+}
+async function answer(value) {
+  const v = await value;
+  if (p.isCancel(v)) bail("Cancelled.");
+  return v;
+}
+async function answerOrThrow(value) {
+  const v = await value;
+  if (p.isCancel(v)) throw new Error("Cancelled.");
+  return v;
+}
+async function resolveAnswers(flags2, ctx) {
+  const name = flags2.name ?? await answer(p.text({ message: "Project name", placeholder: "my-site", validate: (v) => validName(v ?? "") ?? void 0 }));
+  const invalid = validName(name);
+  if (invalid) bail(invalid);
+  const dir = resolve(ctx.cwd, name);
+  if (!await isEmptyOrMissing(dir)) bail(`${dir} exists and is not empty.`);
+  const supabase = flags2.supabase ?? (flags2.yes ? "local" : await answer(
+    p.select({
+      message: "Where should content live?",
+      options: [
+        { value: "local", label: "Local Supabase stack", hint: "supabase start inside the new app; needs the Supabase CLI and Docker" },
+        { value: "hosted", label: "Hosted Supabase project", hint: "paste the project URL and keys" }
+      ]
+    })
+  ));
+  if (supabase === "local") {
+    if (!ctx.hasSupabaseCli) bail("Local mode needs the Supabase CLI: https://supabase.com/docs/guides/cli (brew install supabase/tap/supabase)");
+    return { name, dir, supabase, hasSupabaseCli: true, smoodlyDep: flags2.smoodlyDep };
+  }
+  const url = flags2.url ?? await answer(p.text({ message: "Supabase project URL", placeholder: "https://abcd.supabase.co" }));
+  const publishableKey = flags2.publishableKey ?? await answer(p.text({ message: "Publishable (anon) key" }));
+  const secretKey = flags2.secretKey ?? await answer(p.password({ message: "Secret (service role) key" }));
+  const linkAndPush = !ctx.hasSupabaseCli ? false : flags2.skipLink ? false : flags2.yes ? true : await answer(p.confirm({ message: "Link this app to the project and push the migration now? (supabase link, supabase db push)" }));
+  return { name, dir, supabase, hasSupabaseCli: ctx.hasSupabaseCli, hosted: { keys: { url, publishableKey, secretKey }, linkAndPush }, smoodlyDep: flags2.smoodlyDep };
+}
+function askEditorWith(flags2, env = process.env) {
+  return async (existing) => {
+    if (flags2.editorEmail) {
+      const found = existing.find((u) => u.email === flags2.editorEmail);
+      if (found) return { kind: "pick", user: found };
+      const password3 = env.SMOODLY_EDITOR_PASSWORD;
+      if (!password3) throw new Error(`Set SMOODLY_EDITOR_PASSWORD to create ${flags2.editorEmail}.`);
+      return { kind: "create", email: flags2.editorEmail, password: password3 };
+    }
+    if (existing.length > 0) {
+      const picked = await answerOrThrow(
+        p.select({
+          message: "Who is the first editor?",
+          options: [
+            ...existing.map((u) => ({ value: u.id, label: u.email ?? u.id })),
+            { value: "__new__", label: "Create a new user" }
+          ]
+        })
+      );
+      if (picked !== "__new__") return { kind: "pick", user: existing.find((u) => u.id === picked) };
+    }
+    const email = await answerOrThrow(p.text({ message: "Editor email", validate: (v) => v && v.includes("@") ? void 0 : "An email address" }));
+    const password2 = await answerOrThrow(p.password({ message: "Editor password", validate: (v) => v && v.length >= 8 ? void 0 : "At least 8 characters" }));
+    return { kind: "create", email, password: password2 };
+  };
+}
+
+// src/run.ts
+import { join as join2 } from "node:path";
+
+// src/env.ts
+function renderEnv(keys) {
+  return [
+    "# Smoodly, self-host: the content project's values. SMOODLY_AUTH_URL and",
+    "# SMOODLY_AUTH_KEY default to these two \u2014 leave them unset.",
+    `SMOODLY_URL=${keys.url}`,
+    `SMOODLY_SECRET_KEY=${keys.secretKey}`,
+    `SMOODLY_PUBLISHABLE_KEY=${keys.publishableKey}`,
+    ""
+  ].join("\n");
+}
+
+// src/plan.ts
+function plan(a) {
+  if (a.supabase === "local" && !a.hasSupabaseCli) {
+    throw new Error("Local mode needs the Supabase CLI: https://supabase.com/docs/guides/cli (brew install supabase/tap/supabase)");
+  }
+  const steps = ["copyTemplate", "install", "gitInit"];
+  if (a.supabase === "local") steps.push("supabaseLocal");
+  else if (a.hasSupabaseCli) {
+    steps.push("supabaseInit");
+    if (a.hosted?.linkAndPush) steps.push("linkAndPush");
+  }
+  steps.push("writeEnv", "ensureEditor", "finish");
+  return steps;
+}
+
+// src/supabase-cli.ts
+function parseStatusEnv(output) {
+  const vars = /* @__PURE__ */ new Map();
+  for (const line of output.split("\n")) {
+    const m = /^([A-Z_]+)=(?:"([^"]*)"|(.*))$/.exec(line.trim());
+    if (m) vars.set(m[1], m[2] ?? m[3]);
+  }
+  const url = vars.get("API_URL");
+  const publishableKey = vars.get("ANON_KEY");
+  const secretKey = vars.get("SERVICE_ROLE_KEY");
+  if (!url || !publishableKey || !secretKey) {
+    throw new Error("`supabase status -o env` did not report API_URL, ANON_KEY and SERVICE_ROLE_KEY");
+  }
+  return { url, publishableKey, secretKey };
+}
+
+// src/run.ts
+async function run(answers2, deps) {
+  if (answers2.supabase === "hosted" && !answers2.hosted) {
+    throw new Error("hosted answers need the project's keys");
+  }
+  if (!await deps.fs.isEmptyOrMissing(answers2.dir)) {
+    throw new Error(`${answers2.dir} exists and is not empty.`);
+  }
+  const steps = plan(answers2);
+  const ctx = { keys: answers2.hosted?.keys };
+  const cwd = answers2.dir;
+  const sh = (cmd, args, extra = {}) => deps.exec(cmd, args, { cwd, ...extra });
+  for (const step of steps) {
+    try {
+      switch (step) {
+        case "copyTemplate":
+          await deps.fs.scaffold({ templateDir: deps.templateDir, dir: cwd, name: answers2.name, smoodlyDep: answers2.smoodlyDep });
+          break;
+        case "install":
+          deps.log("Installing dependencies\u2026");
+          await sh("npm", ["install"]);
+          break;
+        case "gitInit":
+          await sh("git", ["init"], { capture: true });
+          await sh("git", ["add", "-A"], { capture: true });
+          await sh("git", ["commit", "-m", "Smoodly site"], { capture: true });
+          break;
+        case "supabaseLocal":
+          deps.log("Starting the local Supabase stack (first run pulls Docker images)\u2026");
+          await sh("supabase", ["init"], { stdin: "ignore" });
+          await sh("supabase", ["start"]);
+          ctx.keys = parseStatusEnv((await sh("supabase", ["status", "-o", "env"], { capture: true })).stdout);
+          break;
+        case "supabaseInit":
+          await sh("supabase", ["init"], { stdin: "ignore" });
+          break;
+        case "linkAndPush":
+          await sh("supabase", ["link"]);
+          await sh("supabase", ["db", "push"]);
+          break;
+        case "writeEnv":
+          await deps.fs.writeFile(join2(cwd, ".env.local"), renderEnv(ctx.keys));
+          break;
+        case "ensureEditor":
+          ctx.editor = await ensureEditor(deps.editorClient(ctx.keys), deps.askEditor);
+          break;
+        case "finish":
+          break;
+      }
+    } catch (e) {
+      const error = e instanceof Error ? e.message : String(e);
+      if (step === "copyTemplate" || step === "install") {
+        await deps.fs.rm(cwd);
+        return { ok: false, step, error, fallback: `Nothing was left behind. Fix the cause and run create-smoodly-app again.` };
+      }
+      if (step === "gitInit") {
+        deps.log(`Skipped the initial git commit (${error}). Commit when you like.`);
+        continue;
+      }
+      return { ok: false, step, error, fallback: fallbackFor(step, answers2, ctx.keys) };
+    }
+  }
+  return { ok: true, keys: ctx.keys, editor: ctx.editor };
+}
+function fallbackFor(step, answers2, keys) {
+  const envLines = keys ? `Write ${answers2.name}/.env.local:
+
+${renderEnv(keys).split("\n").filter((l) => !l.startsWith("#")).join("\n").trimEnd()}` : `Write ${answers2.name}/.env.local with SMOODLY_URL, SMOODLY_SECRET_KEY and SMOODLY_PUBLISHABLE_KEY (from \`supabase status\`).`;
+  const editorLines = [
+    "Create the first editor: add a user in Supabase Studio (Authentication \u2192 Users), then in the SQL editor:",
+    "",
+    "    insert into editors (user_id, role) values ('<the user id>', 'owner');"
+  ].join("\n");
+  switch (step) {
+    case "supabaseLocal":
+      return [`cd ${answers2.name} && supabase init && supabase start`, "", envLines, "", editorLines].join("\n");
+    case "supabaseInit": {
+      const commands = answers2.hosted?.linkAndPush ? [`cd ${answers2.name} && supabase init && supabase link && supabase db push`] : [`cd ${answers2.name} && supabase init`, "", "When you are ready: supabase link && supabase db push"];
+      return [...commands, "", envLines, "", editorLines].join("\n");
+    }
+    case "linkAndPush":
+      return [`cd ${answers2.name} && supabase link && supabase db push`, "", envLines, "", editorLines].join("\n");
+    case "writeEnv":
+      return [envLines, "", editorLines].join("\n");
+    case "ensureEditor":
+      return [
+        "If the editors table is missing, apply the migration first: `supabase db push` (hosted) or `supabase start` (local).",
+        "",
+        editorLines
+      ].join("\n");
+    default:
+      return "";
+  }
+}
+
+// src/index.ts
+var TEMPLATE_DIR = fileURLToPath(new URL("../templates/next/", import.meta.url));
+var flags;
+try {
+  flags = parseFlags(process.argv.slice(2));
+} catch (e) {
+  console.error(e instanceof Error ? e.message : String(e));
+  console.error(HELP);
+  process.exit(2);
+}
+if (flags.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+p2.intro("create-smoodly-app");
+var answers;
+var outcome;
+try {
+  const hasSupabaseCli = await hasCommand("supabase", exec, process.cwd());
+  answers = await resolveAnswers(flags, { hasSupabaseCli, cwd: process.cwd() });
+  outcome = await run(answers, {
+    exec,
+    templateDir: TEMPLATE_DIR,
+    editorClient: supabaseEditorClient,
+    askEditor: askEditorWith(flags),
+    log: (line) => p2.log.step(line),
+    fs: { isEmptyOrMissing, scaffold, writeFile: (path, text2) => writeFile2(path, text2), rm: (dir) => rm(dir, { recursive: true, force: true }) }
+  });
+} catch (e) {
+  p2.cancel(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}
+if (!outcome.ok) {
+  p2.log.error(`${outcome.step} failed: ${outcome.error}`);
+  if (outcome.fallback) p2.note(outcome.fallback, "Finish by hand");
+  process.exit(1);
+}
+p2.note(
+  [`cd ${answers.name}`, "npm run dev", "", "Site:  http://localhost:3000", "Admin: http://localhost:3000/admin", `Editor: ${outcome.editor.email ?? outcome.editor.id}`].join("\n"),
+  "Ready"
+);
+p2.outro("Happy editing.");

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-smoodly-app",
+  "version": "0.0.1",
+  "description": "Create a Smoodly site: a fresh Next.js app with the admin mounted, a Supabase schema, an env file and a first editor.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laniakea-studio/smoodly-cms.git",
+    "directory": "packages/create-smoodly-app"
+  },
+  "type": "module",
+  "bin": { "create-smoodly-app": "./dist/index.js" },
+  "files": ["dist", "templates"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "npm run build:template && npm run build:cli",
+    "build:template": "tsx scripts/build-template.ts",
+    "build:cli": "esbuild src/index.ts --bundle --packages=external --platform=node --format=esm --target=node20 --outfile=dist/index.js --banner:js='#!/usr/bin/env node'",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@supabase/supabase-js": "^2.113.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "@types/react": "^19",
+    "esbuild": "^0.28.2",
+    "tsx": "^4",
+    "typescript": "^5",
+    "vitest": "^3"
+  }
+}

package/templates/next/README.md

@@ -0,0 +1,31 @@
+# Smoodly site
+
+Created by `create-smoodly-app`. Content lives in Supabase; the admin is
+mounted at `/admin` from the `smoodly` package.
+
+    npm run dev          # http://localhost:3000 — /admin is the editor
+
+## Where things are
+
+- `app/page.tsx` — the home page: its zones and JSX, registered as the fixed slug `home`.
+- `app/[slug]/page.tsx` — every other page editors create.
+- `components/sections/` — the building blocks editors compose with. Add one, list it in `sections.ts`.
+- `collections.ts` — structured content (people, articles). Add a collection, then add its view to a new migration with `collectionSQL` from `smoodly`.
+- `lib/smoodly/` — the wiring: stores, the admin ops action, the admin mount.
+- `.env.local` — `SMOODLY_URL`, `SMOODLY_SECRET_KEY`, `SMOODLY_PUBLISHABLE_KEY`.
+
+## Editors
+
+Anyone who may open `/admin` is a Supabase Auth user with a row in the
+`editors` table. To add one: create the user in Supabase Studio
+(Authentication → Users), then in the SQL editor:
+
+    insert into editors (user_id, role) values ('<the user id>', 'editor');
+
+## Hosted Supabase
+
+    supabase init        # if the CLI has not been set up here yet
+    supabase link        # pick the project
+    supabase db push     # applies supabase/migrations/
+
+Then put the project's URL and keys in `.env.local`.

package/templates/next/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.next/
+.env.local
+next-env.d.ts
+*.tsbuildinfo

package/templates/next/app/(smoodly)/admin/[[...segments]]/page.tsx

@@ -0,0 +1 @@
+export { AdminPage as default } from "../../../../lib/smoodly/admin";

package/templates/next/app/(smoodly)/admin/layout.tsx

@@ -0,0 +1 @@
+export { AdminLayout as default } from "../../../lib/smoodly/admin";

package/templates/next/app/[slug]/page.tsx

@@ -0,0 +1,42 @@
+import { smoodly, z, Zone, type Props } from "smoodly";
+import { Hero } from "../../components/sections/Hero";
+import { ArticleList } from "../../components/sections/ArticleList";
+import { CtaBanner } from "../../components/sections/CtaBanner";
+import { renderSmoodlyPage, smoodlyMetadata } from "../../lib/smoodly";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+type Params = Promise<{ slug: string }>;
+
+// Open registration: editors create as many of these as they like, and
+// this one file serves all of them — at depth 1 only. Nested paths are
+// the catch-all's job (app/[...rest]).
+export const pageSchema = smoodly.schema.page({
+  name: "page",
+  title: "Page",
+  zones: {
+    hero: z.sections([Hero]).max(1),
+    body: z.freeform({ sections: [ArticleList] }),
+    // Locked: fields only. One CtaBanner, always there, never movable.
+    prefooter: z.locked(CtaBanner),
+  },
+  meta: { seo: true },
+});
+
+function PageView({ zones }: Props<typeof pageSchema>) {
+  return (
+    <>
+      <Zone of={zones.hero} />
+      <Zone of={zones.body} />
+      <Zone of={zones.prefooter} />
+    </>
+  );
+}
+
+export const StandardPage = smoodly.page(pageSchema, PageView);
+
+export const generateMetadata = async ({ params }: { params: Params }) =>
+  smoodlyMetadata(StandardPage, { slug: (await params).slug });
+
+export default async function Page({ params, searchParams }: { params: Params; searchParams: SearchParams }) {
+  return renderSmoodlyPage(StandardPage, { slug: (await params).slug, searchParams });
+}

package/templates/next/app/layout.tsx

@@ -0,0 +1,11 @@
+import type { ReactNode } from "react";
+
+export const metadata = { title: "Smoodly site" };
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}

package/templates/next/app/page.tsx

@@ -0,0 +1,48 @@
+import { smoodly, z, Zone, type Props } from "smoodly";
+import { Hero } from "../components/sections/Hero";
+import { ArticleList } from "../components/sections/ArticleList";
+import { CtaBanner } from "../components/sections/CtaBanner";
+import { renderSmoodlyPage, smoodlyMetadata } from "../lib/smoodly";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+// The simple strategy: this file IS the page. Zones, JSX and the route
+// live together; `slug` makes it a singleton the editor cannot delete or
+// duplicate. See docs/DESIGN.md §3.
+export const homeSchema = smoodly.schema.page({
+  name: "home",
+  title: "Home",
+  slug: "home",
+  zones: {
+    hero: z.sections([Hero]).max(1),
+    body: z.freeform({ sections: [ArticleList] }),
+    // Locked: fields only. One CtaBanner, always there, never movable.
+    prefooter: z.locked(CtaBanner),
+  },
+  meta: { seo: true },
+});
+
+function HomeView({ zones }: Props<typeof homeSchema>) {
+  return (
+    <>
+      <Zone of={zones.hero} />
+      <Zone of={zones.body} />
+      <Zone of={zones.prefooter} />
+      <footer>
+        <p>Hard-coded footer — owned by the developer, invisible to the editor.</p>
+      </footer>
+    </>
+  );
+}
+
+export const HomePage = smoodly.page(homeSchema, HomeView);
+
+// No `dynamic = "force-dynamic"` needed: renderSmoodlyPage and
+// smoodlyMetadata wait for a request themselves, so `next build` never
+// prerenders this route against the database.
+
+export const generateMetadata = () => smoodlyMetadata(HomePage);
+
+export default async function Page({ searchParams }: { searchParams: SearchParams }) {
+  return renderSmoodlyPage(HomePage, { searchParams });
+}