arach/dewey-docs

Dewey Documentation Toolkit

Dewey generates AI-agent-ready documentation for software projects. It creates AGENTS.md, llms.txt, docs.json, install.md files, and can scaffold complete static doc sites from markdown.

When to Use

Activate this skill when the user asks to:

• "Set up documentation for my project"
• "Make my docs AI-friendly"
• "Generate AGENTS.md"
• "Create an llms.txt file"
• "Add agent-ready docs"
• "Set up Dewey"
• "Create a doc site"
• "Generate a docs website from my markdown"

Installation

pnpm add @arach/dewey
# or
npm install @arach/dewey

CLI Commands

| Command | Purpose | |---------|---------| | dewey init | Create docs/ folder and dewey.config.ts | | dewey audit | Check documentation completeness | | dewey generate | Create AGENTS.md, llms.txt, docs.json, install.md | | dewey create | Scaffold a static Astro doc site from markdown | | dewey agent | Score agent-readiness (0-100 scale) |

Quick Setup

# 1. Install
pnpm add @arach/dewey

# 2. Initialize
npx dewey init

# 3. Generate agent files
npx dewey generate

This creates:

docs/
├── overview.md
├── quickstart.md
├── AGENTS.md        # Combined agent context
└── llms.txt         # Plain text summary
dewey.config.ts      # Configuration

Doc Site Generator

dewey create scaffolds a complete static doc site from a folder of markdown:

npx dewey create my-docs --source ./docs --theme ocean
cd my-docs && pnpm install && pnpm dev

• Astro-based static HTML output (no empty SPA shells)
• Pagefind search built in
• 8 themes — neutral, ocean, emerald, purple, dusk, rose, github, warm
• Dark mode with system preference detection
• Auto-navigation from frontmatter ordering

Configuration (dewey.config.ts)

import { defineConfig } from '@arach/dewey'

export default defineConfig({
  project: {
    name: 'my-project',
    tagline: 'A brief description',
    type: 'npm-package', // or 'cli-tool', 'macos-app', 'react-library', 'monorepo', 'generic'
  },

  agent: {
    // Critical rules agents MUST follow
    criticalContext: [
      'Always use TypeScript',
      'Run tests before committing',
    ],

    // Key directories for navigation
    entryPoints: {
      'Source': 'src/',
      'Tests': 'tests/',
      'Config': 'config/',
    },

    // Pattern-based instructions
    rules: [
      { pattern: '*.test.ts', instruction: 'Use vitest for testing' },
      { pattern: 'src/api/*', instruction: 'Follow REST conventions' },
    ],

    // Docs to include in AGENTS.md
    sections: ['overview', 'quickstart', 'api'],
  },

  docs: {
    path: './docs',
    output: './',
    required: ['overview.md', 'quickstart.md'],
  },

  // For install.md generation (installmd.org standard)
  install: {
    objective: 'Set up the development environment',
    doneWhen: {
      command: 'npm test',
      expectedOutput: 'All tests passed',
    },
    prerequisites: ['Node.js 18+', 'pnpm'],
    steps: [
      { description: 'Install dependencies', command: 'pnpm install' },
      { description: 'Run tests', command: 'pnpm test' },
    ],
  },
})

Project Types

| Type | Best For | |------|----------| | npm-package | Published npm packages | | cli-tool | Command-line tools | | macos-app | macOS applications | | react-library | React component libraries | | monorepo | Multi-package workspaces | | generic | Other projects |

Generated Files

AGENTS.md

Combined documentation with critical context for AI agents:

• Project overview and structure
• Critical rules and conventions
• Entry points for navigation
• API reference

llms.txt

Plain text summary optimized for LLM context windows:

• Concise project description
• Key commands
• Installation steps
• Links to full docs

docs.json

Structured JSON for programmatic access:

• Full documentation tree
• Metadata and navigation
• Searchable content

install.md

LLM-executable installation instructions following installmd.org:

