@tenphi/cookbook 0.27.0 → 0.30.0

package/docs/custom-components.md

@@ -2,11 +2,11 @@
 title: Custom components
 description: Style your Astro and MDX components with Tasty and validate their tokens and parts.
 ---
-Use this guide after [theme configuration](./theme-and-components.md) when you
-need markup beyond Cookbook's built-in surfaces. For ordinary visual changes,
-consult the [component styles](./component-styles.md) reference first.
+Use this guide when you need markup beyond Cookbook's built-in surfaces. For
+ordinary visual changes, start with the [theme guide](./theme-and-components.md)
+and the [component styles](./component-styles.md) reference.
 
-## Authoring custom components
+## Styling exports
 
 Import styling tools from `@tenphi/cookbook/styling`. They use the same Tasty
 runtime as Cookbook, with its semantic colors, typography presets, units, and
@@ -31,13 +31,13 @@ is needed for static components. Set shared tokens, presets, and states in
 modules; configuration files should import `defineDocsConfig()` from
 `@tenphi/cookbook/config`.
 
-### A small named component
+## Define a named component
 
 For a component used by your pages, give its root a name and define its parts
 inside the same style object:
 
 ```ts
-// src/components/StatusBadge.ts
+// docs/components/StatusBadge.ts
 import { defineComponent } from "@tenphi/cookbook/styling";
 
 export const StatusBadge = defineComponent("StatusBadge", {
@@ -45,7 +45,7 @@ export const StatusBadge = defineComponent("StatusBadge", {
   styles: {
     display: "inline-flex",
     padding: "0.5x 1x",
-    radius: "$radius",
+    radius: "1r",
     fill: "#surface-2",
     color: "#text",
     preset: "small",
@@ -69,158 +69,6 @@ theme: {
 merges it with the base styles while rendering on the server. Document the
 root name and every named part when sharing a custom component.
 
-### A shared site logo
-
-Set `site.logo` once to use your artwork in the header and mobile drawer:
-
-```ts
-site: {
-  title: "Acme",
-  logo: "./assets/acme.svg"
-}
-```
-
-Paths are local files relative to the resolved project root, just like
-`site.favicon`. Cookbook reads the intrinsic dimensions and copies the image to
-a content-hashed URL under the deployment base. SVG, PNG, JPEG, WebP, AVIF, and
-GIF are supported. Missing or invalid files fail during setup.
-
-```ts
-site: {
-  title: "Acme",
-  logo: {
-    light: "./assets/acme-light.svg",
-    dark: "./assets/acme-dark.svg",
-    alt: "Acme documentation",
-    href: "/",
-    decorative: true
-  },
-  favicon: "./assets/acme-icon.svg"
-}
-```
-
-Use `src` for one image, or both `light` and `dark`. Variants follow the
-appearance control and the system preference in Auto mode. They must share an
-aspect ratio to prevent layout shifts. Optional `width` and `height` describe
-intrinsic dimensions; Tasty controls display size. Customize
-`theme.styles.SiteLogo` and its complete anatomy: `Image`, `Light`, and `Dark`.
-Wide wordmarks retain their proportions within the header.
-
-The logo is decorative by default because the neighboring title labels the
-site. Set `decorative: false` and `alt` when the image itself carries meaningful
-text. The header logo link still has a name when the image is decorative.
-`href` defaults to the localized documentation home; it accepts a root-relative
-documentation route or HTTP(S) destination. The header title and drawer use the
-same destination. `site.logo: false` removes the mark from both locations.
-
-A logo does not change the favicon or touch icons. Configure `site.favicon`
-separately for square artwork; the default Cookbook icon set remains in place
-until changed. `Logo` remains available as the standalone Cookbook book mark.
-
-The built-in mark uses `theme.palette["logo-surface"]` and `theme.palette["logo-mark"]`.
-The default homepage hero artwork also uses `logo-surface` for its brand fill.
-Both default to Glaze `mode: "fixed"`: the brand background and light book keep
-their polarity in dark mode while respecting Glaze's tone boundaries and
-high-contrast settings. The mark-to-background contrast floor is 3:1 normally
-and 4.5:1 in high contrast. These colors are separate from interactive accents.
-For example, to customize the logo background while retaining brand hue:
-
-```ts
-theme: {
-  brand: { from: "#315efb" },
-  palette: {
-    "logo-surface": {
-      base: "logo-mark",
-      tone: 40,
-      saturation: 0.8,
-      mode: "fixed",
-      contrast: { wcag: [3, 4.5] },
-    },
-    "logo-mark": { tone: 100, saturation: 0, mode: "fixed" },
-  },
-}
-```
-
-Custom image assets keep their authored colors; use `light`/`dark` files when
-you want distinct artwork. Header and drawer home links center logos with the
-site title regardless of their aspect ratio. Use `theme.styles.SiteLogo` for
-image size and `theme.styles.Header.SiteTitle` / `Sidebar.HomeLink`
-for typography; they do not need baseline offsets for a different preset.
-
-### Advanced site title markup
-
-To put your own logo and title in one home link, create
-`docs/components/site-title.ts`:
-
-```ts
-import { defineComponent } from "@tenphi/cookbook/styling";
-
-export const SiteTitleRoot = defineComponent("ProjectSiteTitle", {
-  as: "a",
-  styles: {
-    display: "flex",
-    alignItems: "center",
-    gap: "1x",
-    inlineSize: "min 0",
-    color: "#text",
-    preset: { "": "h4 / strong", "!@md": "h5 / strong" },
-    textDecoration: "none",
-    Logo: {
-      $: "> svg",
-      display: "block",
-      flexShrink: "0",
-      inlineSize: { "": "2rem", "!@md": "1.75rem" },
-      blockSize: { "": "2rem", "!@md": "1.75rem" },
-      color: "#accent-text",
-    },
-    Label: {
-      $: "> span",
-      inlineSize: "min 0",
-      overflow: "hidden",
-      textOverflow: "ellipsis",
-      whiteSpace: "nowrap",
-    },
-  },
-});
-```
-
-Then create `docs/components/SiteTitle.astro`, using an SVG whose paths use
-`currentColor` to follow the semantic accent color:
-
-```astro
----
-import ProjectLogo from "../../public/logo.svg";
-import { SiteTitleRoot } from "./site-title.js";
-
-const { siteTitle, siteTitleHref } = Astro.locals.cookbookRoute;
----
-
-<SiteTitleRoot href={siteTitleHref}>
-  <ProjectLogo aria-hidden="true" focusable="false" />
-  <span translate="no">{siteTitle}</span>
-</SiteTitleRoot>
-```
-
-Register the replacement in `docs.config.ts` and disable the shared mark.
-A `SiteTitle` override affects the header; use `site.logo` above for ordinary
-branding shared with the drawer. For custom drawer markup, override `Sidebar`.
-The custom component supports root styles plus its complete list of named
-sub-elements: `Logo` and `Label`.
-
-```ts
-site: { logo: false },
-components: {
-  overrides: {
-    SiteTitle: "./docs/components/SiteTitle.astro"
-  }
-},
-theme: {
-  customStyles: {
-    ProjectSiteTitle: { Logo: { color: "#text" } }
-  }
-}
-```
-
 `defineComponent(name, options)` accepts Tasty factory options and a name for
 `theme.customStyles[name]`. It merges the configured partial style object before
 creating the component, retaining the other base properties and responsive
@@ -238,7 +86,7 @@ and named sub-elements for owned anatomy, and modifiers/state maps for variants.
 Root selectors may keep stable classes, such as `.project-note`, or use
 `data-component`; avoid classes for sub-elements and modifiers.
 
-### Extending a component
+## Extend a component
 
 Use `extendComponent(name, base, options)` to inherit an existing Tasty
 component's styles, props, variants, and compound parts:
@@ -250,9 +98,12 @@ export const ProjectButton = extendComponent("ProjectButton", Button, {
   type: "button",
   styles: {
     padding: "1x 2x",
-    radius: "$radius",
-    fill: "#surface",
-    Hover: { $: "&:hover", fill: "#surface-2-hover" },
+    radius: "1r",
+    fill: {
+      "": "#surface-2",
+      ":hover": "#surface-2-hover",
+      ":active": "#surface-2-pressed",
+    },
   },
 });
 
@@ -263,8 +114,8 @@ export const CompactButton = extendComponent("CompactButton", ProjectButton, {
 
 `theme.styles.Button` customizes the shared foundation, including Cookbook's
 search and mobile-menu buttons. `theme.customStyles.ProjectButton` and
-`CompactButton` customize each derived component independently. `Button` has
-no named sub-elements; this example adds `Hover` to both descendants.
+`CompactButton` customize each derived component independently. This example
+adds a hover fill to both descendants.
 
 The merge order is the base component's configured styles and selected variant,
 the extension's styles, its named theme override, and styles passed while
@@ -281,7 +132,7 @@ type. To compose reusable style fragments without a component base, use
 `mergeStyles(baseStyles, extensionStyles)`; a shallow spread replaces entire
 nested sub-elements and state maps.
 
-### Global style trees
+## Global style trees
 
 For markup you do not render through a Tasty component, call
 `useGlobalStyles()` during rendering. For example, this Astro component
@@ -310,6 +161,85 @@ useGlobalStyles(
 `defineComponent`, `extendComponent`, and `resolveComponentStyles` read the same `theme.customStyles`
 configuration; user configuration contains only the properties to change. Each custom style name must match a call to one of these helpers.
 
+## Replace built-in markup
+
+When the built-in markup does not fit, replace an Astro component through
+`components.overrides`; see the [list of override names](./configuration.md#components).
+An override owns its markup and behavior. For ordinary branding, configure
+[`site.logo`](./theme-and-components.md#logo-and-favicon) instead.
+
+For example, to put your own logo and title in one home link, create
+`docs/components/site-title.ts`:
+
+```ts
+import { defineComponent } from "@tenphi/cookbook/styling";
+
+export const SiteTitleRoot = defineComponent("ProjectSiteTitle", {
+  as: "a",
+  styles: {
+    display: "flex",
+    alignItems: "center",
+    gap: "1x",
+    inlineSize: "min 0",
+    color: "#text",
+    preset: { "": "h4 / strong", "!@md": "h5 / strong" },
+    textDecoration: "none",
+    Logo: {
+      $: "> svg",
+      display: "block",
+      flexShrink: "0",
+      inlineSize: { "": "2rem", "!@md": "1.75rem" },
+      blockSize: { "": "2rem", "!@md": "1.75rem" },
+      color: "#accent-text",
+    },
+    Label: {
+      $: "> span",
+      inlineSize: "min 0",
+      overflow: "hidden",
+      textOverflow: "ellipsis",
+      whiteSpace: "nowrap",
+    },
+  },
+});
+```
+
+Then create `docs/components/SiteTitle.astro`, using an SVG whose paths use
+`currentColor` to follow the semantic accent color:
+
+```astro
+---
+import ProjectLogo from "../../public/logo.svg";
+import { SiteTitleRoot } from "./site-title.js";
+
+const { siteTitle, siteTitleHref } = Astro.locals.cookbookRoute;
+---
+
+<SiteTitleRoot href={siteTitleHref}>
+  <ProjectLogo aria-hidden="true" focusable="false" />
+  <span translate="no">{siteTitle}</span>
+</SiteTitleRoot>
+```
+
+Register the replacement in `docs.config.ts` and disable the shared mark.
+A `SiteTitle` override affects the header; `site.logo` covers ordinary branding
+shared with the drawer. For custom drawer markup, override `Sidebar`.
+The custom component supports root styles plus its complete list of named
+sub-elements: `Logo` and `Label`.
+
+```ts
+site: { logo: false },
+components: {
+  overrides: {
+    SiteTitle: "./docs/components/SiteTitle.astro"
+  }
+},
+theme: {
+  customStyles: {
+    ProjectSiteTitle: { Logo: { color: "#text" } }
+  }
+}
+```
+
 ## Linting custom styles
 
 `@tenphi/cookbook/eslint-plugin` re-exports the Tasty ESLint plugin together with
@@ -329,10 +259,12 @@ export default {
 Renderer-only consumers can use `extends: "@tenphi/renderer"` instead.
 The preset registers both Cookbook styling import paths, its built-in tokens,
 units, responsive states, and typography presets. It also describes
-`defineComponent`, `extendComponent`, `resolveComponentStyles`, and `mergeStyles`, so their inline
+`defineComponent`, `extendComponent`, and `resolveComponentStyles`, so their inline
 style objects, variants, and named sub-elements receive the same checks as
-`tasty()` calls. Partial overrides passed to `mergeStyles` may omit default state
-values and retain the plugin's safeguards against fixes that replace base styles.
+`tasty()` calls. The upstream plugin recognizes `mergeStyles` directly: its first
+argument is a base style object, and later arguments are partial overrides that
+may omit default state values and retain the safeguards against fixes that replace
+base styles.
 
 ### ESLint
 
@@ -406,6 +338,22 @@ export default {
 `extends` merges and deduplicates these arrays with the inherited configuration,
 so list only your additions. It also inherits the styling helper signatures;
 entries you add to `styleFunctions` override inherited signatures by function name.
+
+To keep the list in sync with the theme automatically, build the validation
+configuration from `docs.config.ts` instead:
+
+```ts
+// tasty.config.ts
+import { createValidationConfig } from "@tenphi/cookbook/eslint-plugin";
+import docs from "./docs.config";
+
+export default createValidationConfig(docs.theme);
+```
+
+`createValidationConfig(theme)` adds the theme's tokens, palette colors (as
+`#name` tokens), units, states, presets, and recipes to Cookbook's built-in
+vocabulary.
+
 The exported `validationConfig` object remains available for programmatic use.
 The entry point also exports the upstream `StyleFunctionConfig` and
 `ResolvedConfig` types for shared lint configurations. Additional imported

