blodemd 0.0.10 → 0.0.12

package/dist/cli.mjs

@@ -3,8 +3,7 @@ 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, select, spinner, text } from "@clack/prompts";
-import { shouldIgnoreRootDocsFile, slugify } from "@repo/common";
+import { confirm, intro, isCancel, log, select, spinner, text } from "@clack/prompts";
 import chalk from "chalk";
 import { Command, InvalidArgumentError } from "commander";
 import open from "open";
@@ -13,13 +12,37 @@ import { once } from "node:events";
 import { createServer } from "node:net";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { createFsSource, loadSiteConfig } from "@repo/previewing";
+import { z } from "zod";
+import "yaml";
 import { watch } from "chokidar";
 import { createServer as createServer$1 } from "node:http";
 import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
+//#region ../../packages/common/dist/index.js
+const BACKSLASH_TO_SLASH_REGEX = /\\/g;
+const TRAILING_SLASHES_REGEX = /\/+$/g;
+const LEADING_SLASHES_REGEX = /^\/+/;
+const normalizePath = (value) => {
+	return value.replace(BACKSLASH_TO_SLASH_REGEX, "/").replace(TRAILING_SLASHES_REGEX, "").replace(LEADING_SLASHES_REGEX, "");
+};
+const slugify = (value) => value.toLowerCase().trim().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/(^-|-$)+/g, "");
+const IGNORED_ROOT_DOCS_FILES = new Set([
+	".gitignore",
+	"AGENTS.md",
+	"CLAUDE.md",
+	"LICENSE",
+	"LICENSE.md",
+	"README.md"
+]);
+const shouldIgnoreRootDocsFile = (value) => {
+	const normalized = normalizePath(value);
+	if (!normalized || normalized.includes("/")) return false;
+	return IGNORED_ROOT_DOCS_FILES.has(normalized);
+};
+//#endregion
 //#region src/constants.ts
 const CLI_NAME = "blodemd";
+const BLODE_PROJECT_ENV = "BLODEMD_PROJECT";
 const OAUTH_CLIENT_ID = "6b5f9860-fe96-4a83-b1ad-266260523c91";
 const DEFAULT_OAUTH_CALLBACK_PORT = 8787;
 const DEFAULT_OAUTH_CALLBACK_PATH = "/auth/callback";
@@ -30,30 +53,6 @@ const getDefaultConfigBaseDir = () => {
 const CONFIG_DIR = join(getDefaultConfigBaseDir(), CLI_NAME);
 const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
 //#endregion
-//#region src/jwt.ts
-const parseJwtBase64Url = (input) => {
-	const normalized = input.replaceAll("-", "+").replaceAll("_", "/");
-	const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
-	return Buffer.from(padded, "base64").toString("utf8");
-};
-const parseJwtClaims = (token) => {
-	const payloadPart = token.split(".").at(1);
-	if (!payloadPart) return null;
-	try {
-		const payload = parseJwtBase64Url(payloadPart);
-		const parsed = JSON.parse(payload);
-		if (typeof parsed !== "object" || parsed === null) return null;
-		const claims = parsed;
-		return {
-			email: typeof claims.email === "string" ? claims.email : void 0,
-			exp: typeof claims.exp === "number" ? claims.exp : void 0,
-			sub: typeof claims.sub === "string" ? claims.sub : void 0
-		};
-	} catch {
-		return null;
-	}
-};
-//#endregion
 //#region src/errors.ts
 const EXIT_CODES = {
 	AUTH_REQUIRED: 4,
@@ -149,14 +148,6 @@ const parseStoredAuthSession = (value) => {
 		user
 	};
 };
-const parseApiKeyCredentials = (value) => {
-	if (!isRecord(value)) return null;
-	if (typeof value.apiKey !== "string") return null;
-	return {
-		apiKey: value.apiKey,
-		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;
@@ -167,13 +158,9 @@ const parseAuthFile = (raw) => {
 	}
 	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
 	};
@@ -203,16 +190,34 @@ const writeStoredAuthSession = async (session) => {
 		version: 1
 	});
 };
-const writeStoredApiKey = async (apiKey) => {
-	await writeAuthFile({
-		apiKey,
-		version: 1
-	});
-};
 const clearStoredCredentials = async () => {
 	await rm(CREDENTIALS_FILE, { force: true });
 };
 //#endregion