• Step-by-step setup
• Verification commands
• Can be piped to AI: curl url/install.md | claude

Agent Content Pattern

Each doc page should have two versions:

docs/
├── overview.md           # Human-readable (prose, examples)
├── agent/
│   └── overview.agent.md # Agent-optimized (dense, structured)

Agent versions should be:

• Dense (no prose, just facts)
• Structured (tables, explicit values)
• Self-contained (no URL fetching needed)
• Cross-referenced against source code

React Components

Dewey provides 22 components for building documentation sites:

Layout

• DocsApp - Complete docs site with routing
• DocsLayout - Main layout (sidebar, TOC, navigation)
• Header - Sticky header with theme toggle
• Sidebar - Left navigation panel
• TableOfContents - Right minimap with scroll-spy

Content

• MarkdownContent - Renders markdown with syntax highlighting
• CodeBlock - Code with copy button
• Callout - Alert boxes (info, warning, tip, danger)
• Tabs - Tabbed content
• Steps - Numbered instructions
• Card, CardGrid - Content cards
• FileTree - Directory visualizer
• ApiTable - Props/params table
• Badge - Status indicators

Agent-Friendly

• AgentContext - Collapsible agent content block
• PromptSlideout - Interactive prompt editor
• CopyButtons - "Copy for AI" button

Provider

• DeweyProvider - Theme and component context

Theme Presets

import { DeweyProvider } from '@arach/dewey'

<DeweyProvider theme="neutral">
  {/* Your docs */}
</DeweyProvider>

Available themes: neutral | ocean | emerald | purple | dusk | rose | github | warm

Built-in Skills

Dewey includes LLM prompt templates for documentation workflows:

docsReviewAgent

Reviews documentation quality, catches drift from codebase:

import { docsReviewAgent } from '@arach/dewey'

const prompt = docsReviewAgent.reviewPage
  .replace('{DOC_FILE}', 'docs/api.md')
  .replace('{SOURCE_FILES}', 'src/types/index.ts')
  .replace('{OUTPUT_FILE}', '.dewey/reviews/api.md')

docsDesignCritic

Critiques page structure and visual design — heading hierarchy, information density, component usage, visual rhythm, reading flow:

import { docsDesignCritic } from '@arach/dewey'

const prompt = docsDesignCritic.critiquePage
  .replace('{DOC_FILE}', 'docs/quickstart.md')
  .replace('{OUTPUT_FILE}', '.dewey/reviews/quickstart-design.md')

installMdGenerator

Generates install.md files following installmd.org standard.

promptSlideoutGenerator

Creates interactive prompt configs for PromptSlideout components.

Workflow: Agent-Ready Docs

1. Initialize: npx dewey init
2. Write docs: Create human-readable markdown in docs/
3. Add agent versions: Create docs/agent/*.agent.md with structured content
4. Configure: Set critical context and rules in dewey.config.ts
5. Generate: npx dewey generate creates AGENTS.md, llms.txt, etc.
6. Audit: npx dewey audit checks completeness
7. Score: npx dewey agent rates agent-readiness (target: 80+)

Example: API Documentation

Human version (docs/api.md):

# API Reference

The API provides methods for managing users...

## createUser(options)

Creates a new user with the specified options.

### Parameters

- `name` - The user's display name
- `email` - Email address (must be unique)

Agent version (docs/agent/api.agent.md):

# API Reference

## createUser

| Param | Type | Required | Default |
|-------|------|----------|---------|
| name | string | yes | - |
| email | string | yes | - |
| role | 'admin' \| 'user' | no | 'user' |

Returns: `Promise<User>`

Throws: `DuplicateEmailError` if email exists

Output

When setting up Dewey for a project:

1. Create dewey.config.ts with appropriate project type
2. Run dewey init to scaffold docs structure
3. Add critical context relevant to the project
4. Generate agent files with dewey generate
5. Verify with dewey agent (target score: 80+)