create-smoodly-app 0.0.3 → 0.0.5

package/README.md

@@ -9,32 +9,43 @@ 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` +
+2. **Multilingual?** No (default) scaffolds one language. Yes asks for the
+   locales, comma-separated, the first being the default (`en, fi`), and
+   scaffolds the next-intl layout: the site under `app/[locale]/`, `i18n/`,
+   `proxy.ts`, translated URLs per locale. Flag: `--locales en,fi`.
+3. Where content lives: a **local Supabase stack** (`supabase init` +
    `supabase start` inside the app; needs the Supabase CLI and Docker; when
    another project holds the default `543xx` ports the new one moves to the
    next free block, `553xx` and so on, and says so) or a
    **hosted project** (URL, publishable key, secret key; then an offer to
    `supabase link --project-ref <ref>` + `supabase db push`, the ref taken
-   from the URL so the CLI never opens its project picker).
-3. The first editor: pick an existing Auth user or create one (email +
+   from the URL so the CLI never opens its project picker). The URL may be
+   pasted without `https://`; anything that is not an http(s) URL is refused
+   before any step runs. A custom domain has no ref, so the link is not
+   offered and the two commands are printed instead.
+4. The first editor: pick an existing Auth user or create one (email +
    password). The `editors` row is written with role `owner`.
    If `@` does not appear when you type it (macOS, `@` on Option+2 with the
    terminal's "Option as Meta" setting on), paste the address or pass
    `--editor-email`.
 
-Every prompt has a flag, so CI can run it: `--supabase local|hosted`, `--url`,
-`--publishable-key`, `--secret-key`, `--editor-email` (password from
+Every prompt has a flag, so CI can run it: `--supabase local|hosted`, `--locales`,
+`--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`.
+`templates/next/` and `templates/next-intl/` are both generated by
+`scripts/build-template.ts` from `examples/site` — the multilingual layout —
+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). The four single-language
+route files live in `variants/single/`, and two exact-line transforms turn
+the example's glue (locale config, `href`) into the single-language one; a
+drifted example fails the build rather than silently shipping stale copies.
+Both templates are 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
@@ -44,6 +55,30 @@ 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
 
+Walked 2026-09-06: both templates scaffolded against the repo's local stack
+in hosted mode, `tsc`, `next build` and `/admin` 200 for each; the
+multilingual one with `--locales en,de`.
+
+## Follow-ups (logged 2026-09-06)
+
+- **A non-interactive run without `--locales` needs `--yes`.** The
+  "Multilingual site?" prompt is asked whenever `--locales` is absent, and
+  with no TTY (a CI step, stdin at EOF) the CLI exits 13 having created
+  nothing — "Detected unsettled top-level await". CI's hosted-mode e2e step
+  hit this; both e2e steps now pass a flag that settles the question
+  (`--yes` for single-language, `--locales en,de` for the multilingual one).
+  A prompt that treated EOF as its default value would need no flag.
+- **The next-intl template inherits next-intl's `localeDetection`
+  default**, which redirects an unprefixed URL to the visitor's preferred
+  locale *keeping the source locale's slugs* — on a site with translated
+  slugs that redirect lands on a 404 (`/company/about-us` →
+  `/fi/company/about-us` for a Finnish browser). Recorded in
+  `examples/site/README.md` under "Multilingual (2026-09-06)". Fixed the
+  same day: `i18n/routing.ts` in the example — and so in the generated
+  `templates/next-intl` — sets `localeDetection: false`, so the English
+  URL stays English for a Finnish browser and the visitor picks a
+  language through the site's own switcher.
+
 ## Follow-ups (logged 2026-09-05)
 
 - Text prompts drop `@` when the terminal sends Option as Meta (macOS,
@@ -84,7 +119,13 @@ The CLI has no runtime dependency on `smoodly`.
   project sorts first (seen 2026-09-05 during the hosted run, caught before
   the push). Fixed 2026-09-05: `projectRef` (src/env.ts) takes the ref from
   the typed URL's first host label and the link step and every fallback
-  line pass it; a custom domain yields no ref and falls back to the picker.
+  line pass it. Seen again 2026-09-05 from the published 0.0.3: a URL typed
+  without `https://` gave no ref (the picker opened) and then failed
+  `ensureEditor` with supabase-js's "Invalid supabaseUrl". Fixed the same
+  day: `normalizeProjectUrl` (src/env.ts) adds the scheme and refuses
+  non-URLs at the prompt and for `--url`; a URL with no ref (custom domain)
+  never offers the link, and `run` throws rather than run a bare
+  `supabase link`.
 - 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

package/dist/index.js

@@ -7,6 +7,16 @@ import { fileURLToPath } from "node:url";
 
 // src/args.ts
 import { parseArgs } from "node:util";
+function parseLocales(input) {
+  const locales = input.split(",").map((s) => s.trim()).filter(Boolean);
+  if (locales.length < 2) throw new Error("--locales needs at least two, comma-separated (e.g. en,fi); a single-language site needs none.");
+  for (const l of locales) {
+    if (!/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(l)) throw new Error(`--locales: "${l}" is not a locale tag (en, fi, sv-SE, pt-BR).`);
+  }
+  const dup = locales.find((l, i) => locales.indexOf(l) !== i);
+  if (dup) throw new Error(`--locales lists "${dup}" twice.`);
+  return locales;
+}
 function parseFlags(argv) {
   const { values, positionals } = parseArgs({
     args: argv,
@@ -18,6 +28,7 @@ function parseFlags(argv) {
       "secret-key": { type: "string" },
       "editor-email": { type: "string" },
       "smoodly-dep": { type: "string" },
+      locales: { type: "string" },
       "skip-link": { type: "boolean", default: false },
       yes: { type: "boolean", short: "y", default: false },
       help: { type: "boolean", short: "h", default: false }
@@ -38,7 +49,8 @@ function parseFlags(argv) {
     skipLink: values["skip-link"] ?? false,
     yes: values.yes ?? false,
     help: values.help ?? false,
-    smoodlyDep: values["smoodly-dep"]
+    smoodlyDep: values["smoodly-dep"],
+    locales: values.locales === void 0 ? void 0 : parseLocales(values.locales)
   };
 }
 var HELP = `create-smoodly-app \u2014 a fresh Next.js site with Smoodly installed
@@ -47,6 +59,7 @@ Usage: npx create-smoodly-app [name] [options]
 
 Options:
   --supabase local|hosted   Where content lives (asked when omitted; local needs the Supabase CLI)
+  --locales <a,b,\u2026>         Multilingual: the locales, first is the default (scaffolds next-intl; omitted = one language)
   --url <url>               Hosted: the Supabase project URL
   --publishable-key <key>   Hosted: the anon / publishable key
   --secret-key <key>        Hosted: the service-role / secret key
@@ -135,6 +148,41 @@ async function isPortFree(port) {
 import * as p from "@clack/prompts";
 import { resolve } 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");
+}
+function normalizeProjectUrl(input) {
+  const raw = input.trim();
+  if (!raw) return null;
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`;
+  try {
+    const url = new URL(withScheme);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (!url.hostname) return null;
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+function projectRef(url) {
+  let host;
+  try {
+    host = new URL(url).hostname;
+  } catch {
+    return null;
+  }
+  const m = /^([a-z0-9]{20})\.supabase\.(co|in|red)$/.exec(host);
+  return m ? m[1] : null;
+}
+
 // src/scaffold.ts
 import { cp, readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -153,6 +201,8 @@ async function isEmptyOrMissing(dir) {
     throw e;
   }
 }
+var ROUTING_LOCALES = '  locales: ["en", "fi"],';
+var ROUTING_DEFAULT = '  defaultLocale: "en",';
 async function scaffold(opts) {
   await cp(opts.templateDir, opts.dir, { recursive: true });
   await rename(join(opts.dir, "_gitignore"), join(opts.dir, ".gitignore"));
@@ -161,6 +211,17 @@ async function scaffold(opts) {
   pkg.name = opts.name;
   if (opts.smoodlyDep) pkg.dependencies.smoodly = opts.smoodlyDep;
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+  if (opts.locales) {
+    const routingPath = join(opts.dir, "i18n/routing.ts");
+    const routing = await readFile(routingPath, "utf8");
+    if (!routing.includes(ROUTING_LOCALES) || !routing.includes(ROUTING_DEFAULT)) {
+      throw new Error("i18n/routing.ts in the template has drifted; expected the lines\n" + ROUTING_LOCALES + "\n" + ROUTING_DEFAULT);
+    }
+    await writeFile(
+      routingPath,
+      routing.replace(ROUTING_LOCALES, `  locales: [${opts.locales.map((l) => JSON.stringify(l)).join(", ")}],`).replace(ROUTING_DEFAULT, `  defaultLocale: ${JSON.stringify(opts.locales[0])},`)
+    );
+  }
 }
 
 // src/prompts.ts
@@ -184,6 +245,19 @@ async function resolveAnswers(flags2, ctx) {
   if (invalid) bail(invalid);
   const dir = resolve(ctx.cwd, name);
   if (!await isEmptyOrMissing(dir)) bail(`${dir} exists and is not empty.`);
+  const locales = flags2.locales ?? (flags2.yes ? void 0 : await answer(p.confirm({ message: "Multilingual site? (next-intl, translated URLs)", initialValue: false })) ? await answer(
+    p.text({
+      message: "Locales, comma-separated, the first is the default",
+      placeholder: "en, fi",
+      validate: (v) => {
+        try {
+          parseLocales(v ?? "");
+        } catch (e) {
+          return e instanceof Error ? e.message : String(e);
+        }
+      }
+    })
+  ).then(parseLocales) : void 0);
   const supabase = flags2.supabase ?? (flags2.yes ? "local" : await answer(
     p.select({
       message: "Where should content live?",
@@ -195,13 +269,26 @@ async function resolveAnswers(flags2, ctx) {
   ));
   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 };
+    return { name, dir, supabase, hasSupabaseCli: true, smoodlyDep: flags2.smoodlyDep, locales };
   }
-  const url = flags2.url ?? await answer(p.text({ message: "Supabase project URL", placeholder: "https://abcd.supabase.co" }));
+  const badUrl = "Supabase project URL must be an http(s) URL, like https://abcd.supabase.co";
+  const typedUrl = flags2.url ?? await answer(
+    p.text({
+      message: "Supabase project URL",
+      placeholder: "https://abcd.supabase.co",
+      validate: (v) => normalizeProjectUrl(v ?? "") ? void 0 : badUrl
+    })
+  );
+  const url = normalizeProjectUrl(typedUrl);
+  if (!url) throw new Error(`${badUrl} (got "${typedUrl}")`);
   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 };
+  const ref = projectRef(url);
+  if (ctx.hasSupabaseCli && !flags2.skipLink && !ref) {
+    p.log.warn(`No project ref in ${url}; skipping supabase link. Run \`supabase link --project-ref <project-ref>\` and \`supabase db push\` yourself.`);
+  }
+  const linkAndPush = !ctx.hasSupabaseCli ? false : flags2.skipLink || !ref ? false : flags2.yes ? true : await answer(p.confirm({ message: `Link this app to the project and push the migration now? (supabase link --project-ref ${ref}, supabase db push)` }));
+  return { name, dir, supabase, hasSupabaseCli: ctx.hasSupabaseCli, hosted: { keys: { url, publishableKey, secretKey }, linkAndPush }, smoodlyDep: flags2.smoodlyDep, locales };
 }
 function askEditorWith(flags2, env = process.env) {
   return async (existing) => {
@@ -233,28 +320,6 @@ function askEditorWith(flags2, env = process.env) {
 // 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");
-}
-function projectRef(url) {
-  let host;
-  try {
-    host = new URL(url).hostname;
-  } catch {
-    return null;
-  }
-  const m = /^([a-z0-9]{20})\.supabase\.(co|in|red)$/.exec(host);
-  return m ? m[1] : null;
-}
-
 // src/plan.ts
 function plan(a) {
   if (a.supabase === "local" && !a.hasSupabaseCli) {
@@ -328,7 +393,13 @@ async function run(answers2, deps) {
     try {
       switch (step) {
         case "copyTemplate":
-          await deps.fs.scaffold({ templateDir: deps.templateDir, dir: cwd, name: answers2.name, smoodlyDep: answers2.smoodlyDep });
+          await deps.fs.scaffold({
+            templateDir: answers2.locales ? deps.templateDirs.intl : deps.templateDirs.single,
+            dir: cwd,
+            name: answers2.name,
+            smoodlyDep: answers2.smoodlyDep,
+            locales: answers2.locales
+          });
           break;
         case "install":
           deps.log("Installing dependencies\u2026");
@@ -415,15 +486,21 @@ ${renderEnv(keys).split("\n").filter((l) => !l.startsWith("#")).join("\n").trimE
   }
 }
 function linkArgs(answers2) {
-  const ref = answers2.hosted ? projectRef(answers2.hosted.keys.url) : null;
-  return ref ? ["link", "--project-ref", ref] : ["link"];
+  const url = answers2.hosted?.keys.url ?? "";
+  const ref = projectRef(url);
+  if (!ref) throw new Error(`no project ref in ${url}; run \`supabase link --project-ref <project-ref>\` yourself`);
+  return ["link", "--project-ref", ref];
 }
 function linkCommand(answers2) {
-  return `supabase ${linkArgs(answers2).join(" ")}`;
+  const ref = answers2.hosted ? projectRef(answers2.hosted.keys.url) : null;
+  return `supabase link --project-ref ${ref ?? "<project-ref>"}`;
 }
 
 // src/index.ts
-var TEMPLATE_DIR = fileURLToPath(new URL("../templates/next/", import.meta.url));
+var TEMPLATE_DIRS = {
+  single: fileURLToPath(new URL("../templates/next/", import.meta.url)),
+  intl: fileURLToPath(new URL("../templates/next-intl/", import.meta.url))
+};
 var flags;
 try {
   flags = parseFlags(process.argv.slice(2));
@@ -444,7 +521,7 @@ try {
   answers = await resolveAnswers(flags, { hasSupabaseCli, cwd: process.cwd() });
   outcome = await run(answers, {
     exec,
-    templateDir: TEMPLATE_DIR,
+    templateDirs: TEMPLATE_DIRS,
     editorClient: supabaseEditorClient,
     askEditor: askEditorWith(flags),
     log: (line) => p2.log.step(line),
@@ -467,7 +544,15 @@ if (!outcome.ok) {
   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"),
+  [
+    `cd ${answers.name}`,
+    "npm run dev",
+    "",
+    "Site:  http://localhost:3000",
+    "Admin: http://localhost:3000/admin",
+    `Editor: ${outcome.editor.email ?? outcome.editor.id}`,
+    ...answers.locales ? [`Locales: ${answers.locales.join(", ")} (i18n/routing.ts)`] : []
+  ].join("\n"),
   "Ready"
 );
 p2.outro("Happy editing.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-smoodly-app",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "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": {

package/templates/next/README.md

@@ -7,11 +7,12 @@ mounted at `/admin` from the `smoodly` package.
 
 ## 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.
+- `app/page.tsx` — the home page: one line calling renderSmoodlyPath([]).
+- `app/[...path]/page.tsx` — every other page and every collection entry, at any depth.
+- `components/pages/` — the page shapes and entry pages: schema + view, one file each.
+- `components/sections/` — the building blocks editors compose with. Add one, list it in `smoodly/sections.ts`.
+- `smoodly/collections.ts` — structured content (people, articles). Add a collection, then add its view to a new migration with `collectionSQL` from `smoodly`.
+- `smoodly/` — the wiring: `config.ts` (the registry and settings), `collections.ts`, `sections.ts`, `server.ts` (stores, site layer, renderer), `ops.ts` (the admin's one server action), `admin.tsx` (the admin mount).
 - `.env.local` — `SMOODLY_URL`, `SMOODLY_SECRET_KEY`, `SMOODLY_PUBLISHABLE_KEY`.
 
 ## Editors

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

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

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

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

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

@@ -0,0 +1,15 @@
+import { renderSmoodlyPath, smoodlyMetadata } from "@/smoodly/server";
+
+type Params = Promise<{ path: string[] }>;
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+// Smoodly: everything else — pages at any depth and collection entries
+// under their `path`. Add app/<segment>/page.tsx beside this file and it
+// wins for that exact path; deeper paths still resolve here.
+export async function generateMetadata({ params }: { params: Params }) {
+  return smoodlyMetadata((await params).path);
+}
+
+export default async function Page({ params, searchParams }: { params: Params; searchParams: SearchParams }) {
+  return renderSmoodlyPath((await params).path, { searchParams });
+}

package/templates/next/app/page.tsx

@@ -1,48 +1,11 @@
-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";
+import { renderSmoodlyPath, smoodlyMetadata } from "@/smoodly/server";
 
 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);
+// Smoodly: the home page. Editing this file replaces or wraps the CMS
+// home; the shapes it can render live in components/pages/.
+export const generateMetadata = () => smoodlyMetadata([]);
 
 export default async function Page({ searchParams }: { searchParams: SearchParams }) {
-  return renderSmoodlyPage(HomePage, { searchParams });
+  return renderSmoodlyPath([], { searchParams });
 }

package/templates/next/components/pages/Article.tsx

@@ -0,0 +1,15 @@
+import { smoodly } from "smoodly";
+import { articles } from "@/smoodly/collections";
+
+// The entry page for `articles`, served at the collection's `path`
+// (/posts/<slug>). Fields only; refs arrive resolved (author is a person).
+export const ArticlePage = smoodly.entryPage(articles, ({ entry, path }) => {
+  const a = entry.fields as { title: string; excerpt?: string; author?: { name: string; role?: string } | null };
+  return (
+    <article data-path={path}>
+      <h1>{a.title}</h1>
+      {a.author && <p>By {a.author.name}{a.author.role ? `, ${a.author.role}` : ""}</p>}
+      {a.excerpt && <p>{a.excerpt}</p>}
+    </article>
+  );
+});

package/templates/next/components/pages/Home.tsx

@@ -0,0 +1,35 @@
+import { smoodly, z, Zone, type Props } from "smoodly";
+import { Hero } from "../sections/Hero";
+import { ArticleList } from "../sections/ArticleList";
+import { CtaBanner } from "../sections/CtaBanner";
+
+// A page shape: zones declared, <Zone /> placed, one file (DESIGN.md §3).
+// `slug` makes it fixed — one record the editor can neither delete nor
+// duplicate — and the config's homePageSlug maps that record to "/".
+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);

package/templates/next/components/pages/Page.tsx

@@ -0,0 +1,40 @@
+import Link from "next/link";
+import { smoodly, z, Zone, type Props } from "smoodly";
+import { Hero } from "../sections/Hero";
+import { ArticleList } from "../sections/ArticleList";
+import { CtaBanner } from "../sections/CtaBanner";
+
+// Open registration: editors create as many of these as they like, at
+// any depth the config allows. `page` is where this one sits in the tree.
+export const pageSchema = smoodly.schema.page({
+  name: "page",
+  title: "Page",
+  zones: {
+    hero: z.sections([Hero]).max(1),
+    body: z.freeform({ sections: [ArticleList] }),
+    prefooter: z.locked(CtaBanner),
+  },
+  meta: { seo: true },
+});
+
+function PageView({ zones, page }: Props<typeof pageSchema>) {
+  return (
+    <>
+      {page.ancestors.length > 0 && (
+        // `url` is the ancestor's site URL through the app's href seam
+        // (/fi/yritys under next-intl); `path` would be the bare CMS path.
+        <nav aria-label="Breadcrumb">
+          {page.ancestors.map((a) => (
+            <span key={a.path}>{a.hasPage ? <Link href={a.url}>{a.title}</Link> : a.title} / </span>
+          ))}
+          {page.title}
+        </nav>
+      )}
+      <Zone of={zones.hero} />
+      <Zone of={zones.body} />
+      <Zone of={zones.prefooter} />
+    </>
+  );
+}
+
+export const StandardPage = smoodly.page(pageSchema, PageView);

package/templates/next/components/sections/ArticleList.tsx

@@ -1,5 +1,5 @@
 import { f, smoodly, type Props } from "smoodly";
-import { articles } from "../../collections";
+import { articles } from "@/smoodly/collections";
 
 export const articleListSchema = smoodly.schema.section({
   name: "articleList",

package/templates/next/package.json

@@ -9,11 +9,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@supabase/supabase-js": "^2.113.0",
     "next": "^16.3.4",
     "react": "^19",
     "react-dom": "^19",
-    "@supabase/supabase-js": "^2.113.0",
-    "smoodly": "0.0.3"
+    "smoodly": "0.0.5"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",

package/templates/next/smoodly/admin.tsx

@@ -0,0 +1,6 @@
+import { createSmoodlyAdmin } from "smoodly/admin/next";
+import { config } from "./config";
+import { smoodlyOp } from "./ops";
+import { publicAuth } from "./server";
+
+export const { AdminPage, AdminLayout } = createSmoodlyAdmin({ config, op: smoodlyOp, auth: publicAuth });

package/templates/next/smoodly/collections.ts

@@ -0,0 +1,26 @@
+import { f, smoodly } from "smoodly";
+
+export const people = smoodly.collection({
+  name: "people",
+  title: "People",
+  titleField: "name",
+  fields: {
+    name: f.text(),
+    role: f.text().optional(),
+  },
+});
+
+export const articles = smoodly.collection({
+  name: "articles",
+  title: "Articles",
+  titleField: "title",
+  path: "posts",
+  fields: {
+    title: f.text(),
+    slug: f.slug({ from: "title" }),
+    excerpt: f.text().optional(),
+    author: f.ref(() => people),
+  },
+});
+
+export const collections = [people, articles];

package/templates/next/smoodly/config.ts

@@ -0,0 +1,27 @@
+import { defineConfig, f } from "smoodly";
+import { collections } from "./collections";
+import { sections } from "./sections";
+import { HomePage } from "@/components/pages/Home";
+import { StandardPage } from "@/components/pages/Page";
+import { ArticlePage } from "@/components/pages/Article";
+
+export { collections, sections };
+
+// The registry and the plain settings, one file. Runtime-free: nothing
+// here imports a route file or Next, so a script, the CLI's template
+// build and (later) the MCP server can load it outside the app.
+export const config = defineConfig({
+  registry: {
+    sections,
+    collections,
+    pages: [HomePage, StandardPage, ArticlePage],
+  },
+  locales: { default: "en", supported: ["en"] },
+  // Smoodly's own default, spelled out: the record the site root serves.
+  homePageSlug: "home",
+  // Nesting on: an editor can put pages three deep.
+  pages: { tree: { depth: 3 } },
+  styles: {
+    sections: { spacing: f.select(["sm", "md", "lg"]).default("md") },
+  },
+});

package/templates/next/smoodly/ops.ts

@@ -0,0 +1,11 @@
+"use server";
+// The app's entire write surface for the admin: ONE exported action,
+// gated by the editors table. ('use server' modules may only export
+// async functions — hence the shape.)
+import { createAdminOpHandler, type AdminOpCall } from "smoodly/admin/next";
+import { config } from "./config";
+import { adminAuth, href, stores } from "./server";
+
+export async function smoodlyOp(call: AdminOpCall) {
+  return createAdminOpHandler({ config, ...stores(), auth: adminAuth(), href })(call);
+}