@tenphi/cookbook 0.17.0 → 0.18.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { resolveDocsTheme } from "@tenphi/starlight";
-import { createDocsGraph, formatDiagnostics, materializePackage, normalizeDocsConfig, readDocsLock, reconcileDocsLock, resolveDocsProject, writeDocsLock } from "@tenphi/docs";
+import { createDocsGraph, formatDiagnostics, materializePackage, normalizeDocsConfig, readDocsLock, reconcileDocsLock, resolveDocsProject, validateBuiltDocs, validateProjectAssets, writeDocsLock } from "@tenphi/docs";
 import { cp, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { parseArgs } from "node:util";
@@ -16,6 +16,9 @@ try {
 			},
 			root: { type: "string" },
 			config: { type: "string" },
+			out: { type: "string" },
+			url: { type: "string" },
+			"public-dir": { type: "string" },
 			"dry-run": {
 				type: "boolean",
 				default: false
@@ -31,14 +34,35 @@ try {
 	if (values.help || positionals.length === 0) printHelp();
 	else {
 		const command = positionals[0];
-		if (command !== "doctor" && command !== "update") throw new Error(`Unknown command: ${command ?? ""}.`);
-		if (command === "doctor" && (positionals.length > 1 || values["dry-run"])) throw new Error("doctor does not accept package selectors or --dry-run.");
+		if (![
+			"doctor",
+			"update",
+			"check-build"
+		].includes(command)) throw new Error(`Unknown command: ${command ?? ""}.`);
+		if (command !== "update" && (positionals.length > 1 || values["dry-run"])) throw new Error(`${command} does not accept package selectors or --dry-run.`);
+		if (command !== "check-build" && (values.out || values.url)) throw new Error("--out and --url are only supported by check-build.");
+		if (values["public-dir"] && command !== "doctor") throw new Error("--public-dir is only supported by doctor.");
 		const project = await resolveDocsProject({
 			root: resolve(values.root ?? process.cwd()),
 			...values.config ? { configFile: values.config } : {}
 		});
-		if (command === "doctor") await doctor(project, values.json);
-		else await update(project, positionals.slice(1), values.json, values["dry-run"]);
+		if (command === "doctor") await doctor(project, values.json, values["public-dir"] ? resolve(values.root ?? process.cwd(), values["public-dir"]) : resolve(values.root ?? process.cwd(), "public"));
+		else if (command === "check-build") {
+			const graph = await createDocsGraph(project);
+			const report = await validateBuiltDocs({
+				directory: resolve(values.root ?? process.cwd(), values.out ?? "dist"),
+				graph,
+				...values.url ? { deployedUrl: values.url } : {}
+			});
+			report.diagnostics.unshift(...graph.diagnostics);
+			report.ok = !report.diagnostics.some((d) => d.severity === "error");
+			if (values.json) console.log(JSON.stringify(report, null, 2));
+			else {
+				if (report.diagnostics.length) console.log(formatDiagnostics(report.diagnostics));
+				console.log(`${report.ok ? "Passed" : "Failed"} ${report.scope} checks: ${report.pages} pages, ${report.assets} assets${report.checkedUrls ? `, ${report.checkedUrls} deployed URLs` : ""}.`);
+			}
+			if (!report.ok) process.exitCode = 1;
+		} else await update(project, positionals.slice(1), values.json, values["dry-run"]);
 	}
 } catch (error) {
 	const message = error instanceof Error ? error.message : String(error);
@@ -56,19 +80,25 @@ try {
 	else console.error(formatDiagnostics(diagnostics));
 	process.exitCode = 1;
 }
-async function doctor(project, json) {
+async function doctor(project, json, publicDirectory) {
 	const theme = resolveDocsTheme(project.config.theme);
 	const graph = await createDocsGraph(project);
-	const diagnostics = [...graph.diagnostics, ...theme.diagnostics];
+	const diagnostics = [
+		...graph.diagnostics,
+		...theme.diagnostics,
+		...await validateProjectAssets(project, graph, publicDirectory)
+	];
 	const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === "error");
 	if (json) console.log(JSON.stringify({
 		ok: !hasErrors,
+		scope: "preflight",
+		buildVerified: false,
 		pages: graph.entries.length,
 		assets: graph.assets.length,
 		diagnostics
 	}, null, 2));
 	else if (diagnostics.length > 0) console.log(formatDiagnostics(diagnostics));
-	else console.log(`Cookbook is healthy: ${graph.entries.length} pages, ${graph.assets.length} assets.`);
+	else console.log(`Preflight passed: ${graph.entries.length} pages, ${graph.assets.length} content assets. MDX compilation, remote fonts, and deployment are not checked. Run astro build and cookbook check-build.`);
 	if (hasErrors) process.exitCode = 1;
 }
 async function update(project, packages, json, dryRun) {
@@ -111,7 +141,7 @@ async function update(project, packages, json, dryRun) {
 	}
 }
 function printHelp() {
-	console.log(`Usage: cookbook <command> [options]\n\nCommands:\n  doctor             Validate content, configuration, and theme\n  update [packages]  Reconcile configured package sources and their lock\n\nOptions:\n  --root <directory>\n  --config <path>\n  --dry-run          Preview an update without writing files\n  --json\n  -h, --help`);
+	console.log(`Usage: cookbook <command> [options]\n\nCommands:\n  doctor             Check configuration, content graph, theme, and local files\n  check-build        Inspect production output and optionally deployed URLs\n  update [packages]  Reconcile configured package sources and their lock\n\nOptions:\n  --root <directory>\n  --config <path>\n  --public-dir <directory>  Local public assets for doctor (default: public)\n  --out <directory>        Built output (default: dist)\n  --url <base-url>         Also check a deployed site\n  --dry-run          Preview an update without writing files\n  --json\n  -h, --help`);
 	process.exit(0);
 }
 //#endregion

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { cp, mkdir } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { parseArgs } from \"node:util\";\nimport {\n  createDocsGraph,\n  formatDiagnostics,\n  materializePackage,\n  normalizeDocsConfig,\n  readDocsLock,\n  reconcileDocsLock,\n  resolveDocsProject,\n  writeDocsLock,\n  type DocsDiagnostic,\n  type DocsProject,\n} from \"@tenphi/docs\";\nimport { resolveDocsTheme } from \"@tenphi/starlight\";\n\nlet jsonOutput = process.argv.slice(2).includes(\"--json\");\n\ntry {\n  const { positionals, values } = parseArgs({\n    allowPositionals: true,\n    options: {\n      json: { type: \"boolean\", default: false },\n      root: { type: \"string\" },\n      config: { type: \"string\" },\n      \"dry-run\": { type: \"boolean\", default: false },\n      help: { type: \"boolean\", short: \"h\", default: false },\n    },\n  });\n  jsonOutput = values.json;\n  if (values.help || positionals.length === 0) {\n    printHelp();\n  } else {\n    const command = positionals[0];\n    if (command !== \"doctor\" && command !== \"update\") {\n      throw new Error(`Unknown command: ${command ?? \"\"}.`);\n    }\n    if (command === \"doctor\" && (positionals.length > 1 || values[\"dry-run\"])) {\n      throw new Error(\"doctor does not accept package selectors or --dry-run.\");\n    }\n    const project = await resolveDocsProject({\n      root: resolve(values.root ?? process.cwd()),\n      ...(values.config ? { configFile: values.config } : {}),\n    });\n    if (command === \"doctor\") await doctor(project, values.json);\n    else\n      await update(\n        project,\n        positionals.slice(1),\n        values.json,\n        values[\"dry-run\"],\n      );\n  }\n} catch (error) {\n  const message = error instanceof Error ? error.message : String(error);\n  const diagnostics: DocsDiagnostic[] =\n    error && typeof error === \"object\" && \"diagnostics\" in error\n      ? (error.diagnostics as DocsDiagnostic[])\n      : [{ code: \"COOKBOOK_CLI_ERROR\", severity: \"error\", message }];\n  if (jsonOutput) {\n    console.log(\n      JSON.stringify({ ok: false, pages: 0, assets: 0, diagnostics }, null, 2),\n    );\n  } else {\n    console.error(formatDiagnostics(diagnostics));\n  }\n  process.exitCode = 1;\n}\n\nasync function doctor(project: DocsProject, json: boolean): Promise<void> {\n  const theme = resolveDocsTheme(project.config.theme);\n  const graph = await createDocsGraph(project);\n  const diagnostics = [...graph.diagnostics, ...theme.diagnostics];\n  const hasErrors = diagnostics.some(\n    (diagnostic) => diagnostic.severity === \"error\",\n  );\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: !hasErrors,\n          pages: graph.entries.length,\n          assets: graph.assets.length,\n          diagnostics,\n        },\n        null,\n        2,\n      ),\n    );\n  } else if (diagnostics.length > 0) {\n    console.log(formatDiagnostics(diagnostics));\n  } else {\n    console.log(\n      `Cookbook is healthy: ${graph.entries.length} pages, ${graph.assets.length} assets.`,\n    );\n  }\n  if (hasErrors) process.exitCode = 1;\n}\n\nasync function update(\n  project: DocsProject,\n  packages: string[],\n  json: boolean,\n  dryRun: boolean,\n): Promise<void> {\n  const existing = await readDocsLock(project.root);\n  const next = await reconcileDocsLock(project.config, existing, { packages });\n  const changes = next.sources.map((source) => ({\n    requested: source.requested,\n    from:\n      existing?.sources.find(\n        (current) => current.requested === source.requested,\n      )?.resolved ?? null,\n    to: source.resolved,\n  }));\n  const removed =\n    existing?.sources\n      .filter(\n        (source) =>\n          !next.sources.some(\n            (current) => current.requested === source.requested,\n          ),\n      )\n      .map((source) => source.requested) ?? [];\n  if (!dryRun) {\n    const build = normalizeDocsConfig(project.config).build;\n    for (const source of next.sources) {\n      if (!source.vendored) continue;\n      const current = existing?.sources.find(\n        (entry) => entry.requested === source.requested,\n      );\n      if (\n        current?.vendored === source.vendored &&\n        current.integrity === source.integrity\n      )\n        continue;\n      const { vendored, ...remote } = source;\n      const artifact = await materializePackage(remote, build, project.root);\n      const destination = resolve(project.root, vendored);\n      await mkdir(dirname(destination), { recursive: true });\n      await cp(artifact, destination, { recursive: true });\n    }\n    await writeDocsLock(project.root, next);\n  }\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: true,\n          pages: 0,\n          assets: 0,\n          diagnostics: [],\n          dryRun,\n          changes,\n          removed,\n          lock: next,\n        },\n        null,\n        2,\n      ),\n    );\n  } else {\n    for (const change of changes)\n      console.log(\n        `${change.requested}: ${change.from ?? \"(new)\"} -> ${change.to}`,\n      );\n    for (const source of removed) console.log(`Removed ${source}`);\n    console.log(\n      dryRun\n        ? \"Dry run: cookbook.lock.json is unchanged.\"\n        : \"Updated cookbook.lock.json.\",\n    );\n  }\n}\n\nfunction printHelp(): never {\n  console.log(\n    `Usage: cookbook <command> [options]\\n\\nCommands:\\n  doctor             Validate content, configuration, and theme\\n  update [packages]  Reconcile configured package sources and their lock\\n\\nOptions:\\n  --root <directory>\\n  --config <path>\\n  --dry-run          Preview an update without writing files\\n  --json\\n  -h, --help`,\n  );\n  process.exit(0);\n}\n"],"mappings":"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"}
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { cp, mkdir } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { parseArgs } from \"node:util\";\nimport {\n  createDocsGraph,\n  formatDiagnostics,\n  materializePackage,\n  normalizeDocsConfig,\n  readDocsLock,\n  reconcileDocsLock,\n  resolveDocsProject,\n  writeDocsLock,\n  validateProjectAssets,\n  validateBuiltDocs,\n  type DocsDiagnostic,\n  type DocsProject,\n} from \"@tenphi/docs\";\nimport { resolveDocsTheme } from \"@tenphi/starlight\";\n\nlet jsonOutput = process.argv.slice(2).includes(\"--json\");\n\ntry {\n  const { positionals, values } = parseArgs({\n    allowPositionals: true,\n    options: {\n      json: { type: \"boolean\", default: false },\n      root: { type: \"string\" },\n      config: { type: \"string\" },\n      out: { type: \"string\" },\n      url: { type: \"string\" },\n      \"public-dir\": { type: \"string\" },\n      \"dry-run\": { type: \"boolean\", default: false },\n      help: { type: \"boolean\", short: \"h\", default: false },\n    },\n  });\n  jsonOutput = values.json;\n  if (values.help || positionals.length === 0) {\n    printHelp();\n  } else {\n    const command = positionals[0];\n    if (![\"doctor\", \"update\", \"check-build\"].includes(command!)) {\n      throw new Error(`Unknown command: ${command ?? \"\"}.`);\n    }\n    if (command !== \"update\" && (positionals.length > 1 || values[\"dry-run\"])) {\n      throw new Error(\n        `${command} does not accept package selectors or --dry-run.`,\n      );\n    }\n    if (command !== \"check-build\" && (values.out || values.url))\n      throw new Error(\"--out and --url are only supported by check-build.\");\n    if (values[\"public-dir\"] && command !== \"doctor\")\n      throw new Error(\"--public-dir is only supported by doctor.\");\n    const project = await resolveDocsProject({\n      root: resolve(values.root ?? process.cwd()),\n      ...(values.config ? { configFile: values.config } : {}),\n    });\n    if (command === \"doctor\")\n      await doctor(\n        project,\n        values.json,\n        values[\"public-dir\"]\n          ? resolve(values.root ?? process.cwd(), values[\"public-dir\"])\n          : resolve(values.root ?? process.cwd(), \"public\"),\n      );\n    else if (command === \"check-build\") {\n      const graph = await createDocsGraph(project);\n      const report = await validateBuiltDocs({\n        directory: resolve(values.root ?? process.cwd(), values.out ?? \"dist\"),\n        graph,\n        ...(values.url ? { deployedUrl: values.url } : {}),\n      });\n      report.diagnostics.unshift(...graph.diagnostics);\n      report.ok = !report.diagnostics.some((d) => d.severity === \"error\");\n      if (values.json) console.log(JSON.stringify(report, null, 2));\n      else {\n        if (report.diagnostics.length)\n          console.log(formatDiagnostics(report.diagnostics));\n        console.log(\n          `${report.ok ? \"Passed\" : \"Failed\"} ${report.scope} checks: ${report.pages} pages, ${report.assets} assets${report.checkedUrls ? `, ${report.checkedUrls} deployed URLs` : \"\"}.`,\n        );\n      }\n      if (!report.ok) process.exitCode = 1;\n    } else\n      await update(\n        project,\n        positionals.slice(1),\n        values.json,\n        values[\"dry-run\"],\n      );\n  }\n} catch (error) {\n  const message = error instanceof Error ? error.message : String(error);\n  const diagnostics: DocsDiagnostic[] =\n    error && typeof error === \"object\" && \"diagnostics\" in error\n      ? (error.diagnostics as DocsDiagnostic[])\n      : [{ code: \"COOKBOOK_CLI_ERROR\", severity: \"error\", message }];\n  if (jsonOutput) {\n    console.log(\n      JSON.stringify({ ok: false, pages: 0, assets: 0, diagnostics }, null, 2),\n    );\n  } else {\n    console.error(formatDiagnostics(diagnostics));\n  }\n  process.exitCode = 1;\n}\n\nasync function doctor(\n  project: DocsProject,\n  json: boolean,\n  publicDirectory?: string,\n): Promise<void> {\n  const theme = resolveDocsTheme(project.config.theme);\n  const graph = await createDocsGraph(project);\n  const diagnostics = [\n    ...graph.diagnostics,\n    ...theme.diagnostics,\n    ...(await validateProjectAssets(project, graph, publicDirectory)),\n  ];\n  const hasErrors = diagnostics.some(\n    (diagnostic) => diagnostic.severity === \"error\",\n  );\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: !hasErrors,\n          scope: \"preflight\",\n          buildVerified: false,\n          pages: graph.entries.length,\n          assets: graph.assets.length,\n          diagnostics,\n        },\n        null,\n        2,\n      ),\n    );\n  } else if (diagnostics.length > 0) {\n    console.log(formatDiagnostics(diagnostics));\n  } else {\n    console.log(\n      `Preflight passed: ${graph.entries.length} pages, ${graph.assets.length} content assets. MDX compilation, remote fonts, and deployment are not checked. Run astro build and cookbook check-build.`,\n    );\n  }\n  if (hasErrors) process.exitCode = 1;\n}\n\nasync function update(\n  project: DocsProject,\n  packages: string[],\n  json: boolean,\n  dryRun: boolean,\n): Promise<void> {\n  const existing = await readDocsLock(project.root);\n  const next = await reconcileDocsLock(project.config, existing, { packages });\n  const changes = next.sources.map((source) => ({\n    requested: source.requested,\n    from:\n      existing?.sources.find(\n        (current) => current.requested === source.requested,\n      )?.resolved ?? null,\n    to: source.resolved,\n  }));\n  const removed =\n    existing?.sources\n      .filter(\n        (source) =>\n          !next.sources.some(\n            (current) => current.requested === source.requested,\n          ),\n      )\n      .map((source) => source.requested) ?? [];\n  if (!dryRun) {\n    const build = normalizeDocsConfig(project.config).build;\n    for (const source of next.sources) {\n      if (!source.vendored) continue;\n      const current = existing?.sources.find(\n        (entry) => entry.requested === source.requested,\n      );\n      if (\n        current?.vendored === source.vendored &&\n        current.integrity === source.integrity\n      )\n        continue;\n      const { vendored, ...remote } = source;\n      const artifact = await materializePackage(remote, build, project.root);\n      const destination = resolve(project.root, vendored);\n      await mkdir(dirname(destination), { recursive: true });\n      await cp(artifact, destination, { recursive: true });\n    }\n    await writeDocsLock(project.root, next);\n  }\n  if (json) {\n    console.log(\n      JSON.stringify(\n        {\n          ok: true,\n          pages: 0,\n          assets: 0,\n          diagnostics: [],\n          dryRun,\n          changes,\n          removed,\n          lock: next,\n        },\n        null,\n        2,\n      ),\n    );\n  } else {\n    for (const change of changes)\n      console.log(\n        `${change.requested}: ${change.from ?? \"(new)\"} -> ${change.to}`,\n      );\n    for (const source of removed) console.log(`Removed ${source}`);\n    console.log(\n      dryRun\n        ? \"Dry run: cookbook.lock.json is unchanged.\"\n        : \"Updated cookbook.lock.json.\",\n    );\n  }\n}\n\nfunction printHelp(): never {\n  console.log(\n    `Usage: cookbook <command> [options]\\n\\nCommands:\\n  doctor             Check configuration, content graph, theme, and local files\\n  check-build        Inspect production output and optionally deployed URLs\\n  update [packages]  Reconcile configured package sources and their lock\\n\\nOptions:\\n  --root <directory>\\n  --config <path>\\n  --public-dir <directory>  Local public assets for doctor (default: public)\\n  --out <directory>        Built output (default: dist)\\n  --url <base-url>         Also check a deployed site\\n  --dry-run          Preview an update without writing files\\n  --json\\n  -h, --help`,\n  );\n  process.exit(0);\n}\n"],"mappings":"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"}

