@notionx/create-notionx-app 1.0.0

package/dist/templates/lib/site/config.ts.tmpl

@@ -0,0 +1,120 @@
+// Static fallback for the Notion-backed site settings.
+//
+// `getSiteSettings()` (in `./settings.ts`) reads from a dedicated
+// Notion data source, but every consumer in the project still uses
+// the `siteConfig` shape below. We keep two copies on purpose:
+//
+//   1. Notion is the editor surface — operators tweak site name /
+//      tagline / description / SEO / navigation / theme / footer
+//      there without redeploying.
+//   2. The values below are the *last-resort fallback* if Notion
+//      is unreachable or the data source is empty.
+//
+// If you only want the static copy (no Notion), delete
+// `lib/site/settings.ts` and the `siteSettingsSource` entry in
+// `lib/content/models.ts`, then point the pages at `siteConfig`
+// directly again. The repo is intentionally structured so that
+// removing Notion is a 3-line change.
+
+import { contentSources } from "../content/models.ts";
+
+export const fallbackSiteConfig = {
+  name: "{{projectName}}",
+  description:
+    "A Notion-powered site built on @notionx/core, running on Cloudflare Workers with D1, R2, and Cloudflare Images.",
+  tagline: "{{projectName}} on Notion and Cloudflare",
+  defaultLocale: "{{defaultLocale}}",
+  socialImageUrl:
+    "https://picsum.photos/seed/{{projectName}}-social/1200/630" as string | null,
+  ogImageUrl:
+    "https://picsum.photos/seed/{{projectName}}-social/1200/630" as string | null,
+  locales: {{supportedLocalesJson}},
+  seo: {
+    title: "{{projectName}}",
+    description:
+      "A Notion-powered site built on @notionx/core, running on Cloudflare Workers with D1, R2, and Cloudflare Images.",
+  },
+  navigation: {
+    main: [
+      {
+        label: "Home",
+        href: "/",
+        modelId: "home",
+      },
+      {
+        label: "About",
+        href: "/about",
+        modelId: "about",
+      },
+      {
+        label: "Blog",
+        href: "{{contentSourceListPath}}",
+        modelId: "{{contentSourceId}}",
+      },
+    ],
+    cta: null as { label: string; href: string } | null,
+    adminHref: "/login",
+  },
+  theme: {
+    primary: "slate" as
+      | "slate"
+      | "gray"
+      | "zinc"
+      | "red"
+      | "orange"
+      | "amber"
+      | "green"
+      | "blue",
+    accent: "blue" as
+      | "slate"
+      | "gray"
+      | "zinc"
+      | "red"
+      | "orange"
+      | "amber"
+      | "green"
+      | "blue",
+    font: "inter" as "inter" | "geist" | "system",
+  },
+  footer: {
+    columns: [
+      {
+        label: "Company",
+        items: [
+          { label: "Home", href: "/" },
+          { label: "About", href: "/about" },
+        ],
+      },
+      {
+        label: "Content",
+        items: [{ label: "Blog", href: "{{contentSourceListPath}}" }],
+      },
+      {
+        label: "Legal",
+        items: [{ label: "Privacy", href: "/privacy" }],
+      },
+    ] as Array<{
+      label: string;
+      items: Array<{ label: string; href: string }>;
+    }>,
+    social: [] as Array<{ label: string; href: string }>,
+    tagline: "{{projectName}} on Notion and Cloudflare",
+    copyright: `© ${new Date().getFullYear()} {{projectName}}`,
+  },
+  primarySourceId: "{{contentSourceId}}",
+  sources: contentSources,
+};
+
+export type SiteConfig = typeof fallbackSiteConfig;
+
+/**
+ * `siteConfig` is preserved as an alias for `fallbackSiteConfig` so
+ * existing imports (`import { siteConfig } from "@/lib/site/config"`)
+ * keep working. New code should prefer `getSiteSettings()` from
+ * `./settings.ts` for runtime values, and `fallbackSiteConfig` only
+ * when an async read is impossible (e.g. inside `generateMetadata`
+ * for routes that need a synchronous title). See
+ * `app/layout.tsx` for the async pattern.
+ */
+export const siteConfig: SiteConfig = fallbackSiteConfig;
+export default siteConfig;

package/dist/templates/lib/site/request-env.ts.tmpl

