@tenphi/cookbook 0.27.0 → 0.30.0

package/README.md

@@ -1,12 +1,12 @@
 # @tenphi/cookbook
 
 Before changing a site's appearance, read the
-[customization rules](./docs/customization-rules.md)
-([online](https://cookbook.tenphi.me/customization-rules/)). The package ships
-the complete [Cookbook documentation](./docs/index.md) and local Tasty and Glaze
-references under `docs/upstream/`, including Tasty's
-[style rules for AI agents](./docs/upstream/tasty/docs/ai-agents.md).
-The guide includes a project instruction snippet and the lint setup.
+[customization rules](https://cookbook.tenphi.me/customization-rules/). The
+package ships the complete [Cookbook documentation](https://cookbook.tenphi.me/)
+in `node_modules/@tenphi/cookbook/docs/`, with local Tasty and Glaze references
+under `docs/upstream/`, including Tasty's style rules for AI agents at
+`docs/upstream/tasty/docs/ai-agents.md`. The customization rules include a
+project instruction snippet and the lint setup.
 
 Install the complete integration with `npx astro add @tenphi/cookbook`:
 
@@ -39,9 +39,9 @@ export default defineDocsConfig({
 
 For local fonts, place files in `public/fonts/` and use
 `fonts: { body: { family: "My Font", files: [{ src: "/fonts/my-font.woff2" }] } }`.
-See [Component styles](./docs/component-styles.md) for all named
-sub-elements and [Custom components](./docs/custom-components.md) for the
-custom component flow.
+See [Component styles](https://cookbook.tenphi.me/component-styles/) for all
+named sub-elements and [Custom components](https://cookbook.tenphi.me/custom-components/)
+for the custom component flow.
 
 Without configuration, a root `README.md` becomes `/` and
 `docs/**/*.{md,mdx}` supplies the remaining pages. Cookbook includes its Astro renderer,
@@ -60,7 +60,8 @@ export const ProjectBadge = defineComponent("ProjectBadge", {
 ```
 
 Customize this component's root through `theme.customStyles.ProjectBadge`; it has no
-named sub-elements. The `/styling` entry point also exports `tasty`, `useGlobalStyles`,
+named sub-elements. The `/styling` entry point also exports `extendComponent`,
+the shared `Button` foundation, `tasty`, `useGlobalStyles`,
 `resolveComponentStyles`, `mergeStyles`, and the `Styles` type. Cookbook extracts
 the CSS automatically. See [Custom components](https://cookbook.tenphi.me/custom-components/)
 for a complete custom logo and site title example.
@@ -77,7 +78,8 @@ export default {
 ```
 
 The entry point exports the default Tasty ESLint plugin, `recommended` and `strict`
-rule maps, and the upstream configuration types. The preset recognizes Cookbook's
+rule maps, the `validationConfig` preset, `createValidationConfig(theme)` for
+deriving names from a theme, and the upstream configuration types. The preset recognizes Cookbook's
 theme names and custom styling helpers, including `defineComponent`. `extends`
 merges your additional tokens, states, and presets with these built-ins.
 See [Linting custom styles](https://cookbook.tenphi.me/custom-components/#linting-custom-styles)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 
-import renderer_default, { CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/renderer";
+import renderer_default, { CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, ResolvedDocsTheme, resolveDocsTheme } from "@tenphi/renderer";
 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, renderer_default as default, defineDocsConfig, mergeDocsConfig };
+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 ResolvedDocsTheme, 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, renderer_default as default, defineDocsConfig, mergeDocsConfig, resolveDocsTheme };

package/dist/index.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import renderer_default, { DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/renderer";
+import renderer_default, { DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, resolveDocsTheme } from "@tenphi/renderer";
 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, renderer_default as default, defineDocsConfig, mergeDocsConfig };
+export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, COOKBOOK_PALETTE_NAMES, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS, renderer_default as default, defineDocsConfig, mergeDocsConfig, resolveDocsTheme };

package/docs/ai-agents.md

@@ -37,10 +37,12 @@ Set `site.url` in `docs.config.ts` to the public HTTPS origin. If the site is
 hosted under a path, set Astro's `base` in `astro.config.ts`. A production build
 then gives every page a canonical URL and creates a sitemap. Cookbook also writes:
 
-- `llms.txt`, a short index of published pages with titles, descriptions, and
-  links to their readable HTML pages. Drafts are omitted. This is an optional
+- `llms.txt`, a short index of published pages with titles, descriptions, links
+  to their HTML pages and, unless `site.seo.copyPage` is `false`, their Markdown
+  copies. Drafts, noindex pages, and non-canonical duplicates are omitted. This is an optional
   discovery aid for agents that choose to read it.
-- `robots.txt` at origin-root deployments with a pointer to the sitemap. A
+- `robots.txt` at origin-root deployments with `site.url` set, with a pointer to
+  the sitemap. A
   `robots.txt` below a path such as `/project/` would not control the origin's
   crawlers, so Cookbook does not generate one there.
 

package/docs/architecture.md

@@ -14,12 +14,12 @@ maintained in this repository.
 
 ## Packages
 
-| Package                   | Responsibility                                                                                          |
-| ------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `@tenphi/create-cookbook` | Inspect an npm artifact and scaffold a reproducible documentation project                               |
-| `@tenphi/cookbook`        | Provide the memorable Astro integration, public config exports, and CLI                                 |
-| `@tenphi/docs`            | Discover sources, resolve packages, build the content graph, transform Markdown, and report diagnostics |
-| `@tenphi/renderer`        | Render the graph with Astro and provide the Tasty/Glaze theme, components, search, and static assets    |
+| Package                   | Responsibility                                                                                                                                             |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tenphi/create-cookbook` | Scaffold a documentation project for a new site, an existing repository, or a locked npm package                                                           |
+| `@tenphi/cookbook`        | Provide the memorable Astro integration, public config exports, and CLI                                                                                    |
+| `@tenphi/docs`            | Validate configuration, resolve the Glaze palette, discover sources, resolve packages, build the content graph, transform Markdown, and report diagnostics |
+| `@tenphi/renderer`        | Render the graph with Astro and provide the Tasty/Glaze theme, components, search, and static assets                                                       |
 
 The `@tenphi/cookbook` default export represents the complete product. Consumers do
 not compose renderer internals themselves.
@@ -27,7 +27,7 @@ not compose renderer internals themselves.
 ## Build pipeline
 
 1. Validate and normalize the configuration.
-2. Collect local and locked package sources.
+2. Collect local files, local OpenAPI documents, and locked package sources.
 3. Assign canonical routes to every document.
 4. Parse Markdown and collect headings, links, and assets.
 5. Rewrite internal references through the completed route graph.
@@ -135,6 +135,9 @@ The monorepo's `apps/reference` project is both the deployed documentation site
 and an end-to-end fixture. Its integration discovers `docs.config.ts`, whose
 `root: "../.."` loads this `docs/` tree through the same route pipeline used by
 convention-mode sites. CI builds the same app before GitHub Pages publishes it.
+The site is deployed only after a package release: the release workflow creates
+a version tag and starts the Pages workflow from that tag, so the public
+reference matches the published code.
 
 Return to [Cookbook](./index.md) or inspect the
 [repository](https://github.com/tenphi/cookbook).

package/docs/authoring.mdx

@@ -1,6 +1,6 @@
 ---
 title: Authoring components
-description: Use accessible tabs, callouts, code groups, cards, steps, and isolated previews.
+description: Write pages, then use accessible tabs, callouts, code groups, cards, steps, and isolated previews.
 sidebar:
   order: 4
 ---
@@ -19,6 +19,18 @@ Write ordinary Markdown for most pages. Use MDX when a page needs components,
 and import them from `@tenphi/cookbook/components`. Local MDX is supported by
 default; npm MDX requires an explicit `trust: "mdx"` source declaration.
 
+## Page titles and descriptions
+
+A page's title comes from its frontmatter `title`, then the source
+declaration's `title`, then its first `#` heading, then its file name. When the
+page starts with an `#` heading equal to its title, Cookbook removes that heading
+from the body so the title is not shown twice. The description comes from
+frontmatter `description`, then the source declaration, then the first prose
+paragraph of at least 20 characters, cut to 240 characters.
+
+See [page frontmatter](./configuration.md#page-frontmatter) for every field,
+including `slug`, `draft`, `sidebar`, `prev`, and `next`.
+
 ## Tabs
 
 Every panel requires a `label`. Arrow keys, Home, and End move between tabs;
@@ -44,7 +56,8 @@ import { Tab, Tabs } from "@tenphi/cookbook/components";
 Use `kind="note"`, `"tip"`, `"caution"`, or `"danger"`; `title` overrides the
 visible label. The default kind is `note`. Status colors come from
 `theme.palette.info`, `success`, `warning`, and `danger` and adapt to all schemes
-and contrast modes.
+and contrast modes. For callouts written in plain Markdown, use
+[GitHub alerts](./plugins.md#github-alerts).
 
 ```mdx
 <Callout kind="tip" title="Keep content close to code">
@@ -81,10 +94,13 @@ Each panel retains keyboard-accessible tabs and readable fallback content.
   ]}
 />
 
-## Cards, steps, and previews
+## Cards and steps
 
 Use a card to link to another page, or omit `href` to present a standalone
-summary. `Steps` renders an ordered list; put ordinary `li` elements inside it.
+summary. `href` is used as written: give a public URL, including any Astro
+`base`, or a `#fragment`. Unlike Markdown links, `.md` paths are not rewritten;
+`cookbook check-build` reports broken targets. `Steps` renders an ordered list;
+put ordinary `li` elements inside it.
 
 ```mdx
 import { Card, Steps } from "@tenphi/cookbook/components";
@@ -110,6 +126,8 @@ import { Card, Steps } from "@tenphi/cookbook/components";
   <li>Build and check the output.</li>
 </Steps>
 
+## Previews
+
 `Preview` runs HTML and optional JavaScript in a sandboxed iframe with a source
 disclosure. It cannot access the documentation page's origin. Its `css` prop is
 for the isolated preview document; style the documentation shell with Tasty.
@@ -130,6 +148,8 @@ import { Preview } from "@tenphi/cookbook/components";
   css={"button { padding: 0.75rem; }"}
 />
 
+### Run your own library
+
 To demonstrate your own library, build it into the site's public directory
 (`public/` by default) and list the files in `scripts` by their public path,
 without the Astro `base`. Cookbook inlines each file, in order, before
@@ -154,21 +174,72 @@ shows each inlined file as a `<script src>` tag. Every preview embeds its own
 copy, so keep demo bundles small. A missing file or a path outside the public
 directory fails the build.
 
-The frame is at least `10rem` tall, and content outside it is clipped. Give a
-demo with an overlay, such as a listbox, a popover, or a modal dialog, more
-room with `height`, the frame's minimum height as a CSS length such as `18rem`
-or `320px`. Any other value, including a percentage or `calc()`, fails the
-build. To change every preview, style `theme.styles.Preview.Frame` instead.
+### Frame size
+
+A preview that runs scripts, with `javascript` or `scripts`, fits its frame to
+its content. The frame grows and shrinks as the content changes, the page
+width changes, or fonts load. It is at least `10rem` tall and at most as tall
+as the browser window; taller content scrolls inside the frame. A preview
+without scripts keeps a `10rem` frame, and content beyond it scrolls.
+
+```mdx
+<Preview
+  title="Growing list"
+  html={'<button type="button">Add item</button><ol></ol>'}
+  javascript={
+    "document.querySelector('button').addEventListener('click', () => document.querySelector('ol').append(document.createElement('li')));"
+  }
+/>
+```
+
+<Preview
+  title="Growing list"
+  html={'<button type="button">Add item</button><ol></ol>'}
+  javascript={
+    "document.querySelector('button').addEventListener('click', () => document.querySelector('ol').append(document.createElement('li')));"
+  }
+/>
+
+The frame fits the content in the document's flow. An overlay, such as a
+listbox, a popover, a modal dialog, or an absolutely positioned menu, doesn't
+make it taller when it opens, so reserve room for it:
+
+- `buffer` adds room below the content for a picker's list, such as a select's
+  or a combobox's. The room follows the content as the page width changes it.
+  It defaults to no extra room. A preview without scripts can't measure its
+  content, so `buffer` has no effect there.
+- `height` sets the frame's minimum height in place of `10rem`, for an overlay
+  that uses the whole frame, such as a modal dialog. It also applies to
+  previews without scripts.
+
+The frame is as tall as the content plus `buffer`, up to the window's height,
+and never shorter than `height`. Both take a CSS length with a unit, such as
+`12rem`, `320px`, or `0px`; any other value, including a unitless `0`, a
+percentage, or `calc()`, fails the build. To change every preview, style
+`theme.styles.Preview.Frame` instead.
 
 ```mdx
 <Preview
   title="Library select"
-  height="18rem"
+  buffer="15rem"
   html={"<acme-select label='Fruit'></acme-select>"}
   scripts={["/demo/select.js"]}
 />
+
+<Preview
+  title="Library dialog"
+  height="24rem"
+  html={"<acme-dialog open>Saved</acme-dialog>"}
+  scripts={["/demo/dialog.js"]}
+/>
 ```
 
+Don't size the content by the frame, for example with `100vh` or
+`height: 100%` on the root element: the frame can't fit such content, and it
+can grow to the window's height.
+
+### Forms
+
 Forms in a preview can be submitted. To show what a form sends, call
 `event.preventDefault()` in a `submit` listener and read its `FormData`;
 otherwise the submission navigates the frame away from the demo. The
@@ -202,62 +273,95 @@ origin.
 `Logo` renders the Cookbook mark. Use `label` when it carries meaning or
 `decorative` beside nearby text that already names the site. To display your
 own artwork in the header and drawer, configure
-[`site.logo`](./configuration.md#site-logo).
+[`site.logo`](./theme-and-components.md#logo-and-favicon).
 
-## Diff snippets
+## Code fences
 
-Use a `diff` code fence to highlight additions and deletions. The `+` and `-`
-markers remain visible independently of their theme-aware backgrounds:
+Fenced code blocks get Shiki highlighting and a copy control. Use a `diff` or
+`patch` fence to highlight additions and deletions. The `+` and `-` markers
+remain visible independently of their theme-aware backgrounds:
 
 ```diff
 -formatOkhsl(v.h, v.s * 100, l * 100);
 +formatOkhsl(v.h, v.s, l);
 ```
 
+A `mermaid` fence renders a static, theme-aware diagram; see
+[Mermaid diagrams](./configuration.md#markdown).
+
 ## Component props
 
-| 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 root `class`; renders the Cookbook mark                                                                |
-| `Preview` | Required `title`; optional `html`, `css`, `javascript`, public-file `scripts`, and frame `height`; isolates examples in a sandboxed iframe |
+| Component   | Props and behavior                                                                                                                                                                              |
+| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Tabs`      | Optional `label`, the tab list's accessible name (default "Examples"); contains `Tab` elements                                                                                                  |
+| `Tab`       | Required `label`, used as the tab button text and as the panel heading without JavaScript                                                                                                       |
+| `Callout`   | Optional `kind` (`note` by default, `tip`, `caution`, or `danger`) and `title`                                                                                                                  |
+| `CodeGroup` | Optional `label` (default "Code examples") and required `items`: `{ label, code, language? }[]`                                                                                                 |
+| `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 root `class`; renders the Cookbook mark                                                                                                                     |
+| `Preview`   | Required `title`; optional `html`, `css`, `javascript`, public-file `scripts`, minimum frame `height`, and overlay `buffer`; isolates examples in a sandboxed iframe that fits scripted content |
 
 The public package exports each component's props type, such as `TabProps`,
 `CalloutProps`, and `CodeGroupProps`. Styles and all named sub-elements are
-listed in [Component styles](./component-styles.md#style-customization).
+listed in [Component styles](./component-styles.md#complete-component-anatomy).
 
 ## 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`:
+Desktop pages show a table of contents for heading levels 2 and 3. Set the
+site defaults with the top-level
+[`tableOfContents`](./configuration.md#table-of-contents) key; set the same
+field in a page's frontmatter to change one page:
 
-```ts
-tableOfContents: { mobile: true, minHeadingLevel: 2, maxHeadingLevel: 3 }
+```yaml
+tableOfContents:
+  mobile: true
+  maxHeadingLevel: 4
 ```
 
-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.
-The desktop contents list highlights the current section and scrolls its own
-list when the active link moves out of view.
-Customize `theme.styles.MobileTableOfContents` and `TableOfContentsLayout`.
+A page's `tableOfContents` object replaces the site's heading levels; omitted
+levels fall back to 2 and 3. Only `mobile` falls back to `docs.config.ts`.
+`tableOfContents: false` disables both versions. Selecting a mobile contents
+link closes the disclosure and moves keyboard focus to the heading. The desktop
+contents list highlights the current section and scrolls its own list when the
+active link moves out of view. Customize `theme.styles.TableOfContents` (desktop
+list), `MobileTableOfContents`, and `TableOfContentsLayout`.
 
-## Hero images
+## Hero
 
-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:
+Add `hero` to a page's frontmatter to show a hero above the content. Home
+pages usually combine it with the wide `template: splash` layout:
 
 ```yaml
+template: splash
 hero:
-  tagline: Build something useful.
+  title: Build something useful
+  tagline: Documentation that stays with the code.
   image:
     file: ./assets/hero.png
     alt: A preview of the documentation
+  actions:
+    - text: Get started
+      link: ./getting-started.md
+      variant: primary
+    - text: Compare tools
+      link: /comparison
+      variant: secondary
 ```
 
+`title` defaults to the page title. Each action needs `text` and `link`;
+`variant` is `primary`, `secondary`, or `minimal`. Action links go through the
+same link rewriting as Markdown, so a relative `.md` path works.
+
+### Hero images
+
+Use a relative local image. Cookbook reads its intrinsic dimensions and
+reserves the correct aspect ratio as the layout responds to screen width.
 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.
+`height`; explicit dimensions on a local image must match its aspect ratio.
+`image.html` accepts inline HTML, such as an SVG, in local content and is
+removed from untrusted package Markdown. 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

@@ -5,10 +5,37 @@ sidebar:
   order: 6
 ---
 
+Cookbook has two command-line tools: the `cookbook` command from
+`@tenphi/cookbook`, and the project creator run through
+`npm create @tenphi/cookbook`.
+
+| Command                | Purpose                                                          |
+| ---------------------- | ---------------------------------------------------------------- |
+| `cookbook doctor`      | Check configuration, content, links, and local files (preflight) |
+| `cookbook check-build` | Check the built site and, with `--url`, its deployment           |
+| `cookbook update`      | Create or refresh `cookbook.lock.json` for npm package sources   |
+| `cookbook --help`      | Print usage; `cookbook` without a command does the same          |
+
 The integration and CLI discover `docs.config.ts`, `.mts`, `.js`, or `.mjs` in the
 project directory. Its `root` sets the content and lock directory. Use `--root`
 to select another project, or `--config` for an explicit config path relative to
-that project.
+that project. Add `--json` to any command for machine-readable output.
+
+Projects made by the creator wrap these commands in `package.json` scripts:
+
+| Script        | Runs                                                                     |
+| ------------- | ------------------------------------------------------------------------ |
+| `dev`         | `astro dev`                                                              |
+| `build`       | `astro build`                                                            |
+| `preview`     | `astro preview`                                                          |
+| `typecheck`   | `tsc --noEmit`                                                           |
+| `doctor`      | `cookbook doctor`                                                        |
+| `check-build` | `cookbook check-build`                                                   |
+| `validate`    | `tsc --noEmit && cookbook doctor && astro build && cookbook check-build` |
+| `update`      | `cookbook update`                                                        |
+
+In a project you set up yourself, add the same scripts or run
+`npx @tenphi/cookbook <command>`.
 
 ## Validate with doctor
 
@@ -28,7 +55,9 @@ 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:
+Every JSON result has `ok`, `pages`, `assets`, and `diagnostics`, including
+argument and configuration failures. Doctor adds `scope: "preflight"` and
+`buildVerified: false`:
 
 ```json
 {
@@ -49,11 +78,9 @@ 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.
+`--out` defaults to `dist` and 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,
@@ -69,11 +96,11 @@ 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.
+JSON output has `scope` (`built-output` or `deployment`) and `checkedUrls`
+instead of `buildVerified`. 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
 
@@ -84,14 +111,16 @@ npx @tenphi/cookbook update --json
 ```
 
 `update` reads package sources from configuration, creates the first lock,
-resolves changed tags or ranges, and removes entries that are no longer declared.
-A package name or exact requested specifier selects individual updates. An
-unselected source must already have a matching lock; otherwise run a full update.
+resolves every declared tag or range again, and removes entries that are no
+longer declared. An unchanged `@latest` or `^1` therefore moves to its newest
+match. A package name or exact requested specifier selects individual updates.
+An unselected source must already have a matching lock; otherwise run a full
+update.
 
 `--dry-run` resolves versions and shows the proposed changes without writing
-files. JSON output adds `dryRun`, `changes`, `removed`, and `lock` to the envelope.
-Review and commit the resulting lock diff before deploying. Builds require an
-exact requested-specifier match and never silently substitute a lock for another
+files. JSON output adds `dryRun`, `changes`, `removed`, and `lock`. Review and
+commit the resulting lock diff before deploying. Builds require an exact
+requested-specifier match and never silently substitute a lock for another
 range or tag.
 
 Vendored sources remain vendored. New artifacts are stored in separate integrity
@@ -109,22 +138,52 @@ npm create @tenphi/cookbook@latest docs-site -- --source . --yes
 npm create @tenphi/cookbook@latest docs-site -- --package @scope/package --yes
 ```
 
-| Flag                                                             | Purpose                                           |
-| ---------------------------------------------------------------- | ------------------------------------------------- |
-| `--source <directory>`                                           | Document an existing local repository             |
-| `--package <specifier>`                                          | Document a locked npm artifact                    |
-| `--yes`, `-y`                                                    | Use non-interactive defaults                      |
-| `--brand <color>`                                                | Set the Glaze brand seed                          |
-| `--site <url>`                                                   | Set the canonical site URL                        |
-| `--base <path>`                                                  | Set Astro's hosting subpath                       |
-| `--deploy github-pages\|netlify\|cloudflare-pages\|vercel\|none` | Add deployment setup or a host guide              |
-| `--package-manager npm\|pnpm\|yarn`                              | Select the project manager                        |
-| `--no-install`                                                   | Generate files without installing dependencies    |
-| `--vendor`                                                       | Vendor the npm artifact for offline builds        |
-| `--trust-package`                                                | Permit MDX execution from the locked npm artifact |
-| `--open`                                                         | Start and open the development server             |
+Pass creator flags after `--` so `npm create` forwards them.
+
+| Argument or flag                                                 | Purpose                                                                        |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `[destination]`                                                  | Target directory; defaults to `docs-site`, or `<name>-docs` with `--package`   |
+| `--source <directory>`                                           | Document an existing local repository                                          |
+| `--package <specifier>`                                          | Document a locked npm artifact                                                 |
+| `--yes`, `-y`                                                    | Never prompt; fail instead of asking to overwrite a non-empty destination      |
+| `--brand <color>`                                                | Set the Glaze brand seed                                                       |
+| `--site <url>`                                                   | Set the canonical site URL                                                     |
+| `--base <path>`                                                  | Set Astro's hosting subpath                                                    |
+| `--deploy github-pages\|netlify\|cloudflare-pages\|vercel\|none` | Add a [deployment workflow or host guide](./deployment.md)                     |
+| `--package-manager npm\|pnpm\|yarn`                              | Select the package manager; defaults to the one that ran the creator, then npm |
+| `--no-install`                                                   | Generate files without installing dependencies                                 |
+| `--vendor`                                                       | Vendor the npm artifact for offline builds                                     |
+| `--trust-package`                                                | Permit MDX execution from the locked npm artifact                              |
+| `--open`                                                         | Start the development server in the background, without output, and open it    |
+| `--help`, `-h`                                                   | Print usage                                                                    |
 
 `--source` and `--package` are mutually exclusive. With neither, the creator
 writes a local starter. `--vendor` and `--trust-package` require `--package`.
-`--open` requires installation. A non-empty destination requires interactive
-confirmation before generated files can be overwritten.
+`--open` requires installation; stop the background server yourself when you
+are done. A non-empty destination requires interactive confirmation before
+generated files can be overwritten.
+
+Yarn 4 uses Plug'n'Play by default, which Cookbook does not support. For Yarn,
+the creator writes `.yarnrc.yml` with `nodeLinker: node-modules` and an empty
+`yarn.lock`, so the site also installs as its own project inside an existing
+Yarn repository. With `--deploy github-pages`, a site created inside a Git
+repository gets its workflow at the repository root; see
+[GitHub Pages](./deployment.md#github-pages).
+
+## Diagnostic codes
+
+Each diagnostic has a code, a severity, a message, and usually a source file,
+line, and hint. Errors fail the command; warnings do not.
+
+| Stage                        | Codes                                                                                                                                                                                                                                                                                                                           |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Configuration                | `DOCS_CONFIG_INVALID`, `DOCS_CONFIG_UNKNOWN_KEY`                                                                                                                                                                                                                                                                                |
+| Sources and routes           | `DOCS_NO_PAGES`, `DOCS_SOURCE_NOT_FOUND`, `DOCS_SOURCE_OUTSIDE_ROOT`, `DOCS_DUPLICATE_SOURCE`, `DOCS_DUPLICATE_ROUTE`, `DOCS_FRONTMATTER_INVALID`, `DOCS_REDIRECT_INVALID`, `DOCS_VERSION_ROOT_MISSING`, `DOCS_NAV_TARGET_NOT_FOUND`, `DOCS_OPENAPI_INVALID`                                                                    |
+| Links and assets             | `DOCS_LINK_NOT_FOUND` (a warning unless `build.strict`), `DOCS_FRAGMENT_NOT_FOUND` (an error with `build.ci`), `DOCS_LINK_UNSAFE`, `DOCS_AMBIGUOUS_LINK`, `DOCS_HEADING_DUPLICATE`, `DOCS_ASSET_NOT_FOUND`, `DOCS_ASSET_UNSAFE`                                                                                                 |
+| Content safety               | `DOCS_RAW_HTML_STRIPPED`, `DOCS_RAW_HTML_REJECTED`, `DOCS_UNTRUSTED_HTML`, `DOCS_UNTRUSTED_MDX`                                                                                                                                                                                                                                 |
+| Doctor only                  | `DOCS_CONFIG_ASSET_MISSING`, `DOCS_COMPONENT_UNRESOLVED`, `DOCS_SEMANTIC_CONTRAST_UNMET`, `DOCS_BRAND_CONTRAST_UNMET`                                                                                                                                                                                                           |
+| Built output (`check-build`) | `DOCS_BUILD_MISSING`, `DOCS_SITE_URL_MISSING` (a warning), `DOCS_OUTPUT_URL_INVALID`, `DOCS_OUTPUT_LINK_MISSING`, `DOCS_OUTPUT_FRAGMENT_MISSING`, `DOCS_PUBLISHING_PAGE_MISSING`, `DOCS_CANONICAL_INVALID`, `DOCS_INDEX_POLICY_MISMATCH`, `DOCS_SITEMAP_PAGE_MISSING`, `DOCS_SITEMAP_UNLISTED_PAGE`, `DOCS_AGENT_UNLISTED_PAGE` |
+| Deployment (`--url`)         | `DOCS_DEPLOYMENT_HTTP`, `DOCS_DEPLOYMENT_PAGE_MISMATCH`, `DOCS_DEPLOYMENT_NOINDEX`, `DOCS_DEPLOYMENT_ASSET_INVALID`, `DOCS_DEPLOYMENT_FETCH`                                                                                                                                                                                    |
+| Command line                 | `COOKBOOK_CLI_ERROR` for invalid arguments and other command failures                                                                                                                                                                                                                                                           |
+
+See [troubleshooting](./troubleshooting.md) for common fixes.