@tenphi/cookbook 0.16.0 → 0.17.1

package/README.md

@@ -25,6 +25,23 @@ import { defineDocsConfig } from "@tenphi/cookbook/config";
 export default defineDocsConfig({ site: { title: "My project" } });
 ```
 
+Set fonts, typography, and built-in element styles in the same file:
+
+```ts
+export default defineDocsConfig({
+  theme: {
+    fonts: { body: "Inter", heading: "Newsreader" },
+    presets: { h1: { fontSize: "3rem" } },
+    styles: { Sidebar: { LinkLabel: { whiteSpace: "normal" } } },
+  },
+});
+```
+
+For local fonts, place files in `public/fonts/` and use
+`fonts: { body: { family: "My Font", files: [{ src: "/fonts/my-font.woff2" }] } }`.
+See [Theme and components](./docs/theme-and-components.md) for all named
+sub-elements and the custom component flow.
+
 Without configuration, a root `README.md` becomes `/` and
 `docs/**/*.{md,mdx}` supplies the remaining pages. Cookbook includes Starlight,
 generates only static output, and derives its URL base from Astro. Adding other

package/dist/config.d.ts

@@ -1,3 +1,3 @@
 
-import { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, ComponentStylesConfig, DocsConfig, DocsSource, ThemeConfig, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs/config";
-export { COOKBOOK_COMPONENT_NAMES, COOKBOOK_COMPONENT_SUB_ELEMENTS, type ComponentStylesConfig, type DocsConfig, type DocsSource, type ThemeConfig, defineDocsConfig, mergeDocsConfig };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 
 import starlight_default, { CookbookOptions, DEFAULT_THEME_TOKENS, DEFAULT_TYPOGRAPHY_PRESETS } from "@tenphi/starlight";
-import { BrandConfig, 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, ThemeConfig, ThemePaletteConfig, ThemeTokenValue, ThemeTokens, TypographyPreset, TypographyPresets, defineDocsConfig, mergeDocsConfig } from "@tenphi/docs";
-export { type BrandConfig, 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 ThemeConfig, type ThemePaletteConfig, type ThemeTokenValue, type ThemeTokens, type TypographyPreset, type TypographyPresets, starlight_default as default, defineDocsConfig, mergeDocsConfig };
+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 };

package/docs/ai-agents.md

@@ -0,0 +1,61 @@
+---
+title: AI agents
+description: Create a Cookbook site with a coding agent and make the published docs easy for agents to find and read.
+sidebar:
+  order: 3
+---
+
+Cookbook's project creator writes an `AGENTS.md` beside `docs.config.ts` and an
+`.agents/skills/upgrade-cookbook/SKILL.md` for dependency upgrades. They tell
+coding agents where content lives, where to find Cookbook's installed reference
+docs, how to upgrade Cookbook, and how to validate changes. Give an agent a
+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.
+
+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
+```
+
+For a new project without existing documentation, omit `--source .`. To document
+an npm artifact, use `--package name@version` instead. The [getting started
+guide](./getting-started.md) covers all three paths. Agents should edit
+`docs.config.ts` for site metadata, navigation, and theme, and follow the
+[customization rules](./customization-rules.md) for styling.
+Replace the example URL with the site's actual public origin.
+
+## Make the published site readable
+
+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
+  discovery aid for agents that choose to read it.
+- `robots.txt` at origin-root deployments 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.
+
+You can supply your own `public/llms.txt` or `public/robots.txt`; Cookbook keeps
+those files. For sites under a path, configure an origin-root `robots.txt` at
+the hosting layer if you need one.
+
+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`.
+
+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/).

package/docs/cli.md

@@ -67,20 +67,20 @@ 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\|none`       | Add a deployment workflow                         |
-| `--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             |
+| 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             |
 
 `--source` and `--package` are mutually exclusive. With neither, the creator
 writes a local starter. `--vendor` and `--trust-package` require `--package`.

package/docs/configuration.md

@@ -29,8 +29,10 @@ and the lock live. `--root` chooses the CLI's configuration search directory;
 discovery and resolves its `root` relative to the integration root.
 
 Use `mergeDocsConfig(preset, overrides)` to compose shared configuration. Objects
-merge recursively and arrays replace; Tasty styles preserve default values when
-adding conditional overrides. Neither input is mutated. See
+merge recursively and arrays replace. Each `theme.fonts` role replaces its
+previous definition, so switching a role from Google to local files takes one
+override. Tasty styles preserve default values when adding conditional
+overrides. Neither input is mutated. See
 [working examples](./examples.md#share-configuration-and-themes).
 
 ## Redirects
@@ -64,7 +66,34 @@ with one locked npm package source infers its version automatically; set this
 field for local or multi-package documentation. Read it from the package
 manifest when possible so it remains current. `url` configures Astro's canonical
 site origin and sitemap metadata. If Astro also declares `site`, the values must
-match. `repository` adds a source link to the header.
+match. It also lets Cookbook put absolute page URLs in `llms.txt` and a sitemap
+pointer in the origin-root `robots.txt`. `repository` adds a source link to the
+header.
+
+For multiple documentation versions, set `site.versions` and mount content at
+each version root. The header then shows a version selector. It links to the
+same route in another version when that page exists and falls back to the
+other version's root when it does not:
+
+```ts
+site: {
+  versions: [
+    { label: "Latest", routeBase: "/" },
+    { label: "v1", routeBase: "/v1" },
+  ],
+},
+content: {
+  sources: [
+    { file: "README.md", route: "/" },
+    { glob: "docs/**/*.md", base: "docs" },
+    { file: "versions/v1/README.md", routeBase: "/v1", route: "/" },
+    { glob: "versions/v1/docs/**/*.md", base: "versions/v1/docs", routeBase: "/v1" },
+  ],
+},
+```
+
+Each `routeBase` must have a page, and version roots must be distinct. A
+single-version site can continue using `site.version` for a simple label.
 
 ### Site icons
 
@@ -315,12 +344,36 @@ fallback. Every internal route named anywhere in navigation must exist.
 theme: {
   brand: {
     from: "#2f5bff",
-    contrast: { apca: 45 }
+    contrast: { apca: [45, 60] }
   },
   palette: {
-    surface: "#fcfcff",
-    text: "#20232a",
-    textSoft: "#626875"
+    surface: { tone: 98, saturation: 0.05 },
+    text: {
+      base: "surface",
+      tone: 0,
+      saturation: 0,
+      contrast: { wcag: [7, 10] }
+    },
+    heading: {
+      base: "surface",
+      tone: [4, 0],
+      saturation: 0,
+      contrast: { wcag: [7, 10] }
+    },
+    textSoft: {
+      base: "surface",
+      tone: [25, 10],
+      saturation: 0.05,
+      contrast: { wcag: [4.5, 7] }
+    }
+  },
+  fonts: {
+    body: "Inter",
+    heading: { google: "Newsreader", weights: [400, 700] },
+    code: {
+      family: "Project Mono",
+      files: [{ src: "/fonts/project-mono.woff2", weight: "100 900" }]
+    }
   },
   tokens: {
     "$radius": "8px",
@@ -332,9 +385,8 @@ theme: {
   },
   states: {},
   presets: {
-    body: { fontFamily: "Inter, sans-serif", boldFontWeight: 680 },
+    body: { boldFontWeight: 680 },
     heading: {
-      fontFamily: "Newsreader, serif",
       fontWeight: 650,
       boldFontWeight: 740
     }
@@ -351,10 +403,20 @@ theme: {
 
 The default brand is `okhsl(266 68% 48%)`, a blue with 68% saturation; controls
 use an `8px` radius and cards use `16px`. Onest is the default body and heading family, while JetBrains Mono is
-used for code. The default layout is capped at `87.5rem` (1400px), matching the
-Tasty site, with a `58rem` reading column and a `17.5rem` sidebar. `palette`
-supplies semantic Glaze inputs rather than component colors,
-so the whole interface continues to adapt in dark and high-contrast modes. A requested APCA floor below 45 requires the explicit
+used for code. `theme.fonts` loads Google families by name or local files from
+`public/`, and applies them to the body, heading, and code presets. See
+[Change font families](./theme-and-components.md#change-font-families) for both
+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. 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
 [Theme and components](./theme-and-components.md).
 
@@ -393,6 +455,22 @@ Configure renderer-level Markdown options such as custom remark or rehype
 plugins and Shiki languages through Astro's top-level `markdown` configuration.
 Cookbook preserves those settings while adding its own build-time transforms.
 
+Starlight content and behavior plugins can be supplied to the Astro integration:
+
+```ts
+import myStarlightPlugin from "./plugins/my-starlight-plugin.js";
+
+export default defineConfig({
+  integrations: [cookbook({ plugins: [myStarlightPlugin()] })],
+});
+```
+
+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 renders fenced `mermaid` blocks as responsive, theme-aware SVG during
 the static build. Flowcharts, state, sequence, class, and entity-relationship
 diagrams are supported. Invalid or unsupported diagrams remain visible as
@@ -510,7 +588,7 @@ the Astro base. `variant` is `default` or `primary` and applies on desktop;
 and adds safe new-window attributes when enabled. Customize the complete
 button and popover style tree through `theme.styles.HeaderLinks`.
 
-`theme.palette.header` sets the translucent header's color seed. It defaults
+`theme.palette.header` sets the translucent header's color declaration. It defaults
 to `theme.palette.surface`; Glaze resolves it for light, dark, and both high
 contrast modes. Adjust blur and other header styling via `theme.styles.HeaderFrame`.
 `theme.palette.overlay` controls the fixed underlay color, defaulting to black at

package/docs/content-sources.md

@@ -1,6 +1,6 @@
 ---
 title: Content sources
-description: Collect local files, globs, and locked npm package documentation into one route graph.
+description: Collect local files, OpenAPI specs, and locked npm package documentation into one route graph.
 sidebar:
   order: 3
 ---
@@ -92,6 +92,34 @@ A frontmatter `slug` is relative to `routeBase`, including when it begins with
 accept `routeBase`, which prefixes their explicit `route`. Empty `sources: []`
 means no sources; omit the property to enable conventions.
 
+## OpenAPI references
+
+Add a local OpenAPI 3.x JSON or YAML document to generate a searchable overview
+and one page per operation:
+
+```ts
+content: {
+  sources: [
+    { file: "README.md", route: "/" },
+    { openapi: "api/openapi.yaml", routeBase: "/api" },
+  ],
+}
+```
+
+The overview appears at `/api`. An operation with `operationId: getWidget`
+appears at `/api/get-widget`. Without an operation ID, Cookbook derives a route
+from its method and path. Operation IDs must create distinct routes. The pages
+include parameters, request bodies, responses, examples, and the document's
+schemas. Source links point back to the spec file. Use a navigation item such
+as `{ label: "API", link: "/api", items: [{ label: "Operations", autogenerate: { directory: "/api" } }] }`
+to show the operations in the sidebar.
+
+The source must stay within its declared `root` unless
+`content.allowOutsideRoot` is enabled. External `$ref` values require bundling
+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.
+
 ## npm package sources
 
 Package sources read documentation from the actual npm artifact:

package/docs/customization-rules.md

@@ -23,6 +23,7 @@ before overriding a built-in component.
 | ----------------------------- | ------------------------------------------------------ |
 | Brand and semantic colors     | `theme.brand` and the supported `theme.palette` inputs |
 | Shared dimensions and spacing | `theme.tokens`                                         |
+| Font loading and family roles | `theme.fonts`                                          |
 | Typography                    | `theme.presets`                                        |
 | Responsive conditions         | `theme.states`                                         |
 | Existing component appearance | Partial Tasty objects in `theme.styles.<Name>`         |
@@ -63,8 +64,8 @@ belong in `docs.config.ts`.
   owning style object. Keep their selectors and base styles together instead
   of spreading component anatomy across unrelated global rules.
 * Use semantic color tokens such as `#text`, `#surface`, and `#accent-text`
