@tenphi/cookbook 0.13.0 → 0.16.0

package/docs/customization-rules.md

@@ -0,0 +1,153 @@
+---
+title: Customization rules
+description: The customization contract for Cookbook consumers and coding agents, with local Tasty and Glaze references.
+sidebar:
+  order: 5
+---
+Read this guide before changing a Cookbook site's appearance. It applies to
+consumer projects and custom components. Cookbook's repository `AGENTS.md`
+also covers engine maintenance; consumers do not need to edit its component
+registries or internal helpers.
+
+## Read the configuration first
+
+Inspect `docs.config.ts`, `tasty.config.ts`, and the components you are changing.
+Reuse the site's existing semantic colors, tokens, presets, responsive states,
+and named sub-elements. Do not invent configuration names. Consult the complete
+[component anatomy reference](./theme-and-components.md#style-customization)
+before overriding a built-in component.
+
+## Choose the customization surface
+
+| Change                        | Supported surface                                      |
+| ----------------------------- | ------------------------------------------------------ |
+| Brand and semantic colors     | `theme.brand` and the supported `theme.palette` inputs |
+| Shared dimensions and spacing | `theme.tokens`                                         |
+| Typography                    | `theme.presets`                                        |
+| Responsive conditions         | `theme.states`                                         |
+| Existing component appearance | Partial Tasty objects in `theme.styles.<Name>`         |
+| Custom component appearance   | `defineComponent()` and `theme.customStyles.<Name>`    |
+| Markup or behavior            | `components.overrides` with an owned Astro component   |
+
+Prefer configuration changes when the markup and behavior already fit. Supply
+only the properties you want to change: Cookbook merges partial overrides into
+its complete base styles using Tasty's `mergeStyles`. Do not copy the entire
+default style tree or rebuild it in user configuration. Built-in names belong
+in `theme.styles`; custom names belong in `theme.customStyles`.
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  theme: {
+    styles: {
+      StarlightHeader: { SiteTitle: { preset: "h4 / strong" } },
+    },
+  },
+});
+```
+
+## Write styles through Cookbook
+
+Import `defineComponent`, `tasty`, `useGlobalStyles`, `resolveComponentStyles`,
+and `mergeStyles` from `@tenphi/cookbook/styling` as needed. Cookbook supplies
+the configured runtime and extracts static CSS; installing another Tasty
+integration or calling upstream `configure()` is unnecessary. Shared settings
+belong in `docs.config.ts`.
+
+* Express styles with Tasty. Do not add CSS files, CSS modules, Astro `<style>`
+  blocks, inline `style` attributes, or imported Starlight styles to customize
+  the documentation interface. The isolated content of `Preview` is a separate
+  demonstration surface.
+* Model descendants and pseudo-elements as named sub-elements inside the
+  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
+  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
+  wire modifier internals such as `$bold-font-weight` yourself.
+* Use `defineComponent(name, options)` for customizable component roots.
+  For global style trees, pass `resolveComponentStyles(name, baseStyles)` to
+  `useGlobalStyles()`. Both read partial overrides from `theme.customStyles`.
+  Document each custom component's name and complete named sub-element list.
+* When replacing a component, own its markup and behavior. Keep keyboard
+  access, focus, semantics, responsive behavior, and appearance modes intact.
+
+The [custom component examples](./theme-and-components.md#authoring-custom-components)
+show both a component root and a global style tree using these APIs.
+
+## Read the underlying references
+
+Cookbook's rules govern its integration and supported customization surfaces.
+Use the upstream references for syntax and color behavior. Upstream examples
+may configure standalone applications or other frameworks; keep Cookbook's
+imports, configuration, and rendering setup when adapting them.
+
+* [Tasty style rules for AI agents](./upstream/tasty/docs/ai-agents.md): concise
+  rules for values, state maps, tokens, selectors, and sub-elements.
+* [Tasty style DSL](./upstream/tasty/docs/dsl.md) and
+  [style properties](./upstream/tasty/docs/styles.md): syntax and property reference.
+* [Tasty methodology](./upstream/tasty/docs/methodology.md) and
+  [configuration](./upstream/tasty/docs/configuration.md): component design and shared settings.
+* [Glaze methodology](./upstream/glaze/docs/methodology.md): semantic palettes
+  and contrast relationships.
+* [Glaze API](./upstream/glaze/docs/api.md): color inputs, schemes, and contrast solving.
+
+## Documentation in the installed package
+
+The public `@tenphi/cookbook` package includes this guide and the rest of the
+Cookbook documentation in `docs/`. Its `docs/upstream/` directory contains
+generated Tasty and Glaze documentation snapshots, their READMEs, and licenses.
+`docs/upstream/manifest.json` records the source package versions and release
+references. These match the dependencies used to build that Cookbook release;
+consumer dependency overrides can change the installed runtime independently.
+
+In the packaged copies, links to available upstream reference pages point to
+these local snapshots. The Markdown references work offline. Links to source
+code and artwork absent from the npm packages point to their upstream release
+and still need internet access. The published website keeps its online links.
+
+Start at `node_modules/@tenphi/cookbook/docs/customization-rules.md`. When the
+package manager uses a different layout, resolve the exported documentation
+path from the consuming project:
+
+```sh
+node --input-type=module -e "console.log(import.meta.resolve('@tenphi/cookbook/docs/customization-rules.md'))"
+```
+
+Read the resolved file as Markdown; documentation exports are file references,
+not JavaScript modules. The snapshots are generated during Cookbook's build
+and packaging, with no network fetch or consumer installation hook.
+
+## Guide coding agents explicitly
+
+Having documentation installed does not ensure an agent reads it. Add a short
+instruction to your project's existing agent guidance, adjusting the path for
+the app that depends on Cookbook:
+
+```md
+Before customizing this Cookbook site, read
+node_modules/@tenphi/cookbook/docs/customization-rules.md and follow its linked
+Tasty and Glaze references. Inspect docs.config.ts and tasty.config.ts first.
+Use Cookbook's public styling APIs, semantic palette tokens, typography
+presets, and partial component overrides. Run the project's style lint,
+cookbook doctor, and build commands after changes.
+```
+
+## Check the result
+
+Adopt the [Cookbook Tasty lint configuration](./theme-and-components.md#linting-custom-styles)
+and extend its built-in vocabulary in `tasty.config.ts`:
+
+```ts
+export default { extends: "@tenphi/cookbook" };
+```
+
+Run the configured style linter, `cookbook doctor`, and the site build. The
+linter checks supported Tasty rules; it does not enforce every architectural
+rule above or inspect arbitrary CSS. Review custom components at mobile and
+desktop sizes, with keyboard navigation, in light and dark schemes, and with
+normal and high contrast.

package/docs/deployment.md

@@ -0,0 +1,78 @@
+---
+title: Deployment
+description: Build static output for GitHub Pages and other static hosts.
+sidebar:
+  order: 7
+---
+
+Cookbook always produces a static Astro build. The output in `dist/` can be
+served by GitHub Pages, Cloudflare Pages, Netlify, Vercel static hosting, or a
+plain file server.
+
+## Build locally
+
+```sh
+npm run build
+npm run preview
+```
+
+Run [`cookbook doctor`](./cli.md#validate-with-doctor) in CI before building
+when you want a focused content diagnostic step.
+
+## GitHub Pages
+
+Give the deployment workflow read access to the repository plus permission to
+write Pages and request an identity token:
+
+```yaml
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+```
+
+Build the site, upload `dist/` with the official Pages artifact action, and
+deploy it with the official Pages deploy action. Use GitHub's `github-pages`
+environment so the deployment URL and protection rules remain visible in the
+repository.
+
+For an organization or user site, keep Astro's `base: "/"`. For a project site
+served at `https://owner.github.io/repository/`, set Astro's
+`base: "/repository/"`; Cookbook derives the same base for its graph and
+assets.
+
+## Custom domains
+
+Set Cookbook's canonical site metadata to the HTTPS origin. The integration
+forwards it to Astro:
+
+```ts
+export default defineConfig({
+  integrations: [
+    cookbook({
+      config: {
+        site: { url: "https://docs.example.com" },
+      },
+    }),
+  ],
+});
+```
+
+Configure the custom domain in the repository's Pages settings and point DNS
+at the GitHub Pages host. For a custom Actions workflow, GitHub stores the
+domain in the Pages settings; a `CNAME` file in the artifact is ignored and is
+not required.
+
+This site is deployed by the repository's Pages workflow to
+`cookbook.tenphi.me` with HTTPS enforcement enabled.
+
+## Other static hosts
+
+Use the host's ordinary static-site settings:
+
+- build command: `npm run build`
+- publish directory: `dist`
+- Node.js: 22.14 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.

