Instructions for creating comprehensive user-facing documentation from scratch by analyzing the codebase.

Purpose

Generate structured documentation in the /docs directory that helps end users understand and use the system. This is technical user documentation that is designed to be human-readable.

Core Principles

Code-First Verification

Every documented feature must be verified to exist in code. Never document aspirational functionality.

Minimal Content, Maximal Coverage

Document every code component (function, class, API, hook, configuration) with only essential information. Comprehensive coverage means each discrete component gets dedicated documentation. Minimal content means concise explanations.

Modular Component Documentation

Each discrete component gets its own dedicated file with complete coverage of all its methods, properties, and functionality.

Code Structure Mirroring

Documentation structure must directly mirror actual code organization. Each subdirectory corresponds to actual code extensions.

End User Focus

Write for people who need to USE the system, not build it. Make technical concepts accessible.

Workflow

1. Code Structure Analysis

Map the actual file, class, and function organization. Use comprehensive scanning to understand the codebase architecture.

2. Component Discovery

Continue systematic search until ALL handlers, tools, APIs, filters, actions, and components are cataloged. Do not proceed until complete inventory is achieved.

3. Entry Point Identification

Distinguish main user-facing APIs from internal helper functions. Prioritize documentation of user-facing functionality.

4. Usage Pattern Extraction

Find actual usage workflows in existing code, tests, and examples. Document real patterns, not theoretical usage.

5. Create Directory Structure

Create subdirectories in /docs that directly correspond to actual code extensions and components.

6. Create Documentation Files

Use homeboy docs audit <component> to identify gaps, then create files manually following the structure standards in homeboy docs documentation/structure. Use homeboy docs map <component> to generate a codebase map for AI-assisted documentation.

7. Write Content

For each file:

• Document all methods, properties, configuration options within that component’s scope
• Include only complete code examples from actual implementation
• Show actual usage patterns found in existing code

8. Coverage Validation

Verify ALL discovered components have been documented before completion.

9. Run Audit

homeboy docs audit <component>

Verify all generated documentation references valid code paths. Fix any broken tasks before marking generation complete.

Forbidden Content

Never generate:

• Installation guides or setup instructions
• Getting started tutorials or step-by-step guides
• Troubleshooting sections or common issues
• Configuration walkthroughs or setup wizards
• Generic workflow examples or use case scenarios
• Version history or changelog content
• Marketing copy or feature promotion
• Comprehensive explanations of basic concepts

File Naming

• Use descriptive filenames that reflect functionality being documented
• No generic names like readme.md, index.md, or overview.md in subdirectories
• File names describe what the content covers
• For directory entry points, use {directory}/{directory}.md pattern (see homeboy docs documentation/structure)

Generate Spec Schema

The homeboy docs generate command accepts a JSON spec that defines files to create. The spec can be provided as a positional argument, via --json, from a file with @path/to/spec.json, or from stdin with -.

Schema

{
  "output_dir": "string (required) — target directory for generated files",
  "files": [
    {
      "path": "string (required) — relative path within output_dir (e.g., 'api/endpoints.md')",
      "title": "string (optional) — used to generate an H1 heading when content is not provided",
      "content": "string (optional) — full file content; when provided, replaces auto-generated heading"
    }
  ]
}

Field Behavior

• output_dir: Created automatically if it doesn’t exist. All file paths are relative to this directory.
• files[].path: Parent directories are created automatically. Must include file extension.
• files[].title: Only used when content is omitted. Generates # {title}n as the file content.
• files[].content: When provided, written as-is. The title field is ignored.
• If neither title nor content is provided, an H1 heading is auto-generated from the filename (kebab-case and snake_case converted to Title Case).

Example

homeboy docs generate @spec.json

Where spec.json contains:

{
  "output_dir": "docs/api",
  "files": [
    {"path": "endpoints.md", "title": "API Endpoints"},
    {"path": "auth/oauth.md", "title": "OAuth Flow"},
    {"path": "errors.md"}
  ]
}

This creates:

• docs/api/endpoints.md with heading "API Endpoints"
• docs/api/auth/oauth.md with heading "OAuth Flow"
• docs/api/errors.md with auto-generated heading "Errors"

Output

Returns JSON with files_created, files_updated, and hints arrays. Files that already exist are reported as updated rather than created.

Completion Criteria

Do not mark generation complete until:

• Every discoverable handler, tool, API, filter, action, and component has dedicated documentation
• All code extensions identified in discovery phase have corresponding documentation files
• All subdirectories in /docs correspond to actual code extensions
• All documented workflows correspond to actual code patterns

Quality Gates

Before completion, verify:

• All documented features verified to exist in current codebase
• Present-tense language throughout
• All code extensions have corresponding documentation
• User-focused explanations that remain technically accurate
• Complete usage examples from actual implementation
• Hierarchical structure mirrors actual code organization