-  in component styles. Configure color seeds through `theme.brand` and the
-  supported `theme.palette` roles so Glaze can resolve every scheme and
+  in component styles. Configure Glaze color declarations through `theme.brand`
+  and the supported `theme.palette` roles so Glaze can resolve every scheme and
   contrast mode. Do not hard-code component colors or invent palette keys.
 * Apply semantic typography with `preset`, for example `"small"` or
   `"h2 / strong"`. Do not reconstruct presets from individual font tokens or

package/docs/deployment.md

@@ -65,14 +65,31 @@ not required.
 
 This site is deployed by the repository's Pages workflow to
 `cookbook.tenphi.me` with HTTPS enforcement enabled.
+The Cookbook repository deploys its own documentation only after a package
+release. The release workflow creates a version tag and then starts the Pages
+workflow from that tag, so the public reference matches the published code.
 
 ## Other static hosts
 
-Use the host's ordinary static-site settings:
+The creator supports `--deploy netlify`, `--deploy cloudflare-pages`, and
+`--deploy vercel`. It writes a `DEPLOYMENT.md` with host settings; Netlify also
+gets `netlify.toml`. You can also use the host's ordinary static-site settings:
 
 - build command: `npm run build`
 - publish directory: `dist`
-- Node.js: 22.14 or newer
+- Node.js: 22.19 or newer
 
 If the host serves the site below a path rather than at an origin root, set
 Astro's `base`; Cookbook derives it automatically.
