Documentation

Documentation Standards

Complete documentation standards for dx-toolkit packages. Use these guidelines when creating or updating README.md and AGENTS.md files.

Root README.md - Monorepo Overview

IMPORTANT: The root README.md (at monorepo level) is an exception to package-specific guidelines.

Purpose: Clean navigation document for developers (integrators + contributors)

Structure:

1. Title and intro - Multi-platform toolkit (Claude Code, Cursor, 20+ AI agents)
2. NPM Packages - One-liner per package with Documentation link
3. Marketplace - One-liner per plugin with Documentation link (match NPM Packages format)
4. Quick Start - Development setup only (prerequisites + setup commands)
5. Monorepo Commands - Workspace-level and package-specific commands
6. Documentation - Package docs and contributor docs links
7. Directory Structure - Basic structure overview
8. Roadmap - Packages and plugins in development (link to docs/ROADMAP.md)
9. Contributing - Link to CONTRIBUTING.md
10. License and Support - Standard sections

Key Principles:

• ✅ Single Quick Start for development setup - No separate user/contributor sections
• ✅ Unified format - NPM Packages and Marketplace use same one-liner pattern
• ✅ Link to detailed docs - Don't duplicate AGENTS.md or package READMEs
• ✅ Show both command patterns - Root shortcuts AND bun --cwd packages/<package> <command>
• ✅ Complete environment setup - Both YDC_API_KEY and ANTHROPIC_API_KEY
• ✅ Build before test - bun run build then bun test in Quick Start
• ✅ Reflect current state - Update roadmap for upcoming work
• ❌ Don't separate "For Users" vs "For Contributors" - Single flow
• ❌ Don't duplicate Testing/Code Quality sections - Covered in Monorepo Commands
• ❌ Don't include "Working with AI Agents" section - Link to AGENTS.md instead
• ❌ Don't include "GitHub Workflows" section - Link to AGENTS.md instead
• ❌ Don't use <details> for progressive disclosure - Keep simple and linear

Quick Start Pattern:

## Quick Start