package/docs/customization-rules.md

@@ -11,24 +11,28 @@ registries or internal helpers.
 
 ## Read the configuration first
 
-Inspect `docs.config.ts`, `tasty.config.ts`, and the components you are changing.
+Inspect `docs.config.ts`, `tasty.config.ts` (when the project has adopted style
+linting), 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](./component-styles.md#style-customization)
+[component anatomy reference](./component-styles.md#complete-component-anatomy)
 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`                                         |
-| Font loading and family roles | `theme.fonts`                                          |
-| 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   |
+| Change                                  | Supported surface                                      |
+| --------------------------------------- | ------------------------------------------------------ |
+| 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`                                          |
+| Font delivery and caching               | `theme.fontLoading`                                    |
+| Typography                              | `theme.presets`                                        |
+| Responsive conditions                   | `theme.states`                                         |
+| Glaze adaptation                        | `theme.glaze` and `theme.contrastLevel`                |
+| Custom units and reusable style bundles | `theme.units` and `theme.recipes`                      |
+| 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
@@ -89,7 +93,7 @@ belong in `docs.config.ts`.
 * When replacing a component, own its markup and behavior. Keep keyboard
   access, focus, semantics, responsive behavior, and appearance modes intact.
 
-The [custom component examples](./custom-components.md#authoring-custom-components)
+The [custom component examples](./custom-components.md)
 show both a component root and a global style tree using these APIs.
 
 ## Read the underlying references
@@ -144,7 +148,8 @@ 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.
+Tasty and Glaze references. Inspect docs.config.ts (and tasty.config.ts, if
+present) 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.
@@ -159,6 +164,10 @@ and extend its built-in vocabulary in `tasty.config.ts`:
 export default { extends: "@tenphi/cookbook" };
 ```
 
+To derive your theme's names automatically, use
+[`createValidationConfig(docs.theme)`](./custom-components.md#custom-theme-names)
+instead.
+
 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

package/docs/deployment.md

@@ -16,66 +16,116 @@ npm run validate
 npm run preview
 ```
 
-New projects include `validate`: preflight, production build, then built-output
-checks. Existing projects can add this script using the [upgrade guide](./migration.md).
-Run [`cookbook doctor`](./cli.md#validate-with-doctor) for a focused preflight.
+New projects include `validate`: type checking, preflight, production build,
+then built-output checks. Existing projects can add
+`"validate": "tsc --noEmit && cookbook doctor && astro build && cookbook check-build"`
+to their `package.json` scripts. Run [`cookbook doctor`](./cli.md#validate-with-doctor)
+alone for a faster preflight.
+
+## Public URL and base path
+
+Set `site.url` in `docs.config.ts` to the site's public HTTPS origin, such as
+`https://docs.example.com`. A production build then gives every page a
+canonical URL and creates a sitemap. Cookbook forwards the value to Astro's
+`site`; if `astro.config.ts` also sets `site`, the two must match.
+
+When the host serves the site below a path, such as
+`https://owner.github.io/repository/`, set Astro's `base: "/repository/"` in
+`astro.config.ts`. Cookbook derives its routes and assets from Astro's `base`,
+so do not repeat the path in `docs.config.ts` routes.
+
+Page URLs follow Astro's `trailingSlash` and `build.format`. The default
+directory output writes `guide/index.html`, so links, canonicals, and `llms.txt`
+use `/guide/`. `build.format: "file"` writes `guide.html` and uses `/guide`,
+while the home remains the directory index at the base. `trailingSlash` set to
+`"always"` or `"never"` overrides both. Either way, readers follow the URL the
+host serves directly instead of a redirect.
 
 ## GitHub Pages
 
-Give the deployment workflow read access to the repository plus permission to
-write Pages and request an identity token:
+Create the project with `--deploy github-pages` to generate a GitHub Actions
+workflow. For an app at the root of its repository, the creator writes
+`.github/workflows/deploy.yml`. With npm, the workflow looks like this:
 
 ```yaml
+name: Deploy documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
 permissions:
+  actions: read
   contents: read
   pages: write
   id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run validate
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
 ```
 
-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.
+In the repository's Pages settings, select **GitHub Actions** as the source.
+The `github-pages` environment keeps the deployment URL and protection rules
+visible in the repository.
+
+GitHub runs workflows only from the repository root's `.github/workflows/`.
+When the app is created inside an existing Git repository, such as
+`docs-site/` after `--source .`, the creator writes
+`.github/workflows/deploy-docs.yml` at the repository root instead. That
+workflow runs its commands in `docs-site`, caches dependencies from the app's
+lockfile, and uploads `docs-site/dist`. The creator does not overwrite an
+existing `deploy-docs.yml`; it stops before writing any files.
 
 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.
-
-Page URLs follow Astro's `trailingSlash` and `build.format`. The default
-directory output writes `guide/index.html`, so links, canonicals, and `llms.txt`
-use `/guide/`. `build.format: "file"` writes `guide.html` and uses `/guide`,
-while the home remains the directory index at the base. `trailingSlash` set to
-`"always"` or `"never"` overrides both. Either way, readers follow the URL the
-host serves directly instead of a redirect.
+`base: "/repository/"`.
 
-## Custom domains
+### Custom domains
 
-Set Cookbook's canonical site metadata to the HTTPS origin. The integration
-forwards it to Astro:
+Set `site.url` to the custom HTTPS origin:
 
 ```ts
-export default defineConfig({
-  integrations: [
-    cookbook({
-      config: {
-        site: { url: "https://docs.example.com" },
-      },
-    }),
-  ],
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: { title: "Example", 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.
-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.
+not required. A custom domain serves the site at the origin root, so keep
+Astro's `base: "/"`.
 
 ## Other static hosts
 
@@ -90,30 +140,28 @@ gets `netlify.toml`. You can also use the host's ordinary static-site settings:
 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.
+## Discovery files
 
-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.
+The build emits `llms.txt` with links to published documentation pages and,
+when `site.url` is set, a sitemap. At an origin root with `site.url` set, it
+also 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.
 
-For title templates, social images, preview noindex, older-version policies,
-breadcrumbs, and copy-page downloads, see [Publishing metadata](./publishing.md).
+See [Publishing metadata](./publishing.md) for title templates, social images,
+preview noindex, older-version policies, breadcrumbs, and Markdown downloads,
+and [AI agents](./ai-agents.md) for how agents read the published site.
 
 ## Validate the published result
 
-New projects include `npm run validate` for preflight, build, and output checks.
-After the host finishes deploying, run:
+After the host finishes deploying, check the deployment against the same local
+`dist/` output that was uploaded:
 
 ```sh
 npx @tenphi/cookbook check-build --url https://docs.example.com/manual/
 ```
 
-Use your actual deployment URL, including any base path, and the same local
-`dist/` output that was deployed. See [CLI checks](./cli.md#check-the-built-site-and-deployment)
-for the exact coverage, warnings, JSON output, and custom output directories.
+Use your actual deployment URL, including any base path. Then check the
+deployed HTML, `sitemap-index.xml`, and `llms.txt` through their public URLs.
+See [CLI checks](./cli.md#check-the-built-site-and-deployment) for the exact
+coverage, warnings, JSON output, and custom output directories.

package/docs/es/getting-started.md

@@ -63,8 +63,6 @@ Cookbook incluye su renderizador Astro y detecta `docs.config.ts` automáticamen
 
 ## Configura el sitio
 
-Empieza con las [recetas completas de marca, logotipo y fuentes](../recipes.md). Para cambios de estilo más detallados o componentes nuevos, consulta las [reglas de personalización](../customization-rules.md). Estas reglas y las referencias originales también se incluyen en el paquete instalado de Cookbook.
-
 Crea `docs.config.ts` junto a `astro.config.ts`:
 
 ```ts
@@ -83,9 +81,11 @@ export default defineDocsConfig({
 });
 ```
 
-Cambia `theme.fonts` para usar [Google Fonts por nombre o tus propios archivos de fuentes](../fonts-and-typography.md). Usa `theme.presets` para los detalles tipográficos, `theme.styles` para los elementos integrados y `defineComponent()` con `theme.customStyles` para añadir elementos. La [guía del tema](../theme-and-components.md) es un punto de partida; la [referencia de estilos de componentes](../component-styles.md) enumera todas las partes personalizables.
+Cambia `theme.fonts` para usar [Google Fonts por nombre o tus propios archivos de fuentes](../fonts-and-typography.md#change-font-families). Usa `theme.presets` para los detalles tipográficos, `theme.styles` para los elementos integrados y `defineComponent()` con `theme.customStyles` para añadir elementos. La [guía del tema](../theme-and-components.md) es un punto de partida; la [referencia de estilos de componentes](../component-styles.md) enumera todas las partes personalizables.
+
+Para partir de una configuración completa, consulta las [recetas de marca, logotipo y fuentes](../recipes.md). Para cambios de estilo más detallados o componentes nuevos, consulta las [reglas de personalización](../customization-rules.md). Estas reglas y las referencias originales también se incluyen en el paquete instalado de Cookbook.
 
-La integración y la CLI cargan la misma configuración. Se admiten `docs.config.ts`, `.mts`, `.js` y `.mjs`, en ese orden. Un objeto `config` explícito en la integración tiene prioridad; `configFile: false` desactiva la detección. Usa `cookbook({ configFile: "./config/manual.ts" })` y `cookbook doctor --config ./config/manual.ts` para una ubicación no estándar.
+La integración y la CLI cargan la misma configuración. Se admiten `docs.config.ts`, `.mts`, `.js` y `.mjs`, en ese orden. Un objeto `config` explícito en la integración tiene prioridad; `configFile: false` desactiva la detección. Usa `cookbook({ configFile: "./config/manual.ts" })` y `cookbook doctor --config ./config/manual.ts` para una ubicación no estándar. Como `root` se resuelve desde el directorio del archivo de configuración, ese archivo necesita `root: ".."` para seguir leyendo `README.md` y `docs/` desde el directorio de la aplicación.
 
 ## Raíces de monorepositorios
 
@@ -106,4 +106,6 @@ npm run validate
 npm run preview
 ```
 
-El resto de las guías se encuentra actualmente en inglés: [ejemplos](../examples.md), [componentes para redactar](../authoring.mdx), [flujo para agentes de IA](../ai-agents.md), [despliegue](../deployment.md) y [actualización entre versiones](../migration.md). Puedes partir de las [recetas](../recipes.md) para adaptar una configuración completa. Si falla la validación, consulta [solución de problemas](../troubleshooting.md).
+`validate` comprueba los tipos del proyecto, ejecuta la verificación previa de Cookbook, compila el sitio y revisa el resultado. En un proyecto que configuraste tú mismo, añade los scripts de los [comandos de la CLI](../cli.md) o ejecuta `npx @tenphi/cookbook doctor`.
+
+El resto de las guías se encuentra actualmente en inglés: [ejemplos](../examples.md), [componentes para redactar](../authoring.mdx), [flujo para agentes de IA](../ai-agents.md), [despliegue](../deployment.md) y [actualización entre versiones](../migration.md). Si falla la validación, consulta [solución de problemas](../troubleshooting.md).