+
+## Discovery and agent access
+
+Set `site.url` to the public HTTPS origin before building. This enables canonical
+page URLs and the sitemap. The build also emits `llms.txt` with links to
+published documentation pages. At an origin root, it emits `robots.txt` pointing
+to the sitemap. Host these files with the rest of `dist/`; custom files in
+`public/` take precedence. For path-hosted sites, manage the origin's
+`robots.txt` in the hosting configuration.
+
+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.

package/docs/examples.md

@@ -79,7 +79,10 @@ A preset is an ordinary exported `DocsConfig` object:
 import { defineDocsConfig, mergeDocsConfig } from "@tenphi/cookbook/config";
 
 const company = defineDocsConfig({
-  theme: { brand: "#315efb", tokens: { $radius: "8px" } },
+  theme: {
+    brand: { from: "#315efb" },
+    tokens: { $radius: "8px" },
+  },
   markdown: { rawHtml: "sanitize" },
 });
 
@@ -89,6 +92,9 @@ export default mergeDocsConfig(company, {
 });
 ```
 
+Each `theme.brand` or `theme.palette` color replaces the corresponding color in
+the preset. Supply the complete Glaze declaration for a color you override.
+
 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

package/docs/getting-started.md

@@ -5,7 +5,7 @@ sidebar:
   order: 2
 ---
 
-Cookbook requires Node.js 22.14 or newer.
+Cookbook requires Node.js 22.19 or newer.
 
 ## Create your first site
 
@@ -16,7 +16,8 @@ npm run dev
 ```
 
 The creator writes a README, Astro configuration, and `docs.config.ts`, then