@@ -0,0 +1,71 @@
+// Per-request `env` accessor for deeply-nested helpers.
+//
+// In a Cloudflare Worker the `env` binding is only available as the
+// second argument to the `fetch` handler. To make it reachable from
+// arbitrary call sites (e.g. `getSiteSettings()` invoked from a
+// server component, an admin action, or a cron job), we thread it
+// through Node's `AsyncLocalStorage` — once per request.
+//
+// Lifecycle:
+//   - The worker entry in `worker/index.ts` calls
+//     `runWithRequestEnv(env, () => handler.fetch(...))` for every
+//     incoming request (and for any `scheduled` invocation).
+//   - Any code reachable from that handler can call
+//     `getRequestEnv()` to read back the current request's `env`,
+//     without having to plumb it down the call stack.
+//
+// Why not `getRequestContext()` from `cloudflare:workers`?
+//   - `cloudflare:workers` does NOT export `getRequestContext` at
+//     any current compatibility date. Importing it triggers a
+//     `Uncaught SyntaxError: ... does not provide an export named
+//     'getRequestContext'` at worker boot, which crashes the
+//     deploy. (Verified against `@cloudflare/workers-types`
+//     4.20260613.1 and workerd 2026-06-05.)
+//   - Even on a runtime that *did* export it, that helper does not
+//     surface the user `env` bindings — only the `ExecutionContext`.
+//     We need the full `env` so we can read `CONTENT_CACHE` and
+//     other KV namespaces.
+//
+// Why not vinext's `unified-request-context` shim?
+//   - It exposes a per-request context object, but its
+//     `executionContext` field is the Cloudflare `ExecutionContext`
+//     (waitUntil/passThroughOnException), not the `env` bindings.
+//   - Reaching in to attach `env` to vinext's internal context
+//     would couple us to vinext's private shape.
+//
+// `AsyncLocalStorage` requires the `nodejs_compat` compatibility
+// flag, which the scaffolder enables by default.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Shape of the Cloudflare `env` parameter as far as this project
+ * is concerned. The KV binding is the only one we read at
+ * runtime; other bindings (D1, R2, secrets) are accessed by the
+ * foundation worker directly and don't need ALS propagation.
+ */
+export interface RequestEnv {
+  CONTENT_CACHE?: KVNamespace;
+  // Extend as new runtime consumers need to read env outside the
+  // worker entry (e.g. cron-triggered helpers).
+}
+
+const _envStore = new AsyncLocalStorage<RequestEnv>();
+
+/**
+ * Run `fn` with `env` available to any `getRequestEnv()` call
+ * reachable from `fn`. Use this from the worker entry once per
+ * request, before delegating to vinext/foundation.
+ */
+export function runWithRequestEnv<T>(env: RequestEnv, fn: () => T): T {
+  return _envStore.run(env, fn);
+}
+
+/**
+ * Read the current request's `env`, or `undefined` when called
+ * outside a `runWithRequestEnv` scope (e.g. from a build script,
+ * test, or one-off CLI invocation).
+ */
+export function getRequestEnv(): RequestEnv | undefined {
+  return _envStore.getStore();
+}

package/dist/templates/lib/site/settings.fallback.ts.tmpl

@@ -0,0 +1,21 @@
+// Fallback site settings loader — used when the project opts out
+// of the Notion-backed `site-settings` data source
+// (`--no-site-settings` / `CREATE_NOTIONX_NO_SITE_SETTINGS=1`).
+//
+// Every function returns the hard-coded fallback from `./config.ts`
+// unchanged. The shape matches the Notion-backed loader so call
+// sites don't need to know which version is installed.
+
+import { fallbackSiteConfig, type SiteConfig } from "./config";
+
+export function getStaticSiteSettings(): SiteConfig {
+  return fallbackSiteConfig;
+}
+
+export async function getSiteSettings(): Promise<SiteConfig> {
+  return fallbackSiteConfig;
+}
+
+export async function invalidateSiteSettingsCache(): Promise<void> {
+  // No-op — there's no KV cache to clear in fallback mode.
+}

package/dist/templates/lib/site/settings.ts.tmpl