**Prerequisites:**
- Bun >= 1.2.21: [Installation guide](https://bun.sh/docs/installation)
- GitHub CLI (recommended): `brew install gh` (macOS) or [other platforms](...)

**Development setup:**
```bash
# Clone repository
git clone git@github.com:youdotcom-oss/dx-toolkit.git
cd dx-toolkit

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env and add your YDC_API_KEY and ANTHROPIC_API_KEY
source .env

# Authenticate with GitHub (if using gh CLI)
gh auth login

# Build all packages
bun run build

# Run all tests
bun test

# Run all quality checks
bun run check

For comprehensive development guidelines, see AGENTS.md.

**Package/Plugin Listing Pattern** (One-liner with link):
```markdown
### [@youdotcom-oss/mcp](./packages/mcp/)
MCP Server giving AI agents real-time web search, AI answers, and content extraction via Model Context Protocol. **[Documentation →](./packages/mcp/README.md)**

### [teams-anthropic-integration](./plugins/teams-anthropic-integration/)
Generate Microsoft Teams apps with You.com Anthropic integration using `@youdotcom-oss/teams-anthropic` - handles setup workflow for new and existing apps. **[Documentation →](./plugins/teams-anthropic-integration/README.md)**

Contributing Pattern (Just link):

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

Target Length: ~200 lines (down from 300-400 with removed sections)

These guidelines apply to package-level documentation (e.g., packages/mcp/README.md, packages/ai-sdk-plugin/README.md).

Thin AGENTS.md Philosophy

Package AGENTS.md files should be minimal wrappers that primarily reference skills.

What to Include (Package-Specific Only)

✅ Include these in package AGENTS.md:

• Quick setup commands (2-3 lines)
• Framework-specific patterns (e.g., "Teams.ai Memory API uses push() not addMessage()")
• Domain-specific integration rules (e.g., "Anthropic requires system messages as separate parameter")
• Package-specific error patterns (e.g., "MCP tools must return responses, never throw")
• Architecture diagram if complex
• Troubleshooting specific to this package

What to Reference (Universal Patterns)

❌ Reference skills instead of duplicating:

• Arrow functions, Bun APIs → .claude/rules/code-patterns.md
• Test patterns, retry config → .claude/rules/code-patterns.md
• Error handling (err: unknown) → .claude/rules/code-patterns.md
• Type guards, private fields → .claude/rules/code-patterns.md
• Git workflow, commits → .claude/rules/git-workflow.md
• Documentation standards → .claude/skills/documentation

Good vs Bad Examples

❌ BAD - Bloated AGENTS.md (500+ lines):

## Code Style

### Arrow Functions
Always use arrow functions...
[50 lines of examples]

### Numeric Separators
Use underscores for large numbers...
[30 lines of examples]

### Error Handling
Always use try/catch with typed errors...
[100 lines of examples]

### Testing
Use test() not it()...
[150 lines of examples]

## Package-Specific Patterns
[Buried at the bottom, only 20 lines]

✅ GOOD - Thin AGENTS.md (150 lines):

## Code Style

> **For universal patterns**: See `.claude/rules/code-patterns.md`

## Package-Specific Patterns

### Teams.ai Memory API

Use `push()` and `values()`, NEVER `addMessage()`:
```ts
// ✅ Correct
await memory.push(input);
const messages = await memory.values();

[Only package-specific patterns, ~100 lines total]

Related Skills

• .claude/skills/teams-ai-patterns - Teams.ai integration
• .claude/rules/code-patterns.md - Universal patterns

## Document Types

### Package README.md - User-Facing Documentation

**Audience**: End users (developers integrating the package)

**Tone**: Encouraging and accessible

**Content Requirements**:
- Maximum 4 steps in "Getting started" section
- Natural language examples in quotes
- Progressive disclosure with collapsible sections
- Second-person voice ("you", "your")
- Emphasize immediate value

**Language Patterns**:
| ✅ Do | ❌ Don't |
|-------|----------|
| "Get up and running in 3 quick steps" | "Installation procedure requires..." |
| "No installation required" | "This package is hosted remotely" |
| "Your agent will automatically..." | "The system executes..." |
| "Just describe what you want" | "Invoke the tool with parameters" |

### Package AGENTS.md - Thin Developer Documentation

**Audience**: Developers, contributors, AI coding agents

**Tone**: Directive and technical (for package-specific content)

**Content Requirements** (Thin approach):
- Clear audience disclaimer at top
- Quick setup (2-3 commands)
- Reference to universal skills immediately
- **ONLY package-specific patterns** (framework APIs, domain rules)
- Architecture diagram if needed
- Symptom/solution troubleshooting for package-specific issues
- Heavy skill references throughout

**Structure**:
```markdown
# Package Development Guide

> For end users: See [README.md]
> For universal patterns: `.claude/rules/code-patterns.md`

## Quick Start
[2-3 commands only]

## Code Style
> See `.claude/rules/code-patterns.md`

## Package-Specific Patterns
[Only patterns unique to this package's domain]

## Testing
> For universal patterns: `.claude/rules/code-patterns.md`

### Package-Specific Testing
[Only if truly unique to this package]

## Related Skills
[List of relevant skills]

Target Length: 100-200 lines (not 500+)

API Documentation Strategy

Do NOT create API.md files. Instead:

Add TSDoc to all exports

/**
 * Search the web using You.com API
 *
 * @param config - Optional configuration with API key
 * @returns AI SDK tool for web search
 *
 * @example
 * ```ts
 * import { youSearch } from '@youdotcom-oss/ai-sdk-plugin';
 *
 * const search = youSearch();
 * await generateText({
 *   model: 'anthropic/claude-sonnet-4.5',
 *   tools: { search },
 *   prompt: 'What happened today?'
 * });
 * ```
 */
export const youSearch = (config: YouToolsConfig = {}) => { ... }

Benefits of TSDoc over API.md

✅ Single source of truth - Types + docs in code ✅ Always in sync - Can't drift from implementation ✅ IDE integration - Hover shows docs instantly ✅ AI reads directly - Agents can access from source ✅ Less maintenance - One less file to update

Thin AGENTS.md Template

# {Package Name} Development Guide

Developer documentation for {package description}.

> **For end users**: See [README.md](./README.md) for setup and usage.
> **For universal patterns**: See `.claude/rules/code-patterns.md`

---

## Quick Start

\`\`\`bash
cd packages/{package-name}
bun install
bun test
\`\`\`

## Code Style

> **For universal patterns**: See `.claude/rules/code-patterns.md`

## Package-Specific Patterns

### [Framework/Domain Pattern 1]

[Only include if unique to this package's domain]

\`\`\`ts
// ✅ Correct - package-specific best practice
[example]

// ❌ Wrong - problematic pattern for this package
[anti-pattern]
\`\`\`

**Why this pattern?**
[Explanation specific to this package's domain]

### [Framework/Domain Pattern 2]

[Continue with only package-specific patterns]

## Testing

> **For universal patterns**: See `.claude/rules/code-patterns.md`

### Package-Specific Testing Patterns

[Only if testing approach is unique to this package]

## Architecture

[Diagram or description if package has complex architecture]

## Troubleshooting

### Symptom: [Package-specific problem]

**Solution**:
\`\`\`bash
[Fix specific to this package]
\`\`\`

## Related Skills

- `.claude/skills/{package-specific-skill}` - [Package-specific patterns]
- `.claude/rules/code-patterns.md` - Universal code patterns
- `.claude/skills/documentation` - Documentation standards
- `.claude/rules/git-workflow.md` - Git conventions

## Contributing

See root AGENTS.md for contribution guidelines.

**Package scope**: Use \`{package-name}\` in commit messages:
\`\`\`bash
feat({package-name}): add feature
fix({package-name}): resolve issue
\`\`\`

Target: 100-200 lines total, not 500+

Validation Checklists

Package README.md Checklist:

• Has 4-step "Getting started" section
• Uses encouraging language ("quick", "easy", "just")
• Provides natural language examples
• Uses second-person voice throughout
• Emphasizes immediate value
• Avoids technical jargon in main flow

Package AGENTS.md Checklist (Thin Approach):

• Starts with clear audience disclaimer
• References .claude/rules/code-patterns.md upfront
• Quick setup is 2-3 commands only
• Contains ONLY package-specific patterns
• No universal patterns duplicated (arrow functions, test patterns, etc.)
• Heavy skill references throughout
• Target length: 100-200 lines (not 500+)
• Lists related skills at bottom

TSDoc API Documentation:

• All exports have TSDoc comments
• TSDoc includes description, params, returns
• TSDoc includes @example with runnable code
• No separate API.md file exists

Common Mistakes

❌ Bloated AGENTS.md

# AGENTS.md (600 lines)

## Arrow Functions
[100 lines of universal patterns]

## Error Handling
[150 lines of universal patterns]

## Testing
[200 lines of universal patterns]

## Package-Specific Patterns
[Only 50 lines buried at bottom]

Problem: Duplicates universal patterns, hard to maintain, hard to find package-specific content

✅ Thin AGENTS.md

# AGENTS.md (150 lines)

> For universal patterns: `.claude/rules/code-patterns.md`

## Package-Specific Patterns

### Teams.ai Memory API
[50 lines of package-specific patterns]

### Anthropic Streaming
[50 lines of package-specific patterns]

## Related Skills
- `.claude/skills/teams-ai-patterns`
- `.claude/rules/code-patterns.md`

Benefits: Easy to maintain, clear separation, package-specific content easy to find

Migration Path

For Existing Packages

1. Audit current AGENTS.md - Identify universal vs package-specific patterns
2. Extract universal patterns - Already covered by skills, can remove
3. Keep package-specific - Framework APIs, domain rules, architecture
4. Add skill references - Point to relevant skills throughout
5. Target 100-200 lines - Thin wrapper, not comprehensive guide

Example Migration

Before (500 lines):

• 300 lines universal patterns (arrow functions, testing, error handling)
• 200 lines package-specific (Teams.ai Memory API, Anthropic streaming)

After (150 lines):

• 50 lines references to skills
• 100 lines package-specific patterns
• Clear, focused, maintainable

Document Type Comparison

Quick reference comparing package documentation types:

Common Mistakes

❌ Bloated Package AGENTS.md with Universal Patterns

# Package AGENTS.md (WRONG)

## Arrow Functions

Always use arrow functions...
[100 lines of examples]

## Testing

Use test() not it()...
[150 lines of examples]

## Package-Specific
[Only 50 lines buried at bottom]

Problem: Bloated with universal patterns, hard to maintain

✅ Right: Package AGENTS.md References Skills

# Package AGENTS.md (RIGHT)

> For universal patterns: `.claude/rules/code-patterns.md`

## Package-Specific Patterns

### Teams.ai Memory API
Use `push()` not `addMessage()`...
[Only package-specific content]

Related Skills

• .claude/rules/code-patterns.md - Universal code patterns
• .claude/rules/git-workflow.md - Git conventions
• .claude/rules/workflows.md - Package setup workflow

Converted and distributed by TomeVault — claim your Tome and manage your conversions.