@tenphi/cookbook 0.15.0 → 0.17.0

package/docs/content-sources.md

@@ -0,0 +1,178 @@
+---
+title: Content sources
+description: Collect local files, OpenAPI specs, and locked npm package documentation into one route graph.
+sidebar:
+  order: 3
+---
+
+Cookbook first collects every source and assigns each one a canonical route.
+Only then does it rewrite links and assets. That two-phase graph lets pages
+link across directories and source declarations without depending on discovery
+order.
+
+## Convention mode
+
+When `content.sources` is omitted, Cookbook includes these sources when they
+exist:
+
+```ts
+[
+  { file: "README.md", route: "/" },
+  { glob: "docs/**/*.{md,mdx}", base: "docs" },
+];
+```
+
+Files or directories beginning with `_` are excluded from glob discovery.
+Explicit `content.sources` replace these conventions.
+
+## Local files
+
+Use a file declaration for a single document with an optional explicit route
+or inferred metadata:
+
+```ts
+{
+  file: "README.md",
+  route: "/",
+  title: "Product documentation",
+  description: "Learn how to use the product."
+}
+```
+
+Use a glob for a documentation tree:
+
+```ts
+{
+  glob: ["docs/**/*.md", "docs/**/*.mdx"],
+  base: "docs",
+  routeBase: "/",
+  exclude: ["docs/internal/**"]
+}
+```
+
+`base` is removed from generated routes. `routeBase` is then prepended. A
+directory `README.md` or `index.md` maps to the directory route; other pages
+use extensionless routes.
+
+| Source path          | `base` | `routeBase`  | Route                        |
+| -------------------- | ------ | ------------ | ---------------------------- |
+| `README.md`          | —      | —            | `/` when explicitly assigned |
+| `docs/setup.md`      | `docs` | —            | `/setup`                     |
+| `docs/api/index.md`  | `docs` | —            | `/api`                       |
+| `docs/api/client.md` | `docs` | `/reference` | `/reference/api/client`      |
+
+Source paths are resolved from the configured project root. Paths outside that
+root are rejected unless `content.allowOutsideRoot` is explicitly enabled.
+Prefer an explicit source `root` when documenting another package; file and
+glob paths, links, and assets are confined to that declared source root.
+
+## Source identities and repeated mounts
+
+Every source can have an `id` containing letters, digits, underscores, and
+hyphens. Without one, Cookbook uses `source-1`, `source-2`, and so on. Explicit
+IDs are stable when declarations are reordered and must be unique.
+
+```ts
+content: {
+  sources: [
+    { id: "v1", root: "versions/v1", glob: "**/*.md", routeBase: "/v1" },
+    { id: "v2", root: "versions/v2", glob: "**/*.md", routeBase: "/v2" },
+  ];
+}
+```
+
+The same files may appear in several mounts. Relative links prefer the current
+source; an unambiguous page in another source can also resolve by file path.
+Use `source:v2/guide.md` to select another mount explicitly. The path is relative
+to that source's root, before `base` is removed from routes. Queries and heading
+fragments are preserved.
+
+A frontmatter `slug` is relative to `routeBase`, including when it begins with
+`/`. For example, `slug: intro` under `/v2` creates `/v2/intro`. File sources also
+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:
+
+```ts
+{
+  package: "@scope/package@latest",
+  include: ["README.md", "docs/**/*.md"],
+  exclude: ["docs/internal/**"],
+  index: "README.md",
+  routeBase: "/"
+}
+```
+
+Run `cookbook update` to create or reconcile the lock after editing sources.
+A production build uses the exact requested specifier, version, and integrity stored in
+`cookbook.lock.json`. The package creator writes this lock automatically.
+Artifacts are integrity-checked, extracted with file-count and size limits,
+and cached by integrity.
+
+Package Markdown is untrusted by default. Raw HTML is sanitized to safe
+elements, HTML-capable frontmatter is stripped, custom `head` entries are discarded,
+unsafe URL protocols are rejected, and MDX cannot execute. Set `trust: "mdx"`
+only after reviewing the exact locked artifact; doing so allows its build-time
+code to run. Trusted MDX is compiled by Starlight, including relative component
+imports from the source file's directory. Package-provided indexes, include
+patterns, exclude patterns, and every discovered file are confined to the
+extracted artifact root.
+
+## Links and assets
+
+Write ordinary repository-relative Markdown:
+
+```md
+[Install](./getting-started.md)
+![Architecture](./assets/architecture.svg)
+```
+
+Known document links are rewritten to public routes. Query strings and heading
+fragments are preserved, and fragments are checked against the target page's
+GitHub-style heading IDs. Inline and reference-style links and images are
+supported. Local images and downloadable files are validated, content-hashed,
+and copied into the static build.
+
+Absolute web links, `mailto:`, `tel:`, and hash-only links remain unchanged by
+default. Set `content.localizeRepositoryLinks: true` to rewrite absolute links
+back into the collected documentation when they match `site.repository` or the
+current package's `repository` manifest field. GitHub/GitLab `blob`, `tree`, and
+`raw` URLs plus Bitbucket `src` URLs are recognized; query strings and fragments
+are preserved. Links without a matching collected page remain external.
+
+Missing relative links are errors in strict mode; missing assets and paths
+escaping an allowed source root are always errors.
+
+Run the [doctor command](./cli.md#validate-with-doctor) before committing a
+large content move.

package/docs/customization-rules.md

@@ -0,0 +1,154 @@
+---
+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`                                         |
+| 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   |
+
+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 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
+  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,95 @@
+---
+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.
+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
+
+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.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

@@ -0,0 +1,101 @@
+---
+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: { from: "#315efb" },
+    tokens: { $radius: "8px" },
+  },
+  markdown: { rawHtml: "sanitize" },
+});
+
+export default mergeDocsConfig(company, {
+  site: { title: "Product docs" },
+  theme: { tokens: { "$content-width": "52rem" } },
+});
+```
+
+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
+objects and merge into Cookbook's complete base styles inside the renderer.

package/docs/getting-started.md

@@ -0,0 +1,134 @@
+---
+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.19 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. 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.
+
+## 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: { 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.
+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),
+the [AI agent workflow](./ai-agents.md), and [deployment](./deployment.md). Existing users should read the
+[prerelease migration guide](./migration.md).