{ "schemaVersion": 1, "version": 1, "project": { "name": "dewey", "version": null, "tagline": "Documentation toolkit for AI-agent-ready docs", "repository": null }, "ownership": { "owner": "dewey", "lifecycle": "regenerate", "registry": "/.dewey-generated.json" }, "artifacts": { "manifest": "/agent/manifest.json", "docs": "/agent/docs.json", "prompts": "/agent/prompts.json", "context": "/agent/context.md", "contextJson": "/agent/context.json", "allMarkdown": "/agent/bundles/all.md", "promptBundle": "/agent/bundles/prompts.md", "rawMarkdownBase": "/agent/raw/docs/", "bundles": { "core": "/agent/bundles/core.md", "prompts": "/agent/bundles/prompts.md", "all": "/agent/bundles/all.md" } }, "recommendedReadOrder": [ "overview", "quickstart", "api" ], "docs": [ { "id": "AGENTS", "slug": "AGENTS", "kind": "doc", "title": "dewey", "description": "Documentation toolkit for AI-agent-ready docs and retrieval artifacts", "sourcePath": "docs/AGENTS.md", "url": "/docs/AGENTS", "rawUrl": "/agent/raw/docs/AGENTS.md", "headings": [ { "depth": 1, "text": "dewey", "anchor": "dewey" }, { "depth": 2, "text": "Critical Context", "anchor": "critical-context" }, { "depth": 2, "text": "Project Structure", "anchor": "project-structure" }, { "depth": 2, "text": "Quick Navigation", "anchor": "quick-navigation" }, { "depth": 2, "text": "CLI Commands", "anchor": "cli-commands" }, { "depth": 2, "text": "Skills System", "anchor": "skills-system" }, { "depth": 3, "text": "Using Skills", "anchor": "using-skills" }, { "depth": 2, "text": "React Components (22 total)", "anchor": "react-components-22-total" }, { "depth": 3, "text": "Entry Points", "anchor": "entry-points" }, { "depth": 3, "text": "Layout", "anchor": "layout" }, { "depth": 3, "text": "Content", "anchor": "content" }, { "depth": 3, "text": "Agent-Friendly", "anchor": "agent-friendly" }, { "depth": 3, "text": "Provider", "anchor": "provider" }, { "depth": 2, "text": "Configuration (dewey.config.ts)", "anchor": "configuration-dewey-config-ts" }, { "depth": 2, "text": "Type Reference", "anchor": "type-reference" }, { "depth": 3, "text": "CalloutType", "anchor": "callouttype" }, { "depth": 3, "text": "BadgeVariant", "anchor": "badgevariant" }, { "depth": 3, "text": "ThemePreset", "anchor": "themepreset" }, { "depth": 2, "text": "File Generation", "anchor": "file-generation" }, { "depth": 2, "text": "Agent Content Pattern", "anchor": "agent-content-pattern" } ], "tokensEstimate": 1011, "frontmatter": {}, "markdown": "# dewey\n\n> Documentation toolkit for AI-agent-ready docs and retrieval artifacts\n\n## Critical Context\n\n**IMPORTANT:** Read these rules before making any changes:\n\n- Dewey generates standard files plus the `agent/` retrieval surface: manifests, raw markdown, prompts, and bundles\n- Skills are LLM prompts, NOT deterministic code - they guide agents\n- Each doc page should have TWO versions: human (.md) and agent (.agent.md)\n- The `.dewey/` folder contains generated artifacts (reviews, prompts, drift reports)\n- Never hardcode values that exist in source code - always cross-reference\n\n## Project Structure\n\n| Component | Path | Purpose |\n|-----------|------|---------|\n| React Components | `packages/docs/src/components/` | Optional docs UI components |\n| CLI Commands | `packages/docs/src/cli/commands/` | init, audit, generate, agent |\n| Skills | `packages/docs/src/skills/` | LLM prompt templates |\n| Documentation Site | `www/src/app/` | Live docs at dewey site |\n\n## Quick Navigation\n\n- Entry point: `packages/docs/src/index.ts`\n- CLI entry: `packages/docs/src/cli/index.ts`\n- Config schema: `packages/docs/src/cli/schema.ts`\n- Main layout: `packages/docs/src/components/DocsLayout.tsx`\n\n## CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `dewey init` | Scaffold docs structure + dewey.config.ts |\n| `dewey audit` | Validate documentation completeness |\n| `dewey generate` | Create AGENTS.md, llms.txt, docs.json, install.md, and `agent/` artifacts |\n| `dewey create` | Optional static docs site from markdown |\n| `dewey agent` | Score agent-readiness (100 pts scale) |\n| `dewey update` | Refresh Dewey-owned generated-site files |\n| `dewey eject` | Transfer a component to consumer ownership |\n\n## Skills System\n\nSkills are exportable LLM prompts that guide agents:\n\n| Skill | Purpose |\n|-------|---------|\n| `docsReviewAgent` | Review docs quality, catch drift from codebase |\n| `docsDesignCritic` | Critique page structure — heading hierarchy, component usage, visual rhythm |\n| `promptSlideoutGenerator` | Generate AI-consumable prompt configs |\n| `installMdGenerator` | Create LLM-executable installation (installmd.org) |\n\n### Using Skills\n\n```typescript\nimport { docsReviewAgent } from '@arach/dewey'\n\n// Get the prompt template\nconst prompt = docsReviewAgent.reviewPage\n .replace('{DOC_FILE}', 'docs/api.md')\n .replace('{SOURCE_FILES}', 'src/types/index.ts')\n .replace('{OUTPUT_FILE}', '.dewey/reviews/api.md')\n\n// Feed to LLM for execution\n```\n\n## React Components (22 total)\n\n### Entry Points\n- `DocsApp` - Complete docs site with routing\n- `DocsIndex` - Card-based landing page\n\n### Layout\n- `DocsLayout` - Main layout (sidebar, TOC, navigation)\n- `Header` - Sticky header with theme toggle\n- `Sidebar` - Left navigation panel\n- `TableOfContents` - Right minimap with scroll-spy\n\n### Content\n- `MarkdownContent` - Renders markdown with syntax highlighting\n- `CodeBlock` - Code with copy button\n- `Callout` - Alert boxes (info, warning, tip, danger)\n- `Tabs` - Tabbed content\n- `Steps` - Numbered instructions\n- `Card`, `CardGrid` - Content cards\n- `FileTree` - Directory visualizer\n- `ApiTable` - Props/params table\n- `Badge` - Status indicators\n\n### Agent-Friendly\n- `AgentContext` - Collapsible agent content block\n- `PromptSlideout` - Interactive prompt editor with parameters\n- `CopyButtons` - \"Copy for AI\" and \"Copy Markdown\" buttons\n\n### Provider\n- `DeweyProvider` - Theme and component context\n\n## Configuration (dewey.config.ts)\n\n```typescript\nexport default {\n project: {\n name: string,\n tagline: string,\n type: 'npm-package' | 'cli-tool' | 'macos-app' | 'react-library' | 'monorepo' | 'generic',\n },\n agent: {\n criticalContext: string[], // Rules agents MUST know\n entryPoints: Record, // Key directories\n rules: Array<{ pattern, instruction }>,\n sections: string[], // Docs to include in AGENTS.md\n },\n docs: {\n path: string, // Default: './docs'\n output: string, // Default: './'\n required: string[],\n },\n install: {\n objective: string,\n doneWhen: { command, expectedOutput },\n prerequisites: string[],\n steps: Array<{ description, command, alternatives }>,\n },\n}\n```\n\n## Type Reference\n\n### CalloutType\n`'info'` | `'warning'` | `'tip'` | `'danger'`\n\n### BadgeVariant\n`'default'` | `'success'` | `'warning'` | `'danger'` | `'info'` | `'purple'`\n\n### ThemePreset\n`'neutral'` | `'ocean'` | `'emerald'` | `'purple'` | `'dusk'` | `'rose'` | `'github'` | `'warm'` | `'midnight'` | `'editorial'` | `'mono'` | `'hudson'`\n\n## File Generation\n\n`dewey generate` creates:\n\n| File | Format | Purpose |\n|------|--------|---------|\n| AGENTS.md | Markdown | Combined docs with critical context |\n| llms.txt | Plain text | General software context |\n| docs.json | JSON | Structured documentation |\n| install.md | Markdown | LLM-executable installation (installmd.org) |\n| agent/ | Markdown + JSON | Recursive retrieval manifests, raw docs, prompts, and bundles |\n\n## Agent Content Pattern\n\nEach doc page should have two versions:\n\n```\ndocs/\n├── overview.md # Human-readable\n├── quickstart.md\n├── agent/\n│ ├── overview.agent.md # Agent-optimized (dense, structured)\n│ └── quickstart.agent.md\n├── AGENTS.md # Combined agent doc\n└── llms.txt # Plain text summary\n```\n\nThe `.agent.md` versions are:\n- Denser (no prose, just facts)\n- Structured (tables, explicit values)\n- Self-contained (no URL fetching needed)\n- Cross-referenced against source code\n\n---\n\n*Generated by Dewey | [github.com/arach/dewey](https://github.com/arach/dewey)*\n", "content": "# dewey\n\n> Documentation toolkit for AI-agent-ready docs and retrieval artifacts\n\n## Critical Context\n\n**IMPORTANT:** Read these rules before making any changes:\n\n- Dewey generates standard files plus the `agent/` retrieval surface: manifests, raw markdown, prompts, and bundles\n- Skills are LLM prompts, NOT deterministic code - they guide agents\n- Each doc page should have TWO versions: human (.md) and agent (.agent.md)\n- The `.dewey/` folder contains generated artifacts (reviews, prompts, drift reports)\n- Never hardcode values that exist in source code - always cross-reference\n\n## Project Structure\n\n| Component | Path | Purpose |\n|-----------|------|---------|\n| React Components | `packages/docs/src/components/` | Optional docs UI components |\n| CLI Commands | `packages/docs/src/cli/commands/` | init, audit, generate, agent |\n| Skills | `packages/docs/src/skills/` | LLM prompt templates |\n| Documentation Site | `www/src/app/` | Live docs at dewey site |\n\n## Quick Navigation\n\n- Entry point: `packages/docs/src/index.ts`\n- CLI entry: `packages/docs/src/cli/index.ts`\n- Config schema: `packages/docs/src/cli/schema.ts`\n- Main layout: `packages/docs/src/components/DocsLayout.tsx`\n\n## CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `dewey init` | Scaffold docs structure + dewey.config.ts |\n| `dewey audit` | Validate documentation completeness |\n| `dewey generate` | Create AGENTS.md, llms.txt, docs.json, install.md, and `agent/` artifacts |\n| `dewey create` | Optional static docs site from markdown |\n| `dewey agent` | Score agent-readiness (100 pts scale) |\n| `dewey update` | Refresh Dewey-owned generated-site files |\n| `dewey eject` | Transfer a component to consumer ownership |\n\n## Skills System\n\nSkills are exportable LLM prompts that guide agents:\n\n| Skill | Purpose |\n|-------|---------|\n| `docsReviewAgent` | Review docs quality, catch drift from codebase |\n| `docsDesignCritic` | Critique page structure — heading hierarchy, component usage, visual rhythm |\n| `promptSlideoutGenerator` | Generate AI-consumable prompt configs |\n| `installMdGenerator` | Create LLM-executable installation (installmd.org) |\n\n### Using Skills\n\n```typescript\nimport { docsReviewAgent } from '@arach/dewey'\n\n// Get the prompt template\nconst prompt = docsReviewAgent.reviewPage\n .replace('{DOC_FILE}', 'docs/api.md')\n .replace('{SOURCE_FILES}', 'src/types/index.ts')\n .replace('{OUTPUT_FILE}', '.dewey/reviews/api.md')\n\n// Feed to LLM for execution\n```\n\n## React Components (22 total)\n\n### Entry Points\n- `DocsApp` - Complete docs site with routing\n- `DocsIndex` - Card-based landing page\n\n### Layout\n- `DocsLayout` - Main layout (sidebar, TOC, navigation)\n- `Header` - Sticky header with theme toggle\n- `Sidebar` - Left navigation panel\n- `TableOfContents` - Right minimap with scroll-spy\n\n### Content\n- `MarkdownContent` - Renders markdown with syntax highlighting\n- `CodeBlock` - Code with copy button\n- `Callout` - Alert boxes (info, warning, tip, danger)\n- `Tabs` - Tabbed content\n- `Steps` - Numbered instructions\n- `Card`, `CardGrid` - Content cards\n- `FileTree` - Directory visualizer\n- `ApiTable` - Props/params table\n- `Badge` - Status indicators\n\n### Agent-Friendly\n- `AgentContext` - Collapsible agent content block\n- `PromptSlideout` - Interactive prompt editor with parameters\n- `CopyButtons` - \"Copy for AI\" and \"Copy Markdown\" buttons\n\n### Provider\n- `DeweyProvider` - Theme and component context\n\n## Configuration (dewey.config.ts)\n\n```typescript\nexport default {\n project: {\n name: string,\n tagline: string,\n type: 'npm-package' | 'cli-tool' | 'macos-app' | 'react-library' | 'monorepo' | 'generic',\n },\n agent: {\n criticalContext: string[], // Rules agents MUST know\n entryPoints: Record, // Key directories\n rules: Array<{ pattern, instruction }>,\n sections: string[], // Docs to include in AGENTS.md\n },\n docs: {\n path: string, // Default: './docs'\n output: string, // Default: './'\n required: string[],\n },\n install: {\n objective: string,\n doneWhen: { command, expectedOutput },\n prerequisites: string[],\n steps: Array<{ description, command, alternatives }>,\n },\n}\n```\n\n## Type Reference\n\n### CalloutType\n`'info'` | `'warning'` | `'tip'` | `'danger'`\n\n### BadgeVariant\n`'default'` | `'success'` | `'warning'` | `'danger'` | `'info'` | `'purple'`\n\n### ThemePreset\n`'neutral'` | `'ocean'` | `'emerald'` | `'purple'` | `'dusk'` | `'rose'` | `'github'` | `'warm'` | `'midnight'` | `'editorial'` | `'mono'` | `'hudson'`\n\n## File Generation\n\n`dewey generate` creates:\n\n| File | Format | Purpose |\n|------|--------|---------|\n| AGENTS.md | Markdown | Combined docs with critical context |\n| llms.txt | Plain text | General software context |\n| docs.json | JSON | Structured documentation |\n| install.md | Markdown | LLM-executable installation (installmd.org) |\n| agent/ | Markdown + JSON | Recursive retrieval manifests, raw docs, prompts, and bundles |\n\n## Agent Content Pattern\n\nEach doc page should have two versions:\n\n```\ndocs/\n├── overview.md # Human-readable\n├── quickstart.md\n├── agent/\n│ ├── overview.agent.md # Agent-optimized (dense, structured)\n│ └── quickstart.agent.md\n├── AGENTS.md # Combined agent doc\n└── llms.txt # Plain text summary\n```\n\nThe `.agent.md` versions are:\n- Denser (no prose, just facts)\n- Structured (tables, explicit values)\n- Self-contained (no URL fetching needed)\n- Cross-referenced against source code\n\n---\n\n*Generated by Dewey | [github.com/arach/dewey](https://github.com/arach/dewey)*" }, { "id": "api", "slug": "api", "kind": "doc", "title": "API Reference", "description": "Public TypeScript, React, theme, and agent-artifact APIs for @arach/dewey", "sourcePath": "docs/api.md", "url": "/docs/api", "rawUrl": "/agent/raw/docs/api.md", "headings": [ { "depth": 2, "text": "Choose the right surface", "anchor": "choose-the-right-surface" }, { "depth": 2, "text": "Package entry points", "anchor": "package-entry-points" }, { "depth": 2, "text": "Configuration API", "anchor": "configuration-api" }, { "depth": 3, "text": "DeweyConfig", "anchor": "deweyconfig" }, { "depth": 2, "text": "Programmatic agent artifacts", "anchor": "programmatic-agent-artifacts" }, { "depth": 3, "text": "Artifact functions", "anchor": "artifact-functions" }, { "depth": 3, "text": "Artifact types and classification", "anchor": "artifact-types-and-classification" }, { "depth": 2, "text": "React API", "anchor": "react-api" }, { "depth": 3, "text": "Provider and complete app", "anchor": "provider-and-complete-app" }, { "depth": 3, "text": "Layout and content components", "anchor": "layout-and-content-components" }, { "depth": 3, "text": "Content and agent-friendly components", "anchor": "content-and-agent-friendly-components" }, { "depth": 3, "text": "Navigation types", "anchor": "navigation-types" }, { "depth": 2, "text": "Themes", "anchor": "themes" }, { "depth": 2, "text": "Skills and structured agent content", "anchor": "skills-and-structured-agent-content" }, { "depth": 2, "text": "Complete main-module export inventory", "anchor": "complete-main-module-export-inventory" } ], "tokensEstimate": 2821, "frontmatter": { "title": "API Reference", "description": "Public TypeScript, React, theme, and agent-artifact APIs for @arach/dewey", "order": 5, "group": "Reference", "groupId": "reference" }, "markdown": "---\ntitle: API Reference\ndescription: Public TypeScript, React, theme, and agent-artifact APIs for @arach/dewey\norder: 5\ngroup: Reference\ngroupId: reference\n---\n\nDewey’s primary product surface is the CLI: use it to audit documentation and generate agent-ready artifacts. The TypeScript API supports typed configuration, programmatic artifact retrieval, and an optional React presentation layer. The public module is defined by `packages/docs/src/index.ts`; package subpaths are defined by `packages/docs/package.json`.\n\n## Choose the right surface\n\n| Goal | Surface | Import or command |\n|---|---|---|\n| Generate `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and `agent/` | CLI | `bunx dewey generate` |\n| Validate structure or score readiness | CLI | `bunx dewey audit` / `bunx dewey agent` |\n| Author a type-checked `dewey.config.ts` | Main TypeScript module | `@arach/dewey` |\n| Collect or build retrieval artifacts in code | Artifact subpath | `@arach/dewey/agent-artifacts` |\n| Render Markdown in an existing React app | Optional UI | `@arach/dewey` + CSS subpaths |\n| Scaffold a standalone docs site | Optional UI | `bunx dewey create` |\n\nThe React components do not replace generation. Keep `.md` and `.agent.md` source pairs, run the CLI pipeline, and add UI only when humans need a rendered site.\n\n## Package entry points\n\n| Package path | Contents |\n|---|---|\n| `@arach/dewey` | Configuration helper, themes, React components, hooks, skills, utilities, and types |\n| `@arach/dewey/react` | Compatibility alias for the same module as `@arach/dewey` |\n| `@arach/dewey/agent-artifacts` | Markdown collection, manifests, bundles, and ownership-safe artifact writing |\n| `@arach/dewey/css` | Full CSS bundle |\n| `@arach/dewey/styles` | Alias for the full CSS bundle |\n| `@arach/dewey/css/base.css` | Base component styles |\n| `@arach/dewey/css/tokens` | Semantic `--dw-*` tokens |\n| `@arach/dewey/css/tailwind` | Tailwind-oriented CSS |\n| `@arach/dewey/css/colors/.css` | One published color preset |\n| `@arach/dewey/tailwind` | Tailwind preset module |\n\nThere is no wildcard color export. `` must be one of the twelve published names listed under [Themes](#themes).\n\n## Configuration API\n\n`defineConfig` parses and returns a `DeweyConfig`; it is not just a TypeScript identity helper. Invalid values throw a Zod validation error. Its source is `packages/docs/src/cli/schema.ts`.\n\n```ts\n// dewey.config.ts\nimport { defineConfig } from '@arach/dewey'\n\nexport default defineConfig({\n project: {\n name: 'my-library',\n tagline: 'A useful TypeScript library',\n type: 'npm-package',\n version: '1.0.0',\n },\n agent: {\n criticalContext: ['Use Bun for package operations'],\n entryPoints: { API: 'src/index.ts', Tests: 'test/' },\n rules: [\n { pattern: '*.test.ts', instruction: 'Use bun:test.' },\n ],\n sections: [], // empty means all human-readable docs\n },\n docs: {\n path: './docs',\n output: './',\n required: ['overview', 'quickstart', 'api'],\n },\n install: {\n objective: 'Install my-library.',\n prerequisites: ['Node.js 18+'],\n steps: [{ description: 'Install', command: 'bun add my-library' }],\n doneWhen: { command: 'bun test', expectedOutput: 'all tests pass' },\n },\n})\n```\n\n### `DeweyConfig`\n\n| Field | Type | Default / requirement |\n|---|---|---|\n| `project.name` | `string` | Required |\n| `project.tagline` | `string` | Optional |\n| `project.type` | `ProjectType` | `'generic'` |\n| `project.version` | `string` | Optional |\n| `agent.criticalContext` | `string[]` | `[]` |\n| `agent.entryPoints` | `Record` | `{}` |\n| `agent.rules` | `{ pattern: string; instruction: string }[]` | `[]` |\n| `agent.sections` | `string[]` | `[]`; empty includes every human-readable document |\n| `docs.path` | `string` | `'./docs'` |\n| `docs.output` | `string` | `'./'` |\n| `docs.required` | `string[]` | `['overview', 'quickstart']` |\n| `install.objective` | `string` | Optional |\n| `install.doneWhen` | `{ command: string; expectedOutput?: string }` | Optional |\n| `install.prerequisites` | `string[]` | `[]` |\n| `install.steps` | Install step array | `[]` |\n| `install.hostedUrl` | `string` | Optional |\n\n`ProjectType` is `'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`.\n\n## Programmatic agent artifacts\n\nImport this surface from `@arach/dewey/agent-artifacts`, implemented in `packages/docs/src/cli/agent-artifacts.ts`.\n\n```ts\nimport {\n buildAgentManifest,\n collectMarkdownArtifacts,\n getMarkdownArtifact,\n writeAgentArtifacts,\n} from '@arach/dewey/agent-artifacts'\n\nconst options = {\n rootDir: process.cwd(),\n docsDir: './docs',\n}\nconst project = { name: 'my-library', version: '1.0.0' }\n\nconst docs = await collectMarkdownArtifacts(options)\nconst manifest = buildAgentManifest(docs, { project })\nconst api = await getMarkdownArtifact('api', options)\n\nconst preview = await writeAgentArtifacts({\n ...options,\n outputDir: './generated',\n project,\n dryRun: true,\n})\n\nconsole.log(manifest.recommendedReadOrder, api?.rawUrl, preview.operations)\n```\n\n`dryRun: true` plans the same ownership-aware operations without writing. A real write creates or updates Dewey-owned outputs and prunes stale outputs in the selected artifact scope; `overwrite: true` explicitly permits replacement of reviewed desired-output conflicts, including modified or unowned targets.\n\n### Artifact functions\n\n| Export | Signature / result |\n|---|---|\n| `collectMarkdownArtifacts(options?)` | Recursively parse `.md` and `.mdx`; returns sorted `Promise` |\n| `getMarkdownArtifact(slug, options?)` | Find by normalized slug or source path; returns `Promise` |\n| `getPromptArtifact(promptId, options?)` | Find a prompt under `prompts/`; returns `Promise` |\n| `parseDocArtifact(filePath, raw?, options?)` | Parse one file or supplied Markdown string into a `MarkdownArtifact` |\n| `buildAgentManifest(docs, options?)` | Build an `AgentManifest`; `includeContent` controls embedded Markdown/content |\n| `buildPromptRegistry(docs, options?)` | Build the schema-versioned prompt registry |\n| `buildContextBundle(docs, slugs, title?)` | Render selected slugs as one Markdown bundle |\n| `buildAgentArtifactFiles(options?)` | Build generated file descriptions in memory without applying them |\n| `writeAgentArtifacts(options?)` | Plan and optionally apply artifact writes; returns counts, paths, and operations |\n\n### Artifact types and classification\n\n`CollectMarkdownArtifactsOptions` accepts `rootDir?` and `docsDir?`. `WriteAgentArtifactsOptions` adds `outputDir?`, `project?`, `dryRun?`, and `overwrite?`. `AgentArtifactsProject` is `{ name: string; version?: string; tagline?: string; repository?: string }`.\n\n`MarkdownArtifactKind` is `'doc' | 'agent' | 'prompt' | 'reference' | 'proposal'`. Classification is path-based:\n\n| Path pattern | Kind |\n|---|---|\n| `prompts/**` | `prompt` |\n| `agent/**` or a slug ending in `.agent` | `agent` |\n| `reference/**` | `reference` |\n| `proposals/**` | `proposal` |\n| Everything else | `doc` |\n\nA `MarkdownArtifact` includes `id`, `slug`, `kind`, optional `promptId`, title/description, `sourcePath`, retrieval URLs, frontmatter, headings, token estimate, raw Markdown, and body content. Manifest types exported by the subpath are `AgentManifest`, `AgentManifestEntry`, `PromptManifestEntry`, `MarkdownArtifact`, `MarkdownHeading`, and the option/project types above.\n\n## React API\n\nReact is an optional presentation layer. The main source is `packages/docs/src/index.ts`; component contracts live in `packages/docs/src/components/`.\n\n```tsx\n'use client'\n\nimport {\n AutoTableOfContents,\n CopyButtons,\n DeweyProvider,\n MarkdownContent,\n} from '@arach/dewey'\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\n\nexport function DocPage({ markdown, agentMarkdown }: {\n markdown: string\n agentMarkdown: string\n}) {\n return (\n \n \n \n \n \n )\n}\n```\n\nComponents that call Dewey hooks must be descendants of `DeweyProvider`. In a Next.js App Router project, put the provider and interactive components behind a client boundary; load Markdown and generate static params on the server.\n\n### Provider and complete app\n\n| Export | Required props | Important optional props |\n|---|---|---|\n| `DeweyProvider` | `children` | `components`, `theme`, `defaultDark`, `storageKey` |\n| `DocsApp` | `docs: Record` | `config`, `currentPage`, `providerProps`; `onNavigate` is currently reserved and not invoked |\n| `DocsIndex` | `tree: PageNode[]` | `projectName`, `tagline`, `description`, `basePath`, `hero`, `showSearch`, `heroIcon`, `quickLinks`, `layout` |\n\n`FrameworkComponents` can provide a `Link` component accepting anchor props plus `href`, and an optional `Image` component accepting image props. `ThemeConfig` accepts `preset?`, partial `colors` (`primary`, `background`, `foreground`, `accent`), and partial `fonts` (`sans`, `mono`).\n\n`DocsAppConfig.layout.header` is `boolean | 'minimal'`; the other layout switches are booleans: `sidebar`, `toc`, `footer`, `prevNext`, and `breadcrumbs`.\n\n### Layout and content components\n\n| Export | Required props | Important optional props |\n|---|---|---|\n| `Header` | None | `projectName`, `homeUrl`, `backUrl`, `backLabel`, `label`, `showThemeToggle`, `actions` |\n| `Sidebar` | `tree` | `currentPage`, `projectName`, `basePath`, `isOpen`, `onClose`, `header`, `footer` |\n| `MarkdownContent` | `content` | `isDark` |\n| `TableOfContents` | None | `items`, `title`, `className`, `scrollOffset` |\n| `AutoTableOfContents` | None | `markdown`, `containerRef`, `title`, `className` |\n| `DocsLayout` | `children`, `title`, `navigation`, `projectName` | Router-neutral shell; accepts `currentPage` and a framework `LinkComponent`, with plain anchors by default; its prop type is not re-exported by the main entry point |\n| `CodeBlock` / `HeadingLink` | See source | Values are public, but their prop interfaces are not exported |\n\n`TocItem` is `{ id: string; title: string; level: number }`. Related exports are `useActiveSection`, `extractTocItems`, `extractTocFromDom`, `useTableOfContents`, and `extractSections`.\n\n### Content and agent-friendly components\n\n| Export | Required props | Important optional props / unions |\n|---|---|---|\n| `Callout` | `children` | `type?: 'info' \\| 'warning' \\| 'tip' \\| 'danger'`, `title` |\n| `Tabs` / `Tab` | `children`; `Tab` also requires `label` | `Tabs.defaultTab` |\n| `Steps` / `Step` | `children`; `Step` also requires `title` | — |\n| `Card` | `title` | `description`, `icon`, `href`, `children` |\n| `CardGrid` | `children` | `columns?: 2 \\| 3 \\| 4` |\n| `FileTree` | `items` | `defaultExpanded`; item `type?: 'file' \\| 'folder'` |\n| `ApiTable` | `properties` | `title` |\n| `Badge` | `children` | `variant`, `size?: 'sm' \\| 'md'` |\n| `CopyButtons` | `markdownContent` | `agentContent`, `showLabels`, `onCopy`, `className` |\n| `AgentContext` | `content` | `title`, `defaultExpanded`, `className` |\n| `PromptSlideout` | `isOpen`, `onClose`, `info`, `starterTemplate` | `title`, `description`, `params`, `examples`, `expectedOutput`, `className` |\n\n`BadgeVariant` is `'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple'`. `CopyButtons.onCopy` receives `'markdown' | 'agent' | 'plain'`.\n\n### Navigation types\n\n`PageNode` is a discriminated union of `PageItem`, `PageFolder`, and `PageSeparator` using `type: 'page' | 'folder' | 'separator'`. Page/navigation badge colors are `'info' | 'success' | 'warning' | 'error' | 'default'`. `NavigationConfig` is `NavigationGroup[]`.\n\nLegacy compatibility types are also exported: `NavItem`, `NavGroup`, `DocSection`, `BadgeColor`, `PageLink`, and `DocsConfig`. The legacy `BadgeColor` union is `'blue' | 'emerald' | 'purple' | 'amber' | 'rose'`.\n\n## Themes\n\nThe canonical registry is `packages/docs/src/themes.ts`.\n\n```ts\nimport {\n THEME_REGISTRY,\n VALID_THEMES,\n isThemeName,\n resolveTheme,\n type ThemeName,\n} from '@arach/dewey'\n\nconst input = process.env.DOCS_THEME\nconst theme: ThemeName = resolveTheme(input) // invalid or missing -> 'neutral'\n\nif (input && !isThemeName(input)) {\n console.warn(`Choose one of: ${VALID_THEMES.join(', ')}`)\n}\n\nconsole.log(THEME_REGISTRY[theme].cssFile)\n```\n\n`ThemeName` and `ThemePreset` contain the same values:\n\n`'neutral' | 'ocean' | 'emerald' | 'purple' | 'dusk' | 'rose' | 'github' | 'warm' | 'midnight' | 'editorial' | 'mono' | 'hudson'`\n\n`PUBLISHED_CSS_THEMES` lists presets with CSS exports; `VALID_THEMES` lists presets accepted by generated sites. Every current registry entry belongs to both lists. `resolveTheme` falls back to `'neutral'`.\n\nAll twelve presets resolve the same semantic contract in light and dark: surfaces/foregrounds, primary/secondary/accent pairs, border/ring, info/warning/error/success pairs, code and syntax colors, sidebar/header colors, typography, radii, shadows, and motion. Runtime components and generated sites consume semantic `--dw-*` variables; public components do not own literal color palettes.\n\nContract tests verify every preset and generated-site theme in both modes, reject missing/dead tokens, require WCAG AA text pairs and visible focus, and check reduced-motion behavior. `bun run --cwd packages/docs test:visual` renders representative navigation, prose, controls, semantic states, code, and tables for 12 themes × light/dark and compares 24 Playwright screenshots.\n\n## Skills and structured agent content\n\nThe skill exports are LLM prompt definitions, not deterministic generators:\n\n| Export | Type / role |\n|---|---|\n| `docsReviewAgent` | Prompt set for accuracy and drift review; result type `DocsReviewResult` |\n| `docsDesignCritic` | Prompt set for structure/design critique; result type `DocsDesignCritiqueResult` |\n| `promptSlideoutGenerator` | Prompt set for authoring slideout configuration; type `PromptSlideoutConfig` |\n| `installMdGenerator` | Prompt set for installmd.org content; type `InstallMdConfig` |\n| `improveAIPrompts` | Iterative discovery/draft/review/refinement prompt set; types `PromptImprovementPass` and `PromptQualityCriteria` |\n\n`improveAIPromptsSkill` is a deprecated alias of `improveAIPrompts` for compatibility.\n\nStructured agent content can be assembled and rendered without the CLI:\n\n```ts\nimport {\n agentContent,\n renderAgentJson,\n renderAgentMarkdown,\n} from '@arach/dewey'\n\nconst api = agentContent('api', 'API', 'Public package contracts')\n .enums('Themes', { ThemePreset: ['neutral', 'ocean'] })\n .code('Import', 'ts', \"import { defineConfig } from '@arach/dewey'\")\n .build()\n\nconst markdown = renderAgentMarkdown(api)\nconst json = renderAgentJson(api)\n```\n\nThe related exports are `AgentContentBuilder`, `renderAgentPlainText`, and the `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, and `ListSection` types.\n\n## Complete main-module export inventory\n\nThe following names are re-exported from `packages/docs/src/index.ts`.\n\n| Group | Runtime exports |\n|---|---|\n| Config | `defineConfig` |\n| Themes | `PUBLISHED_CSS_THEMES`, `THEME_REGISTRY`, `VALID_THEMES`, `isThemeName`, `resolveTheme` |\n| App/provider | `DocsApp`, `DocsAppDefault`, `DocsIndex`, `DeweyProvider`, `useDewey`, `useTheme`, `useComponents`, `useLink` |\n| Layout/content | `Header`, `DocsLayout`, `MarkdownContent`, `CodeBlock`, `HeadingLink`, `Sidebar`, `TableOfContents`, `AutoTableOfContents`, `useActiveSection`, `extractTocItems`, `extractTocFromDom` |\n| UI | `Callout`, `Tabs`, `Tab`, `Steps`, `Step`, `Card`, `CardGrid`, `FileTree`, `ApiTable`, `Badge` |\n| Agent UI | `CopyButtons`, `AgentContext`, `PromptSlideout` |\n| Skills | `promptSlideoutGenerator`, `docsReviewAgent`, `docsDesignCritic`, `installMdGenerator`, `improveAIPrompts`, `improveAIPromptsSkill` |\n| Hooks/utilities | `useDarkMode`, `useTableOfContents`, `extractSections`, `cn`, `resolveIcon`, `commonIcons` |\n| Agent content | `agentContent`, `AgentContentBuilder`, `renderAgentMarkdown`, `renderAgentJson`, `renderAgentPlainText` |\n\n| Type group | Type exports |\n|---|---|\n| Config/themes | `AgentRule`, `DeweyConfig`, `InstallConfig`, `ProjectType`, `ThemeDefinition`, `ThemeName`, `ThemePreset` |\n| App/provider | `DocsAppProps`, `DocsAppConfig`, `DocsIndexProps`, `DeweyProviderProps`, `DeweyContextValue`, `ThemeConfig`, `FrameworkComponents` |\n| Components | `HeaderProps`, `DocsLayoutProps`, `MarkdownContentProps`, `SidebarProps`, `AutoTocProps`, `TableOfContentsProps`, `TocItem`, `CalloutProps`, `CalloutType`, `TabsProps`, `TabProps`, `StepsProps`, `StepProps`, `CardProps`, `CardGridProps`, `FileTreeProps`, `FileTreeItem`, `ApiTableProps`, `ApiProperty`, `BadgeProps`, `BadgeVariant`, `CopyButtonsProps`, `AgentContextProps`, `PromptSlideoutProps`, `PromptParam` |\n| Skills/content | `PromptSlideoutConfig`, `DocsReviewResult`, `DocsDesignCritiqueResult`, `InstallMdConfig`, `PromptImprovementPass`, `PromptQualityCriteria`, `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, `ListSection` |\n| Navigation/utilities | `PageTree`, `PageNode`, `PageItem`, `PageFolder`, `PageSeparator`, `FlatPage`, `NavigationConfig`, `NavigationGroup`, `NavigationItem`, `CommonIconName` |\n| Legacy | `NavItem`, `NavGroup`, `DocSection`, `BadgeColor`, `PageLink`, `DocsConfig` |\n\nFor command flags and workflows, use the [CLI reference](./cli.md). For a complete server/client integration, use [Integrate into an existing site](./integrate-existing-site.md).\n", "content": "Dewey’s primary product surface is the CLI: use it to audit documentation and generate agent-ready artifacts. The TypeScript API supports typed configuration, programmatic artifact retrieval, and an optional React presentation layer. The public module is defined by `packages/docs/src/index.ts`; package subpaths are defined by `packages/docs/package.json`.\n\n## Choose the right surface\n\n| Goal | Surface | Import or command |\n|---|---|---|\n| Generate `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and `agent/` | CLI | `bunx dewey generate` |\n| Validate structure or score readiness | CLI | `bunx dewey audit` / `bunx dewey agent` |\n| Author a type-checked `dewey.config.ts` | Main TypeScript module | `@arach/dewey` |\n| Collect or build retrieval artifacts in code | Artifact subpath | `@arach/dewey/agent-artifacts` |\n| Render Markdown in an existing React app | Optional UI | `@arach/dewey` + CSS subpaths |\n| Scaffold a standalone docs site | Optional UI | `bunx dewey create` |\n\nThe React components do not replace generation. Keep `.md` and `.agent.md` source pairs, run the CLI pipeline, and add UI only when humans need a rendered site.\n\n## Package entry points\n\n| Package path | Contents |\n|---|---|\n| `@arach/dewey` | Configuration helper, themes, React components, hooks, skills, utilities, and types |\n| `@arach/dewey/react` | Compatibility alias for the same module as `@arach/dewey` |\n| `@arach/dewey/agent-artifacts` | Markdown collection, manifests, bundles, and ownership-safe artifact writing |\n| `@arach/dewey/css` | Full CSS bundle |\n| `@arach/dewey/styles` | Alias for the full CSS bundle |\n| `@arach/dewey/css/base.css` | Base component styles |\n| `@arach/dewey/css/tokens` | Semantic `--dw-*` tokens |\n| `@arach/dewey/css/tailwind` | Tailwind-oriented CSS |\n| `@arach/dewey/css/colors/.css` | One published color preset |\n| `@arach/dewey/tailwind` | Tailwind preset module |\n\nThere is no wildcard color export. `` must be one of the twelve published names listed under [Themes](#themes).\n\n## Configuration API\n\n`defineConfig` parses and returns a `DeweyConfig`; it is not just a TypeScript identity helper. Invalid values throw a Zod validation error. Its source is `packages/docs/src/cli/schema.ts`.\n\n```ts\n// dewey.config.ts\nimport { defineConfig } from '@arach/dewey'\n\nexport default defineConfig({\n project: {\n name: 'my-library',\n tagline: 'A useful TypeScript library',\n type: 'npm-package',\n version: '1.0.0',\n },\n agent: {\n criticalContext: ['Use Bun for package operations'],\n entryPoints: { API: 'src/index.ts', Tests: 'test/' },\n rules: [\n { pattern: '*.test.ts', instruction: 'Use bun:test.' },\n ],\n sections: [], // empty means all human-readable docs\n },\n docs: {\n path: './docs',\n output: './',\n required: ['overview', 'quickstart', 'api'],\n },\n install: {\n objective: 'Install my-library.',\n prerequisites: ['Node.js 18+'],\n steps: [{ description: 'Install', command: 'bun add my-library' }],\n doneWhen: { command: 'bun test', expectedOutput: 'all tests pass' },\n },\n})\n```\n\n### `DeweyConfig`\n\n| Field | Type | Default / requirement |\n|---|---|---|\n| `project.name` | `string` | Required |\n| `project.tagline` | `string` | Optional |\n| `project.type` | `ProjectType` | `'generic'` |\n| `project.version` | `string` | Optional |\n| `agent.criticalContext` | `string[]` | `[]` |\n| `agent.entryPoints` | `Record` | `{}` |\n| `agent.rules` | `{ pattern: string; instruction: string }[]` | `[]` |\n| `agent.sections` | `string[]` | `[]`; empty includes every human-readable document |\n| `docs.path` | `string` | `'./docs'` |\n| `docs.output` | `string` | `'./'` |\n| `docs.required` | `string[]` | `['overview', 'quickstart']` |\n| `install.objective` | `string` | Optional |\n| `install.doneWhen` | `{ command: string; expectedOutput?: string }` | Optional |\n| `install.prerequisites` | `string[]` | `[]` |\n| `install.steps` | Install step array | `[]` |\n| `install.hostedUrl` | `string` | Optional |\n\n`ProjectType` is `'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`.\n\n## Programmatic agent artifacts\n\nImport this surface from `@arach/dewey/agent-artifacts`, implemented in `packages/docs/src/cli/agent-artifacts.ts`.\n\n```ts\nimport {\n buildAgentManifest,\n collectMarkdownArtifacts,\n getMarkdownArtifact,\n writeAgentArtifacts,\n} from '@arach/dewey/agent-artifacts'\n\nconst options = {\n rootDir: process.cwd(),\n docsDir: './docs',\n}\nconst project = { name: 'my-library', version: '1.0.0' }\n\nconst docs = await collectMarkdownArtifacts(options)\nconst manifest = buildAgentManifest(docs, { project })\nconst api = await getMarkdownArtifact('api', options)\n\nconst preview = await writeAgentArtifacts({\n ...options,\n outputDir: './generated',\n project,\n dryRun: true,\n})\n\nconsole.log(manifest.recommendedReadOrder, api?.rawUrl, preview.operations)\n```\n\n`dryRun: true` plans the same ownership-aware operations without writing. A real write creates or updates Dewey-owned outputs and prunes stale outputs in the selected artifact scope; `overwrite: true` explicitly permits replacement of reviewed desired-output conflicts, including modified or unowned targets.\n\n### Artifact functions\n\n| Export | Signature / result |\n|---|---|\n| `collectMarkdownArtifacts(options?)` | Recursively parse `.md` and `.mdx`; returns sorted `Promise` |\n| `getMarkdownArtifact(slug, options?)` | Find by normalized slug or source path; returns `Promise` |\n| `getPromptArtifact(promptId, options?)` | Find a prompt under `prompts/`; returns `Promise` |\n| `parseDocArtifact(filePath, raw?, options?)` | Parse one file or supplied Markdown string into a `MarkdownArtifact` |\n| `buildAgentManifest(docs, options?)` | Build an `AgentManifest`; `includeContent` controls embedded Markdown/content |\n| `buildPromptRegistry(docs, options?)` | Build the schema-versioned prompt registry |\n| `buildContextBundle(docs, slugs, title?)` | Render selected slugs as one Markdown bundle |\n| `buildAgentArtifactFiles(options?)` | Build generated file descriptions in memory without applying them |\n| `writeAgentArtifacts(options?)` | Plan and optionally apply artifact writes; returns counts, paths, and operations |\n\n### Artifact types and classification\n\n`CollectMarkdownArtifactsOptions` accepts `rootDir?` and `docsDir?`. `WriteAgentArtifactsOptions` adds `outputDir?`, `project?`, `dryRun?`, and `overwrite?`. `AgentArtifactsProject` is `{ name: string; version?: string; tagline?: string; repository?: string }`.\n\n`MarkdownArtifactKind` is `'doc' | 'agent' | 'prompt' | 'reference' | 'proposal'`. Classification is path-based:\n\n| Path pattern | Kind |\n|---|---|\n| `prompts/**` | `prompt` |\n| `agent/**` or a slug ending in `.agent` | `agent` |\n| `reference/**` | `reference` |\n| `proposals/**` | `proposal` |\n| Everything else | `doc` |\n\nA `MarkdownArtifact` includes `id`, `slug`, `kind`, optional `promptId`, title/description, `sourcePath`, retrieval URLs, frontmatter, headings, token estimate, raw Markdown, and body content. Manifest types exported by the subpath are `AgentManifest`, `AgentManifestEntry`, `PromptManifestEntry`, `MarkdownArtifact`, `MarkdownHeading`, and the option/project types above.\n\n## React API\n\nReact is an optional presentation layer. The main source is `packages/docs/src/index.ts`; component contracts live in `packages/docs/src/components/`.\n\n```tsx\n'use client'\n\nimport {\n AutoTableOfContents,\n CopyButtons,\n DeweyProvider,\n MarkdownContent,\n} from '@arach/dewey'\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\n\nexport function DocPage({ markdown, agentMarkdown }: {\n markdown: string\n agentMarkdown: string\n}) {\n return (\n \n \n \n \n \n )\n}\n```\n\nComponents that call Dewey hooks must be descendants of `DeweyProvider`. In a Next.js App Router project, put the provider and interactive components behind a client boundary; load Markdown and generate static params on the server.\n\n### Provider and complete app\n\n| Export | Required props | Important optional props |\n|---|---|---|\n| `DeweyProvider` | `children` | `components`, `theme`, `defaultDark`, `storageKey` |\n| `DocsApp` | `docs: Record` | `config`, `currentPage`, `providerProps`; `onNavigate` is currently reserved and not invoked |\n| `DocsIndex` | `tree: PageNode[]` | `projectName`, `tagline`, `description`, `basePath`, `hero`, `showSearch`, `heroIcon`, `quickLinks`, `layout` |\n\n`FrameworkComponents` can provide a `Link` component accepting anchor props plus `href`, and an optional `Image` component accepting image props. `ThemeConfig` accepts `preset?`, partial `colors` (`primary`, `background`, `foreground`, `accent`), and partial `fonts` (`sans`, `mono`).\n\n`DocsAppConfig.layout.header` is `boolean | 'minimal'`; the other layout switches are booleans: `sidebar`, `toc`, `footer`, `prevNext`, and `breadcrumbs`.\n\n### Layout and content components\n\n| Export | Required props | Important optional props |\n|---|---|---|\n| `Header` | None | `projectName`, `homeUrl`, `backUrl`, `backLabel`, `label`, `showThemeToggle`, `actions` |\n| `Sidebar` | `tree` | `currentPage`, `projectName`, `basePath`, `isOpen`, `onClose`, `header`, `footer` |\n| `MarkdownContent` | `content` | `isDark` |\n| `TableOfContents` | None | `items`, `title`, `className`, `scrollOffset` |\n| `AutoTableOfContents` | None | `markdown`, `containerRef`, `title`, `className` |\n| `DocsLayout` | `children`, `title`, `navigation`, `projectName` | Router-neutral shell; accepts `currentPage` and a framework `LinkComponent`, with plain anchors by default; its prop type is not re-exported by the main entry point |\n| `CodeBlock` / `HeadingLink` | See source | Values are public, but their prop interfaces are not exported |\n\n`TocItem` is `{ id: string; title: string; level: number }`. Related exports are `useActiveSection`, `extractTocItems`, `extractTocFromDom`, `useTableOfContents`, and `extractSections`.\n\n### Content and agent-friendly components\n\n| Export | Required props | Important optional props / unions |\n|---|---|---|\n| `Callout` | `children` | `type?: 'info' \\| 'warning' \\| 'tip' \\| 'danger'`, `title` |\n| `Tabs` / `Tab` | `children`; `Tab` also requires `label` | `Tabs.defaultTab` |\n| `Steps` / `Step` | `children`; `Step` also requires `title` | — |\n| `Card` | `title` | `description`, `icon`, `href`, `children` |\n| `CardGrid` | `children` | `columns?: 2 \\| 3 \\| 4` |\n| `FileTree` | `items` | `defaultExpanded`; item `type?: 'file' \\| 'folder'` |\n| `ApiTable` | `properties` | `title` |\n| `Badge` | `children` | `variant`, `size?: 'sm' \\| 'md'` |\n| `CopyButtons` | `markdownContent` | `agentContent`, `showLabels`, `onCopy`, `className` |\n| `AgentContext` | `content` | `title`, `defaultExpanded`, `className` |\n| `PromptSlideout` | `isOpen`, `onClose`, `info`, `starterTemplate` | `title`, `description`, `params`, `examples`, `expectedOutput`, `className` |\n\n`BadgeVariant` is `'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple'`. `CopyButtons.onCopy` receives `'markdown' | 'agent' | 'plain'`.\n\n### Navigation types\n\n`PageNode` is a discriminated union of `PageItem`, `PageFolder`, and `PageSeparator` using `type: 'page' | 'folder' | 'separator'`. Page/navigation badge colors are `'info' | 'success' | 'warning' | 'error' | 'default'`. `NavigationConfig` is `NavigationGroup[]`.\n\nLegacy compatibility types are also exported: `NavItem`, `NavGroup`, `DocSection`, `BadgeColor`, `PageLink`, and `DocsConfig`. The legacy `BadgeColor` union is `'blue' | 'emerald' | 'purple' | 'amber' | 'rose'`.\n\n## Themes\n\nThe canonical registry is `packages/docs/src/themes.ts`.\n\n```ts\nimport {\n THEME_REGISTRY,\n VALID_THEMES,\n isThemeName,\n resolveTheme,\n type ThemeName,\n} from '@arach/dewey'\n\nconst input = process.env.DOCS_THEME\nconst theme: ThemeName = resolveTheme(input) // invalid or missing -> 'neutral'\n\nif (input && !isThemeName(input)) {\n console.warn(`Choose one of: ${VALID_THEMES.join(', ')}`)\n}\n\nconsole.log(THEME_REGISTRY[theme].cssFile)\n```\n\n`ThemeName` and `ThemePreset` contain the same values:\n\n`'neutral' | 'ocean' | 'emerald' | 'purple' | 'dusk' | 'rose' | 'github' | 'warm' | 'midnight' | 'editorial' | 'mono' | 'hudson'`\n\n`PUBLISHED_CSS_THEMES` lists presets with CSS exports; `VALID_THEMES` lists presets accepted by generated sites. Every current registry entry belongs to both lists. `resolveTheme` falls back to `'neutral'`.\n\nAll twelve presets resolve the same semantic contract in light and dark: surfaces/foregrounds, primary/secondary/accent pairs, border/ring, info/warning/error/success pairs, code and syntax colors, sidebar/header colors, typography, radii, shadows, and motion. Runtime components and generated sites consume semantic `--dw-*` variables; public components do not own literal color palettes.\n\nContract tests verify every preset and generated-site theme in both modes, reject missing/dead tokens, require WCAG AA text pairs and visible focus, and check reduced-motion behavior. `bun run --cwd packages/docs test:visual` renders representative navigation, prose, controls, semantic states, code, and tables for 12 themes × light/dark and compares 24 Playwright screenshots.\n\n## Skills and structured agent content\n\nThe skill exports are LLM prompt definitions, not deterministic generators:\n\n| Export | Type / role |\n|---|---|\n| `docsReviewAgent` | Prompt set for accuracy and drift review; result type `DocsReviewResult` |\n| `docsDesignCritic` | Prompt set for structure/design critique; result type `DocsDesignCritiqueResult` |\n| `promptSlideoutGenerator` | Prompt set for authoring slideout configuration; type `PromptSlideoutConfig` |\n| `installMdGenerator` | Prompt set for installmd.org content; type `InstallMdConfig` |\n| `improveAIPrompts` | Iterative discovery/draft/review/refinement prompt set; types `PromptImprovementPass` and `PromptQualityCriteria` |\n\n`improveAIPromptsSkill` is a deprecated alias of `improveAIPrompts` for compatibility.\n\nStructured agent content can be assembled and rendered without the CLI:\n\n```ts\nimport {\n agentContent,\n renderAgentJson,\n renderAgentMarkdown,\n} from '@arach/dewey'\n\nconst api = agentContent('api', 'API', 'Public package contracts')\n .enums('Themes', { ThemePreset: ['neutral', 'ocean'] })\n .code('Import', 'ts', \"import { defineConfig } from '@arach/dewey'\")\n .build()\n\nconst markdown = renderAgentMarkdown(api)\nconst json = renderAgentJson(api)\n```\n\nThe related exports are `AgentContentBuilder`, `renderAgentPlainText`, and the `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, and `ListSection` types.\n\n## Complete main-module export inventory\n\nThe following names are re-exported from `packages/docs/src/index.ts`.\n\n| Group | Runtime exports |\n|---|---|\n| Config | `defineConfig` |\n| Themes | `PUBLISHED_CSS_THEMES`, `THEME_REGISTRY`, `VALID_THEMES`, `isThemeName`, `resolveTheme` |\n| App/provider | `DocsApp`, `DocsAppDefault`, `DocsIndex`, `DeweyProvider`, `useDewey`, `useTheme`, `useComponents`, `useLink` |\n| Layout/content | `Header`, `DocsLayout`, `MarkdownContent`, `CodeBlock`, `HeadingLink`, `Sidebar`, `TableOfContents`, `AutoTableOfContents`, `useActiveSection`, `extractTocItems`, `extractTocFromDom` |\n| UI | `Callout`, `Tabs`, `Tab`, `Steps`, `Step`, `Card`, `CardGrid`, `FileTree`, `ApiTable`, `Badge` |\n| Agent UI | `CopyButtons`, `AgentContext`, `PromptSlideout` |\n| Skills | `promptSlideoutGenerator`, `docsReviewAgent`, `docsDesignCritic`, `installMdGenerator`, `improveAIPrompts`, `improveAIPromptsSkill` |\n| Hooks/utilities | `useDarkMode`, `useTableOfContents`, `extractSections`, `cn`, `resolveIcon`, `commonIcons` |\n| Agent content | `agentContent`, `AgentContentBuilder`, `renderAgentMarkdown`, `renderAgentJson`, `renderAgentPlainText` |\n\n| Type group | Type exports |\n|---|---|\n| Config/themes | `AgentRule`, `DeweyConfig`, `InstallConfig`, `ProjectType`, `ThemeDefinition`, `ThemeName`, `ThemePreset` |\n| App/provider | `DocsAppProps`, `DocsAppConfig`, `DocsIndexProps`, `DeweyProviderProps`, `DeweyContextValue`, `ThemeConfig`, `FrameworkComponents` |\n| Components | `HeaderProps`, `DocsLayoutProps`, `MarkdownContentProps`, `SidebarProps`, `AutoTocProps`, `TableOfContentsProps`, `TocItem`, `CalloutProps`, `CalloutType`, `TabsProps`, `TabProps`, `StepsProps`, `StepProps`, `CardProps`, `CardGridProps`, `FileTreeProps`, `FileTreeItem`, `ApiTableProps`, `ApiProperty`, `BadgeProps`, `BadgeVariant`, `CopyButtonsProps`, `AgentContextProps`, `PromptSlideoutProps`, `PromptParam` |\n| Skills/content | `PromptSlideoutConfig`, `DocsReviewResult`, `DocsDesignCritiqueResult`, `InstallMdConfig`, `PromptImprovementPass`, `PromptQualityCriteria`, `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, `ListSection` |\n| Navigation/utilities | `PageTree`, `PageNode`, `PageItem`, `PageFolder`, `PageSeparator`, `FlatPage`, `NavigationConfig`, `NavigationGroup`, `NavigationItem`, `CommonIconName` |\n| Legacy | `NavItem`, `NavGroup`, `DocSection`, `BadgeColor`, `PageLink`, `DocsConfig` |\n\nFor command flags and workflows, use the [CLI reference](./cli.md). For a complete server/client integration, use [Integrate into an existing site](./integrate-existing-site.md)." }, { "id": "cli", "slug": "cli", "kind": "doc", "title": "CLI Reference", "description": "Dewey commands and their main options", "sourcePath": "docs/cli.md", "url": "/docs/cli", "rawUrl": "/agent/raw/docs/cli.md", "headings": [ { "depth": 2, "text": "Run Dewey", "anchor": "run-dewey" }, { "depth": 2, "text": "Commands", "anchor": "commands" }, { "depth": 2, "text": "Project-aware initialization", "anchor": "project-aware-initialization" }, { "depth": 2, "text": "Recommended order", "anchor": "recommended-order" }, { "depth": 2, "text": "Generate options", "anchor": "generate-options" }, { "depth": 2, "text": "Machine-readable checks", "anchor": "machine-readable-checks" }, { "depth": 2, "text": "Generated-site maintenance", "anchor": "generated-site-maintenance" }, { "depth": 2, "text": "Error handling in automation", "anchor": "error-handling-in-automation" } ], "tokensEstimate": 1184, "frontmatter": { "title": "CLI Reference", "description": "Dewey commands and their main options", "order": 3, "group": "Reference", "groupId": "reference" }, "markdown": "---\ntitle: CLI Reference\ndescription: Dewey commands and their main options\norder: 3\ngroup: Reference\ngroupId: reference\n---\n\nDewey audits documentation, generates agent-facing artifacts, and publishes the same Markdown through optional site templates.\n\n## Run Dewey\n\nInstall Dewey in a project and use its local binary:\n\n```bash\nbun add -d @arach/dewey\nbunx dewey --help\n```\n\nFor a one-off run without installing it first, address the scoped package directly:\n\n```bash\nbunx @arach/dewey@latest --help\n```\n\n## Commands\n\n| Command | Purpose |\n|---|---|\n| `dewey init` | Create a documentation structure and `dewey.config.ts` |\n| `dewey audit` | Check documentation completeness and quality |\n| `dewey generate` | Generate `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and `agent/` artifacts |\n| `dewey agent` | Evaluate agent-readiness and recommend improvements |\n| `dewey create ` | Publish Markdown with a Next.js or Astro site template |\n| `dewey update [dir]` | Refresh Dewey-owned files in a generated site |\n| `dewey eject [dir]` | Take ownership of a generated component |\n\n## Project-aware initialization\n\n`init --type` accepts `generic`, `npm-package`, `cli-tool`, `react-library`, `macos-app`, or `monorepo`. Invalid values fail with the complete valid-value list. The selected type changes the generated human/agent page pair, required-document configuration, installation defaults, verification command, and evidence that `audit` / `agent` expect.\n\n```bash\nbunx dewey init --type cli-tool\nbunx dewey init --type react-library\nbunx dewey init --type monorepo\n```\n\n| Type | Focus page | Evidence expected |\n|---|---|---|\n| `generic` | `architecture` | System structure plus a public interface or integration boundary |\n| `npm-package` | `api` | Package-manager install command plus typed public API |\n| `cli-tool` | `commands` | Commands/options plus executable shell usage |\n| `react-library` | `components` | Component props plus JSX/TSX rendering example |\n| `macos-app` | `architecture` | macOS lifecycle plus Swift/SwiftUI/Xcode evidence |\n| `monorepo` | `packages` | Workspace organization plus package/application paths |\n\n## Recommended order\n\n`init` → author docs → `generate` → `audit` → `agent` → optional human UI.\n\n| Goal | Path |\n|---|---|\n| Agent-ready artifacts only | Stop after `generate` / `audit` / `agent` |\n| Docs UI inside an existing React/Next.js app | [Integrate into an existing site](./integrate-existing-site.md) |\n| New standalone docs site | `dewey create --source ./docs --template nextjs` |\n\nSee [Quickstart](./quickstart.md) for the full onboarding sequence.\n\n## Generate options\n\n```bash\ndewey generate --source ./docs --output ./generated\ndewey generate --agents-md\ndewey generate --llms-txt\ndewey generate --docs-json\ndewey generate --install-md\ndewey generate --agent-artifacts\ndewey generate --dry-run\ndewey generate --overwrite\n```\n\n`--source` overrides `docs.path` for a run. An empty `agent.sections` array includes every human-readable Markdown document recursively; provide section IDs only when you want an explicit allowlist.\n\nBefore writing, `generate` prints a plan containing every create, update, preserve, and stale-file deletion. Use `--dry-run` to preview the same plan without creating the output directory or changing files. Dewey tracks owned outputs in `.dewey-generated.json`; unknown or edited desired files block the write. After reviewing the preview, `--overwrite` can explicitly replace those conflicts and adopt the resulting outputs.\n\n`generate`, `create`, and the programmatic artifact API share one recursive discovery/frontmatter pipeline. A default `generate` builds the retrieval manifest once, derives link tables and bundles from that manifest, and keeps full content in purpose-built surfaces: raw Markdown and bundles, document content in `agent/docs.json`, and prompt content in `agent/prompts.json`. `agent/context.md` and `agent/context.json` are retrieval indexes, not additional full-content copies.\n\n`llms.txt` summaries prefer frontmatter descriptions, then prose, lists, headings, and finally the page title. Prompt URLs normalize the `prompts/` prefix once. Generated installation commands preserve scoped package names such as `@scope/package`.\n\n`create` uses the same discovered documents and then composes the agent-artifact writer into the new site. Generated Next.js and Astro package manifests pin the tested dependency versions; Pagefind is a declared dependency rather than an unpinned `bunx` download. Unknown themes emit a warning before falling back to `neutral`.\n\n## Machine-readable checks\n\nBoth audit commands can emit JSON for CI and other tooling:\n\n```bash\ndewey audit --json\ndewey agent --json\n```\n\n`audit` is deterministic structural validation. `agent` is evidence-based readiness coaching: it scores the documentation surface and recommends next actions, but does not write files.\n\nBoth JSON reports add:\n\n- `projectType`: selected profile, label, pass/fail state, and the evidence found for each requirement.\n- `drift`: `clean`, `issues`, or `not-applicable`, counts for checked pairs/source files/references/contracts, and structured issues.\n\nHuman output always summarizes project-type evidence and drift. Add `--verbose` for matched documents and issue codes. `audit` reports these findings as recommendations without changing its structural page score; `agent` uses project-type evidence in Project Context and uses unresolved contract drift when judging valid-value quality.\n\nDrift checks cover missing/orphan `.agent.md` counterparts, missing cited source paths, human/agent literal-union mismatches, and literal union/enum differences between docs and conventional or configured source trees. The analysis is regex/evidence based: it does not prove semantic prose equivalence, execute examples, or understand arbitrary computed TypeScript types. Treat a clean report as a focused consistency check, not a substitute for review.\n\n## Generated-site maintenance\n\n`update` and `eject` have an ownership contract; see [Maintaining generated sites](./maintenance.md) for adoption, dry runs, ejected ownership, backups, and recovery. The obsolete `--refresh-nav` option has been removed: regenerate source artifacts with `dewey generate`, while `update` only refreshes Dewey-owned scaffold files.\n\n## Error handling in automation\n\nCommands reject invalid configuration and return a non-zero exit status. In CI, capture JSON only after checking the command succeeded:\n\n```bash\nif ! report=\"$(bunx dewey audit --json)\"; then\n echo \"Dewey audit failed before producing a valid report\" >&2\n exit 1\nfi\nprintf '%s\\n' \"$report\"\n```\n", "content": "Dewey audits documentation, generates agent-facing artifacts, and publishes the same Markdown through optional site templates.\n\n## Run Dewey\n\nInstall Dewey in a project and use its local binary:\n\n```bash\nbun add -d @arach/dewey\nbunx dewey --help\n```\n\nFor a one-off run without installing it first, address the scoped package directly:\n\n```bash\nbunx @arach/dewey@latest --help\n```\n\n## Commands\n\n| Command | Purpose |\n|---|---|\n| `dewey init` | Create a documentation structure and `dewey.config.ts` |\n| `dewey audit` | Check documentation completeness and quality |\n| `dewey generate` | Generate `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and `agent/` artifacts |\n| `dewey agent` | Evaluate agent-readiness and recommend improvements |\n| `dewey create ` | Publish Markdown with a Next.js or Astro site template |\n| `dewey update [dir]` | Refresh Dewey-owned files in a generated site |\n| `dewey eject [dir]` | Take ownership of a generated component |\n\n## Project-aware initialization\n\n`init --type` accepts `generic`, `npm-package`, `cli-tool`, `react-library`, `macos-app`, or `monorepo`. Invalid values fail with the complete valid-value list. The selected type changes the generated human/agent page pair, required-document configuration, installation defaults, verification command, and evidence that `audit` / `agent` expect.\n\n```bash\nbunx dewey init --type cli-tool\nbunx dewey init --type react-library\nbunx dewey init --type monorepo\n```\n\n| Type | Focus page | Evidence expected |\n|---|---|---|\n| `generic` | `architecture` | System structure plus a public interface or integration boundary |\n| `npm-package` | `api` | Package-manager install command plus typed public API |\n| `cli-tool` | `commands` | Commands/options plus executable shell usage |\n| `react-library` | `components` | Component props plus JSX/TSX rendering example |\n| `macos-app` | `architecture` | macOS lifecycle plus Swift/SwiftUI/Xcode evidence |\n| `monorepo` | `packages` | Workspace organization plus package/application paths |\n\n## Recommended order\n\n`init` → author docs → `generate` → `audit` → `agent` → optional human UI.\n\n| Goal | Path |\n|---|---|\n| Agent-ready artifacts only | Stop after `generate` / `audit` / `agent` |\n| Docs UI inside an existing React/Next.js app | [Integrate into an existing site](./integrate-existing-site.md) |\n| New standalone docs site | `dewey create --source ./docs --template nextjs` |\n\nSee [Quickstart](./quickstart.md) for the full onboarding sequence.\n\n## Generate options\n\n```bash\ndewey generate --source ./docs --output ./generated\ndewey generate --agents-md\ndewey generate --llms-txt\ndewey generate --docs-json\ndewey generate --install-md\ndewey generate --agent-artifacts\ndewey generate --dry-run\ndewey generate --overwrite\n```\n\n`--source` overrides `docs.path` for a run. An empty `agent.sections` array includes every human-readable Markdown document recursively; provide section IDs only when you want an explicit allowlist.\n\nBefore writing, `generate` prints a plan containing every create, update, preserve, and stale-file deletion. Use `--dry-run` to preview the same plan without creating the output directory or changing files. Dewey tracks owned outputs in `.dewey-generated.json`; unknown or edited desired files block the write. After reviewing the preview, `--overwrite` can explicitly replace those conflicts and adopt the resulting outputs.\n\n`generate`, `create`, and the programmatic artifact API share one recursive discovery/frontmatter pipeline. A default `generate` builds the retrieval manifest once, derives link tables and bundles from that manifest, and keeps full content in purpose-built surfaces: raw Markdown and bundles, document content in `agent/docs.json`, and prompt content in `agent/prompts.json`. `agent/context.md` and `agent/context.json` are retrieval indexes, not additional full-content copies.\n\n`llms.txt` summaries prefer frontmatter descriptions, then prose, lists, headings, and finally the page title. Prompt URLs normalize the `prompts/` prefix once. Generated installation commands preserve scoped package names such as `@scope/package`.\n\n`create` uses the same discovered documents and then composes the agent-artifact writer into the new site. Generated Next.js and Astro package manifests pin the tested dependency versions; Pagefind is a declared dependency rather than an unpinned `bunx` download. Unknown themes emit a warning before falling back to `neutral`.\n\n## Machine-readable checks\n\nBoth audit commands can emit JSON for CI and other tooling:\n\n```bash\ndewey audit --json\ndewey agent --json\n```\n\n`audit` is deterministic structural validation. `agent` is evidence-based readiness coaching: it scores the documentation surface and recommends next actions, but does not write files.\n\nBoth JSON reports add:\n\n- `projectType`: selected profile, label, pass/fail state, and the evidence found for each requirement.\n- `drift`: `clean`, `issues`, or `not-applicable`, counts for checked pairs/source files/references/contracts, and structured issues.\n\nHuman output always summarizes project-type evidence and drift. Add `--verbose` for matched documents and issue codes. `audit` reports these findings as recommendations without changing its structural page score; `agent` uses project-type evidence in Project Context and uses unresolved contract drift when judging valid-value quality.\n\nDrift checks cover missing/orphan `.agent.md` counterparts, missing cited source paths, human/agent literal-union mismatches, and literal union/enum differences between docs and conventional or configured source trees. The analysis is regex/evidence based: it does not prove semantic prose equivalence, execute examples, or understand arbitrary computed TypeScript types. Treat a clean report as a focused consistency check, not a substitute for review.\n\n## Generated-site maintenance\n\n`update` and `eject` have an ownership contract; see [Maintaining generated sites](./maintenance.md) for adoption, dry runs, ejected ownership, backups, and recovery. The obsolete `--refresh-nav` option has been removed: regenerate source artifacts with `dewey generate`, while `update` only refreshes Dewey-owned scaffold files.\n\n## Error handling in automation\n\nCommands reject invalid configuration and return a non-zero exit status. In CI, capture JSON only after checking the command succeeded:\n\n```bash\nif ! report=\"$(bunx dewey audit --json)\"; then\n echo \"Dewey audit failed before producing a valid report\" >&2\n exit 1\nfi\nprintf '%s\\n' \"$report\"\n```" }, { "id": "integrate-existing-site", "slug": "integrate-existing-site", "kind": "doc", "title": "Integrate into an existing site", "description": "Embed Dewey docs components in an existing React or Next.js app while keeping agent generation as the core contract", "sourcePath": "docs/integrate-existing-site.md", "url": "/docs/integrate-existing-site", "rawUrl": "/agent/raw/docs/integrate-existing-site.md", "headings": [ { "depth": 2, "text": "When to embed vs scaffold", "anchor": "when-to-embed-vs-scaffold" }, { "depth": 2, "text": "Prerequisites", "anchor": "prerequisites" }, { "depth": 2, "text": "Package and CSS installation", "anchor": "package-and-css-installation" }, { "depth": 3, "text": "CSS entry points", "anchor": "css-entry-points" }, { "depth": 3, "text": "Import path note", "anchor": "import-path-note" }, { "depth": 2, "text": "Recommended architecture", "anchor": "recommended-architecture" }, { "depth": 2, "text": "Server-to-client wrapper", "anchor": "server-to-client-wrapper" }, { "depth": 3, "text": "1. Client provider", "anchor": "1-client-provider" }, { "depth": 3, "text": "2. Server page + client content", "anchor": "2-server-page-client-content" }, { "depth": 2, "text": "Static export configuration", "anchor": "static-export-configuration" }, { "depth": 2, "text": "Recursive content loading", "anchor": "recursive-content-loading" }, { "depth": 3, "text": "Optional navigation from docs.json", "anchor": "optional-navigation-from-docs-json" }, { "depth": 2, "text": "Themes at runtime", "anchor": "themes-at-runtime" }, { "depth": 2, "text": "Docs layout shell (Header + Sidebar)", "anchor": "docs-layout-shell-header-sidebar" }, { "depth": 2, "text": "Dewey generation alongside the site", "anchor": "dewey-generation-alongside-the-site" }, { "depth": 3, "text": "Onboarding sequence (shared with greenfield)", "anchor": "onboarding-sequence-shared-with-greenfield" }, { "depth": 3, "text": "Serve agent files from the static host", "anchor": "serve-agent-files-from-the-static-host" }, { "depth": 2, "text": "CI", "anchor": "ci" }, { "depth": 1, "text": ".github/workflows/docs.yml (illustrative)", "anchor": "github-workflows-docs-yml-illustrative" }, { "depth": 2, "text": "Monorepo notes", "anchor": "monorepo-notes" }, { "depth": 2, "text": "Checklist", "anchor": "checklist" }, { "depth": 2, "text": "Related", "anchor": "related" } ], "tokensEstimate": 3226, "frontmatter": { "title": "Integrate into an existing site", "description": "Embed Dewey docs components in an existing React or Next.js app while keeping agent generation as the core contract", "order": 6, "group": "Guides", "groupId": "guides" }, "markdown": "---\ntitle: Integrate into an existing site\ndescription: Embed Dewey docs components in an existing React or Next.js app while keeping agent generation as the core contract\norder: 6\ngroup: Guides\ngroupId: guides\n---\n\nDewey is a **docs agent** first: it audits, scores, and generates agent-ready artifacts (`AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and the `agent/` retrieval surface). The React components are an **optional presentation layer** so the same Markdown can power a human-facing docs UI inside a site you already own.\n\nThis guide is for teams that already have a React or Next.js app and want docs under a route such as `/docs` — without running `dewey create` as a separate site. For a greenfield docs site, see [Quickstart](./quickstart.md) and `dewey create`.\n\n## When to embed vs scaffold\n\n| Path | Use when |\n|------|----------|\n| **Embed components** (this guide) | You already have React/Next.js routing, layout, design system, or deploy pipeline |\n| **`dewey create`** | You want a standalone docs site generated from Markdown |\n| **Generate only** | You need agent artifacts and no docs UI |\n\nEmbedding does not replace `dewey init` / `audit` / `generate` / `agent`. Keep the CLI pipeline for judgment and retrieval; use components only to render Markdown for humans.\n\n## Prerequisites\n\n| Requirement | Notes |\n|-------------|--------|\n| Node.js 18+ | |\n| Bun 1.3+ (recommended) | Examples below use Bun |\n| React 18 or 19 | Peer dependency of `@arach/dewey` |\n| Next.js App Router | Patterns below target App Router; adapt for Pages Router if needed |\n| Existing Markdown under `docs/` | Prefer the [agent content pattern](./overview.md#agent-content-pattern): `.md` + `.agent.md` |\n\n## Package and CSS installation\n\n```bash\nbun add @arach/dewey gray-matter\n```\n\n- Runtime dependency (not only `-d`) when the site imports Dewey components.\n- `gray-matter` is the usual choice for frontmatter when you load files from disk (same approach as `dewey create --template nextjs`).\n- No router package is required by Dewey. `react-router-dom` is not a peer dependency; pass a framework link adapter where needed.\n\n### CSS entry points\n\nImport base styles, design tokens, and one color theme in a root layout or global CSS entry:\n\n```tsx\n// app/layout.tsx (or app/docs/layout.tsx)\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\n```\n\n| Export | Purpose |\n|--------|---------|\n| `@arach/dewey/css` | Full bundle (base + tokens + default theme wiring) |\n| `@arach/dewey/css/base.css` | Reset and base rules |\n| `@arach/dewey/css/tokens` | Semantic `--dw-*` CSS variables |\n| `@arach/dewey/css/colors/.css` | Color preset |\n| `@arach/dewey/styles` | Alias of the full CSS bundle |\n| `@arach/dewey/tailwind` | Tailwind preset for `--dw-*` utilities |\n\n**Themes:** `neutral`, `ocean`, `emerald`, `purple`, `dusk`, `rose`, `github`, `warm`, `midnight`, `editorial`, `mono`, `hudson`.\n\nTokens use the `--dw-*` prefix so they rarely collide with a host design system. Dark mode follows a `.dark` class on an ancestor (DeweyProvider manages this when you use the provider).\n\nThe complete semantic contract covers surfaces and foregrounds; primary, secondary, and accent pairs; border/ring; info, warning, error, and success pairs; code and syntax colors; sidebar/header colors; typography, radii, shadows, and motion. Every public component and generated theme consumes this contract. The package verifies WCAG AA pairs, focus and reduced motion, plus 24 representative Playwright screenshots (12 themes × light/dark).\n\n### Import path note\n\n`@arach/dewey` and `@arach/dewey/react` resolve to the **same** module surface. Prefer `@arach/dewey` in new code; treat `/react` as a compatibility alias, not a separate React-only package.\n\n```tsx\nimport {\n DeweyProvider,\n Header,\n Sidebar,\n MarkdownContent,\n AutoTableOfContents,\n CopyButtons,\n} from '@arach/dewey'\n```\n\n## Recommended architecture\n\nKeep a clear server/client boundary (required for static export and App Router):\n\n```\napp/\n layout.tsx # server: fonts, CSS imports, Providers shell\n providers.tsx # client: DeweyProvider + Next.js Link/Image\n docs/\n layout.tsx # client or server shell: Header + Sidebar\n [...slug]/\n page.tsx # server: load markdown, generateStaticParams\n content.tsx # client: MarkdownContent, TOC, CopyButtons\nlib/\n dewey.tsx # components map + providerProps + siteConfig\n docs.ts # recursive fs loaders (server-only)\n navigation.ts # nav tree from docs.json (optional)\ndocs/ # source markdown (project root or monorepo package)\n```\n\nThis mirrors what `dewey create --template nextjs` scaffolds, without forcing a separate project.\n\n## Server-to-client wrapper\n\nDewey layout and content components use React hooks (theme, TOC scroll-spy, copy buttons). In the App Router they must run as **client** components. Static export and `generateStaticParams` must run on the **server**.\n\n**Pattern:** server page loads and serializes doc data → client content component renders Dewey UI.\n\n### 1. Client provider\n\n```tsx\n// app/providers.tsx\n'use client'\n\nimport { DeweyProvider } from '@arach/dewey'\nimport type { DeweyProviderProps } from '@arach/dewey'\nimport type { AnchorHTMLAttributes } from 'react'\nimport Link from 'next/link'\n\ntype DeweyLinkProps = AnchorHTMLAttributes & { href: string }\nconst DeweyLink = ({ href, ...props }: DeweyLinkProps) => \n\nconst providerProps: Omit = {\n theme: 'ocean',\n components: { Link: DeweyLink },\n}\n\nexport function Providers({ children }: { children: React.ReactNode }) {\n return {children}\n}\n```\n\nWire `Providers` once in the root layout (server component):\n\n```tsx\n// app/layout.tsx\nimport type { Metadata } from 'next'\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\nimport { Providers } from './providers'\n\nexport const metadata: Metadata = {\n title: 'Project docs',\n}\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n \n )\n}\n```\n\n`suppressHydrationWarning` on `` avoids noise from theme class hydration.\n\n### 2. Server page + client content\n\n```tsx\n// app/docs/[...slug]/page.tsx\nimport { getDocBySlug, getAllDocSlugs } from '@/lib/docs'\nimport { DocContent } from './content'\n\ninterface PageProps {\n params: Promise<{ slug: string[] }>\n}\n\nexport async function generateStaticParams() {\n const slugs = getAllDocSlugs()\n return slugs.map((slug) => ({ slug: slug.split('/') }))\n}\n\nexport default async function DocPage({ params }: PageProps) {\n const { slug } = await params\n const doc = getDocBySlug(slug.join('/'))\n\n if (!doc) {\n return
Page not found
\n }\n\n return \n}\n```\n\n```tsx\n// app/docs/[...slug]/content.tsx\n'use client'\n\nimport { MarkdownContent, AutoTableOfContents, CopyButtons } from '@arach/dewey'\nimport type { DocData } from '@/lib/docs'\n\nexport function DocContent({ doc }: { doc: DocData }) {\n return (\n
\n
\n

{doc.title}

\n {doc.description ?

{doc.description}

: null}\n \n \n
\n \n
\n )\n}\n```\n\nPass only serializable props (`string`, plain objects) across the boundary — not file handles or class instances.\n\n## Static export configuration\n\nFor fully static hosting (GitHub Pages, S3, many CDNs):\n\n```js\n// next.config.js\n/** @type {import('next').NextConfig} */\nconst nextConfig = {\n output: 'export',\n images: { unoptimized: true },\n transpilePackages: ['@arach/dewey'],\n}\n\nmodule.exports = nextConfig\n```\n\n| Setting | Why |\n|---------|-----|\n| `output: 'export'` | Emits a static `out/` directory |\n| `images.unoptimized` | Required when using `output: 'export'` with Next Image |\n| `transpilePackages: ['@arach/dewey']` | Ensures Dewey ESM ships correctly through Next’s bundler |\n\n`generateStaticParams` must return every docs slug you want pre-rendered. Without it, nested routes are missing from the export.\n\nIf the host app is **not** a pure static export, you can still use the same server/client split and omit `output: 'export'`; keep `transpilePackages` when bundling Dewey.\n\n## Recursive content loading\n\nDiscover human Markdown recursively; exclude `.agent.md` from the page list, then attach an agent counterpart when present.\n\n```ts\n// lib/docs.ts\nimport fs from 'fs'\nimport path from 'path'\nimport matter from 'gray-matter'\n\nexport interface DocData {\n slug: string\n title: string\n description?: string\n content: string\n agentContent?: string\n order: number\n}\n\nconst docsDirectory = path.join(process.cwd(), 'docs')\n\nfunction walkDir(dir: string, base = ''): string[] {\n const results: string[] = []\n try {\n for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n const rel = base ? `${base}/${entry.name}` : entry.name\n if (entry.isDirectory()) {\n results.push(...walkDir(path.join(dir, entry.name), rel))\n } else {\n results.push(rel)\n }\n }\n } catch {\n // missing directory\n }\n return results\n}\n\nexport function getAllDocSlugs(): string[] {\n return walkDir(docsDirectory)\n .filter((file) => file.endsWith('.md') && !file.endsWith('.agent.md'))\n .map((file) => file.replace(/\\.md$/, ''))\n}\n\nexport function getDocBySlug(slug: string): DocData | null {\n try {\n const fullPath = path.join(docsDirectory, `${slug}.md`)\n const fileContents = fs.readFileSync(fullPath, 'utf-8')\n const { data, content } = matter(fileContents)\n\n let agentContent: string | undefined\n const agentCandidates = [\n path.join(docsDirectory, `${slug}.agent.md`),\n path.join(docsDirectory, 'agent', `${slug}.agent.md`),\n ]\n const agentPath = agentCandidates.find((p) => fs.existsSync(p))\n if (agentPath) {\n const agentFile = fs.readFileSync(agentPath, 'utf-8')\n const { content: agentBody } = matter(agentFile)\n agentContent = agentBody.trim() || undefined\n }\n\n return {\n slug,\n title: (data.title as string) || slug,\n description: data.description as string | undefined,\n content: content.trim(),\n agentContent,\n order: (data.order as number) || 999,\n }\n } catch {\n return null\n }\n}\n```\n\n| Rule | Behavior |\n|------|----------|\n| Human page | `docs/**/*.md` excluding `*.agent.md` |\n| Colocated agent | `docs/guides/install.agent.md` next to `docs/guides/install.md` |\n| Nested agent folder | `docs/agent/guides/install.agent.md` (or `docs/agent/overview.agent.md` for top-level pages) |\n| Nested routes | Slug `guides/install` → URL `/docs/guides/install` |\n\nMatch Dewey’s generate behavior: an empty `agent.sections` array includes every human-readable Markdown document recursively.\n\n### Optional navigation from `docs.json`\n\nAfter `bunx dewey generate`, import the generated manifest for sidebar groups:\n\n```ts\n// lib/navigation.ts\nimport docsJson from '../../docs.json'\nimport type { PageNode } from '@arach/dewey'\n\nexport function getNavTree(): PageNode[] {\n return (docsJson as { groups: { title: string; items: { id: string; title: string; description?: string }[] }[] })\n .groups.map((group) => ({\n type: 'folder' as const,\n name: group.title,\n defaultOpen: true,\n children: group.items.map((item) => ({\n type: 'page' as const,\n id: item.id,\n name: item.title,\n description: item.description,\n })),\n }))\n}\n```\n\nRegenerate `docs.json` whenever nav or page set changes so the UI and agent artifacts stay aligned.\n\n## Themes at runtime\n\nPreset via provider:\n\n```tsx\n\n {children}\n\n```\n\nOr partial overrides:\n\n```tsx\n\n {children}\n\n```\n\nPair the CSS file (`@arach/dewey/css/colors/purple.css`) with the matching `theme` prop so tokens and components stay in sync.\n\nOptional Tailwind:\n\n```ts\n// tailwind.config.ts\nimport type { Config } from 'tailwindcss'\nimport deweyPreset from '@arach/dewey/tailwind'\n\nexport default {\n presets: [deweyPreset],\n content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],\n} satisfies Config\n```\n\n## Docs layout shell (Header + Sidebar)\n\n```tsx\n// app/docs/layout.tsx\n'use client'\n\nimport { usePathname } from 'next/navigation'\nimport { Header, Sidebar } from '@arach/dewey'\nimport { getNavTree } from '@/lib/navigation'\n\nconst basePath = '/docs'\nconst projectName = 'My Project'\nconst defaultPage = 'overview'\n\nexport default function DocsLayout({ children }: { children: React.ReactNode }) {\n const pathname = usePathname()\n const currentPage =\n pathname.replace(new RegExp(`^${basePath}/?`), '').replace(/\\/$/, '') || defaultPage\n\n return (\n <>\n
\n
\n \n
{children}
\n
\n \n )\n}\n```\n\nPrefer composing `Header`, `Sidebar`, `MarkdownContent`, and `AutoTableOfContents` when you want full control. The packaged `DocsLayout` is also router-neutral: it uses anchors by default and accepts `LinkComponent` plus `currentPage`.\n\n```tsx\nimport { DocsLayout, MarkdownContent } from '@arach/dewey'\n\n\n \n\n```\n\n## Dewey generation alongside the site\n\nKeep agent generation in the **same repository** as the host app. Components render Markdown; generation produces retrieval artifacts for agents and CI.\n\n### Onboarding sequence (shared with greenfield)\n\n| Step | Command | Role |\n|------|---------|------|\n| 1. Install | `bun add @arach/dewey gray-matter` | Package on the site; CLI available via `bunx` |\n| 2. Init (once) | `bunx dewey init` | `docs/` + `dewey.config.ts` if missing |\n| 3. Author | Write `.md` + `.agent.md` | Human and agent sources |\n| 4. Generate | `bunx dewey generate` | Artifacts + `docs.json` for nav/retrieval |\n| 5. Audit | `bunx dewey audit` | Deterministic structure/completeness checks |\n| 6. Score | `bunx dewey agent` | Agent-readiness judgment (0–100) |\n| 7. Render | Your Next/React routes | Optional human UI (this guide) |\n| 8. Optional scaffold | `bunx dewey create …` | Only if you want a **separate** generated site |\n\nSuggested `package.json` scripts:\n\n```json\n{\n \"scripts\": {\n \"docs:generate\": \"bunx dewey generate\",\n \"docs:audit\": \"bunx dewey audit\",\n \"docs:agent\": \"bunx dewey agent\",\n \"prebuild\": \"bun run docs:generate\",\n \"dev\": \"next dev\",\n \"build\": \"next build\"\n }\n}\n```\n\nCustom paths:\n\n```bash\nbunx dewey generate --source ./content/docs --output ./public\n```\n\n`--source` overrides `docs.path` for one run. Empty `agent.sections: []` includes all human Markdown recursively.\n\n### Serve agent files from the static host\n\nCopy or generate into `public/` (or your static asset root) so agents can fetch:\n\n| Artifact | Typical public URL |\n|----------|-------------------|\n| `llms.txt` | `/llms.txt` |\n| `AGENTS.md` | `/AGENTS.md` |\n| `install.md` | `/install.md` |\n| `agent/**` | `/agent/**` |\n\nExample: set `docs.output` (or `--output`) to `public` for files you want deployed with the site, or add a small copy step after generate.\n\n## CI\n\nEnforce documentation quality without blocking only on the UI build:\n\n```yaml\n# .github/workflows/docs.yml (illustrative)\nname: docs\non:\n pull_request:\n paths: ['docs/**', 'dewey.config.ts', 'package.json']\n\njobs:\n dewey:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v2\n - run: bun install\n - run: bunx dewey generate\n - run: bunx dewey audit --json\n - run: bunx dewey agent --json\n # Optional: fail if score below policy by parsing agent JSON in a follow-up step\n```\n\n| Command | CI use |\n|---------|--------|\n| `dewey generate` | Ensure artifacts are reproducible and committed or built in-pipeline |\n| `dewey audit --json` | Machine-readable structure checks |\n| `dewey agent --json` | Machine-readable readiness score |\n\nRun generate **before** `next build` when the app imports `docs.json` or serves files from `public/`.\n\n## Monorepo notes\n\n| Setup | Approach |\n|-------|----------|\n| Docs package + app package | Point `--source` at the docs package path; depend on `@arach/dewey` from the app |\n| Shared `docs/` at repo root | `process.cwd()` in Next is the app package — set `docsDirectory` to a path relative to the monorepo root (or symlink `docs` into the app) |\n| Generate once for many apps | Run `dewey generate` at the repo root; publish `agent/` and `docs.json` as static assets |\n\n## Checklist\n\n- [ ] `@arach/dewey` + CSS theme imported\n- [ ] `DeweyProvider` in a client `Providers` wrapper with Next `Link` / `Image`\n- [ ] Server `page.tsx` + client `content.tsx` split\n- [ ] `generateStaticParams` covers recursive slugs (if static export)\n- [ ] Recursive loader skips `.agent.md` for routes but loads agent siblings for `CopyButtons` / agent view\n- [ ] `bunx dewey generate` (and optional audit/agent) in local and CI pipelines\n- [ ] Agent artifacts reachable at stable URLs if you expose them publicly\n\n## Related\n\n- [Quickstart](./quickstart.md) — full init → generate → optional create sequence\n- [CLI Reference](./cli.md) — flags for generate, audit, agent, create\n- [Overview](./overview.md) — product positioning and agent content pattern\n- [Skills](./skills.md) — LLM prompt skills for review and install.md\n- [Maintaining generated sites](./maintenance.md) — update/eject ownership, adoption, backups, recovery, and release checks\n\nFor a ready-made Next.js project instead of embedding, use:\n\n```bash\nbunx dewey create my-docs --source ./docs --template nextjs --theme ocean\ncd my-docs && bun install && bun run dev\n```\n", "content": "Dewey is a **docs agent** first: it audits, scores, and generates agent-ready artifacts (`AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and the `agent/` retrieval surface). The React components are an **optional presentation layer** so the same Markdown can power a human-facing docs UI inside a site you already own.\n\nThis guide is for teams that already have a React or Next.js app and want docs under a route such as `/docs` — without running `dewey create` as a separate site. For a greenfield docs site, see [Quickstart](./quickstart.md) and `dewey create`.\n\n## When to embed vs scaffold\n\n| Path | Use when |\n|------|----------|\n| **Embed components** (this guide) | You already have React/Next.js routing, layout, design system, or deploy pipeline |\n| **`dewey create`** | You want a standalone docs site generated from Markdown |\n| **Generate only** | You need agent artifacts and no docs UI |\n\nEmbedding does not replace `dewey init` / `audit` / `generate` / `agent`. Keep the CLI pipeline for judgment and retrieval; use components only to render Markdown for humans.\n\n## Prerequisites\n\n| Requirement | Notes |\n|-------------|--------|\n| Node.js 18+ | |\n| Bun 1.3+ (recommended) | Examples below use Bun |\n| React 18 or 19 | Peer dependency of `@arach/dewey` |\n| Next.js App Router | Patterns below target App Router; adapt for Pages Router if needed |\n| Existing Markdown under `docs/` | Prefer the [agent content pattern](./overview.md#agent-content-pattern): `.md` + `.agent.md` |\n\n## Package and CSS installation\n\n```bash\nbun add @arach/dewey gray-matter\n```\n\n- Runtime dependency (not only `-d`) when the site imports Dewey components.\n- `gray-matter` is the usual choice for frontmatter when you load files from disk (same approach as `dewey create --template nextjs`).\n- No router package is required by Dewey. `react-router-dom` is not a peer dependency; pass a framework link adapter where needed.\n\n### CSS entry points\n\nImport base styles, design tokens, and one color theme in a root layout or global CSS entry:\n\n```tsx\n// app/layout.tsx (or app/docs/layout.tsx)\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\n```\n\n| Export | Purpose |\n|--------|---------|\n| `@arach/dewey/css` | Full bundle (base + tokens + default theme wiring) |\n| `@arach/dewey/css/base.css` | Reset and base rules |\n| `@arach/dewey/css/tokens` | Semantic `--dw-*` CSS variables |\n| `@arach/dewey/css/colors/.css` | Color preset |\n| `@arach/dewey/styles` | Alias of the full CSS bundle |\n| `@arach/dewey/tailwind` | Tailwind preset for `--dw-*` utilities |\n\n**Themes:** `neutral`, `ocean`, `emerald`, `purple`, `dusk`, `rose`, `github`, `warm`, `midnight`, `editorial`, `mono`, `hudson`.\n\nTokens use the `--dw-*` prefix so they rarely collide with a host design system. Dark mode follows a `.dark` class on an ancestor (DeweyProvider manages this when you use the provider).\n\nThe complete semantic contract covers surfaces and foregrounds; primary, secondary, and accent pairs; border/ring; info, warning, error, and success pairs; code and syntax colors; sidebar/header colors; typography, radii, shadows, and motion. Every public component and generated theme consumes this contract. The package verifies WCAG AA pairs, focus and reduced motion, plus 24 representative Playwright screenshots (12 themes × light/dark).\n\n### Import path note\n\n`@arach/dewey` and `@arach/dewey/react` resolve to the **same** module surface. Prefer `@arach/dewey` in new code; treat `/react` as a compatibility alias, not a separate React-only package.\n\n```tsx\nimport {\n DeweyProvider,\n Header,\n Sidebar,\n MarkdownContent,\n AutoTableOfContents,\n CopyButtons,\n} from '@arach/dewey'\n```\n\n## Recommended architecture\n\nKeep a clear server/client boundary (required for static export and App Router):\n\n```\napp/\n layout.tsx # server: fonts, CSS imports, Providers shell\n providers.tsx # client: DeweyProvider + Next.js Link/Image\n docs/\n layout.tsx # client or server shell: Header + Sidebar\n [...slug]/\n page.tsx # server: load markdown, generateStaticParams\n content.tsx # client: MarkdownContent, TOC, CopyButtons\nlib/\n dewey.tsx # components map + providerProps + siteConfig\n docs.ts # recursive fs loaders (server-only)\n navigation.ts # nav tree from docs.json (optional)\ndocs/ # source markdown (project root or monorepo package)\n```\n\nThis mirrors what `dewey create --template nextjs` scaffolds, without forcing a separate project.\n\n## Server-to-client wrapper\n\nDewey layout and content components use React hooks (theme, TOC scroll-spy, copy buttons). In the App Router they must run as **client** components. Static export and `generateStaticParams` must run on the **server**.\n\n**Pattern:** server page loads and serializes doc data → client content component renders Dewey UI.\n\n### 1. Client provider\n\n```tsx\n// app/providers.tsx\n'use client'\n\nimport { DeweyProvider } from '@arach/dewey'\nimport type { DeweyProviderProps } from '@arach/dewey'\nimport type { AnchorHTMLAttributes } from 'react'\nimport Link from 'next/link'\n\ntype DeweyLinkProps = AnchorHTMLAttributes & { href: string }\nconst DeweyLink = ({ href, ...props }: DeweyLinkProps) => \n\nconst providerProps: Omit = {\n theme: 'ocean',\n components: { Link: DeweyLink },\n}\n\nexport function Providers({ children }: { children: React.ReactNode }) {\n return {children}\n}\n```\n\nWire `Providers` once in the root layout (server component):\n\n```tsx\n// app/layout.tsx\nimport type { Metadata } from 'next'\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\nimport { Providers } from './providers'\n\nexport const metadata: Metadata = {\n title: 'Project docs',\n}\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n return (\n \n \n {children}\n \n \n )\n}\n```\n\n`suppressHydrationWarning` on `` avoids noise from theme class hydration.\n\n### 2. Server page + client content\n\n```tsx\n// app/docs/[...slug]/page.tsx\nimport { getDocBySlug, getAllDocSlugs } from '@/lib/docs'\nimport { DocContent } from './content'\n\ninterface PageProps {\n params: Promise<{ slug: string[] }>\n}\n\nexport async function generateStaticParams() {\n const slugs = getAllDocSlugs()\n return slugs.map((slug) => ({ slug: slug.split('/') }))\n}\n\nexport default async function DocPage({ params }: PageProps) {\n const { slug } = await params\n const doc = getDocBySlug(slug.join('/'))\n\n if (!doc) {\n return
Page not found
\n }\n\n return \n}\n```\n\n```tsx\n// app/docs/[...slug]/content.tsx\n'use client'\n\nimport { MarkdownContent, AutoTableOfContents, CopyButtons } from '@arach/dewey'\nimport type { DocData } from '@/lib/docs'\n\nexport function DocContent({ doc }: { doc: DocData }) {\n return (\n
\n
\n