-installs dependencies. Edit `README.md` to change the home page. Add
+installs dependencies. It also writes `AGENTS.md` with instructions for coding
+agents. Edit `README.md` to change the home page. Add
 `docs/guide.md` to create `/guide`. New and edited pages appear in the development
 server without a restart.
 
@@ -86,10 +87,19 @@ export default defineDocsConfig({
     description: "Documentation for Example Project",
     repository: "https://github.com/example/project",
   },
-  theme: { brand: "#2f5bff" },
+  theme: {
+    brand: { from: "#2f5bff" },
+    fonts: { body: "Inter", heading: "Newsreader" },
+  },
 });
 ```
 
+Change `theme.fonts` to use [Google Fonts by name or your own font files](./theme-and-components.md#change-font-families).
+Use `theme.presets` for typography details, `theme.styles` for built-in elements,
+and `defineComponent()` with `theme.customStyles` to add a new element. The
+[theme guide](./theme-and-components.md) includes examples and the complete
+list of customizable sub-elements.
+
 The integration and CLI load the same configuration. Supported filenames are
 `docs.config.ts`, `.mts`, `.js`, and `.mjs`, in that order. An explicit integration
 `config` object takes precedence; `configFile: false` disables discovery.
@@ -120,5 +130,5 @@ npm run preview
 ```
 
 See [working examples](./examples.md), [authoring components](./authoring.mdx),