+//#region src/jwt.ts
+const parseJwtBase64Url = (input) => {
+	const normalized = input.replaceAll("-", "+").replaceAll("_", "/");
+	const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+	return Buffer.from(padded, "base64").toString("utf8");
+};
+const parseJwtClaims = (token) => {
+	const payloadPart = token.split(".").at(1);
+	if (!payloadPart) return null;
+	try {
+		const payload = parseJwtBase64Url(payloadPart);
+		const parsed = JSON.parse(payload);
+		if (typeof parsed !== "object" || parsed === null) return null;
+		const claims = parsed;
+		return {
+			email: typeof claims.email === "string" ? claims.email : void 0,
+			exp: typeof claims.exp === "number" ? claims.exp : void 0,
+			sub: typeof claims.sub === "string" ? claims.sub : void 0
+		};
+	} catch {
+		return null;
+	}
+};
+//#endregion
 //#region src/supabase.ts
 const resolveSupabaseConfig = () => {
 	return { url: process.env.SUPABASE_URL ?? process.env.NEXT_PUBLIC_SUPABASE_URL ?? "https://bwnxwgkgyklzzmpbzuoz.supabase.co" };
@@ -253,53 +258,30 @@ const shouldRefresh = (session) => {
 	const ms = expiresInMs(session);
 	return ms !== null && ms <= 6e4;
 };
-const tokenFromRaw = (token, source) => {
-	const claims = parseJwtClaims(token);
-	return {
-		expiresAt: typeof claims?.exp === "number" ? (/* @__PURE__ */ new Date(claims.exp * 1e3)).toISOString() : null,
-		source,
-		token,
-		user: claims?.sub || claims?.email ? {
-			email: claims.email ?? null,
-			id: claims.sub ?? "unknown"
-		} : null
-	};
-};
 const sessionToResolvedToken = (session) => ({
 	expiresAt: session.expiresAt,
 	source: "stored",
 	token: session.accessToken,
 	user: session.user
 });
-const resolveAuthToken = async (optApiKey) => {
-	const envToken = (optApiKey ?? process.env["BLODEMD_API_KEY"])?.trim();
-	if (envToken) return tokenFromRaw(envToken, optApiKey ? "flag" : "environment");
-	const data = await readAuthFile();
-	const session = data?.session;
-	if (session) {
-		if (!(shouldRefresh(session) || isExpired(session))) return sessionToResolvedToken(session);
-		if (session.refreshToken) try {
-			const { tokenUrl } = buildOAuthUrls(resolveSupabaseConfig());
-			const updatedSession = tokenResponseToStoredSession(await refreshAccessToken({
-				clientId: OAUTH_CLIENT_ID,
-				tokenUrl
-			}, session.refreshToken));
-			await writeStoredAuthSession(updatedSession);
-			return sessionToResolvedToken(updatedSession);
-		} catch {}
-		if (isExpired(session)) {
-			await clearStoredCredentials();
-			return null;
-		}
-		return sessionToResolvedToken(session);
+const resolveAuthToken = async () => {
+	const session = (await readAuthFile())?.session;
+	if (!session) return null;
+	if (!(shouldRefresh(session) || isExpired(session))) return sessionToResolvedToken(session);
+	if (session.refreshToken) try {
+		const { tokenUrl } = buildOAuthUrls(resolveSupabaseConfig());
+		const updatedSession = tokenResponseToStoredSession(await refreshAccessToken({
+			clientId: OAUTH_CLIENT_ID,
+			tokenUrl
+		}, session.refreshToken));
+		await writeStoredAuthSession(updatedSession);
+		return sessionToResolvedToken(updatedSession);
+	} catch {}
+	if (isExpired(session)) {
+		await clearStoredCredentials();
+		return null;
 	}
-	if (data?.apiKey) return {
-		expiresAt: null,
-		source: "stored",
-		token: data.apiKey.apiKey,
-		user: null
-	};
-	return null;
+	return sessionToResolvedToken(session);
 };
 const resolveTokenStatus = (token) => {
 	if (!token.expiresAt) return {
@@ -333,6 +315,642 @@ const parsePort = (value, label = "Port") => {
 	return parsed;
 };
 //#endregion
+//#region ../../packages/models/dist/docs-config.js
+const UrlOrPathSchema = z.string().min(1);
+const SlugSchema = z.string().min(1).regex(/^[a-z0-9-]+$/);
+const DocsColorsSchema = z.object({
+	background: z.string().optional(),
+	border: z.string().optional(),
+	dark: z.string().optional(),
+	light: z.string().optional(),
+	muted: z.string().optional(),
+	primary: z.string().min(1),
+	surface: z.string().optional()
+}).strict();
+const DocsFontsSchema = z.object({
+	body: z.string().optional(),
+	cssUrl: z.string().optional(),
+	heading: z.string().optional(),
+	mono: z.string().optional(),
+	provider: z.enum([
+		"google",
+		"local",
+		"custom"
+	]).optional()
+}).strict();
+const DocsLogoSchema = z.object({
+	alt: z.string().optional(),
+	dark: UrlOrPathSchema.optional(),
+	href: z.string().min(1).optional(),
+	light: UrlOrPathSchema.optional()
+}).strict();
+const DocsNavLinkSchema = z.object({
+	href: z.string().min(1),
+	label: z.string().min(1)
+}).strict();
+const DocsNavAnchorSchema = z.object({
+	href: z.string().min(1),
+	label: z.string().min(1)
+}).strict();
+const DocsNavLocaleSchema = z.object({
+	label: z.string().min(1),
+	locale: z.string().optional(),
+	url: z.string().min(1)
+}).strict();
+const DocsNavVersionSchema = z.object({
+	label: z.string().min(1),
+	url: z.string().min(1)
+}).strict();
+const DocsOpenApiSourceSchema = z.object({
+	basePath: z.string().optional(),
+	directory: z.string().optional(),
+	include: z.array(z.string()).optional(),
+	source: z.string().min(1)
+}).strict();
+const DocsNavGroupSchema = z.object({
+	expanded: z.boolean().optional(),
+	group: z.string().optional(),
+	hidden: z.boolean().optional(),
+	openapi: z.union([z.string().min(1), DocsOpenApiSourceSchema]).optional(),
+	pages: z.array(z.string()).optional()
+}).strict();
+const DocsNavTabSchema = z.object({
+	groups: z.array(DocsNavGroupSchema).optional(),
+	href: z.string().min(1).optional(),
+	icon: z.string().optional(),
+	label: z.string().min(1),
+	pages: z.array(z.string()).optional()
+}).strict().refine((value) => Boolean(value.groups?.length || value.pages?.length || value.href), {
+	message: "tab must define groups, pages, or href",
+	path: []
+});
+const DocsNavigationSchema = z.object({
+	global: z.object({
+		anchors: z.array(DocsNavAnchorSchema).optional(),
+		links: z.array(DocsNavLinkSchema).optional()
+	}).strict().optional(),
+	groups: z.array(DocsNavGroupSchema).optional(),
+	hidden: z.array(z.string()).optional(),
+	languages: z.array(DocsNavLocaleSchema).optional(),
+	pages: z.array(z.string()).optional(),
+	tabs: z.array(DocsNavTabSchema).optional(),
+	versions: z.array(DocsNavVersionSchema).optional()
+}).strict();
+const DocsScriptsSchema = z.object({
+	body: z.array(z.string()).optional(),
+	head: z.array(z.string()).optional()
+}).strict();
+const DocsSeoSchema = z.object({ indexing: z.enum(["all", "default"]).optional() }).strict();
+const DocsFeatureFlagsSchema = z.object({
+	rightToc: z.boolean().optional(),
+	search: z.boolean().optional(),
+	themeToggle: z.boolean().optional(),
+	toc: z.boolean().optional()
+}).strict();
+const DocsOpenApiProxySchema = z.object({
+	allowedHosts: z.array(z.string()).optional(),
+	enabled: z.boolean().optional()
+}).strict();
+const MintlifyLogoSchema = z.union([UrlOrPathSchema, z.object({
+	dark: UrlOrPathSchema,
+	href: z.string().min(1).optional(),
+	light: UrlOrPathSchema
+}).strict()]);
+const MintlifyFaviconSchema = z.union([UrlOrPathSchema, z.object({
+	dark: UrlOrPathSchema,
+	light: UrlOrPathSchema
+}).strict()]);
+const MintlifyNavbarLinkSchema = z.object({
+	href: z.string().min(1),
+	icon: z.string().optional(),
+	iconType: z.string().optional(),
+	label: z.string().optional(),
+	type: z.enum(["discord", "github"]).optional()
+}).strict();
+const MintlifyNavbarPrimarySchema = z.object({
+	href: z.string().min(1),
+	label: z.string().optional(),
+	type: z.enum([
+		"button",
+		"discord",
+		"github"
+	])
+}).strict();
+const MintlifyNavbarSchema = z.object({
+	links: z.array(MintlifyNavbarLinkSchema).optional(),
+	primary: MintlifyNavbarPrimarySchema.optional()
+}).strict();
+const MintlifyNavigationGlobalSchema = z.object({ anchors: z.array(z.object({
+	anchor: z.string().min(1),
+	color: z.object({
+		dark: z.string().optional(),
+		light: z.string().optional()
+	}).strict().optional(),
+	hidden: z.boolean().optional(),
+	href: z.string().min(1),
+	icon: z.string().optional(),
+	iconType: z.string().optional()
+}).strict()).optional() }).strict();
+const MintlifyNavigationGroupSchema = z.object({
+	expanded: z.boolean().optional(),
+	group: z.string().min(1),
+	hidden: z.boolean().optional(),
+	icon: z.string().optional(),
+	pages: z.array(z.string()).optional(),
+	root: z.string().optional(),
+	tag: z.string().optional()
+}).strict();
+const MintlifyNavTabSchema = z.object({
+	groups: z.array(MintlifyNavigationGroupSchema).optional(),
+	hidden: z.boolean().optional(),
+	href: z.string().min(1).optional(),
+	icon: z.string().optional(),
+	pages: z.array(z.string()).optional(),
+	tab: z.string().min(1)
+}).strict();
+const MintlifyNavigationSchema = z.object({
+	global: MintlifyNavigationGlobalSchema.optional(),
+	groups: z.array(MintlifyNavigationGroupSchema).optional(),
+	languages: z.array(z.object({
+		default: z.boolean().optional(),
+		hidden: z.boolean().optional(),
+		href: z.string().min(1),
+		language: z.string().min(1)
+	}).strict()).optional(),
+	pages: z.array(z.string()).optional(),
+	tabs: z.array(MintlifyNavTabSchema).optional(),
+	versions: z.array(z.object({
+		default: z.boolean().optional(),
+		hidden: z.boolean().optional(),
+		href: z.string().min(1),
+		version: z.string().min(1)
+	}).strict()).optional()
+}).strict().refine((value) => Boolean(value.groups?.length || value.pages?.length || value.tabs?.length || value.languages?.length || value.versions?.length), {
+	message: "navigation must define at least one of groups, pages, tabs, languages, or versions",
+	path: []
+});
+const MintlifyApiSchema = z.object({
+	asyncapi: z.union([
+		z.string(),
+		z.array(z.string()),
+		DocsOpenApiSourceSchema
+	]).optional(),
+	examples: z.object({
+		autogenerate: z.boolean().optional(),
+		defaults: z.enum(["all", "required"]).optional(),
+		languages: z.array(z.string()).optional(),
+		prefill: z.boolean().optional()
+	}).strict().optional(),
+	mdx: z.object({
+		auth: z.object({
+			method: z.enum([
+				"basic",
+				"bearer",
+				"cobo",
+				"key"
+			]).optional(),
+			name: z.string().optional()
+		}).strict().optional(),
+		server: z.union([z.string().min(1), z.array(z.string().min(1))]).optional()
+	}).strict().optional(),
+	openapi: z.union([
+		z.string(),
+		z.array(z.string()),
+		DocsOpenApiSourceSchema
+	]).optional(),
+	params: z.object({ expanded: z.enum(["all", "closed"]).optional() }).strict().optional(),
+	playground: z.object({
+		credentials: z.boolean().optional(),
+		display: z.enum([
+			"auth",
+			"interactive",
+			"none",
+			"simple"
+		]).optional(),
+		proxy: z.boolean().optional()
+	}).strict().optional(),
+	url: z.literal("full").optional()
+}).strict();
+const MintlifyAppearanceSchema = z.object({
+	default: z.enum([
+		"dark",
+		"light",
+		"system"
+	]).optional(),
+	strict: z.boolean().optional()
+}).strict();
+const MintlifyMetadataSchema = z.object({ timestamp: z.boolean().optional() }).strict();
+const MintlifySearchSchema = z.object({ prompt: z.string().optional() }).strict();
+const ContextualBuiltinOptionSchema = z.enum([
+	"add-mcp",
+	"aistudio",
+	"assistant",
+	"chatgpt",
+	"claude",
+	"copy",
+	"cursor",
+	"devin",
+	"devin-mcp",
+	"gemini",
+	"grok",
+	"mcp",
+	"perplexity",
+	"view",
+	"vscode",
+	"windsurf"
+]);
+const ContextualCustomHrefQuerySchema = z.object({
+	key: z.string().min(1),
+	value: z.string().min(1)
+}).strict();
+const ContextualCustomHrefObjectSchema = z.object({
+	base: z.string().min(1),
+	query: z.array(ContextualCustomHrefQuerySchema)
+}).strict();
+const ContextualCustomOptionSchema = z.object({
+	description: z.string().min(1),
+	href: z.union([z.string().min(1), ContextualCustomHrefObjectSchema]),
+	icon: z.string().min(1),
+	iconType: z.string().optional(),
+	title: z.string().min(1)
+}).strict();
+const ContextualOptionSchema = z.union([ContextualBuiltinOptionSchema, ContextualCustomOptionSchema]);
+const DocsContextualSchema = z.object({
+	display: z.enum(["header", "toc"]).optional(),
+	options: z.array(ContextualOptionSchema)
+}).strict();
+const DocsConfigSchema = z.object({
+	$schema: z.string().optional(),
+	api: MintlifyApiSchema.optional(),
+	appearance: MintlifyAppearanceSchema.optional(),
+	contextual: DocsContextualSchema.optional(),
+	description: z.string().optional(),
+	favicon: MintlifyFaviconSchema.optional(),
+	logo: MintlifyLogoSchema.optional(),
+	metadata: MintlifyMetadataSchema.optional(),
+	name: z.string().min(1),
+	navbar: MintlifyNavbarSchema.optional(),
+	navigation: MintlifyNavigationSchema,
+	search: MintlifySearchSchema.optional(),
+	seo: DocsSeoSchema.optional(),
+	slug: SlugSchema.optional()
+}).strict();
+const ContentTypeSchema = z.enum([
+	"site",
+	"blog",
+	"docs",
+	"courses",
+	"products",
+	"notes",
+	"forms",
+	"sheets",
+	"slides",
+	"todos"
+]);
+const FrontmatterBaseSchema = z.object({
+	description: z.string().optional(),
+	hidden: z.boolean().optional(),
+	title: z.string().min(1)
+}).passthrough();
+FrontmatterBaseSchema.extend({
+	date: z.string().min(1),
+	tags: z.array(z.string()).optional()
+}).passthrough();
+FrontmatterBaseSchema.extend({ order: z.number() }).passthrough();
+FrontmatterBaseSchema.extend({
+	currency: z.string().min(1),
+	price: z.number(),
+	sku: z.string().min(1)
+}).passthrough();
+FrontmatterBaseSchema.extend({ date: z.string().min(1) }).passthrough();
+const FormFieldSchema = z.object({
+	id: z.string().min(1),
+	label: z.string().min(1),
+	options: z.array(z.string()).optional(),
+	required: z.boolean().optional(),
+	type: z.string().min(1)
+}).passthrough();
+FrontmatterBaseSchema.extend({ fields: z.array(FormFieldSchema).min(1) }).passthrough();
+FrontmatterBaseSchema.extend({ columns: z.array(z.string()).min(1) }).passthrough();
+FrontmatterBaseSchema.extend({ date: z.string().min(1) }).passthrough();
+const PageModeSchema = z.enum([
+	"default",
+	"wide",
+	"custom",
+	"frame",
+	"center"
+]);
+FrontmatterBaseSchema.extend({
+	deprecated: z.boolean().optional(),
+	hideApiMarker: z.boolean().optional(),
+	hideFooterPagination: z.boolean().optional(),
+	icon: z.string().optional(),
+	iconType: z.enum([
+		"regular",
+		"solid",
+		"light",
+		"thin",
+		"sharp-solid",
+		"duotone",
+		"brands"
+	]).optional(),
+	keywords: z.array(z.string()).optional(),
+	mode: PageModeSchema.optional(),
+	noindex: z.boolean().optional(),
+	sidebarTitle: z.string().optional(),
+	tag: z.string().optional(),
+	url: z.string().url().optional()
+}).passthrough();
+const CollectionIndexSchema = z.object({
+	description: z.string().optional(),
+	hidden: z.boolean().optional(),
+	slug: z.string().min(1),
+	title: z.string().optional()
+}).strict();
+const CollectionSortSchema = z.object({
+	direction: z.enum(["asc", "desc"]).optional(),
+	field: z.enum([
+		"date",
+		"order",
+		"title",
+		"price"
+	]).optional()
+}).strict();
+const CollectionConfigSchema = z.object({
+	id: z.string().min(1),
+	index: CollectionIndexSchema.optional(),
+	navigation: DocsNavigationSchema.optional(),
+	openapi: z.union([
+		z.string(),
+		z.array(z.string()),
+		DocsOpenApiSourceSchema
+	]).optional(),
+	root: z.string().optional(),
+	slugPrefix: z.string().optional(),
+	sort: CollectionSortSchema.optional(),
+	type: ContentTypeSchema
+}).strict();
+const SiteConfigSchema = z.object({
+	collections: z.array(CollectionConfigSchema).min(1),
+	colors: DocsColorsSchema.optional(),
+	contextual: DocsContextualSchema.optional(),
+	description: z.string().optional(),
+	favicon: UrlOrPathSchema.optional(),
+	features: DocsFeatureFlagsSchema.optional(),
+	fonts: DocsFontsSchema.optional(),
+	logo: DocsLogoSchema.optional(),
+	metadata: z.object({
+		defaultTitle: z.string().optional(),
+		ogImage: UrlOrPathSchema.optional(),
+		titleTemplate: z.string().optional()
+	}).strict().optional(),
+	name: z.string().min(1),
+	navigation: DocsNavigationSchema.optional(),
+	openapiProxy: DocsOpenApiProxySchema.optional(),
+	scripts: DocsScriptsSchema.optional(),
+	seo: DocsSeoSchema.optional(),
+	slug: SlugSchema.optional(),
+	theme: z.string().optional()
+}).strict();
+//#endregion
+//#region ../../packages/validation/dist/index.js
+const formatIssues = (issues) => issues.map((issue) => {
+	return `${issue.path.length ? issue.path.map(String).join(".") : "root"}: ${issue.message}`;
+});
+const validateSiteConfig = (input) => {
+	const result = SiteConfigSchema.safeParse(input);
+	if (result.success) return {
+		data: result.data,
+		success: true
+	};
+	return {
+		errors: formatIssues(result.error.issues),
+		success: false
+	};
+};
+const validateDocsConfig = (input) => {
+	const result = DocsConfigSchema.safeParse(input);
+	if (result.success) return {
+		data: result.data,
+		success: true
+	};
+	return {
+		errors: formatIssues(result.error.issues),
+		success: false
+	};
+};
+//#endregion
+//#region ../../packages/previewing/dist/fs-source.js
+const IGNORED_DIRECTORIES = new Set([
+	"app",
+	"lib",
+	"node_modules",
+	"public"
+]);
+const isNotFoundError = (error) => Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+const isWithinRoot = (root, candidate) => candidate === root || candidate.startsWith(`${root}${path.sep}`);
+const resolveWithinRoot = (root, relativePath) => {
+	const normalized = normalizePath(relativePath);
+	const absolutePath = path.resolve(root, normalized);
+	if (!isWithinRoot(root, absolutePath)) throw new Error(`Path "${relativePath}" escapes the content source root.`);
+	return absolutePath;
+};
+const walkFiles = async (directory, prefix) => {
+	const entries = await fs.readdir(directory, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries) {
+		if (entry.name.startsWith(".")) continue;
+		const absolutePath = path.join(directory, entry.name);
+		const relativePath = prefix ? path.join(prefix, entry.name) : entry.name;
+		if (entry.isDirectory()) {
+			if (IGNORED_DIRECTORIES.has(entry.name)) continue;
+			files.push(...await walkFiles(absolutePath, relativePath));
+			continue;
+		}
+		if (entry.isFile()) {
+			if (!prefix && shouldIgnoreRootDocsFile(entry.name)) continue;
+			files.push(normalizePath(relativePath));
+		}
+	}
+	return files;
+};
+var FsContentSource = class {
+	root;
+	constructor(root) {
+		this.root = path.resolve(root);
+	}
+	async readFile(relativePath) {
+		return await fs.readFile(resolveWithinRoot(this.root, relativePath), "utf8");
+	}
+	async listFiles(directory) {
+		return await walkFiles(resolveWithinRoot(this.root, directory), "");
+	}
+	async exists(relativePath) {
+		try {
+			await fs.access(resolveWithinRoot(this.root, relativePath));
+			return true;
+		} catch (error) {
+			if (isNotFoundError(error)) return false;
+			throw error;
+		}
+	}
+	resolveUrl() {
+		return null;
+	}
+};
+const createFsSource = (root) => new FsContentSource(root);
+//#endregion
+//#region ../../packages/previewing/dist/index.js
+const LEGACY_PROJECT_NAME_FALLBACK_WARNING$1 = "docs.json.slug is recommended. Falling back to docs.json.name as the deployment slug is deprecated.";
+new Set(PageModeSchema.options);
+const DOCS_CONFIG_FILE = "docs.json";
+const defaultLinkLabel = (input) => {
+	if (input.label) return input.label;
+	if (input.type === "github") return "GitHub";
+	if (input.type === "discord") return "Discord";
+	try {
+		return new URL(input.href).hostname;
+	} catch {
+		return input.href;
+	}
+};
+const mapDocsConfig = (docs) => {
+	const navigation = {
+		global: docs.navbar?.links?.length || docs.navigation.global?.anchors?.length ? {
+			anchors: docs.navigation.global?.anchors?.map((anchor) => ({
+				href: anchor.href,
+				label: anchor.anchor
+			})),
+			links: docs.navbar?.links?.map((link) => ({
+				href: link.href,
+				label: defaultLinkLabel(link)
+			}))
+		} : void 0,
+		groups: docs.navigation.groups?.map((group) => ({
+			expanded: group.expanded,
+			group: group.group,
+			hidden: group.hidden,
+			pages: group.root ? [group.root, ...(group.pages ?? []).filter((page) => page !== group.root)] : group.pages
+		})),
+		languages: docs.navigation.languages?.map((language) => ({
+			label: language.language,
+			locale: language.language,
+			url: language.href
+		})),
+		pages: docs.navigation.pages,
+		tabs: docs.navigation.tabs?.map((tab) => ({
+			groups: tab.groups?.map((group) => ({
+				expanded: group.expanded,
+				group: group.group,
+				hidden: group.hidden,
+				pages: group.root ? [group.root, ...(group.pages ?? []).filter((page) => page !== group.root)] : group.pages
+			})),
+			href: tab.href,
+			icon: tab.icon,
+			label: tab.tab,
+			pages: tab.pages
+		})),
+		versions: docs.navigation.versions?.map((version) => ({
+			label: version.version,
+			url: version.href
+		}))
+	};
+	return {
+		collections: [{
+			id: "docs",
+			navigation,
+			openapi: docs.api?.openapi,
+			root: "",
+			type: "docs"
+		}],
+		contextual: docs.contextual,
+		description: docs.description,
+		favicon: typeof docs.favicon === "string" ? docs.favicon : docs.favicon?.light,
+		features: {
+			rightToc: true,
+			search: true,
+			themeToggle: docs.appearance?.strict !== true,
+			toc: true
+		},
+		logo: docs.logo ? {
+			dark: typeof docs.logo === "string" ? docs.logo : docs.logo.dark,
+			href: typeof docs.logo === "string" ? void 0 : docs.logo.href,
+			light: typeof docs.logo === "string" ? docs.logo : docs.logo.light
+		} : void 0,
+		name: docs.name,
+		navigation,
+		openapiProxy: { enabled: docs.api?.playground?.proxy !== false && Boolean(docs.api?.openapi || docs.api?.asyncapi) },
+		seo: docs.seo,
+		slug: docs.slug
+	};
+};
+const getProjectWarnings = (config) => config.slug ? [] : [LEGACY_PROJECT_NAME_FALLBACK_WARNING$1];
+const readJsonConfig = async (source, relativePath) => JSON.parse(await source.readFile(relativePath));
+const normalizeRefPath = (baseDirectory, reference) => {
+	if (reference.startsWith("/") || reference.startsWith("\\") || reference.startsWith("http://") || reference.startsWith("https://")) throw new Error(`Invalid $ref "${reference}". Only relative JSON files are supported.`);
+	const normalized = normalizePath(path.posix.join(baseDirectory, reference));
+	if (!normalized || normalized === "." || normalized.startsWith("../") || normalized.includes("/../")) throw new Error(`Invalid $ref "${reference}".`);
+	return normalized;
+};
+const resolveJsonRefs = async (source, value, baseDirectory, seen) => {
+	if (Array.isArray(value)) return await Promise.all(value.map((item) => resolveJsonRefs(source, item, baseDirectory, seen)));
+	if (!value || typeof value !== "object") return value;
+	const record = value;
+	const reference = record.$ref;
+	if (typeof reference === "string") {
+		const resolvedPath = normalizeRefPath(baseDirectory, reference);
+		if (seen.has(resolvedPath)) throw new Error(`Circular $ref detected for "${resolvedPath}".`);
+		const nextSeen = new Set(seen);
+		nextSeen.add(resolvedPath);
+		const referencedValue = await resolveJsonRefs(source, await readJsonConfig(source, resolvedPath), path.posix.dirname(resolvedPath) === "." ? "" : normalizePath(path.posix.dirname(resolvedPath)), nextSeen);
+		const siblingEntries = Object.entries(record).filter(([key]) => key !== "$ref");
+		if (!siblingEntries.length || !referencedValue || typeof referencedValue !== "object" || Array.isArray(referencedValue)) return referencedValue;
+		const siblingValue = await resolveJsonRefs(source, Object.fromEntries(siblingEntries), baseDirectory, seen);
+		return {
+			...referencedValue,
+			...siblingValue
+		};
+	}
+	const resolvedEntries = await Promise.all(Object.entries(record).map(async ([key, entryValue]) => [key, await resolveJsonRefs(source, entryValue, baseDirectory, seen)]));
+	return Object.fromEntries(resolvedEntries);
+};
+const readResolvedJsonConfig = async (source, relativePath) => await resolveJsonRefs(source, await readJsonConfig(source, relativePath), path.posix.dirname(relativePath) === "." ? "" : normalizePath(path.posix.dirname(relativePath)), new Set([relativePath]));
+const loadDocsConfig = async (source) => {
+	if (!await source.exists(DOCS_CONFIG_FILE)) return null;
+	try {
+		const parsed = await readResolvedJsonConfig(source, DOCS_CONFIG_FILE);
+		const siteResult = validateSiteConfig(parsed);
+		if (siteResult.success) return {
+			config: siteResult.data,
+			ok: true,
+			warnings: getProjectWarnings(siteResult.data)
+		};
+		const docsResult = validateDocsConfig(parsed);
+		if (docsResult.success) return {
+			config: mapDocsConfig(docsResult.data),
+			ok: true,
+			warnings: getProjectWarnings(docsResult.data)
+		};
+		return {
+			errors: docsResult.errors,
+			ok: false
+		};
+	} catch (error) {
+		return {
+			errors: [error instanceof Error ? error.message : `Failed to load ${DOCS_CONFIG_FILE}`],
+			ok: false
+		};
+	}
+};
+const loadSiteConfig = async (source) => {
+	const docsConfig = await loadDocsConfig(source);
+	if (docsConfig) return docsConfig;
+	return {
+		errors: [`${DOCS_CONFIG_FILE} not found.`],
+		ok: false
+	};
+};
+//#endregion
 //#region src/site-config.ts
 const CONFIG_FILE$2 = "docs.json";
 const getSiteConfigHint = (errors) => {
@@ -831,10 +1449,48 @@ const findExistingPaths = async (root, relativePaths) => {
 	}))).filter((relativePath) => relativePath !== null).toSorted((left, right) => left.localeCompare(right));
 };
 //#endregion
+//#region src/project-config.ts
+const LEGACY_PROJECT_NAME_FALLBACK_WARNING = "docs.json.slug is recommended. Falling back to docs.json.name as the deployment slug is deprecated.";
+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 deriveDisplayNameFromProjectSlug = (projectSlug) => projectSlug.split("-").filter(Boolean).map((segment) => segment[0]?.toUpperCase() + segment.slice(1)).join(" ");
+const resolveProjectTarget = (options) => {
+	if (options.cliProject) return {
+		project: options.cliProject,
+		usedLegacyNameFallback: false
+	};
+	if (options.envProject) return {
+		project: options.envProject,
+		usedLegacyNameFallback: false
+	};
+	if (options.config.slug) return {
+		project: options.config.slug,
+		usedLegacyNameFallback: false
+	};
+	if (options.config.name) return {
+		project: options.config.name,
+		usedLegacyNameFallback: true
+	};
+	return {
+		project: void 0,
+		usedLegacyNameFallback: false
+	};
+};
+const getProjectSlugError = (project) => {
+	if (!project) return;
+	return validateProjectSlug(project);
+};
+//#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 escapeXmlText = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
 const isScaffoldTemplate = (value) => SCAFFOLD_TEMPLATES.includes(value);
 const normalizeProjectSlug = (value) => slugify(value) || "my-project";
 const resolveScaffoldDirectory = (directory) => directory?.trim() || "docs";
@@ -843,22 +1499,16 @@ const deriveDefaultProjectSlug = (directory, cwd) => {
 	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) => ({
+const createMinimalDocsJson = (projectSlug, displayName) => ({
 	$schema: "https://blode.md/docs.json",
-	name: projectSlug,
+	name: displayName,
 	navigation: { groups: [{
 		group: "Getting Started",
 		pages: ["index"]
-	}] }
+	}] },
+	slug: projectSlug
 });
-const createStarterDocsJson = (projectSlug) => ({
+const createStarterDocsJson = (projectSlug, displayName) => ({
 	$schema: "https://blode.md/docs.json",
 	appearance: { default: "system" },
 	contextual: { options: [
@@ -870,12 +1520,12 @@ const createStarterDocsJson = (projectSlug) => ({
 	description: "Ship documentation from your terminal.",
 	favicon: "/favicon.svg",
 	logo: {
-		alt: `${projectSlug} logo`,
+		alt: `${displayName} logo`,
 		dark: "/logo/dark.svg",
 		light: "/logo/light.svg"
 	},
 	metadata: { timestamp: true },
-	name: projectSlug,
+	name: displayName,
 	navigation: { groups: [{
 		group: "Getting Started",
 		pages: [
@@ -883,7 +1533,8 @@ const createStarterDocsJson = (projectSlug) => ({
 			"quickstart",
 			"development"
 		]
-	}] }
+	}] },
+	slug: projectSlug
 });
 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.",
@@ -927,270 +1578,276 @@ const claudeInstructions = [
 	"- Run `blodemd validate` before publishing.",
 	""
 ].join("\n");
-const createMinimalFiles = (projectSlug) => [{
-	content: stringifyJson(createMinimalDocsJson(projectSlug)),
+const createMinimalFiles = (projectSlug, displayName) => [{
+	content: stringifyJson(createMinimalDocsJson(projectSlug, displayName)),
 	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 createStarterFiles = (projectSlug, displayName) => {
+	const escapedDisplayName = escapeXmlText(displayName);
+	return [
+		{
+			content: stringifyJson(createStarterDocsJson(projectSlug, displayName)),
+			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 `slug` in `docs.json` matches your deployment target.",
+				"- Update `name` in `docs.json` to match the visible product or docs brand.",
+				"- 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 `slug` in `docs.json` matches your deployment target.",
+				"2. Update `name` in `docs.json` to match your visible docs brand.",
+				"3. Update the `description` field to match your product.",
+				"4. Replace the assets in `/logo` and `/images`.",
+				"5. Run `blodemd dev` to preview locally.",
+				"6. 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 `slug` in `docs.json` and set the display `name` and description.",
+				"- 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">${escapedDisplayName}</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">${escapedDisplayName}</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);
+	const displayName = options?.displayName ?? deriveDisplayNameFromProjectSlug(projectSlug);
+	return template === "starter" ? createStarterFiles(projectSlug, displayName) : createMinimalFiles(projectSlug, displayName);
 };
 //#endregion
 //#region src/new-flow.ts
@@ -1497,6 +2154,18 @@ const promptForProjectSlug = async (initialValue) => {
 	if (isCancel(projectSlug)) return;
 	return projectSlug.trim();
 };
+const promptForDisplayName = async (initialValue) => {
+	const displayName = await text({
+		initialValue,
+		message: "Display name",
+		placeholder: initialValue,
+		validate: (value) => {
+			if (!value?.trim()) return "Display name is required.";
+		}
+	});
+	if (isCancel(displayName)) return;
+	return displayName.trim();
+};
 const resolveRequestedDirectory = async (directory, shouldPrompt) => {
 	let currentDirectoryEntries = [];
 	if (!directory && shouldPrompt) currentDirectoryEntries = await fs.readdir(process.cwd());
@@ -1527,14 +2196,20 @@ const confirmScaffoldTarget = async (root, template, shouldPrompt, options) => {
 	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 resolveProjectSlug = async (providedSlug, directory, shouldPrompt) => {
 	const defaultProjectSlug = deriveDefaultProjectSlug(directory, process.cwd());
-	if (providedName) return providedName;
+	if (providedSlug) return providedSlug;
 	if (!shouldPrompt) return defaultProjectSlug;
 	return await promptForProjectSlug(defaultProjectSlug);
 };
-const writeScaffoldFiles = async (root, template, projectSlug) => {
-	for (const file of getScaffoldFiles(template, { projectSlug })) {
+const resolveDisplayName = async (providedDisplayName, projectSlug, shouldPrompt) => {
+	const defaultDisplayName = deriveDisplayNameFromProjectSlug(projectSlug);
+	if (providedDisplayName?.trim()) return providedDisplayName.trim();
+	if (!shouldPrompt) return defaultDisplayName;
+	return await promptForDisplayName(defaultDisplayName);
+};
+const writeScaffoldFiles = async (root, template, options) => {
+	for (const file of getScaffoldFiles(template, options)) {
 		const filePath = path.join(root, file.path);
 		await fs.mkdir(path.dirname(filePath), { recursive: true });
 		if (file.type === "symlink") {
@@ -1552,9 +2227,13 @@ const fetchUserEmail = async (apiUrl, token) => {
 	}
 };
 const resolvePushConfig = async (config, options) => {
-	const project = options.project ?? process.env["BLODEMD_PROJECT"] ?? config.name;
+	const { project, usedLegacyNameFallback } = resolveProjectTarget({
+		cliProject: options.project,
+		config,
+		envProject: process.env[BLODE_PROJECT_ENV]
+	});
 	const apiUrl = options.apiUrl ?? process.env["BLODEMD_API_URL"] ?? "https://api.blode.md";
-	const authToken = (await resolveAuthToken(options.apiKey))?.token;
+	const authToken = (await resolveAuthToken())?.token;
 	const branch = options.branch ?? process.env["BLODEMD_BRANCH"] ?? process.env.GITHUB_REF_NAME ?? readGitValue([
 		"rev-parse",
 		"--abbrev-ref",
@@ -1565,35 +2244,42 @@ const resolvePushConfig = async (config, options) => {
 		"-1",
 		"--pretty=%s"
 	]);
-	if (!project) throw new Error("Missing project slug. Set \"name\" in docs.json, pass --project, or set BLODEMD_PROJECT.");
-	if (!authToken) throw new Error("Missing credentials. Run \"blodemd login\", pass --api-key, or set BLODEMD_API_KEY.");
+	if (!project) throw new Error("Missing project slug. Set \"slug\" in docs.json, pass --project, or set BLODEMD_PROJECT.");
+	const projectSlugError = getProjectSlugError(project);
+	if (projectSlugError) {
+		if (usedLegacyNameFallback) throw new Error(`docs.json.name is not a valid deployment slug. Add "slug" to docs.json, pass --project, or set BLODEMD_PROJECT. ${projectSlugError}`);
+		throw new Error(`Invalid project slug "${project}". ${projectSlugError}`);
+	}
+	if (!authToken) throw new Error("Not logged in. Run \"blodemd login\" to authenticate.");
 	return {
 		apiUrl,
 		authToken,
 		branch,
 		commitMessage,
-		project
+		project,
+		projectDisplayName: config.name?.trim() || project,
+		usedLegacyNameFallback
 	};
 };
-const autoCreateProject = async (project, apiUrl, headers) => {
+const autoCreateProject = async (project, projectDisplayName, apiUrl, headers) => {
 	if (!(await readAuthFile())?.session) throw new Error(`Project "${project}" not found. Create it at blode.md or login with "blodemd login" to auto-create.`);
 	const shouldCreate = await confirm({ message: `Project "${project}" doesn't exist. Create it?` });
 	if (isCancel(shouldCreate) || !shouldCreate) return false;
 	const createResult = await requestJson(new URL("/projects", apiUrl).toString(), {
 		body: JSON.stringify({
-			name: project,
+			name: projectDisplayName,
 			slug: project
 		}),
 		headers,
 		method: "POST"
 	}, "Failed to create project");
-	log.success(`Project ${chalk.cyan(createResult.project.slug)} created`);
-	log.info(`API key for CI: ${chalk.dim(createResult.token)}`);
+	log.success(`Project ${chalk.cyan(createResult.slug)} created`);
 	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.`);
+	if (options?.name && !options.slug) log.warn(`"${chalk.cyan("--name")}" is deprecated. Use ${chalk.cyan("--slug")} instead.`);
 	try {
 		const template = options?.template ?? "minimal";
 		const shouldPrompt = isInteractiveTerminal() && !options?.yes;
@@ -1608,15 +2294,24 @@ const scaffoldDocsSite = async (directory, options) => {
 			log.warn("Cancelled");
 			return;
 		}
-		const projectSlug = await resolveProjectSlug(options?.name, resolvedDirectory, shouldPrompt);
+		const projectSlug = await resolveProjectSlug(options?.slug ?? options?.name, resolvedDirectory, shouldPrompt);
 		if (!projectSlug) {
 			log.warn("Cancelled");
 			return;
 		}
+		const displayName = await resolveDisplayName(options?.displayName, projectSlug, shouldPrompt);
+		if (!displayName) {
+			log.warn("Cancelled");
+			return;
+		}
 		await fs.mkdir(root, { recursive: true });
-		await writeScaffoldFiles(root, template, projectSlug);
+		await writeScaffoldFiles(root, template, {
+			displayName,
+			projectSlug
+		});
 		log.success(`Docs scaffolded in ${chalk.cyan(root)}`);
 		if (template === "starter") log.info("Starter template includes brand assets and helper files.");
+		log.info(`Display name: ${chalk.cyan(displayName)}`);
 		log.info(`Project slug: ${chalk.cyan(projectSlug)}`);
 		log.info("Done");
 	} catch (error) {
@@ -1648,29 +2343,9 @@ program.name("blodemd").description("Blode.md CLI").version(cliVersion);
 program.hook("preAction", () => {
 	assertSupportedNodeVersion();
 });
-program.command("login").description("Authenticate with Blode.md").option("--token", "Paste an API key instead of using browser login").option("--port <port>", "Loopback callback port", String(DEFAULT_OAUTH_CALLBACK_PORT)).option("--timeout <seconds>", "OAuth timeout in seconds", String(180)).option("--no-open", "Print URL instead of opening the browser").action(async (options) => {
+program.command("login").description("Authenticate with Blode.md via GitHub in your browser").option("--port <port>", "Loopback callback port", String(DEFAULT_OAUTH_CALLBACK_PORT)).option("--timeout <seconds>", "OAuth timeout in seconds", String(180)).option("--no-open", "Print URL instead of opening the browser").action(async (options) => {
 	intro(chalk.bold("blodemd login"));
 	try {
-		if (options.token) {
-			const apiKey = await password({
-				message: "Enter your API key",
-				validate: (value) => {
-					if (!value) return "API key is required.";
-				}
-			});
-			if (isCancel(apiKey)) {
-				log.warn("Cancelled");
-				return;
-			}
-			await writeStoredApiKey({
-				apiKey,
-				type: "api-key"
-			});
-			const prefix = apiKey.split(".")[0] ?? apiKey.slice(0, 12);
-			log.success(`Authenticated as ${chalk.cyan(prefix)}`);
-			log.info("Done");
-			return;
-		}
 		const { authorizeUrl, tokenUrl } = buildOAuthUrls(resolveSupabaseConfig());
 		const clientId = OAUTH_CLIENT_ID;
 		const port = parsePort(options.port);
@@ -1687,6 +2362,7 @@ program.command("login").description("Authenticate with Blode.md").option("--tok
 		authUrl.searchParams.set("code_challenge_method", "S256");
 		authUrl.searchParams.set("state", state);
 		authUrl.searchParams.set("scope", "openid email profile");
+		authUrl.searchParams.set("provider", "github");
 		const callbackPromise = waitForOAuthCode({
 			expectedState: state,
 			redirectUrl,
@@ -1739,15 +2415,6 @@ program.command("whoami").description("Show current authentication").action(asyn
 			log.warn("Not logged in. Run \"blodemd login\" to authenticate.");
 			return;
 		}
-		if (resolved.source === "environment") {
-			log.info("Authenticated via BLODEMD_API_KEY environment variable");
-			return;
-		}
-		if (!resolved.expiresAt && !resolved.user) {
-			const prefix = resolved.token.split(".")[0] ?? resolved.token.slice(0, 12);
-			log.info(`Logged in with API key ${chalk.cyan(prefix)}`);
-			return;
-		}
 		const status = resolveTokenStatus(resolved);
 		const email = resolved.user?.email ?? await fetchUserEmail(process.env["BLODEMD_API_URL"] ?? "https://api.blode.md", resolved.token);
 		if (email) log.info(`Logged in as ${chalk.cyan(email)}`);
@@ -1757,17 +2424,21 @@ program.command("whoami").description("Show current authentication").action(asyn
 		reportCommandError("Whoami 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) => {
+program.command("new").description("Create a new blode.md documentation site").argument("[directory]", "target directory").option("--slug <slug>", "project slug for docs.json", parseProjectSlug).option("--name <slug>", "deprecated alias for --slug", parseProjectSlug).option("--display-name <name>", "display name for docs.json").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, {
+		displayName: options.displayName,
 		name: options.name,
+		slug: options.slug ?? 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) => {
+program.command("init", { hidden: true }).argument("[directory]", "target directory").option("--slug <slug>", "project slug for docs.json", parseProjectSlug).option("--name <slug>", "deprecated alias for --slug", parseProjectSlug).option("--display-name <name>", "display name for docs.json").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",
+		displayName: options.displayName,
 		name: options.name,
+		slug: options.slug ?? options.name,
 		template: options.template,
 		yes: options.yes
 	});
@@ -1783,7 +2454,7 @@ program.command("validate").description("Validate docs.json").argument("[dir]",
 		reportCommandError("Validation failed", error);
 	}
 });
-program.command("push").description("Deploy docs").argument("[dir]", "docs directory").option("--project <slug>", "project slug (env: BLODEMD_PROJECT)").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--api-key <token>", "API key (env: BLODEMD_API_KEY)").option("--branch <name>", "git branch (env: BLODEMD_BRANCH)").option("--message <msg>", "deploy message (env: BLODEMD_COMMIT_MESSAGE)").action(async (dir, options) => {
+program.command("push").description("Deploy docs").argument("[dir]", "docs directory").option("--project <slug>", "project slug (env: BLODEMD_PROJECT)").option("--api-url <url>", "API URL (env: BLODEMD_API_URL)").option("--branch <name>", "git branch (env: BLODEMD_BRANCH)").option("--message <msg>", "deploy message (env: BLODEMD_COMMIT_MESSAGE)").action(async (dir, options) => {
 	intro(chalk.bold("blodemd push"));
 	const s = spinner();
 	try {
@@ -1792,7 +2463,8 @@ program.command("push").description("Deploy docs").argument("[dir]", "docs direc
 		const { config, warnings } = await loadValidatedSiteConfig(root);
 		s.stop("Configuration valid");
 		for (const warning of warnings) log.warn(warning);
-		const { project, apiUrl, authToken, branch, commitMessage } = await resolvePushConfig(config, options);
+		const { project, projectDisplayName, apiUrl, authToken, branch, commitMessage, usedLegacyNameFallback } = await resolvePushConfig(config, options);
+		if (usedLegacyNameFallback) log.warn(LEGACY_PROJECT_NAME_FALLBACK_WARNING);
 		s.start("Collecting files");
 		const files = await collectFiles(root);
 		if (files.length === 0) throw new Error("No files found to deploy.");
@@ -1817,7 +2489,7 @@ program.command("push").description("Deploy docs").argument("[dir]", "docs direc
 		} catch (error) {
 			if (!(error instanceof Error ? error.message : "").includes("404")) throw error;
 			s.stop("Project not found");
-			if (!await autoCreateProject(project, apiUrl, headers)) {
+			if (!await autoCreateProject(project, projectDisplayName, apiUrl, headers)) {
 				log.info("Cancelled");
 				return;
 			}