Dewey Documentation Toolkit

Dewey generates AI-agent-ready documentation for software projects. It creates AGENTS.md, llms.txt, docs.json, and install.md files that AI coding agents can consume effectively.

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”

Installation

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

CLI Commands

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

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

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')

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+)