-and [deployment](./deployment.md). Existing users should read the
+the [AI agent workflow](./ai-agents.md), and [deployment](./deployment.md). Existing users should read the
 [prerelease migration guide](./migration.md).

package/docs/theme-and-components.md

@@ -28,22 +28,24 @@ cover the configuration language accepted by `theme.styles`:
 
 ## Brand color
 
-The default brand is a calm blue with 68% OKHSL saturation. The short form
-accepts any color value supported by Glaze:
+The default brand is a calm blue with 68% OKHSL saturation. Set a brand color
+with Glaze's `from` declaration:
 
 ```ts
 theme: {
-  brand: "okhsl(266 68% 48%)",
+  brand: {
+    from: "#2f5bff";
+  }
 }
 ```
 
-Use the object form to set an explicit contrast target:
+Add a contrast target when the brand appears as text or focus color:
 
 ```ts
 theme: {
   brand: {
-    from: "oklch(58% 0.22 265)",
-    contrast: { apca: [60, 75] }
+    from: "#2f5bff",
+    contrast: { apca: [45, 60] }
   }
 }
 ```
@@ -54,33 +56,68 @@ floor requires. Dark and high-contrast schemes resolve independently.
 
 Cookbook rejects a normal APCA target below 45 unless
 `unsafeContrast: true` is present. That escape hatch is intentionally visible
-in configuration reviews.
+in configuration reviews. Literal color shorthand and structured
+`hue`/`saturation`/`tone` input also remain supported for the brand.
 
 ## Semantic palette
 
-`brand` controls accent text, fills, and focus. The optional palette inputs
-control the neutral reading surface. `info`, `success`, `warning`, and `danger`
-configure callout status seeds; each exposes a border role, `-text`, and
-`-surface` semantic tokens for all schemes and contrast modes. The authored surface is preserved in the
-light scheme; its dark counterpart is deliberately desaturated so a nearly
-white tint cannot turn into vivid dark chrome when its tone is inverted. Glaze
-resolves all values independently for light, dark, normal, and high-contrast
-modes:
+`brand` controls accent text, fills, and focus. The optional palette roles
+control the reading surface, text, and callout colors. Declare color
+relationships with Glaze's `tone`, `base`, and `contrast` properties:
 
 ```ts
 theme: {
-  brand: "okhsl(266 68% 48%)",
+  brand: { from: "#2f5bff" },
   palette: {
-    surface: "#fffdf8",
-    text: "#211f1c",
-    textSoft: "#66615a"
+    surface: { tone: 98, saturation: 0.05 },
+    text: {
+      base: "surface",
+      tone: 0,
+      saturation: 0,
+      contrast: { wcag: [7, 10] }
+    },
+    heading: {
+      base: "surface",
+      tone: [4, 0],
+      saturation: 0,
+      contrast: { wcag: [7, 10] }
+    },
+    textSoft: {
+      base: "surface",
+      tone: [25, 10],
+      saturation: 0.05,
+      contrast: { wcag: [4.5, 7] }
+    }
   },
   contrastLevel: "auto"
 }
 ```
 
+Glaze resolves each declaration for light, dark, normal, and high-contrast
+modes. In a tone or contrast pair, the first value applies to normal mode;
+the second applies to high contrast. Use absolute tones for reading text:
+`text` starts at tone 0 and `heading` at tone 4, giving headings only a slight
+reduction in contrast. Glaze applies its tone boundaries in normal mode, so
+body text is not pure black, then inverts the tones for dark mode. High-contrast
+mode uses the full range. `textSoft` is reserved for secondary text.
+`heading` follows an explicitly configured `text` declaration unless it has
+its own declaration, preserving existing custom palettes.
+Contrast requirements are minimum safeguards: Glaze preserves the authored
+tone when it already meets the floor. A small relative tone step from the
+surface would instead leave the solver to produce text at that minimum.
+
+Palette declarations inherit the brand hue and saturation:
+`saturation` is a 0–1 factor of that seed, and `tone` is 0–100. They can set
+an absolute tone or a tone relative to `base`. Use `from` on a palette role
+when it needs its own color seed; otherwise relative declarations keep its
+relationship to the brand and surrounding surface as the scheme or contrast
+changes. `info`, `success`, `warning`, and `danger` also accept Glaze
+declarations and expose border, `-text`, and `-surface` semantic tokens.
+Cookbook keeps literal surface seeds desaturated in the dark scheme so a nearly
+white tint does not become vivid dark chrome when its tone is inverted.
+
 Components consume semantic colors consistently: `surface`, `header`, `surface-2`,
