feat: add aidocs serve command with MkDocs Material theme

- Add `aidocs serve` command to serve docs with live reload
- Auto-discovers navigation from folder structure
- Material Design theme with light/dark mode
- Hot reload when markdown files change
- Full-text search and code highlighting
- Optional `--build` flag for static site export
- Combine Quick Start and Installation sections in README

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: binaryk

.claude/settings.local.json

@@ -18,7 +18,8 @@
       "Bash(brew install:*)",
       "Bash(brew untap:*)",
       "Bash(aidocs version:*)",
-      "Bash(uv pip install:*)"
+      "Bash(uv pip install:*)",
+      "Bash(git checkout:*)"
     ]
   }
 }

README.md

@@ -2,6 +2,10 @@
 
 AI-powered documentation generator for web applications.
 
+[![Watch the video](https://img.youtube.com/vi/cmwt4XizcTw/maxresdefault.jpg)](https://youtu.be/cmwt4XizcTw)
+
+▶️ **[Watch the demo on YouTube](https://youtu.be/cmwt4XizcTw)**
+
 ## How It Works
 
 aidocs generates comprehensive documentation by combining **three sources of truth**:
@@ -27,44 +31,34 @@ This produces documentation that's accurate to both the code AND the actual user
                     └────────────────────────┘
 ```
 
-## Installation
+## Quick Start
 
 ```bash
-# Install from PyPI
+# 1. Install the CLI
 uv tool install aidocs
 
-# Or install from GitHub
-uv tool install aidocs --from git+https://github.com/binarcode/aidocs-cli.git
+# 2. Add to your project
+cd your-project
+aidocs init .
 
-# Or use pipx
-pipx install aidocs
+# 3. Generate docs (in Claude Code)
+/docs:generate https://myapp.com/dashboard
 ```
 
-## Updating
-
-When a new version is released, update the CLI and reinstall commands in your project:
-
+**Alternative installation:**
 ```bash
-# 1. Update the CLI
-aidocs update
+# From GitHub (latest)
+uv tool install aidocs --from git+https://github.com/binarcode/aidocs-cli.git
 
-# 2. Reinstall commands in your project (adds new slash commands)
-cd your-project
-aidocs init . --force
+# Or use pipx
+pipx install aidocs
 ```
 
-The `--force` flag overwrites existing command files, adding any new commands from the latest version.
-
-**Tip:** Run `aidocs update --github` to get the latest unreleased features from GitHub.
-
-## Quick Start
-
+**Updating:**
 ```bash
-# Install the CLI
-uv tool install aidocs
-
-# Add to your project
-aidocs init .
+aidocs update                  # Update from PyPI
+aidocs update --github         # Update from GitHub (latest)
+aidocs init . --force          # Reinstall commands in project
 ```
 
 ## Usage Flow
@@ -258,6 +252,43 @@ docs/
 
 **Next step:** Run `aidocs rag-vectors` to generate embeddings
 
+### `aidocs export-pdf`
+
+Export markdown documentation to PDF with auto-generated table of contents.
+
+```bash
+aidocs export-pdf docs/projects/index.md                    # Export to docs/exports/
+aidocs export-pdf docs/flows/sync-users.md -o manual.pdf    # Custom output path
+```
+
+**Options:**
+| Option | Description |
+|--------|-------------|
+| `--output, -o` | Output PDF path (default: `docs/exports/{name}.pdf`) |
+
+**What it does:**
+1. Reads the markdown file
+2. Extracts H1/H2 headings for table of contents
+3. Converts markdown to styled HTML
+4. Uses Chrome/Chromium headless to render PDF
+5. Saves with proper page breaks and formatting
+
+**Output:**
+```
+╭──────────── Success ────────────╮
+│ PDF exported successfully!      │
+│                                 │
+│ Title: Projects Overview        │
+│ TOC entries: 8                  │
+│ Size: 245.3 KB                  │
+│                                 │
+│ Output: docs/exports/index.pdf  │
+╰─────────────────────────────────╯
+```
+
+**Requirements:**
+- Chrome or Chromium installed (uses headless mode)
+
 ### `aidocs rag-vectors`
 
 Generate embeddings and SQL for vector database import.
@@ -303,6 +334,8 @@ psql $DATABASE_URL -f docs/.chunks/sync.sql
 
 Serve documentation with live reload using MkDocs Material theme.
 
+![aidocs serve](docs/aidocs-serve.png)
+
 ```bash
 aidocs serve                    # Serve docs/ on port 8000
 aidocs serve --port 3000        # Custom port

docs/aidocs-serve.png

@@ -1,6 +1,6 @@
 [project]
 name = "aidocs"
-version = "0.13.2"
+version = "0.14.0"
 description = "AI-powered documentation generator for web applications. Install docs commands into your Claude Code project."
 readme = "README.md"
 license = { text = "MIT" }

docs/exports/README.pdf

@@ -1,6 +1,6 @@
 """AI-powered documentation generator CLI for Claude Code projects."""
 
-__version__ = "0.13.2"
+__version__ = "0.14.0"
 
 from .cli import app
 

pyproject.toml

@@ -14,6 +14,7 @@
 from .chunker import chunk_directory
 from .embeddings import generate_sync_sql, get_openai_api_key
 from .installer import check_tools, install_docs_module
+from .pdf_exporter import export_markdown_to_pdf
 from .server import generate_mkdocs_config, validate_docs_directory, write_mkdocs_config
 
 console = Console()
@@ -436,6 +437,65 @@ def on_status(message: str) -> None:
         raise typer.Exit(1)
 
 
+@app.command("export-pdf")
+def export_pdf(
+    markdown_file: str = typer.Argument(
+        ...,
+        help="Path to the markdown file to export.",
+    ),
+    output: Optional[str] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output PDF path (default: docs/exports/{name}.pdf).",
+    ),
+) -> None:
+    """Export markdown documentation to PDF.
+
+    Converts a markdown file to a styled PDF with auto-generated
+    table of contents. Uses Chrome/Chromium for rendering.
+
+    Examples:
+        aidocs export-pdf docs/projects/index.md
+        aidocs export-pdf docs/flows/sync-users.md -o manual.pdf
+    """
+    md_path = Path(markdown_file)
+    out_path = Path(output) if output else None
+
+    console.print(f"[blue]Exporting {markdown_file} to PDF...[/blue]")
+    console.print()
+
+    def on_status(msg: str) -> None:
+        console.print(f"  [dim]{msg}[/dim]")
+
+    try:
+        result = export_markdown_to_pdf(md_path, out_path, on_status=on_status)
+
+        if not result["success"]:
+            console.print(f"[red]Error: {result.get('error', 'Unknown error')}[/red]")
+            raise typer.Exit(1)
+
+        stats = result["stats"]
+        console.print()
+        console.print(Panel.fit(
+            f"[green]PDF exported successfully![/green]\n\n"
+            f"[bold]Title:[/bold] {stats['title']}\n"
+            f"[bold]TOC entries:[/bold] {stats['toc_entries']}\n"
+            f"[bold]Size:[/bold] {stats['size_kb']} KB\n\n"
+            f"[bold]Output:[/bold] {result['output_path']}\n\n"
+            f"[dim]Open with:[/dim]\n"
+            f"  [cyan]open {result['output_path']}[/cyan]",
+            title="Success",
+            border_style="green",
+        ))
+
+    except typer.Exit:
+        raise
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
 @app.command()
 def serve(
     docs_dir: Optional[str] = typer.Argument(
@@ -512,7 +572,7 @@ def serve(
 
             try:
                 result = subprocess.run(
-                    ["mkdocs", "build", "-f", str(config_path)],
+                    [sys.executable, "-m", "mkdocs", "build", "-f", str(config_path)],
                     capture_output=True,
                     text=True,
                 )
@@ -533,7 +593,7 @@ def serve(
                     raise typer.Exit(1)
 
             except FileNotFoundError:
-                console.print("[red]Error: mkdocs not found. Install with: pip install mkdocs mkdocs-material[/red]")
+                console.print("[red]Error: Failed to run mkdocs. Try reinstalling aidocs.[/red]")
                 raise typer.Exit(1)
         else:
             url = f"http://{host}:{port}"
@@ -549,9 +609,10 @@ def serve(
 
             try:
                 cmd = [
-                    "mkdocs", "serve",
+                    sys.executable, "-m", "mkdocs", "serve",
                     "-f", str(config_path),
                     "-a", f"{host}:{port}",
+                    "--watch", str(target_dir),
                 ]
 
                 if open_browser:
@@ -564,7 +625,7 @@ def open_after_delay() -> None:
                 subprocess.run(cmd)
 
             except FileNotFoundError:
-                console.print("[red]Error: mkdocs not found. Install with: pip install mkdocs mkdocs-material[/red]")
+                console.print("[red]Error: Failed to run mkdocs. Try reinstalling aidocs.[/red]")
                 raise typer.Exit(1)
             except KeyboardInterrupt:
                 console.print("\n[yellow]Server stopped.[/yellow]")

src/aidocs_cli/__init__.py

@@ -66,8 +66,6 @@ def install_docs_module(
     console.print("[dim]Copying workflow files...[/dim]")
     workflows_src = templates_path / "workflows"
     if workflows_src.exists():
-        if workflows_dest.exists() and force:
-            shutil.rmtree(workflows_dest)
         shutil.copytree(workflows_src, workflows_dest, dirs_exist_ok=True)
 
         for workflow_dir in workflows_dest.iterdir():