package/docs/examples.md

@@ -0,0 +1,95 @@
+---
+title: Working examples
+description: Complete configuration patterns for repositories, monorepos, npm content, and shared themes.
+sidebar:
+  order: 3
+---
+
+Each example uses the same Astro integration:
+
+```ts
+import { defineConfig } from "astro/config";
+import cookbook from "@tenphi/cookbook";
+
+export default defineConfig({ integrations: [cookbook()] });
+```
+
+## Local repository
+
+Put this in `docs.config.ts` at the repository root. README/docs discovery is
+automatic; add `content.sources` only when you need different routes or files.
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({ site: { title: "My library" } });
+```
+
+Run `cookbook doctor`, then `astro dev` or `astro build`.
+
+## Monorepo with two packages
+
+For an app in `apps/docs/`, resolve content from the repository, then give each
+source an ID, a root, and a route mount:
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  root: "../..",
+  site: { title: "SDK documentation" },
+  content: {
+    sources: [
+      { id: "api", root: "packages/api", glob: "**/*.md", routeBase: "/api" },
+      { id: "ui", root: "packages/ui", glob: "**/*.md", routeBase: "/ui" },
+    ],
+  },
+});
+```
+
+Use `source:ui/README.md` for an explicit link to the UI package. Ordinary relative
+links stay in their own source mount when the same file appears in several
+versions. A relative frontmatter slug is appended to that source's `routeBase`.
+
+## Locked npm documentation
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: { title: "Published API" },
+  content: {
+    sources: [{ id: "api", package: "@scope/package@^2", routeBase: "/api" }],
+  },
+});
+```
+
+Run `cookbook update` once, commit `cookbook.lock.json`, then run `cookbook doctor`
+and `astro build`. When changing `^2` to `^3`, run update again. A stale lock fails
+with instructions instead of rendering the old version.
+
+A package source can specify `registry` for an alternative registry. The default
+is the npm public registry. Keep credentials out of committed configuration.
+
+## Share configuration and themes
+
+A preset is an ordinary exported `DocsConfig` object:
+
+```ts
+import { defineDocsConfig, mergeDocsConfig } from "@tenphi/cookbook/config";
+
+const company = defineDocsConfig({
+  theme: { brand: "#315efb", tokens: { $radius: "8px" } },
+  markdown: { rawHtml: "sanitize" },
+});
+
+export default mergeDocsConfig(company, {
+  site: { title: "Product docs" },
+  theme: { tokens: { "$content-width": "52rem" } },
+});
+```
+
+Objects merge recursively, arrays replace, and inputs are not mutated. Tasty
+styles preserve their default values when adding conditional overrides. A preset
+can live in a shared workspace package. Component overrides remain partial Tasty
+objects and merge into Cookbook's complete base styles inside the renderer.

package/docs/getting-started.md

@@ -0,0 +1,124 @@
+---
+title: Getting started
+description: Start a documentation site, document an existing repository, or use a published npm package.
+sidebar:
+  order: 2
+---
+
+Cookbook requires Node.js 22.14 or newer.
+
+## Create your first site
+
+```sh
+npm create @tenphi/cookbook@latest my-docs -- --yes
+cd my-docs
+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
+`docs/guide.md` to create `/guide`. New and edited pages appear in the development
+server without a restart.
+
+## Document an existing repository
+
+Run this from your repository root:
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+cd docs-site
+npm run dev
+```
+
+The generated `docs.config.ts` points back to your repository. Your root README
+becomes the home page and `docs/**/*.{md,mdx}` supplies the other pages. Cookbook
+reads those files without copying or rewriting them.
+
+Use `--no-install` to generate files before installing dependencies. The creator
+refuses to overwrite a non-empty destination in non-interactive mode.
+
+## Document a published npm package
+
+```sh
+npm create @tenphi/cookbook@latest my-package-docs -- \
+  --package @scope/package@latest --yes
+cd my-package-docs
+npm run dev
+```
+
+The creator discovers documentation inside the actual published artifact and
+writes its exact version and integrity to `cookbook.lock.json`. Commit this file.
+The documented package is not installed and its lifecycle scripts do not run.
+Run `npm run update` when you want to resolve the requested tag or range again.
+
+## Add to an existing Astro project
+
+```sh
+npx astro add @tenphi/cookbook
+```
+
+Your Astro configuration needs one integration:
+
+```ts
+import { defineConfig } from "astro/config";
+import cookbook from "@tenphi/cookbook";
+
+export default defineConfig({ integrations: [cookbook()] });
+```
+
+Cookbook includes Starlight and discovers `docs.config.ts` automatically.
+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.
+
+Create `docs.config.ts` next to `astro.config.ts`:
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: {
+    title: "Example Project",
+    description: "Documentation for Example Project",
+    repository: "https://github.com/example/project",
+  },
+  theme: { brand: "#2f5bff" },
+});
+```
+
+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.
+Use `cookbook({ configFile: "./config/manual.ts" })` and
+`cookbook doctor --config ./config/manual.ts` for a nonstandard location.
+
+## Monorepo roots
+
+An app in `apps/docs/` can use repository content with:
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({ root: "../.." });
+```
+
+`root` is relative to the documentation configuration file. It controls content,
+local assets, and `cookbook.lock.json`. Run `npm run doctor` from the app directory;
+it resolves the same repository root as the integration. Individual sources can
+also declare their own roots for multi-package sites.
+
+## Validate and publish
+
+```sh
+npm run doctor
+npm run build
+npm run preview
+```
+
+See [working examples](./examples.md), [authoring components](./authoring.mdx),
+and [deployment](./deployment.md). Existing users should read the
+[prerelease migration guide](./migration.md).

package/docs/index.md

@@ -0,0 +1,74 @@
+---
+title: Cookbook
+description: Build a polished static documentation site from the Markdown your project already owns.
+template: splash
+hero:
+  title: Documentation that stays with the code.
+  tagline: Turn repository Markdown or a locked npm package into a polished, searchable Astro site—without creating a second source of truth.
+  image:
+    html: '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="240" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="14" fill="currentColor"/><path fill="#fff" d="M14.8 16c6.7.2 12.3 2 16.7 5.4v28.4c-4.4-3.1-10-4.7-16.6-4.9a3 3 0 0 1-2.9-3V19a3 3 0 0 1 2.8-3Z"/><path fill="#fff" d="M49.2 16c-6.7.2-12.3 2-16.7 5.4v28.4c4.4-3.1 10-4.7 16.6-4.9a3 3 0 0 0 2.9-3V19a3 3 0 0 0-2.8-3Z"/></svg>'
+  actions:
+    - text: Get started
+      link: /getting-started/
+      variant: primary
+    - text: See how it compares
+      link: /starlight-comparison/
+      variant: secondary
+sidebar:
+  order: 1
+---
+## Keep documentation close to its source
+
+Cookbook combines [Astro](https://astro.build) and
+[Starlight](https://starlight.astro.build) with repository-aware content,
+strict validation, local Pagefind search, and a theme powered by
+[Tasty](./upstream/tasty/README.md) and [Glaze](./upstream/glaze/README.md).
+
+### Repository-native
+
+Keep `README.md`, `docs/`, and local assets where they already live. Cookbook
+transforms sources in memory and never rewrites them.
+
+### Package-first
+
+Build a reproducible site from the files actually published to npm—without
+cloning the package repository or running its lifecycle scripts.
+
+### Strict and static
+
+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.
+
+## Choose a path
+
+Create a documentation project from a published npm package:
+
+```sh
+npm create @tenphi/cookbook@latest my-package-docs -- --package your-package
+```
+
+Or add the complete integration to an Astro project:
+
+```sh
+npx astro add @tenphi/cookbook
+```
+
+Continue with [Getting started](./getting-started.md), then learn how
+[content sources](./content-sources.md) become routes.
+
+## See the product, not a mock-up
+
+The pages you are reading live in this repository's root `docs/` directory.
+The small Astro app under `apps/reference` points the integration at the
+repository root, validates this content through the same graph-backed route
+pipeline used by consumer sites, builds the site, and publishes the result to
+GitHub Pages. There is no copied documentation tree.
+
+This homepage also uses Cookbook's public `template: splash` and `hero`
+frontmatter. The heading permalinks, code-copy controls, edit links, and Git
+timestamps throughout the guide are the same capabilities available to every
+Cookbook site.
+
+See [Architecture](./architecture.md) for the package boundaries behind the
+site.

package/docs/migration.md

@@ -0,0 +1,36 @@
+---
+title: Prerelease migration
+description: Upgrade to the shared configuration, source identity, and typed customization APIs.
+sidebar:
+  order: 9
+---
+
+This prerelease intentionally tightens several contracts.
+
+- Move generated inline documentation configuration to `docs.config.ts` and use
+  `cookbook()` in Astro. Existing explicit `cookbook({ config })` remains valid,
+  but CLI commands read the shared configuration file.
+- For nested Astro apps, put `root: "../.."` in `docs.config.ts`; paths resolve
+  relative to that file. Individual sources may now specify `root` and `id`.
+- Run `cookbook update` after changing a requested npm specifier. A lock for
+  another range or tag is no longer accepted by package name alone.
+- `rawHtml: "sanitize"` preserves safe HTML and removes executable markup and
+  presentational attributes. Use `"strip"` for the former removal behavior;
+  removal now emits a diagnostic. `"reject"` still fails validation.
+- Unrecognized page frontmatter is kept in graph entry `metadata`. Use
+  `content.frontmatter: "reject"` for the former strict behavior. Cookbook's
+  recognized fields retain their validation.
+- `slug` is now relative to the source mount, including when it starts with `/`.
+  Use a separate source mount for an unrelated public route.
+- Repeated files in separate source declarations create separate entries.
+  Give mounts stable IDs and use `source:<id>/<source-path>` for explicit links.
+  `entryBySource(path)` returns `undefined` for an ambiguous path; pass a source
+  ID as its second argument. Graph entry IDs include the source ID.
+- Unknown names in `theme.styles` are errors. Register user-authored component
+  styles in `theme.customStyles`. Built-in component names and sub-elements
+  provide strict editor checking; style objects still contain only overrides.
+- `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.

