Documentation Generation CLI Tool

Overview

A CLI tool (@facs95/doc-gen) that automatically generates vectorization-optimized documentation from codebases. This tool helps developers create high-quality, AI-friendly documentation that can be uploaded to ChatSDK's knowledge base for context-aware chat responses.

Problem Statement

Developers need to provide comprehensive documentation to power AI chat assistants, but:

• Writing documentation from scratch is time-consuming
• Existing docs may not be optimized for vector databases and RAG systems
• Code changes often outpace documentation updates
• Documentation needs specific structure for effective semantic search

Solution

An intelligent CLI tool that:

1. Analyzes codebases to extract API endpoints, components, types, and patterns
2. Generates structured documentation with AI-assisted descriptions
3. Optimizes content for vector embeddings (chunking, metadata, keywords)
4. Exports in formats ready for upload to ChatSDK's knowledge base

Quick Start: Claude Code Commands (Available Now)

Status: ✅ Ready to use - No installation required!

While the full standalone CLI tool is in development, we've created Claude Code slash commands that provide the core documentation generation functionality right now. These commands leverage Claude's deep code understanding to generate vectorization-optimized docs.

Installation

The commands are available globally in Claude Code. No package installation needed!

Location: ~/.claude/commands/

• gen-docs-init.md - Interactive setup command
• gen-docs.md - Code analysis and generation command

Usage

Step 1: Initialize (First Time)

In any project directory within Claude Code, run:

/gen-docs-init

This will:

• Ask 8 interactive questions about your product (purpose, features, common tasks, audience, tech stack, etc.)
• Create ./doc-gen.config.json with your answers
• Generate initial guide chunks (Overview, Getting Started, Features, Common Tasks)
• Set up the ./chat-docs/ directory structure

Questions asked:

1. What does your product do? (one sentence)
2. What are your main features?
3. What are common user tasks?
4. Do you have existing documentation?
5. Who is your primary audience?
6. What is your technology stack?
7. What documentation style do you prefer?
8. Should we analyze your codebase?

Step 2: Generate Documentation from Code

/gen-docs

This will:

• Load the config from ./doc-gen.config.json (or use defaults)
• Analyze your codebase (TypeScript, JavaScript, React components)
• Extract all exported APIs, components, types, functions
• Generate vectorization-optimized JSON chunks in ./chat-docs/chunks/
• Create/update manifest.json with statistics
• Provide a detailed summary report

What it generates:

• API documentation (functions, endpoints)
• React component docs (props, usage)
• TypeScript type definitions
• Related code detection
• Usage examples
• Rich metadata (keywords, importance, user intent)

Step 3: Review & Export

# Review generated files
ls ./chat-docs/chunks/

# Export for upload (manual zip)
zip -r chat-docs.zip chat-docs/

Example Workflow

# In your project directory
cd my-awesome-app

# Initialize and answer questions
/gen-docs-init

# Generate docs from codebase
/gen-docs

# Later, after code changes, regenerate
/gen-docs

Output Structure

chat-docs/
├── doc-gen.config.json       # Your project configuration
├── manifest.json             # Index of all documentation
└── chunks/
    ├── api/
    │   └── *.json            # API function docs
    ├── components/
    │   └── *.json            # React component docs
    ├── types/
    │   └── *.json            # TypeScript type docs
    ├── functions/
    │   └── *.json            # Utility function docs
    └── guides/
        └── *.json            # Getting started, feature guides

Example Generated Chunk

{
  "id": "component-chatprovider",
  "title": "ChatProvider Component",
  "content": "ChatProvider is the main entry point for integrating ChatSDK into your React application. It wraps your app and provides chat functionality...\n\n## Usage\n\n```tsx\nimport { ChatProvider } from '@cyborg-sdk/react';\n\nfunction App() {\n  return (\n    <ChatProvider config={{ apiKey: 'your-api-key' }}>\n      <YourApp />\n    </ChatProvider>\n  );\n}\n```",
  "metadata": {
    "type": "component",
    "category": "setup",
    "keywords": ["chatprovider", "setup", "configuration", "provider"],
    "codeRef": "src/provider/ChatProvider.tsx:1",
    "relatedChunks": ["hook-usechat", "type-chatconfig"],
    "relatedPages": ["/"],
    "importance": "critical",
    "userIntent": ["setup", "getting started", "integration"],
    "lastUpdated": "2025-11-02T00:00:00Z"
  }
}

Advantages of Claude Code Approach