@@ -0,0 +1,320 @@
+// Notion-backed site settings loader.
+//
+// Reads the singleton row from the `site-settings` Notion data
+// source (declared in `lib/content/models.ts`) and merges it with
+// the static fallback in `./config.ts`. The result has the same
+// shape as `siteConfig` so call sites don't need to know which
+// source actually answered.
+//
+// Caching strategy:
+//   - One KV read per request. On miss, fetch from Notion, cache
+//     the merged result for 5 minutes, and return.
+//   - The first request after a Notion edit pays the Notion RTT
+//     (~150ms in our measurements); subsequent requests in the
+//     5-minute window are KV reads (~5ms).
+//
+// To invalidate early after editing Notion, you have two options:
+//   1. Wait up to 5 minutes (the default TTL).
+//   2. Hit `POST /api/admin/site-settings/revalidate` (mounted by
+//      the worker when an admin session is present) which clears
+//      the KV entry. The endpoint re-uses
+//      `@notionx/core/auth/routes/viewer` to authorize the caller.
+//
+// If the Notion data source is empty or the row can't be read,
+// `fallbackSiteConfig` from `./config.ts` is returned unchanged.
+// The fallback is also what `getStaticSiteSettings()` returns
+// synchronously — useful for places that can't `await` (e.g.
+// a `generateMetadata` shortcut that builds an error page).
+
+import { getRequestEnv } from "./request-env";
+import {
+  hasNotionModelConfig,
+  listGenericNotionContent,
+} from "@notionx/core/notion";
+import { siteSettingsSource } from "../content/models";
+import { fallbackSiteConfig, type SiteConfig } from "./config";
+
+const CACHE_KEY = "site-settings:v1";
+const CACHE_TTL_SECONDS = 5 * 60;
+
+/**
+ * Read the `CONTENT_CACHE` KV binding from the current request, if
+ * any. Returns `null` when called outside a request scope (build
+ * scripts, tests, one-off scripts) — callers must handle that and
+ * skip caching rather than throwing.
+ */
+function readKv(): KVNamespace | null {
+  return getRequestEnv()?.CONTENT_CACHE ?? null;
+}
+
+type RawNavItem = {
+  label: string;
+  href: string;
+  children?: RawNavItem[];
+};
+
+type RawSiteSettings = {
+  name?: string;
+  tagline?: string;
+  description?: string;
+  defaultLocale?: string;
+  socialImageUrl?: string;
+  ogImageUrl?: string;
+  seo?: { title?: string; description?: string };
+  navigation?: {
+    main?: RawNavItem[];
+    cta?: { label: string; href: string } | null;
+  };
+  theme?: { primary?: string; accent?: string; font?: string };
+  footer?: {
+    columns?: Array<{ label: string; items: Array<{ label: string; href: string }> }>;
+    social?: Array<{ label: string; href: string }>;
+    tagline?: string;
+    copyright?: string;
+  };
+};
+
+function readRichText(
+  properties: Record<string, unknown>,
+  field: string
+): string {
+  const prop = properties[field] as
+    | { rich_text?: Array<{ plain_text?: string }> }
+    | undefined;
+  if (!prop?.rich_text?.length) return "";
+  return prop.rich_text.map((t) => t.plain_text ?? "").join("").trim();
+}
+
+function readUrl(
+  properties: Record<string, unknown>,
+  field: string
+): string | null {
+  const prop = properties[field] as
+    | { url?: string | null }
+    | undefined;
+  return prop?.url ?? null;
+}
+
+function readSelect(
+  properties: Record<string, unknown>,
+  field: string
+): string {
+  const prop = properties[field] as
+    | { select?: { name?: string } | null }
+    | undefined;
+  return prop?.select?.name?.trim() ?? "";
+}
+
+function readJson<T>(
+  properties: Record<string, unknown>,
+  field: string,
+  fallback: T
+): T {
+  const raw = readRichText(properties, field);
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Synchronous build-time copy. Use this only when `await` is not
+ * possible (rare — prefer `getSiteSettings`). Returns the
+ * hard-coded fallback, no Notion I/O.
+ */
+export function getStaticSiteSettings(): SiteConfig {
+  return fallbackSiteConfig;
+}
+
+/**
+ * Resolve the current site settings.
+ *
+ * Order of precedence for each field:
+ *   1. Notion row (if `site-settings` data source is reachable and
+ *      contains a row)
+ *   2. `fallbackSiteConfig` (so a Notion outage never breaks the
+ *      home page or SEO metadata)
+ *
+ * The result is cached in `CONTENT_CACHE` (KV) under
+ * `site-settings:v1` for 5 minutes per process. Bump the cache key
+ * suffix to invalidate globally after a breaking schema change.
+ */
+export async function getSiteSettings(): Promise<SiteConfig> {
+  const kv = readKv();
+  if (kv) {
+    const cached = await kv.get<SiteConfig>(CACHE_KEY, "json");
+    if (cached) return cached;
+  }
+
+  const merged = await loadFromNotion();
+
+  if (kv) {
+    // Best-effort write. KV failure shouldn't break the page.
+    kv.put(CACHE_KEY, JSON.stringify(merged), {
+      expirationTtl: CACHE_TTL_SECONDS,
+    }).catch(() => {});
+  }
+
+  return merged;
+}
+
+async function loadFromNotion(): Promise<SiteConfig> {
+  // `hasNotionModelConfig` reads the env from the active request
+  // context. If Notion isn't configured we return the fallback
+  // untouched — never throw, so the home page can't 500 because of
+  // a CMS blip.
+  let configured = false;
+  try {
+    configured = await hasNotionModelConfig(siteSettingsSource);
+  } catch {
+    configured = false;
+  }
+  if (!configured) {
+    return fallbackSiteConfig;
+  }
+
+  let items: Awaited<
+    ReturnType<typeof listGenericNotionContent<typeof siteSettingsSource.source.fields>>
+  >;
+  try {
+    items = await listGenericNotionContent(siteSettingsSource);
+  } catch {
+    return fallbackSiteConfig;
+  }
+  if (!items.length) {
+    return fallbackSiteConfig;
+  }
+
+  // The first published row wins. If the operator has multiple
+  // rows they can pick the active one by checking `Published` in
+  // Notion; we deliberately don't try to be clever about which row
+  // is "active" beyond that to keep the model predictable.
+  const row = items[0];
+  if (!row) return fallbackSiteConfig;
+
+  const raw: RawSiteSettings = {
+    name: row.title || undefined,
+    tagline: row.properties.tagline
+      ? Array.isArray(row.properties.tagline)
+        ? row.properties.tagline[0]
+        : (row.properties.tagline as string)
+      : undefined,
+    description: row.description || undefined,
+    socialImageUrl: row.coverImage || undefined,
+  };
+
+  // The Notion mapper doesn't know about every field we expose
+  // (e.g. `defaultLocale` lives in a `Select` column). Read it
+  // straight off the raw Notion page object that
+  // `listGenericNotionContent` returns — its `properties` map
+  // includes everything Notion sent us, not just the mapped ones.
+  const extra = (row as unknown as { properties?: Record<string, unknown> })
+    .properties;
+  if (extra && typeof extra === "object") {
+    const defaultLocale = readSelect(extra, "Default Locale");
+    if (defaultLocale) raw.defaultLocale = defaultLocale;
+    const tagline = readRichText(extra, "Tagline");
+    if (tagline) raw.tagline = tagline;
+    const socialImage = readUrl(extra, "Social Image");
+    if (socialImage) raw.socialImageUrl = socialImage;
+
+    // SEO
+    const metaTitle = readRichText(extra, "Meta Title");
+    const metaDescription = readRichText(extra, "Meta Description");
+    if (metaTitle || metaDescription) {
+      raw.seo = {
+        title: metaTitle || raw.name,
+        description: metaDescription || raw.description,
+      };
+    }
+    const ogImage = readUrl(extra, "OG Image");
+    if (ogImage) raw.ogImageUrl = ogImage;
+
+    // Navigation
+    const nav = readJson<RawNavItem[]>(extra, "Nav", []);
+    const cta = readJson<{ label: string; href: string } | null>(
+      extra,
+      "Nav CTA",
+      null
+    );
+    raw.navigation = { main: nav, cta };
+
+    // Theme
+    const primary = readSelect(extra, "Primary Color");
+    const accent = readSelect(extra, "Accent Color");
+    const font = readSelect(extra, "Font Family");
+    if (primary || accent || font) {
+      raw.theme = { primary, accent, font };
+    }
+
+    // Footer
+    type FooterColumn = {
+      label: string;
+      items: Array<{ label: string; href: string }>;
+    };
+    const columns = readJson<FooterColumn[]>(extra, "Footer Columns", []);
+    const social = readJson<Array<{ label: string; href: string }>>(
+      extra,
+      "Footer Social Links",
+      []
+    );
+    const taglineFooter = readRichText(extra, "Footer Tagline");
+    const copyright = readRichText(extra, "Footer Copyright");
+    raw.footer = { columns, social, tagline: taglineFooter, copyright };
+  }
+
+  return {
+    ...fallbackSiteConfig,
+    name: raw.name?.trim() || fallbackSiteConfig.name,
+    tagline: raw.tagline?.trim() || raw.name?.trim() || fallbackSiteConfig.tagline,
+    description:
+      raw.description?.trim() || fallbackSiteConfig.description,
+    socialImageUrl: raw.socialImageUrl ?? fallbackSiteConfig.socialImageUrl,
+    ogImageUrl: raw.ogImageUrl ?? raw.socialImageUrl ?? fallbackSiteConfig.ogImageUrl,
+    defaultLocale:
+      raw.defaultLocale?.trim() || fallbackSiteConfig.defaultLocale,
+    seo: {
+      title: raw.seo?.title?.trim() || fallbackSiteConfig.seo.title,
+      description:
+        raw.seo?.description?.trim() || fallbackSiteConfig.seo.description,
+    },
+    navigation: {
+      ...fallbackSiteConfig.navigation,
+      main: raw.navigation?.main?.length
+        ? raw.navigation.main
+        : fallbackSiteConfig.navigation.main,
+      cta: raw.navigation?.cta ?? fallbackSiteConfig.navigation.cta,
+    },
+    theme: {
+      primary:
+        (raw.theme?.primary as SiteConfig["theme"]["primary"]) ??
+        fallbackSiteConfig.theme.primary,
+      accent:
+        (raw.theme?.accent as SiteConfig["theme"]["accent"]) ??
+        fallbackSiteConfig.theme.accent,
+      font:
+        (raw.theme?.font as SiteConfig["theme"]["font"]) ??
+        fallbackSiteConfig.theme.font,
+    },
+    footer: {
+      columns: raw.footer?.columns ?? fallbackSiteConfig.footer.columns,
+      social: raw.footer?.social ?? fallbackSiteConfig.footer.social,
+      tagline: raw.footer?.tagline ?? fallbackSiteConfig.footer.tagline,
+      copyright:
+        raw.footer?.copyright ?? fallbackSiteConfig.footer.copyright,
+    },
+  };
+}
+
+/**
+ * Drop the cached entry. Call this from a Notion webhook handler
+ * (or an admin "revalidate" button) so editors see their changes
+ * without waiting for the 5-minute TTL.
+ */
+export async function invalidateSiteSettingsCache(): Promise<void> {
+  const kv = readKv();
+  if (!kv) return;
+  await kv.delete(CACHE_KEY);
+}

package/dist/templates/lib/site/translations.ts.tmpl

@@ -0,0 +1,30 @@
+// Locale-aware site settings merge. The `site-settings` Notion row
+// holds the global config; the `site-settings-translations` row
+// holds locale-specific copy. Missing locale copy falls back to the
+// default-locale translation.
+
+import { i18n } from "@/lib/i18n";
+import { siteSettingsContract } from "@/lib/locale-contract";
+
+export type SiteSettingsTranslation = {
+  pageId: string;
+  sourcePageId: string;
+  locale: string;
+  tagline: string;
+  description: string;
+  seoTitle: string;
+  seoDescription: string;
+  navLabels: Record<string, string>;
+  footerLabels: Record<string, string>;
+  globalFallbackCopy: string;
+  published: boolean;
+};
+
+export function pickSiteSettingsTranslation(
+  rows: readonly SiteSettingsTranslation[],
+  locale: string
+) {
+  const direct = rows.find((row) => row.locale === locale);
+  if (direct) return direct;
+  return rows.find((row) => row.locale === i18n.defaultLocale) ?? null;
+}

package/dist/templates/lib/utils.ts.tmpl

@@ -0,0 +1,9 @@
+// shadcn/ui 标准的 cn() 工具：合并 className，去重 Tailwind 冲突类。
+// 不直接依赖 @notionx/core，避免在用户代码里制造隐式依赖。
+
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/dist/templates/migrations/0001_init.sql.tmpl

@@ -0,0 +1,57 @@
+-- Foundation auth schema. Mirrors the `users`, `app_settings`, and
+-- `auth_rate_limits` tables that `@notionx/core`'s `createAuth`,
+-- `getAuthViewer`, and `runSchemaHealthChecks` rely on. Run all
+-- statements with `wrangler d1 migrations apply <db-name>`; the
+-- generated project ships this file as `migrations/0001_init.sql`.
+
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT NOT NULL UNIQUE,
+  name TEXT,
+  picture TEXT,
+  google_sub TEXT UNIQUE,
+  password_hash TEXT,
+  email_verified INTEGER NOT NULL DEFAULT 0,
+  email_verify_token TEXT,
+  email_verify_expires_at TEXT,
+  password_reset_token TEXT,
+  password_reset_expires_at TEXT,
+  session_rev INTEGER NOT NULL DEFAULT 0,
+  role TEXT NOT NULL DEFAULT 'user',
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  last_seen_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);
+CREATE INDEX IF NOT EXISTS idx_users_google_sub ON users(google_sub);
+CREATE INDEX IF NOT EXISTS idx_users_email_verify_token
+  ON users(email_verify_token);
+CREATE INDEX IF NOT EXISTS idx_users_password_reset_token
+  ON users(password_reset_token);
+
+-- Single-row application settings table. The schema guard
+-- (`runSchemaHealthChecks` in @notionx/core) reads the
+-- `turnstile_enabled` column from this table to verify the schema.
+CREATE TABLE IF NOT EXISTS app_settings (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  site_title TEXT NOT NULL DEFAULT '{{projectName}}',
+  google_enabled INTEGER NOT NULL DEFAULT 0,
+  google_client_id TEXT,
+  google_client_secret TEXT,
+  google_updated_at TEXT,
+  turnstile_enabled INTEGER NOT NULL DEFAULT 0,
+  turnstile_site_key TEXT,
+  turnstile_updated_at TEXT,
+  admin_email TEXT NOT NULL DEFAULT '',
+  updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT OR IGNORE INTO app_settings (id) VALUES (1);
+
+-- Rate-limit buckets for auth flows. The scope column is a string
+-- key like `login:email:user@example.com` or `forgot:ip:1.2.3.4`.
+CREATE TABLE IF NOT EXISTS auth_rate_limits (
+  scope TEXT PRIMARY KEY,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  window_start INTEGER NOT NULL
+);

package/dist/templates/migrations/0002_admin_seed.sql.tmpl

@@ -0,0 +1,30 @@
+-- Bootstrap the admin user and link the configured admin_email to it.
+-- Rendered by `@notionx/create-notionx-app` with the PBKDF2-SHA256
+-- hash of the password collected at scaffold time. Idempotent: safe
+-- to re-run via `wrangler d1 migrations apply`.
+
+-- 1. Make sure the singleton `app_settings` row carries the admin
+--    email that the auth helpers (`isAdminEmail`) consult.
+UPDATE app_settings
+   SET admin_email = '{{adminEmail}}',
+       updated_at = datetime('now')
+ WHERE id = 1;
+
+-- 2. Insert (or refresh) the admin user. Re-runs are safe: the
+--    `users.email` UNIQUE index makes the ON CONFLICT clause take
+--    over and refresh the password hash + role instead of
+--    duplicating. The role is hard-set to 'admin' so the user passes
+--    role checks on the very first request.
+INSERT INTO users (email, name, password_hash, email_verified, role)
+  VALUES (
+    '{{adminEmail}}',
+    '{{adminName}}',
+    '{{adminPasswordHash}}',
+    1,
+    'admin'
+  )
+  ON CONFLICT(email) DO UPDATE SET
+    name           = excluded.name,
+    password_hash  = excluded.password_hash,
+    role           = 'admin',
+    email_verified = 1;

package/dist/templates/migrations/0003_search_index.sql.tmpl

@@ -0,0 +1,29 @@
+-- content_search_index: D1-backed text search index for content sources.
+-- Used by the D1SearchAdapter to answer /api/search queries via
+-- LIKE-based keyword matching. Each row represents one indexed
+-- content page, keyed by (model_id, route_id).
+--
+-- This migration is rendered only when the `search` feature module
+-- is installed (enableSearch = true). When search is removed, the
+-- table is NOT dropped — existing index data is preserved in case
+-- the user re-adds search later.
+
+CREATE TABLE IF NOT EXISTS content_search_index (
+  model_id TEXT NOT NULL,
+  page_id TEXT NOT NULL,
+  route_id TEXT NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  summary TEXT NOT NULL DEFAULT '',
+  body_text TEXT NOT NULL DEFAULT '',
+  facets TEXT NOT NULL DEFAULT '[]',
+  normalized_text TEXT NOT NULL DEFAULT '',
+  source_updated_at TEXT,
+  indexed_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (model_id, route_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_content_search_model
+  ON content_search_index (model_id);
+
+CREATE INDEX IF NOT EXISTS idx_content_search_indexed_at
+  ON content_search_index (indexed_at DESC);