riverbankcms 0.2.0 → 0.2.2

package/dist/plan-2c4zVtlW.mjs

@@ -0,0 +1,2213 @@
+#!/usr/bin/env node
+import { K as parseSiteId, bt as ok, yt as err } from "./src-XEJYAKbQ.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/scaffold/package-contract.ts
+const LOCAL_PACKAGE_VENDOR_DIR = ".riverbank/local-packages";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseStableVersion(value) {
+	if (typeof value !== "string") return undefined;
+	const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(value);
+	if (!match) return undefined;
+	return {
+		major: Number(match[1]),
+		minor: Number(match[2]),
+		patch: Number(match[3])
+	};
+}
+/** Pure package-contract derivation from a parsed manifest. */
+function deriveGeneratedPackageRanges(manifest) {
+	if (!isRecord(manifest)) return {
+		ok: false,
+		error: { tag: "invalid_manifest_shape" }
+	};
+	const version = parseStableVersion(manifest.version);
+	if (!version) return {
+		ok: false,
+		error: {
+			tag: "invalid_cli_version",
+			value: manifest.version
+		}
+	};
+	const peerDependencies = manifest.peerDependencies;
+	const sdkRange = isRecord(peerDependencies) ? peerDependencies["@riverbankcms/sdk"] : undefined;
+	if (typeof sdkRange !== "string" || sdkRange.trim().length === 0) {
+		return {
+			ok: false,
+			error: {
+				tag: "invalid_cli_peer_range",
+				value: sdkRange
+			}
+		};
+	}
+	return {
+		ok: true,
+		value: {
+			sdk: sdkRange,
+			cli: `^${version.major}.${version.minor}.0`
+		}
+	};
+}
+/**
+* Find the nearest package root from a module or executable path. Walking
+* upward works for both the source tree and a packed npm install; it does not
+* rely on the repository's `scripts/` layout.
+*/
+function findPackageManifestPath(startPath = fileURLToPath(import.meta.url), fileExists = existsSync) {
+	let directory = dirname(startPath);
+	while (true) {
+		const candidate = join(directory, "package.json");
+		if (fileExists(candidate)) return candidate;
+		const parent = dirname(directory);
+		if (parent === directory || directory === parse(directory).root) return undefined;
+		directory = parent;
+	}
+}
+/** Effectful package-boundary load; all range derivation remains pure above. */
+function loadGeneratedPackageRanges(manifestPath = findPackageManifestPath()) {
+	if (!manifestPath) throw new Error("Cannot locate the riverbankcms package manifest.");
+	const parsed = deriveGeneratedPackageRanges(JSON.parse(readFileSync(manifestPath, "utf8")));
+	if (!parsed.ok) throw new Error(`Invalid riverbankcms package contract (${parsed.error.tag}).`);
+	return parsed.value;
+}
+
+//#endregion
+//#region src/scaffold/local-manifest.ts
+const DEFAULT_CONTENT_TYPES = {
+	withBlog: false,
+	withEvents: false,
+	withTestimonials: false,
+	withPortfolio: false
+};
+function parseProjectPath(value) {
+	if (typeof value !== "string" || value.length === 0 || value !== value.trim()) return undefined;
+	if (!isAbsolute(value) || value.includes("\0")) return undefined;
+	const normalized = resolve(value);
+	return normalized === parse(normalized).root ? undefined : normalized;
+}
+function parseFeatures(input) {
+	const preview = input.preview;
+	const portal = input.portal;
+	if (preview !== "enabled" && preview !== "disabled") return undefined;
+	if (portal !== "enabled" && portal !== "disabled") return undefined;
+	const contentTypesValue = input.contentTypes;
+	if (contentTypesValue === undefined) {
+		return {
+			preview,
+			portal,
+			contentTypes: DEFAULT_CONTENT_TYPES
+		};
+	}
+	if (typeof contentTypesValue !== "object" || contentTypesValue === null || Array.isArray(contentTypesValue)) return undefined;
+	const value = contentTypesValue;
+	const contentTypes = {
+		withBlog: value.withBlog === true,
+		withEvents: value.withEvents === true,
+		withTestimonials: value.withTestimonials === true,
+		withPortfolio: value.withPortfolio === true
+	};
+	const known = Object.keys(value);
+	if (known.some((key) => !Object.keys(DEFAULT_CONTENT_TYPES).includes(key) || typeof value[key] !== "boolean")) return undefined;
+	return {
+		preview,
+		portal,
+		contentTypes
+	};
+}
+/**
+* Derive only local target state. This boundary can run before a remote site
+* is created because it does not depend on site identity or dashboard data.
+*/
+function deriveScaffoldLocalManifest(input) {
+	const projectPath = parseProjectPath(input.projectPath);
+	if (!projectPath) return err({
+		tag: "invalid_project_path",
+		value: input.projectPath
+	});
+	const features = parseFeatures(input.features);
+	if (!features) return err({
+		tag: "invalid_features",
+		field: "features"
+	});
+	return ok(Object.freeze({
+		projectPath,
+		features: Object.freeze({
+			...features,
+			contentTypes: Object.freeze({ ...features.contentTypes })
+		})
+	}));
+}
+
+//#endregion
+//#region src/scaffold/writer.ts
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/**
+* The single post-link completion authority used by fresh and resumed
+* scaffolds. Keeping it here prevents init from growing a second docs/build
+* implementation with subtly different ordering or error mapping.
+*/
+function createScaffoldCompletion(projectPath, process) {
+	return async () => {
+		try {
+			await process.initializeDocs(projectPath);
+		} catch (error) {
+			return {
+				ok: false,
+				error: {
+					tag: "docs_initialization_failed",
+					message: errorMessage(error)
+				}
+			};
+		}
+		try {
+			await process.verifyBuild(projectPath);
+		} catch (error) {
+			return {
+				ok: false,
+				error: {
+					tag: "build_verification_failed",
+					message: errorMessage(error)
+				}
+			};
+		}
+		return { ok: true };
+	};
+}
+/**
+* Read every target before the first write/process effect. A missing project
+* root is valid when missing or empty; create-next-app is therefore the only
+* process effect allowed to populate a clean target before canonical writes.
+*/
+function preflightScaffoldPlan(plan, filesystem) {
+	return preflightScaffoldTargets(plan, filesystem);
+}
+/** Preflight the local project target before any site-creation/process effect. */
+function preflightScaffoldTargets(manifest, filesystem) {
+	let rootState;
+	try {
+		rootState = filesystem.inspect(manifest.projectPath);
+	} catch (error) {
+		return {
+			tag: "path_inspection_failed",
+			path: manifest.projectPath,
+			message: errorMessage(error)
+		};
+	}
+	if (rootState !== "missing" && rootState !== "directory") {
+		return {
+			tag: "project_target_occupied",
+			path: manifest.projectPath,
+			state: rootState
+		};
+	}
+	if (rootState === "directory") {
+		let entries;
+		try {
+			entries = filesystem.listDirectory(manifest.projectPath);
+		} catch (error) {
+			return {
+				tag: "path_inspection_failed",
+				path: manifest.projectPath,
+				message: errorMessage(error)
+			};
+		}
+		if (entries.length > 0) return {
+			tag: "project_target_occupied",
+			path: manifest.projectPath,
+			state: "directory"
+		};
+	}
+	return undefined;
+}
+/** Write only a preflighted immutable manifest. */
+function writePreflightedScaffoldFiles(plan, filesystem) {
+	try {
+		if (filesystem.inspect(plan.projectPath) === "missing") {
+			try {
+				filesystem.mkdir(plan.projectPath);
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						tag: "directory_create_failed",
+						path: plan.projectPath,
+						message: errorMessage(error)
+					}
+				};
+			}
+		}
+		for (const file of plan.files) {
+			const target = join(plan.projectPath, file.path);
+			try {
+				filesystem.mkdir(dirname(target));
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						tag: "directory_create_failed",
+						path: dirname(target),
+						message: errorMessage(error)
+					}
+				};
+			}
+			try {
+				filesystem.writeFile(target, file.content, Boolean(file.executable));
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						tag: "file_write_failed",
+						path: target,
+						message: errorMessage(error)
+					}
+				};
+			}
+		}
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error: {
+				tag: "path_inspection_failed",
+				path: plan.projectPath,
+				message: errorMessage(error)
+			}
+		};
+	}
+}
+/** Validate all targets, then write the immutable manifest. */
+function writeScaffoldFiles(plan, filesystem) {
+	const preflightError = preflightScaffoldPlan(plan, filesystem);
+	if (preflightError) return {
+		ok: false,
+		error: preflightError
+	};
+	return writePreflightedScaffoldFiles(plan, filesystem);
+}
+/**
+* Prepare a two-stage effect shell so `init` can insert credential link
+* between materialization and docs/build without duplicating the shell.
+*/
+function prepareScaffoldExecution(plan, dependencies, packageSourceOverride) {
+	const preflightError = preflightScaffoldPlan(plan, dependencies.filesystem);
+	if (preflightError) return {
+		ok: false,
+		error: preflightError
+	};
+	return {
+		ok: true,
+		value: { materialize: () => {
+			try {
+				dependencies.process.createNextApp(plan.projectPath);
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						tag: "create_next_app_failed",
+						message: errorMessage(error)
+					}
+				};
+			}
+			const written = writePreflightedScaffoldFiles(plan, dependencies.filesystem);
+			if (!written.ok) return written;
+			try {
+				dependencies.process.cleanupGeneratedDefaults(plan.projectPath);
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						tag: "generated_defaults_cleanup_failed",
+						message: errorMessage(error)
+					}
+				};
+			}
+			try {
+				dependencies.process.configureProject(plan.projectPath, plan);
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						tag: "file_write_failed",
+						path: join(plan.projectPath, "package.json"),
+						message: errorMessage(error)
+					}
+				};
+			}
+			try {
+				dependencies.process.installPackages(plan.projectPath, packageSourceOverride ?? plan.packageSource, plan.packageSource.ranges);
+			} catch (error) {
+				return {
+					ok: false,
+					error: {
+						tag: "package_install_failed",
+						message: errorMessage(error)
+					}
+				};
+			}
+			return {
+				ok: true,
+				value: { completeAfterLink: createScaffoldCompletion(plan.projectPath, dependencies.process) }
+			};
+		} }
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/agents-md.ts
+function agentsMdTemplate() {
+	return {
+		path: "AGENTS.md",
+		content: `# Code Guidelines
+
+Guidelines for AI agents and developers working on this codebase.
+
+## Principles
+
+- **DRY**: Don't repeat yourself. Extract shared logic into helpers.
+- **Modularity**: Small, focused functions that do one thing well.
+- **Functional style**: Prefer pure functions, avoid mutation.
+- **Composition over inheritance**: Build complex behavior from simple pieces.
+- **Simplicity**: The simplest solution that works is often the best.
+
+## SDK Development
+
+This site uses \`@riverbankcms/sdk\` from Riverbank Digital. **We control the SDK repository.**
+
+### When you encounter SDK limitations:
+
+1. **Don't work around SDK shortcomings** in this codebase
+2. Document the limitation and desired behavior
+3. Create a plan/issue for SDK improvements
+4. Implement the fix in the SDK, then use it here
+
+This approach keeps the site code clean and improves the SDK for all users.
+
+## File Organization
+
+\`\`\`
+src/
+  app/              # Next.js App Router pages
+    [[...slug]]/    # CMS-managed pages (catch-all route)
+  lib/              # Shared utilities and SDK client
+  components/       # React components (if needed)
+  __tests__/        # Test files
+\`\`\`
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Files | kebab-case | \`riverbank-client.ts\` |
+| Functions | camelCase | \`getRiverbankClient\` |
+| Types/Interfaces | PascalCase | \`PageProps\` |
+| Constants | SCREAMING_SNAKE_CASE | \`PREVIEW_MODE\` |
+| Components | PascalCase | \`CustomHero.tsx\` |
+
+## Code Quality
+
+### Before committing:
+
+\`\`\`bash
+pnpm verify  # Full check: lint + typecheck + tests
+\`\`\`
+
+### Guidelines:
+
+- Keep functions small and focused
+- Prefer explicit over implicit
+- Add types - avoid \`any\`
+- Handle errors explicitly
+- Write tests for business logic
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/block-extensions.ts
+function blockExtensionsTemplate() {
+	return {
+		path: "src/config/block-extensions.ts",
+		content: `import type { BlockFieldExtensionsMap, BlockFieldOptionsMap } from '@riverbankcms/sdk/config';
+
+/**
+ * Block Field Extensions
+ *
+ * Add custom fields to built-in SDK blocks.
+ * These fields appear in the CMS editor alongside the block's default fields.
+ *
+ * Example:
+ * \`\`\`typescript
+ * 'block.hero': {
+ *   fields: [
+ *     {
+ *       id: 'layout',
+ *       type: 'select',
+ *       label: 'Layout',
+ *       required: false,
+ *       multiple: false,
+ *       options: [
+ *         { value: 'default', label: 'Default' },
+ *         { value: 'centered', label: 'Centered' },
+ *       ],
+ *       defaultValue: 'default',
+ *     },
+ *   ],
+ * }
+ * \`\`\`
+ */
+export const blockFieldExtensions: BlockFieldExtensionsMap = {
+  // Add your block field extensions here
+};
+
+/**
+ * Block Field Options
+ *
+ * Customize the options available for existing fields on built-in blocks.
+ *
+ * Example:
+ * \`\`\`typescript
+ * 'block.embed': {
+ *   layout: {
+ *     options: [
+ *       { value: 'grid', label: 'Grid Layout' },
+ *       { value: 'list', label: 'List Layout' },
+ *     ],
+ *   },
+ * }
+ * \`\`\`
+ */
+export const blockFieldOptions: BlockFieldOptionsMap = {
+  // Add your block field option overrides here
+};
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/block-overrides.ts
+function blockOverridesTemplate() {
+	return {
+		path: "src/lib/block-overrides.tsx",
+		content: `/**
+ * Host block override registrations
+ *
+ * Fully headless sites own rendering for every block kind they use. The empty
+ * registry is intentional while the starter homepage has no blocks. Add a
+ * registration before adding a block to content; an unregistered kind raises
+ * MissingBlockOverrideError rather than using a built-in renderer.
+ *
+ * Example:
+ * \`\`\`typescript
+ * import {
+ *   defineBlockOverrideRegistrations,
+ *   defineLazyBlockOverride,
+ *   type BlockOverrideProps,
+ *   type BlockOverrideRegistrations,
+ *   type HeroContent,
+ * } from '@riverbankcms/sdk/rendering';
+ * import { CustomHero } from '@/components/CustomHero';
+ *
+ * const TypedHero = (props: BlockOverrideProps<HeroContent>) => <CustomHero {...props} />;
+ *
+ * export const blockOverrides = defineBlockOverrideRegistrations({
+ *   // Override the built-in hero block
+ *   hero: TypedHero,
+ *
+ *   // Lazy-load client-heavy or rarely used custom blocks
+ *   'custom.quiz': defineLazyBlockOverride(async () =>
+ *     import('@/components/blocks/QuizBlock').then((module) => module.QuizBlock),
+ *   ),
+ * }) satisfies BlockOverrideRegistrations;
+ * \`\`\`
+ */
+
+import { defineBlockOverrideRegistrations } from '@riverbankcms/sdk/rendering';
+import type { BlockOverrideRegistrations } from '@riverbankcms/sdk/rendering';
+
+export const blockOverrides = defineBlockOverrideRegistrations({}) satisfies
+  BlockOverrideRegistrations;
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/catch-all-page.ts
+function catchAllPageTemplate(config) {
+	const previewImports = config.withPreviewMode ? `import { createPreviewModeBeforeRender } from '@riverbankcms/sdk/preview-next/before-render'\nimport { SdkPreviewModeClient } from '@/components/preview/SdkPreviewModeClient'\n` : "";
+	const previewBeforeRender = config.withPreviewMode ? `,
+  beforeRender: createPreviewModeBeforeRender({
+    getClient: getRiverbankClient,
+    siteId: config.siteId,
+    siteSlug: ${JSON.stringify(config.siteSlug)},
+    PreviewModeClient: SdkPreviewModeClient,
+  })` : "";
+	return {
+		path: "src/app/[[...slug]]/page.tsx",
+		content: `import {
+  createCatchAllPage,
+  createGenerateStaticParams,
+} from '@riverbankcms/sdk/next';
+import { getRiverbankClient } from '@/lib/riverbank-client';
+import { SITE_RENDERING } from '@/lib/rendering';
+import config from '../../../riverbank.config';
+import { blockOverrides } from '@/lib/block-overrides';
+import { dataLoaderOverrides } from '@/lib/data-loader-overrides.server';
+${previewImports}
+
+// Next.js route config values must remain statically analyzable literals.
+export const revalidate = 300;
+export const dynamicParams = true;
+// Route discovery falls back to the homepage when the CMS is unavailable so
+// the scaffold verification build does not require a live API. Add
+// failureMode: 'throw' when production CI should reject discovery failures.
+export const generateStaticParams = createGenerateStaticParams({
+  getClient: getRiverbankClient,
+  siteId: config.siteId,
+});
+
+/**
+ * Create catch-all page using SDK helper
+ *
+ * The createCatchAllPage helper handles:
+ * - Loading page data from CMS
+ * - Rendering blocks with the Page component
+ * - Generating metadata for SEO
+ * - 404 handling for non-existent pages
+ *
+ * Add an override for every block kind used by the site's content. The empty
+ * starter registry is intentional; an unregistered kind raises the SDK's
+ * MissingBlockOverrideError instead of falling back to built-in rendering.
+ */
+const { Page, generateMetadata } = createCatchAllPage({
+  getClient: getRiverbankClient,
+  config,
+  rendering: SITE_RENDERING,
+  searchParamsMode: 'ignore',
+  blockOverrides${previewBeforeRender},
+  dataLoaderOverrides,
+});
+
+export default Page;
+export { generateMetadata };
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/cms-push-staging.ts
+function cmsPushStagingTemplate() {
+	return {
+		path: "scripts/cms-push-staging.sh",
+		executable: true,
+		content: `#!/usr/bin/env bash
+set -euo pipefail
+
+PROJECT_ROOT="$(cd "$(dirname "\${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="\${PROJECT_ROOT}/.env.staging"
+
+APPLY=0
+if [[ "\${1:-}" == "--apply" ]]; then
+  APPLY=1
+  shift
+fi
+
+if [[ ! -f "\${ENV_FILE}" ]]; then
+  echo "Missing \${ENV_FILE}"
+  echo ""
+  echo "Create it by copying the template:"
+  echo "  cp .env.staging.example .env.staging"
+  echo ""
+  echo "Then fill in:"
+  echo "  RIVERBANK_STAGING_SITE_ID=..."
+  echo "  RIVERBANK_STAGING_DASHBOARD_URL=https://..."
+  echo "  RIVERBANK_STAGING_MGMT_API_KEY=bld_mgmt_sk_..."
+  exit 1
+fi
+
+cd "\${PROJECT_ROOT}"
+
+set -a
+# shellcheck disable=SC1090
+source "\${ENV_FILE}"
+set +a
+
+: "\${RIVERBANK_STAGING_SITE_ID:?Missing RIVERBANK_STAGING_SITE_ID in .env.staging}"
+: "\${RIVERBANK_STAGING_DASHBOARD_URL:?Missing RIVERBANK_STAGING_DASHBOARD_URL in .env.staging}"
+: "\${RIVERBANK_STAGING_MGMT_API_KEY:?Missing RIVERBANK_STAGING_MGMT_API_KEY in .env.staging}"
+
+dashboard_url="\${RIVERBANK_STAGING_DASHBOARD_URL}"
+if [[ "\${dashboard_url}" != http://* && "\${dashboard_url}" != https://* ]]; then
+  dashboard_url="https://\${dashboard_url}"
+fi
+
+dashboard_host="$(DASHBOARD_URL="\${dashboard_url}" node -e "console.log(new URL(process.env.DASHBOARD_URL).host)")"
+
+if [[ "\${dashboard_host}" == "www.riverbankcms.com" || "\${dashboard_host}" == "riverbankcms.com" ]]; then
+  echo "Refusing to run staging push against production dashboard host: \${dashboard_host}"
+  exit 1
+fi
+
+export RIVERBANK_REMOTE_SITE_ID="\${RIVERBANK_STAGING_SITE_ID}"
+export RIVERBANK_REMOTE_DASHBOARD_URL="\${dashboard_url}"
+export RIVERBANK_REMOTE_MGMT_API_KEY="\${RIVERBANK_STAGING_MGMT_API_KEY}"
+
+cmd=(pnpm exec riverbankcms push --env=remote)
+if [[ "\${APPLY}" == "1" ]]; then
+  cmd+=(--yes)
+else
+  cmd+=(--dry-run)
+fi
+cmd+=("$@")
+
+echo "Target: \${RIVERBANK_REMOTE_DASHBOARD_URL} (site: \${RIVERBANK_REMOTE_SITE_ID})"
+echo "Running: \${cmd[*]}"
+"\${cmd[@]}"
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/content-types.ts
+const BLOG_CONTENT_TYPE = `  // Blog posts
+  {
+    key: 'post',
+    name: 'Blog Post',
+    description: 'Blog articles and news',
+    hasPages: true,
+    routePattern: '/blog/{slug}',
+    fields: [
+      { id: 'excerpt', type: 'text', label: 'Excerpt', required: false, multiline: true, description: 'Short summary for listings' },
+      { id: 'image', type: 'media', label: 'Featured Image', required: false, mediaKinds: ['image'] },
+      { id: 'content', type: 'richText', label: 'Content', required: true },
+      { id: 'author', type: 'text', label: 'Author', required: false, multiline: false },
+      { id: 'publishedAt', type: 'datetime', label: 'Publish Date', required: false },
+    ],
+  }`;
+const TESTIMONIALS_CONTENT_TYPE = `  // Testimonials
+  {
+    key: 'testimonial',
+    name: 'Testimonial',
+    description: 'Customer testimonials and reviews',
+    hasPages: false,
+    fields: [
+      { id: 'name', type: 'text', label: 'Name', required: true, multiline: false },
+      { id: 'jobTitle', type: 'text', label: 'Job Title', required: false, multiline: false },
+      { id: 'company', type: 'text', label: 'Company', required: false, multiline: false },
+      { id: 'body', type: 'richText', label: 'Quote', required: true },
+    ],
+    titleField: 'name',
+  }`;
+const EVENTS_CONTENT_TYPE = `  // Events
+  {
+    key: 'event',
+    name: 'Event',
+    description: 'Events and workshops',
+    hasPages: true,
+    routePattern: '/events/{slug}',
+    fields: [
+      { id: 'excerpt', type: 'text', label: 'Summary', required: false, multiline: true },
+      { id: 'startsAt', type: 'datetime', label: 'Starts At', required: false },
+      { id: 'endsAt', type: 'datetime', label: 'Ends At', required: false },
+      { id: 'location', type: 'text', label: 'Location', required: false, multiline: false },
+      { id: 'content', type: 'richText', label: 'Details', required: true },
+    ],
+  }`;
+const PORTFOLIO_CONTENT_TYPE = `  // Portfolio items
+  {
+    key: 'portfolio-item',
+    name: 'Portfolio Item',
+    description: 'Work portfolio entries with case study pages',
+    hasPages: true,
+    routePattern: '/work/{slug}',
+    fields: [
+      { id: 'short-description', type: 'text', label: 'Short Description', required: false, multiline: true, description: 'Brief summary shown in carousel/list views' },
+      { id: 'full-description', type: 'richText', label: 'Full Description', required: false, description: 'Detailed description for the case study page' },
+      { id: 'image', type: 'media', label: 'Featured Image', required: false, mediaKinds: ['image'], description: 'Screenshot or hero image' },
+      { id: 'content', type: 'richText', label: 'Case Study Content', required: false, description: 'Full case study content' },
+      { id: 'link', type: 'link', label: 'External Link', required: false, description: 'Link to the live project' },
+    ],
+  }`;
+function contentTypesTemplate(options = {}) {
+	const contentTypes = [];
+	if (options.withBlog) {
+		contentTypes.push(BLOG_CONTENT_TYPE);
+	}
+	if (options.withTestimonials) {
+		contentTypes.push(TESTIMONIALS_CONTENT_TYPE);
+	}
+	if (options.withEvents) {
+		contentTypes.push(EVENTS_CONTENT_TYPE);
+	}
+	if (options.withPortfolio) {
+		contentTypes.push(PORTFOLIO_CONTENT_TYPE);
+	}
+	const contentTypesArray = contentTypes.length > 0 ? `[\n${contentTypes.join(",\n")},\n]` : `[
+  // Add your content types here
+]`;
+	return {
+		path: "src/config/content-types.ts",
+		content: `import type { ContentTypeConfig } from '@riverbankcms/sdk/config';
+import { getContentEntryPrefixesFromContentTypes } from '@riverbankcms/sdk/routing';
+
+/**
+ * Content Type Definitions
+ *
+ * Defines the schema for each content type (testimonials, services, blog posts, etc.)
+ * These are synced to the CMS dashboard via \`pnpm exec riverbankcms push-config\`.
+ *
+ * Example:
+ * \`\`\`typescript
+ * {
+ *   key: 'testimonial',
+ *   name: 'Testimonial',
+ *   description: 'Customer testimonials and reviews',
+ *   hasPages: false,
+ *   fields: [
+ *     { id: 'name', type: 'text', label: 'Name', required: true, multiline: false },
+ *     { id: 'body', type: 'richText', label: 'Quote', required: true },
+ *   ],
+ *   titleField: 'name',
+ * }
+ * \`\`\`
+ */
+export const contentTypes: ContentTypeConfig[] = ${contentTypesArray};
+
+/**
+ * Route prefixes for content types with pages.
+ * Used by the catch-all route to determine whether a path is a content entry.
+ *
+ * Derived from routePattern values (e.g., '/blog/{slug}' → 'blog').
+ */
+export const CONTENT_ENTRY_PREFIXES = getContentEntryPrefixesFromContentTypes(contentTypes);
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/custom-blocks.ts
+function customBlocksTemplate() {
+	return {
+		path: "src/config/custom-blocks.ts",
+		content: `import type { SdkCustomBlock } from '@riverbankcms/sdk/config';
+
+/**
+ * Custom Block Definitions
+ *
+ * Site-specific blocks that extend the SDK's built-in block library.
+ * Each block needs a corresponding React component in src/components
+ * and an entry in blockOverrides.
+ *
+ * Example:
+ * \`\`\`typescript
+ * {
+ *   id: 'custom.hero-banner',
+ *   title: 'Hero Banner',
+ *   description: 'Custom hero with animated background',
+ *   category: 'hero',
+ *   icon: 'Sparkles',
+ *   tags: ['hero', 'banner', 'animated'],
+ *   fields: [
+ *     { id: 'title', type: 'text', label: 'Title', required: true, multiline: false },
+ *     { id: 'subtitle', type: 'text', label: 'Subtitle', required: false, multiline: true },
+ *   ],
+ * }
+ * \`\`\`
+ */
+export const customBlocks: SdkCustomBlock[] = [
+  // Add your custom blocks here
+];
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/data-loader-overrides.ts
+function dataLoaderOverridesTemplate() {
+	return {
+		path: "src/lib/data-loader-overrides.server.ts",
+		content: `import 'server-only';
+
+import type { DataLoaderOverrides } from '@riverbankcms/sdk/next';
+
+/**
+ * Host data loaders run only while rendering Server Components. Keep database
+ * clients, private API credentials, and loader functions in this server module.
+ */
+export const dataLoaderOverrides = {
+  // If a loader reads searchParams, set searchParamsMode: 'dynamic' in the catch-all page.
+  // 'custom.product-grid': {
+  //   products: async ({ content, searchParams, previewStage, renderTarget }) => {
+  //     const category =
+  //       typeof content.category === 'string' ? content.category : undefined;
+  //     const response = await fetch(
+  //       \`https://host-api.example/products?category=\${encodeURIComponent(category ?? '')}\`,
+  //       {
+  //         headers: {
+  //           // Use credentials only for the server request. Never return them.
+  //           Authorization: \`Bearer \${process.env.HOST_API_TOKEN ?? ''}\`,
+  //         },
+  //       },
+  //     );
+  //     const payload: unknown = await response.json();
+  //     return {
+  //       products: parseProductPayload(payload),
+  //       query: searchParams.query ?? null,
+  //       previewStage,
+  //       owner: describeRenderTarget(renderTarget),
+  //     };
+  //   },
+  // },
+} satisfies DataLoaderOverrides;
+
+// Import or implement an application parser before enabling the example.
+// import type { DataLoaderRenderTarget } from '@riverbankcms/sdk/next';
+// declare function parseProductPayload(value: unknown): readonly Product[];
+//
+// function describeRenderTarget(target: DataLoaderRenderTarget): string {
+//   switch (target.kind) {
+//     case 'page':
+//       return target.pageId;
+//     case 'entry-template':
+//       return target.entryId;
+//     case 'page-surface-template':
+//       return target.pageSurfaceId;
+//     default: {
+//       const exhaustive: never = target;
+//       return exhaustive;
+//     }
+//   }
+// }
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/env-config.ts
+function envConfigTemplate(config) {
+	const previewConfig = config.withPreviewMode ? `  /** Whether preview mode is enabled */
+  previewMode: boolean;
+  /** Preview API key for draft content */
+  previewApiKey: string | undefined;
+` : "";
+	const previewReturn = config.withPreviewMode ? `    previewMode: process.env.RIVERBANK_PREVIEW_MODE === 'true',
+    previewApiKey: process.env[\`\${prefix}PREVIEW_API_KEY\`],
+` : "";
+	return {
+		path: "src/lib/env.ts",
+		content: `/**
+ * Multi-environment CMS configuration helper.
+ *
+ * Reads CMS config based on RIVERBANK_ENV (local | remote).
+ * All environment-specific variables use the pattern: RIVERBANK_{ENV}_{KEY}
+ */
+
+type CmsEnv = 'local' | 'remote';
+
+function getCmsEnv(): CmsEnv {
+  // Respect RIVERBANK_ENV if explicitly set (allows build with local CMS)
+  const envOverride = process.env.RIVERBANK_ENV;
+  if (envOverride === 'local' || envOverride === 'remote') {
+    return envOverride;
+  }
+
+  // In production runtime (not build), default to remote
+  // Deployed sites should use remote CMS unless explicitly overridden
+  if (process.env.NODE_ENV === 'production') {
+    return 'remote';
+  }
+
+  // In development, default to 'local'
+  return 'local';
+}
+
+export interface CmsConfig {
+  /** Current environment (local or remote) */
+  env: CmsEnv;
+${previewConfig}
+  /** Site UUID for this environment */
+  siteId: string | undefined;
+  /** Dashboard URL used for CMS API requests */
+  dashboardUrl: string | undefined;
+  /** Live API key for published content */
+  apiKey: string | undefined;
+  /** Management API key for SDK write operations */
+  mgmtApiKey: string | undefined;
+}
+
+/**
+ * Get CMS configuration for the current environment.
+ *
+ * Reads from environment variables with pattern: RIVERBANK_{ENV}_{KEY}
+ * where ENV is determined by RIVERBANK_ENV (defaults to 'local').
+ *
+ * @example
+ * \`\`\`typescript
+ * const { siteId, dashboardUrl, apiKey } = getCmsConfig();
+ * \`\`\`
+ */
+export function getCmsConfig(): CmsConfig {
+  const env = getCmsEnv();
+  const prefix = \`RIVERBANK_\${env.toUpperCase()}_\`;
+
+  return {
+    env,
+${previewReturn}
+    siteId: process.env[\`\${prefix}SITE_ID\`],
+    dashboardUrl: process.env[\`\${prefix}DASHBOARD_URL\`],
+    apiKey: process.env[\`\${prefix}API_KEY\`],
+    mgmtApiKey: process.env[\`\${prefix}MGMT_API_KEY\`],
+  };
+}
+
+/**
+ * Get the current CMS environment name.
+ */
+export function getCurrentEnv(): CmsEnv {
+  return getCmsEnv();
+}
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/env-example.ts
+function envExampleTemplate(config) {
+	const previewBlock = config.withPreviewMode ? `# Preview mode: set to "true" to fetch draft content
+RIVERBANK_PREVIEW_MODE=false
+` : "";
+	const previewKeys = config.withPreviewMode ? `RIVERBANK_LOCAL_PREVIEW_API_KEY=""
+` : "";
+	const remotePreviewKey = config.withPreviewMode ? `RIVERBANK_REMOTE_PREVIEW_API_KEY=""
+` : "";
+	return {
+		path: ".env.example",
+		content: `# Riverbank CMS Configuration
+# Copy this to .env.local and fill in your values
+# Switch environments by changing RIVERBANK_ENV
+
+# Environment selector: local | remote
+RIVERBANK_ENV=local
+
+${previewBlock}
+
+# ============ LOCAL CMS ============
+# Your local development CMS instance
+RIVERBANK_LOCAL_SITE_ID=""
+RIVERBANK_LOCAL_DASHBOARD_URL=""
+RIVERBANK_LOCAL_API_KEY=""
+${previewKeys}RIVERBANK_LOCAL_MGMT_API_KEY=""
+
+# ============ REMOTE CMS ============
+# Your production/staging CMS instance
+RIVERBANK_REMOTE_SITE_ID=""
+RIVERBANK_REMOTE_DASHBOARD_URL=""
+RIVERBANK_REMOTE_API_KEY=""
+${remotePreviewKey}RIVERBANK_REMOTE_MGMT_API_KEY=""
+
+# ============ SHARED ============
+# Set after deployment with \`riverbankcms webhooks setup\`; init never registers a webhook.
+RIVERBANK_WEBHOOK_SECRET=""
+
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/env-staging-example.ts
+function envStagingExampleTemplate() {
+	return {
+		path: ".env.staging.example",
+		content: `RIVERBANK_STAGING_SITE_ID=
+RIVERBANK_STAGING_DASHBOARD_URL=
+RIVERBANK_STAGING_MGMT_API_KEY=
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/error.ts
+function errorTemplate() {
+	return {
+		path: "src/app/error.tsx",
+		content: `'use client';
+
+import { useEffect } from 'react';
+import Link from 'next/link';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    // Log the error to an error reporting service
+    console.error(error);
+  }, [error]);
+
+  return (
+    <div className="min-h-[60vh] flex items-center justify-center px-4">
+      <div className="text-center max-w-md">
+        {/* Error icon */}
+        <div className="w-20 h-20 mx-auto mb-6 rounded-full bg-[var(--color-accent,#f59e0b)]/20 flex items-center justify-center">
+          <svg
+            className="w-10 h-10 text-[var(--color-accent,#f59e0b)]"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={1.5}
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M12 9v3.75m-9.303 3.376c-.866 1.5.217 3.374 1.948 3.374h14.71c1.73 0 2.813-1.874 1.948-3.374L13.949 3.378c-.866-1.5-3.032-1.5-3.898 0L2.697 16.126zM12 15.75h.007v.008H12v-.008z"
+            />
+          </svg>
+        </div>
+
+        {/* Message */}
+        <h1 className="text-2xl sm:text-3xl text-[var(--color-text,#1f2937)] font-bold">
+          Something went wrong
+        </h1>
+        <p className="mt-4 text-lg text-[var(--color-text,#1f2937)]/70">
+          We encountered an unexpected error. Please try again, or contact us if
+          the problem persists.
+        </p>
+
+        {/* Action buttons */}
+        <div className="mt-8 flex flex-wrap justify-center gap-3">
+          <button
+            onClick={() => reset()}
+            className="px-8 py-3 bg-[var(--color-primary,#6d28d9)] text-white rounded-full transition-colors hover:opacity-90 font-medium"
+          >
+            Try Again
+          </button>
+          <Link
+            href="/"
+            className="px-8 py-3 border border-[var(--color-primary,#6d28d9)] text-[var(--color-primary,#6d28d9)] rounded-full transition-colors hover:bg-[var(--color-primary,#6d28d9)]/10 font-medium"
+          >
+            Back to Home
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/example-test.ts
+function exampleTestTemplate() {
+	return {
+		path: "src/__tests__/example.test.mjs",
+		content: `import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+describe('Example test suite', () => {
+  it('should pass a basic test', () => {
+    assert.equal(1 + 1, 2);
+  });
+
+  it('should handle string operations', () => {
+    const greeting = 'Hello, World!';
+    assert.ok(greeting.includes('Hello'));
+    assert.ok(greeting.length > 0);
+  });
+});
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/gitignore.ts
+const LOCAL_MEDIA_CACHE_GITIGNORE_SECTION = `# Riverbank local media cache and migration working files.
+# See .riverbank/docs/content-management.md for when to intentionally track fixtures.
+content/media/*
+!content/media/fixtures/
+!content/media/fixtures/**
+`;
+function gitignoreTemplate() {
+	return {
+		path: ".gitignore",
+		content: `# Dependencies
+node_modules/
+.pnp
+.pnp.*
+
+# Next.js
+.next/
+out/
+
+# Production
+build/
+dist/
+
+# Test output
+coverage/
+
+# Environment files
+.env*
+!.env.example
+!.env.staging.example
+
+${LOCAL_MEDIA_CACHE_GITIGNORE_SECTION}
+
+# Deployment
+.vercel/
+
+# TypeScript
+*.tsbuildinfo
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# OS/editor files
+.DS_Store
+*.swp
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/globals-css.ts
+function globalsCssTemplate(config) {
+	const previewBlock = config.withPreviewMode ? `/* Preview editor chrome (Tailwind-managed).
+ *
+ * The preview chrome uses Tailwind utilities, but importing Tailwind from the SDK can
+ * collide with site styling (preflight, layer order, @theme directives).
+ *
+ * Recommended: keep Tailwind owned by the site, and add Riverbank package @source globs
+ * alongside your own Tailwind entrypoint.
+ *
+ * If your site does NOT use Tailwind, use the legacy single import instead:
+ *   @import "@riverbankcms/sdk/preview-next/styles.css";
+ */
+@import "tailwindcss";
+@import "@riverbankcms/sdk/preview-next/tailwind-sources.css";
+@import "@riverbankcms/sdk/preview-next/chrome.css";
+
+` : "";
+	return {
+		path: "src/app/globals.css",
+		content: `${previewBlock}/* Add host-owned styles below. */
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/layout.ts
+function layoutTemplate(config) {
+	const escapedSiteName = JSON.stringify(config.siteName);
+	const chromeRoot = config.withPreviewMode ? `\n        <div id="builder-editor-chrome-root" className="builder-editor-chrome builder-dashboard-chrome-theme" />` : "";
+	return {
+		path: "src/app/layout.tsx",
+		content: `import type { Metadata } from 'next';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: ${escapedSiteName},
+  description: 'Built with Riverbank CMS',
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <head />
+      <body>
+        ${chromeRoot}
+        {children}
+      </body>
+    </html>
+  );
+}
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/next-config.ts
+function nextConfigTemplate() {
+	return {
+		path: "next.config.ts",
+		content: `import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // Transpile workspace packages (needed for linked packages / local development).
+  transpilePackages: ${JSON.stringify(["@riverbankcms/sdk"])},
+
+  // Allow imports from outside the project directory
+  experimental: {
+    externalDir: true,
+  },
+
+  // Add remote origins required by your deployment. The SDK preserves storage
+  // metadata in content responses, so this scaffold does not assume a provider.
+  images: {
+    remotePatterns: [],
+    dangerouslyAllowSVG: true,
+    contentDispositionType: 'inline',
+  },
+};
+
+export default nextConfig;
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/not-found.ts
+function notFoundTemplate() {
+	return {
+		path: "src/app/not-found.tsx",
+		content: `import Link from 'next/link';
+
+export default function NotFound() {
+  return (
+    <div className="min-h-[60vh] flex items-center justify-center px-4">
+      <div className="text-center max-w-md">
+        {/* Large 404 with brand color */}
+        <h1 className="text-[120px] sm:text-[160px] leading-none text-[var(--color-primary,#6d28d9)]/20 font-bold">
+          404
+        </h1>
+
+        {/* Message */}
+        <h2 className="text-2xl sm:text-3xl text-[var(--color-text,#1f2937)] -mt-4 font-bold">
+          Page not found
+        </h2>
+        <p className="mt-4 text-lg text-[var(--color-text,#1f2937)]/70">
+          Sorry, we couldn&apos;t find the page you&apos;re looking for. It may have been
+          moved or no longer exists.
+        </p>
+
+        {/* Back to home button */}
+        <Link
+          href="/"
+          className="inline-block mt-8 px-8 py-3 bg-[var(--color-primary,#6d28d9)] text-white rounded-full transition-colors hover:opacity-90 font-medium"
+        >
+          Back to Home
+        </Link>
+      </div>
+    </div>
+  );
+}
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/portal-callback-route.ts
+function portalCallbackRouteTemplate() {
+	return {
+		path: "src/app/api/portal/callback/route.ts",
+		content: `/**
+ * Portal callback route.
+ *
+ * Exchanges a short-lived portal code for a session token, stores the token in
+ * an httpOnly cookie, and redirects back to the requested portal path.
+ */
+
+import { handlePortalCallback } from '@riverbankcms/sdk/portal';
+
+export const GET = handlePortalCallback();
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/portal-logout-route.ts
+function portalLogoutRouteTemplate() {
+	return {
+		path: "src/app/api/portal/logout/route.ts",
+		content: `/**
+ * Portal logout route.
+ *
+ * Invalidates the portal session upstream when possible and always clears the
+ * local portal cookie before redirecting.
+ */
+
+import { handlePortalLogout } from '@riverbankcms/sdk/portal';
+
+export const POST = handlePortalLogout();
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/preview-keep-alive-route.ts
+function previewKeepAliveRouteTemplate() {
+	return {
+		path: "src/app/api/preview/keep-alive/route.ts",
+		content: `import type { NextRequest } from 'next/server'
+
+import { createPreviewKeepAliveRouteHandler } from '@riverbankcms/sdk/preview-next/keep-alive'
+import { getCmsConfig } from '@/lib/env'
+
+const handler = createPreviewKeepAliveRouteHandler({
+  dashboardUrl: getCmsConfig().dashboardUrl,
+})
+
+export function GET(request: NextRequest) {
+  return handler(request)
+}
+
+export function POST(request: NextRequest) {
+  return handler(request)
+}
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/preview-mode-client.ts
+function previewModeClientTemplate() {
+	return {
+		path: "src/components/preview/SdkPreviewModeClient.tsx",
+		content: `'use client'
+
+import { PreviewQueryProvider, SdkPreviewMode, type SdkPreviewModePropsWithoutBlockOverrides } from '@riverbankcms/sdk/preview-next/client'
+
+import { blockOverrides } from '@/lib/block-overrides'
+import { SITE_RENDERING } from '@/lib/rendering'
+
+export function SdkPreviewModeClient(props: SdkPreviewModePropsWithoutBlockOverrides) {
+  const { themeRuntime: _themeRuntime, ...previewProps } = props
+
+  return (
+    <PreviewQueryProvider>
+      <SdkPreviewMode
+        {...previewProps}
+        rendering={SITE_RENDERING}
+        blockOverrides={blockOverrides}
+      />
+    </PreviewQueryProvider>
+  )
+}
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/proxy.ts
+function proxyTemplate(config) {
+	const withPreviewMode = Boolean(config?.withPreviewMode);
+	const previewImport = withPreviewMode ? `import { handlePreviewTokens } from '@riverbankcms/sdk/preview-next/middleware';
+import { handleRouteOutcomeRedirect } from '@riverbankcms/sdk/next/middleware';
+
+import { getCmsConfig } from './lib/env';
+import { getRiverbankClient, getSiteId } from './lib/riverbank-client';
+` : `import { handleRouteOutcomeRedirect } from '@riverbankcms/sdk/next/middleware';
+
+import { getRiverbankClient, getSiteId } from './lib/riverbank-client';
+`;
+	const previewBlock = withPreviewMode ? `
+  if (process.env.RIVERBANK_PREVIEW_MODE === 'true') {
+    const { dashboardUrl } = getCmsConfig();
+    const response = await handlePreviewTokens(request, {
+      dashboardUrl: dashboardUrl ?? null,
+      onExchangeFailure: (failure) => {
+        console.warn('[riverbank] preview token exchange failed', failure);
+      },
+    });
+    if (response) return response;
+  }
+
+` : "\n";
+	return {
+		path: "src/proxy.ts",
+		content: `import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+${previewImport}
+
+/**
+ * Proxy to handle system paths that shouldn't go through the CMS.
+ *
+ * Chrome DevTools and other tools request paths like:
+ * - /.well-known/appspecific/com.chrome.devtools.json
+ * - /apple-touch-icon-*.png
+ *
+ * Without this, these requests hit the catch-all route and cause
+ * noisy error logs when the CMS can't find them.
+ */
+export async function proxy(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+${previewBlock}  // System paths that shouldn't go through the CMS
+  const systemPaths = [
+    /^\\/\\.well-known\\//,
+    /^\\/apple-touch-icon/,
+    /^\\/browserconfig\\.xml$/,
+  ];
+
+  if (systemPaths.some(pattern => pattern.test(pathname))) {
+    return new Response(null, { status: 404 });
+  }
+
+  const redirectResponse = await handleRouteOutcomeRedirect(request, {
+    client: getRiverbankClient(),
+    siteId: getSiteId(),
+    onFailure: (error, context) => {
+      console.warn('[riverbank] route outcome redirect check failed', {
+        ...context,
+        error,
+      });
+    },
+  });
+  if (redirectResponse) return redirectResponse;
+
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    // Only run on paths that might be system paths
+    // Exclude _next, api, and common static files
+    '/((?!_next/static|_next/image|api|favicon.ico|robots.txt|sitemap.xml).*)',
+  ],
+};
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/readme.ts
+function gettingStartedSection(config) {
+	const { cli: cliRange } = config.packageRanges;
+	const previewEnvironmentRows = config.withPreviewMode ? `| \`RIVERBANK_PREVIEW_MODE\` | Set to \`true\` to fetch draft content |
+| \`RIVERBANK_LOCAL_PREVIEW_API_KEY\` | Local preview key |
+` : "";
+	const previewSection = config.withPreviewMode ? `## Preview Mode
+
+To preview unpublished content:
+
+1. Set \`RIVERBANK_PREVIEW_MODE=true\` in \`.env.local\`
+2. Ensure \`riverbank.config.ts\` has \`dashboard.previewEditingEnabled: true\` and push config so dashboard preview links include Riverbank preview sessions
+3. Restart the dev server (\`pnpm dev\`)
+
+Preview mode:
+- Fetches draft content instead of published
+- Disables ISR caching for real-time updates
+- Uses the preview API key for authentication
+- Uses \`PreviewQueryProvider\` (React Query) for preview shell state
+
+` : "";
+	return `# ${config.siteName}
+
+A Next.js site powered by Riverbank CMS SDK with host-owned rendering.
+
+## Getting Started
+
+\`\`\`bash
+# Install dependencies. The SDK and CLI are separate packages.
+pnpm install
+
+# Start development server
+pnpm dev
+\`\`\`
+
+Open [http://localhost:${config.devPort}](http://localhost:${config.devPort}) to view your site.
+
+## Content Workflow
+
+\`riverbank.config.ts\` is for schema and configuration: content types, custom blocks, block field options, and preview settings.
+
+Document content lives in \`content/**\`:
+
+\`\`\`
+content/
+  pages/home.json              # CMS pages
+  entries/<type>/<entry>.json  # Content entries
+  navigation.json              # Navigation menus
+  settings.json                # Site settings such as homepage/SEO defaults
+  media/                       # Local media cache / migration working files
+\`\`\`
+
+\`content/media/*\` is gitignored by default because it can hold large downloaded
+or migration-working files. Content JSON should reference media by identifier.
+If you intentionally want to version a few small fixtures, put them under
+\`content/media/fixtures/\`.
+
+Use this flow after editing schema or starter content:
+
+\`\`\`bash
+pnpm exec riverbankcms push-config --env=local
+pnpm exec riverbankcms push --env=local --with-config
+\`\`\`
+
+\`--with-config\` syncs schema/config alongside the file-based document push. It does not push document content from \`riverbank.config.ts\`.
+
+The generated project declares both packages explicitly: \`@riverbankcms/sdk\`
+provides the runtime and \`riverbankcms\` provides the command-line tools.
+The CLI is released independently; the generated \`${cliRange}\` range is derived
+from the published package contract. Run commands through \`pnpm exec riverbankcms\`
+to use the project-local binary.
+
+## Environment Variables
+
+The \`.env.local\` file contains your CMS configuration:
+
+| Variable | Description |
+|----------|-------------|
+| \`RIVERBANK_ENV\` | Environment selector (\`local\` or \`remote\`) |
+${previewEnvironmentRows}
+| \`RIVERBANK_LOCAL_SITE_ID\` | Site ID for local dashboard |
+| \`RIVERBANK_LOCAL_DASHBOARD_URL\` | Local dashboard URL |
+| \`RIVERBANK_LOCAL_API_KEY\` | Local published-content key |
+| \`RIVERBANK_LOCAL_MGMT_API_KEY\` | Local management key (for push) |
+| \`RIVERBANK_WEBHOOK_SECRET\` | Signing secret, added by post-deployment webhook setup |
+
+${previewSection}
+`;
+}
+function renderingSection() {
+	return `## Fully Headless Rendering
+
+Generated sites use override-only rendering with no CMS theme or SDK runtime styling. The canonical choice lives in \`src/lib/rendering.ts\`; keep using \`SITE_RENDERING\` in any additional CMS route or preview entry point.
+
+The starter homepage and override registry are intentionally empty. Add a typed registration in \`src/lib/block-overrides.tsx\` for every block kind that content uses. The SDK raises \`MissingBlockOverrideError\` for a missing registration instead of silently falling back to a built-in renderer.
+
+Built-in semantic kinds are namespaced as \`block.*\` (for example \`block.hero\`, \`block.body-text\`, \`block.media-text\`, \`block.image-gallery\`, \`block.cta-full\`, and \`block.embed\`). The override registry accepts their short names too, such as \`hero\` or \`body-text\`, alongside your \`custom.*\` kinds.
+
+Stateful kinds such as forms, appointment booking, event registration, and commerce need host-owned UI without reimplementing Riverbank-owned behavior. Where a public headless controller exists, compose it behind the server-safe override; the SDK currently exposes booking and event-registration controllers under \`@riverbankcms/sdk/bookings\`. Controller coverage varies by block, so check the public SDK surface rather than assuming every stateful kind is ready for a custom UI.
+
+`;
+}
+function customizationSection() {
+	return `## Customization
+
+### Block Overrides
+
+Register host-owned block rendering. Keep small server-safe overrides as direct components, and use \`defineLazyBlockOverride()\` for client-heavy or rarely used custom blocks so the catch-all route does not eagerly import every block implementation:
+
+\`\`\`tsx
+// In src/lib/block-overrides.tsx
+import {
+  defineBlockOverrideRegistrations,
+  defineLazyBlockOverride,
+  type BlockOverrideRegistrations,
+} from '@riverbankcms/sdk/rendering';
+import { CustomHero } from '@/components/CustomHero';
+
+export const blockOverrides = defineBlockOverrideRegistrations({
+  hero: CustomHero,
+  'custom.quiz': defineLazyBlockOverride(async () =>
+    import('@/components/blocks/QuizBlock').then((module) => module.QuizBlock),
+  ),
+}) satisfies BlockOverrideRegistrations;
+\`\`\`
+
+Keep the \`import()\` inside the lazy factory. Importing a heavy client block at the top of the file and then wrapping it is still eager from the bundler's point of view.
+
+### Server-only Block Data
+
+Use \`src/lib/data-loader-overrides.server.ts\` when a custom block needs data from your own database or API. The generated catch-all already passes this registry to \`createCatchAllPage()\`, and the registry imports Next.js's \`server-only\` marker so accidental Client Component imports fail the build.
+
+Loaders receive the resolved block content, URL search parameters, preview stage, and page/template identity. Return JSON-safe values only: strings, finite numbers, booleans, null, arrays, and plain objects. Functions, class instances, dates, symbols, \`undefined\`, and cyclic values are rejected at runtime while the page continues rendering.
+
+\`generateMetadata()\` never runs these host loaders, including when you provide \`customMetadata\`. Keep secrets and database clients inside the marked registry.
+
+### Public Performance Checklist
+
+- Avoid broad client imports such as \`@riverbankcms/sdk/rendering/client\` or \`@riverbankcms/blocks/client\` in route-level client code; prefer server-safe SDK imports or narrow block subpaths.
+- Do not mark decorative images as \`priority\` in \`next/image\`. Use CSS backgrounds or plain decorative images with empty alt text for non-content flourishes so Lighthouse does not treat them as the LCP candidate.
+- After adding a client-heavy block, run \`pnpm build\` and inspect the production bundle. The SDK keeps built-in islands lazy, but your site code can still accidentally import custom widgets eagerly.
+
+### Custom Pages
+
+Add pages outside the CMS by creating files in \`src/app/\`:
+
+\`\`\`
+src/app/
+  [[...slug]]/page.tsx  # CMS-managed pages (catch-all)
+  custom/page.tsx       # Custom page at /custom
+\`\`\`
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| \`pnpm dev\` | Start development server |
+| \`pnpm build\` | Build for production |
+| \`pnpm start\` | Start production server |
+| \`pnpm dev:local\` | Run against local CMS config |
+| \`pnpm dev:remote\` | Run against remote CMS config |
+| \`pnpm verify\` | Run lint, typecheck, and tests |
+| \`pnpm test\` | Run tests |
+| \`pnpm typecheck\` | Run TypeScript type checking |
+| \`pnpm cms:push:staging\` | Dry-run push to staging (uses \`.env.staging\`) |
+| \`pnpm cms:push:staging:apply\` | Apply push to staging |
+
+## Staging Push
+
+1. Copy \`.env.staging.example\` to \`.env.staging\`
+2. Fill in staging values
+3. Run \`pnpm cms:push:staging\` first
+4. Apply with \`pnpm cms:push:staging:apply\` once output looks correct
+
+`;
+}
+function deploymentSection(config) {
+	return `## Cache revalidation
+
+The scaffold includes \`/api/revalidate\` but does not create a webhook or secret.
+After deploying to a public HTTPS origin, run:
+
+\`\`\`bash
+riverbankcms webhooks setup --env=remote --url=https://your-site.com/api/revalidate
+\`\`\`
+
+Until that explicit setup, the generated pages use the normal ISR interval.
+
+## Deployment
+
+This is a standard Next.js application. Deploy to any platform that supports Next.js:
+
+- [Vercel](https://vercel.com)
+- [Netlify](https://netlify.com)
+- [AWS Amplify](https://aws.amazon.com/amplify/)
+
+Remember to set your environment variables in the deployment platform.
+
+## Learn More
+
+- [Riverbank SDK Documentation](${config.dashboardUrl}/docs)
+- [Next.js Documentation](https://nextjs.org/docs)
+`;
+}
+function readmeTemplate(config) {
+	return {
+		path: "README.md",
+		content: [
+			gettingStartedSection(config),
+			renderingSection(),
+			customizationSection(),
+			deploymentSection(config)
+		].join("\n")
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/revalidate-route.ts
+function revalidateRouteTemplate() {
+	return {
+		path: "src/app/api/revalidate/route.ts",
+		content: `/**
+ * Webhook endpoint for CMS cache revalidation
+ *
+ * This route receives webhook notifications from Riverbank CMS
+ * and invalidates the appropriate Next.js cache entries.
+ *
+ * After deploying, register this endpoint explicitly with:
+ *   riverbankcms webhooks setup --env=remote --url=https://your-site.com/api/revalidate
+ * Init does not register a webhook or create a signing secret.
+ */
+
+import { createRevalidateHandler } from '@riverbankcms/sdk/next/revalidate';
+import { getRiverbankClient } from '@/lib/riverbank-client';
+
+/**
+ * POST handler for webhook requests
+ *
+ * The handler:
+ * 1. Verifies the webhook signature using HMAC-SHA256
+ * 2. Calls revalidateTag() for each cache tag in the payload
+ * 3. Calls revalidatePath() if a path is included
+ * 4. Best-effort clears this process's SDK client response cache
+ * 5. Returns a JSON response with revalidation results
+ */
+export const POST = createRevalidateHandler({
+  getClient: getRiverbankClient,
+  // Optional: Add logging or analytics
+  onRevalidate: (payload, items) => {
+    console.log(\`[Revalidate] \${payload.event}: \${items.join(', ')}\`);
+  },
+});
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/riverbank-client.ts
+function riverbankClientTemplate(config) {
+	const previewConfig = config.withPreviewMode ? `  const { dashboardUrl, apiKey, previewApiKey, env, previewMode } = getCmsConfig();
+
+  // Use preview API key when in preview mode, otherwise use live key
+  const key = previewMode ? previewApiKey : apiKey;
+
+  if (!key) {
+    const keyName = previewMode ? 'PREVIEW_API_KEY' : 'API_KEY';
+    throw new Error(
+      \`RIVERBANK_\${env.toUpperCase()}_\${keyName} is not set. Check your .env.local file.\`,
+    );
+  }
+` : `  const { dashboardUrl, apiKey, env } = getCmsConfig();
+  const key = apiKey;
+
+  if (!key) {
+    throw new Error(
+      \`RIVERBANK_\${env.toUpperCase()}_API_KEY is not set. Check your .env.local file.\`,
+    );
+  }
+`;
+	const cacheConfig = config.withPreviewMode ? `      enabled: !previewMode, // Disable caching in preview mode
+` : `      enabled: true,
+`;
+	const previewExport = config.withPreviewMode ? `
+/** Check if preview mode is enabled. */
+export function isPreviewMode(): boolean {
+  return getCmsConfig().previewMode;
+}
+` : "";
+	return {
+		path: "src/lib/riverbank-client.ts",
+		content: `import { createRiverbankClient, type RiverbankClient } from '@riverbankcms/sdk/server';
+import config from '../../riverbank.config';
+import { getCmsConfig } from './env';
+
+/**
+ * Singleton client instance.
+ *
+ * The client is created once per process and reused for all subsequent calls.
+ * This provides shared caching across all SDK operations, improving performance
+ * by avoiding redundant API calls within the cache TTL window.
+ *
+ * Note: In Next.js server components, each request typically runs in a fresh
+ * context, so cache is effectively per-request unless using persistent processes.
+ * The singleton pattern primarily benefits scenarios with multiple SDK calls
+ * within a single request or when running in long-lived processes.
+ */
+let clientInstance: RiverbankClient | null = null;
+
+/**
+ * Get the configured Riverbank SDK client (singleton).
+ *
+ * Returns a cached client instance, creating one if it doesn't exist.
+ * The client handles:
+ * - API authentication via environment-specific API key
+ * - Request caching (300s TTL, 100 entries max, shared across all calls)
+ * - Type-safe API responses
+ *
+ * Configuration is read based on RIVERBANK_ENV (local | remote).
+ *
+ * @returns The singleton RiverbankClient instance
+ * @throws Error if required environment variables are not set
+ */
+export function getRiverbankClient(): RiverbankClient {
+  if (clientInstance) return clientInstance;
+
+${previewConfig}
+
+  if (!dashboardUrl) {
+    throw new Error(
+      \`RIVERBANK_\${env.toUpperCase()}_DASHBOARD_URL is not set. Check your .env.local file.\`
+    );
+  }
+
+  clientInstance = createRiverbankClient({
+    apiKey: key,
+    baseUrl: \`\${dashboardUrl}/api\`,
+    cache: {
+${cacheConfig}
+      ttl: 300,
+      maxSize: 100,
+    },
+  });
+
+  return clientInstance;
+}
+
+/**
+ * Get the site ID from riverbank.config.ts
+ */
+export function getSiteId(): string {
+  return config.siteId;
+}
+
+/**
+ * Check if preview mode is enabled
+ */
+${previewExport}
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/riverbank-config.ts
+function riverbankConfigTemplate(config) {
+	const previewDashboardConfig = config.withPreviewMode ? `
+  // Dashboard preview links should pass short-lived auth tokens for editable preview mode.
+  dashboard: {
+    previewEditingEnabled: true,
+  },
+` : "";
+	const portalConfig = config.withPortalAuth ? `
+  // Enable portal session token plumbing for customer portal blocks.
+  enablePortal: true,
+` : "";
+	return {
+		path: "riverbank.config.ts",
+		content: `import { defineConfig } from '@riverbankcms/sdk/config';
+import { getCmsConfig } from './src/lib/env';
+import { contentTypes } from './src/config/content-types';
+import { customBlocks } from './src/config/custom-blocks';
+import { blockFieldExtensions, blockFieldOptions } from './src/config/block-extensions';
+
+const { siteId, env } = getCmsConfig();
+
+if (!siteId) {
+  throw new Error(
+    \`RIVERBANK_\${env.toUpperCase()}_SITE_ID is not set. Check your .env.local file.\`
+  );
+}
+
+export default defineConfig({
+  siteId,
+${previewDashboardConfig}
+${portalConfig}
+
+  // Schema/config surfaces sync with \`riverbankcms push-config\`.
+  // Document content lives in content/** and syncs with \`riverbankcms push\`.
+  content: {
+    contentTypes,
+  },
+
+  // Block field options (customize existing field options)
+  blockFieldOptions,
+
+  // Block field extensions (add custom fields to built-in blocks)
+  blockFieldExtensions,
+
+  // Custom blocks
+  customBlocks,
+
+  // Sync configuration - allow updating existing entries
+  sync: {
+    existingEntries: 'update',
+  },
+
+});
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/rendering.ts
+function renderingTemplate() {
+	return {
+		path: "src/lib/rendering.ts",
+		content: `import type { SdkOverrideOnlyRendering } from '@riverbankcms/sdk/rendering';
+
+/** The host owns all block rendering and the runtime styling wrapper. */
+export const SITE_RENDERING = {
+  kind: 'overrides-only',
+  runtime: { kind: 'none' },
+} satisfies SdkOverrideOnlyRendering;
+`
+	};
+}
+
+//#endregion
+//#region src/scaffold/templates/starter-content.ts
+function jsonTemplate(path$1, value) {
+	return {
+		path: path$1,
+		content: `${JSON.stringify(value, null, 2)}\n`
+	};
+}
+function richTextDoc(text) {
+	return {
+		type: "doc",
+		content: [{
+			type: "paragraph",
+			content: [{
+				type: "text",
+				text
+			}]
+		}]
+	};
+}
+function slugifySiteName(siteName) {
+	const slug = siteName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug || "starter-site";
+}
+function starterEntryTemplates(config) {
+	const templates = [];
+	const siteSlug = slugifySiteName(config.siteName);
+	const contentTypes = config.contentTypes ?? {};
+	if (contentTypes.withBlog) {
+		templates.push(jsonTemplate("content/entries/post/welcome.json", {
+			identifier: "welcome",
+			slug: "welcome",
+			status: "draft",
+			data: {
+				title: `Welcome to ${config.siteName}`,
+				excerpt: "A short starter post you can edit or replace.",
+				content: richTextDoc(`Use this first post to introduce ${config.siteName}.`),
+				author: "Team"
+			}
+		}));
+	}
+	if (contentTypes.withTestimonials) {
+		templates.push(jsonTemplate("content/entries/testimonial/example-testimonial.json", {
+			identifier: "example-testimonial",
+			status: "draft",
+			data: {
+				name: "Example Customer",
+				jobTitle: "Founder",
+				company: config.siteName,
+				body: richTextDoc("Add a real testimonial here when you are ready.")
+			}
+		}));
+	}
+	if (contentTypes.withEvents) {
+		templates.push(jsonTemplate("content/entries/event/starter-event.json", {
+			identifier: "starter-event",
+			slug: "starter-event",
+			status: "draft",
+			data: {
+				title: "Starter event",
+				excerpt: "A starter event entry you can edit or replace.",
+				startsAt: "2026-01-01T10:00:00.000Z",
+				endsAt: "2026-01-01T11:00:00.000Z",
+				location: "Online",
+				content: richTextDoc("Add the event details here.")
+			}
+		}));
+	}
+	if (contentTypes.withPortfolio) {
+		templates.push(jsonTemplate("content/entries/portfolio-item/starter-project.json", {
+			identifier: "starter-project",
+			slug: "starter-project",
+			status: "draft",
+			data: {
+				title: `${config.siteName} project`,
+				"short-description": "A starter portfolio item you can edit or replace.",
+				"full-description": richTextDoc(`Describe a ${siteSlug} project here.`),
+				content: richTextDoc("Add the project story here.")
+			}
+		}));
+	}
+	return templates;
+}
+function starterContentTemplates(config) {
+	return [
+		jsonTemplate("content/pages/home.json", {
+			identifier: "home",
+			title: config.siteName,
+			path: "/",
+			status: "published",
+			blocks: []
+		}),
+		jsonTemplate("content/navigation.json", { menus: [{
+			identifier: "main",
+			name: "Main",
+			isPrimary: true,
+			items: [{
+				label: "Home",
+				link: {
+					kind: "page",
+					identifier: "home"
+				}
+			}]
+		}] }),
+		jsonTemplate("content/settings.json", {
+			homepageId: "home",
+			seoDefaults: {
+				title: config.siteName,
+				description: `${config.siteName} website`,
+				allowIndexingInProduction: true
+			}
+		}),
+		...starterEntryTemplates(config)
+	];
+}
+
+//#endregion
+//#region src/scaffold/templates/index.ts
+function generateAllTemplates(config) {
+	const preview = config.withPreviewMode ? [previewKeepAliveRouteTemplate(), previewModeClientTemplate()] : [];
+	const portal = config.withPortalAuth ? [portalCallbackRouteTemplate(), portalLogoutRouteTemplate()] : [];
+	return [
+		gitignoreTemplate(),
+		envConfigTemplate(config),
+		envExampleTemplate(config),
+		envStagingExampleTemplate(),
+		riverbankConfigTemplate(config),
+		riverbankClientTemplate(config),
+		renderingTemplate(),
+		nextConfigTemplate(),
+		globalsCssTemplate(config),
+		layoutTemplate(config),
+		catchAllPageTemplate(config),
+		errorTemplate(),
+		notFoundTemplate(),
+		proxyTemplate({ withPreviewMode: config.withPreviewMode }),
+		...preview,
+		revalidateRouteTemplate(),
+		...portal,
+		cmsPushStagingTemplate(),
+		contentTypesTemplate(config.contentTypes ?? {}),
+		customBlocksTemplate(),
+		blockExtensionsTemplate(),
+		blockOverridesTemplate(),
+		dataLoaderOverridesTemplate(),
+		...starterContentTemplates(config),
+		exampleTestTemplate(),
+		readmeTemplate(config),
+		agentsMdTemplate()
+	];
+}
+
+//#endregion
+//#region src/scaffold/plan.ts
+const REVALIDATE_ROUTE = "src/app/api/revalidate/route.ts";
+const PREVIEW_PATHS = new Set(["src/app/api/preview/keep-alive/route.ts", "src/components/preview/SdkPreviewModeClient.tsx"]);
+function safeScaffoldTargetPath(path$1) {
+	if (!path$1 || path$1.includes("\\") || path$1.includes("\0") || path$1.startsWith("/")) return false;
+	const normalized = path$1.split("/").join(sep);
+	const fromRoot = relative("", normalized);
+	return fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !normalized.split(sep).includes("");
+}
+function parseText(value, maxLength) {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim();
+	return normalized.length > 0 && normalized.length <= maxLength ? normalized : undefined;
+}
+function parseSlug(value) {
+	const slug = parseText(value, 120);
+	return slug && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug) ? slug : undefined;
+}
+function parseDashboardUrl(value) {
+	const text = parseText(value, 2048);
+	if (!text) return undefined;
+	try {
+		const url = new URL(text);
+		if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+		if (url.username || url.password || url.search || url.hash) return undefined;
+		return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+	} catch {
+		return undefined;
+	}
+}
+function validPackageSource(input) {
+	return input.tag === "npm" && input.ranges.sdk.trim().length > 0 && input.ranges.cli.trim().length > 0;
+}
+function validateManifest(files, features) {
+	const seen = new Set();
+	for (const file of files) {
+		if (!safeScaffoldTargetPath(file.path)) return {
+			tag: "unsafe_template_path",
+			path: file.path
+		};
+		if (seen.has(file.path)) return {
+			tag: "duplicate_template_path",
+			path: file.path
+		};
+		seen.add(file.path);
+	}
+	if (!seen.has(REVALIDATE_ROUTE)) return { tag: "missing_revalidate_route" };
+	const hasPreviewPaths = [...seen].some((path$1) => PREVIEW_PATHS.has(path$1));
+	const hasPreviewImports = files.filter((file) => PREVIEW_PATHS.has(file.path)).some((file) => file.content.includes("@riverbankcms/sdk/preview-next"));
+	if (features.preview === "enabled" && (!hasPreviewPaths || !hasPreviewImports)) return { tag: "preview_manifest_mismatch" };
+	if (features.preview === "disabled" && (hasPreviewPaths || hasPreviewImports)) return { tag: "preview_manifest_mismatch" };
+	return undefined;
+}
+function deriveScaffoldPlan(input) {
+	const localManifest = deriveScaffoldLocalManifest({
+		projectPath: input.projectPath,
+		features: input.features
+	});
+	if (!localManifest.ok) return err(localManifest.error);
+	const { projectPath, features } = localManifest.value;
+	const parsedSiteId = parseSiteId(input.siteId);
+	if (!parsedSiteId.ok) return err({
+		tag: "invalid_site_id",
+		value: input.siteId
+	});
+	const siteSlug = parseSlug(input.siteSlug);
+	if (!siteSlug) return err({
+		tag: "invalid_site_slug",
+		value: input.siteSlug
+	});
+	const siteName = parseText(input.siteName, 160);
+	if (!siteName) return err({
+		tag: "invalid_site_name",
+		value: input.siteName
+	});
+	const dashboardUrl = parseDashboardUrl(input.dashboardUrl);
+	if (!dashboardUrl) return err({
+		tag: "invalid_dashboard_url",
+		value: input.dashboardUrl
+	});
+	if (typeof input.devPort !== "number" || !Number.isInteger(input.devPort) || input.devPort < 1 || input.devPort > 65535) {
+		return err({
+			tag: "invalid_dev_port",
+			value: input.devPort
+		});
+	}
+	if (!validPackageSource(input.packageSource)) {
+		return err({
+			tag: "invalid_package_source",
+			field: input.packageSource.ranges.sdk.trim().length > 0 ? "cli" : "sdk"
+		});
+	}
+	const templateConfig = {
+		siteId: parsedSiteId.value,
+		siteSlug,
+		dashboardUrl,
+		siteName,
+		devPort: input.devPort,
+		packageRanges: input.packageSource.ranges,
+		withPreviewMode: features.preview === "enabled",
+		withPortalAuth: features.portal === "enabled",
+		contentTypes: features.contentTypes
+	};
+	const files = generateAllTemplates(templateConfig).map((file) => Object.freeze({ ...file }));
+	const manifestError = validateManifest(files, features);
+	if (manifestError) return err(manifestError);
+	const credentialRequirements = features.preview === "enabled" ? {
+		tag: "with_preview",
+		live: true,
+		management: true,
+		preview: true
+	} : {
+		tag: "standard",
+		live: true,
+		management: true,
+		preview: false
+	};
+	return ok(Object.freeze({
+		projectPath,
+		siteId: parsedSiteId.value,
+		siteSlug,
+		siteName,
+		dashboardUrl,
+		devPort: input.devPort,
+		features,
+		packageSource: Object.freeze({
+			tag: "npm",
+			ranges: Object.freeze({ ...input.packageSource.ranges })
+		}),
+		credentialRequirements,
+		files: Object.freeze(files)
+	}));
+}
+
+//#endregion
+export { prepareScaffoldExecution as a, LOCAL_PACKAGE_VENDOR_DIR as c, loadGeneratedPackageRanges as d, preflightScaffoldTargets as i, deriveGeneratedPackageRanges as l, createScaffoldCompletion as n, writeScaffoldFiles as o, preflightScaffoldPlan as r, deriveScaffoldLocalManifest as s, deriveScaffoldPlan as t, findPackageManifestPath as u };