1. Zero Setup: No npm packages to install, works immediately
2. Deep Understanding: Claude's code intelligence understands context across your entire codebase
3. Interactive: Can ask follow-up questions for clarification
4. Flexible: Easy to customize by editing the command markdown files
5. Fast Iteration: Update prompts in ~/.claude/commands/*.md to refine output
6. Proven: Same AI technology that will power the standalone CLI

Configuration-Driven Generation

The /gen-docs command uses doc-gen.config.json to tailor output:

{
  "version": "1.0.0",
  "project": {
    "name": "my-app",
    "description": "A context-aware AI chat SDK",
    "features": ["Real-time chat", "Context awareness"],
    "commonTasks": ["Setting up authentication", "Customizing UI"],
    "audience": "Frontend developers",
    "techStack": ["React", "TypeScript"]
  },
  "generation": {
    "style": "balanced",
    "chunkSize": 512
  },
  "output": {
    "directory": "./chat-docs",
    "format": "json"
  }
}

The command adapts documentation:

• Style: Task-oriented vs. reference-heavy vs. tutorial-based
• Audience: Adjusts complexity and focus areas
• Features: Tags chunks with relevant features
• Common Tasks: Maps chunks to user intent

Planned Standalone CLI Features

1. Code Analysis & Extraction

npx @facs95/doc-gen generate --source ./src

What it extracts:

• API Endpoints: Express/Fastify routes, tRPC procedures, REST/GraphQL APIs
• React Components: Props, usage examples, variants
• TypeScript Types: Interfaces, type aliases, enums with descriptions
• Functions: Signatures, parameters, return types from JSDoc
• Workflows: Common code patterns and user flows
• Error Codes: Error definitions and handling patterns

2. Vectorization Optimization

Intelligent Chunking:

• Target chunk size: 512 tokens (configurable)
• Overlap between chunks: 50 tokens (maintains context)
• Respects semantic boundaries (doesn't split mid-sentence)
• Each chunk includes metadata for better retrieval

Metadata Enrichment:

{
  "id": "chunk-identifier",
  "title": "Human-readable title",
  "content": "The actual content optimized for embeddings",
  "metadata": {
    "type": "api | component | guide | troubleshooting | concept",
    "category": "authentication | setup | advanced",
    "keywords": ["extracted", "semantic", "keywords"],
    "codeRef": "src/file.ts:line",
    "relatedChunks": ["related-chunk-ids"],
    "relatedPages": ["/dashboard", "/settings"],
    "importance": "critical | high | medium | low",
    "userIntent": ["setup", "troubleshoot", "customize"],
    "lastUpdated": "2025-11-02T00:00:00Z"
  },
  "chunkIndex": 1,
  "totalChunks": 3
}

3. Gap Analysis & Recommendations

npx @facs95/doc-gen validate ./chat-docs

Analyzes documentation quality and provides recommendations for:

• Coverage (% of APIs documented)
• Missing documentation areas
• Quality metrics and code example coverage
• Suggestions for improvements

4. Export & Upload

Export for manual upload:

npx @facs95/doc-gen export --format zip
# Creates: chat-docs-2025-11-02.zip

Direct upload (future integration):

npx @facs95/doc-gen upload --api-key xxx --project my-app

CLI Commands (Planned)

Initialize

npx @facs95/doc-gen init

Creates doc-gen.config.js and prompts for project information.

Generate

npx @facs95/doc-gen generate [options]

Options:
  --source <path>       Source directory to analyze (default: ./src)
  --output <path>       Output directory (default: ./chat-docs)
  --config <path>       Config file path (default: doc-gen.config.js)
  --watch              Watch mode - regenerate on file changes
  --ai                 Enable AI-assisted generation
  --no-cache           Skip cache, regenerate everything

Validate

npx @facs95/doc-gen validate [path]

Options:
  --fix                Auto-fix issues where possible
  --report <format>    Generate report (json | html | markdown)

Export

npx @facs95/doc-gen export [options]

Options:
  --format <type>      Export format (zip | tar | json)
  --output <path>      Output file path

Implementation Status

• ✅ Phase 0: Claude Code slash commands (COMPLETE)
• ⏳ Phase 1: Core extraction (MVP - Standalone CLI)
• ⏳ Phase 2: Enhanced analysis
• ⏳ Phase 3: AI integration
• ⏳ Phase 4: Optimization & validation
• ⏳ Phase 5: ChatSDK integration

Integration with ChatSDK Ecosystem

The generated chunks are optimized for the RAG pipeline:

User Query → Vector Search → Retrieve Relevant Chunks → Combine with Context → AI Response

Benefits of structured chunks:

• Better semantic search (metadata filtering)
• Relevance ranking (importance field)
• Context injection (relatedChunks, relatedPages)
• User intent matching (userIntent field)

Next Steps

1. Run /gen-docs-init in your project
2. Review generated config and guides
3. Run /gen-docs to generate code documentation
4. Iterate and refine as needed
5. Export and upload to ChatSDK knowledge base

Learn more: Check out the Getting Started guide for a step-by-step walkthrough.