blodemd 0.0.10 → 0.0.11

package/dist/cli.mjs

@@ -20,6 +20,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 //#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";
@@ -831,10 +832,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 +882,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 +903,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 +916,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 +961,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 +1537,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 +1579,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,7 +1610,11 @@ 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 branch = options.branch ?? process.env["BLODEMD_BRANCH"] ?? process.env.GITHUB_REF_NAME ?? readGitValue([
@@ -1565,23 +1627,30 @@ 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 (!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("Missing credentials. Run \"blodemd login\", pass --api-key, or set BLODEMD_API_KEY.");
 	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,
@@ -1594,6 +1663,7 @@ const autoCreateProject = async (project, apiUrl, headers) => {
 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 +1678,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) {
@@ -1757,17 +1836,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
 	});
@@ -1792,7 +1875,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 +1901,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;
 			}