@tenphi/cookbook 0.17.1 → 0.18.1

package/docs/getting-started.md

@@ -72,9 +72,10 @@ With no documentation configuration, it uses README/docs conventions.
 
 ## Configure the site
 
-Read the [customization rules](./customization-rules.md) before changing the
-theme or adding custom components. These rules and their upstream references
-are also included in the installed Cookbook package.
+Start with the complete [brand, logo, and font recipes](./recipes.md).
+For deeper style changes or new components, read the
+[customization rules](./customization-rules.md). These rules and upstream
+references are also included in the installed Cookbook package.
 
 Create `docs.config.ts` next to `astro.config.ts`:
 
@@ -124,11 +125,13 @@ also declare their own roots for multi-package sites.
 ## Validate and publish
 
 ```sh
-npm run doctor
-npm run build
+npm run validate
 npm run preview
 ```
 
 See [working examples](./examples.md), [authoring components](./authoring.mdx),
 the [AI agent workflow](./ai-agents.md), and [deployment](./deployment.md). Existing users should read the
-[prerelease migration guide](./migration.md).
+[version-specific upgrade guide](./migration.md).
+
+For a complete configuration to adapt, start with the [recipes](./recipes.md).
+If validation fails, see [troubleshooting](./troubleshooting.md).

package/docs/index.md

@@ -40,22 +40,45 @@ Broken links, missing assets, duplicate routes, invalid navigation, and unsafe
 paths fail with source locations. The result is prerendered HTML and CSS ready
 for GitHub Pages or any static host.
 
+### Styling that fits your product
+
+Glaze turns a brand and semantic palette into light, dark, and high-contrast
+colors with contrast targets. Tasty applies those color roles alongside shared
+tokens and typography presets, so the docs can follow your design system.
+State maps keep hover, focus, and responsive values beside the styles they
+change. Partial `theme.styles` overrides merge before CSS extraction, letting
+you adjust supported components without selector chains or `!important`.
+The browser receives static CSS, with no Tasty or Glaze styling runtime.
+See the [theme reference](./theme-and-components.md) for the palette, presets,
+states, and named component styles.
+
 ## Choose a path
 