-`surface-3`, `text`, `text-soft`, `border`, `border-strong`, `accent-text`,
+`surface-3`, `text`, `heading`, `text-soft`, `border`, `border-strong`, `accent-text`,
 `accent-surface`, `accent-surface-text`, and `focus`. Tasty components can use
 these as `#surface`, `#text`, `#border`, and so on; the Astro shell consumes the
 same resolved values. Glaze also generates hover and pressed states, subtle
@@ -153,18 +190,74 @@ without one-off component overrides.
 The built-in [typography presets](./upstream/tasty/docs/styles.md#preset) are
 `body`, `heading`, `h1` through `h6`, `navigation`, `small`, and `code`. Onest
 is self-hosted and used for body and heading text by default; JetBrains Mono is
-self-hosted for code. Presets merge property-by-property, so changing a font
-does not require copying its size, weight, or line height:
+self-hosted for code.
+
+### Change font families
+
+Set `theme.fonts` to load fonts and apply them to the matching presets. A Google
+Fonts family needs only its name:
+
+```ts
+theme: {
+  fonts: {
+    body: "Inter",
+    heading: "Newsreader"
+  }
+}
+```
+
+The short form requests the family's default style. To use specific weights,
+list them explicitly. Google Fonts must support the requested weights; see the
+[Google Fonts CSS API](https://developers.google.com/fonts/docs/css2) for its
+available styles and weight syntax.
+
+```ts
+theme: {
+  fonts: {
+    body: { google: "Inter", weights: [400, 600, 700] }
+  }
+}
+```
+
+For a font you own, put its files in `public/fonts/` and give Cookbook their
+public paths. Cookbook checks that each file exists during the build and adjusts
+its URL for the Astro `base` path. A variable font can cover a weight range;
+use separate entries for regular and italic files when needed:
+
+```ts
+theme: {
+  fonts: {
+    body: {
+      family: "Acme Sans",
+      files: [
+        { src: "/fonts/acme-sans.woff2", weight: "100 900" },
+        { src: "/fonts/acme-sans-italic.woff2", weight: "100 900", style: "italic" }
+      ]
+    }
+  }
+}
+```
+
+The `body` role also feeds navigation and small text. `heading` feeds `h1`
+through `h6`, while `code` covers code text. Each role has a system fallback.
+Cookbook emits the font faces through Tasty. Google font names are resolved at
+build time, so those builds need network access; the generated site has no
+Google CSS stylesheet. Font files are requested from Google's font CDN when
+visitors open the site. Use local files if you need a self-hosted site.
+
+### Adjust presets
+
+Presets merge property-by-property, so changing size, weight, or line height
+does not require copying the rest of the preset. `theme.presets` takes precedence
+over `theme.fonts` for an explicitly set `fontFamily`:
 
 ```ts
 theme: {
   presets: {
     body: {
-      fontFamily: "Inter, system-ui, sans-serif",
       boldFontWeight: 680
     },
     heading: {
-      fontFamily: "Newsreader, Georgia, serif",
       fontWeight: 650,
       boldFontWeight: 740
     },
@@ -172,13 +265,15 @@ theme: {
       fontSize: "3rem",
       letterSpacing: "-0.02em"
     },
-    code: {
-      fontFamily: "Berkeley Mono, ui-monospace, monospace"
-    }
+    code: { fontSize: "0.9rem" }
   }
 }
 ```
 
+For a system or already loaded font, set its CSS family directly with
+`theme.presets.<role>.fontFamily`. This does not load a font file. Additional
+named presets are available to custom MDX components.
+
 Heading presets reference the `heading` family and weights; body, navigation,
 and controls reference `body`. Semantic `strong` and `b` elements use Tasty's
 `strong` modifier, so their weight comes from the active preset's
@@ -206,8 +301,6 @@ disclosure icons with `Caret` and `ExpandedCaret`.
 Adjacent sidebar items have a `1bw` gap. Inline code scales to `0.875em` of its
 surrounding text, including smaller table text; code blocks keep the `code` preset
 size. Customize inline code through `theme.styles.MarkdownInlineCode`.
-Additional named presets are passed through to Tasty SSR for use in custom MDX
-components.
 Cookbook applies each semantic typography role through its complete Tasty
 `preset`, so configured fields such as `fontStyle` and `textTransform` are not
 silently omitted.
@@ -285,6 +378,7 @@ sub-elements:
 | `MobileNavigationTabs`  | `Trigger`, `Marker`, `Caret`, `ExpandedCaret`, `Label`, `List`, `Item`, `Link`, `HoverLink`, `CurrentLink`                                                                                                                                                                                                                                                                                                                                                                                      |
 | `MobileTableOfContents` | `Item`, `Link`, `LinkLabel`, `HoverLink`, `CurrentLink`, `CurrentIndicator`                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `PackageVersion`        | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `VersionSwitcher`       | `Trigger`, `Panel`, `OpenPanel`, `Link`, `CurrentLink`                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `Preview`               | `Caption`, `Stage`, `Frame`, `Code`, `Summary`, `Pre`                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `Sidebar`               | `Backdrop`, `OpenBackdrop`, `MobileHeading`, `HomeLink`, `HomeLogo`, `HomeLabel`, `Close`, `HoverClose`, `CloseIcon`, `CurrentLink`, `OpenPane`, `Content`, `Tree`, `List`, `Item`, `TopLevelSpacing`, `GroupSpacing`, `NestedItem`, `SectionHeading`, `Control`, `Summary`, `GroupLabel`, `GroupLabelText`, `Link`, `LinkLabel`, `InteractiveControl`, `SummaryMarker`, `Caret`, `ExpandedCaret`, `LinkedSummary`, `GroupLink`, `LinkedSectionHeading`, `SectionLink`, `Badge`, `TopLevelLink` |
 | `SocialIcons`           | `Link`, `HoverLink`, `Icon`                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -293,6 +387,7 @@ sub-elements:
 | `SearchButton`          | `Label`, `Shortcut`, `Hover`, `Active`, `NativeIcon`, `Icon`                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `Layout`                | `LockedPage`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `HeaderLinks`           | `Desktop`, `Link`, `HoverLink`, `PrimaryLink`, `HoverPrimaryLink`, `Trigger`, `HoverTrigger`, `Panel`, `PanelNavigation`, `PanelLink`, `FirstPanelLink`, `Close`, `HoverClose`                                                                                                                                                                                                                                                                                                                  |
+| `Heading`               | `Level1`, `Level2`, `Level3`, `Level4`, `Level5`, `Level6`, `PageTitle`                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `HeaderFrame`           | None                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `PageFrame`             | `MainFrame`, `SidebarFrame`, `Columns`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `Steps`                 | `Item`, `Marker`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -653,7 +748,7 @@ selector, and a close button. The drawer slides in and out over 120ms and
 disables motion when the reader prefers reduced motion. Its mobile shadow uses
 the Glaze `shadow`-typed `#shadow` token. Customize the movement and shadow through
 `theme.styles.Sidebar`, and the underlay through `Sidebar.Backdrop` and
-`OpenBackdrop`. `theme.palette.overlay` supplies the underlay seed, which defaults
+`OpenBackdrop`. `theme.palette.overlay` supplies the underlay declaration, which defaults
 to black at 50% opacity. Glaze resolves it in fixed mode with tone remapping
 disabled, so it stays black in dark and high-contrast schemes.
 Icon buttons retain their plain desktop appearance on mobile. More uses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -47,7 +47,7 @@
     "index": "docs/index.md"
   },
   "engines": {
-    "node": ">=22.14"
+    "node": ">=22.19"
   },
   "publishConfig": {
     "access": "public"
@@ -64,8 +64,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.16.0",
-    "@tenphi/starlight": "0.16.0"
+    "@tenphi/docs": "0.17.1",
+    "@tenphi/starlight": "0.17.1"
   },
   "peerDependencies": {
     "astro": "^7.3.2"