{doc.title}

\n {doc.description ?

{doc.description}

: null}\n \n \n
\n \n
\n )\n}\n```\n\nPass only serializable props (`string`, plain objects) across the boundary — not file handles or class instances.\n\n## Static export configuration\n\nFor fully static hosting (GitHub Pages, S3, many CDNs):\n\n```js\n// next.config.js\n/** @type {import('next').NextConfig} */\nconst nextConfig = {\n output: 'export',\n images: { unoptimized: true },\n transpilePackages: ['@arach/dewey'],\n}\n\nmodule.exports = nextConfig\n```\n\n| Setting | Why |\n|---------|-----|\n| `output: 'export'` | Emits a static `out/` directory |\n| `images.unoptimized` | Required when using `output: 'export'` with Next Image |\n| `transpilePackages: ['@arach/dewey']` | Ensures Dewey ESM ships correctly through Next’s bundler |\n\n`generateStaticParams` must return every docs slug you want pre-rendered. Without it, nested routes are missing from the export.\n\nIf the host app is **not** a pure static export, you can still use the same server/client split and omit `output: 'export'`; keep `transpilePackages` when bundling Dewey.\n\n## Recursive content loading\n\nDiscover human Markdown recursively; exclude `.agent.md` from the page list, then attach an agent counterpart when present.\n\n```ts\n// lib/docs.ts\nimport fs from 'fs'\nimport path from 'path'\nimport matter from 'gray-matter'\n\nexport interface DocData {\n slug: string\n title: string\n description?: string\n content: string\n agentContent?: string\n order: number\n}\n\nconst docsDirectory = path.join(process.cwd(), 'docs')\n\nfunction walkDir(dir: string, base = ''): string[] {\n const results: string[] = []\n try {\n for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {\n const rel = base ? `${base}/${entry.name}` : entry.name\n if (entry.isDirectory()) {\n results.push(...walkDir(path.join(dir, entry.name), rel))\n } else {\n results.push(rel)\n }\n }\n } catch {\n // missing directory\n }\n return results\n}\n\nexport function getAllDocSlugs(): string[] {\n return walkDir(docsDirectory)\n .filter((file) => file.endsWith('.md') && !file.endsWith('.agent.md'))\n .map((file) => file.replace(/\\.md$/, ''))\n}\n\nexport function getDocBySlug(slug: string): DocData | null {\n try {\n const fullPath = path.join(docsDirectory, `${slug}.md`)\n const fileContents = fs.readFileSync(fullPath, 'utf-8')\n const { data, content } = matter(fileContents)\n\n let agentContent: string | undefined\n const agentCandidates = [\n path.join(docsDirectory, `${slug}.agent.md`),\n path.join(docsDirectory, 'agent', `${slug}.agent.md`),\n ]\n const agentPath = agentCandidates.find((p) => fs.existsSync(p))\n if (agentPath) {\n const agentFile = fs.readFileSync(agentPath, 'utf-8')\n const { content: agentBody } = matter(agentFile)\n agentContent = agentBody.trim() || undefined\n }\n\n return {\n slug,\n title: (data.title as string) || slug,\n description: data.description as string | undefined,\n content: content.trim(),\n agentContent,\n order: (data.order as number) || 999,\n }\n } catch {\n return null\n }\n}\n```\n\n| Rule | Behavior |\n|------|----------|\n| Human page | `docs/**/*.md` excluding `*.agent.md` |\n| Colocated agent | `docs/guides/install.agent.md` next to `docs/guides/install.md` |\n| Nested agent folder | `docs/agent/guides/install.agent.md` (or `docs/agent/overview.agent.md` for top-level pages) |\n| Nested routes | Slug `guides/install` → URL `/docs/guides/install` |\n\nMatch Dewey’s generate behavior: an empty `agent.sections` array includes every human-readable Markdown document recursively.\n\n### Optional navigation from `docs.json`\n\nAfter `bunx dewey generate`, import the generated manifest for sidebar groups:\n\n```ts\n// lib/navigation.ts\nimport docsJson from '../../docs.json'\nimport type { PageNode } from '@arach/dewey'\n\nexport function getNavTree(): PageNode[] {\n return (docsJson as { groups: { title: string; items: { id: string; title: string; description?: string }[] }[] })\n .groups.map((group) => ({\n type: 'folder' as const,\n name: group.title,\n defaultOpen: true,\n children: group.items.map((item) => ({\n type: 'page' as const,\n id: item.id,\n name: item.title,\n description: item.description,\n })),\n }))\n}\n```\n\nRegenerate `docs.json` whenever nav or page set changes so the UI and agent artifacts stay aligned.\n\n## Themes at runtime\n\nPreset via provider:\n\n```tsx\n\n {children}\n\n```\n\nOr partial overrides:\n\n```tsx\n\n {children}\n\n```\n\nPair the CSS file (`@arach/dewey/css/colors/purple.css`) with the matching `theme` prop so tokens and components stay in sync.\n\nOptional Tailwind:\n\n```ts\n// tailwind.config.ts\nimport type { Config } from 'tailwindcss'\nimport deweyPreset from '@arach/dewey/tailwind'\n\nexport default {\n presets: [deweyPreset],\n content: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'],\n} satisfies Config\n```\n\n## Docs layout shell (Header + Sidebar)\n\n```tsx\n// app/docs/layout.tsx\n'use client'\n\nimport { usePathname } from 'next/navigation'\nimport { Header, Sidebar } from '@arach/dewey'\nimport { getNavTree } from '@/lib/navigation'\n\nconst basePath = '/docs'\nconst projectName = 'My Project'\nconst defaultPage = 'overview'\n\nexport default function DocsLayout({ children }: { children: React.ReactNode }) {\n const pathname = usePathname()\n const currentPage =\n pathname.replace(new RegExp(`^${basePath}/?`), '').replace(/\\/$/, '') || defaultPage\n\n return (\n <>\n
\n
\n \n
{children}
\n
\n \n )\n}\n```\n\nPrefer composing `Header`, `Sidebar`, `MarkdownContent`, and `AutoTableOfContents` when you want full control. The packaged `DocsLayout` is also router-neutral: it uses anchors by default and accepts `LinkComponent` plus `currentPage`.\n\n```tsx\nimport { DocsLayout, MarkdownContent } from '@arach/dewey'\n\n\n \n\n```\n\n## Dewey generation alongside the site\n\nKeep agent generation in the **same repository** as the host app. Components render Markdown; generation produces retrieval artifacts for agents and CI.\n\n### Onboarding sequence (shared with greenfield)\n\n| Step | Command | Role |\n|------|---------|------|\n| 1. Install | `bun add @arach/dewey gray-matter` | Package on the site; CLI available via `bunx` |\n| 2. Init (once) | `bunx dewey init` | `docs/` + `dewey.config.ts` if missing |\n| 3. Author | Write `.md` + `.agent.md` | Human and agent sources |\n| 4. Generate | `bunx dewey generate` | Artifacts + `docs.json` for nav/retrieval |\n| 5. Audit | `bunx dewey audit` | Deterministic structure/completeness checks |\n| 6. Score | `bunx dewey agent` | Agent-readiness judgment (0–100) |\n| 7. Render | Your Next/React routes | Optional human UI (this guide) |\n| 8. Optional scaffold | `bunx dewey create …` | Only if you want a **separate** generated site |\n\nSuggested `package.json` scripts:\n\n```json\n{\n \"scripts\": {\n \"docs:generate\": \"bunx dewey generate\",\n \"docs:audit\": \"bunx dewey audit\",\n \"docs:agent\": \"bunx dewey agent\",\n \"prebuild\": \"bun run docs:generate\",\n \"dev\": \"next dev\",\n \"build\": \"next build\"\n }\n}\n```\n\nCustom paths:\n\n```bash\nbunx dewey generate --source ./content/docs --output ./public\n```\n\n`--source` overrides `docs.path` for one run. Empty `agent.sections: []` includes all human Markdown recursively.\n\n### Serve agent files from the static host\n\nCopy or generate into `public/` (or your static asset root) so agents can fetch:\n\n| Artifact | Typical public URL |\n|----------|-------------------|\n| `llms.txt` | `/llms.txt` |\n| `AGENTS.md` | `/AGENTS.md` |\n| `install.md` | `/install.md` |\n| `agent/**` | `/agent/**` |\n\nExample: set `docs.output` (or `--output`) to `public` for files you want deployed with the site, or add a small copy step after generate.\n\n## CI\n\nEnforce documentation quality without blocking only on the UI build:\n\n```yaml\n# .github/workflows/docs.yml (illustrative)\nname: docs\non:\n pull_request:\n paths: ['docs/**', 'dewey.config.ts', 'package.json']\n\njobs:\n dewey:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: oven-sh/setup-bun@v2\n - run: bun install\n - run: bunx dewey generate\n - run: bunx dewey audit --json\n - run: bunx dewey agent --json\n # Optional: fail if score below policy by parsing agent JSON in a follow-up step\n```\n\n| Command | CI use |\n|---------|--------|\n| `dewey generate` | Ensure artifacts are reproducible and committed or built in-pipeline |\n| `dewey audit --json` | Machine-readable structure checks |\n| `dewey agent --json` | Machine-readable readiness score |\n\nRun generate **before** `next build` when the app imports `docs.json` or serves files from `public/`.\n\n## Monorepo notes\n\n| Setup | Approach |\n|-------|----------|\n| Docs package + app package | Point `--source` at the docs package path; depend on `@arach/dewey` from the app |\n| Shared `docs/` at repo root | `process.cwd()` in Next is the app package — set `docsDirectory` to a path relative to the monorepo root (or symlink `docs` into the app) |\n| Generate once for many apps | Run `dewey generate` at the repo root; publish `agent/` and `docs.json` as static assets |\n\n## Checklist\n\n- [ ] `@arach/dewey` + CSS theme imported\n- [ ] `DeweyProvider` in a client `Providers` wrapper with Next `Link` / `Image`\n- [ ] Server `page.tsx` + client `content.tsx` split\n- [ ] `generateStaticParams` covers recursive slugs (if static export)\n- [ ] Recursive loader skips `.agent.md` for routes but loads agent siblings for `CopyButtons` / agent view\n- [ ] `bunx dewey generate` (and optional audit/agent) in local and CI pipelines\n- [ ] Agent artifacts reachable at stable URLs if you expose them publicly\n\n## Related\n\n- [Quickstart](./quickstart.md) — full init → generate → optional create sequence\n- [CLI Reference](./cli.md) — flags for generate, audit, agent, create\n- [Overview](./overview.md) — product positioning and agent content pattern\n- [Skills](./skills.md) — LLM prompt skills for review and install.md\n- [Maintaining generated sites](./maintenance.md) — update/eject ownership, adoption, backups, recovery, and release checks\n\nFor a ready-made Next.js project instead of embedding, use:\n\n```bash\nbunx dewey create my-docs --source ./docs --template nextjs --theme ocean\ncd my-docs && bun install && bun run dev\n```" }, { "id": "maintenance", "slug": "maintenance", "kind": "doc", "title": "Maintaining generated sites", "description": "Safely adopt, update, eject, recover, and release Dewey-generated sites", "sourcePath": "docs/maintenance.md", "url": "/docs/maintenance", "rawUrl": "/agent/raw/docs/maintenance.md", "headings": [ { "depth": 2, "text": "Safe update workflow", "anchor": "safe-update-workflow" }, { "depth": 2, "text": "Recover or adopt a missing manifest", "anchor": "recover-or-adopt-a-missing-manifest" }, { "depth": 2, "text": "Eject a Next.js component", "anchor": "eject-a-next-js-component" }, { "depth": 1, "text": "Compose the packaged default (recommended starting point)", "anchor": "compose-the-packaged-default-recommended-starting-point" }, { "depth": 1, "text": "Replace it completely", "anchor": "replace-it-completely" }, { "depth": 2, "text": "Recovery checklist", "anchor": "recovery-checklist" }, { "depth": 2, "text": "Release workflow", "anchor": "release-workflow" }, { "depth": 2, "text": "Related", "anchor": "related" } ], "tokensEstimate": 884, "frontmatter": { "title": "Maintaining generated sites", "description": "Safely adopt, update, eject, recover, and release Dewey-generated sites", "order": 7, "group": "Guides", "groupId": "guides" }, "markdown": "---\ntitle: Maintaining generated sites\ndescription: Safely adopt, update, eject, recover, and release Dewey-generated sites\norder: 7\ngroup: Guides\ngroupId: guides\n---\n\nDewey separates source documentation from the optional generated site. `dewey generate` owns agent-facing artifacts through `.dewey-generated.json`; `dewey create`, `update`, and `eject` maintain the standalone site through `.dewey-manifest.json`. Review those ownership boundaries before forcing a write.\n\n## Safe update workflow\n\nCommit the site before an update so every scaffold change is reviewable.\n\n```bash\nbunx dewey update ./my-docs --dry-run\nbunx dewey update ./my-docs\n```\n\n`update` classifies each current template file as current, safely updatable, missing/new, or modified. It updates Dewey-owned files whose recorded hash is unchanged and skips consumer-owned, ejected, or locally modified files. It never rewrites `package.json` or `docs/*.md` as part of normal scaffold maintenance.\n\nUse `--force` only after inspecting the dry run:\n\n```bash\nbunx dewey update ./my-docs --dry-run\nbunx dewey update ./my-docs --force\n```\n\nForced, locally modified Dewey-owned scaffold files are copied into a timestamped `.dewey-backup//...` tree before replacement. Consumer-owned and ejected files remain protected even with `--force`. Dewey keeps the five newest timestamped snapshots and removes older snapshots after a forced update.\n\n## Recover or adopt a missing manifest\n\nIf `.dewey-manifest.json` is absent but the directory still has the recognizable generated structure, the first `dewey update` adopts it:\n\n- Astro: detects `astro.config.mjs` plus `src/layouts/BaseLayout.astro`.\n- Next.js: detects `next.config.js`, `next.config.mjs`, or `next.config.ts` plus `/src/lib/dewey.tsx`.\n\nThe adoption pass records current hashes, template type, detected project/theme/default page where available, and consumer-owned settings. It writes `.dewey-manifest.json`, stops, and asks you to run `update` again. Review the adopted manifest before that second run. Unknown recorded themes produce a warning and resolve to `neutral`.\n\n## Eject a Next.js component\n\nEjection transfers a component from Dewey-managed defaults to an explicit override:\n\n```bash\n# Compose the packaged default (recommended starting point)\nbunx dewey eject Header ./my-docs\n\n# Replace it completely\nbunx dewey eject Header ./my-docs --full\n```\n\nSupported components are `Header`, `Sidebar`, `TableOfContents`, and `MarkdownContent`. Ejection is currently Next.js-only.\n\nBefore writing, Dewey verifies in memory that it can add the custom import and replace the component map in `/src/lib/dewey.tsx`. If either rewrite cannot be proven, it reports the failed step and creates no override. Successful writes use temporary files and report the status of the override, wiring, and manifest if an I/O failure interrupts the operation.\n\nThe manifest records the override and its wiring as `owner: \"ejected\"` with a content hash, Dewey version, component name, and `wrap` or `full` mode. `update` will not reclaim these entries, including with `--force`; remove or deliberately revise the ejected ownership entries only when you want to restore Dewey defaults.\n\n## Recovery checklist\n\n1. Stop if the update/eject summary reports a partial write.\n2. Inspect `git diff`, `.dewey-manifest.json`, and the latest timestamp under `.dewey-backup/`.\n3. Restore from Git first when the site was committed; otherwise copy only the affected file from the newest backup snapshot.\n4. For a missing manifest, run adoption once and review it before applying templates.\n5. Run the site build and the relevant route/component smoke check after recovery.\n\n## Release workflow\n\nReleases use `packages/docs/package.json` as the package-version source of truth and require an exact matching `v` tag. From a clean checkout:\n\n1. Finalize `CHANGELOG.md`, package version, `dewey.config.ts`, and lockfile.\n2. Run `bun run check`.\n3. Regenerate artifacts and confirm `.dewey-generated.json`, root artifacts, and `agent/` have no drift.\n4. Run `bun run verify:package`.\n5. Commit the release candidate so the checkout is clean and the tested package is reviewable.\n6. Run `bun run verify:release-smoke` to pack, install in an isolated consumer, import the public API, exercise packed CLI `init`/`generate`, and build a generated Next.js site. If it fails, fix and commit, then rerun.\n7. Create the exact tag only after the smoke passes, then let the publish workflow repeat package and smoke verification.\n\nThe release smoke script requires a clean checkout and removes its isolated temporary directory whether it passes or fails. See `RELEASING.md` for the authoritative repository checklist.\n\n## Related\n\n- [CLI Reference](./cli.md) — command flags and generation semantics\n- [Integrate into an existing site](./integrate-existing-site.md) — use components without a standalone scaffold\n- [API Reference](./api.md) — package, component, theme, and artifact contracts\n", "content": "Dewey separates source documentation from the optional generated site. `dewey generate` owns agent-facing artifacts through `.dewey-generated.json`; `dewey create`, `update`, and `eject` maintain the standalone site through `.dewey-manifest.json`. Review those ownership boundaries before forcing a write.\n\n## Safe update workflow\n\nCommit the site before an update so every scaffold change is reviewable.\n\n```bash\nbunx dewey update ./my-docs --dry-run\nbunx dewey update ./my-docs\n```\n\n`update` classifies each current template file as current, safely updatable, missing/new, or modified. It updates Dewey-owned files whose recorded hash is unchanged and skips consumer-owned, ejected, or locally modified files. It never rewrites `package.json` or `docs/*.md` as part of normal scaffold maintenance.\n\nUse `--force` only after inspecting the dry run:\n\n```bash\nbunx dewey update ./my-docs --dry-run\nbunx dewey update ./my-docs --force\n```\n\nForced, locally modified Dewey-owned scaffold files are copied into a timestamped `.dewey-backup//...` tree before replacement. Consumer-owned and ejected files remain protected even with `--force`. Dewey keeps the five newest timestamped snapshots and removes older snapshots after a forced update.\n\n## Recover or adopt a missing manifest\n\nIf `.dewey-manifest.json` is absent but the directory still has the recognizable generated structure, the first `dewey update` adopts it:\n\n- Astro: detects `astro.config.mjs` plus `src/layouts/BaseLayout.astro`.\n- Next.js: detects `next.config.js`, `next.config.mjs`, or `next.config.ts` plus `/src/lib/dewey.tsx`.\n\nThe adoption pass records current hashes, template type, detected project/theme/default page where available, and consumer-owned settings. It writes `.dewey-manifest.json`, stops, and asks you to run `update` again. Review the adopted manifest before that second run. Unknown recorded themes produce a warning and resolve to `neutral`.\n\n## Eject a Next.js component\n\nEjection transfers a component from Dewey-managed defaults to an explicit override:\n\n```bash\n# Compose the packaged default (recommended starting point)\nbunx dewey eject Header ./my-docs\n\n# Replace it completely\nbunx dewey eject Header ./my-docs --full\n```\n\nSupported components are `Header`, `Sidebar`, `TableOfContents`, and `MarkdownContent`. Ejection is currently Next.js-only.\n\nBefore writing, Dewey verifies in memory that it can add the custom import and replace the component map in `/src/lib/dewey.tsx`. If either rewrite cannot be proven, it reports the failed step and creates no override. Successful writes use temporary files and report the status of the override, wiring, and manifest if an I/O failure interrupts the operation.\n\nThe manifest records the override and its wiring as `owner: \"ejected\"` with a content hash, Dewey version, component name, and `wrap` or `full` mode. `update` will not reclaim these entries, including with `--force`; remove or deliberately revise the ejected ownership entries only when you want to restore Dewey defaults.\n\n## Recovery checklist\n\n1. Stop if the update/eject summary reports a partial write.\n2. Inspect `git diff`, `.dewey-manifest.json`, and the latest timestamp under `.dewey-backup/`.\n3. Restore from Git first when the site was committed; otherwise copy only the affected file from the newest backup snapshot.\n4. For a missing manifest, run adoption once and review it before applying templates.\n5. Run the site build and the relevant route/component smoke check after recovery.\n\n## Release workflow\n\nReleases use `packages/docs/package.json` as the package-version source of truth and require an exact matching `v` tag. From a clean checkout:\n\n1. Finalize `CHANGELOG.md`, package version, `dewey.config.ts`, and lockfile.\n2. Run `bun run check`.\n3. Regenerate artifacts and confirm `.dewey-generated.json`, root artifacts, and `agent/` have no drift.\n4. Run `bun run verify:package`.\n5. Commit the release candidate so the checkout is clean and the tested package is reviewable.\n6. Run `bun run verify:release-smoke` to pack, install in an isolated consumer, import the public API, exercise packed CLI `init`/`generate`, and build a generated Next.js site. If it fails, fix and commit, then rerun.\n7. Create the exact tag only after the smoke passes, then let the publish workflow repeat package and smoke verification.\n\nThe release smoke script requires a clean checkout and removes its isolated temporary directory whether it passes or fails. See `RELEASING.md` for the authoritative repository checklist.\n\n## Related\n\n- [CLI Reference](./cli.md) — command flags and generation semantics\n- [Integrate into an existing site](./integrate-existing-site.md) — use components without a standalone scaffold\n- [API Reference](./api.md) — package, component, theme, and artifact contracts" }, { "id": "overview", "slug": "overview", "kind": "doc", "title": "Overview", "description": "Documentation toolkit for AI-agent-ready docs", "sourcePath": "docs/overview.md", "url": "/docs/overview", "rawUrl": "/agent/raw/docs/overview.md", "headings": [ { "depth": 2, "text": "What Dewey Does", "anchor": "what-dewey-does" }, { "depth": 2, "text": "Key Concepts", "anchor": "key-concepts" }, { "depth": 3, "text": "Agent Content Pattern", "anchor": "agent-content-pattern" }, { "depth": 3, "text": "Skills System", "anchor": "skills-system" }, { "depth": 3, "text": "install.md Standard", "anchor": "install-md-standard" }, { "depth": 2, "text": "CLI Commands", "anchor": "cli-commands" }, { "depth": 2, "text": "Onboarding path", "anchor": "onboarding-path" }, { "depth": 2, "text": "Quick Links", "anchor": "quick-links" } ], "tokensEstimate": 654, "frontmatter": { "title": "Overview", "description": "Documentation toolkit for AI-agent-ready docs", "order": 1 }, "markdown": "---\ntitle: Overview\ndescription: Documentation toolkit for AI-agent-ready docs\norder: 1\n---\n\nDewey is a documentation toolkit that prepares your docs for AI agents. It audits, scores, and exports structured documentation artifacts without requiring a specific rendering framework.\n\n## What Dewey Does\n\nDewey is a **docs agent**, not a docs framework. It focuses on:\n\n- **Auditing** - Validates documentation completeness and quality\n- **Scoring** - Rates agent-readiness on a 0-100 scale\n- **Generating** - Creates AGENTS.md, llms.txt, docs.json, install.md, and the `agent/` retrieval surface\n- **Exporting** - Publishes recursive raw markdown, manifests, prompt registries, and context bundles\n- **Publishing** - Optionally scaffolds a static doc site from your markdown\n- **Reviewing** - Skills that catch drift between docs and codebase\n\n## Key Concepts\n\n### Agent Content Pattern\n\nEach documentation page should have two versions:\n\n| Version | Audience | Style |\n|---------|----------|-------|\n| `.md` | Humans | Narrative, explanatory |\n| `.agent.md` | AI agents | Dense, structured, self-contained |\n\n### Skills System\n\nSkills are LLM prompts, not code. Built-in skills:\n\n- `docsReviewAgent` - Reviews docs quality page-by-page\n- `docsDesignCritic` - Critiques page structure and visual design\n- `promptSlideoutGenerator` - Generates AI-consumable prompt configs\n- `installMdGenerator` - Creates install.md following installmd.org\n- `improveAIPrompts` - Iterative discovery, drafting, review, and refinement prompts; `improveAIPromptsSkill` remains as a deprecated alias\n\n### install.md Standard\n\nFollows the [installmd.org](https://installmd.org) specification. LLM-executable:\n\n```bash\ncurl -fsSL https://your-project.com/install.md\n```\n\nSupply the returned instructions to any compatible AI agent.\n\n## CLI Commands\n\n```\ndewey init Create docs/ folder and dewey.config.ts\ndewey audit Check documentation completeness\ndewey generate Create agent-ready files and retrieval artifacts\ndewey agent Score agent-readiness (0-100)\ndewey create Optional static docs site from markdown\n```\n\n## Onboarding path\n\nUse one sequence for every project (details in [Quickstart](./quickstart.md)):\n\n**init → author → generate → audit → agent → (optional UI)**\n\n| Optional UI | Guide |\n|-------------|--------|\n| Embed in an existing React/Next.js app | [Integrate into an existing site](./integrate-existing-site.md) |\n| Scaffold a standalone docs site | `dewey create` (see [CLI](./cli.md)) |\n\nAgent artifacts from `generate` are the product contract. Components and `create` are presentation options on top of that contract.\n\n`init` and the judgment commands are project-aware. The selected project type changes the scaffold and the evidence expected from docs. `audit` and `agent` also report focused source/human/agent drift: paired-file coverage, cited paths, and literal union/enum contracts. These checks are evidence based and do not replace semantic review or executable examples.\n\nGeneration and optional site creation share one recursive document model. Retrieval indexes are derived from one manifest, while full content stays in purpose-built document, prompt, raw, and bundle surfaces instead of being cloned into every JSON file.\n\n## Quick Links\n\n- [Quickstart](./quickstart.md) - Coherent init → generate → audit → agent sequence\n- [Integrate into an existing site](./integrate-existing-site.md) - React/Next.js embed guide\n- [CLI Reference](./cli.md) - All commands and options\n- [API Reference](./api.md) - Public TypeScript, React, theme, and artifact contracts\n- [Skills](./skills.md) - Built-in LLM prompt templates\n- [Maintaining generated sites](./maintenance.md) - Ownership, upgrades, ejection, recovery, and release verification\n", "content": "Dewey is a documentation toolkit that prepares your docs for AI agents. It audits, scores, and exports structured documentation artifacts without requiring a specific rendering framework.\n\n## What Dewey Does\n\nDewey is a **docs agent**, not a docs framework. It focuses on:\n\n- **Auditing** - Validates documentation completeness and quality\n- **Scoring** - Rates agent-readiness on a 0-100 scale\n- **Generating** - Creates AGENTS.md, llms.txt, docs.json, install.md, and the `agent/` retrieval surface\n- **Exporting** - Publishes recursive raw markdown, manifests, prompt registries, and context bundles\n- **Publishing** - Optionally scaffolds a static doc site from your markdown\n- **Reviewing** - Skills that catch drift between docs and codebase\n\n## Key Concepts\n\n### Agent Content Pattern\n\nEach documentation page should have two versions:\n\n| Version | Audience | Style |\n|---------|----------|-------|\n| `.md` | Humans | Narrative, explanatory |\n| `.agent.md` | AI agents | Dense, structured, self-contained |\n\n### Skills System\n\nSkills are LLM prompts, not code. Built-in skills:\n\n- `docsReviewAgent` - Reviews docs quality page-by-page\n- `docsDesignCritic` - Critiques page structure and visual design\n- `promptSlideoutGenerator` - Generates AI-consumable prompt configs\n- `installMdGenerator` - Creates install.md following installmd.org\n- `improveAIPrompts` - Iterative discovery, drafting, review, and refinement prompts; `improveAIPromptsSkill` remains as a deprecated alias\n\n### install.md Standard\n\nFollows the [installmd.org](https://installmd.org) specification. LLM-executable:\n\n```bash\ncurl -fsSL https://your-project.com/install.md\n```\n\nSupply the returned instructions to any compatible AI agent.\n\n## CLI Commands\n\n```\ndewey init Create docs/ folder and dewey.config.ts\ndewey audit Check documentation completeness\ndewey generate Create agent-ready files and retrieval artifacts\ndewey agent Score agent-readiness (0-100)\ndewey create Optional static docs site from markdown\n```\n\n## Onboarding path\n\nUse one sequence for every project (details in [Quickstart](./quickstart.md)):\n\n**init → author → generate → audit → agent → (optional UI)**\n\n| Optional UI | Guide |\n|-------------|--------|\n| Embed in an existing React/Next.js app | [Integrate into an existing site](./integrate-existing-site.md) |\n| Scaffold a standalone docs site | `dewey create` (see [CLI](./cli.md)) |\n\nAgent artifacts from `generate` are the product contract. Components and `create` are presentation options on top of that contract.\n\n`init` and the judgment commands are project-aware. The selected project type changes the scaffold and the evidence expected from docs. `audit` and `agent` also report focused source/human/agent drift: paired-file coverage, cited paths, and literal union/enum contracts. These checks are evidence based and do not replace semantic review or executable examples.\n\nGeneration and optional site creation share one recursive document model. Retrieval indexes are derived from one manifest, while full content stays in purpose-built document, prompt, raw, and bundle surfaces instead of being cloned into every JSON file.\n\n## Quick Links\n\n- [Quickstart](./quickstart.md) - Coherent init → generate → audit → agent sequence\n- [Integrate into an existing site](./integrate-existing-site.md) - React/Next.js embed guide\n- [CLI Reference](./cli.md) - All commands and options\n- [API Reference](./api.md) - Public TypeScript, React, theme, and artifact contracts\n- [Skills](./skills.md) - Built-in LLM prompt templates\n- [Maintaining generated sites](./maintenance.md) - Ownership, upgrades, ejection, recovery, and release verification" }, { "id": "quickstart", "slug": "quickstart", "kind": "doc", "title": "Quickstart", "description": "Get your documentation agent-ready in under 5 minutes", "sourcePath": "docs/quickstart.md", "url": "/docs/quickstart", "rawUrl": "/agent/raw/docs/quickstart.md", "headings": [ { "depth": 2, "text": "Onboarding sequence", "anchor": "onboarding-sequence" }, { "depth": 3, "text": "1. Install", "anchor": "1-install" }, { "depth": 3, "text": "2. Initialize", "anchor": "2-initialize" }, { "depth": 1, "text": "generic | npm-package | cli-tool | react-library | macos-app | monorepo", "anchor": "generic-npm-package-cli-tool-react-library-macos-app-monorepo" }, { "depth": 3, "text": "3. Configure", "anchor": "3-configure" }, { "depth": 3, "text": "4. Write docs", "anchor": "4-write-docs" }, { "depth": 3, "text": "5. Generate agent files", "anchor": "5-generate-agent-files" }, { "depth": 3, "text": "6. Audit", "anchor": "6-audit" }, { "depth": 1, "text": "CI-friendly:", "anchor": "ci-friendly" }, { "depth": 3, "text": "7. Check your score", "anchor": "7-check-your-score" }, { "depth": 3, "text": "8. Optional: human-facing docs UI", "anchor": "8-optional-human-facing-docs-ui" }, { "depth": 2, "text": "Next steps", "anchor": "next-steps" } ], "tokensEstimate": 993, "frontmatter": { "title": "Quickstart", "description": "Get your documentation agent-ready in under 5 minutes", "order": 2 }, "markdown": "---\ntitle: Quickstart\ndescription: Get your documentation agent-ready in under 5 minutes\norder: 2\n---\n\nRequires Node.js 18+ and Bun 1.3+ (recommended) or npm.\n\n## Onboarding sequence\n\nOne path from empty docs to agent-ready artifacts. Optional steps are marked.\n\n| Step | Command / action | What you get |\n|------|------------------|--------------|\n| 1. Install | `bun add -d @arach/dewey` | Local CLI |\n| 2. Init | `bunx dewey init` | `docs/` + `dewey.config.ts` |\n| 3. Configure | Edit `dewey.config.ts` | Project context, agent rules, install steps |\n| 4. Author | Write `.md` and `.agent.md` | Human + agent source pages |\n| 5. Generate | `bunx dewey generate` | `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, `agent/` |\n| 6. Audit | `bunx dewey audit` | Deterministic completeness checks |\n| 7. Score | `bunx dewey agent` | Agent-readiness score (0–100) and recommendations |\n| 8a. Embed (optional) | Components in your React/Next app | Human UI on an **existing** site — [integration guide](./integrate-existing-site.md) |\n| 8b. Create (optional) | `bunx dewey create my-docs --source ./docs --theme ocean` | **Standalone** static docs site |\n\nCore contract is steps 1–7 (especially **generate**). Publishing a site is optional.\n\n### 1. Install\n\n```bash\nbun add -d @arach/dewey\n```\n\nWhen you will import React components into an app, install as a runtime dependency instead: `bun add @arach/dewey`. See [Integrate into an existing site](./integrate-existing-site.md).\n\n### 2. Initialize\n\n```bash\nbunx dewey init\n```\n\nCreates a `docs/` folder with starter templates and a `dewey.config.ts` configuration file.\n\nChoose a project type so the scaffold and later evidence checks match the product:\n\n```bash\nbunx dewey init --type npm-package\n# generic | npm-package | cli-tool | react-library | macos-app | monorepo\n```\n\nEvery type creates paired human and agent pages. The focus page and defaults vary: API for npm packages, command reference for CLIs, component reference for React libraries, architecture for generic/macOS projects, and workspace mapping for monorepos. An invalid type fails instead of silently using `generic`.\n\n### 3. Configure\n\n
\n
dewey.config.ts
\n\n```typescript\nexport default {\n project: {\n name: 'your-project',\n tagline: 'What your project does',\n type: 'npm-package', // or cli-tool, react-library, etc.\n },\n\n agent: {\n criticalContext: [\n // Rules AI agents MUST know\n 'NEVER do X when Y',\n ],\n entryPoints: {\n 'main': 'src/',\n },\n },\n\n install: {\n objective: 'Install and configure your-project.',\n steps: [\n { description: 'Install', command: 'bun add your-project' },\n ],\n },\n}\n```\n\n
\n\n### 4. Write docs\n\nCreate pages in the `docs/` folder:\n\n```\ndocs/\n overview.md # Project introduction\n quickstart.md # Getting started guide\n api.md # API reference\n overview.agent.md # Agent-optimized version (or docs/agent/overview.agent.md)\n```\n\n### 5. Generate agent files\n\n```bash\nbunx dewey generate\n```\n\nOutputs `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and an `agent/` retrieval surface with raw markdown, prompt registries, manifests, and context bundles.\n\nThe same canonical document discovery powers `generate`, the optional `create` scaffold, and the artifact API. Full content is materialized deliberately: document bodies in `agent/docs.json`, prompts in `agent/prompts.json`, and Markdown in `agent/raw/docs/` plus bundles. Context files remain compact retrieval indexes.\n\n### 6. Audit\n\n```bash\nbunx dewey audit\n# CI-friendly:\nbunx dewey audit --json\n```\n\nStructural and completeness checks plus project-type evidence and focused documentation drift. JSON output includes structured `projectType` and `drift` objects. Prefer fixing audit findings before treating the score as a release gate.\n\n### 7. Check your score\n\n
\n
bunx dewey agent
\n\n```\nAgent Readiness Report\nOverall Score: 75/100 (Grade: C)\n\nCategories:\n✓ Project Context: 20/25\n○ Agent-Optimized Files: 20/30\n...\n```\n\n
\n\n```bash\nbunx dewey agent --json # machine-readable for CI\n```\n\n### 8. Optional: human-facing docs UI\n\n**Already have a React or Next.js site?** Embed Dewey components under a `/docs` route:\n\n→ [Integrate into an existing site](./integrate-existing-site.md)\n\n**Want a standalone docs site from the same Markdown?**\n\n```bash\nbunx dewey create my-docs --source ./docs --theme ocean\ncd my-docs && bun install && bun run dev\n```\n\nGenerates a static docs site when you want a separate publishing path alongside agent artifacts.\n\nThe scaffold pins tested Next.js/Astro dependencies and runs the same agent-artifact writer, so it starts with both a human site and the retrieval contract. For later adoption, updates, ejection, backups, and recovery, see [Maintaining generated sites](./maintenance.md).\n\n---\n\n## Next steps\n\n- Create `.agent.md` versions of your docs for denser, structured content\n- Add skills to `.agents/skills/` for custom agent-guided reviews\n- Run `bunx dewey audit` and `bunx dewey agent` in CI (`--json`)\n- Embed components or use `dewey create` only when you need a human site\n- [CLI Reference](./cli.md) · [Skills](./skills.md) · [Existing-site guide](./integrate-existing-site.md)\n- [Maintaining generated sites](./maintenance.md) — ownership, update, eject, recovery, and release checks\n", "content": "Requires Node.js 18+ and Bun 1.3+ (recommended) or npm.\n\n## Onboarding sequence\n\nOne path from empty docs to agent-ready artifacts. Optional steps are marked.\n\n| Step | Command / action | What you get |\n|------|------------------|--------------|\n| 1. Install | `bun add -d @arach/dewey` | Local CLI |\n| 2. Init | `bunx dewey init` | `docs/` + `dewey.config.ts` |\n| 3. Configure | Edit `dewey.config.ts` | Project context, agent rules, install steps |\n| 4. Author | Write `.md` and `.agent.md` | Human + agent source pages |\n| 5. Generate | `bunx dewey generate` | `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, `agent/` |\n| 6. Audit | `bunx dewey audit` | Deterministic completeness checks |\n| 7. Score | `bunx dewey agent` | Agent-readiness score (0–100) and recommendations |\n| 8a. Embed (optional) | Components in your React/Next app | Human UI on an **existing** site — [integration guide](./integrate-existing-site.md) |\n| 8b. Create (optional) | `bunx dewey create my-docs --source ./docs --theme ocean` | **Standalone** static docs site |\n\nCore contract is steps 1–7 (especially **generate**). Publishing a site is optional.\n\n### 1. Install\n\n```bash\nbun add -d @arach/dewey\n```\n\nWhen you will import React components into an app, install as a runtime dependency instead: `bun add @arach/dewey`. See [Integrate into an existing site](./integrate-existing-site.md).\n\n### 2. Initialize\n\n```bash\nbunx dewey init\n```\n\nCreates a `docs/` folder with starter templates and a `dewey.config.ts` configuration file.\n\nChoose a project type so the scaffold and later evidence checks match the product:\n\n```bash\nbunx dewey init --type npm-package\n# generic | npm-package | cli-tool | react-library | macos-app | monorepo\n```\n\nEvery type creates paired human and agent pages. The focus page and defaults vary: API for npm packages, command reference for CLIs, component reference for React libraries, architecture for generic/macOS projects, and workspace mapping for monorepos. An invalid type fails instead of silently using `generic`.\n\n### 3. Configure\n\n
\n
dewey.config.ts
\n\n```typescript\nexport default {\n project: {\n name: 'your-project',\n tagline: 'What your project does',\n type: 'npm-package', // or cli-tool, react-library, etc.\n },\n\n agent: {\n criticalContext: [\n // Rules AI agents MUST know\n 'NEVER do X when Y',\n ],\n entryPoints: {\n 'main': 'src/',\n },\n },\n\n install: {\n objective: 'Install and configure your-project.',\n steps: [\n { description: 'Install', command: 'bun add your-project' },\n ],\n },\n}\n```\n\n
\n\n### 4. Write docs\n\nCreate pages in the `docs/` folder:\n\n```\ndocs/\n overview.md # Project introduction\n quickstart.md # Getting started guide\n api.md # API reference\n overview.agent.md # Agent-optimized version (or docs/agent/overview.agent.md)\n```\n\n### 5. Generate agent files\n\n```bash\nbunx dewey generate\n```\n\nOutputs `AGENTS.md`, `llms.txt`, `docs.json`, `install.md`, and an `agent/` retrieval surface with raw markdown, prompt registries, manifests, and context bundles.\n\nThe same canonical document discovery powers `generate`, the optional `create` scaffold, and the artifact API. Full content is materialized deliberately: document bodies in `agent/docs.json`, prompts in `agent/prompts.json`, and Markdown in `agent/raw/docs/` plus bundles. Context files remain compact retrieval indexes.\n\n### 6. Audit\n\n```bash\nbunx dewey audit\n# CI-friendly:\nbunx dewey audit --json\n```\n\nStructural and completeness checks plus project-type evidence and focused documentation drift. JSON output includes structured `projectType` and `drift` objects. Prefer fixing audit findings before treating the score as a release gate.\n\n### 7. Check your score\n\n
\n
bunx dewey agent
\n\n```\nAgent Readiness Report\nOverall Score: 75/100 (Grade: C)\n\nCategories:\n✓ Project Context: 20/25\n○ Agent-Optimized Files: 20/30\n...\n```\n\n
\n\n```bash\nbunx dewey agent --json # machine-readable for CI\n```\n\n### 8. Optional: human-facing docs UI\n\n**Already have a React or Next.js site?** Embed Dewey components under a `/docs` route:\n\n→ [Integrate into an existing site](./integrate-existing-site.md)\n\n**Want a standalone docs site from the same Markdown?**\n\n```bash\nbunx dewey create my-docs --source ./docs --theme ocean\ncd my-docs && bun install && bun run dev\n```\n\nGenerates a static docs site when you want a separate publishing path alongside agent artifacts.\n\nThe scaffold pins tested Next.js/Astro dependencies and runs the same agent-artifact writer, so it starts with both a human site and the retrieval contract. For later adoption, updates, ejection, backups, and recovery, see [Maintaining generated sites](./maintenance.md).\n\n---\n\n## Next steps\n\n- Create `.agent.md` versions of your docs for denser, structured content\n- Add skills to `.agents/skills/` for custom agent-guided reviews\n- Run `bunx dewey audit` and `bunx dewey agent` in CI (`--json`)\n- Embed components or use `dewey create` only when you need a human site\n- [CLI Reference](./cli.md) · [Skills](./skills.md) · [Existing-site guide](./integrate-existing-site.md)\n- [Maintaining generated sites](./maintenance.md) — ownership, update, eject, recovery, and release checks" }, { "id": "skills", "slug": "skills", "kind": "doc", "title": "Skills", "description": "Expert instructions that guide AI agents through specific documentation tasks", "sourcePath": "docs/skills.md", "url": "/docs/skills", "rawUrl": "/agent/raw/docs/skills.md", "headings": [ { "depth": 2, "text": "Built-in Skills", "anchor": "built-in-skills" }, { "depth": 2, "text": "Creating Custom Skills", "anchor": "creating-custom-skills" }, { "depth": 1, "text": "Skill Name", "anchor": "skill-name" }, { "depth": 2, "text": "When to Use", "anchor": "when-to-use" }, { "depth": 2, "text": "Instructions", "anchor": "instructions" }, { "depth": 2, "text": "Example", "anchor": "example" }, { "depth": 2, "text": "Best Practices", "anchor": "best-practices" } ], "tokensEstimate": 469, "frontmatter": { "title": "Skills", "description": "Expert instructions that guide AI agents through specific documentation tasks", "order": 4 }, "markdown": "---\ntitle: Skills\ndescription: Expert instructions that guide AI agents through specific documentation tasks\norder: 4\n---\n\nSkills are LLM prompts, not code. They're expert instructions that tell AI agents exactly how to perform a task — what to check, what to produce, and what success looks like.\n\n## Built-in Skills\n\n| Skill | Purpose | Usage |\n|-------|---------|-------|\n| `docsReviewAgent` | Reviews doc quality page-by-page — catches stale content, missing sections, unclear explanations, broken links | `Use the docsReviewAgent skill to review docs/overview.md` |\n| `promptSlideoutGenerator` | Generates AI-consumable prompt configurations for documentation pages | `Use promptSlideoutGenerator to create prompt config for the API page` |\n| `docsDesignCritic` | Critiques page structure and visual design — heading hierarchy, component usage, information density | `Use docsDesignCritic to critique docs/quickstart.md` |\n| `installMdGenerator` | Creates install.md files following the [installmd.org](https://installmd.org) spec | `Use installMdGenerator to create install.md from dewey.config.ts` |\n| `improveAIPrompts` | Iteratively discovers prompt opportunities, drafts self-contained contracts, reviews them, and refines the result | `Use improveAIPrompts.passes.discovery.prompt`, then draft/review/refine passes |\n\n`improveAIPrompts` is the public name. `improveAIPromptsSkill` is exported only as a deprecated compatibility alias and references the same object.\n\n```ts\nimport { improveAIPrompts } from '@arach/dewey'\n\nconst discovery = improveAIPrompts.passes.discovery.prompt\nconst review = improveAIPrompts.passes.review.prompt\n .replace('{PASTE_DRAFT}', draft)\n```\n\nThe pass prompts guide an LLM; they do not inspect a repository or rewrite files by themselves. Supply the requested context, evaluate the model output against the included quality criteria, and retain human review for project-specific constraints.\n\n---\n\n## Creating Custom Skills\n\nSkills live as markdown files in your project:\n\n```\n.agents/skills/\n my-skill.md\n```\n\nEach skill follows a consistent structure:\n\n
\n
my-skill.md
\n\n```markdown\n# Skill Name\n\nBrief description of what this skill does.\n\n## When to Use\n\n- Situation 1\n- Situation 2\n\n## Instructions\n\nStep-by-step guide for the AI agent:\n\n1. First, check X\n2. Then, do Y\n3. Finally, verify Z\n\n## Example\n\nShow an example input and expected output.\n```\n\n
\n\n## Best Practices\n\n| Do | Don't |\n|----|-------|\n| Be specific and actionable | Use vague instructions |\n| Include examples | Assume context |\n| Define success criteria | Leave outcomes ambiguous |\n| Reference file paths | Use relative descriptions |\n", "content": "Skills are LLM prompts, not code. They're expert instructions that tell AI agents exactly how to perform a task — what to check, what to produce, and what success looks like.\n\n## Built-in Skills\n\n| Skill | Purpose | Usage |\n|-------|---------|-------|\n| `docsReviewAgent` | Reviews doc quality page-by-page — catches stale content, missing sections, unclear explanations, broken links | `Use the docsReviewAgent skill to review docs/overview.md` |\n| `promptSlideoutGenerator` | Generates AI-consumable prompt configurations for documentation pages | `Use promptSlideoutGenerator to create prompt config for the API page` |\n| `docsDesignCritic` | Critiques page structure and visual design — heading hierarchy, component usage, information density | `Use docsDesignCritic to critique docs/quickstart.md` |\n| `installMdGenerator` | Creates install.md files following the [installmd.org](https://installmd.org) spec | `Use installMdGenerator to create install.md from dewey.config.ts` |\n| `improveAIPrompts` | Iteratively discovers prompt opportunities, drafts self-contained contracts, reviews them, and refines the result | `Use improveAIPrompts.passes.discovery.prompt`, then draft/review/refine passes |\n\n`improveAIPrompts` is the public name. `improveAIPromptsSkill` is exported only as a deprecated compatibility alias and references the same object.\n\n```ts\nimport { improveAIPrompts } from '@arach/dewey'\n\nconst discovery = improveAIPrompts.passes.discovery.prompt\nconst review = improveAIPrompts.passes.review.prompt\n .replace('{PASTE_DRAFT}', draft)\n```\n\nThe pass prompts guide an LLM; they do not inspect a repository or rewrite files by themselves. Supply the requested context, evaluate the model output against the included quality criteria, and retain human review for project-specific constraints.\n\n---\n\n## Creating Custom Skills\n\nSkills live as markdown files in your project:\n\n```\n.agents/skills/\n my-skill.md\n```\n\nEach skill follows a consistent structure:\n\n
\n
my-skill.md
\n\n```markdown\n# Skill Name\n\nBrief description of what this skill does.\n\n## When to Use\n\n- Situation 1\n- Situation 2\n\n## Instructions\n\nStep-by-step guide for the AI agent:\n\n1. First, check X\n2. Then, do Y\n3. Finally, verify Z\n\n## Example\n\nShow an example input and expected output.\n```\n\n
\n\n## Best Practices\n\n| Do | Don't |\n|----|-------|\n| Be specific and actionable | Use vague instructions |\n| Include examples | Assume context |\n| Define success criteria | Leave outcomes ambiguous |\n| Reference file paths | Use relative descriptions |" }, { "id": "agent/api.agent", "slug": "agent/api.agent", "kind": "agent", "title": "API Reference", "description": "Dense contract for Dewey's public TypeScript, React, theme, and artifact APIs", "sourcePath": "docs/agent/api.agent.md", "url": "/agent/raw/docs/agent/api.agent.md", "rawUrl": "/agent/raw/docs/agent/api.agent.md", "headings": [ { "depth": 1, "text": "Dewey API - Agent Context", "anchor": "dewey-api-agent-context" }, { "depth": 2, "text": "Purpose", "anchor": "purpose" }, { "depth": 2, "text": "Source of truth", "anchor": "source-of-truth" }, { "depth": 2, "text": "Surface selection", "anchor": "surface-selection" }, { "depth": 2, "text": "Package subpaths", "anchor": "package-subpaths" }, { "depth": 2, "text": "Config", "anchor": "config" }, { "depth": 2, "text": "Artifact API", "anchor": "artifact-api" }, { "depth": 2, "text": "Themes", "anchor": "themes" }, { "depth": 2, "text": "React minimal example", "anchor": "react-minimal-example" }, { "depth": 2, "text": "Component contracts", "anchor": "component-contracts" }, { "depth": 2, "text": "Component/navigation unions", "anchor": "component-navigation-unions" }, { "depth": 2, "text": "Main module runtime exports", "anchor": "main-module-runtime-exports" }, { "depth": 2, "text": "Main module type exports", "anchor": "main-module-type-exports" }, { "depth": 2, "text": "Skills are prompts", "anchor": "skills-are-prompts" }, { "depth": 2, "text": "Router and theme contract", "anchor": "router-and-theme-contract" }, { "depth": 2, "text": "Structured agent content", "anchor": "structured-agent-content" } ], "tokensEstimate": 2284, "frontmatter": { "title": "API Reference", "description": "Dense contract for Dewey's public TypeScript, React, theme, and artifact APIs", "order": 5, "group": "Reference", "groupId": "reference" }, "markdown": "---\ntitle: API Reference\ndescription: Dense contract for Dewey's public TypeScript, React, theme, and artifact APIs\norder: 5\ngroup: Reference\ngroupId: reference\n---\n\n# Dewey API - Agent Context\n\n## Purpose\n\nPublic contracts for `@arach/dewey`. CLI generation/audit is the primary product; TypeScript artifact APIs enable retrieval automation; React/theme APIs are optional presentation.\n\n## Source of truth\n\n| Surface | Source path |\n|---|---|\n| Main public exports | `packages/docs/src/index.ts` |\n| Package subpaths | `packages/docs/package.json` |\n| Config schema | `packages/docs/src/cli/schema.ts` |\n| CLI commands/options | `packages/docs/src/cli/index.ts` |\n| Artifact API | `packages/docs/src/cli/agent-artifacts.ts` |\n| Ownership planner | `packages/docs/src/cli/generation-plan.ts` |\n| Theme registry | `packages/docs/src/themes.ts` |\n| React contracts | `packages/docs/src/components/` |\n| Navigation types | `packages/docs/src/types/page-tree.ts` |\n| Legacy types | `packages/docs/src/types.ts` |\n| Structured agent content | `packages/docs/src/utils/agent-content.ts` |\n\n## Surface selection\n\n| Goal | Use |\n|---|---|\n| Generate agent artifacts | `bunx dewey generate` |\n| Deterministic structural validation | `bunx dewey audit` |\n| Evidence-based readiness score | `bunx dewey agent` |\n| Typed config | `defineConfig` from `@arach/dewey` |\n| Programmatic retrieval/build/write | `@arach/dewey/agent-artifacts` |\n| Existing React/Next UI | components from `@arach/dewey` + CSS subpaths |\n| Standalone docs UI | `bunx dewey create` |\n\nInvariant: CLI/artifact generation is the product contract. React components and generated sites are optional human-facing layers. Maintain human `.md` + dense `.agent.md` pairs.\n\n## Package subpaths\n\n| Import | Contract |\n|---|---|\n| `@arach/dewey` | Main JS/types |\n| `@arach/dewey/react` | Exact compatibility alias of main JS/types |\n| `@arach/dewey/agent-artifacts` | Artifact JS/types |\n| `@arach/dewey/css` | Full CSS |\n| `@arach/dewey/styles` | Full CSS alias |\n| `@arach/dewey/css/base.css` | Base CSS |\n| `@arach/dewey/css/tokens` | Semantic token CSS |\n| `@arach/dewey/css/tailwind` | Tailwind-oriented CSS |\n| `@arach/dewey/css/colors/{theme}.css` | Explicit per-theme CSS export; no wildcard |\n| `@arach/dewey/tailwind` | Tailwind preset JS/types |\n\n## Config\n\n```ts\nimport { defineConfig } from '@arach/dewey'\n\nexport default defineConfig({\n project: { name: 'pkg', type: 'npm-package', version: '1.0.0' },\n agent: {\n criticalContext: ['Use Bun'],\n entryPoints: { API: 'src/index.ts' },\n rules: [{ pattern: '*.test.ts', instruction: 'Use bun:test.' }],\n sections: [],\n },\n docs: {\n path: './docs',\n output: './',\n required: ['overview', 'quickstart', 'api'],\n },\n install: {\n objective: 'Install pkg.',\n prerequisites: ['Node.js 18+'],\n steps: [{ description: 'Install', command: 'bun add pkg' }],\n doneWhen: { command: 'bun test', expectedOutput: 'all tests pass' },\n },\n})\n```\n\n`defineConfig(input): DeweyConfig` parses with Zod and throws on invalid input.\n\n| Config path | Type | Default/required |\n|---|---|---|\n| `project.name` | `string` | required |\n| `project.tagline` | `string?` | optional |\n| `project.type` | `ProjectType` | `'generic'` |\n| `project.version` | `string?` | optional |\n| `agent.criticalContext` | `string[]` | `[]` |\n| `agent.entryPoints` | `Record` | `{}` |\n| `agent.rules` | `AgentRule[]` | `[]` |\n| `agent.sections` | `string[]` | `[]`; empty = every human-readable doc |\n| `docs.path` | `string` | `'./docs'` |\n| `docs.output` | `string` | `'./'` |\n| `docs.required` | `string[]` | `['overview','quickstart']` |\n| `install.objective` | `string?` | optional |\n| `install.doneWhen` | `{command:string;expectedOutput?:string}?` | optional |\n| `install.prerequisites` | `string[]` | `[]` |\n| `install.steps` | `{description:string;command?:string;alternatives?:{condition:string;command:string}[]}[]` | `[]` |\n| `install.hostedUrl` | `string?` | optional |\n\n`ProjectType = 'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`.\n\nMain config types: `AgentRule`, `DeweyConfig`, `InstallConfig`, `ProjectType`.\n\n## Artifact API\n\nImport only from `@arach/dewey/agent-artifacts`.\n\n| Export | Contract |\n|---|---|\n| `collectMarkdownArtifacts(options?)` | `Promise`; recursive `.md`/`.mdx`, deterministic sort |\n| `getMarkdownArtifact(slug, options?)` | `Promise`; normalized slug/source lookup |\n| `getPromptArtifact(promptId, options?)` | `Promise`; prompt lookup |\n| `parseDocArtifact(filePath, raw?, options?)` | `Promise` |\n| `buildAgentManifest(docs, {project?,includeContent?}?)` | `AgentManifest` |\n| `buildPromptRegistry(docs, {project?,includeContent?}?)` | schema-versioned registry object |\n| `buildContextBundle(docs, slugs, title?)` | Markdown `string` |\n| `buildAgentArtifactFiles(options?)` | in-memory generated file set; no apply |\n| `writeAgentArtifacts(options?)` | plans and optionally applies writes; returns `docs`, `prompts`, `written`, `changed`, `deleted`, `operations` |\n\n```ts\nimport {\n collectMarkdownArtifacts,\n buildAgentManifest,\n writeAgentArtifacts,\n} from '@arach/dewey/agent-artifacts'\n\nconst input = { rootDir: process.cwd(), docsDir: './docs' }\nconst project = { name: 'pkg', version: '1.0.0' }\nconst docs = await collectMarkdownArtifacts(input)\nconst manifest = buildAgentManifest(docs, { project })\nconst preview = await writeAgentArtifacts({\n ...input,\n outputDir: './generated',\n project,\n dryRun: true,\n})\nconsole.log(manifest.recommendedReadOrder, preview.operations)\n```\n\n| Type | Fields |\n|---|---|\n| `CollectMarkdownArtifactsOptions` | `rootDir?`, `docsDir?` |\n| `WriteAgentArtifactsOptions` | previous + `outputDir?`, `project?`, `dryRun?`, `overwrite?` |\n| `AgentArtifactsProject` | `name`, `version?`, `tagline?`, `repository?` |\n| `MarkdownHeading` | `depth`, `text`, `anchor` |\n| `MarkdownArtifact` | `id`, `slug`, `kind`, `promptId?`, `title`, `description`, `sourcePath`, `url`, `rawUrl`, `promptUrl?`, `frontmatter`, `headings`, `tokensEstimate`, `rawMarkdown`, `content` |\n\nOther exported artifact types: `AgentManifest`, `AgentManifestEntry`, `PromptManifestEntry`.\n\n`MarkdownArtifactKind = 'doc' | 'agent' | 'prompt' | 'reference' | 'proposal'`.\n\n| Slug/path condition, first match | Kind |\n|---|---|\n| starts `prompts/` | `prompt` |\n| starts `agent/` or ends `.agent` | `agent` |\n| starts `reference/` | `reference` |\n| starts `proposals/` | `proposal` |\n| otherwise | `doc` |\n\nWrite semantics: `dryRun` never applies; desired unowned outputs block unless `overwrite`; stale deletion is limited to Dewey-owned outputs in `agentArtifacts` scope.\n\n## Themes\n\n```text\nThemeName = ThemePreset =\n'neutral' | 'ocean' | 'emerald' | 'purple' | 'dusk' | 'rose' | 'github' |\n'warm' | 'midnight' | 'editorial' | 'mono' | 'hudson'\n```\n\n| Export | Contract |\n|---|---|\n| `THEME_REGISTRY` | canonical name -> `{cssFile,generatedSite}` |\n| `PUBLISHED_CSS_THEMES` | readonly presets with CSS |\n| `VALID_THEMES` | readonly presets accepted by generated sites |\n| `isThemeName(string)` | type guard |\n| `resolveTheme(string?)` | valid theme or `'neutral'` fallback |\n\nAll current themes are published and generated-site-valid. Pair `theme=\"ocean\"` with `@arach/dewey/css/colors/ocean.css`.\n\nCustom `ThemeConfig`: `preset?: ThemePreset`; `colors?: {primary?,background?,foreground?,accent?}`; `fonts?: {sans?,mono?}`.\n\n## React minimal example\n\n```tsx\n'use client'\nimport {\n AutoTableOfContents,\n CopyButtons,\n DeweyProvider,\n MarkdownContent,\n} from '@arach/dewey'\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\n\nexport function Page({ markdown, agentMarkdown }: {\n markdown: string\n agentMarkdown: string\n}) {\n return (\n \n \n \n \n \n )\n}\n```\n\nProvider rule: components using Dewey context hooks require `DeweyProvider`. Next App Router: provider/interactive layer is client; filesystem/static-param work is server.\n\n## Component contracts\n\n| Value export | Required props | Optional contract |\n|---|---|---|\n| `DeweyProvider` | `children` | `components`, `theme`, `defaultDark`, `storageKey` |\n| `DocsApp` | `docs: Record` | `config`, `currentPage`, `providerProps`; `onNavigate` reserved/not invoked |\n| `DocsIndex` | `tree: PageNode[]` | `projectName`, `tagline`, `description`, `basePath`, `hero`, `showSearch`, `heroIcon`, `quickLinks`, `layout?: 'stacked'|'columns'` |\n| `Header` | none | `projectName`, `homeUrl`, `backUrl`, `backLabel`, `label`, `showThemeToggle`, `actions` |\n| `Sidebar` | `tree` | `currentPage`, `projectName`, `basePath`, `isOpen`, `onClose`, `header`, `footer` |\n| `MarkdownContent` | `content` | `isDark` |\n| `TableOfContents` | none | `items`, `title`, `className`, `scrollOffset` |\n| `AutoTableOfContents` | none | `markdown`, `containerRef`, `title`, `className` |\n| `Callout` | `children` | `type`, `title` |\n| `Tabs` / `Tab` | `children`; Tab: `label` | Tabs: `defaultTab` |\n| `Steps` / `Step` | `children`; Step: `title` | — |\n| `Card` | `title` | `description`, `icon`, `href`, `children` |\n| `CardGrid` | `children` | `columns?: 2|3|4` |\n| `FileTree` | `items` | `defaultExpanded`; item `type?: 'file'|'folder'` |\n| `ApiTable` | `properties` | `title` |\n| `Badge` | `children` | `variant`, `size?: 'sm'|'md'` |\n| `CopyButtons` | `markdownContent` | `agentContent`, `showLabels`, `onCopy`, `className` |\n| `AgentContext` | `content` | `title`, `defaultExpanded`, `className` |\n| `PromptSlideout` | `isOpen`, `onClose`, `info`, `starterTemplate` | `title`, `description`, `params`, `examples`, `expectedOutput`, `className` |\n\n`DocsLayout` is router-neutral: it uses plain anchors by default and accepts `LinkComponent` plus `currentPage` for host integration. `DocsLayoutProps` is re-exported from main. `CodeBlock` and `HeadingLink` values are public; their prop interfaces are not exported.\n\n## Component/navigation unions\n\n```text\nCalloutType = 'info' | 'warning' | 'tip' | 'danger'\nBadgeVariant = 'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple'\nCopyButtons.onCopy type = 'markdown' | 'agent' | 'plain'\nPageNode.type = 'page' | 'folder' | 'separator'\nPage/navigation badgeColor = 'info' | 'success' | 'warning' | 'error' | 'default'\nDocsAppConfig.layout.header = boolean | 'minimal'\nlegacy BadgeColor = 'blue' | 'emerald' | 'purple' | 'amber' | 'rose'\nlegacy DocSection.level = 2 | 3\n```\n\n## Main module runtime exports\n\n| Group | Names |\n|---|---|\n| Config | `defineConfig` |\n| Themes | `PUBLISHED_CSS_THEMES`, `THEME_REGISTRY`, `VALID_THEMES`, `isThemeName`, `resolveTheme` |\n| App/provider | `DocsApp`, `DocsAppDefault`, `DocsIndex`, `DeweyProvider`, `useDewey`, `useTheme`, `useComponents`, `useLink` |\n| Layout/content | `Header`, `DocsLayout`, `MarkdownContent`, `CodeBlock`, `HeadingLink`, `Sidebar`, `TableOfContents`, `AutoTableOfContents`, `useActiveSection`, `extractTocItems`, `extractTocFromDom` |\n| UI | `Callout`, `Tabs`, `Tab`, `Steps`, `Step`, `Card`, `CardGrid`, `FileTree`, `ApiTable`, `Badge` |\n| Agent UI | `CopyButtons`, `AgentContext`, `PromptSlideout` |\n| Skills | `promptSlideoutGenerator`, `docsReviewAgent`, `docsDesignCritic`, `installMdGenerator`, `improveAIPrompts`, `improveAIPromptsSkill` |\n| Hooks/utils | `useDarkMode`, `useTableOfContents`, `extractSections`, `cn`, `resolveIcon`, `commonIcons` |\n| Agent content | `agentContent`, `AgentContentBuilder`, `renderAgentMarkdown`, `renderAgentJson`, `renderAgentPlainText` |\n\n## Main module type exports\n\n| Group | Names |\n|---|---|\n| Config/themes | `AgentRule`, `DeweyConfig`, `InstallConfig`, `ProjectType`, `ThemeDefinition`, `ThemeName`, `ThemePreset` |\n| App/provider | `DocsAppProps`, `DocsAppConfig`, `DocsIndexProps`, `DeweyProviderProps`, `DeweyContextValue`, `ThemeConfig`, `FrameworkComponents` |\n| Components | `HeaderProps`, `DocsLayoutProps`, `MarkdownContentProps`, `SidebarProps`, `AutoTocProps`, `TableOfContentsProps`, `TocItem`, `CalloutProps`, `CalloutType`, `TabsProps`, `TabProps`, `StepsProps`, `StepProps`, `CardProps`, `CardGridProps`, `FileTreeProps`, `FileTreeItem`, `ApiTableProps`, `ApiProperty`, `BadgeProps`, `BadgeVariant`, `CopyButtonsProps`, `AgentContextProps`, `PromptSlideoutProps`, `PromptParam` |\n| Skills/content | `PromptSlideoutConfig`, `DocsReviewResult`, `DocsDesignCritiqueResult`, `InstallMdConfig`, `PromptImprovementPass`, `PromptQualityCriteria`, `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, `ListSection` |\n| Navigation/utils | `PageTree`, `PageNode`, `PageItem`, `PageFolder`, `PageSeparator`, `FlatPage`, `NavigationConfig`, `NavigationGroup`, `NavigationItem`, `CommonIconName` |\n| Legacy | `NavItem`, `NavGroup`, `DocSection`, `BadgeColor`, `PageLink`, `DocsConfig` |\n\n## Skills are prompts\n\n| Export | Result type | Meaning |\n|---|---|---|\n| `docsReviewAgent` | `DocsReviewResult` | LLM prompt set: correctness/drift review |\n| `docsDesignCritic` | `DocsDesignCritiqueResult` | LLM prompt set: structure/design critique |\n| `promptSlideoutGenerator` | `PromptSlideoutConfig` | LLM prompt set: slideout authoring |\n| `installMdGenerator` | `InstallMdConfig` | LLM prompt set: install.md authoring |\n| `improveAIPrompts` | `PromptImprovementPass` / `PromptQualityCriteria` | Iterative prompt discovery, draft, review, refinement |\n\n`improveAIPromptsSkill`: deprecated runtime alias, identical object.\n\n## Router and theme contract\n\n- `DocsLayout`: no React Router dependency; default plain anchor; optional `LinkComponent`; optional explicit `currentPage`; browser pathname fallback.\n- `react-router-dom`: not a package peer dependency.\n- Twelve themes × light/dark resolve one `--dw-*` semantic contract across runtime CSS, components, Tailwind, and generated sites.\n- Required categories: surface/foreground; primary/secondary/accent pairs; border/ring; info/warning/error/success pairs; code/syntax; sidebar/header; fonts/radii/shadows/motion.\n- Automated proof: token completeness/dead-token rejection, WCAG AA text pairs, focus, reduced motion, semantic/component checks, and 24 Playwright screenshots.\n\n## Structured agent content\n\n```ts\nimport { agentContent, renderAgentMarkdown } from '@arach/dewey'\n\nconst content = agentContent('api', 'API', 'Public contracts')\n .enums('Themes', { ThemePreset: ['neutral', 'ocean'] })\n .code('Import', 'ts', \"import { defineConfig } from '@arach/dewey'\")\n .build()\n\nconst markdown = renderAgentMarkdown(content)\n```\n\nRuntime: `agentContent`, `AgentContentBuilder`, `renderAgentMarkdown`, `renderAgentJson`, `renderAgentPlainText`.\n\nTypes: `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, `ListSection`.\n", "content": "# Dewey API - Agent Context\n\n## Purpose\n\nPublic contracts for `@arach/dewey`. CLI generation/audit is the primary product; TypeScript artifact APIs enable retrieval automation; React/theme APIs are optional presentation.\n\n## Source of truth\n\n| Surface | Source path |\n|---|---|\n| Main public exports | `packages/docs/src/index.ts` |\n| Package subpaths | `packages/docs/package.json` |\n| Config schema | `packages/docs/src/cli/schema.ts` |\n| CLI commands/options | `packages/docs/src/cli/index.ts` |\n| Artifact API | `packages/docs/src/cli/agent-artifacts.ts` |\n| Ownership planner | `packages/docs/src/cli/generation-plan.ts` |\n| Theme registry | `packages/docs/src/themes.ts` |\n| React contracts | `packages/docs/src/components/` |\n| Navigation types | `packages/docs/src/types/page-tree.ts` |\n| Legacy types | `packages/docs/src/types.ts` |\n| Structured agent content | `packages/docs/src/utils/agent-content.ts` |\n\n## Surface selection\n\n| Goal | Use |\n|---|---|\n| Generate agent artifacts | `bunx dewey generate` |\n| Deterministic structural validation | `bunx dewey audit` |\n| Evidence-based readiness score | `bunx dewey agent` |\n| Typed config | `defineConfig` from `@arach/dewey` |\n| Programmatic retrieval/build/write | `@arach/dewey/agent-artifacts` |\n| Existing React/Next UI | components from `@arach/dewey` + CSS subpaths |\n| Standalone docs UI | `bunx dewey create` |\n\nInvariant: CLI/artifact generation is the product contract. React components and generated sites are optional human-facing layers. Maintain human `.md` + dense `.agent.md` pairs.\n\n## Package subpaths\n\n| Import | Contract |\n|---|---|\n| `@arach/dewey` | Main JS/types |\n| `@arach/dewey/react` | Exact compatibility alias of main JS/types |\n| `@arach/dewey/agent-artifacts` | Artifact JS/types |\n| `@arach/dewey/css` | Full CSS |\n| `@arach/dewey/styles` | Full CSS alias |\n| `@arach/dewey/css/base.css` | Base CSS |\n| `@arach/dewey/css/tokens` | Semantic token CSS |\n| `@arach/dewey/css/tailwind` | Tailwind-oriented CSS |\n| `@arach/dewey/css/colors/{theme}.css` | Explicit per-theme CSS export; no wildcard |\n| `@arach/dewey/tailwind` | Tailwind preset JS/types |\n\n## Config\n\n```ts\nimport { defineConfig } from '@arach/dewey'\n\nexport default defineConfig({\n project: { name: 'pkg', type: 'npm-package', version: '1.0.0' },\n agent: {\n criticalContext: ['Use Bun'],\n entryPoints: { API: 'src/index.ts' },\n rules: [{ pattern: '*.test.ts', instruction: 'Use bun:test.' }],\n sections: [],\n },\n docs: {\n path: './docs',\n output: './',\n required: ['overview', 'quickstart', 'api'],\n },\n install: {\n objective: 'Install pkg.',\n prerequisites: ['Node.js 18+'],\n steps: [{ description: 'Install', command: 'bun add pkg' }],\n doneWhen: { command: 'bun test', expectedOutput: 'all tests pass' },\n },\n})\n```\n\n`defineConfig(input): DeweyConfig` parses with Zod and throws on invalid input.\n\n| Config path | Type | Default/required |\n|---|---|---|\n| `project.name` | `string` | required |\n| `project.tagline` | `string?` | optional |\n| `project.type` | `ProjectType` | `'generic'` |\n| `project.version` | `string?` | optional |\n| `agent.criticalContext` | `string[]` | `[]` |\n| `agent.entryPoints` | `Record` | `{}` |\n| `agent.rules` | `AgentRule[]` | `[]` |\n| `agent.sections` | `string[]` | `[]`; empty = every human-readable doc |\n| `docs.path` | `string` | `'./docs'` |\n| `docs.output` | `string` | `'./'` |\n| `docs.required` | `string[]` | `['overview','quickstart']` |\n| `install.objective` | `string?` | optional |\n| `install.doneWhen` | `{command:string;expectedOutput?:string}?` | optional |\n| `install.prerequisites` | `string[]` | `[]` |\n| `install.steps` | `{description:string;command?:string;alternatives?:{condition:string;command:string}[]}[]` | `[]` |\n| `install.hostedUrl` | `string?` | optional |\n\n`ProjectType = 'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`.\n\nMain config types: `AgentRule`, `DeweyConfig`, `InstallConfig`, `ProjectType`.\n\n## Artifact API\n\nImport only from `@arach/dewey/agent-artifacts`.\n\n| Export | Contract |\n|---|---|\n| `collectMarkdownArtifacts(options?)` | `Promise`; recursive `.md`/`.mdx`, deterministic sort |\n| `getMarkdownArtifact(slug, options?)` | `Promise`; normalized slug/source lookup |\n| `getPromptArtifact(promptId, options?)` | `Promise`; prompt lookup |\n| `parseDocArtifact(filePath, raw?, options?)` | `Promise` |\n| `buildAgentManifest(docs, {project?,includeContent?}?)` | `AgentManifest` |\n| `buildPromptRegistry(docs, {project?,includeContent?}?)` | schema-versioned registry object |\n| `buildContextBundle(docs, slugs, title?)` | Markdown `string` |\n| `buildAgentArtifactFiles(options?)` | in-memory generated file set; no apply |\n| `writeAgentArtifacts(options?)` | plans and optionally applies writes; returns `docs`, `prompts`, `written`, `changed`, `deleted`, `operations` |\n\n```ts\nimport {\n collectMarkdownArtifacts,\n buildAgentManifest,\n writeAgentArtifacts,\n} from '@arach/dewey/agent-artifacts'\n\nconst input = { rootDir: process.cwd(), docsDir: './docs' }\nconst project = { name: 'pkg', version: '1.0.0' }\nconst docs = await collectMarkdownArtifacts(input)\nconst manifest = buildAgentManifest(docs, { project })\nconst preview = await writeAgentArtifacts({\n ...input,\n outputDir: './generated',\n project,\n dryRun: true,\n})\nconsole.log(manifest.recommendedReadOrder, preview.operations)\n```\n\n| Type | Fields |\n|---|---|\n| `CollectMarkdownArtifactsOptions` | `rootDir?`, `docsDir?` |\n| `WriteAgentArtifactsOptions` | previous + `outputDir?`, `project?`, `dryRun?`, `overwrite?` |\n| `AgentArtifactsProject` | `name`, `version?`, `tagline?`, `repository?` |\n| `MarkdownHeading` | `depth`, `text`, `anchor` |\n| `MarkdownArtifact` | `id`, `slug`, `kind`, `promptId?`, `title`, `description`, `sourcePath`, `url`, `rawUrl`, `promptUrl?`, `frontmatter`, `headings`, `tokensEstimate`, `rawMarkdown`, `content` |\n\nOther exported artifact types: `AgentManifest`, `AgentManifestEntry`, `PromptManifestEntry`.\n\n`MarkdownArtifactKind = 'doc' | 'agent' | 'prompt' | 'reference' | 'proposal'`.\n\n| Slug/path condition, first match | Kind |\n|---|---|\n| starts `prompts/` | `prompt` |\n| starts `agent/` or ends `.agent` | `agent` |\n| starts `reference/` | `reference` |\n| starts `proposals/` | `proposal` |\n| otherwise | `doc` |\n\nWrite semantics: `dryRun` never applies; desired unowned outputs block unless `overwrite`; stale deletion is limited to Dewey-owned outputs in `agentArtifacts` scope.\n\n## Themes\n\n```text\nThemeName = ThemePreset =\n'neutral' | 'ocean' | 'emerald' | 'purple' | 'dusk' | 'rose' | 'github' |\n'warm' | 'midnight' | 'editorial' | 'mono' | 'hudson'\n```\n\n| Export | Contract |\n|---|---|\n| `THEME_REGISTRY` | canonical name -> `{cssFile,generatedSite}` |\n| `PUBLISHED_CSS_THEMES` | readonly presets with CSS |\n| `VALID_THEMES` | readonly presets accepted by generated sites |\n| `isThemeName(string)` | type guard |\n| `resolveTheme(string?)` | valid theme or `'neutral'` fallback |\n\nAll current themes are published and generated-site-valid. Pair `theme=\"ocean\"` with `@arach/dewey/css/colors/ocean.css`.\n\nCustom `ThemeConfig`: `preset?: ThemePreset`; `colors?: {primary?,background?,foreground?,accent?}`; `fonts?: {sans?,mono?}`.\n\n## React minimal example\n\n```tsx\n'use client'\nimport {\n AutoTableOfContents,\n CopyButtons,\n DeweyProvider,\n MarkdownContent,\n} from '@arach/dewey'\nimport '@arach/dewey/css/base.css'\nimport '@arach/dewey/css/tokens'\nimport '@arach/dewey/css/colors/ocean.css'\n\nexport function Page({ markdown, agentMarkdown }: {\n markdown: string\n agentMarkdown: string\n}) {\n return (\n \n \n \n \n \n )\n}\n```\n\nProvider rule: components using Dewey context hooks require `DeweyProvider`. Next App Router: provider/interactive layer is client; filesystem/static-param work is server.\n\n## Component contracts\n\n| Value export | Required props | Optional contract |\n|---|---|---|\n| `DeweyProvider` | `children` | `components`, `theme`, `defaultDark`, `storageKey` |\n| `DocsApp` | `docs: Record` | `config`, `currentPage`, `providerProps`; `onNavigate` reserved/not invoked |\n| `DocsIndex` | `tree: PageNode[]` | `projectName`, `tagline`, `description`, `basePath`, `hero`, `showSearch`, `heroIcon`, `quickLinks`, `layout?: 'stacked'|'columns'` |\n| `Header` | none | `projectName`, `homeUrl`, `backUrl`, `backLabel`, `label`, `showThemeToggle`, `actions` |\n| `Sidebar` | `tree` | `currentPage`, `projectName`, `basePath`, `isOpen`, `onClose`, `header`, `footer` |\n| `MarkdownContent` | `content` | `isDark` |\n| `TableOfContents` | none | `items`, `title`, `className`, `scrollOffset` |\n| `AutoTableOfContents` | none | `markdown`, `containerRef`, `title`, `className` |\n| `Callout` | `children` | `type`, `title` |\n| `Tabs` / `Tab` | `children`; Tab: `label` | Tabs: `defaultTab` |\n| `Steps` / `Step` | `children`; Step: `title` | — |\n| `Card` | `title` | `description`, `icon`, `href`, `children` |\n| `CardGrid` | `children` | `columns?: 2|3|4` |\n| `FileTree` | `items` | `defaultExpanded`; item `type?: 'file'|'folder'` |\n| `ApiTable` | `properties` | `title` |\n| `Badge` | `children` | `variant`, `size?: 'sm'|'md'` |\n| `CopyButtons` | `markdownContent` | `agentContent`, `showLabels`, `onCopy`, `className` |\n| `AgentContext` | `content` | `title`, `defaultExpanded`, `className` |\n| `PromptSlideout` | `isOpen`, `onClose`, `info`, `starterTemplate` | `title`, `description`, `params`, `examples`, `expectedOutput`, `className` |\n\n`DocsLayout` is router-neutral: it uses plain anchors by default and accepts `LinkComponent` plus `currentPage` for host integration. `DocsLayoutProps` is re-exported from main. `CodeBlock` and `HeadingLink` values are public; their prop interfaces are not exported.\n\n## Component/navigation unions\n\n```text\nCalloutType = 'info' | 'warning' | 'tip' | 'danger'\nBadgeVariant = 'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple'\nCopyButtons.onCopy type = 'markdown' | 'agent' | 'plain'\nPageNode.type = 'page' | 'folder' | 'separator'\nPage/navigation badgeColor = 'info' | 'success' | 'warning' | 'error' | 'default'\nDocsAppConfig.layout.header = boolean | 'minimal'\nlegacy BadgeColor = 'blue' | 'emerald' | 'purple' | 'amber' | 'rose'\nlegacy DocSection.level = 2 | 3\n```\n\n## Main module runtime exports\n\n| Group | Names |\n|---|---|\n| Config | `defineConfig` |\n| Themes | `PUBLISHED_CSS_THEMES`, `THEME_REGISTRY`, `VALID_THEMES`, `isThemeName`, `resolveTheme` |\n| App/provider | `DocsApp`, `DocsAppDefault`, `DocsIndex`, `DeweyProvider`, `useDewey`, `useTheme`, `useComponents`, `useLink` |\n| Layout/content | `Header`, `DocsLayout`, `MarkdownContent`, `CodeBlock`, `HeadingLink`, `Sidebar`, `TableOfContents`, `AutoTableOfContents`, `useActiveSection`, `extractTocItems`, `extractTocFromDom` |\n| UI | `Callout`, `Tabs`, `Tab`, `Steps`, `Step`, `Card`, `CardGrid`, `FileTree`, `ApiTable`, `Badge` |\n| Agent UI | `CopyButtons`, `AgentContext`, `PromptSlideout` |\n| Skills | `promptSlideoutGenerator`, `docsReviewAgent`, `docsDesignCritic`, `installMdGenerator`, `improveAIPrompts`, `improveAIPromptsSkill` |\n| Hooks/utils | `useDarkMode`, `useTableOfContents`, `extractSections`, `cn`, `resolveIcon`, `commonIcons` |\n| Agent content | `agentContent`, `AgentContentBuilder`, `renderAgentMarkdown`, `renderAgentJson`, `renderAgentPlainText` |\n\n## Main module type exports\n\n| Group | Names |\n|---|---|\n| Config/themes | `AgentRule`, `DeweyConfig`, `InstallConfig`, `ProjectType`, `ThemeDefinition`, `ThemeName`, `ThemePreset` |\n| App/provider | `DocsAppProps`, `DocsAppConfig`, `DocsIndexProps`, `DeweyProviderProps`, `DeweyContextValue`, `ThemeConfig`, `FrameworkComponents` |\n| Components | `HeaderProps`, `DocsLayoutProps`, `MarkdownContentProps`, `SidebarProps`, `AutoTocProps`, `TableOfContentsProps`, `TocItem`, `CalloutProps`, `CalloutType`, `TabsProps`, `TabProps`, `StepsProps`, `StepProps`, `CardProps`, `CardGridProps`, `FileTreeProps`, `FileTreeItem`, `ApiTableProps`, `ApiProperty`, `BadgeProps`, `BadgeVariant`, `CopyButtonsProps`, `AgentContextProps`, `PromptSlideoutProps`, `PromptParam` |\n| Skills/content | `PromptSlideoutConfig`, `DocsReviewResult`, `DocsDesignCritiqueResult`, `InstallMdConfig`, `PromptImprovementPass`, `PromptQualityCriteria`, `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, `ListSection` |\n| Navigation/utils | `PageTree`, `PageNode`, `PageItem`, `PageFolder`, `PageSeparator`, `FlatPage`, `NavigationConfig`, `NavigationGroup`, `NavigationItem`, `CommonIconName` |\n| Legacy | `NavItem`, `NavGroup`, `DocSection`, `BadgeColor`, `PageLink`, `DocsConfig` |\n\n## Skills are prompts\n\n| Export | Result type | Meaning |\n|---|---|---|\n| `docsReviewAgent` | `DocsReviewResult` | LLM prompt set: correctness/drift review |\n| `docsDesignCritic` | `DocsDesignCritiqueResult` | LLM prompt set: structure/design critique |\n| `promptSlideoutGenerator` | `PromptSlideoutConfig` | LLM prompt set: slideout authoring |\n| `installMdGenerator` | `InstallMdConfig` | LLM prompt set: install.md authoring |\n| `improveAIPrompts` | `PromptImprovementPass` / `PromptQualityCriteria` | Iterative prompt discovery, draft, review, refinement |\n\n`improveAIPromptsSkill`: deprecated runtime alias, identical object.\n\n## Router and theme contract\n\n- `DocsLayout`: no React Router dependency; default plain anchor; optional `LinkComponent`; optional explicit `currentPage`; browser pathname fallback.\n- `react-router-dom`: not a package peer dependency.\n- Twelve themes × light/dark resolve one `--dw-*` semantic contract across runtime CSS, components, Tailwind, and generated sites.\n- Required categories: surface/foreground; primary/secondary/accent pairs; border/ring; info/warning/error/success pairs; code/syntax; sidebar/header; fonts/radii/shadows/motion.\n- Automated proof: token completeness/dead-token rejection, WCAG AA text pairs, focus, reduced motion, semantic/component checks, and 24 Playwright screenshots.\n\n## Structured agent content\n\n```ts\nimport { agentContent, renderAgentMarkdown } from '@arach/dewey'\n\nconst content = agentContent('api', 'API', 'Public contracts')\n .enums('Themes', { ThemePreset: ['neutral', 'ocean'] })\n .code('Import', 'ts', \"import { defineConfig } from '@arach/dewey'\")\n .build()\n\nconst markdown = renderAgentMarkdown(content)\n```\n\nRuntime: `agentContent`, `AgentContentBuilder`, `renderAgentMarkdown`, `renderAgentJson`, `renderAgentPlainText`.\n\nTypes: `AgentContent`, `AgentSection`, `TableSection`, `EnumSection`, `CodeSection`, `TextSection`, `ListSection`." }, { "id": "agent/cli.agent", "slug": "agent/cli.agent", "kind": "agent", "title": "CLI Reference", "description": "Dense Dewey CLI contract for agents", "sourcePath": "docs/agent/cli.agent.md", "url": "/agent/raw/docs/agent/cli.agent.md", "rawUrl": "/agent/raw/docs/agent/cli.agent.md", "headings": [ { "depth": 1, "text": "Dewey CLI", "anchor": "dewey-cli" }, { "depth": 2, "text": "Direct execution", "anchor": "direct-execution" }, { "depth": 2, "text": "Recommended order", "anchor": "recommended-order" }, { "depth": 2, "text": "Generation selection", "anchor": "generation-selection" }, { "depth": 2, "text": "Audit versus agent", "anchor": "audit-versus-agent" }, { "depth": 2, "text": "Project type contract", "anchor": "project-type-contract" }, { "depth": 2, "text": "Canonical generation contract", "anchor": "canonical-generation-contract" }, { "depth": 2, "text": "JSON evidence and drift", "anchor": "json-evidence-and-drift" }, { "depth": 2, "text": "Maintenance contract", "anchor": "maintenance-contract" }, { "depth": 2, "text": "Automation error contract", "anchor": "automation-error-contract" } ], "tokensEstimate": 939, "frontmatter": { "title": "CLI Reference", "description": "Dense Dewey CLI contract for agents", "order": 3, "group": "Reference", "groupId": "reference" }, "markdown": "---\ntitle: CLI Reference\ndescription: Dense Dewey CLI contract for agents\norder: 3\ngroup: Reference\ngroupId: reference\n---\n\n# Dewey CLI\n\n| Command | Inputs | Writes | Purpose |\n|---|---|---|---|\n| `dewey init` | `--type`, `--force` | `docs/`, `dewey.config.ts` | Initialize Dewey |\n| `dewey audit` | `--verbose`, `--json` | none | Check documentation quality |\n| `dewey generate` | `--source`, `--output`, artifact selectors | root artifacts, `agent/` | Compile docs for humans, agents, and tooling |\n| `dewey agent` | `--verbose`, `--json` | none | Evaluate agent-readiness and recommend improvements |\n| `dewey create ` | `--source`, `--template`, `--theme`, `--name` | generated site | Publish Markdown through Next.js or Astro |\n| `dewey update [dir]` | `--dry-run`, `--force` | Dewey-owned site files | Upgrade or adopt a generated site |\n| `dewey eject [dir]` | `--full` | consumer-owned component | Transfer ownership for customization |\n\n## Direct execution\n\n```bash\nbunx @arach/dewey@latest \n```\n\n## Recommended order\n\n`init` → author → `generate` → `audit` → `agent` → optional UI (`docs/integrate-existing-site.md` or `create`).\n\n## Generation selection\n\n- Default: all standard files plus `agent/` retrieval artifacts.\n- `agent.sections: []`: recursively include every human-readable `.md` file.\n- Non-empty `agent.sections`: exact doc-ID allowlist, including nested IDs such as `guides/install`.\n- `--source `: override `docs.path` for one run.\n- `--output `: override `docs.output`; directory is created recursively.\n- `--dry-run`: print create/update/preserve/delete operations without writing.\n- `--overwrite`: explicitly replace reviewed desired-output conflicts, including modified or unowned targets; use only after `--dry-run`.\n\n## Audit versus agent\n\n| Command | Contract |\n|---|---|\n| `audit` | Deterministic structural validation of every discovered human page |\n| `agent` | Evidence-based readiness coaching; reports a score and next actions; writes nothing |\n\n## Project type contract\n\n`ProjectType = 'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`\n\n| Type | `init` focus pair | Evidence required by audit/agent |\n|---|---|---|\n| `generic` | `architecture.md` + agent pair | Architecture/system structure; interface or integration boundary |\n| `npm-package` | `api.md` + agent pair | Package-manager installation; typed public API |\n| `cli-tool` | `commands.md` + agent pair | Commands/options; executable shell usage |\n| `react-library` | `components.md` + agent pair | Components/props; JSX/TSX example |\n| `macos-app` | `architecture.md` + agent pair | macOS lifecycle; Swift/SwiftUI/Xcode evidence |\n| `monorepo` | `packages.md` + agent pair | Workspaces/monorepo; `packages/` or `apps/` paths |\n\n`init --type` changes required docs, paired scaffold content, install defaults, and verification commands. Invalid values fail and list every valid value.\n\n## Canonical generation contract\n\n- One recursive discovery/frontmatter pipeline serves `generate`, `create`, and `@arach/dewey/agent-artifacts`.\n- One `AgentManifest` drives retrieval links, read order, context indexes, and bundle selection.\n- `agent/context.md` + `agent/context.json`: retrieval metadata/indexes; no repeated full document corpus.\n- `agent/docs.json`: content for doc/agent/reference/proposal entries.\n- `agent/prompts.json`: prompt content.\n- `agent/raw/docs/**` + `agent/bundles/**`: intentional full Markdown retrieval surfaces.\n- `llms.txt`: description → prose → list → heading → title summary fallback.\n- Prompt fallback URLs remove exactly one leading `prompts/` segment.\n- Scoped install name such as `@scope/package` remains scoped.\n- `create` composes the artifact writer after scaffold creation.\n- Generated Next.js/Astro dependencies are exact tested versions; Pagefind is declared.\n- Unknown theme: warn, then resolve to `neutral`.\n\n## JSON evidence and drift\n\nBoth `audit --json` and `agent --json` contain `projectType` and `drift`.\n\n| Drift field | Contract |\n|---|---|\n| `status` | `clean` / `issues` / `not-applicable` |\n| Counts | `checkedPairs`, `checkedSourceFiles`, `checkedSourceReferences`, `checkedContracts` |\n| Issue codes | `MISSING_AGENT_COUNTERPART`, `ORPHAN_AGENT_DOCUMENT`, `MISSING_SOURCE_REFERENCE`, `AGENT_CONTRACT_MISSING`, `HUMAN_AGENT_CONTRACT_MISMATCH`, `DOC_SOURCE_CONTRACT_MISMATCH` |\n\nHuman summary always prints project-type and drift status; `--verbose` prints evidence and issue details. `audit` adds recommendations but retains structural page scoring. `agent` uses project evidence and unresolved contract drift in readiness scoring.\n\nLimitations: regex/evidence analysis only; conventional/configured TS/TSX/JS/JSX/Swift source trees; no example execution, semantic prose equivalence, or arbitrary computed-type analysis.\n\n## Maintenance contract\n\n- `update` flags: `--dry-run`, `--force`; no `--refresh-nav`.\n- First `update` can adopt manifest-less generated Astro or Next.js sites, writes `.dewey-manifest.json`, then asks for a second run.\n- `eject` supports Next.js `Header`, `Sidebar`, `TableOfContents`, `MarkdownContent`; mode `wrap` or `full`.\n- Exact ownership/recovery/backup behavior: `docs/agent/maintenance.agent.md`.\n\n## Automation error contract\n\n- Invalid configuration or command input is rejected with a non-zero exit status.\n- For `--json`, check process success before parsing stdout.\n- Shell pattern: `if ! report=\"$(bunx dewey audit --json)\"; then echo \"Dewey audit failed\" >&2; exit 1; fi`.\n", "content": "# Dewey CLI\n\n| Command | Inputs | Writes | Purpose |\n|---|---|---|---|\n| `dewey init` | `--type`, `--force` | `docs/`, `dewey.config.ts` | Initialize Dewey |\n| `dewey audit` | `--verbose`, `--json` | none | Check documentation quality |\n| `dewey generate` | `--source`, `--output`, artifact selectors | root artifacts, `agent/` | Compile docs for humans, agents, and tooling |\n| `dewey agent` | `--verbose`, `--json` | none | Evaluate agent-readiness and recommend improvements |\n| `dewey create ` | `--source`, `--template`, `--theme`, `--name` | generated site | Publish Markdown through Next.js or Astro |\n| `dewey update [dir]` | `--dry-run`, `--force` | Dewey-owned site files | Upgrade or adopt a generated site |\n| `dewey eject [dir]` | `--full` | consumer-owned component | Transfer ownership for customization |\n\n## Direct execution\n\n```bash\nbunx @arach/dewey@latest \n```\n\n## Recommended order\n\n`init` → author → `generate` → `audit` → `agent` → optional UI (`docs/integrate-existing-site.md` or `create`).\n\n## Generation selection\n\n- Default: all standard files plus `agent/` retrieval artifacts.\n- `agent.sections: []`: recursively include every human-readable `.md` file.\n- Non-empty `agent.sections`: exact doc-ID allowlist, including nested IDs such as `guides/install`.\n- `--source `: override `docs.path` for one run.\n- `--output `: override `docs.output`; directory is created recursively.\n- `--dry-run`: print create/update/preserve/delete operations without writing.\n- `--overwrite`: explicitly replace reviewed desired-output conflicts, including modified or unowned targets; use only after `--dry-run`.\n\n## Audit versus agent\n\n| Command | Contract |\n|---|---|\n| `audit` | Deterministic structural validation of every discovered human page |\n| `agent` | Evidence-based readiness coaching; reports a score and next actions; writes nothing |\n\n## Project type contract\n\n`ProjectType = 'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`\n\n| Type | `init` focus pair | Evidence required by audit/agent |\n|---|---|---|\n| `generic` | `architecture.md` + agent pair | Architecture/system structure; interface or integration boundary |\n| `npm-package` | `api.md` + agent pair | Package-manager installation; typed public API |\n| `cli-tool` | `commands.md` + agent pair | Commands/options; executable shell usage |\n| `react-library` | `components.md` + agent pair | Components/props; JSX/TSX example |\n| `macos-app` | `architecture.md` + agent pair | macOS lifecycle; Swift/SwiftUI/Xcode evidence |\n| `monorepo` | `packages.md` + agent pair | Workspaces/monorepo; `packages/` or `apps/` paths |\n\n`init --type` changes required docs, paired scaffold content, install defaults, and verification commands. Invalid values fail and list every valid value.\n\n## Canonical generation contract\n\n- One recursive discovery/frontmatter pipeline serves `generate`, `create`, and `@arach/dewey/agent-artifacts`.\n- One `AgentManifest` drives retrieval links, read order, context indexes, and bundle selection.\n- `agent/context.md` + `agent/context.json`: retrieval metadata/indexes; no repeated full document corpus.\n- `agent/docs.json`: content for doc/agent/reference/proposal entries.\n- `agent/prompts.json`: prompt content.\n- `agent/raw/docs/**` + `agent/bundles/**`: intentional full Markdown retrieval surfaces.\n- `llms.txt`: description → prose → list → heading → title summary fallback.\n- Prompt fallback URLs remove exactly one leading `prompts/` segment.\n- Scoped install name such as `@scope/package` remains scoped.\n- `create` composes the artifact writer after scaffold creation.\n- Generated Next.js/Astro dependencies are exact tested versions; Pagefind is declared.\n- Unknown theme: warn, then resolve to `neutral`.\n\n## JSON evidence and drift\n\nBoth `audit --json` and `agent --json` contain `projectType` and `drift`.\n\n| Drift field | Contract |\n|---|---|\n| `status` | `clean` / `issues` / `not-applicable` |\n| Counts | `checkedPairs`, `checkedSourceFiles`, `checkedSourceReferences`, `checkedContracts` |\n| Issue codes | `MISSING_AGENT_COUNTERPART`, `ORPHAN_AGENT_DOCUMENT`, `MISSING_SOURCE_REFERENCE`, `AGENT_CONTRACT_MISSING`, `HUMAN_AGENT_CONTRACT_MISMATCH`, `DOC_SOURCE_CONTRACT_MISMATCH` |\n\nHuman summary always prints project-type and drift status; `--verbose` prints evidence and issue details. `audit` adds recommendations but retains structural page scoring. `agent` uses project evidence and unresolved contract drift in readiness scoring.\n\nLimitations: regex/evidence analysis only; conventional/configured TS/TSX/JS/JSX/Swift source trees; no example execution, semantic prose equivalence, or arbitrary computed-type analysis.\n\n## Maintenance contract\n\n- `update` flags: `--dry-run`, `--force`; no `--refresh-nav`.\n- First `update` can adopt manifest-less generated Astro or Next.js sites, writes `.dewey-manifest.json`, then asks for a second run.\n- `eject` supports Next.js `Header`, `Sidebar`, `TableOfContents`, `MarkdownContent`; mode `wrap` or `full`.\n- Exact ownership/recovery/backup behavior: `docs/agent/maintenance.agent.md`.\n\n## Automation error contract\n\n- Invalid configuration or command input is rejected with a non-zero exit status.\n- For `--json`, check process success before parsing stdout.\n- Shell pattern: `if ! report=\"$(bunx dewey audit --json)\"; then echo \"Dewey audit failed\" >&2; exit 1; fi`." }, { "id": "agent/integrate-existing-site.agent", "slug": "agent/integrate-existing-site.agent", "kind": "agent", "title": "Integrate existing site (agent)", "description": "Dense contract for embedding Dewey components in React/Next.js while keeping generate/audit/agent as the core path", "sourcePath": "docs/agent/integrate-existing-site.agent.md", "url": "/agent/raw/docs/agent/integrate-existing-site.agent.md", "rawUrl": "/agent/raw/docs/agent/integrate-existing-site.agent.md", "headings": [ { "depth": 1, "text": "Dewey embed contract (existing React / Next.js)", "anchor": "dewey-embed-contract-existing-react-next-js" }, { "depth": 2, "text": "Positioning", "anchor": "positioning" }, { "depth": 2, "text": "Decision table", "anchor": "decision-table" }, { "depth": 2, "text": "Install", "anchor": "install" }, { "depth": 2, "text": "Onboarding sequence (shared)", "anchor": "onboarding-sequence-shared" }, { "depth": 2, "text": "Architecture (Next App Router)", "anchor": "architecture-next-app-router" }, { "depth": 3, "text": "Boundary rule", "anchor": "boundary-rule" }, { "depth": 3, "text": "Prefer composed shell", "anchor": "prefer-composed-shell" }, { "depth": 2, "text": "Theme proof contract", "anchor": "theme-proof-contract" }, { "depth": 2, "text": "Static export", "anchor": "static-export" }, { "depth": 2, "text": "Content discovery rules", "anchor": "content-discovery-rules" }, { "depth": 2, "text": "Provider snippet contract", "anchor": "provider-snippet-contract" }, { "depth": 2, "text": "Scripts (host package.json)", "anchor": "scripts-host-package-json" }, { "depth": 2, "text": "CI (minimum)", "anchor": "ci-minimum" }, { "depth": 2, "text": "Public agent URLs (optional)", "anchor": "public-agent-urls-optional" }, { "depth": 2, "text": "Monorepo", "anchor": "monorepo" }, { "depth": 2, "text": "Anti-patterns", "anchor": "anti-patterns" }, { "depth": 2, "text": "Related paths", "anchor": "related-paths" } ], "tokensEstimate": 1328, "frontmatter": { "title": "Integrate existing site (agent)", "description": "Dense contract for embedding Dewey components in React/Next.js while keeping generate/audit/agent as the core path", "order": 6, "group": "Guides", "groupId": "guides" }, "markdown": "---\ntitle: Integrate existing site (agent)\ndescription: Dense contract for embedding Dewey components in React/Next.js while keeping generate/audit/agent as the core path\norder: 6\ngroup: Guides\ngroupId: guides\n---\n\n# Dewey embed contract (existing React / Next.js)\n\n## Positioning\n\n| Layer | Role | Required? |\n|---|---|---|\n| CLI `init` / `audit` / `generate` / `agent` | Judgment + retrieval artifacts | Yes for agent-ready docs |\n| React components + CSS | Optional human UI in host app | No |\n| `dewey create` | Scaffold standalone site | Alternative to embed |\n\nDewey is a **docs agent**, not a docs framework. Embedding components does not replace generation.\n\n## Decision table\n\n| Situation | Action |\n|---|---|\n| Existing React/Next app needs `/docs` | Embed components (this doc) |\n| No site yet | `bunx dewey create … --template nextjs` |\n| Agents only | `bunx dewey generate` (+ audit/agent); skip UI |\n\n## Install\n\n```bash\nbun add @arach/dewey gray-matter\n```\n\n| Export | Use |\n|---|---|\n| `@arach/dewey` | Canonical JS/TS imports |\n| `@arach/dewey/react` | **Same as main** — compatibility alias only |\n| `@arach/dewey/css` | Full CSS bundle |\n| `@arach/dewey/css/base.css` | Base |\n| `@arach/dewey/css/tokens` | `--dw-*` tokens |\n| `@arach/dewey/css/colors/.css` | Theme preset |\n| `@arach/dewey/tailwind` | Tailwind preset |\n| `@arach/dewey/agent-artifacts` | Programmatic collectors |\n\nRouter dependency: none. `react-router-dom` is not a peer dependency.\n\n**Themes:** `neutral` \\| `ocean` \\| `emerald` \\| `purple` \\| `dusk` \\| `rose` \\| `github` \\| `warm` \\| `midnight` \\| `editorial` \\| `mono` \\| `hudson`\n\n## Onboarding sequence (shared)\n\n| # | Step | Command / action |\n|---|---|---|\n| 1 | Install | `bun add @arach/dewey gray-matter` |\n| 2 | Init | `bunx dewey init` (if no `docs/` + config) |\n| 3 | Author | Human `.md` + optional `.agent.md` |\n| 4 | Generate | `bunx dewey generate` |\n| 5 | Audit | `bunx dewey audit` / `--json` |\n| 6 | Score | `bunx dewey agent` / `--json` |\n| 7 | Embed UI | Host routes + provider + loaders |\n| 8 | Optional | `bunx dewey create` only for separate site |\n\n## Architecture (Next App Router)\n\n| File | Runtime | Duty |\n|---|---|---|\n| `app/layout.tsx` | server | CSS imports, wrap `Providers` |\n| `app/providers.tsx` | client | `DeweyProvider` + Next `Link`/`Image` |\n| `app/docs/layout.tsx` | client (typical) | `Header` + `Sidebar` |\n| `app/docs/[...slug]/page.tsx` | server | `getDocBySlug`, `generateStaticParams` |\n| `app/docs/[...slug]/content.tsx` | client | `MarkdownContent`, TOC, `CopyButtons` |\n| `lib/docs.ts` | server-only | Recursive fs + gray-matter |\n| `lib/navigation.ts` | either | Nav from `docs.json` |\n\n### Boundary rule\n\n- Hooks / Dewey interactive UI → **client** (`'use client'`).\n- `generateStaticParams` / fs / static export → **server**.\n- Cross boundary: serializable props only (`DocData` strings/numbers).\n\n### Prefer composed shell\n\nCompose `Header`, `Sidebar`, `MarkdownContent`, `AutoTableOfContents` for maximum host control. `DocsLayout` is also router-neutral: default anchors, optional `LinkComponent`, optional `currentPage`, browser-path fallback.\n\n## Theme proof contract\n\n- Twelve presets; light and dark.\n- Shared semantic `--dw-*` contract across components, CSS, Tailwind, generated sites.\n- Categories: surfaces/foregrounds; primary/secondary/accent; border/ring; status pairs; code/syntax; sidebar/header; typography/radius/shadow/motion.\n- Tests: complete/dead tokens, WCAG AA text pairs, focus, reduced motion, component semantics, 24 Playwright screenshots.\n\n## Static export\n\n```js\n// next.config.js\nmodule.exports = {\n output: 'export',\n images: { unoptimized: true },\n transpilePackages: ['@arach/dewey'],\n}\n```\n\n| Key | Required for |\n|---|---|\n| `output: 'export'` | Pure static `out/` |\n| `images.unoptimized` | Next Image under export |\n| `transpilePackages` | Bundle `@arach/dewey` ESM |\n| `generateStaticParams` | Pre-render every nested slug |\n\n## Content discovery rules\n\n| Rule | Value |\n|---|---|\n| Human pages | recursive `**/*.md` excluding `*.agent.md` |\n| Agent colocated | `.agent.md` beside human file |\n| Agent nested | `docs/agent/.agent.md` |\n| Slug | path without `.md` (e.g. `guides/install`) |\n| Generate default | `agent.sections: []` → all human docs recursively |\n| CLI override | `dewey generate --source --output ` |\n\n## Provider snippet contract\n\n```tsx\n'use client'\nimport { DeweyProvider } from '@arach/dewey'\nimport type { AnchorHTMLAttributes } from 'react'\nimport Link from 'next/link'\n\ntype DeweyLinkProps = AnchorHTMLAttributes & { href: string }\nconst DeweyLink = ({ href, ...props }: DeweyLinkProps) => \n\n// theme: ThemePreset | ThemeConfig\n// Adapt framework links to Dewey's required string-href contract.\n{children}\n```\n\nRoot `` recommended for theme class hydration.\n\n## Scripts (host package.json)\n\n| Script | Command |\n|---|---|\n| `docs:generate` | `bunx dewey generate` |\n| `docs:audit` | `bunx dewey audit` |\n| `docs:agent` | `bunx dewey agent` |\n| `prebuild` | generate before `next build` when importing `docs.json` / public artifacts |\n\n## CI (minimum)\n\n```bash\nbun install\nbunx dewey generate\nbunx dewey audit --json\nbunx dewey agent --json\n```\n\nGate on audit failures and/or agent score thresholds as policy.\n\n## Public agent URLs (optional)\n\n| Artifact | URL example |\n|---|---|\n| `llms.txt` | `/llms.txt` |\n| `AGENTS.md` | `/AGENTS.md` |\n| `install.md` | `/install.md` |\n| `agent/**` | `/agent/**` |\n\nWrite via `docs.output` / `--output public` or post-generate copy.\n\n## Monorepo\n\n| Case | Approach |\n|---|---|\n| Docs at repo root | Resolve `docsDirectory` to monorepo root, not app `cwd` alone |\n| Docs package | `--source` to package; app depends on `@arach/dewey` |\n| Multi-app | Generate once at root; ship static `agent/` + `docs.json` |\n\n## Anti-patterns\n\n| Don't | Do |\n|---|---|\n| Treat embed as replacing `generate` | Always run generate for agent surface |\n| Import hooks in server `page.tsx` | Split page (server) / content (client) |\n| Use only top-level `docs/*.md` walk | Recursive walk; nested routes |\n| Prefer `@arach/dewey/react` as different API | Import from `@arach/dewey` |\n| Frame as competing docs frameworks | Present as optional UI on agent pipeline |\n\n## Related paths\n\n| Doc | Role |\n|---|---|\n| `docs/integrate-existing-site.md` | Human narrative guide |\n| `docs/quickstart.md` | Greenfield sequence |\n| `docs/cli.md` | Flags |\n| `docs/maintenance.md` | Update/eject ownership, adoption, backups, recovery, release |\n| `packages/docs/src/cli/templates/nextjs.ts` | Canonical scaffold reference (implementation, not consumer edit target) |\n", "content": "# Dewey embed contract (existing React / Next.js)\n\n## Positioning\n\n| Layer | Role | Required? |\n|---|---|---|\n| CLI `init` / `audit` / `generate` / `agent` | Judgment + retrieval artifacts | Yes for agent-ready docs |\n| React components + CSS | Optional human UI in host app | No |\n| `dewey create` | Scaffold standalone site | Alternative to embed |\n\nDewey is a **docs agent**, not a docs framework. Embedding components does not replace generation.\n\n## Decision table\n\n| Situation | Action |\n|---|---|\n| Existing React/Next app needs `/docs` | Embed components (this doc) |\n| No site yet | `bunx dewey create … --template nextjs` |\n| Agents only | `bunx dewey generate` (+ audit/agent); skip UI |\n\n## Install\n\n```bash\nbun add @arach/dewey gray-matter\n```\n\n| Export | Use |\n|---|---|\n| `@arach/dewey` | Canonical JS/TS imports |\n| `@arach/dewey/react` | **Same as main** — compatibility alias only |\n| `@arach/dewey/css` | Full CSS bundle |\n| `@arach/dewey/css/base.css` | Base |\n| `@arach/dewey/css/tokens` | `--dw-*` tokens |\n| `@arach/dewey/css/colors/.css` | Theme preset |\n| `@arach/dewey/tailwind` | Tailwind preset |\n| `@arach/dewey/agent-artifacts` | Programmatic collectors |\n\nRouter dependency: none. `react-router-dom` is not a peer dependency.\n\n**Themes:** `neutral` \\| `ocean` \\| `emerald` \\| `purple` \\| `dusk` \\| `rose` \\| `github` \\| `warm` \\| `midnight` \\| `editorial` \\| `mono` \\| `hudson`\n\n## Onboarding sequence (shared)\n\n| # | Step | Command / action |\n|---|---|---|\n| 1 | Install | `bun add @arach/dewey gray-matter` |\n| 2 | Init | `bunx dewey init` (if no `docs/` + config) |\n| 3 | Author | Human `.md` + optional `.agent.md` |\n| 4 | Generate | `bunx dewey generate` |\n| 5 | Audit | `bunx dewey audit` / `--json` |\n| 6 | Score | `bunx dewey agent` / `--json` |\n| 7 | Embed UI | Host routes + provider + loaders |\n| 8 | Optional | `bunx dewey create` only for separate site |\n\n## Architecture (Next App Router)\n\n| File | Runtime | Duty |\n|---|---|---|\n| `app/layout.tsx` | server | CSS imports, wrap `Providers` |\n| `app/providers.tsx` | client | `DeweyProvider` + Next `Link`/`Image` |\n| `app/docs/layout.tsx` | client (typical) | `Header` + `Sidebar` |\n| `app/docs/[...slug]/page.tsx` | server | `getDocBySlug`, `generateStaticParams` |\n| `app/docs/[...slug]/content.tsx` | client | `MarkdownContent`, TOC, `CopyButtons` |\n| `lib/docs.ts` | server-only | Recursive fs + gray-matter |\n| `lib/navigation.ts` | either | Nav from `docs.json` |\n\n### Boundary rule\n\n- Hooks / Dewey interactive UI → **client** (`'use client'`).\n- `generateStaticParams` / fs / static export → **server**.\n- Cross boundary: serializable props only (`DocData` strings/numbers).\n\n### Prefer composed shell\n\nCompose `Header`, `Sidebar`, `MarkdownContent`, `AutoTableOfContents` for maximum host control. `DocsLayout` is also router-neutral: default anchors, optional `LinkComponent`, optional `currentPage`, browser-path fallback.\n\n## Theme proof contract\n\n- Twelve presets; light and dark.\n- Shared semantic `--dw-*` contract across components, CSS, Tailwind, generated sites.\n- Categories: surfaces/foregrounds; primary/secondary/accent; border/ring; status pairs; code/syntax; sidebar/header; typography/radius/shadow/motion.\n- Tests: complete/dead tokens, WCAG AA text pairs, focus, reduced motion, component semantics, 24 Playwright screenshots.\n\n## Static export\n\n```js\n// next.config.js\nmodule.exports = {\n output: 'export',\n images: { unoptimized: true },\n transpilePackages: ['@arach/dewey'],\n}\n```\n\n| Key | Required for |\n|---|---|\n| `output: 'export'` | Pure static `out/` |\n| `images.unoptimized` | Next Image under export |\n| `transpilePackages` | Bundle `@arach/dewey` ESM |\n| `generateStaticParams` | Pre-render every nested slug |\n\n## Content discovery rules\n\n| Rule | Value |\n|---|---|\n| Human pages | recursive `**/*.md` excluding `*.agent.md` |\n| Agent colocated | `.agent.md` beside human file |\n| Agent nested | `docs/agent/.agent.md` |\n| Slug | path without `.md` (e.g. `guides/install`) |\n| Generate default | `agent.sections: []` → all human docs recursively |\n| CLI override | `dewey generate --source --output ` |\n\n## Provider snippet contract\n\n```tsx\n'use client'\nimport { DeweyProvider } from '@arach/dewey'\nimport type { AnchorHTMLAttributes } from 'react'\nimport Link from 'next/link'\n\ntype DeweyLinkProps = AnchorHTMLAttributes & { href: string }\nconst DeweyLink = ({ href, ...props }: DeweyLinkProps) => \n\n// theme: ThemePreset | ThemeConfig\n// Adapt framework links to Dewey's required string-href contract.\n{children}\n```\n\nRoot `` recommended for theme class hydration.\n\n## Scripts (host package.json)\n\n| Script | Command |\n|---|---|\n| `docs:generate` | `bunx dewey generate` |\n| `docs:audit` | `bunx dewey audit` |\n| `docs:agent` | `bunx dewey agent` |\n| `prebuild` | generate before `next build` when importing `docs.json` / public artifacts |\n\n## CI (minimum)\n\n```bash\nbun install\nbunx dewey generate\nbunx dewey audit --json\nbunx dewey agent --json\n```\n\nGate on audit failures and/or agent score thresholds as policy.\n\n## Public agent URLs (optional)\n\n| Artifact | URL example |\n|---|---|\n| `llms.txt` | `/llms.txt` |\n| `AGENTS.md` | `/AGENTS.md` |\n| `install.md` | `/install.md` |\n| `agent/**` | `/agent/**` |\n\nWrite via `docs.output` / `--output public` or post-generate copy.\n\n## Monorepo\n\n| Case | Approach |\n|---|---|\n| Docs at repo root | Resolve `docsDirectory` to monorepo root, not app `cwd` alone |\n| Docs package | `--source` to package; app depends on `@arach/dewey` |\n| Multi-app | Generate once at root; ship static `agent/` + `docs.json` |\n\n## Anti-patterns\n\n| Don't | Do |\n|---|---|\n| Treat embed as replacing `generate` | Always run generate for agent surface |\n| Import hooks in server `page.tsx` | Split page (server) / content (client) |\n| Use only top-level `docs/*.md` walk | Recursive walk; nested routes |\n| Prefer `@arach/dewey/react` as different API | Import from `@arach/dewey` |\n| Frame as competing docs frameworks | Present as optional UI on agent pipeline |\n\n## Related paths\n\n| Doc | Role |\n|---|---|\n| `docs/integrate-existing-site.md` | Human narrative guide |\n| `docs/quickstart.md` | Greenfield sequence |\n| `docs/cli.md` | Flags |\n| `docs/maintenance.md` | Update/eject ownership, adoption, backups, recovery, release |\n| `packages/docs/src/cli/templates/nextjs.ts` | Canonical scaffold reference (implementation, not consumer edit target) |" }, { "id": "agent/maintenance.agent", "slug": "agent/maintenance.agent", "kind": "agent", "title": "Maintaining generated sites", "description": "Dense ownership, update, ejection, recovery, backup, and release contract", "sourcePath": "docs/agent/maintenance.agent.md", "url": "/agent/raw/docs/agent/maintenance.agent.md", "rawUrl": "/agent/raw/docs/agent/maintenance.agent.md", "headings": [ { "depth": 1, "text": "Dewey generated-site maintenance contract", "anchor": "dewey-generated-site-maintenance-contract" }, { "depth": 2, "text": "Ownership manifests", "anchor": "ownership-manifests" }, { "depth": 2, "text": "Update", "anchor": "update" }, { "depth": 2, "text": "Manifest adoption", "anchor": "manifest-adoption" }, { "depth": 2, "text": "Ejection", "anchor": "ejection" }, { "depth": 2, "text": "Recovery", "anchor": "recovery" }, { "depth": 2, "text": "Release gate", "anchor": "release-gate" } ], "tokensEstimate": 596, "frontmatter": { "title": "Maintaining generated sites", "description": "Dense ownership, update, ejection, recovery, backup, and release contract", "order": 7, "group": "Guides", "groupId": "guides" }, "markdown": "---\ntitle: Maintaining generated sites\ndescription: Dense ownership, update, ejection, recovery, backup, and release contract\norder: 7\ngroup: Guides\ngroupId: guides\n---\n\n# Dewey generated-site maintenance contract\n\n## Ownership manifests\n\n| Surface | Manifest | Owner |\n|---|---|---|\n| Agent artifacts from `generate` | `.dewey-generated.json` | Generation planner/scopes |\n| Standalone Astro/Next.js scaffold | `.dewey-manifest.json` | `create` / `update` / `eject` |\n\nDo not conflate the manifests. Source `docs/*.md` and consumer `package.json` are not normal `update` targets.\n\n## Update\n\n```bash\nbunx dewey update ./my-docs --dry-run\nbunx dewey update ./my-docs\nbunx dewey update ./my-docs --force\n```\n\n| State | Default behavior |\n|---|---|\n| Dewey-owned, recorded hash unchanged | Update safely |\n| Already equal to current template | Leave current; refresh manifest metadata |\n| Missing/new template file | Create |\n| Consumer/ejected/locally modified | Skip |\n| Modified Dewey-owned scaffold with `--force` | Back up, replace, remain `owner: dewey` |\n| Consumer/ejected entry with `--force` | Stay protected; never reclaimed by `update` |\n\nBackup contract: timestamped `.dewey-backup//...`; retain five newest timestamped snapshots after forced updates.\n\n## Manifest adoption\n\nFirst `update` with no manifest:\n\n| Template | Detection |\n|---|---|\n| Astro | `astro.config.mjs` + `src/layouts/BaseLayout.astro` |\n| Next.js | one of `next.config.js` / `.mjs` / `.ts` + `/src/lib/dewey.tsx` |\n\nAction: write `.dewey-manifest.json`; infer template/current hashes and available project/theme/default-page settings; stop; require a second `update` run. Unknown theme warns and becomes `neutral`.\n\n## Ejection\n\nSupported Next.js components: `Header`, `Sidebar`, `TableOfContents`, `MarkdownContent`.\n\nModes:\n\n- `wrap`: override composes packaged default.\n- `full`: complete consumer implementation.\n\nPre-write proof: custom import exists in candidate `/src/lib/dewey.tsx`; component mapping points to custom import. Proof failure => no override write. Successful file replacement uses temporary-file rename.\n\nManifest entries for override and wiring:\n\n```text\nowner: ejected\nhash: content hash\nversion: Dewey version\ncomponent: component name\nmode: wrap | full\n```\n\n`update` never reclaims consumer/ejected entries, including with `--force`. Restoring a default is an explicit ownership decision outside the update path.\n\n## Recovery\n\n1. Inspect command partial-write status and `git diff`.\n2. Prefer Git restore from a committed pre-update state.\n3. Otherwise restore only affected file from newest `.dewey-backup//`.\n4. Missing manifest: adopt once, inspect, rerun.\n5. Build and smoke-check affected route/component.\n\n## Release gate\n\n| Order | Check |\n|---|---|\n| 1 | Clean checkout; changelog/package version/config/lock aligned |\n| 2 | `bun run check` |\n| 3 | Generate; no `.dewey-generated.json`, root-artifact, or `agent/` drift |\n| 4 | `bun run verify:package` |\n| 5 | Commit release candidate; checkout becomes clean/reviewable |\n| 6 | `bun run verify:release-smoke`; fix + commit + rerun on failure |\n| 7 | Exact `v` tag only after smoke; publish workflow repeats verification |\n\nRelease smoke: real tarball; isolated consumer install/import; packed CLI `init` + `generate`; generated Next.js build; clean-checkout precondition; temporary directory removed on pass/fail.\n\nAuthoritative repository procedure: `RELEASING.md`.\n", "content": "# Dewey generated-site maintenance contract\n\n## Ownership manifests\n\n| Surface | Manifest | Owner |\n|---|---|---|\n| Agent artifacts from `generate` | `.dewey-generated.json` | Generation planner/scopes |\n| Standalone Astro/Next.js scaffold | `.dewey-manifest.json` | `create` / `update` / `eject` |\n\nDo not conflate the manifests. Source `docs/*.md` and consumer `package.json` are not normal `update` targets.\n\n## Update\n\n```bash\nbunx dewey update ./my-docs --dry-run\nbunx dewey update ./my-docs\nbunx dewey update ./my-docs --force\n```\n\n| State | Default behavior |\n|---|---|\n| Dewey-owned, recorded hash unchanged | Update safely |\n| Already equal to current template | Leave current; refresh manifest metadata |\n| Missing/new template file | Create |\n| Consumer/ejected/locally modified | Skip |\n| Modified Dewey-owned scaffold with `--force` | Back up, replace, remain `owner: dewey` |\n| Consumer/ejected entry with `--force` | Stay protected; never reclaimed by `update` |\n\nBackup contract: timestamped `.dewey-backup//...`; retain five newest timestamped snapshots after forced updates.\n\n## Manifest adoption\n\nFirst `update` with no manifest:\n\n| Template | Detection |\n|---|---|\n| Astro | `astro.config.mjs` + `src/layouts/BaseLayout.astro` |\n| Next.js | one of `next.config.js` / `.mjs` / `.ts` + `/src/lib/dewey.tsx` |\n\nAction: write `.dewey-manifest.json`; infer template/current hashes and available project/theme/default-page settings; stop; require a second `update` run. Unknown theme warns and becomes `neutral`.\n\n## Ejection\n\nSupported Next.js components: `Header`, `Sidebar`, `TableOfContents`, `MarkdownContent`.\n\nModes:\n\n- `wrap`: override composes packaged default.\n- `full`: complete consumer implementation.\n\nPre-write proof: custom import exists in candidate `/src/lib/dewey.tsx`; component mapping points to custom import. Proof failure => no override write. Successful file replacement uses temporary-file rename.\n\nManifest entries for override and wiring:\n\n```text\nowner: ejected\nhash: content hash\nversion: Dewey version\ncomponent: component name\nmode: wrap | full\n```\n\n`update` never reclaims consumer/ejected entries, including with `--force`. Restoring a default is an explicit ownership decision outside the update path.\n\n## Recovery\n\n1. Inspect command partial-write status and `git diff`.\n2. Prefer Git restore from a committed pre-update state.\n3. Otherwise restore only affected file from newest `.dewey-backup//`.\n4. Missing manifest: adopt once, inspect, rerun.\n5. Build and smoke-check affected route/component.\n\n## Release gate\n\n| Order | Check |\n|---|---|\n| 1 | Clean checkout; changelog/package version/config/lock aligned |\n| 2 | `bun run check` |\n| 3 | Generate; no `.dewey-generated.json`, root-artifact, or `agent/` drift |\n| 4 | `bun run verify:package` |\n| 5 | Commit release candidate; checkout becomes clean/reviewable |\n| 6 | `bun run verify:release-smoke`; fix + commit + rerun on failure |\n| 7 | Exact `v` tag only after smoke; publish workflow repeats verification |\n\nRelease smoke: real tarball; isolated consumer install/import; packed CLI `init` + `generate`; generated Next.js build; clean-checkout precondition; temporary directory removed on pass/fail.\n\nAuthoritative repository procedure: `RELEASING.md`." }, { "id": "agent/overview.agent", "slug": "agent/overview.agent", "kind": "agent", "title": "dewey - Agent Context", "description": "init → author → generate → audit → agent → optional UI", "sourcePath": "docs/agent/overview.agent.md", "url": "/agent/raw/docs/agent/overview.agent.md", "rawUrl": "/agent/raw/docs/agent/overview.agent.md", "headings": [ { "depth": 1, "text": "dewey - Agent Context", "anchor": "dewey-agent-context" }, { "depth": 2, "text": "Package", "anchor": "package" }, { "depth": 2, "text": "Purpose", "anchor": "purpose" }, { "depth": 2, "text": "CLI Commands", "anchor": "cli-commands" }, { "depth": 2, "text": "Onboarding path", "anchor": "onboarding-path" }, { "depth": 2, "text": "Generated Files", "anchor": "generated-files" }, { "depth": 2, "text": "Retrieval Artifacts", "anchor": "retrieval-artifacts" }, { "depth": 2, "text": "Skills (LLM Prompts)", "anchor": "skills-llm-prompts" }, { "depth": 2, "text": "Components (22)", "anchor": "components-22" }, { "depth": 2, "text": "Config Schema", "anchor": "config-schema" }, { "depth": 2, "text": "Valid Values", "anchor": "valid-values" }, { "depth": 2, "text": "Judgment and generation model", "anchor": "judgment-and-generation-model" }, { "depth": 2, "text": "Key Files", "anchor": "key-files" } ], "tokensEstimate": 676, "frontmatter": {}, "markdown": "# dewey - Agent Context\n\n## Package\n@arach/dewey\n\n## Purpose\nDocumentation toolkit that prepares docs for AI agents. Generates standard agent files, recursive retrieval artifacts, and optional static docs sites.\n\n## CLI Commands\n\n| Command | Action |\n|---------|--------|\n| `dewey init` | Create docs/ + dewey.config.ts |\n| `dewey audit` | Validate completeness |\n| `dewey generate` | Create AGENTS.md, llms.txt, docs.json, install.md, agent/ artifacts |\n| `dewey agent` | Score agent-readiness (0-100 pts) |\n| `dewey create` | Optional static docs site from markdown |\n\n## Onboarding path\n\n`init` → author → `generate` → `audit` → `agent` → optional UI\n\n| Optional UI | Doc |\n|-------------|-----|\n| Embed existing React/Next | `docs/integrate-existing-site.md` |\n| Standalone scaffold | `dewey create` |\n\nPublic TypeScript, React, theme, and artifact contracts: `docs/api.md`.\n\n## Generated Files\n\n| File | Purpose |\n|------|---------|\n| AGENTS.md | Combined docs with critical context |\n| llms.txt | Plain text for LLMs |\n| docs.json | Structured JSON |\n| install.md | LLM-executable installation (installmd.org) |\n\n## Retrieval Artifacts\n\n| File | Purpose |\n|------|---------|\n| agent/manifest.json | Discovery index |\n| agent/docs.json | Document entries with non-prompt content |\n| agent/prompts.json | Prompt registry with prompt content |\n| agent/context.md | Compact retrieval index |\n| agent/context.json | JSON retrieval index |\n| agent/raw/docs/ | Raw markdown mirror |\n\n## Skills (LLM Prompts)\n\n| Skill | Purpose |\n|-------|---------|\n| docsReviewAgent | Review quality, catch drift |\n| docsDesignCritic | Critique page structure and visual design |\n| promptSlideoutGenerator | Generate prompt configs |\n| installMdGenerator | Create install.md |\n| improveAIPrompts | Iterative prompt discovery/draft/review/refinement; public name |\n| improveAIPromptsSkill | Deprecated alias of `improveAIPrompts` |\n\n## Components (22)\n\nEntry: DocsApp, DocsIndex\nLayout: DocsLayout, Header, Sidebar, TableOfContents\nContent: MarkdownContent, CodeBlock, Callout, Tabs, Steps, Card, FileTree, ApiTable, Badge\nAgent: AgentContext, PromptSlideout, CopyButtons\nProvider: DeweyProvider\n\n## Config Schema\n\n```typescript\n{\n project: { name, tagline, type },\n agent: { criticalContext[], entryPoints{}, rules[], sections[] },\n docs: { path, output, required[] },\n install: { objective, doneWhen, prerequisites[], steps[] }\n}\n```\n\n## Valid Values\n\nProjectType: 'npm-package' | 'cli-tool' | 'macos-app' | 'react-library' | 'monorepo' | 'generic'\nCalloutType: 'info' | 'warning' | 'tip' | 'danger'\nBadgeVariant: 'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple'\nThemePreset: 'neutral' | 'ocean' | 'emerald' | 'purple' | 'dusk' | 'rose' | 'github' | 'warm' | 'midnight' | 'editorial' | 'mono' | 'hudson'\n\n## Judgment and generation model\n\n- Project type changes paired scaffold, required docs, install defaults, verification, and evidence checks.\n- `audit` + `agent` JSON include `projectType` and `drift`.\n- Drift checks pairing/cited paths/literal union-enum contracts; regex/evidence only, not semantic/executable proof.\n- `generate`, `create`, artifact API share canonical recursive discovery/frontmatter.\n- One manifest drives retrieval indexes/link tables/bundles.\n- Full content is separated: docs JSON, prompts JSON, raw Markdown, bundles.\n\nGenerated-site ownership/recovery/release: `docs/maintenance.md` and `docs/agent/maintenance.agent.md`.\n\n## Key Files\n\n| Path | Purpose |\n|------|---------|\n| packages/docs/src/index.ts | Main exports |\n| packages/docs/src/cli/index.ts | CLI entry |\n| packages/docs/src/cli/schema.ts | Config schema |\n| packages/docs/src/skills/ | LLM prompt templates |\n", "content": "# dewey - Agent Context\n\n## Package\n@arach/dewey\n\n## Purpose\nDocumentation toolkit that prepares docs for AI agents. Generates standard agent files, recursive retrieval artifacts, and optional static docs sites.\n\n## CLI Commands\n\n| Command | Action |\n|---------|--------|\n| `dewey init` | Create docs/ + dewey.config.ts |\n| `dewey audit` | Validate completeness |\n| `dewey generate` | Create AGENTS.md, llms.txt, docs.json, install.md, agent/ artifacts |\n| `dewey agent` | Score agent-readiness (0-100 pts) |\n| `dewey create` | Optional static docs site from markdown |\n\n## Onboarding path\n\n`init` → author → `generate` → `audit` → `agent` → optional UI\n\n| Optional UI | Doc |\n|-------------|-----|\n| Embed existing React/Next | `docs/integrate-existing-site.md` |\n| Standalone scaffold | `dewey create` |\n\nPublic TypeScript, React, theme, and artifact contracts: `docs/api.md`.\n\n## Generated Files\n\n| File | Purpose |\n|------|---------|\n| AGENTS.md | Combined docs with critical context |\n| llms.txt | Plain text for LLMs |\n| docs.json | Structured JSON |\n| install.md | LLM-executable installation (installmd.org) |\n\n## Retrieval Artifacts\n\n| File | Purpose |\n|------|---------|\n| agent/manifest.json | Discovery index |\n| agent/docs.json | Document entries with non-prompt content |\n| agent/prompts.json | Prompt registry with prompt content |\n| agent/context.md | Compact retrieval index |\n| agent/context.json | JSON retrieval index |\n| agent/raw/docs/ | Raw markdown mirror |\n\n## Skills (LLM Prompts)\n\n| Skill | Purpose |\n|-------|---------|\n| docsReviewAgent | Review quality, catch drift |\n| docsDesignCritic | Critique page structure and visual design |\n| promptSlideoutGenerator | Generate prompt configs |\n| installMdGenerator | Create install.md |\n| improveAIPrompts | Iterative prompt discovery/draft/review/refinement; public name |\n| improveAIPromptsSkill | Deprecated alias of `improveAIPrompts` |\n\n## Components (22)\n\nEntry: DocsApp, DocsIndex\nLayout: DocsLayout, Header, Sidebar, TableOfContents\nContent: MarkdownContent, CodeBlock, Callout, Tabs, Steps, Card, FileTree, ApiTable, Badge\nAgent: AgentContext, PromptSlideout, CopyButtons\nProvider: DeweyProvider\n\n## Config Schema\n\n```typescript\n{\n project: { name, tagline, type },\n agent: { criticalContext[], entryPoints{}, rules[], sections[] },\n docs: { path, output, required[] },\n install: { objective, doneWhen, prerequisites[], steps[] }\n}\n```\n\n## Valid Values\n\nProjectType: 'npm-package' | 'cli-tool' | 'macos-app' | 'react-library' | 'monorepo' | 'generic'\nCalloutType: 'info' | 'warning' | 'tip' | 'danger'\nBadgeVariant: 'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple'\nThemePreset: 'neutral' | 'ocean' | 'emerald' | 'purple' | 'dusk' | 'rose' | 'github' | 'warm' | 'midnight' | 'editorial' | 'mono' | 'hudson'\n\n## Judgment and generation model\n\n- Project type changes paired scaffold, required docs, install defaults, verification, and evidence checks.\n- `audit` + `agent` JSON include `projectType` and `drift`.\n- Drift checks pairing/cited paths/literal union-enum contracts; regex/evidence only, not semantic/executable proof.\n- `generate`, `create`, artifact API share canonical recursive discovery/frontmatter.\n- One manifest drives retrieval indexes/link tables/bundles.\n- Full content is separated: docs JSON, prompts JSON, raw Markdown, bundles.\n\nGenerated-site ownership/recovery/release: `docs/maintenance.md` and `docs/agent/maintenance.agent.md`.\n\n## Key Files\n\n| Path | Purpose |\n|------|---------|\n| packages/docs/src/index.ts | Main exports |\n| packages/docs/src/cli/index.ts | CLI entry |\n| packages/docs/src/cli/schema.ts | Config schema |\n| packages/docs/src/skills/ | LLM prompt templates |" }, { "id": "agent/quickstart.agent", "slug": "agent/quickstart.agent", "kind": "agent", "title": "Quickstart for agents", "description": "Deterministic setup sequence and expected Dewey outputs", "sourcePath": "docs/agent/quickstart.agent.md", "url": "/agent/raw/docs/agent/quickstart.agent.md", "rawUrl": "/agent/raw/docs/agent/quickstart.agent.md", "headings": [ { "depth": 1, "text": "Dewey quickstart contract", "anchor": "dewey-quickstart-contract" }, { "depth": 2, "text": "Preconditions", "anchor": "preconditions" }, { "depth": 2, "text": "Execution sequence", "anchor": "execution-sequence" }, { "depth": 2, "text": "Generated outputs", "anchor": "generated-outputs" }, { "depth": 2, "text": "Selection rules", "anchor": "selection-rules" }, { "depth": 2, "text": "Project type initialization", "anchor": "project-type-initialization" }, { "depth": 2, "text": "Check report contract", "anchor": "check-report-contract" }, { "depth": 2, "text": "Canonical generation", "anchor": "canonical-generation" }, { "depth": 2, "text": "Optional publishing", "anchor": "optional-publishing" } ], "tokensEstimate": 716, "frontmatter": { "title": "Quickstart for agents", "description": "Deterministic setup sequence and expected Dewey outputs", "order": 2 }, "markdown": "---\ntitle: Quickstart for agents\ndescription: Deterministic setup sequence and expected Dewey outputs\norder: 2\n---\n\n# Dewey quickstart contract\n\n## Preconditions\n\n| Requirement | Value |\n|---|---|\n| Runtime | Node.js 18+ |\n| Preferred package manager | Bun 1.3+ |\n| Package | `@arach/dewey` |\n\n## Execution sequence\n\n| Step | Command or action | Expected result |\n|---|---|---|\n| Install | `bun add -d @arach/dewey` (or `bun add` if importing components) | Local `dewey` binary available |\n| Initialize | `bunx dewey init --type ` | Type-specific paired docs and `dewey.config.ts` created |\n| Configure | Edit `dewey.config.ts` | Project context, document paths, agent rules defined |\n| Author | Add human `.md` and agent `.agent.md` pages | Paired documentation source exists |\n| Generate | `bunx dewey generate` | Standard files and `agent/` retrieval surface written |\n| Audit | `bunx dewey audit` / `--json` | Deterministic documentation checks reported |\n| Score | `bunx dewey agent` / `--json` | Agent-readiness score and recommendations reported |\n| Embed UI (optional) | Host React/Next routes | See `docs/integrate-existing-site.md` |\n| Create site (optional) | `bunx dewey create …` | Standalone static site only |\n\nOrder is fixed for greenfield and embed alike: **init → author → generate → audit → agent → optional UI**.\n\n## Generated outputs\n\n| Path | Contract |\n|---|---|\n| `AGENTS.md` | Combined project context and selected docs |\n| `llms.txt` | Compact LLM-facing index and summaries |\n| `docs.json` | Structured documentation manifest |\n| `install.md` | installmd.org-compatible execution guide |\n| `agent/manifest.json` | Retrieval discovery manifest |\n| `agent/docs.json` | Structured document entries with non-prompt content |\n| `agent/prompts.json` | Prompt registry with prompt content |\n| `agent/context.md` | Compact retrieval index; no repeated corpus |\n| `agent/raw/docs/**` | Recursive raw Markdown mirror |\n\n## Selection rules\n\n| Configuration | Behavior |\n|---|---|\n| `agent.sections: []` | Include all human `.md` documents recursively |\n| Non-empty `agent.sections` | Include exact document IDs only |\n| `generate --source ` | Override `docs.path` for one run |\n| `generate --output ` | Override `docs.output`; create directory recursively |\n\n## Project type initialization\n\n`ProjectType = 'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`\n\nType selects paired focus page, required docs, install defaults, verification command, and audit/agent evidence profile. Invalid type is a hard error.\n\n## Check report contract\n\n`audit --json` and `agent --json` include:\n\n- `projectType`: label/pass/evidence.\n- `drift`: status/counts/structured issues.\n\nDrift scope: pairing, orphan agent docs, cited paths, literal unions/enums across human/agent/source. Limitation: regex/evidence consistency only; no semantic prose or example execution.\n\n## Canonical generation\n\n- Discovery/frontmatter parse shared by `generate`, `create`, artifact API.\n- Manifest drives link tables/read order/bundles.\n- Full content: `agent/docs.json` for non-prompts, `agent/prompts.json` for prompts, raw/bundle Markdown for retrieval.\n- Context surfaces contain indexes, not another full corpus.\n- `llms.txt` summary fallback: frontmatter description → prose → list → heading → title.\n- Scoped install package names preserved; prompt URLs do not duplicate `prompts/`.\n- Generated site dependencies pinned to tested versions; Pagefind declared.\n\n## Optional publishing\n\n| Mode | Entry |\n|---|---|\n| Embed in existing React/Next | `docs/integrate-existing-site.md` + `docs/agent/integrate-existing-site.agent.md` |\n| Standalone site | `bunx dewey create my-docs --source ./docs --theme ocean` |\n\nPublishing is optional; generated agent artifacts remain the core contract.\n\nMaintenance: `docs/maintenance.md` + `docs/agent/maintenance.agent.md`.\n", "content": "# Dewey quickstart contract\n\n## Preconditions\n\n| Requirement | Value |\n|---|---|\n| Runtime | Node.js 18+ |\n| Preferred package manager | Bun 1.3+ |\n| Package | `@arach/dewey` |\n\n## Execution sequence\n\n| Step | Command or action | Expected result |\n|---|---|---|\n| Install | `bun add -d @arach/dewey` (or `bun add` if importing components) | Local `dewey` binary available |\n| Initialize | `bunx dewey init --type ` | Type-specific paired docs and `dewey.config.ts` created |\n| Configure | Edit `dewey.config.ts` | Project context, document paths, agent rules defined |\n| Author | Add human `.md` and agent `.agent.md` pages | Paired documentation source exists |\n| Generate | `bunx dewey generate` | Standard files and `agent/` retrieval surface written |\n| Audit | `bunx dewey audit` / `--json` | Deterministic documentation checks reported |\n| Score | `bunx dewey agent` / `--json` | Agent-readiness score and recommendations reported |\n| Embed UI (optional) | Host React/Next routes | See `docs/integrate-existing-site.md` |\n| Create site (optional) | `bunx dewey create …` | Standalone static site only |\n\nOrder is fixed for greenfield and embed alike: **init → author → generate → audit → agent → optional UI**.\n\n## Generated outputs\n\n| Path | Contract |\n|---|---|\n| `AGENTS.md` | Combined project context and selected docs |\n| `llms.txt` | Compact LLM-facing index and summaries |\n| `docs.json` | Structured documentation manifest |\n| `install.md` | installmd.org-compatible execution guide |\n| `agent/manifest.json` | Retrieval discovery manifest |\n| `agent/docs.json` | Structured document entries with non-prompt content |\n| `agent/prompts.json` | Prompt registry with prompt content |\n| `agent/context.md` | Compact retrieval index; no repeated corpus |\n| `agent/raw/docs/**` | Recursive raw Markdown mirror |\n\n## Selection rules\n\n| Configuration | Behavior |\n|---|---|\n| `agent.sections: []` | Include all human `.md` documents recursively |\n| Non-empty `agent.sections` | Include exact document IDs only |\n| `generate --source ` | Override `docs.path` for one run |\n| `generate --output ` | Override `docs.output`; create directory recursively |\n\n## Project type initialization\n\n`ProjectType = 'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'`\n\nType selects paired focus page, required docs, install defaults, verification command, and audit/agent evidence profile. Invalid type is a hard error.\n\n## Check report contract\n\n`audit --json` and `agent --json` include:\n\n- `projectType`: label/pass/evidence.\n- `drift`: status/counts/structured issues.\n\nDrift scope: pairing, orphan agent docs, cited paths, literal unions/enums across human/agent/source. Limitation: regex/evidence consistency only; no semantic prose or example execution.\n\n## Canonical generation\n\n- Discovery/frontmatter parse shared by `generate`, `create`, artifact API.\n- Manifest drives link tables/read order/bundles.\n- Full content: `agent/docs.json` for non-prompts, `agent/prompts.json` for prompts, raw/bundle Markdown for retrieval.\n- Context surfaces contain indexes, not another full corpus.\n- `llms.txt` summary fallback: frontmatter description → prose → list → heading → title.\n- Scoped install package names preserved; prompt URLs do not duplicate `prompts/`.\n- Generated site dependencies pinned to tested versions; Pagefind declared.\n\n## Optional publishing\n\n| Mode | Entry |\n|---|---|\n| Embed in existing React/Next | `docs/integrate-existing-site.md` + `docs/agent/integrate-existing-site.agent.md` |\n| Standalone site | `bunx dewey create my-docs --source ./docs --theme ocean` |\n\nPublishing is optional; generated agent artifacts remain the core contract.\n\nMaintenance: `docs/maintenance.md` + `docs/agent/maintenance.agent.md`." }, { "id": "agent/skills.agent", "slug": "agent/skills.agent", "kind": "agent", "title": "Skills for agents", "description": "Dewey skill inventory and authoring contract", "sourcePath": "docs/agent/skills.agent.md", "url": "/agent/raw/docs/agent/skills.agent.md", "rawUrl": "/agent/raw/docs/agent/skills.agent.md", "headings": [ { "depth": 1, "text": "Dewey skills contract", "anchor": "dewey-skills-contract" }, { "depth": 2, "text": "Built-in inventory", "anchor": "built-in-inventory" }, { "depth": 2, "text": "Public prompt-improvement contract", "anchor": "public-prompt-improvement-contract" }, { "depth": 2, "text": "Custom skill location", "anchor": "custom-skill-location" }, { "depth": 2, "text": "Required skill sections", "anchor": "required-skill-sections" }, { "depth": 2, "text": "Authoring rules", "anchor": "authoring-rules" } ], "tokensEstimate": 389, "frontmatter": { "title": "Skills for agents", "description": "Dewey skill inventory and authoring contract", "order": 4 }, "markdown": "---\ntitle: Skills for agents\ndescription: Dewey skill inventory and authoring contract\norder: 4\n---\n\n# Dewey skills contract\n\nSkills are LLM instructions, not deterministic executable code.\n\n## Built-in inventory\n\n| Skill | Purpose | Success condition |\n|---|---|---|\n| `docsReviewAgent` | Review one page for correctness, completeness, clarity, links, and source drift | Findings reference evidence and actionable changes |\n| `docsDesignCritic` | Review hierarchy, information density, component use, and visual structure | Critique separates structural and presentation issues |\n| `promptSlideoutGenerator` | Produce AI-consumable prompt configuration for a page | Output has explicit inputs, instructions, and expected result |\n| `installMdGenerator` | Produce installmd.org-compatible `install.md` | Instructions are executable, environment-aware, and verifiable |\n| `improveAIPrompts` | Discover → draft → review → refine prompt contracts | Result is self-contained and satisfies exported quality criteria |\n\n## Public prompt-improvement contract\n\n| Export | Status |\n|---|---|\n| `improveAIPrompts` | Canonical public runtime object |\n| `improveAIPromptsSkill` | Deprecated alias; same object |\n| `PromptImprovementPass` | Public type |\n| `PromptQualityCriteria` | Public type |\n\nUsage: select a prompt from `improveAIPrompts.passes`, replace its placeholders, send it to an LLM, and review the result. The export is prompt content, not repository automation or a deterministic generator.\n\n## Custom skill location\n\n`.agents/skills/.md`\n\n## Required skill sections\n\n| Section | Content |\n|---|---|\n| Name and description | One bounded capability |\n| When to Use | Concrete trigger conditions |\n| Instructions | Ordered, actionable workflow |\n| Success criteria | Verifiable completion conditions |\n| Example | Representative input and expected output |\n\n## Authoring rules\n\n- Use explicit file paths and commands.\n- State required context and constraints.\n- Separate deterministic checks from model judgment.\n- Include failure and escalation behavior.\n- Avoid vague goals, hidden assumptions, and presentation-only prose.\n- Treat examples as contracts, not decoration.\n", "content": "# Dewey skills contract\n\nSkills are LLM instructions, not deterministic executable code.\n\n## Built-in inventory\n\n| Skill | Purpose | Success condition |\n|---|---|---|\n| `docsReviewAgent` | Review one page for correctness, completeness, clarity, links, and source drift | Findings reference evidence and actionable changes |\n| `docsDesignCritic` | Review hierarchy, information density, component use, and visual structure | Critique separates structural and presentation issues |\n| `promptSlideoutGenerator` | Produce AI-consumable prompt configuration for a page | Output has explicit inputs, instructions, and expected result |\n| `installMdGenerator` | Produce installmd.org-compatible `install.md` | Instructions are executable, environment-aware, and verifiable |\n| `improveAIPrompts` | Discover → draft → review → refine prompt contracts | Result is self-contained and satisfies exported quality criteria |\n\n## Public prompt-improvement contract\n\n| Export | Status |\n|---|---|\n| `improveAIPrompts` | Canonical public runtime object |\n| `improveAIPromptsSkill` | Deprecated alias; same object |\n| `PromptImprovementPass` | Public type |\n| `PromptQualityCriteria` | Public type |\n\nUsage: select a prompt from `improveAIPrompts.passes`, replace its placeholders, send it to an LLM, and review the result. The export is prompt content, not repository automation or a deterministic generator.\n\n## Custom skill location\n\n`.agents/skills/.md`\n\n## Required skill sections\n\n| Section | Content |\n|---|---|\n| Name and description | One bounded capability |\n| When to Use | Concrete trigger conditions |\n| Instructions | Ordered, actionable workflow |\n| Success criteria | Verifiable completion conditions |\n| Example | Representative input and expected output |\n\n## Authoring rules\n\n- Use explicit file paths and commands.\n- State required context and constraints.\n- Separate deterministic checks from model judgment.\n- Include failure and escalation behavior.\n- Avoid vague goals, hidden assumptions, and presentation-only prose.\n- Treat examples as contracts, not decoration." } ], "prompts": [ { "id": "audit-docs", "slug": "prompts/audit-docs", "title": "Prompts Audit Docs", "description": "Use this prompt to audit a project's documentation for agent-readiness.", "sourcePath": "docs/prompts/audit-docs.md", "promptUrl": "/agent/prompts/audit-docs.md", "rawUrl": "/agent/raw/docs/prompts/audit-docs.md", "headings": [ { "depth": 2, "text": "Expected Output", "anchor": "expected-output" } ], "tokensEstimate": 192, "frontmatter": {} }, { "id": "create-agent-md", "slug": "prompts/create-agent-md", "title": "Prompts Create Agent Md", "description": "Use this prompt to convert human documentation to agent-optimized format.", "sourcePath": "docs/prompts/create-agent-md.md", "promptUrl": "/agent/prompts/create-agent-md.md", "rawUrl": "/agent/raw/docs/prompts/create-agent-md.md", "headings": [ { "depth": 2, "text": "Example", "anchor": "example" }, { "depth": 2, "text": "init", "anchor": "init" } ], "tokensEstimate": 227, "frontmatter": {} } ] }