|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +aidocs is a Python CLI tool that generates AI-powered documentation for web applications. It installs slash commands into Claude Code projects (e.g., `/docs:generate`, `/docs:flow`) that combine vision analysis, codebase analysis, and interactive UI exploration to produce comprehensive documentation. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Setup development environment |
| 13 | +uv venv && uv pip install -e . |
| 14 | + |
| 15 | +# Run CLI |
| 16 | +aidocs check # Check environment/dependencies |
| 17 | +aidocs init . # Install docs module in current project |
| 18 | +aidocs version # Show version |
| 19 | + |
| 20 | +# RAG/Embeddings workflow |
| 21 | +aidocs rag-chunks docs/ # Chunk markdown files for vector DB |
| 22 | +aidocs rag-vectors # Generate embeddings (requires OPENAI_API_KEY) |
| 23 | + |
| 24 | +# Documentation server |
| 25 | +aidocs serve # Serve docs with MkDocs Material |
| 26 | +aidocs serve --build # Build static site |
| 27 | + |
| 28 | +# PDF export |
| 29 | +aidocs export-pdf docs/page.md |
| 30 | +``` |
| 31 | + |
| 32 | +## Architecture |
| 33 | + |
| 34 | +``` |
| 35 | +src/aidocs_cli/ |
| 36 | +├── __init__.py # Version and entry point |
| 37 | +├── cli.py # Typer CLI commands (init, check, serve, rag-*, export-pdf) |
| 38 | +├── installer.py # Copies templates to target project (.claude/commands/, .claude/workflows/) |
| 39 | +├── chunker.py # Splits markdown at ## headings for RAG |
| 40 | +├── embeddings.py # OpenAI embeddings + SQL generation for pgvector |
| 41 | +├── server.py # MkDocs config generation and nav discovery |
| 42 | +├── pdf_exporter.py # Markdown→HTML→PDF with Chrome/Playwright |
| 43 | +└── templates/ |
| 44 | + ├── commands/docs/ # Slash command definitions (*.md) |
| 45 | + └── workflows/ # Workflow implementations per command |
| 46 | +``` |
| 47 | + |
| 48 | +### Key Components |
| 49 | + |
| 50 | +- **CLI (cli.py)**: Uses Typer with Rich for terminal UI. Entry point is `app()`. |
| 51 | +- **Installer**: Copies command/workflow templates to target project's `.claude/` directory (or `.cursor/` for Cursor). |
| 52 | +- **Chunker**: Creates `.chunks.json` files alongside markdown, tracks changes via `docs/.chunks/manifest.json`. |
| 53 | +- **Embeddings**: Calls OpenAI API (text-embedding-3-small, 1536 dimensions), outputs `docs/.chunks/sync.sql` for pgvector import. |
| 54 | +- **Server**: Auto-discovers nav structure from folder hierarchy, generates ephemeral `mkdocs.yml`. |
| 55 | + |
| 56 | +### Slash Commands Flow |
| 57 | + |
| 58 | +When `aidocs init` runs: |
| 59 | +1. Templates from `src/aidocs_cli/templates/` are copied to project's `.claude/commands/docs/` and `.claude/workflows/docs/` |
| 60 | +2. Each command (e.g., `generate.md`) references a workflow that defines the multi-step process |
| 61 | +3. Workflows use Playwright MCP for browser automation when needed |
| 62 | + |
| 63 | +## Version Management |
| 64 | + |
| 65 | +Version is defined in two places (keep in sync): |
| 66 | +- `pyproject.toml` → `version = "X.Y.Z"` |
| 67 | +- `src/aidocs_cli/__init__.py` → `__version__ = "X.Y.Z"` |
| 68 | + |
| 69 | +## Release Process |
| 70 | + |
| 71 | +1. Update version in both files |
| 72 | +2. Commit and push to main |
| 73 | +3. Create GitHub release → triggers `.github/workflows/publish.yml` (PyPI) and `.github/workflows/update-homebrew.yml` |
| 74 | + |
| 75 | +## Dependencies |
| 76 | + |
| 77 | +Core: typer, rich, httpx, mkdocs, mkdocs-material, pyyaml |
| 78 | + |
| 79 | +Python 3.11+ required. Build system uses hatchling. |
| 80 | + |
| 81 | +## Environment Variables |
| 82 | + |
| 83 | +- `OPENAI_API_KEY`: Required for `rag-vectors` command (embedding generation) |
0 commit comments