package/docs/starlight-comparison.md

@@ -0,0 +1,124 @@
+---
+title: Cookbook and Starlight
+description: Understand which Starlight authoring conventions Cookbook preserves and where its repository and theme model differs.
+sidebar:
+  order: 5
+---
+Cookbook uses [Astro Starlight](https://starlight.astro.build/) as its
+documentation shell. It keeps familiar page-authoring conventions while adding
+repository and npm content sources, stricter validation, and a Tasty/Glaze
+theme model.
+
+## Cookbook or Starlight?
+
+Start with the place where the documentation must live. Starlight is a strong
+choice when an Astro site owns its content. Cookbook is designed for projects
+where the repository Markdown—or the documentation actually published in an
+npm package—must remain the source of truth.
+
+| Concern                 | Starlight                                                                          | Cookbook                                                                                                                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Starting point          | Add Starlight to an Astro project and author its documentation content collection. | Add one integration to an Astro project, or generate a complete site directly from a published npm package.                                                                           |
+| Content ownership       | The documentation site conventionally owns its Markdown under `src/content/docs/`. | Reads `README.md`, repository `docs/` trees, files outside the Astro app, and selected files from npm artifacts without copying or rewriting them.                                    |
+| Reproducible releases   | Follows the dependencies and content committed with the site.                      | Can lock an npm package to its exact resolved version and integrity, then rebuild from the files users actually receive.                                                              |
+| Build guarantees        | Provides Starlight's content schema and Astro build pipeline.                      | Adds strict checks for duplicate routes, broken links, missing assets, unsafe paths, and invalid navigation with source-aware diagnostics.                                            |
+| Design system           | Supports CSS variables, custom CSS, and component overrides.                       | Exposes the full [Tasty styling DSL](./upstream/tasty/docs/dsl.md) through configuration, with Glaze-generated semantic colors and named style trees for Cookbook and shell surfaces. |
+| Familiar authoring      | Defines the Starlight page, navigation, i18n, and frontmatter conventions.         | Preserves those conventions—including splash pages, locales, edit links, and last-updated metadata—while resolving them against each original source.                                 |
+| Structural escape hatch | Replaces Starlight components when markup or behavior must change.                 | Supports Astro component overrides for structural changes; visual changes normally stay in typed `theme` configuration.                                                               |
+
+Choose Starlight when the documentation site is the natural home for the
+content and its CSS-oriented customization model fits the project. Choose
+Cookbook when documentation must stay beside the code, match a published
+package, fail strictly when references drift, or expose a reusable design
+system entirely through configuration.
+
+## Customize with Tasty's DSL
+
+Cookbook customization is not limited to replacing token values. Every entry
+under `theme.styles` is a partial Tasty style object that Cookbook merges into
+the component's base style tree. That gives configuration access to the same
+responsive values, state maps, calculations, semantic tokens, typography
+presets, and named sub-elements used by Cookbook itself:
+
+```ts
+export default defineDocsConfig({
+  theme: {
+    states: {
+      "@touch": "@media(pointer: coarse)",
+    },
+    styles: {
+      MarkdownCodeBlock: {
+        Pre: {
+          padding: {
+            "": "2x 4x",
+            "@mobile": "1.5x 3x",
+          },
+          radius: "$card-radius",
+        },
+        CopyButton: {
+          inlineSize: {
+            "": "2rem",
+            "@touch": "2.5rem",
+          },
+          scale: {
+            "": "1",
+            ":active": "0.94",
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+The user supplies only overrides; the merge happens inside Cookbook. See
+[Theme and components](./theme-and-components.md#style-customization) for the
+complete component and sub-element inventory, and the
+[Tasty documentation](./upstream/tasty/docs/README.md) for the DSL's properties and
+conditional syntax. Structural Astro overrides remain available when a change
+requires different markup or behavior rather than styling.
+
+## Configure the shared capabilities
+
+```ts
+export default defineDocsConfig({
+  editLink: {
+    baseUrl: "https://github.com/example/project/edit/main/",
+  },
+  lastUpdated: true,
+  locales: {
+    root: { label: "English", lang: "en" },
+    fr: { label: "Français", lang: "fr" },
+  },
+  defaultLocale: "root",
+});
+```
+
+The keys deliberately match Starlight so an existing Starlight author does not
+need to relearn page metadata or i18n. Cookbook resolves edit and Git metadata
+before handing each page to Starlight because its source may live in a root
+`docs/` directory, outside the Astro app, or inside a locked npm artifact.
+
+## Create a splash page
+
+```yaml
+---
+title: Example
+template: splash
+hero:
+  title: Build something clear.
+  tagline: A short explanation of the value your project provides.
+  actions:
+    - text: Get started
+      link: /getting-started/
+      variant: primary
+    - text: View API
+      link: /reference/
+      variant: secondary
+---
+```
+
+Use `template: doc` (the default) for conventional reference pages. See
+Starlight's [page guide](https://starlight.astro.build/guides/pages/) for the
+authoring model Cookbook builds on, then use [Theme and
+components](./theme-and-components.md) for Cookbook-specific styling.