-Create a documentation project from a published npm package:
+| I want to…                           | Start here                              | Then read                                                             |
+| ------------------------------------ | --------------------------------------- | --------------------------------------------------------------------- |
+| Start a site                         | [Getting started](./getting-started.md) | [Validate and deploy](./deployment.md)                                |
+| Have an agent set it up              | [AI agent workflow](./ai-agents.md)     | [Customization rules](./customization-rules.md)                       |
+| Bring existing Markdown or an API    | [Content sources](./content-sources.md) | [Working examples](./examples.md)                                     |
+| Write pages and interactive examples | [Authoring](./authoring.mdx)            | [Mobile contents and hero images](./authoring.mdx#on-page-navigation) |
+| Change brand, fonts, or logo         | [Configuration recipes](./recipes.md)   | [Theme reference](./theme-and-components.md)                          |
+| Add a Starlight plugin               | [Plugin compatibility](./plugins.md)    | [Architecture](./architecture.md)                                     |
+| Publish for people and agents        | [Deployment](./deployment.md)           | [Publishing metadata](./publishing.md)                                |
+| Update or fix an existing site       | [Upgrade Cookbook](./migration.md)      | [Troubleshooting](./troubleshooting.md)                               |
 
-```sh
-npm create @tenphi/cookbook@latest my-package-docs -- --package your-package
-```
+The **Guide** follows these tasks. **Reference** contains the complete
+[configuration](./configuration.md), [theme and component anatomy](./theme-and-components.md),
+[publishing controls](./publishing.md), and [CLI](./cli.md).
 
-Or add the complete integration to an Astro project:
+To start immediately:
 
 ```sh
-npx astro add @tenphi/cookbook
+npm create @tenphi/cookbook@latest my-docs -- --yes
+cd my-docs
+npm run dev
 ```
 
-Continue with [Getting started](./getting-started.md), then learn how
-[content sources](./content-sources.md) become routes.
+Existing Astro projects can use `npx astro add @tenphi/cookbook`. See
+[Getting started](./getting-started.md) for repository and npm package sources.
 
 ## See the product, not a mock-up
 

package/docs/migration.md

@@ -1,11 +1,104 @@
 ---
-title: Prerelease migration
-description: Upgrade to the shared configuration, source identity, and typed customization APIs.
+title: Upgrade Cookbook
+description: Version-specific changes, runtime upgrades, and documentation-source updates.
 sidebar:
   order: 9
 ---
 
-This prerelease intentionally tightens several contracts.
+## Upgrade the site runtime
+
+Check your current `@tenphi/cookbook`, Astro, and Node versions first. Read the
+[release notes](https://github.com/tenphi/cookbook/releases), then update the
+runtime dependency using the package manager that owns your lockfile:
+
+```sh
+npm install @tenphi/cookbook@latest
+npx @tenphi/cookbook doctor
+npm run build
+npx @tenphi/cookbook check-build
+npm run preview
+```
+
+For pnpm use `pnpm add`; for Yarn use `yarn add`. Commit the package manifest and
+package-manager lockfile together. Keep Astro inside Cookbook's declared peer
+range. Review the preview with your custom styles, plugins, fonts, languages,
+and versions before deploying. After deployment, run `cookbook check-build
+--url https://docs.example.com/` against that exact build output.
+
+The creator starts new projects; rerunning it over an existing project is not
+an upgrade path. Generated sites include `.agents/skills/upgrade-cookbook/`
+for an agent-assisted upgrade. See [quality checks](./quality-checks.md) for
+validation coverage and [troubleshooting](./troubleshooting.md) for failures.
+
+### Runtime updates versus documentation updates
+
+`cookbook update` updates **imported npm documentation**, according to the
+specifiers in `content.sources`. It writes `cookbook.lock.json`; it does not
+upgrade the site's Cookbook runtime or package-manager dependencies. Commit the
+documentation lock separately when intentionally updating imported content.
+Local Markdown needs no lock update.
+
+## 0.17.x to 0.18
+
+These changes are included in the next minor release:
+
+- **Google fonts:** family-name shorthand loads preset weights and italics and
+  self-hosts the files. The initial build requires network access. Preserve the
+  Astro font cache for offline rebuilds, use local files for checked-in assets,
+  or select `theme.fontLoading.google: "remote"` for CDN delivery. See
+  [fonts](./theme-and-components.md#change-font-families).
+- **Colors:** body tone 0 and heading tone 4 remain the reading defaults.
+  The default logo uses fixed Glaze colors (`logo-surface` and `logo-mark`), so
+  its book stays light in dark mode. Customize these independently of accents.
+  Additional semantic-pair checks may reject custom colors that previously
+  passed. Follow the named pair and mode in the diagnostic; see
+  [contrast troubleshooting](./troubleshooting.md#contrast-failures).
+- **Header controls:** round controls use `$header-control-radius`, independently
+  of `$radius`. Set the new token to your preferred radius to keep your previous
+  header shape.
+- **Drafts:** production builds retain draft pages at direct URLs and mark them
+  `noindex`. They are omitted from generated navigation, search, sitemaps, and
+  agent indexes. A draft is public to anyone with the URL; use host access
+  controls for private previews.
+- **Plugins:** custom metadata is available to route middleware and through
+  Cookbook's content API. Plugins that need Astro's synthetic content files or
+  inject their own CSS require adaptation. See the tested
+  [plugin matrix](./plugins.md#verified-compatibility).
+- **Styles:** rendered inline styles are rejected. Move custom styling to Tasty
+  and registered theme style trees. Keep these components server-rendered;
+  browser scripts and `client:*` islands cannot import Cookbook styling, Tasty,
+  or Glaze. Attach interaction scripts to the static markup. Isolated,
+  sandboxed `Preview` content is the
+  documented exception. The new surface inventory is in the
+  [theme reference](./theme-and-components.md).
+- **Page text:** the footer offers copy/download Markdown by default. Set
+  `site.seo.copyPage: false` to disable the controls and generated page files.
+  Configure static host headers if raw Markdown must be excluded from indexing;
+  see [deployment](./deployment.md).
+- **Validation:** existing projects can add
+  `"validate": "cookbook doctor && astro build && cookbook check-build"`
+  to their scripts. `doctor` is explicitly a preflight; successful MDX compilation
+  and deployment require the later checks.
+
+Review locale navigation and canonical metadata after upgrading. Locale/version
+links now target actual pages and available fallbacks instead of invented URLs.
+A version switcher changes the selected route; configure navigation groups
+explicitly when you want to curate which version trees are shown.
+
+## 0.16 to 0.17
+
+Use Node.js **22.19 or newer**. Cookbook 0.17 adopted Starlight 0.42.4 and added
+Google/local font configuration, Glaze palette declarations, OpenAPI sources,
+version navigation, plugin forwarding, agent instructions, and static discovery
+files. These features are opt-in except for generated discovery metadata.
+Version 0.17.1 restored strong body/heading colors with absolute Glaze tones.
+If you added temporary contrast workarounds in 0.17.0, compare them with those
+defaults before carrying them forward.
+
+## Upgrading from before 0.14
+
+The shared-configuration and source-identity changes shipped in **0.14.0**.
+Apply these steps if your project still uses the earlier contracts:
 
 - Move generated inline documentation configuration to `docs.config.ts` and use
   `cookbook()` in Astro. Existing explicit `cookbook({ config })` remains valid,
@@ -32,5 +125,5 @@ This prerelease intentionally tightens several contracts.
 - `Tabs` now expects `Tab` children with accessible labels. It provides keyboard
   navigation and panels; use an ordinary custom component for a grouping layout.
 
-See [authoring](./authoring.mdx) for the new components and [working
-examples](./examples.md) for complete configuration patterns.
+See [authoring](./authoring.mdx) for component usage and
+[working examples](./examples.md) for repository configuration patterns.

package/docs/plugins.md

@@ -0,0 +1,120 @@
+---
+title: Starlight plugins
+---
+
+Cookbook accepts Starlight content and behavior plugins in `astro.config.mjs`:
+
+```js cookbook-verify=github-alerts
+import cookbook from "@tenphi/cookbook";
+import githubAlerts from "starlight-github-alerts";
+import { unified } from "@astrojs/markdown-remark";
+
+export default {
+  markdown: { processor: unified() },
+  integrations: [cookbook({ plugins: [githubAlerts()] })],
+};
+```
+
+Install `starlight-github-alerts` and `@astrojs/markdown-remark` in your project. Cookbook supplies the Starlight runtime; respect
+plugins' peer dependency ranges when upgrading. See [configuration](./configuration.md)
+for Astro Markdown hooks and [customization](./theme-and-components.md) for styling.
+
+## Verified compatibility
+
+The consumer check `pnpm check:plugins` tests these versions with the repository's
+pinned Astro and Starlight versions. Compatibility with other versions is not implied.
+
+| Integration                                                        | Tested version   | Contract                                                                                                                             |
+| ------------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `starlight-github-alerts`                                          | 0.4.0            | With `unified()`, Markdown and MDX alert syntax uses Cookbook's Tasty `StarlightAside` adapter.                                      |
+| `starlight-links-validator`                                        | 0.26.0           | Incompatible with mounted sources: error reporting assumes physical `src/content/docs` files. Cookbook rejects it with a diagnostic. |
+| Route middleware and `i18n:setup`                                  | Starlight 0.42.4 | Custom metadata, body, file path, and translations survive in real consumer builds with locales and a base path.                     |
+| Plugins requiring `astro:content`'s `docs` collection              | —                | Cookbook's renderer uses its own graph. Adapt to the content API below; no native collection is populated automatically.             |
+| Plugins supplying CSS, styled Astro components, or Expressive Code | —                | Require an adapter built with Tasty. The build rejects incompatible output.                                                          |
+
+GitHub Alerts 0.4.0 assumes an older Sätteri plugin structure and silently skips
+alerts with Starlight 0.42.4's default processor. Cookbook rejects that combination
+with a configuration hint. Use `unified()` as above, or Starlight's native
+`:::note` / `:::tip` directives with the default processor.
+
+GitHub alerts inherit the semantic blue, green, yellow, and red surfaces. Customize
+`theme.styles.StarlightAside` with `Note`, `Tip`, `Caution`, `Danger`, `Title`, `Icon`,
+and `FirstContent`. Styles merge into the full owned tree; the plugin's stylesheet
+is unnecessary. All supported appearance modes use the Glaze palette.
+
+Cookbook validates graph links itself. `starlight-links-validator` 0.26.0 loads,
+but fails while reporting broken links because it tries to read synthesized
+`src/content/docs` paths. Its middleware also cannot add previously absent links
+to its validation store. Use Cookbook's doctor and built-output checks for mounted
+sources. Plugins that depend on native collection IDs or mutate routing after
+graph creation need a Cookbook-specific adapter.
+
+## Custom metadata and schemas
+
+Unknown source frontmatter is preserved as `entry.metadata` by default, and is
+available to route middleware as `locals.starlightRoute.entry.data`. Cookbook's
+validated built-in fields take precedence. Set `content.frontmatter: "reject"`
+only if your site does not use custom metadata.
+
+Optionally validate custom fields or supply defaults with a Zod-compatible schema:
+
+```js
+import cookbook from "@tenphi/cookbook";
+import { z } from "astro/zod";
+
+export default {
+  integrations: [
+    cookbook({
+      frontmatterSchema: z.object({
+        owner: z.string().default("docs-team"),
+      }),
+    }),
+  ],
+};
+```
+
+The schema receives **custom metadata only** and may use `parse` or `parseAsync`.
+Returned fields merge with preserved metadata. Values must be JSON-compatible;
+errors identify the source file. Reserved fields such as `title`, `slug`, `draft`,
+and `aliases` belong in source frontmatter and cannot be set by this schema.
+A schema cannot change routing or discovery after the graph is built.
+
+Route middleware also receives the transformed Markdown source in `entry.body`
+and the actual source location in `entry.filePath`. Presentation changes made by
+middleware do not update the graph, sitemap, or agent text. Put shared publishing
+metadata in source configuration so every output agrees.
+
+## Query Cookbook content
+
+Use this build-time API in Astro components and route middleware:
+
+```js
+import {
+  getCookbookCollection,
+  getCookbookEntry,
+} from "@tenphi/cookbook/content";
+
+const pages = getCookbookCollection();
+const allPages = getCookbookCollection({ includeDrafts: true });
+const page = getCookbookEntry("/guide");
+```
+
+The renderer package exposes the same functions at `@tenphi/starlight/content`.
+Routes include locale/version prefixes but exclude Astro's deployment `base`.
+Collection queries omit drafts by default; exact lookups can retrieve a draft.
+Results are independent snapshots, including `metadata`, `frontmatter`, `body`,
+`transformedBody`, source information, headings, and links. Mutating a result does
+not change generated pages. Do not import this API into client-side code: it is
+backed by the site's build-time content graph.
+
+## Diagnose incompatible plugins
+
+- **Plugin adds `customCss`:** disable its stylesheet option and provide a Tasty
+  adapter, or choose a content-only plugin. The configuration error names the plugin.
+- **Inline styles or external stylesheet in built output:** replace that visual
+  component with owned markup styled through `tasty()` and registered
+  `theme.styles` anatomy. See [customization rules](./customization-rules.md).
+- **Empty `getCollection("docs")`:** use the Cookbook content API above. Cookbook
+  does not create a second, potentially conflicting Starlight content collection.
+- **Missing custom field:** keep `content.frontmatter` at its default `"preserve"`,
+  validate its shape, and read it after the Cookbook route bridge has run.

package/docs/publishing.md

@@ -0,0 +1,153 @@
+---
+title: Publishing metadata
+description: Configure titles, social previews, canonical URLs, indexing, and agent-readable pages.
+---
+
+Set `site.url` (or Astro's `site`) to your public origin. Astro's `base` is applied
+to page URLs, local social images, sitemaps, and Markdown downloads automatically.
+Conflicting Cookbook and Astro origins fail configuration validation.
+
+## Titles and social previews
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: {
+    title: "Acme",
+    url: "https://docs.example.com",
+    seo: {
+      titleTemplate: "{title} | {site}",
+      image: {
+        src: "/social.png", // public/social.png; deployment base is added
+        alt: "Acme developer documentation",
+        width: 1200,
+        height: 630,
+      },
+      breadcrumbs: true,
+    },
+  },
+});
+```
+
+Without a template, Cookbook renders `Page | Site`, or just `Site` when both names
+match. Templates require `{title}` and may use `{site}`. A page's `seo.title` is a
+complete document title, overriding the template; its visible heading is unchanged.
+
+Social images accept an absolute HTTP(S) URL or a root-relative public asset path.
+Provide meaningful `alt` text. Dimensions are optional but must be provided together.
+A page inherits the site image, can replace it, or can set `image: false`. Pages
+without an image use a `summary` card; an image enables `summary_large_image`.
+
+```yaml
+---
+title: Authentication
+seo:
+  title: Authentication reference — Acme
+  image:
+    src: /authentication.png
+    alt: Acme authentication flow
+    width: 1200
+    height: 630
+---
+```
+
+Cookbook owns document titles, canonical links, robots directives, and the social
+fields described above. Configure these through `seo` instead of duplicating them
+in `head`. Other custom head tags remain supported.
+
+## Indexing and previews
+
+`site.seo.index: false` adds `noindex, follow` to documentation pages and omits them
+from sitemaps, language alternatives, and `llms.txt`. Navigation and direct links
+continue to work. A page cannot override a site or version's `index: false`.
+
+Choose preview policy explicitly in configuration:
+
+```ts
+site: {
+  url: "https://docs.example.com",
+  seo: { index: process.env.DOCS_PREVIEW !== "1" },
+}
+```
+
+Build previews with `DOCS_PREVIEW=1`. Keep the production canonical origin while
+serving the preview from another host. `noindex` is a crawler instruction, not
+access control. Crawlers must be allowed to fetch the HTML to see it; do not rely
+on a robots.txt disallow rule to communicate noindex. See Google's
+[noindex guidance](https://developers.google.com/search/docs/crawling-indexing/block-indexing).
+
+A page can opt out using `seo: { index: false }`. A draft is always noindex and also
+omitted from navigation, pagination, search, sitemaps, and agent discovery. Drafts
+remain available at their ordinary production URL and do not get Markdown copies.
+
+## Versions, locales, and canonical URLs
+
+Every published version is indexed by default. Opt older versions out explicitly:
+
+```ts
+site: {
+  versions: [
+    { label: "Current", routeBase: "/" },
+    { label: "v1", routeBase: "/v1", index: false },
+  ],
+}
+```
+
+Locale prefixes precede version roots: `/fr/v1/guide`. Version matching uses the
+most specific configured root after the locale prefix. Only actual, indexable,
+self-canonical translations are advertised in `hreflang` and the sitemap.
+
+For duplicate content, set a page's `seo.canonical` to the preferred **absolute
+HTTP(S) URL without a fragment**. The duplicate keeps its normal route and is
+omitted from sitemap and agent indexes; canonicalization alone does not add
+noindex. Distinct versions keep self-canonical URLs unless you explicitly identify
+them as duplicates. See Google's
+[canonical guidance](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls).
+
+## Breadcrumb structured data
+
+`site.seo.breadcrumbs: true` emits a `BreadcrumbList` when at least two actual
+ancestor pages exist. Intermediate folders without pages are skipped. To describe
+a different navigation journey, supply at least two `{name, url}` items in a page's
+`seo.breadcrumbs`. URLs must be absolute HTTP(S); the final URL must match that
+page's canonical. Set `seo.breadcrumbs: false` on a page to disable it.
+
+Structured data helps machines understand the page hierarchy. It does not guarantee
+any search appearance; validate the deployed output using Google's
+[breadcrumb documentation](https://developers.google.com/search/docs/appearance/structured-data/breadcrumb).
+
+## Page text for readers and agents
+
+Published pages include **Copy page** and **Download Markdown** controls. The head also
+advertises a `rel="alternate" type="text/markdown"` URL. Downloads contain clean
+Markdown with canonical URL, source path, language, and version metadata. Code
+fences and rewritten links are preserved. Executable MDX, expressions, raw HTML,
+and isolated previews are omitted; generated interactive component output may
+only be available in the HTML. Read the HTML when that content matters.
+
+The version comes from the matching documentation version, then `site.version`.
+Copying requires browser clipboard access; the Markdown link remains available if
+permission is unavailable or JavaScript is disabled. Set `site.seo.copyPage: false`
+to disable page text and both controls. Customize the controls with
+`theme.styles.PageActions`: `Control`, `Hover`, `Focus`, `Pending`, and `Status`.
+
+`llms.txt` links to discoverable canonical pages and their Markdown representations.
+`_cookbook/publishing.json` records non-draft page URLs and publishing policy for
+validation tools. Existing `public/llms.txt` and root `public/robots.txt` take
+precedence; maintain their policy yourself.
+
+For static hosts, apply `X-Robots-Tag: noindex` to `/_cookbook/pages/*` (with your
+base prefix) to keep alternate Markdown copies out of web search. For example,
+Netlify/Cloudflare Pages projects can add this to `public/_headers`:
+
+```text
+/_cookbook/pages/*
+  X-Robots-Tag: noindex
+```
+
+The static HTML's noindex does not automatically apply to a separate Markdown URL.
+Preview deployments should apply a site-wide noindex response header when the
+host supports it. On hosts without custom headers, disable `copyPage` for previews
+and private review content. Agent files are a reading convenience, not a claim of
+better AI answers or higher search rankings.

package/docs/quality-checks.md

@@ -0,0 +1,71 @@
+---
+title: Quality checks
+description: Validate a site, understand the consumer test matrix, and measure output budgets.
+---
+
+## For your documentation site
+
+Run `npm run validate` in a generated project: it checks the configuration and
+local files, builds the site, and validates the output. After deploying, run
+`npx @tenphi/cookbook check-build --url https://docs.example.com/` against the
+same build. See [CLI validation](./cli.md#check-the-built-site-and-deployment)
+for coverage and preview-host behavior.
+
+Also review keyboard navigation, mobile layouts, and all four light/dark and
+normal/high-contrast combinations after changing styles. Automated accessibility
+checks supplement this review; they do not establish complete accessibility.
+
+## Cookbook's verification suite
+
+Repository contributors can run these checks after `pnpm build`:
+
+| Command                      | Coverage                                                                                     |
+| ---------------------------- | -------------------------------------------------------------------------------------------- |
+| `pnpm test`                  | Configuration, graph, rendering helpers, diagnostics, and interaction logic                  |
+| `pnpm check:locales`         | Real locale/fallback/navigation consumers                                                    |
+| `pnpm check:publishing-site` | Combined base paths, locales, versions, drafts, SEO, and agent Markdown                      |
+| `pnpm check:theming`         | Consumer components, colors, units, recipes, presets, overrides, and logos                   |
+| `pnpm check:fonts`           | Real Google variable/italic fonts, local fonts, and offline cache rebuild                    |
+| `pnpm check:plugins`         | Tested plugin contracts and actionable incompatibility failures                              |
+| `pnpm check:recipes`         | Extract, type-check, build, and validate documented configurations verbatim                  |
+| `pnpm check:authoring`       | Custom highlighting, code groups, mobile contents, hero images, and OpenAPI                  |
+| `pnpm check:browser`         | Chromium keyboard/focus, search, copy actions, appearance, mobile navigation, and axe checks |
+| `pnpm check:install`         | Clean installation and build from packed artifacts, including lint/type exports              |
+| `pnpm check:benchmark`       | A generated 500-page corpus with 10,000 headings and code samples                            |
+
+Install the browser once with `pnpm exec playwright install chromium`.
+CI covers npm, pnpm, and Yarn installations, Node 22/24/26, and Linux, macOS,
+and Windows in representative combinations. Yarn uses its `node-modules` linker;
+Plug'n'Play is not covered. The weekly upstream canary installs the newest Astro
+version allowed by Cookbook's peer range and actually builds the packed consumer.
+Google Fonts checks run in that network-enabled canary. Published documentation
+is checked after deployment against its uploaded build artifact.
+
+The lint consumer uses TypeScript 6 for the typescript-eslint parser and the
+workspace TypeScript compiler for public API checks; typescript-eslint currently
+rejects the TypeScript 7 API. Runtime compilation and lint parsing are separate.
+
+## Performance budgets and corpus measurements
+
+The reference build enforces separate limits for initial page JavaScript,
+lazy search assets, font files, images, and extracted Tasty CSS. A default guide
+currently loads about 12 KB of first-party JavaScript initially; search is lazy.
+The checked reference output contains about 73 KB of fonts and 35 KB of images.
+`node scripts/check-reference-budgets.mjs` prints measured bytes and limits.
+These are uncompressed first-party build sizes, excluding external analytics.
+
+A local macOS / Node 22.22 run processed 500 pages with 10,000 headings in about
+1.1 seconds and built that site in 33.5 seconds. A 1,000-page / 20,000-heading
+graph took about 2.8 seconds, with roughly 499 MiB RSS after three runs. These are
+observations on one machine, not throughput guarantees. The full-build corpus
+uses explicit minimal navigation so the measurement is not dominated by repeating
+hundreds of sidebar links in every page.
+
+```sh
+COOKBOOK_BENCH_PAGES=1000 COOKBOOK_BENCH_BUILD=1 pnpm check:benchmark
+COOKBOOK_TEST_MANAGER=pnpm pnpm check:install
+COOKBOOK_TEST_UPSTREAM=1 pnpm check:install
+```
+
+Investigate regressions before changing a budget. CI retains browser traces on
+failure, and the benchmark reports graph timings, memory, and optional build time.

package/docs/recipes.md

@@ -0,0 +1,116 @@
+---
+title: Configuration recipes
+description: Complete, build-checked configurations for common documentation tasks.
+---
+
+These are complete `docs.config.ts` files. Start with a generated Cookbook
+project, keep its `astro.config` integration, and replace the documentation
+configuration with one recipe. Add the files listed above each example.
+[Working examples](./examples.md) covers repository and npm source layouts;
+[configuration](./configuration.md) and the [theme reference](./theme-and-components.md)
+cover every option.
+
+The repository's `pnpm check:recipes` extracts the marked examples below and in
+Working examples verbatim, type-checks them, builds actual consumer sites, and
+checks their output. Fixtures supply the documented content and local assets.
+Network-dependent Google font coverage runs separately in `check:fonts`.
+
+## Brand, logo, and round header controls
+
+Put your artwork at `public/logo.svg`. Logo files use their intrinsic aspect
+ratio; the site title provides its label when the artwork is decorative.
+
+```ts cookbook-verify=branding
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: {
+    title: "Acme docs",
+    logo: { src: "./public/logo.svg", decorative: true },
+  },
+  theme: {
+    brand: { from: "#d97706" },
+    tokens: { "$header-control-radius": "999px", $radius: "8px" },
+    styles: { SearchResults: { Input: { radius: "12px" } } },
+  },
+});
+```
+
+The header token also covers the mobile sidebar close control. Copy buttons and
+page navigation keep the base radius. Built-in element overrides merge into the
+complete defaults. See the [named style anatomy](./theme-and-components.md).
+
+## Local variable font
+
+Place a licensed variable WOFF2 font at `public/fonts/acme.woff2`. This example
+uses its normal style; add an italic file when available.
+
+```ts cookbook-verify=local-font
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: { title: "Acme docs" },
+  theme: {
+    brand: { from: "#315efb" },
+    fonts: {
+      body: {
+        family: "Acme Sans",
+        files: [{ src: "/fonts/acme.woff2", weight: "100 800" }],
+      },
+    },
+    presets: { heading: { fontWeight: 650 } },
+  },
+});
+```
+
+For Google Fonts use `fonts: { body: "Inter", heading: "Newsreader" }` instead.
+Cookbook downloads and self-hosts the required weights and italics at build time.
+See [fonts](./theme-and-components.md#change-font-families) for caching,
+explicit ranges, styles, and remote delivery.
+
+## English and French
+
+Create `docs/index.md`, `docs/guide.md`, `docs/fr/index.md`, and
+`docs/fr/guide.md`. Routes are `/`, `/guide`, `/fr`, and `/fr/guide`.
+
+```ts cookbook-verify=locales
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: { title: "Acme docs", url: "https://docs.example.com" },
+  content: { sources: [{ glob: "docs/**/*.md", base: "docs" }] },
+  locales: {
+    root: { label: "English", lang: "en" },
+    fr: { label: "Français" },
+  },
+  defaultLocale: "root",
+  navigation: ["/", "/guide"],
+  translations: { fr: { appearance: "Présentation" } },
+});
+```
+
+Navigation adapts to real translations. Missing translations use a real fallback
+in the language picker; they do not generate phantom routes or alternate links.
+
+## Preview publishing
+
+Set the preview's own URL and Astro `base` if hosted in a subdirectory. Serve
+private previews behind host authentication.
+
+```ts cookbook-verify=preview
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: {
+    title: "Acme preview",
+    url: "https://preview.example.com",
+    seo: { index: false, copyPage: false },
+  },
+  tableOfContents: { mobile: true },
+});
+```
+
+Build, run `cookbook check-build`, deploy that output, then run
+`cookbook check-build --url https://preview.example.com/`. See
+[deployment](./deployment.md) for production metadata, host headers, and sitemap
+checks, and [troubleshooting](./troubleshooting.md) when a check fails.