package/dist/config.d.ts

@@ -1,3 +1,3 @@
 
-import { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStylesConfig, DocsConfig, DocsSource, ThemeConfig, ThemeFont, ThemeFontFile, ThemeFonts, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs/config";
-export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStylesConfig, type DocsConfig, type DocsSource, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, defineDocsConfig, mergeDocsConfig };
+import { BreadcrumbItem, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStylesConfig, DocsConfig, DocsSource, FontLoadingConfig, PageSeoConfig, SiteLogoConfig, SiteSeoConfig, SocialImage, TableOfContentsConfig, ThemeConfig, ThemeFont, ThemeFontFile, ThemeFonts, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs/config";
+export { type BreadcrumbItem, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStylesConfig, type DocsConfig, type DocsSource, type FontLoadingConfig, type PageSeoConfig, type SiteLogoConfig, type SiteSeoConfig, type SocialImage, type TableOfContentsConfig, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, defineDocsConfig, mergeDocsConfig };

package/dist/content.d.ts

@@ -0,0 +1,3 @@
+
+import { getCookbookCollection, getCookbookEntry } from "@tenphi/starlight/content";
+export { getCookbookCollection, getCookbookEntry };

package/dist/content.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { getCookbookCollection, getCookbookEntry } from "@tenphi/starlight/content";
+export { getCookbookCollection, getCookbookEntry };

package/dist/eslint-plugin.d.ts

@@ -1,3 +1,3 @@
 
-import eslint_plugin_default, { ResolvedConfig, StyleFunctionConfig, TastyValidationConfig, recommended, strict, validationConfig } from "@tenphi/starlight/eslint-plugin";
-export { type ResolvedConfig, type StyleFunctionConfig, type TastyValidationConfig, eslint_plugin_default as default, recommended, strict, validationConfig };
+import eslint_plugin_default, { ResolvedConfig, StyleFunctionConfig, TastyValidationConfig, createValidationConfig, recommended, strict, validationConfig } from "@tenphi/starlight/eslint-plugin";
+export { type ResolvedConfig, type StyleFunctionConfig, type TastyValidationConfig, createValidationConfig, eslint_plugin_default as default, recommended, strict, validationConfig };

package/dist/eslint-plugin.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import eslint_plugin_default, { recommended, strict, validationConfig } from "@tenphi/starlight/eslint-plugin";
-export { eslint_plugin_default as default, recommended, strict, validationConfig };
+import eslint_plugin_default, { createValidationConfig, recommended, strict, validationConfig } from "@tenphi/starlight/eslint-plugin";
+export { createValidationConfig, eslint_plugin_default as default, recommended, strict, validationConfig };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 
 import starlight_default, { CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/starlight";
-import { BrandConfig, BrandDeclaration, BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStyleConfig, ComponentStyles, ComponentStylesConfig, ComponentsConfig, ContentConfig, CookbookComponentName, CookbookComponentStyles, CookbookComponentSubElementName, DocsAsset, DocsConfig, DocsDiagnostic, DocsEntry, DocsFrontmatter, DocsGraph, DocsRoute, DocsSource, EditLinkConfig, HeadConfig, LocaleConfig, MarkdownConfig, NavigationConfig, NavigationItem, NavigationPlacement, NavigationTab, SearchConfig, SiteConfig, SiteIconConfig, SiteVersion, ThemeConfig, ThemeFont, ThemeFontFile, ThemeFonts, ThemePaletteColor, ThemePaletteConfig, ThemeTokenValue, ThemeTokens, TypographyPreset, TypographyPresets, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
-export { type BrandConfig, type BrandDeclaration, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type CookbookComponentStyles, type CookbookComponentSubElementName, type CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, type DocsAsset, type DocsConfig, type DocsDiagnostic, type DocsEntry, type DocsFrontmatter, type DocsGraph, type DocsRoute, type DocsSource, type EditLinkConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type SearchConfig, type SiteConfig, type SiteIconConfig, type SiteVersion, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, type ThemePaletteColor, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, starlight_default as default, defineDocsConfig, mergeDocsConfig };
+import { BrandConfig, BrandDeclaration, BreadcrumbItem, BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, ComponentStyleConfig, ComponentStyles, ComponentStylesConfig, ComponentsConfig, ContentConfig, CookbookComponentName, CookbookComponentStyles, CookbookComponentSubElementName, DocsAsset, DocsConfig, DocsDiagnostic, DocsEntry, DocsFrontmatter, DocsGraph, DocsRoute, DocsSource, EditLinkConfig, FontLoadingConfig, HeadConfig, LocaleConfig, MarkdownConfig, NavigationConfig, NavigationItem, NavigationPlacement, NavigationTab, PageSeoConfig, SearchConfig, SiteConfig, SiteIconConfig, SiteLogoConfig, SiteSeoConfig, SiteVersion, SocialImage, TableOfContentsConfig, ThemeConfig, ThemeFont, ThemeFontFile, ThemeFonts, ThemePaletteColor, ThemePaletteConfig, ThemeTokenValue, ThemeTokens, TypographyPreset, TypographyPresets, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
+export { type BrandConfig, type BrandDeclaration, type BreadcrumbItem, type BuildConfig, COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, type ComponentStyleConfig, type ComponentStyles, type ComponentStylesConfig, type ComponentsConfig, type ContentConfig, type CookbookComponentName, type CookbookComponentStyles, type CookbookComponentSubElementName, type CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, type DocsAsset, type DocsConfig, type DocsDiagnostic, type DocsEntry, type DocsFrontmatter, type DocsGraph, type DocsRoute, type DocsSource, type EditLinkConfig, type FontLoadingConfig, type HeadConfig, type LocaleConfig, type MarkdownConfig, type NavigationConfig, type NavigationItem, type NavigationPlacement, type NavigationTab, type PageSeoConfig, type SearchConfig, type SiteConfig, type SiteIconConfig, type SiteLogoConfig, type SiteSeoConfig, type SiteVersion, type SocialImage, type TableOfContentsConfig, type ThemeConfig, type ThemeFont, type ThemeFontFile, type ThemeFonts, type ThemePaletteColor, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, starlight_default as default, defineDocsConfig, mergeDocsConfig };

package/dist/index.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
 import starlight_default, { DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/starlight";
-import { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
-export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, starlight_default as default, defineDocsConfig, mergeDocsConfig };
+import { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
+export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, starlight_default as default, defineDocsConfig, mergeDocsConfig };

package/docs/ai-agents.md

@@ -14,15 +14,14 @@ concrete task, for example:
 > Create a Cookbook site for this repository in `docs-site/`. Use the existing
 > README and `docs/` pages as sources. Set the public site URL to
 > `https://docs.example.com`, add a getting started page if one is missing,
-> and run the doctor and production build.
+> and run the complete validation command.
 
 From the repository root, the agent can run:
 
 ```sh
 npm create @tenphi/cookbook@latest docs-site -- --source . --site https://docs.example.com --yes
 cd docs-site
-npm run doctor
-npm run build
+npm run validate
 ```
 
 For a new project without existing documentation, omit `--source .`. To document
@@ -53,9 +52,21 @@ The HTML pages remain the primary source of information. Their text, headings,
 links, and page metadata are present in the static response, so an agent can
 read them without running client JavaScript. Write descriptive headings and
 link text, keep instructions current, and verify the production output with
-`npm run build` and `npm run preview`.
+`npm run validate` and `npm run preview`.
 
 Google's [AI Search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)
 prioritizes ordinary crawlability and useful content. It says `llms.txt` is
 not used by Google Search; Cookbook provides it for other agents that use the
 [llms.txt proposal](https://llmstxt.org/).
+
+## Read a published page
+
+Follow the page’s `rel="alternate" type="text/markdown"` link or its **Download Markdown**
+control for a clean reading representation with canonical/source/language/version
+metadata. Use the HTML for interactive component output omitted from Markdown.
+See [Publishing metadata](./publishing.md) for discovery and indexing controls.
+
+For maintenance, follow the [upgrade guide](./migration.md), then check the
+[deployed output](./deployment.md#validate-the-published-result). The
+[recipes](./recipes.md) provide complete starting configurations;
+[troubleshooting](./troubleshooting.md) explains common failures.

package/docs/authoring.mdx

@@ -51,8 +51,9 @@ and contrast modes.
 ## Code groups
 
 Pass labeled source strings to create an accessible tabbed code group. `language`
-is an optional visible label; these programmatic snippets render as escaped plain
-text. Ordinary fenced Markdown provides syntax highlighting.
+selects the Shiki grammar (defaults to plain text). Groups share semantic syntax
+colors, configured grammars/transformers, and copy controls with Markdown fences.
+Each panel retains keyboard-accessible tabs and readable fallback content.
 
 ```mdx
 <CodeGroup
@@ -74,13 +75,46 @@ text. Ordinary fenced Markdown provides syntax highlighting.
 
 ## Other components
 
-| Component | Props and behavior                                                                                                |
-| --------- | ----------------------------------------------------------------------------------------------------------------- |
-| `Card`    | Optional `title` and `href`; renders an article or link with slot content                                         |
-| `Steps`   | Ordered list container; supply `li` elements                                                                      |
-| `Logo`    | Optional `label`, `decorative`, and `class`; renders the Cookbook mark                                            |
-| `Preview` | Required `title`; optional `html`, `css`, and `javascript`; isolates examples in Shadow DOM or a sandboxed iframe |
+| Component | Props and behavior                                                                                  |
+| --------- | --------------------------------------------------------------------------------------------------- |
+| `Card`    | Optional `title` and `href`; renders an article or link with slot content                           |
+| `Steps`   | Ordered list container; supply `li` elements                                                        |
+| `Logo`    | Optional `label`, `decorative`, and `class`; renders the Cookbook mark                              |
+| `Preview` | Required `title`; optional `html`, `css`, and `javascript`; isolates examples in a sandboxed iframe |
 
 The public package exports each component's props type, such as `TabProps`,
 `CalloutProps`, and `CodeGroupProps`. Styles and all named sub-elements are
 listed in [Theme and components](./theme-and-components.md#style-customization).
+
+## On-page navigation
+
+Desktop pages show a table of contents. Opt into a compact disclosure below the
+header on smaller screens, globally in `docs.config.ts`:
+
+```ts
+tableOfContents: { mobile: true, minHeadingLevel: 2, maxHeadingLevel: 3 }
+```
+
+The same frontmatter field can change heading levels or set `mobile: false` on
+one page. `tableOfContents: false` disables both versions. Selecting a mobile
+contents link closes the disclosure and moves keyboard focus to the heading.
+Customize `theme.styles.MobileTableOfContents` and `TableOfContentsLayout`.
+
+## Hero images
+
+Use a relative local image in frontmatter. Cookbook reads its intrinsic dimensions
+and reserves the correct aspect ratio as the layout responds to screen width:
+
+```yaml
+hero:
+  tagline: Build something useful.
+  image:
+    file: ./assets/hero.png
+    alt: A preview of the documentation
+```
+
+Use `light` and `dark` instead of `file` for appearance variants; both must have
+the same aspect ratio. Remote or public-path images require explicit `width` and
+`height`. Hero images load eagerly with high fetch priority; use ordinary Markdown
+images for content farther down the page. `theme.styles.Hero.Visual` controls
+responsive sizing without changing the intrinsic dimensions.

package/docs/cli.md

@@ -20,19 +20,61 @@ npx @tenphi/cookbook doctor --config ./config/manual.ts --json
 
 Doctor checks the content graph, configuration, semantic theme, links, assets,
 navigation, and redirects without starting Astro. It exits non-zero for errors.
-It does not compile MDX or replace a full Astro build.
+It validates configured local font files, logo/favicon sources, public social
+images, and component override paths. `--public-dir ./static` supports a custom
+Astro public directory; the default is `public/` in the app directory.
+
+Doctor reports **preflight** health. It does not compile MDX or components,
+download Google fonts, check image decoding, inspect Astro plugins, or verify
+the emitted site. These checks happen during the build and output validation.
 
 JSON results use a stable envelope, including configuration failures:
 
 ```json
 {
   "ok": true,
+  "scope": "preflight",
+  "buildVerified": false,
   "pages": 8,
   "assets": 3,
   "diagnostics": []
 }
 ```
 
+## Check the built site and deployment
+
+```sh
+npm run validate
+npx @tenphi/cookbook check-build --out dist --json
+npx @tenphi/cookbook check-build --out dist --url https://docs.example.com/manual/
+```
+
+New projects include `validate`, which runs `cookbook doctor && astro build &&
+cookbook check-build`. Existing projects can add that script to `package.json`.
+Use the same environment variables and configuration for building and checking.
+`--out` is relative to the selected app directory, even when `docs.config.ts`
+points at a different content root.
+
+`check-build` reads actual HTML and CSS plus Cookbook's publishing manifest. It
+checks local page/asset URLs, heading fragments, referenced fonts, social images,
+canonical and indexing metadata, sitemap coverage, and discovery files. Direct
+links to drafts are valid; drafts must still be built and carry `noindex`.
+External links and remote font availability are outside this local check.
+
+With `--url`, it also fetches the built pages and referenced local assets from
+that deployment, checks status codes, rejects HTML fallbacks for assets, and
+compares page title/canonical/indexing metadata. Include the deployed path prefix;
+it may differ from the production prefix in the build. Production canonicals can
+remain unchanged on a preview host. An unexpected `X-Robots-Tag: noindex` on an
+indexable page is reported. Network failures exit non-zero; rerun after the host
+has finished deploying.
+
+JSON adds `scope` (`built-output` or `deployment`) and `checkedUrls`. A missing
+production site URL is a warning: configure `site.url` or Astro's `site` before
+relying on canonical or sitemap checks. Warnings do not fail the command.
+This checks output and hosting; browser accessibility and interaction testing
+remain separate steps.
+
 ## Update package content
 
 ```sh

package/docs/configuration.md

@@ -20,6 +20,10 @@ export default defineDocsConfig({
 Cookbook validates the configuration when it loads. Unknown top-level and
 section keys are errors.
 
+Start with a complete [configuration recipe](./recipes.md) for common tasks.
+This page documents the available options; [working examples](./examples.md)
+covers repository layouts and shared presets.
+
 ## Project resolution and presets
 
 `cookbook()` and CLI commands discover the same `docs.config.ts`. Set `root`
@@ -92,10 +96,19 @@ content: {
 },
 ```
 
-Each `routeBase` must have a page, and version roots must be distinct. A
+Each `routeBase` must have a home page (a localized home also qualifies), and version roots must be distinct. A
 single-version site can continue using `site.version` for a simple label.
 
-### Site icons
+### Site logo
+
+`site.logo` accepts a local image path, `false` to hide the mark, or an object
+with `src` (one image) or `light` and `dark` (appearance variants). Optional
+`alt`, `decorative`, `href`, `width`, and `height` control accessible text,
+destination, and intrinsic sizing. It applies to the header and mobile drawer.
+See the [shared logo guide](./theme-and-components.md#a-shared-site-logo).
+The logo and favicon are independent.
+
+## Site icons
 
 Cookbook ships its book mark as the default favicon. Set `site.favicon` to a
 local SVG, PNG, JPEG, WebP, AVIF, or GIF when the documentation should use the
@@ -204,6 +217,14 @@ renderer frontmatter. Use `content.frontmatter: "reject"` to reject unrelated
 fields. Other supported fields include `aliases`, `template`, `hero`, `editUrl`,
 `lastUpdated`, `prev`, `next`, `head`, `draft`, and `slug`.
 
+### Draft pages
+
+Set `draft: true` to publish a page for review at its normal URL. Drafts remain
+available in development and production, and authored links to them are valid.
+They are excluded from automatic navigation, pagination, search, sitemaps, and
+`llms.txt`, and receive `noindex` metadata. Removing `draft` makes the page
+discoverable on the next build. A draft URL is public; this is not access control.
+
 ## Languages
 
 Expose Starlight's multilingual routing and language picker directly:
@@ -218,10 +239,17 @@ defaultLocale: "root",
 ```
 
 Locale keys other than `root` are URL prefixes. A source routed to `/fr/guide`
-is the French counterpart of `/guide`; `defaultLocale` provides fallback
-content when a translated route is missing. See Starlight's
-[internationalization guide](https://starlight.astro.build/guides/i18n/) for
-the shared routing and fallback behavior.
+is the French counterpart of `/guide`. Navigation and pagination include the
+current locale's published routes. Locale prefixes are added once, after the
+site's deployment base.
+
+Cookbook does not create duplicate fallback pages. When the language picker
+cannot find a translation, it links to the equivalent page in `defaultLocale`,
+then an existing locale home or default-language home. The picker labels
+cross-language fallbacks. Locales with no usable target are omitted. Header home
+links use the same policy, so a missing `/fr/` never creates a broken home link.
+Alternate-language metadata lists only existing published translations. Drafts
+remain directly accessible but are excluded from locale discovery.
 
 ## Content
 
@@ -350,13 +378,19 @@ theme: {
     surface: { tone: 98, saturation: 0.05 },
     text: {
       base: "surface",
-      tone: "-10",
+      tone: 0,
+      saturation: 0,
+      contrast: { wcag: [7, 10] }
+    },
+    heading: {
+      base: "surface",
+      tone: [4, 0],
       saturation: 0,
       contrast: { wcag: [7, 10] }
     },
     textSoft: {
       base: "surface",
-      tone: "-10",
+      tone: [25, 10],
       saturation: 0.05,
       contrast: { wcag: [4.5, 7] }
     }
@@ -404,8 +438,11 @@ flows. The default layout is capped at `87.5rem` (1400px), matching the
 Tasty site, with a `58rem` reading column and a `17.5rem` sidebar. `brand.from`
 supplies the color seed. `palette` supplies semantic Glaze declarations that
 inherit its hue and saturation unless a role supplies its own `from`. `tone` and
-a saturation factor set the surface; `base` and `contrast` express reading-color
-requirements against that surface. Glaze resolves light, dark, and both
+a saturation factor set the surface. Reading text uses absolute tones: body
+text starts at 0, and headings at 4. Glaze applies normal-mode tone boundaries
+and adapts the values for dark mode; `base` and `contrast` provide minimum
+contrast safeguards. `palette.heading` follows an explicit `palette.text`
+declaration unless customized separately. Glaze resolves light, dark, and both
 high-contrast modes independently. Literal color shorthand and structured
 brand hue/saturation/tone remain supported. A requested APCA floor below 45 requires the explicit
 `unsafeContrast: true` escape hatch. Learn more in
@@ -456,11 +493,9 @@ export default defineConfig({
 });
 ```
 
-Cookbook forwards these plugins to Starlight. Plugins that add stylesheets or
-style tags fail the production build because Cookbook ships only Tasty styles.
-Plugins that replace
-Cookbook-owned components or change routes can conflict with the content graph.
-Use `theme.styles` for visual changes.
+Cookbook preserves custom metadata for route middleware and supports custom schemas.
+See the [plugin compatibility guide](./plugins.md) for the tested ecosystem matrix,
+content query API, Tasty adapters, and collection/style limitations.
 
 Cookbook renders fenced `mermaid` blocks as responsive, theme-aware SVG during
 the static build. Flowcharts, state, sequence, class, and entity-relationship
@@ -585,3 +620,30 @@ contrast modes. Adjust blur and other header styling via `theme.styles.HeaderFra
 `theme.palette.overlay` controls the fixed underlay color, defaulting to black at
 50% opacity in every scheme. The mobile drawer uses the Glaze shadow token and
 a 120ms slide transition; customize these through `theme.styles.Sidebar`.
+
+### Translate Cookbook controls
+
+Cookbook includes English and French interface messages. Other languages use
+English for missing Cookbook messages while Starlight supplies its own built-in
+translations. Override messages by language code; regional codes fall back to the
+base language and then English:
+
+```ts
+translations: {
+  de: {
+    appearance: "Darstellung",
+    closeNavigation: "Navigation schließen",
+    "navigation.Guide": "Anleitung",
+  },
+},
+```
+
+`navigation.<configured label>` translates named tabs and navigation groups.
+Automatically generated links use the title from the translated page.
+Cookbook message keys are `appearance`, `colorScheme`, `contrast`,
+`normalContrast`, `highContrast`, `auto`, `closeNavigation`, `primary`, `sections`,
+`chooseSection`, `headerLinks`, `more`, `closeMore`, `moreLinks`, `versions`,
+`documentationVersion`, `documentationVersions`, `version`, `home`,
+`generatedWith`, `viewSource`, `copyCode`, `codeCopied`, `codeCopyError`,
+`copyHeading`, `linkCopied`, `linkCopyError`, `notFound`, `notFoundDescription`,
+and `fallback`. Preserve `{heading}` in the `copyHeading` message.

package/docs/content-sources.md

@@ -120,6 +120,32 @@ into one local document before the build. Cookbook checks the spec size against
 `build.maxAssetBytes` and reports invalid or duplicate operation routes.
 Generated pages are static references; they do not make requests to the API.
 
+### Supported OpenAPI details
+
+Cookbook renders the core OpenAPI 3.0/3.1 operation model:
+
+- Operation parameters replace path parameters with the same **name and location**.
+  The same name in `query` and `path` remains two parameters.
+- Parameters and request/response media types render singular `example` values
+  (including `false`, `0`, and `null`) and named `examples`. Local Example Object
+  references resolve to their summaries, descriptions, and values. HTTP(S)
+  `externalValue` examples are linked and never fetched by the build.
+- Operations inherit document `security`. An explicit array replaces it;
+  `security: []` declares anonymous access. Empty objects allow an anonymous
+  alternative. Schemes within an object are required together; array entries
+  are alternatives. Scheme details and required scopes appear on each page.
+- Local JSON Pointer references support escaped names and reference chains.
+  Reference-only cycles and unknown security schemes produce diagnostics.
+  Recursive schema definitions remain visible as JSON references.
+
+These follow the [OpenAPI parameter and security rules](https://spec.openapis.org/oas/v3.1.1.html#operation-object).
+Cookbook is not a complete OpenAPI validator or an interactive API client.
+Callbacks, webhooks, link execution, OAuth login flows, multipart editors,
+request serialization, and interactive schema expansion are not implemented.
+Schema JSON is displayed as authored; externally split specs must be bundled
+first. Use an OpenAPI validator alongside `cookbook doctor` for specification
+validation beyond the rendered feature set.
+
 ## npm package sources
 
 Package sources read documentation from the actual npm artifact:

package/docs/customization-rules.md

@@ -48,6 +48,14 @@ export default defineDocsConfig({
 });
 ```
 
+## Keep styling on the server
+
+Tasty and Glaze run during build/server rendering. The browser receives extracted
+CSS; never initialize their configuration or ship their runtime in client scripts
+or hydrated islands. Use server-rendered styled components with small client
+scripts for behavior. Cookbook rejects browser imports of its styling API,
+Tasty, and Glaze, including transitive dependencies.
+
 ## Write styles through Cookbook
 
 Import `defineComponent`, `tasty`, `useGlobalStyles`, `resolveComponentStyles`,

package/docs/deployment.md

@@ -12,12 +12,13 @@ plain file server.
 ## Build locally
 
 ```sh
-npm run build
+npm run validate
 npm run preview
 ```
 
-Run [`cookbook doctor`](./cli.md#validate-with-doctor) in CI before building
-when you want a focused content diagnostic step.
+New projects include `validate`: preflight, production build, then built-output
+checks. Existing projects can add this script using the [upgrade guide](./migration.md).
+Run [`cookbook doctor`](./cli.md#validate-with-doctor) for a focused preflight.
 
 ## GitHub Pages
 
@@ -93,3 +94,19 @@ to the sitemap. Host these files with the rest of `dist/`; custom files in
 
 Check the deployed HTML, `sitemap-index.xml`, and `llms.txt` through their public
 URLs. See [AI agents](./ai-agents.md) for the setup and reading workflow.
+
+For title templates, social images, preview noindex, older-version policies,
+breadcrumbs, and copy-page downloads, see [Publishing metadata](./publishing.md).
+
+## Validate the published result
+
+New projects include `npm run validate` for preflight, build, and output checks.
+After the host finishes deploying, run:
+
+```sh
+npx @tenphi/cookbook check-build --url https://docs.example.com/manual/
+```
+
+Use your actual deployment URL, including any base path, and the same local
+`dist/` output that was deployed. See [CLI checks](./cli.md#check-the-built-site-and-deployment)
+for the exact coverage, warnings, JSON output, and custom output directories.

package/docs/examples.md

@@ -19,7 +19,7 @@ export default defineConfig({ integrations: [cookbook()] });
 Put this in `docs.config.ts` at the repository root. README/docs discovery is
 automatic; add `content.sources` only when you need different routes or files.
 
-```ts
+```ts cookbook-verify=minimal
 import { defineDocsConfig } from "@tenphi/cookbook/config";
 
 export default defineDocsConfig({ site: { title: "My library" } });
@@ -75,7 +75,7 @@ is the npm public registry. Keep credentials out of committed configuration.
 
 A preset is an ordinary exported `DocsConfig` object:
 
-```ts
+```ts cookbook-verify=shared-theme
 import { defineDocsConfig, mergeDocsConfig } from "@tenphi/cookbook/config";
 
 const company = defineDocsConfig({
@@ -99,3 +99,6 @@ Objects merge recursively, arrays replace, and inputs are not mutated. Tasty
 styles preserve their default values when adding conditional overrides. A preset
 can live in a shared workspace package. Component overrides remain partial Tasty
 objects and merge into Cookbook's complete base styles inside the renderer.
+
+For complete branding, font, locale, and preview configurations, see
+[configuration recipes](./recipes.md).