blodemd 0.0.8 → 0.0.10

package/dist/cli.mjs

@@ -3,9 +3,10 @@ import { createRequire } from "node:module";
 import { spawn, spawnSync } from "node:child_process";
 import fs, { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path, { join } from "node:path";
-import { confirm, intro, isCancel, log, password, spinner } from "@clack/prompts";
+import { confirm, intro, isCancel, log, password, select, spinner, text } from "@clack/prompts";
+import { shouldIgnoreRootDocsFile, slugify } from "@repo/common";
 import chalk from "chalk";
-import { Command } from "commander";
+import { Command, InvalidArgumentError } from "commander";
 import open from "open";
 import { homedir } from "node:os";
 import { once } from "node:events";
@@ -116,24 +117,36 @@ const refreshAccessToken = (config, refreshToken) => {
 //#endregion
 //#region src/storage.ts
 const isRecord = (value) => typeof value === "object" && value !== null;
+const readNullableString = (value) => {
+	if (value === void 0 || value === null) return null;
+	return typeof value === "string" ? value : void 0;
+};
+const parseStoredSessionUser = (value) => {
+	if (value === void 0 || value === null) return null;
+	if (!isRecord(value) || typeof value.id !== "string") return;
+	const email = readNullableString(value.email);
+	if (email === void 0) return;
+	return {
+		email,
+		id: value.id
+	};
+};
 const parseStoredAuthSession = (value) => {
 	if (!isRecord(value)) return null;
 	if (typeof value.accessToken !== "string") return null;
-	if (value.refreshToken !== null && typeof value.refreshToken !== "string") return null;
-	if (value.expiresAt !== null && typeof value.expiresAt !== "string") return null;
-	const { user } = value;
-	if (user !== null && (!isRecord(user) || typeof user.id !== "string" || user.email !== null && typeof user.email !== "string")) return null;
+	const refreshToken = readNullableString(value.refreshToken);
+	if (refreshToken === void 0) return null;
+	const expiresAt = readNullableString(value.expiresAt);
+	if (expiresAt === void 0) return null;
+	const user = parseStoredSessionUser(value.user);
+	if (user === void 0) return null;
 	if (typeof value.createdAt !== "string") return null;
-	const parsedUser = user === null || !isRecord(user) ? null : {
-		email: user.email ?? null,
-		id: user.id
-	};
 	return {
 		accessToken: value.accessToken,
 		createdAt: value.createdAt,
-		expiresAt: value.expiresAt ?? null,
-		refreshToken: value.refreshToken ?? null,
-		user: parsedUser
+		expiresAt,
+		refreshToken,
+		user
 	};
 };
 const parseApiKeyCredentials = (value) => {
@@ -144,20 +157,34 @@ const parseApiKeyCredentials = (value) => {
 		type: "api-key"
 	};
 };
+const createInvalidCredentialsError = (detail) => new CliError(detail ? `Invalid credentials format in ${CREDENTIALS_FILE}: ${detail}` : `Invalid credentials format in ${CREDENTIALS_FILE}`, EXIT_CODES.ERROR);
+const parseAuthFile = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new CliError(`Invalid credentials JSON in ${CREDENTIALS_FILE}`, EXIT_CODES.ERROR);
+	}
+	if (!isRecord(parsed) || parsed.version !== 1) throw createInvalidCredentialsError();
+	const hasSession = Object.hasOwn(parsed, "session");
+	const hasApiKey = Object.hasOwn(parsed, "apiKey");
+	const session = hasSession && parsed.session !== void 0 ? parseStoredAuthSession(parsed.session) : void 0;
+	const apiKey = hasApiKey && parsed.apiKey !== void 0 ? parseApiKeyCredentials(parsed.apiKey) : void 0;
+	if (hasSession && parsed.session !== void 0 && !session) throw createInvalidCredentialsError("stored session is malformed.");
+	if (hasApiKey && parsed.apiKey !== void 0 && !apiKey) throw createInvalidCredentialsError("stored API key is malformed.");
+	return {
+		apiKey: apiKey ?? void 0,
+		session: session ?? void 0,
+		version: 1
+	};
+};
 const readAuthFile = async () => {
 	try {
-		const raw = await readFile(CREDENTIALS_FILE, "utf8");
-		const parsed = JSON.parse(raw);
-		if (!isRecord(parsed) || parsed.version !== 1) throw new CliError(`Invalid credentials format in ${CREDENTIALS_FILE}`, EXIT_CODES.ERROR);
-		return {
-			apiKey: parseApiKeyCredentials(parsed.apiKey) ?? void 0,
-			session: parseStoredAuthSession(parsed.session) ?? void 0,
-			version: 1
-		};
+		return parseAuthFile(await readFile(CREDENTIALS_FILE, "utf8"));
 	} catch (error) {
 		if (isRecord(error) && error.code === "ENOENT") return null;
 		if (error instanceof CliError) throw error;
-		return null;
+		throw new CliError(`Failed to read credentials file at ${CREDENTIALS_FILE}`, EXIT_CODES.ERROR);
 	}
 };
 const writeAuthFile = async (data) => {
@@ -291,11 +318,30 @@ const resolveTokenStatus = (token) => {
 	};
 };
 //#endregion
+//#region src/validation.ts
+const MAX_PORT = 65535;
+const parsePositiveInteger = (value, label) => {
+	const trimmed = value.trim();
+	if (!/^\d+$/u.test(trimmed)) throw new CliError(`${label} must be a positive integer.`, EXIT_CODES.VALIDATION);
+	const parsed = Number(trimmed);
+	if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new CliError(`${label} must be a positive integer.`, EXIT_CODES.VALIDATION);
+	return parsed;
+};
+const parsePort = (value, label = "Port") => {
+	const parsed = parsePositiveInteger(value, label);
+	if (parsed > MAX_PORT) throw new CliError(`${label} must be between 1 and ${MAX_PORT}.`, EXIT_CODES.VALIDATION);
+	return parsed;
+};
+//#endregion
 //#region src/site-config.ts
 const CONFIG_FILE$2 = "docs.json";
+const getSiteConfigHint = (errors) => {
+	if (errors.includes(`${CONFIG_FILE$2} not found.`)) return `Make sure ${CONFIG_FILE$2} exists in the selected docs directory or pass the docs directory explicitly.`;
+	return `Fix the ${CONFIG_FILE$2} errors above and try again.`;
+};
 const loadValidatedSiteConfig = async (root) => {
 	const result = await loadSiteConfig(createFsSource(root));
-	if (!result.ok) throw new CliError(result.errors.join("\n"), EXIT_CODES.VALIDATION, `Make sure ${CONFIG_FILE$2} exists and is valid JSON.`);
+	if (!result.ok) throw new CliError(result.errors.join("\n"), EXIT_CODES.VALIDATION, getSiteConfigHint(result.errors));
 	return {
 		config: result.config,
 		warnings: result.warnings
@@ -304,6 +350,12 @@ const loadValidatedSiteConfig = async (root) => {
 //#endregion
 //#region src/dev/resolve-root.ts
 const CONFIG_FILE$1 = "docs.json";
+const ROOT_CANDIDATES = [
+	"",
+	"docs",
+	path.join("apps", "docs")
+];
+const NESTED_DOCS_ROOT_CONTAINERS = [path.join("content"), path.join("apps", "docs", "content")];
 const fileExists$1 = async (filePath) => {
 	try {
 		await fs.access(filePath);
@@ -312,17 +364,30 @@ const fileExists$1 = async (filePath) => {
 		return false;
 	}
 };
-const resolveDocsRoot = async (dir) => {
-	if (dir) return path.resolve(process.cwd(), dir);
-	const candidates = [
-		process.cwd(),
-		path.join(process.cwd(), "docs"),
-		path.join(process.cwd(), "apps/docs")
-	];
+const resolveDocsRoot = async (dir, cwd = process.cwd()) => {
+	const currentWorkingDir = path.resolve(cwd);
+	if (dir) return path.resolve(currentWorkingDir, dir);
+	const candidates = ROOT_CANDIDATES.map((candidate) => path.join(currentWorkingDir, candidate));
 	for (const candidate of candidates) if (await fileExists$1(path.join(candidate, CONFIG_FILE$1))) return candidate;
-	return process.cwd();
+	for (const container of NESTED_DOCS_ROOT_CONTAINERS) {
+		const containerPath = path.join(currentWorkingDir, container);
+		if (!await fileExists$1(containerPath)) continue;
+		const docsRoots = (await fs.readdir(containerPath, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => path.join(containerPath, entry.name)).toSorted((left, right) => {
+			const preferredNames = ["docs", "example"];
+			const leftRank = preferredNames.indexOf(path.basename(left));
+			const rightRank = preferredNames.indexOf(path.basename(right));
+			if (leftRank !== rightRank) {
+				if (leftRank === -1) return 1;
+				if (rightRank === -1) return -1;
+				return leftRank - rightRank;
+			}
+			return left.localeCompare(right);
+		});
+		for (const candidate of docsRoots) if (await fileExists$1(path.join(candidate, CONFIG_FILE$1))) return candidate;
+	}
+	return currentWorkingDir;
 };
-const validateDocsRoot = async (root) => await loadValidatedSiteConfig(root);
+const validateDocsRoot = loadValidatedSiteConfig;
 //#endregion
 //#region src/dev/watcher.ts
 const INVALIDATE_ENDPOINT = "/blodemd-dev/invalidate";
@@ -393,11 +458,9 @@ const RUNTIME_EXCLUDE_DIRS = new Set([
 	".turbo",
 	"node_modules"
 ]);
-const parsePositiveInteger$1 = (value, label) => {
-	const parsed = Number.parseInt(value, 10);
-	if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`${label} must be a positive integer.`, EXIT_CODES.VALIDATION);
-	return parsed;
-};
+const STANDALONE_RUNTIME_MAX_AGE_MS = 1440 * 60 * 1e3;
+const STANDALONE_RUNTIME_PREFIX = "standalone-runtime-";
+const TURBOPACK_ARGS = ["dev", "--turbopack"];
 const fileExists = async (filePath) => {
 	try {
 		await fs.access(filePath);
@@ -406,6 +469,35 @@ const fileExists = async (filePath) => {
 		return false;
 	}
 };
+const resolveCommonAncestor = (pathsToCompare) => {
+	const [firstPath, ...restPaths] = pathsToCompare;
+	if (!firstPath) return path.sep;
+	const first = path.resolve(firstPath);
+	const { root } = path.parse(first);
+	const firstSegments = first.slice(root.length).split(path.sep).filter(Boolean);
+	const sharedSegments = [];
+	for (const [index, segment] of firstSegments.entries()) {
+		if (!restPaths.every((candidatePath) => {
+			const candidate = path.resolve(candidatePath);
+			if (path.parse(candidate).root !== root) return false;
+			return candidate.slice(root.length).split(path.sep).filter(Boolean)[index] === segment;
+		})) break;
+		sharedSegments.push(segment);
+	}
+	return path.join(root, ...sharedSegments);
+};
+const cleanupStandaloneRuntimeRoots = async (configDir, maxAgeMs = STANDALONE_RUNTIME_MAX_AGE_MS) => {
+	const cutoff = Date.now() - maxAgeMs;
+	const entries = await fs.readdir(configDir, { withFileTypes: true });
+	await Promise.all(entries.filter((entry) => entry.isDirectory() && entry.name.startsWith(STANDALONE_RUNTIME_PREFIX)).map(async (entry) => {
+		const entryPath = path.join(configDir, entry.name);
+		if ((await fs.stat(entryPath)).mtimeMs >= cutoff) return;
+		await fs.rm(entryPath, {
+			force: true,
+			recursive: true
+		});
+	}));
+};
 const probePortAvailability = async (port) => {
 	const server = createServer();
 	const listening = (async () => {
@@ -481,44 +573,53 @@ const isStandaloneCliInstall = async (cliPackageRoot) => {
 		return cliPackageRoot.split(path.sep).includes("node_modules");
 	}
 };
+const createStandaloneRuntimeRoot = async (configDir = CONFIG_DIR) => {
+	await fs.mkdir(configDir, { recursive: true });
+	await cleanupStandaloneRuntimeRoots(configDir);
+	return await fs.mkdtemp(path.join(configDir, STANDALONE_RUNTIME_PREFIX));
+};
 const materializeStandaloneRuntime = async (cliPackageRoot) => {
-	const runtimeRoot = path.join(CONFIG_DIR, "standalone-runtime");
-	await fs.rm(runtimeRoot, {
-		force: true,
-		recursive: true
-	});
-	await fs.mkdir(runtimeRoot, { recursive: true });
-	for (const dir of [
-		"dev-server",
-		"docs",
-		"packages"
-	]) await copyStandaloneTree(path.join(cliPackageRoot, dir), path.join(runtimeRoot, dir));
-	await fs.symlink(path.join(cliPackageRoot, "node_modules"), path.join(runtimeRoot, "node_modules"), process.platform === "win32" ? "junction" : "dir");
-	await fs.writeFile(path.join(runtimeRoot, "dev-server", "package.json"), `${JSON.stringify({
-		dependencies: {
-			next: "16.2.1",
-			react: "^19.2.0",
-			"react-dom": "^19.2.0"
-		},
-		devDependencies: {
-			"@types/node": "^22.19.15",
-			"@types/react": "19.2.14",
-			"@types/react-dom": "19.2.3",
-			typescript: "6.0.2"
-		},
-		name: "blodemd-dev-server",
-		private: true,
-		type: "module"
-	}, null, 2)}\n`);
-	return {
-		devServerDir: path.join(runtimeRoot, "dev-server"),
-		packagesDir: path.join(runtimeRoot, "packages")
-	};
+	const runtimeRoot = await createStandaloneRuntimeRoot();
+	try {
+		for (const dir of [
+			"dev-server",
+			"docs",
+			"packages"
+		]) await copyStandaloneTree(path.join(cliPackageRoot, dir), path.join(runtimeRoot, dir));
+		await fs.symlink(path.join(cliPackageRoot, "node_modules"), path.join(runtimeRoot, "node_modules"), process.platform === "win32" ? "junction" : "dir");
+		await fs.mkdir(path.join(runtimeRoot, "dev-server", "node_modules"), { recursive: true });
+		await fs.symlink(path.join(runtimeRoot, "packages", "@repo"), path.join(runtimeRoot, "dev-server", "node_modules", "@repo"), process.platform === "win32" ? "junction" : "dir");
+		await fs.writeFile(path.join(runtimeRoot, "dev-server", "package.json"), `${JSON.stringify({
+			dependencies: {
+				next: "16.2.1",
+				react: "^19.2.0",
+				"react-dom": "^19.2.0"
+			},
+			devDependencies: {
+				"@types/node": "^22.19.15",
+				"@types/react": "19.2.14",
+				"@types/react-dom": "19.2.3",
+				typescript: "6.0.2"
+			},
+			name: "blodemd-dev-server",
+			private: true,
+			type: "module"
+		}, null, 2)}\n`);
+		return {
+			devServerDir: path.join(runtimeRoot, "dev-server"),
+			runtimeRoot
+		};
+	} catch (error) {
+		await fs.rm(runtimeRoot, {
+			force: true,
+			recursive: true
+		});
+		throw error;
+	}
 };
 /**
-* Check if a shipped dev-server exists alongside the CLI (npm-installed mode).
-* Verifies both the dev-server directory AND that `next` is resolvable
-* (it's a dependency when npm-installed, but not in the monorepo).
+* Check if a shipped dev-server exists alongside an installed CLI package.
+* We only use standalone mode when the package root lives under `node_modules`.
 */
 const findStandaloneDevServer = async (cliPackageRoot) => {
 	const devServerDir = path.join(cliPackageRoot, "dev-server");
@@ -534,7 +635,7 @@ const findStandaloneDevServer = async (cliPackageRoot) => {
 		devServerDir: runtime.devServerDir,
 		mode: "standalone",
 		nextPackageRoot: cliPackageRoot,
-		packagesDir: runtime.packagesDir
+		runtimeRoot: runtime.runtimeRoot
 	};
 };
 /**
@@ -567,36 +668,39 @@ const resolveDevServer = async (cliFilePath) => {
 		repoRoot: await findMonorepoRoot(path.dirname(cliFilePath))
 	};
 };
-const spawnDevServer = (server, { root, port }) => {
-	if (server.mode === "standalone") {
-		const nextBin = resolveNextBin(server.nextPackageRoot);
-		return spawn(process.execPath, [
-			nextBin,
+const buildDevServerLaunch = (server, { root, port }) => {
+	if (server.mode === "standalone") return {
+		args: [resolveNextBin(server.nextPackageRoot), ...TURBOPACK_ARGS],
+		command: process.execPath,
+		cwd: server.devServerDir,
+		env: {
+			...process.env,
+			BLODEMD_PACKAGES_DIR: path.join(server.runtimeRoot, "packages"),
+			BLODEMD_TURBOPACK_ROOT: resolveCommonAncestor([server.nextPackageRoot, server.runtimeRoot]),
+			DOCS_ROOT: root,
+			PORT: String(port)
+		}
+	};
+	return {
+		args: [
+			"run",
 			"dev",
-			"--webpack"
-		], {
-			cwd: server.devServerDir,
-			env: {
-				...process.env,
-				BLODEMD_PACKAGES_DIR: server.packagesDir,
-				DOCS_ROOT: root,
-				NODE_PATH: [server.packagesDir, process.env.NODE_PATH].filter(Boolean).join(path.delimiter),
-				PORT: String(port)
-			},
-			stdio: "inherit"
-		});
-	}
-	return spawn(process.platform === "win32" ? "npm.cmd" : "npm", [
-		"run",
-		"dev",
-		"--workspace=dev-server"
-	], {
+			"--workspace=dev-server"
+		],
+		command: process.platform === "win32" ? "npm.cmd" : "npm",
 		cwd: server.repoRoot,
 		env: {
 			...process.env,
 			DOCS_ROOT: root,
 			PORT: String(port)
-		},
+		}
+	};
+};
+const spawnDevServer = (server, options) => {
+	const launch = buildDevServerLaunch(server, options);
+	return spawn(launch.command, launch.args, {
+		cwd: launch.cwd,
+		env: launch.env,
 		stdio: "inherit"
 	});
 };
@@ -615,16 +719,35 @@ const waitForServer = async ({ child, port }) => {
 	}
 	throw new CliError("Timed out waiting for the local dev server to start.", EXIT_CODES.ERROR);
 };
-const devCommand = async ({ dir, openBrowser, port: portValue }) => {
-	intro(chalk.bold("blodemd dev"));
+const defaultDevCommandDependencies = {
+	createWatcher: createDevWatcher,
+	getCliFilePath: () => fileURLToPath(import.meta.url),
+	getIntro: intro,
+	getLog: log,
+	getOpen: open,
+	parsePortValue: parsePort,
+	removeDirectory: fs.rm,
+	resolveDevPortValue: resolveDevPort,
+	resolveDocsRootValue: resolveDocsRoot,
+	resolveServer: resolveDevServer,
+	shutdownChild: shutdownChildProcess,
+	spawnServer: spawnDevServer,
+	validateDocsRootValue: validateDocsRoot,
+	waitForServerReady: waitForServer
+};
+const devCommand = async ({ dir, openBrowser, port: portValue }, dependencies = defaultDevCommandDependencies) => {
+	const cliLog = dependencies.getLog;
+	dependencies.getIntro(chalk.bold("blodemd dev"));
 	try {
-		const resolvedPort = await resolveDevPort(parsePositiveInteger$1(portValue, "Port"));
-		const root = await resolveDocsRoot(dir);
-		await validateDocsRoot(root);
-		const server = await resolveDevServer(fileURLToPath(import.meta.url));
+		const port = dependencies.parsePortValue(portValue);
+		const resolvedPort = await dependencies.resolveDevPortValue(port);
+		const root = await dependencies.resolveDocsRootValue(dir);
+		await dependencies.validateDocsRootValue(root);
+		const cliFilePath = dependencies.getCliFilePath();
+		const server = await dependencies.resolveServer(cliFilePath);
 		const localUrl = `http://localhost:${resolvedPort}`;
-		log.info(`Docs root: ${chalk.cyan(root)}`);
-		const child = spawnDevServer(server, {
+		cliLog.info(`Docs root: ${chalk.cyan(root)}`);
+		const child = dependencies.spawnServer(server, {
 			port: resolvedPort,
 			root
 		});
@@ -637,21 +760,25 @@ const devCommand = async ({ dir, openBrowser, port: portValue }) => {
 				await watcher.close();
 				watcher = null;
 			}
-			await shutdownChildProcess(child);
+			await dependencies.shutdownChild(child);
+			if (server.mode === "standalone") await dependencies.removeDirectory(server.runtimeRoot, {
+				force: true,
+				recursive: true
+			});
 		};
 		process.once("SIGINT", closeAll);
 		process.once("SIGTERM", closeAll);
 		try {
-			await waitForServer({
+			await dependencies.waitForServerReady({
 				child,
 				port: resolvedPort
 			});
-			watcher = await createDevWatcher({
+			watcher = await dependencies.createWatcher({
 				port: resolvedPort,
 				root
 			});
-			log.success(`Dev server running at ${chalk.cyan(localUrl)}`);
-			if (openBrowser) await open(localUrl);
+			cliLog.success(`Dev server running at ${chalk.cyan(localUrl)}`);
+			if (openBrowser) await dependencies.getOpen(localUrl);
 			const [code, signal] = await once(child, "exit");
 			if (shuttingDown || signal === "SIGINT" || signal === "SIGTERM") return;
 			if (code !== 0) throw new CliError(`The local dev server exited with code ${code ?? "unknown"}.`, EXIT_CODES.ERROR);
@@ -662,12 +789,434 @@ const devCommand = async ({ dir, openBrowser, port: portValue }) => {
 		}
 	} catch (error) {
 		const cliError = toCliError(error);
-		log.error(cliError.message);
-		if (cliError.hint) log.info(cliError.hint);
+		cliLog.error(cliError.message);
+		if (cliError.hint) cliLog.info(cliError.hint);
 		process.exitCode = cliError.exitCode;
 	}
 };
 //#endregion
+//#region src/fs-utils.ts
+const writeFileIfMissing = async (filePath, content) => {
+	try {
+		await fs.writeFile(filePath, content, { flag: "wx" });
+	} catch (error) {
+		const { code } = error;
+		if (code === "EEXIST") {
+			if ((await fs.stat(filePath).catch(() => null))?.isFile()) return;
+		}
+		throw error;
+	}
+};
+const writeSymlinkIfMissing = async (filePath, target, options) => {
+	const lstat = options?.lstat ?? fs.lstat;
+	const symlink = options?.symlink ?? fs.symlink;
+	try {
+		await symlink(target, filePath);
+	} catch (error) {
+		const { code } = error;
+		if (code === "EEXIST") {
+			const existing = await lstat(filePath).catch(() => null);
+			if (existing?.isFile() || existing?.isSymbolicLink()) return;
+		}
+		if (options?.fallbackContent && (code === "EINVAL" || code === "ENOTSUP" || code === "EPERM" || code === "UNKNOWN")) {
+			await writeFileIfMissing(filePath, options.fallbackContent);
+			return;
+		}
+		throw error;
+	}
+};
+const findExistingPaths = async (root, relativePaths) => {
+	return (await Promise.all(relativePaths.map(async (relativePath) => {
+		return await fs.lstat(path.join(root, relativePath)).catch(() => null) ? relativePath : null;
+	}))).filter((relativePath) => relativePath !== null).toSorted((left, right) => left.localeCompare(right));
+};
+//#endregion
+//#region src/scaffold.ts
+const SCAFFOLD_TEMPLATES = ["minimal", "starter"];
+const DEFAULT_SCAFFOLD_DIRECTORY = "docs";
+const stringifyJson = (value) => `${JSON.stringify(value, null, 2)}\n`;
+const isScaffoldTemplate = (value) => SCAFFOLD_TEMPLATES.includes(value);
+const normalizeProjectSlug = (value) => slugify(value) || "my-project";
+const resolveScaffoldDirectory = (directory) => directory?.trim() || "docs";
+const deriveDefaultProjectSlug = (directory, cwd) => {
+	const resolvedDirectory = resolveScaffoldDirectory(directory);
+	if (resolvedDirectory === "." || resolvedDirectory === "docs") return normalizeProjectSlug(path.basename(cwd));
+	return normalizeProjectSlug(path.basename(path.resolve(cwd, resolvedDirectory)));
+};
+const validateProjectSlug = (value) => {
+	const trimmed = value?.trim();
+	if (!trimmed) return "Project slug is required.";
+	const normalized = slugify(trimmed);
+	if (!normalized) return "Use at least one letter or number.";
+	if (normalized !== trimmed) return `Use lowercase letters, numbers, and hyphens. Try "${normalized}".`;
+};
+const createMinimalDocsJson = (projectSlug) => ({
+	$schema: "https://blode.md/docs.json",
+	name: projectSlug,
+	navigation: { groups: [{
+		group: "Getting Started",
+		pages: ["index"]
+	}] }
+});
+const createStarterDocsJson = (projectSlug) => ({
+	$schema: "https://blode.md/docs.json",
+	appearance: { default: "system" },
+	contextual: { options: [
+		"copy",
+		"view",
+		"chatgpt",
+		"claude"
+	] },
+	description: "Ship documentation from your terminal.",
+	favicon: "/favicon.svg",
+	logo: {
+		alt: `${projectSlug} logo`,
+		dark: "/logo/dark.svg",
+		light: "/logo/light.svg"
+	},
+	metadata: { timestamp: true },
+	name: projectSlug,
+	navigation: { groups: [{
+		group: "Getting Started",
+		pages: [
+			"index",
+			"quickstart",
+			"development"
+		]
+	}] }
+});
+const claudeInstructions = [
+	"> **First-time setup**: Customize this file for your project. Prompt the user to update terminology, style preferences, and content boundaries before drafting large amounts of docs.",
+	"",
+	"# Documentation project instructions",
+	"",
+	"## About this project",
+	"",
+	"- This is a documentation site built on [Blode.md](https://blode.md)",
+	"- Pages are MDX files with YAML frontmatter",
+	"- Configuration lives in `docs.json`",
+	"- Run `blodemd dev` to preview locally",
+	"- Run `blodemd validate` before publishing",
+	"- Run `blodemd push` to deploy",
+	"",
+	"## Terminology",
+	"",
+	"{/* Add product-specific terms and preferred usage */}",
+	"{/* Example: Use \"workspace\" not \"project\", \"member\" not \"user\" */}",
+	"",
+	"## Style preferences",
+	"",
+	"{/* Add any project-specific style rules below */}",
+	"",
+	"- Use active voice and second person (\"you\")",
+	"- Keep sentences concise and task-oriented",
+	"- Use sentence case for headings",
+	"- Bold UI labels: Click **Settings**",
+	"- Use code formatting for file names, commands, paths, JSON fields, and code references",
+	"",
+	"## Content boundaries",
+	"",
+	"{/* Define what should and shouldn't be documented */}",
+	"{/* Example: Don't document internal admin features */}",
+	"",
+	"## Workflow reminders",
+	"",
+	"- Content lives in MDX files next to `docs.json`.",
+	"- Update `docs.json` when navigation or branding changes.",
+	"- Prefer concise, task-oriented documentation.",
+	"- Run `blodemd validate` before publishing.",
+	""
+].join("\n");
+const createMinimalFiles = (projectSlug) => [{
+	content: stringifyJson(createMinimalDocsJson(projectSlug)),
+	path: "docs.json"
+}, {
+	content: "---\ntitle: Welcome\n---\n\nStart writing your docs here.\n",
+	path: "index.mdx"
+}];
+const createStarterFiles = (projectSlug) => [
+	{
+		content: stringifyJson(createStarterDocsJson(projectSlug)),
+		path: "docs.json"
+	},
+	{
+		content: [
+			"---",
+			"title: Welcome",
+			"description: Start here.",
+			"---",
+			"",
+			"# Welcome",
+			"",
+			"This starter gives you branded assets, repo helper files, and a small docs structure you can rewrite quickly.",
+			"",
+			"![Starter illustration](images/hero-light.svg)",
+			"",
+			"## What is included",
+			"",
+			"- A starter `docs.json` with branding, contextual actions, and navigation.",
+			"- Placeholder brand assets in `/logo` and `/images`.",
+			"- Repo helper files like `.gitignore`, `README.md`, `AGENTS.md`, and `CLAUDE.md`.",
+			"",
+			"## Next steps",
+			"",
+			"- Confirm the `name` field in `docs.json` matches your project slug.",
+			"- Set `description` in `docs.json` to explain your product.",
+			"- Replace the files in `/logo` and `/images` with your own brand assets.",
+			"- Rewrite `CLAUDE.md` with your terminology and writing standards.",
+			"- Update this page, then preview locally with `blodemd dev`.",
+			"",
+			"## Included pages",
+			"",
+			"- [Quickstart](quickstart)",
+			"- [Development](development)",
+			""
+		].join("\n"),
+		path: "index.mdx"
+	},
+	{
+		content: [
+			"---",
+			"title: Quickstart",
+			"description: Get your docs running fast.",
+			"---",
+			"",
+			"# Quickstart",
+			"",
+			"![Setup checklist](images/checks-passed.svg)",
+			"",
+			"1. Confirm the `name` field in `docs.json`.",
+			"2. Update the `description` field to match your product.",
+			"3. Replace the assets in `/logo` and `/images`.",
+			"4. Run `blodemd dev` to preview locally.",
+			"5. Run `blodemd push` when you are ready to publish.",
+			""
+		].join("\n"),
+		path: "quickstart.mdx"
+	},
+	{
+		content: [
+			"---",
+			"title: Development",
+			"description: Work on your docs locally.",
+			"---",
+			"",
+			"# Development",
+			"",
+			"![Dark preview illustration](images/hero-dark.svg)",
+			"",
+			"Preview locally with:",
+			"",
+			"```bash",
+			"blodemd dev",
+			"```",
+			"",
+			"Validate your configuration with:",
+			"",
+			"```bash",
+			"blodemd validate",
+			"```",
+			"",
+			"Keep `CLAUDE.md` current as your product terminology and writing rules evolve.",
+			""
+		].join("\n"),
+		path: "development.mdx"
+	},
+	{
+		content: [
+			"# Documentation starter",
+			"",
+			"This directory was scaffolded with `blodemd new --template starter`.",
+			"",
+			"## What is included",
+			"",
+			"- `docs.json` with branding, contextual actions, and starter navigation",
+			"- `index.mdx`, `quickstart.mdx`, and `development.mdx`",
+			"- Placeholder brand assets in `/logo` and `/images`",
+			"- Repo helper files: `.gitignore`, `README.md`, `AGENTS.md`, and `CLAUDE.md`",
+			"",
+			"## Commands",
+			"",
+			"```bash",
+			"blodemd dev",
+			"blodemd validate",
+			"blodemd push",
+			"```",
+			"",
+			"## Customize",
+			"",
+			"- Confirm the project slug and set the description in `docs.json`.",
+			"- Replace the assets in `/logo` and `/images`.",
+			"- Rewrite `CLAUDE.md` with project-specific terminology and writing rules.",
+			"- Rewrite the starter pages to match your product.",
+			"- Add a `LICENSE` file deliberately if this repo will be public.",
+			""
+		].join("\n"),
+		path: "README.md"
+	},
+	{
+		fallbackContent: claudeInstructions,
+		path: "AGENTS.md",
+		target: "CLAUDE.md",
+		type: "symlink"
+	},
+	{
+		content: claudeInstructions,
+		path: "CLAUDE.md"
+	},
+	{
+		content: [
+			"# dependencies",
+			"node_modules/",
+			"",
+			"# local env files",
+			".env*",
+			"!.env.example",
+			"",
+			"# build and cache",
+			".next/",
+			".turbo/",
+			"coverage/",
+			"dist/",
+			".vercel/",
+			"*.tsbuildinfo",
+			"",
+			"# logs",
+			"*.log",
+			"",
+			"# misc",
+			".DS_Store",
+			""
+		].join("\n"),
+		path: ".gitignore"
+	},
+	{
+		content: [
+			"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\" fill=\"none\">",
+			"  <rect width=\"64\" height=\"64\" rx=\"16\" fill=\"#0D9373\"/>",
+			"  <path d=\"M20 18h14c8.837 0 16 7.163 16 16s-7.163 16-16 16H20V18Z\" fill=\"#CFF6EE\"/>",
+			"  <path d=\"M28 26h6c5.523 0 10 4.477 10 10s-4.477 10-10 10h-6V26Z\" fill=\"#0C3A33\"/>",
+			"</svg>",
+			""
+		].join("\n"),
+		path: "favicon.svg"
+	},
+	{
+		content: [
+			"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 240 64\" fill=\"none\">",
+			"  <rect width=\"64\" height=\"64\" rx=\"16\" fill=\"#0C3A33\"/>",
+			"  <path d=\"M20 18h14c8.837 0 16 7.163 16 16s-7.163 16-16 16H20V18Z\" fill=\"#CFF6EE\"/>",
+			`  <text x="84" y="41" fill="#111827" font-family="Arial, sans-serif" font-size="28" font-weight="700">${projectSlug}</text>`,
+			"</svg>",
+			""
+		].join("\n"),
+		path: "logo/light.svg"
+	},
+	{
+		content: [
+			"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 240 64\" fill=\"none\">",
+			"  <rect width=\"64\" height=\"64\" rx=\"16\" fill=\"#CFF6EE\"/>",
+			"  <path d=\"M20 18h14c8.837 0 16 7.163 16 16s-7.163 16-16 16H20V18Z\" fill=\"#0C3A33\"/>",
+			`  <text x="84" y="41" fill="#F9FAFB" font-family="Arial, sans-serif" font-size="28" font-weight="700">${projectSlug}</text>`,
+			"</svg>",
+			""
+		].join("\n"),
+		path: "logo/dark.svg"
+	},
+	{
+		content: [
+			"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 960 520\" fill=\"none\">",
+			"  <rect width=\"960\" height=\"520\" rx=\"32\" fill=\"#F4FBF8\"/>",
+			"  <rect x=\"48\" y=\"48\" width=\"260\" height=\"424\" rx=\"24\" fill=\"#E1F4EE\"/>",
+			"  <rect x=\"96\" y=\"120\" width=\"164\" height=\"20\" rx=\"10\" fill=\"#0D9373\" opacity=\".25\"/>",
+			"  <rect x=\"96\" y=\"164\" width=\"132\" height=\"16\" rx=\"8\" fill=\"#0D9373\" opacity=\".18\"/>",
+			"  <rect x=\"96\" y=\"204\" width=\"152\" height=\"16\" rx=\"8\" fill=\"#0D9373\" opacity=\".18\"/>",
+			"  <rect x=\"356\" y=\"80\" width=\"556\" height=\"104\" rx=\"24\" fill=\"#0D9373\"/>",
+			"  <rect x=\"388\" y=\"116\" width=\"220\" height=\"18\" rx=\"9\" fill=\"#CFF6EE\"/>",
+			"  <rect x=\"388\" y=\"148\" width=\"156\" height=\"14\" rx=\"7\" fill=\"#CFF6EE\" opacity=\".7\"/>",
+			"  <rect x=\"356\" y=\"216\" width=\"268\" height=\"256\" rx=\"24\" fill=\"#FFFFFF\"/>",
+			"  <rect x=\"388\" y=\"260\" width=\"168\" height=\"16\" rx=\"8\" fill=\"#0C3A33\" opacity=\".18\"/>",
+			"  <rect x=\"388\" y=\"292\" width=\"196\" height=\"16\" rx=\"8\" fill=\"#0C3A33\" opacity=\".12\"/>",
+			"  <rect x=\"656\" y=\"216\" width=\"256\" height=\"256\" rx=\"24\" fill=\"#0C3A33\"/>",
+			"  <rect x=\"692\" y=\"260\" width=\"128\" height=\"16\" rx=\"8\" fill=\"#CFF6EE\" opacity=\".85\"/>",
+			"  <rect x=\"692\" y=\"292\" width=\"152\" height=\"16\" rx=\"8\" fill=\"#CFF6EE\" opacity=\".45\"/>",
+			"  <circle cx=\"804\" cy=\"380\" r=\"52\" fill=\"#0D9373\"/>",
+			"</svg>",
+			""
+		].join("\n"),
+		path: "images/hero-light.svg"
+	},
+	{
+		content: [
+			"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 960 520\" fill=\"none\">",
+			"  <rect width=\"960\" height=\"520\" rx=\"32\" fill=\"#071715\"/>",
+			"  <rect x=\"48\" y=\"48\" width=\"260\" height=\"424\" rx=\"24\" fill=\"#0F2E28\"/>",
+			"  <rect x=\"96\" y=\"120\" width=\"164\" height=\"20\" rx=\"10\" fill=\"#CFF6EE\" opacity=\".18\"/>",
+			"  <rect x=\"96\" y=\"164\" width=\"132\" height=\"16\" rx=\"8\" fill=\"#CFF6EE\" opacity=\".14\"/>",
+			"  <rect x=\"96\" y=\"204\" width=\"152\" height=\"16\" rx=\"8\" fill=\"#CFF6EE\" opacity=\".14\"/>",
+			"  <rect x=\"356\" y=\"80\" width=\"556\" height=\"104\" rx=\"24\" fill=\"#0D9373\"/>",
+			"  <rect x=\"388\" y=\"116\" width=\"220\" height=\"18\" rx=\"9\" fill=\"#E8FFF9\"/>",
+			"  <rect x=\"388\" y=\"148\" width=\"156\" height=\"14\" rx=\"7\" fill=\"#E8FFF9\" opacity=\".6\"/>",
+			"  <rect x=\"356\" y=\"216\" width=\"268\" height=\"256\" rx=\"24\" fill=\"#0C3A33\"/>",
+			"  <rect x=\"388\" y=\"260\" width=\"168\" height=\"16\" rx=\"8\" fill=\"#CFF6EE\" opacity=\".22\"/>",
+			"  <rect x=\"388\" y=\"292\" width=\"196\" height=\"16\" rx=\"8\" fill=\"#CFF6EE\" opacity=\".16\"/>",
+			"  <rect x=\"656\" y=\"216\" width=\"256\" height=\"256\" rx=\"24\" fill=\"#E9FFF8\"/>",
+			"  <rect x=\"692\" y=\"260\" width=\"128\" height=\"16\" rx=\"8\" fill=\"#0C3A33\" opacity=\".24\"/>",
+			"  <rect x=\"692\" y=\"292\" width=\"152\" height=\"16\" rx=\"8\" fill=\"#0C3A33\" opacity=\".12\"/>",
+			"  <circle cx=\"804\" cy=\"380\" r=\"52\" fill=\"#0D9373\"/>",
+			"</svg>",
+			""
+		].join("\n"),
+		path: "images/hero-dark.svg"
+	},
+	{
+		content: [
+			"<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 960 520\" fill=\"none\">",
+			"  <rect width=\"960\" height=\"520\" rx=\"32\" fill=\"#F8FCFA\"/>",
+			"  <rect x=\"60\" y=\"76\" width=\"840\" height=\"368\" rx=\"28\" fill=\"#FFFFFF\" stroke=\"#D7ECE6\" stroke-width=\"4\"/>",
+			"  <rect x=\"108\" y=\"124\" width=\"96\" height=\"96\" rx=\"24\" fill=\"#0D9373\"/>",
+			"  <path d=\"M136 172l18 18 38-48\" stroke=\"#CFF6EE\" stroke-linecap=\"round\" stroke-linejoin=\"round\" stroke-width=\"18\"/>",
+			"  <rect x=\"244\" y=\"132\" width=\"280\" height=\"24\" rx=\"12\" fill=\"#0C3A33\"/>",
+			"  <rect x=\"244\" y=\"176\" width=\"416\" height=\"18\" rx=\"9\" fill=\"#0C3A33\" opacity=\".16\"/>",
+			"  <rect x=\"244\" y=\"214\" width=\"340\" height=\"18\" rx=\"9\" fill=\"#0C3A33\" opacity=\".12\"/>",
+			"  <rect x=\"108\" y=\"280\" width=\"744\" height=\"22\" rx=\"11\" fill=\"#0D9373\" opacity=\".12\"/>",
+			"  <rect x=\"108\" y=\"326\" width=\"520\" height=\"22\" rx=\"11\" fill=\"#0D9373\" opacity=\".12\"/>",
+			"  <rect x=\"108\" y=\"372\" width=\"612\" height=\"22\" rx=\"11\" fill=\"#0D9373\" opacity=\".12\"/>",
+			"</svg>",
+			""
+		].join("\n"),
+		path: "images/checks-passed.svg"
+	}
+];
+const getScaffoldFiles = (template, options) => {
+	const projectSlug = options?.projectSlug ?? "my-project";
+	return template === "starter" ? createStarterFiles(projectSlug) : createMinimalFiles(projectSlug);
+};
+//#endregion
+//#region src/new-flow.ts
+const CREATE_IN_SUBDIRECTORY = "create-in-subdirectory";
+const SCAFFOLD_CURRENT_DIRECTORY = "scaffold-current-directory";
+const CANCEL_SCAFFOLD = "cancel";
+const resolveInitialDirectory = (options) => {
+	if (options.directory) return {
+		directory: options.directory,
+		kind: "target"
+	};
+	if (!options.interactive) return {
+		directory: DEFAULT_SCAFFOLD_DIRECTORY,
+		kind: "target"
+	};
+	if (options.currentDirectoryEntries.length === 0) return {
+		directory: ".",
+		kind: "target"
+	};
+	return { kind: "prompt" };
+};
+const resolveDirectoryFromAction = (action, subdirectory) => {
+	if (action === "scaffold-current-directory") return ".";
+	if (action === "create-in-subdirectory") return subdirectory?.trim() || "docs";
+};
+//#endregion
 //#region src/oauth-callback.ts
 const SUCCESS_HTML = "<!doctype html><html><head><meta charset=\"utf-8\"/><title>Blode.md CLI</title></head><body><h2>Logged in! You can close this tab.</h2></body></html>";
 const escapeHtml = (text) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
@@ -753,8 +1302,7 @@ const MIN_SUPPORTED_NODE_VERSION = [
 	17,
 	0
 ];
-const MAX_SUPPORTED_NODE_MAJOR = 25;
-const SUPPORTED_NODE_RANGE = ">=20.17.0 <25";
+const SUPPORTED_NODE_RANGE = ">=20.17.0";
 const parseVersion = (input) => {
 	const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(input.trim());
 	if (!match) return null;
@@ -779,7 +1327,6 @@ const isSupportedNodeVersion = (version) => {
 	if (!parsed) return false;
 	const [major, minor, patch] = parsed;
 	const [minMajor, minMinor, minPatch] = MIN_SUPPORTED_NODE_VERSION;
-	if (major >= MAX_SUPPORTED_NODE_MAJOR) return false;
 	if (major !== minMajor) return major > minMajor;
 	if (minor !== minMinor) return minor > minMinor;
 	return patch >= minPatch;
@@ -794,8 +1341,7 @@ const readCliVersion = (moduleUrl) => {
 	return JSON.parse(raw).version ?? "0.0.0";
 };
 //#endregion
-//#region src/cli.ts
-const CONFIG_FILE = "docs.json";
+//#region src/upload.ts
 const TEXT_CONTENT_TYPES = {
 	".css": "text/css; charset=utf-8",
 	".html": "text/html; charset=utf-8",
@@ -808,11 +1354,37 @@ const TEXT_CONTENT_TYPES = {
 	".yaml": "application/yaml; charset=utf-8",
 	".yml": "application/yaml; charset=utf-8"
 };
-const ensureFile = async (filePath, content) => {
-	try {
-		await fs.writeFile(filePath, content, { flag: "wx" });
-	} catch {}
+const normalizeRelativePath = (root, filePath) => path.relative(root, filePath).split(path.sep).join("/");
+const getContentType = (filePath) => TEXT_CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+const estimateUploadItemBytes = (item) => item.contentBase64.length + item.path.length + 64;
+const createUploadBatchItem = async (filePath, root, readFile) => {
+	return {
+		contentBase64: (await readFile(filePath)).toString("base64"),
+		contentType: getContentType(filePath),
+		path: normalizeRelativePath(root, filePath)
+	};
 };
+const createUploadBatches = async function* createUploadBatchesGenerator({ files, maxBatchBytes, readFile = fs.readFile, root }) {
+	let currentBatch = [];
+	let currentBatchBytes = 0;
+	for (const filePath of files) {
+		const item = await createUploadBatchItem(filePath, root, readFile);
+		if (shouldIgnoreRootDocsFile(item.path)) continue;
+		const itemBytes = estimateUploadItemBytes(item);
+		if (itemBytes > maxBatchBytes) throw new CliError(`File "${item.path}" is too large to upload in a single request.`, EXIT_CODES.VALIDATION, "Split the file into smaller pieces or raise the server request limit.");
+		if (currentBatch.length > 0 && currentBatchBytes + itemBytes > maxBatchBytes) {
+			yield currentBatch;
+			currentBatch = [];
+			currentBatchBytes = 0;
+		}
+		currentBatch.push(item);
+		currentBatchBytes += itemBytes;
+	}
+	if (currentBatch.length > 0) yield currentBatch;
+};
+//#endregion
+//#region src/cli.ts
+const CONFIG_FILE = "docs.json";
 const readGitValue = (gitArgs) => {
 	const result = spawnSync("git", gitArgs, {
 		encoding: "utf8",
@@ -825,30 +1397,32 @@ const readGitValue = (gitArgs) => {
 	if (result.status !== 0) return;
 	return result.stdout.trim() || void 0;
 };
-const normalizeRelativePath = (root, filePath) => path.relative(root, filePath).split(path.sep).join("/");
 const shouldSkipEntry = (name) => name.startsWith(".") || name === "node_modules";
-const collectFiles = async (root) => {
-	const entries = await fs.readdir(root, { withFileTypes: true });
+const collectFiles = async (root, directory = root) => {
+	const entries = await fs.readdir(directory, { withFileTypes: true });
 	const files = [];
 	for (const entry of entries) {
 		if (shouldSkipEntry(entry.name)) continue;
-		const absolutePath = path.join(root, entry.name);
+		const absolutePath = path.join(directory, entry.name);
+		const relativePath = path.relative(root, absolutePath).split(path.sep).join("/");
 		if (entry.isDirectory()) {
-			files.push(...await collectFiles(absolutePath));
+			files.push(...await collectFiles(root, absolutePath));
 			continue;
 		}
-		if (entry.isFile()) files.push(absolutePath);
+		if (entry.isFile()) {
+			if (shouldIgnoreRootDocsFile(relativePath)) continue;
+			files.push(absolutePath);
+		}
 	}
 	return files.toSorted((left, right) => left.localeCompare(right));
 };
-const getContentType = (filePath) => TEXT_CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
 const readJson = async (response) => {
-	const text = await response.text();
-	if (!text) return null;
+	const responseText = await response.text();
+	if (!responseText) return null;
 	try {
-		return JSON.parse(text);
+		return JSON.parse(responseText);
 	} catch {
-		return text;
+		return responseText;
 	}
 };
 const requestJson = async (url, init, message) => {
@@ -860,11 +1434,6 @@ const requestJson = async (url, init, message) => {
 	}
 	return data;
 };
-const parsePositiveInteger = (value, label) => {
-	const parsed = Number.parseInt(value, 10);
-	if (!Number.isInteger(parsed) || parsed <= 0) throw new CliError(`${label} must be a positive integer.`, EXIT_CODES.VALIDATION);
-	return parsed;
-};
 const reportCommandError = (prefix, error) => {
 	const cliError = toCliError(error);
 	log.error(`${prefix}: ${cliError.message}`);
@@ -872,6 +1441,109 @@ const reportCommandError = (prefix, error) => {
 	log.info("Failed");
 	process.exitCode = cliError.exitCode;
 };
+const parseScaffoldTemplate = (value) => {
+	if (isScaffoldTemplate(value)) return value;
+	throw new InvalidArgumentError(`Expected one of: ${SCAFFOLD_TEMPLATES.join(", ")}.`);
+};
+const parseProjectSlug = (value) => {
+	const validationError = validateProjectSlug(value);
+	if (validationError) throw new InvalidArgumentError(validationError);
+	return value.trim();
+};
+const isInteractiveTerminal = () => process.stdin.isTTY === true && process.stdout.isTTY === true;
+const promptForNoArgDirectoryAction = async () => {
+	const directoryAction = await select({
+		initialValue: CREATE_IN_SUBDIRECTORY,
+		message: "Directory . is not empty. What would you like to do?",
+		options: [
+			{
+				hint: "recommended",
+				label: "Create in a subdirectory",
+				value: CREATE_IN_SUBDIRECTORY
+			},
+			{
+				hint: "scaffold here",
+				label: "Scaffold current directory",
+				value: SCAFFOLD_CURRENT_DIRECTORY
+			},
+			{
+				label: "Cancel",
+				value: CANCEL_SCAFFOLD
+			}
+		]
+	});
+	if (isCancel(directoryAction)) return;
+	return directoryAction;
+};
+const promptForSubdirectoryName = async () => {
+	const subdirectory = await text({
+		initialValue: DEFAULT_SCAFFOLD_DIRECTORY,
+		message: "Subdirectory name",
+		placeholder: DEFAULT_SCAFFOLD_DIRECTORY,
+		validate: (value) => {
+			if (!value?.trim()) return "Subdirectory name is required.";
+		}
+	});
+	if (isCancel(subdirectory)) return;
+	return subdirectory.trim();
+};
+const promptForProjectSlug = async (initialValue) => {
+	const projectSlug = await text({
+		initialValue,
+		message: "Project slug",
+		placeholder: initialValue,
+		validate: validateProjectSlug
+	});
+	if (isCancel(projectSlug)) return;
+	return projectSlug.trim();
+};
+const resolveRequestedDirectory = async (directory, shouldPrompt) => {
+	let currentDirectoryEntries = [];
+	if (!directory && shouldPrompt) currentDirectoryEntries = await fs.readdir(process.cwd());
+	const initialResolution = resolveInitialDirectory({
+		currentDirectoryEntries,
+		directory,
+		interactive: shouldPrompt
+	});
+	if (initialResolution.kind === "target") return { directory: initialResolution.directory };
+	const directoryAction = await promptForNoArgDirectoryAction();
+	if (!directoryAction || directoryAction === "cancel") return;
+	const resolvedDirectory = resolveDirectoryFromAction(directoryAction, directoryAction === "create-in-subdirectory" ? await promptForSubdirectoryName() : void 0);
+	if (!resolvedDirectory) return;
+	return {
+		directory: resolvedDirectory,
+		skipNonEmptyConfirmation: directoryAction === SCAFFOLD_CURRENT_DIRECTORY
+	};
+};
+const confirmScaffoldTarget = async (root, template, shouldPrompt, options) => {
+	const existingTarget = await fs.lstat(root).catch(() => null);
+	if (existingTarget && !existingTarget.isDirectory()) throw new Error(`Target path already exists and is not a directory: ${root}`);
+	if (!existingTarget?.isDirectory()) return true;
+	const existingScaffoldPaths = await findExistingPaths(root, getScaffoldFiles(template).map((file) => file.path));
+	if (existingScaffoldPaths.length > 0) throw new Error(`Target directory already contains scaffold files: ${existingScaffoldPaths.join(", ")}. Use a different directory or remove those files first.`);
+	if ((await fs.readdir(root)).toSorted((left, right) => left.localeCompare(right)).length === 0) return true;
+	if (options?.skipNonEmptyConfirmation) return true;
+	if (!shouldPrompt) throw new Error(`Target directory is not empty: ${root}. Choose an empty directory or run this command in an interactive terminal to confirm scaffolding there.`);
+	const shouldContinue = await confirm({ message: `Scaffold into the non-empty directory ${root}? Existing files will be left untouched.` });
+	return !isCancel(shouldContinue) && shouldContinue;
+};
+const resolveProjectSlug = async (providedName, directory, shouldPrompt) => {
+	const defaultProjectSlug = deriveDefaultProjectSlug(directory, process.cwd());
+	if (providedName) return providedName;
+	if (!shouldPrompt) return defaultProjectSlug;
+	return await promptForProjectSlug(defaultProjectSlug);
+};
+const writeScaffoldFiles = async (root, template, projectSlug) => {
+	for (const file of getScaffoldFiles(template, { projectSlug })) {
+		const filePath = path.join(root, file.path);
+		await fs.mkdir(path.dirname(filePath), { recursive: true });
+		if (file.type === "symlink") {
+			await writeSymlinkIfMissing(filePath, file.target, { fallbackContent: file.fallbackContent });
+			continue;
+		}
+		await writeFileIfMissing(filePath, file.content);
+	}
+};
 const fetchUserEmail = async (apiUrl, token) => {
 	try {
 		return (await requestJson(`${apiUrl}/auth/me`, { headers: { Authorization: `Bearer ${token}` } }, "Failed to fetch user info")).email;
@@ -919,32 +1591,47 @@ const autoCreateProject = async (project, apiUrl, headers) => {
 	log.info(`API key for CI: ${chalk.dim(createResult.token)}`);
 	return true;
 };
+const scaffoldDocsSite = async (directory, options) => {
+	intro(chalk.bold("blodemd new"));
+	if (options?.deprecatedCommand) log.warn(`"${options.deprecatedCommand}" is deprecated. Use ${chalk.cyan("blodemd new")} instead.`);
+	try {
+		const template = options?.template ?? "minimal";
+		const shouldPrompt = isInteractiveTerminal() && !options?.yes;
+		const selectedDirectory = await resolveRequestedDirectory(directory, shouldPrompt);
+		if (!selectedDirectory) {
+			log.warn("Cancelled");
+			return;
+		}
+		const resolvedDirectory = resolveScaffoldDirectory(selectedDirectory.directory);
+		const root = path.resolve(process.cwd(), resolvedDirectory);
+		if (!await confirmScaffoldTarget(root, template, shouldPrompt, { skipNonEmptyConfirmation: selectedDirectory.skipNonEmptyConfirmation })) {
+			log.warn("Cancelled");
+			return;
+		}
+		const projectSlug = await resolveProjectSlug(options?.name, resolvedDirectory, shouldPrompt);
+		if (!projectSlug) {
+			log.warn("Cancelled");
+			return;
+		}
+		await fs.mkdir(root, { recursive: true });
+		await writeScaffoldFiles(root, template, projectSlug);
+		log.success(`Docs scaffolded in ${chalk.cyan(root)}`);
+		if (template === "starter") log.info("Starter template includes brand assets and helper files.");
+		log.info(`Project slug: ${chalk.cyan(projectSlug)}`);
+		log.info("Done");
+	} catch (error) {
+		reportCommandError("New failed", error);
+	}
+};
 const MAX_BATCH_BYTES = 4 * 1024 * 1024;
 const uploadFiles = async (files, root, apiPath, deploymentId, headers, s) => {
 	s.start(`Uploading ${files.length} files`);
-	const items = await Promise.all(files.map(async (filePath) => {
-		return {
-			contentBase64: (await fs.readFile(filePath)).toString("base64"),
-			contentType: getContentType(filePath),
-			path: normalizeRelativePath(root, filePath)
-		};
-	}));
-	const batches = [];
-	let current = [];
-	let currentBytes = 0;
-	for (const item of items) {
-		const itemBytes = item.contentBase64.length + item.path.length + 64;
-		if (current.length > 0 && currentBytes + itemBytes > MAX_BATCH_BYTES) {
-			batches.push(current);
-			current = [];
-			currentBytes = 0;
-		}
-		current.push(item);
-		currentBytes += itemBytes;
-	}
-	if (current.length > 0) batches.push(current);
 	let uploaded = 0;
-	for (const batch of batches) {
+	for await (const batch of createUploadBatches({
+		files,
+		maxBatchBytes: MAX_BATCH_BYTES,
+		root
+	})) {
 		await requestJson(apiPath(`/${deploymentId}/files/batch`), {
 			body: JSON.stringify({ files: batch }),
 			headers,
@@ -986,7 +1673,7 @@ program.command("login").description("Authenticate with Blode.md").option("--tok
 		}
 		const { authorizeUrl, tokenUrl } = buildOAuthUrls(resolveSupabaseConfig());
 		const clientId = OAUTH_CLIENT_ID;
-		const port = parsePositiveInteger(options.port, "Port");
+		const port = parsePort(options.port);
 		const timeoutSeconds = parsePositiveInteger(options.timeout, "Timeout");
 		const redirectUrl = new URL(`http://127.0.0.1:${port}${DEFAULT_OAUTH_CALLBACK_PATH}`);
 		const state = createOAuthState();
@@ -1030,9 +1717,15 @@ program.command("login").description("Authenticate with Blode.md").option("--tok
 program.command("logout").description("Remove stored credentials").action(async () => {
 	intro(chalk.bold("blodemd logout"));
 	try {
-		const existing = await readAuthFile();
+		let existing = false;
+		try {
+			await fs.access(CREDENTIALS_FILE);
+			existing = true;
+		} catch {
+			existing = false;
+		}
 		await clearStoredCredentials();
-		if (existing?.session || existing?.apiKey) log.success("Credentials removed.");
+		if (existing) log.success("Credentials removed.");
 		else log.info("No stored credentials found.");
 		log.info("Done");
 	} catch (error) {
@@ -1064,28 +1757,20 @@ program.command("whoami").description("Show current authentication").action(asyn
 		reportCommandError("Whoami failed", error);
 	}
 });
-program.command("init").description("Scaffold a docs folder").argument("[dir]", "target directory", "docs").action(async (dir) => {
-	intro(chalk.bold("blodemd init"));
-	try {
-		const root = path.resolve(process.cwd(), dir);
-		await fs.mkdir(root, { recursive: true });
-		await ensureFile(path.join(root, CONFIG_FILE), `${JSON.stringify({
-			$schema: "https://docs.blode.md/docs.json",
-			colors: { primary: "#0D9373" },
-			name: "my-project",
-			navigation: { groups: [{
-				group: "Getting Started",
-				pages: ["index"]
-			}] },
-			theme: "mint"
-		}, null, 2)}\n`);
-		await ensureFile(path.join(root, "index.mdx"), "---\ntitle: Welcome\n---\n\nStart writing your docs here.\n");
-		log.success(`Docs scaffolded in ${chalk.cyan(root)}`);
-		log.info(`Set ${chalk.cyan("name")} in docs.json to your project slug.`);
-		log.info("Done");
-	} catch (error) {
-		reportCommandError("Init failed", error);
-	}
+program.command("new").description("Create a new blode.md documentation site").argument("[directory]", "target directory").option("--name <slug>", "project slug for docs.json", parseProjectSlug).option("-t, --template <template>", `scaffold template (${SCAFFOLD_TEMPLATES.join(", ")})`, parseScaffoldTemplate, "minimal").option("-y, --yes", "accept defaults without prompting").action(async (directory, options) => {
+	await scaffoldDocsSite(directory, {
+		name: options.name,
+		template: options.template,
+		yes: options.yes
+	});
+});
+program.command("init", { hidden: true }).argument("[directory]", "target directory").option("--name <slug>", "project slug for docs.json", parseProjectSlug).option("-t, --template <template>", `scaffold template (${SCAFFOLD_TEMPLATES.join(", ")})`, parseScaffoldTemplate, "minimal").option("-y, --yes", "accept defaults without prompting").action(async (directory, options) => {
+	await scaffoldDocsSite(directory, {
+		deprecatedCommand: "blodemd init",
+		name: options.name,
+		template: options.template,
+		yes: options.yes
+	});
 });
 program.command("validate").description("Validate docs.json").argument("[dir]", "docs directory").action(async (dir) => {
 	intro(chalk.bold("blodemd validate"));