ragtime-cli 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

{ragtime_cli-0.2.3.dist-info → ragtime_cli-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.3
+Version: 0.2.4
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT
@@ -37,8 +37,12 @@ Local-first memory and RAG system for Claude Code. Semantic search over code, do
 - **Memory Storage**: Store structured knowledge with namespaces, types, and metadata
 - **Semantic Search**: Query memories and docs with natural language
 - **Cross-Branch Sync**: Share context with teammates before PRs merge
+- **Convention Checking**: Verify code follows team standards before PRs
+- **Doc Generation**: Generate documentation from code (stubs or AI-powered)
+- **Debug Tools**: Verify index integrity, inspect similarity scores
 - **MCP Server**: Native Claude Code integration
-- **Claude Commands**: Pre-built `/remember`, `/recall`, `/handoff`, `/start` commands
+- **Claude Commands**: Pre-built `/remember`, `/recall`, `/create-pr`, `/generate-docs` commands
+- **ghp-cli Integration**: Auto-context when starting issues
 
 ## Installation
 
@@ -52,6 +56,9 @@ pip install ragtime-cli
 # Initialize in your project
 ragtime init
 
+# Index your docs
+ragtime index
+
 # Store a memory
 ragtime remember "Auth uses JWT with 15-min expiry" \
   --namespace app \
@@ -63,6 +70,9 @@ ragtime search "authentication" --namespace app
 
 # Install Claude commands
 ragtime install --workspace
+
+# Check for updates
+ragtime update --check
 ```
 
 ## CLI Commands
@@ -94,19 +104,75 @@ ragtime search "how does auth work" --namespace app --limit 10
 
 # Reindex memory files
 ragtime reindex
+
+# Audit docs for missing frontmatter
+ragtime audit docs/
+ragtime audit docs/ --fix    # Interactively add frontmatter
+ragtime audit docs/ --json   # Machine-readable output
+```
+
+### Documentation Generation
+
+```bash
+# Generate doc stubs from code
+ragtime generate src/ --stubs
+
+# Specify output location
+ragtime generate src/ --stubs -o docs/api
+
+# Python only
+ragtime generate src/ --stubs -l python
+
+# Include private methods
+ragtime generate src/ --stubs --include-private
+```
+
+### Debug & Verification
+
+```bash
+# Debug a search query (show similarity scores)
+ragtime debug search "authentication"
+ragtime debug search "auth" --show-vectors
+
+# Find similar documents
+ragtime debug similar docs/auth/jwt.md
+
+# Index statistics by namespace/type
+ragtime debug stats
+ragtime debug stats --by-namespace
+ragtime debug stats --by-type
+
+# Verify index integrity
+ragtime debug verify
 ```
 
 ### Cross-Branch Sync
 
 ```bash
-# Sync teammate's branch memories
-ragtime sync origin/jm/feature-auth
+# Sync all teammate branch memories
+ragtime sync
 
-# Clean up stale synced folders
+# Auto-prune stale synced folders
+ragtime sync --auto-prune
+
+# Manual prune
 ragtime prune --dry-run
 ragtime prune
 ```
 
+### Daemon (Auto-Sync)
+
+```bash
+# Start background sync daemon
+ragtime daemon start --interval 5m
+
+# Check status
+ragtime daemon status
+
+# Stop daemon
+ragtime daemon stop
+```
+
 ### Claude Integration
 
 ```bash
@@ -118,48 +184,47 @@ ragtime install --global
 
 # List available commands
 ragtime install --list
-```
 
-## MCP Server
-
-Add to your Claude config (`.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "ragtime": {
-      "command": "ragtime-mcp",
-      "args": ["--path", "."]
-    }
-  }
-}
+# Set up ghp-cli hooks
+ragtime setup-ghp
 ```
 
-Available tools:
-- `remember` - Store a memory
-- `search` - Semantic search
-- `list_memories` - List with filters
-- `get_memory` - Get by ID
-- `store_doc` - Store document verbatim
-- `forget` - Delete memory
-- `graduate` - Promote branch → app
-- `update_status` - Change memory status
-
 ## Storage Structure
 
 ```
-.claude/memory/
-├── app/{component}/            # Graduated app knowledge
+.ragtime/
+├── config.yaml              # Configuration
+├── CONVENTIONS.md           # Team rules (checked by /create-pr)
+├── app/{component}/         # Graduated app knowledge (tracked)
 │   └── {id}-{slug}.md
-├── team/                       # Team conventions
+├── team/                    # Team conventions (tracked)
 │   └── {id}-{slug}.md
-├── users/{username}/           # User preferences
-│   └── {id}-{slug}.md
-└── branches/
-    ├── {branch-slug}/          # Your branch (tracked in git)
-    │   ├── context.md          # Session handoff
-    │   └── {id}-{slug}.md
-    └── {branch}(unmerged)/     # Synced from teammates (gitignored)
+├── branches/
+│   ├── {branch-slug}/       # Your branch (tracked in git)
+│   │   ├── context.md
+│   │   └── {id}-{slug}.md
+│   └── .{branch-slug}/      # Synced from teammates (gitignored, dot-prefix)
+├── archive/branches/        # Archived completed branches (tracked)
+└── index/                   # ChromaDB vector store (gitignored)
+```
+
+## Configuration
+
+`.ragtime/config.yaml`:
+
+```yaml
+docs:
+  paths: ["docs", ".ragtime"]
+  patterns: ["**/*.md"]
+  exclude: ["**/node_modules/**"]
+
+code:
+  paths: ["."]
+  languages: ["python", "typescript", "dart"]
+
+conventions:
+  files: [".ragtime/CONVENTIONS.md"]
+  also_search_memories: true
 ```
 
 ## Memory Format
@@ -174,7 +239,7 @@ type: architecture
 component: auth
 confidence: high
 status: active
-added: '2026-01-31'
+added: '2025-01-31'
 author: bretwardjames
 ---
 
@@ -200,6 +265,7 @@ Sessions are stored in Redis, not cookies.
 | `decision` | Why we chose X over Y |
 | `convention` | Team standards |
 | `pattern` | Reusable approaches |
+| `integration` | External service connections |
 | `context` | Session handoff |
 
 ## Claude Commands
@@ -212,8 +278,79 @@ After `ragtime install --workspace`:
 | `/recall` | Search memories |
 | `/handoff` | Save session context |
 | `/start` | Resume work on an issue |
-| `/pr-graduate` | Curate branch knowledge after merge |
-| `/audit` | Find duplicates/conflicts |
+| `/create-pr` | Check conventions, graduate memories, create PR |
+| `/generate-docs` | AI-powered documentation generation from code |
+| `/import-docs` | Migrate existing docs to memories |
+| `/pr-graduate` | Curate branch knowledge (fallback if forgot before PR) |
+| `/audit` | Find duplicates/conflicts in memories |
+
+## MCP Server
+
+Add to your Claude config (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ragtime": {
+      "command": "ragtime-mcp",
+      "args": ["--path", "."]
+    }
+  }
+}
+```
+
+Available tools:
+- `remember` - Store a memory
+- `search` - Semantic search
+- `list_memories` - List with filters
+- `get_memory` - Get by ID
+- `store_doc` - Store document verbatim
+- `forget` - Delete memory
+- `graduate` - Promote branch → app
+- `update_status` - Change memory status
+
+## ghp-cli Integration
+
+If you use [ghp-cli](https://github.com/bretwardjames/ghp-cli):
+
+```bash
+# Register ragtime hooks
+ragtime setup-ghp
+```
+
+This auto-creates `context.md` from issue details when you run `ghp start`.
+
+## Workflow
+
+### Starting Work
+
+```bash
+ghp start 123              # Creates branch + context.md
+# or
+ragtime new-branch 123     # Just the context
+```
+
+### During Development
+
+```bash
+/remember "API uses rate limiting"   # Capture insights
+/handoff                              # Save progress for later
+```
+
+### Before PR
+
+```bash
+/create-pr
+# 1. Checks code against CONVENTIONS.md
+# 2. Reviews branch memories
+# 3. Graduates selected memories to app/
+# 4. Commits knowledge with code
+# 5. Creates PR
+```
+
+### After Merge
+
+Graduated knowledge is already in the PR. Run `ragtime prune` to clean up synced folders.
 
 ## License
 

{ragtime_cli-0.2.3.dist-info → ragtime_cli-0.2.4.dist-info}/RECORD

@@ -1,12 +1,13 @@
-ragtime_cli-0.2.3.dist-info/licenses/LICENSE,sha256=9A0wJs2PRDciGRH4F8JUJ-aMKYQyq_gVu2ixrXs-l5A,1070
+ragtime_cli-0.2.4.dist-info/licenses/LICENSE,sha256=9A0wJs2PRDciGRH4F8JUJ-aMKYQyq_gVu2ixrXs-l5A,1070
 src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-src/cli.py,sha256=PZ6NHl7rOyUVZ2HAcGPoytNRtsHczybTBy7A6xQpgoA,47320
+src/cli.py,sha256=iNCYKD6w1gi64eNeb8BFj-xPzVnQLqHMzmPzoRGE3tI,67135
 src/config.py,sha256=kaJV-7yI-LMW16e1w6JvM1ZCjgPf8EiBBOM4OXio6I8,4045
 src/db.py,sha256=BKrlhilXYHNaj-ZcffinSXVhdUqowmwpFPBx7aLxamU,4642
 src/mcp_server.py,sha256=Tx0i73GXO0YmcVrdO7UjRMS0auN8fBG2LOpHuf_LUC0,20374
 src/memory.py,sha256=POT2lYeBcEx4_MPbsIdet6ScwcjmuETz8Dxmz-Z_7IY,11939
 src/commands/audit.md,sha256=Xkucm-gfBIMalK9wf7NBbyejpsqBTUAGGlb7GxMtMPY,5137
 src/commands/create-pr.md,sha256=u6-jVkDP_6bJQp6ImK039eY9F6B9E2KlAVlvLY-WV6Q,9483
+src/commands/generate-docs.md,sha256=9W2Yy-PDyC3p5k39uEb31z5YAHkSKsQLg6gV3tLgSnQ,7015
 src/commands/handoff.md,sha256=8VxTddtW08jGTW36GW_rS77JdeSn8vHeMfklrWwVUD4,5055
 src/commands/import-docs.md,sha256=ByIdcfbdiF77HoFv5U6zZ_YvZf00-hAs9EMconXssvY,6927
 src/commands/pr-graduate.md,sha256=nXJMuXeOp0SZfjQ567NUO02Rg9zPQHQFbZbJ4Q_His0,6692
@@ -16,8 +17,8 @@ src/commands/save.md,sha256=7gTpW46AU9Y4l8XVZ8f4h1sEdBfVqIRA7hlidUxMAC4,251
 src/commands/start.md,sha256=qoqhkMgET74DBx8YPIT1-wqCiVBUDxlmevigsCinHSY,6506
 src/indexers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 src/indexers/docs.py,sha256=7FENHaKSvC1T557bRzvmrjyaG_vK94GuQG9XMZdr89w,3349
-ragtime_cli-0.2.3.dist-info/METADATA,sha256=QaKUlKE4A2BwGX3NNTXm02JLwko_msFmJg3K6RyOmmo,5311
-ragtime_cli-0.2.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-ragtime_cli-0.2.3.dist-info/entry_points.txt,sha256=cWLbeyMxZNbew-THS3bHXTpCRXt1EaUy5QUOXGXLjl4,75
-ragtime_cli-0.2.3.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
-ragtime_cli-0.2.3.dist-info/RECORD,,
+ragtime_cli-0.2.4.dist-info/METADATA,sha256=VtuTNejyKDZqNrVuC5tJGNHWDHVrIY-2Pk1-k0NlwWY,8383
+ragtime_cli-0.2.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ragtime_cli-0.2.4.dist-info/entry_points.txt,sha256=cWLbeyMxZNbew-THS3bHXTpCRXt1EaUy5QUOXGXLjl4,75
+ragtime_cli-0.2.4.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+ragtime_cli-0.2.4.dist-info/RECORD,,

src/cli.py

@@ -166,7 +166,7 @@ def get_remote_branches_with_ragtime(path: Path) -> list[str]:
 
 
 @click.group()
-@click.version_option(version="0.2.3")
+@click.version_option(version="0.2.4")
 def main():
     """Ragtime - semantic search over code and documentation."""
     pass
@@ -1175,6 +1175,586 @@ def daemon_status(path: Path):
         pid_file.unlink()
 
 
+# ============================================================================
+# Debug Commands
+# ============================================================================
+
+
+@main.group()
+def debug():
+    """Debug and verify the vector index."""
+    pass
+
+
+@debug.command("search")
+@click.argument("query")
+@click.option("--path", type=click.Path(exists=True, path_type=Path), default=".")
+@click.option("--limit", "-l", default=5, help="Max results")
+@click.option("--show-vectors", is_flag=True, help="Show vector statistics")
+def debug_search(query: str, path: Path, limit: int, show_vectors: bool):
+    """Debug a search query - show scores and ranking details."""
+    path = Path(path).resolve()
+    db = get_db(path)
+
+    results = db.search(query=query, limit=limit)
+
+    if not results:
+        click.echo("No results found.")
+        return
+
+    click.echo(f"\nQuery: \"{query}\"")
+    click.echo(f"{'─' * 60}")
+
+    for i, result in enumerate(results, 1):
+        meta = result["metadata"]
+        distance = result["distance"]
+        similarity = 1 - distance if distance else None
+
+        click.echo(f"\n[{i}] {meta.get('file', 'unknown')}")
+        click.echo(f"    Distance: {distance:.4f}")
+        click.echo(f"    Similarity: {similarity:.4f} ({similarity * 100:.1f}%)")
+        click.echo(f"    Namespace: {meta.get('namespace', '-')}")
+        click.echo(f"    Type: {meta.get('type', '-')}")
+
+        # Show content preview
+        preview = result["content"][:100].replace("\n", " ")
+        click.echo(f"    Preview: {preview}...")
+
+    if show_vectors:
+        click.echo(f"\n{'─' * 60}")
+        click.echo("Vector Statistics:")
+        click.echo(f"  Total indexed: {db.collection.count()}")
+        click.echo(f"  Embedding model: all-MiniLM-L6-v2 (ChromaDB default)")
+        click.echo(f"  Vector dimensions: 384")
+        click.echo(f"  Distance metric: cosine")
+
+
+@debug.command("similar")
+@click.argument("file_path", type=click.Path(exists=True))
+@click.option("--path", type=click.Path(exists=True, path_type=Path), default=".")
+@click.option("--limit", "-l", default=5, help="Max similar docs")
+def debug_similar(file_path: str, path: Path, limit: int):
+    """Find documents similar to a given file."""
+    path = Path(path).resolve()
+    db = get_db(path)
+
+    # Read the file content
+    try:
+        content = Path(file_path).read_text()
+    except Exception as e:
+        click.echo(f"✗ Could not read file: {e}", err=True)
+        return
+
+    # Use the content as the query
+    results = db.search(query=content, limit=limit + 1)  # +1 to exclude self
+
+    click.echo(f"\nDocuments similar to: {file_path}")
+    click.echo(f"{'─' * 60}")
+
+    shown = 0
+    for result in results:
+        # Skip the file itself
+        if result["metadata"].get("file", "").endswith(file_path):
+            continue
+
+        shown += 1
+        if shown > limit:
+            break
+
+        meta = result["metadata"]
+        distance = result["distance"]
+        similarity = 1 - distance if distance else None
+
+        click.echo(f"\n[{shown}] {meta.get('file', 'unknown')}")
+        click.echo(f"    Similarity: {similarity:.4f} ({similarity * 100:.1f}%)")
+
+        preview = result["content"][:100].replace("\n", " ")
+        click.echo(f"    Preview: {preview}...")
+
+
+@debug.command("stats")
+@click.option("--path", type=click.Path(exists=True, path_type=Path), default=".")
+@click.option("--by-namespace", is_flag=True, help="Show counts by namespace")
+@click.option("--by-type", is_flag=True, help="Show counts by type")
+def debug_stats(path: Path, by_namespace: bool, by_type: bool):
+    """Show detailed index statistics."""
+    path = Path(path).resolve()
+    db = get_db(path)
+
+    total = db.collection.count()
+    click.echo(f"\nIndex Statistics")
+    click.echo(f"{'─' * 40}")
+    click.echo(f"Total documents: {total}")
+
+    if total == 0:
+        click.echo("\nIndex is empty. Run 'ragtime index' first.")
+        return
+
+    # Get all documents for analysis
+    all_docs = db.collection.get()
+
+    if by_namespace or (not by_namespace and not by_type):
+        namespaces = {}
+        for meta in all_docs["metadatas"]:
+            ns = meta.get("namespace", "unknown")
+            namespaces[ns] = namespaces.get(ns, 0) + 1
+
+        click.echo(f"\nBy Namespace:")
+        for ns, count in sorted(namespaces.items(), key=lambda x: -x[1]):
+            pct = count / total * 100
+            click.echo(f"  {ns}: {count} ({pct:.1f}%)")
+
+    if by_type or (not by_namespace and not by_type):
+        types = {}
+        for meta in all_docs["metadatas"]:
+            t = meta.get("type", "unknown")
+            types[t] = types.get(t, 0) + 1
+
+        click.echo(f"\nBy Type:")
+        for t, count in sorted(types.items(), key=lambda x: -x[1]):
+            pct = count / total * 100
+            click.echo(f"  {t}: {count} ({pct:.1f}%)")
+
+
+@debug.command("verify")
+@click.option("--path", type=click.Path(exists=True, path_type=Path), default=".")
+def debug_verify(path: Path):
+    """Verify index integrity with test queries."""
+    path = Path(path).resolve()
+    db = get_db(path)
+
+    total = db.collection.count()
+    if total == 0:
+        click.echo("✗ Index is empty. Run 'ragtime index' first.")
+        return
+
+    click.echo(f"\nVerifying index ({total} documents)...")
+    click.echo(f"{'─' * 40}")
+
+    issues = []
+
+    # Test 1: Basic search works
+    click.echo("\n1. Testing basic search...")
+    try:
+        results = db.search("test", limit=1)
+        if results:
+            click.echo("   ✓ Search returns results")
+        else:
+            click.echo("   ⚠ Search returned no results (might be ok if no relevant docs)")
+    except Exception as e:
+        click.echo(f"   ✗ Search failed: {e}")
+        issues.append("Basic search failed")
+
+    # Test 2: Check for documents with missing metadata
+    click.echo("\n2. Checking metadata integrity...")
+    all_docs = db.collection.get()
+    missing_namespace = 0
+    missing_type = 0
+
+    for meta in all_docs["metadatas"]:
+        if not meta.get("namespace"):
+            missing_namespace += 1
+        if not meta.get("type"):
+            missing_type += 1
+
+    if missing_namespace:
+        click.echo(f"   ⚠ {missing_namespace} docs missing namespace")
+    else:
+        click.echo("   ✓ All docs have namespace")
+
+    if missing_type:
+        click.echo(f"   ⚠ {missing_type} docs missing type")
+    else:
+        click.echo("   ✓ All docs have type")
+
+    # Test 3: Check for duplicate IDs
+    click.echo("\n3. Checking for duplicates...")
+    ids = all_docs["ids"]
+    unique_ids = set(ids)
+    if len(ids) != len(unique_ids):
+        dup_count = len(ids) - len(unique_ids)
+        click.echo(f"   ✗ {dup_count} duplicate IDs found")
+        issues.append("Duplicate IDs")
+    else:
+        click.echo("   ✓ No duplicate IDs")
+
+    # Test 4: Similarity sanity check
+    click.echo("\n4. Testing similarity consistency...")
+    if total >= 2:
+        # Pick first doc and find similar
+        first_content = all_docs["documents"][0]
+        results = db.search(first_content[:500], limit=2)
+        if results and len(results) >= 1:
+            top_similarity = 1 - results[0]["distance"]
+            if top_similarity > 0.9:
+                click.echo(f"   ✓ Self-similarity check passed ({top_similarity:.2f})")
+            else:
+                click.echo(f"   ⚠ Self-similarity lower than expected ({top_similarity:.2f})")
+        else:
+            click.echo("   ⚠ Could not perform similarity check")
+    else:
+        click.echo("   - Skipped (need at least 2 docs)")
+
+    # Summary
+    click.echo(f"\n{'─' * 40}")
+    if issues:
+        click.echo(f"⚠ Found {len(issues)} issues:")
+        for issue in issues:
+            click.echo(f"  - {issue}")
+    else:
+        click.echo("✓ Index verification passed")
+
+
+# ============================================================================
+# Documentation Generation
+# ============================================================================
+
+
+@main.command()
+@click.argument("code_path", type=click.Path(exists=True, path_type=Path))
+@click.option("--output", "-o", type=click.Path(path_type=Path), default="docs/api",
+              help="Output directory for docs")
+@click.option("--stubs", is_flag=True, help="Generate stub docs with TODOs (no AI)")
+@click.option("--language", "-l", multiple=True,
+              help="Languages to document (python, typescript, javascript)")
+@click.option("--include-private", is_flag=True, help="Include private methods (_name)")
+def generate(code_path: Path, output: Path, stubs: bool, language: tuple, include_private: bool):
+    """Generate documentation from code.
+
+    Creates markdown documentation from code structure.
+
+    Examples:
+        ragtime generate src/ --stubs           # Create stub docs
+        ragtime generate src/ -o docs/api       # Specify output
+        ragtime generate src/ -l python         # Python only
+    """
+    import ast
+    import re as re_module
+
+    code_path = Path(code_path).resolve()
+    output = Path(output)
+
+    if not stubs:
+        click.echo("Use --stubs for stub generation, or /generate-docs for AI-powered docs")
+        click.echo("\nExample: ragtime generate src/ --stubs")
+        return
+
+    # Determine languages
+    if language:
+        languages = list(language)
+    else:
+        languages = ["python", "typescript", "javascript"]
+
+    # Map extensions to languages
+    ext_map = {
+        "python": [".py"],
+        "typescript": [".ts", ".tsx"],
+        "javascript": [".js", ".jsx"],
+    }
+
+    extensions = []
+    for lang in languages:
+        extensions.extend(ext_map.get(lang, []))
+
+    # Find code files
+    code_files = []
+    for ext in extensions:
+        code_files.extend(code_path.rglob(f"*{ext}"))
+
+    # Filter out common exclusions
+    exclude_patterns = ["__pycache__", "node_modules", ".venv", "venv", "dist", "build"]
+    code_files = [
+        f for f in code_files
+        if not any(ex in str(f) for ex in exclude_patterns)
+    ]
+
+    if not code_files:
+        click.echo(f"No code files found in {code_path}")
+        return
+
+    click.echo(f"Found {len(code_files)} code files")
+    click.echo(f"Output: {output}/")
+    click.echo(f"{'─' * 50}")
+
+    output.mkdir(parents=True, exist_ok=True)
+    generated = 0
+
+    for code_file in code_files:
+        try:
+            content = code_file.read_text()
+        except Exception:
+            continue
+
+        relative = code_file.relative_to(code_path)
+        doc_path = output / relative.with_suffix(".md")
+
+        # Parse based on extension
+        if code_file.suffix == ".py":
+            doc_content = generate_python_stub(code_file, content, include_private)
+        elif code_file.suffix in [".ts", ".tsx", ".js", ".jsx"]:
+            doc_content = generate_typescript_stub(code_file, content, include_private)
+        else:
+            continue
+
+        if doc_content:
+            doc_path.parent.mkdir(parents=True, exist_ok=True)
+            doc_path.write_text(doc_content)
+            try:
+                doc_display = doc_path.relative_to(Path.cwd())
+            except ValueError:
+                doc_display = doc_path
+            click.echo(f"  ✓ {relative} → {doc_display}")
+            generated += 1
+
+    click.echo(f"\n{'─' * 50}")
+    click.echo(f"✓ Generated {generated} documentation stubs")
+    click.echo(f"\nNext steps:")
+    click.echo(f"  1. Fill in the TODO placeholders")
+    click.echo(f"  2. Or use /generate-docs for AI-generated content")
+    click.echo(f"  3. Run 'ragtime index' to make searchable")
+
+
+def generate_python_stub(file_path: Path, content: str, include_private: bool) -> str:
+    """Generate markdown stub from Python code."""
+    import ast
+
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return ""
+
+    lines = []
+    lines.append(f"# {file_path.stem}")
+    lines.append(f"\n> **File:** `{file_path}`")
+    lines.append("\n## Overview\n")
+    lines.append("TODO: Describe what this module does.\n")
+
+    # Get module docstring
+    if ast.get_docstring(tree):
+        lines.append(f"> {ast.get_docstring(tree)}\n")
+
+    classes = []
+    functions = []
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef):
+            if not include_private and node.name.startswith("_"):
+                continue
+            classes.append(node)
+        elif isinstance(node, ast.FunctionDef) or isinstance(node, ast.AsyncFunctionDef):
+            if not include_private and node.name.startswith("_"):
+                continue
+            functions.append(node)
+
+    # Document classes
+    if classes:
+        lines.append("---\n")
+        lines.append("## Classes\n")
+
+        for cls in classes:
+            lines.append(f"### `{cls.name}`\n")
+            if ast.get_docstring(cls):
+                lines.append(f"{ast.get_docstring(cls)}\n")
+            else:
+                lines.append("TODO: Describe this class.\n")
+
+            # Find __init__ and methods
+            methods = []
+            init_node = None
+            for item in cls.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    if item.name == "__init__":
+                        init_node = item
+                    elif not item.name.startswith("_") or include_private:
+                        methods.append(item)
+
+            # Constructor
+            if init_node:
+                lines.append("#### Constructor\n")
+                sig = get_function_signature(init_node)
+                lines.append(f"```python\n{sig}\n```\n")
+                params = get_function_params(init_node)
+                if params:
+                    lines.append("| Parameter | Type | Default | Description |")
+                    lines.append("|-----------|------|---------|-------------|")
+                    for p in params:
+                        lines.append(f"| `{p['name']}` | `{p['type']}` | {p['default']} | TODO |")
+                    lines.append("")
+
+            # Methods
+            if methods:
+                lines.append("#### Methods\n")
+                for method in methods:
+                    async_prefix = "async " if isinstance(method, ast.AsyncFunctionDef) else ""
+                    ret = get_return_annotation(method)
+                    lines.append(f"##### `{async_prefix}{method.name}(...) -> {ret}`\n")
+                    if ast.get_docstring(method):
+                        lines.append(f"{ast.get_docstring(method)}\n")
+                    else:
+                        lines.append("TODO: Describe this method.\n")
+
+    # Document functions
+    if functions:
+        lines.append("---\n")
+        lines.append("## Functions\n")
+
+        for func in functions:
+            async_prefix = "async " if isinstance(func, ast.AsyncFunctionDef) else ""
+            ret = get_return_annotation(func)
+            lines.append(f"### `{async_prefix}{func.name}(...) -> {ret}`\n")
+            if ast.get_docstring(func):
+                lines.append(f"{ast.get_docstring(func)}\n")
+            else:
+                lines.append("TODO: Describe this function.\n")
+
+            params = get_function_params(func)
+            if params:
+                lines.append("**Parameters:**\n")
+                for p in params:
+                    lines.append(f"- `{p['name']}` (`{p['type']}`): TODO")
+                lines.append("")
+
+            lines.append(f"**Returns:** `{ret}` - TODO\n")
+
+    return "\n".join(lines)
+
+
+def get_function_signature(node) -> str:
+    """Get function signature string."""
+    import ast
+
+    args = []
+    for arg in node.args.args:
+        if arg.arg == "self":
+            continue
+        type_hint = ""
+        if arg.annotation:
+            type_hint = f": {ast.unparse(arg.annotation)}"
+        args.append(f"{arg.arg}{type_hint}")
+
+    return f"def {node.name}({', '.join(args)})"
+
+
+def get_function_params(node) -> list:
+    """Get function parameters with types and defaults."""
+    import ast
+
+    params = []
+    defaults = node.args.defaults
+    num_defaults = len(defaults)
+    num_args = len(node.args.args)
+
+    for i, arg in enumerate(node.args.args):
+        if arg.arg in ("self", "cls"):
+            continue
+
+        type_hint = "Any"
+        if arg.annotation:
+            try:
+                type_hint = ast.unparse(arg.annotation)
+            except:
+                type_hint = "Any"
+
+        default = "-"
+        default_idx = i - (num_args - num_defaults)
+        if default_idx >= 0 and default_idx < len(defaults):
+            try:
+                default = f"`{ast.unparse(defaults[default_idx])}`"
+            except:
+                default = "..."
+
+        params.append({
+            "name": arg.arg,
+            "type": type_hint,
+            "default": default,
+        })
+
+    return params
+
+
+def get_return_annotation(node) -> str:
+    """Get return type annotation."""
+    import ast
+
+    if node.returns:
+        try:
+            return ast.unparse(node.returns)
+        except:
+            return "Any"
+    return "None"
+
+
+def generate_typescript_stub(file_path: Path, content: str, include_private: bool) -> str:
+    """Generate markdown stub from TypeScript/JavaScript code."""
+    import re as re_module
+
+    lines = []
+    lines.append(f"# {file_path.stem}")
+    lines.append(f"\n> **File:** `{file_path}`")
+    lines.append("\n## Overview\n")
+    lines.append("TODO: Describe what this module does.\n")
+
+    # Find exports using regex
+    class_pattern = r'export\s+(?:default\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?'
+    func_pattern = r'export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)(?:\s*:\s*([^\{]+))?'
+    const_pattern = r'export\s+const\s+(\w+)\s*(?::\s*([^=]+))?\s*='
+    interface_pattern = r'export\s+(?:default\s+)?interface\s+(\w+)'
+    type_pattern = r'export\s+type\s+(\w+)'
+
+    classes = re_module.findall(class_pattern, content)
+    functions = re_module.findall(func_pattern, content)
+    consts = re_module.findall(const_pattern, content)
+    interfaces = re_module.findall(interface_pattern, content)
+    types = re_module.findall(type_pattern, content)
+
+    # Interfaces and Types
+    if interfaces or types:
+        lines.append("---\n")
+        lines.append("## Types\n")
+        for iface in interfaces:
+            lines.append(f"### `interface {iface}`\n")
+            lines.append("TODO: Describe this interface.\n")
+        for t in types:
+            lines.append(f"### `type {t}`\n")
+            lines.append("TODO: Describe this type.\n")
+
+    # Classes
+    if classes:
+        lines.append("---\n")
+        lines.append("## Classes\n")
+        for cls_name, extends in classes:
+            lines.append(f"### `{cls_name}`")
+            if extends:
+                lines.append(f" extends `{extends}`")
+            lines.append("\n")
+            lines.append("TODO: Describe this class.\n")
+
+    # Functions
+    if functions:
+        lines.append("---\n")
+        lines.append("## Functions\n")
+        for func_name, params, return_type in functions:
+            ret = return_type.strip() if return_type else "void"
+            lines.append(f"### `{func_name}({params}) => {ret}`\n")
+            lines.append("TODO: Describe this function.\n")
+
+    # Constants
+    if consts:
+        lines.append("---\n")
+        lines.append("## Constants\n")
+        lines.append("| Name | Type | Description |")
+        lines.append("|------|------|-------------|")
+        for const_name, const_type in consts:
+            t = const_type.strip() if const_type else "unknown"
+            lines.append(f"| `{const_name}` | `{t}` | TODO |")
+        lines.append("")
+
+    if len(lines) <= 5:  # Only header
+        return ""
+
+    return "\n".join(lines)
+
+
 @main.command()
 @click.argument("docs_path", type=click.Path(exists=True, path_type=Path), default="docs")
 @click.option("--path", type=click.Path(exists=True, path_type=Path), default=".")
@@ -1370,7 +1950,7 @@ def update(check: bool):
     from urllib.request import urlopen
     from urllib.error import URLError
 
-    current = "0.2.3"
+    current = "0.2.4"
 
     click.echo(f"Current version: {current}")
     click.echo("Checking PyPI for updates...")

src/commands/generate-docs.md

@@ -0,0 +1,325 @@
+---
+description: Generate documentation from code with AI analysis
+allowed-arguments: path to code (e.g., /generate-docs src/)
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion, Glob, Grep
+---
+
+# Generate Docs
+
+Analyze code and generate comprehensive documentation.
+
+**Usage:**
+- `/generate-docs src/` - Generate docs for src folder
+- `/generate-docs src/auth/` - Document specific module
+- `/generate-docs` - Interactive mode
+
+## Overview
+
+You (Claude) will:
+1. Read and understand the code
+2. Write clear, helpful documentation
+3. Include examples and usage notes
+4. Output as markdown files
+
+This is the AI-powered version. For quick stubs without AI, use `ragtime generate --stubs`.
+
+## Step 1: Get the Code Path
+
+**If `$ARGUMENTS` provided:**
+- Use it as the code path
+
+**If no arguments:**
+- Ask: "What code should I document? (e.g., src/, src/auth/, specific file)"
+
+## Step 2: Discover Code Files
+
+```bash
+# Find code files
+find {path} -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" \) \
+  -not -path "*/__pycache__/*" \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.venv/*"
+```
+
+If many files found, ask:
+```
+Found {count} files. Options:
+
+1. Document all
+2. Document specific folder
+3. Document specific files (I'll list them)
+```
+
+## Step 3: Choose Output Location
+
+```
+Where should I save the documentation?
+
+1. **docs/api/** - API reference docs
+2. **docs/code/** - Code documentation
+3. **.ragtime/app/** - As searchable memories
+4. **Custom path**
+```
+
+## Step 4: Analyze and Document Each File
+
+For each code file:
+
+1. **Read the full file**
+2. **Understand what it does** - purpose, patterns, relationships
+3. **Write documentation** that explains:
+   - What the module/class/function does
+   - Why it exists (context)
+   - How to use it (examples)
+   - Important details (edge cases, requirements)
+
+### Documentation Quality Guidelines
+
+**Good documentation answers:**
+- What does this do?
+- Why would I use it?
+- How do I use it?
+- What should I watch out for?
+
+**Avoid:**
+- Just restating the function name ("getUserById gets a user by ID")
+- Obvious descriptions
+- Missing the "why"
+
+### Documentation Template
+
+```markdown
+# {Module Name}
+
+> **File:** `{path}`
+
+## Overview
+
+{2-3 sentences explaining what this module does and why it exists}
+
+## Quick Start
+
+\`\`\`{language}
+{Simple usage example}
+\`\`\`
+
+---
+
+## API Reference
+
+### `ClassName`
+
+{Description of the class - what it represents, when to use it}
+
+#### Constructor
+
+\`\`\`{language}
+{constructor signature}
+\`\`\`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `param` | `Type` | {Actual description} |
+
+#### Methods
+
+##### `methodName(params) -> ReturnType`
+
+{What this method does, not just restating the name}
+
+**Parameters:**
+- `param` (`Type`): {Description}
+
+**Returns:** {What it returns and when}
+
+**Example:**
+\`\`\`{language}
+{Practical example}
+\`\`\`
+
+**Notes:**
+- {Important edge cases}
+- {Performance considerations}
+- {Related methods}
+
+---
+
+## Functions
+
+### `functionName(params) -> ReturnType`
+
+{Description}
+
+{Parameters, returns, example - same format as methods}
+
+---
+
+## Constants / Configuration
+
+| Name | Value | Description |
+|------|-------|-------------|
+| `CONSTANT` | `value` | {What it's for} |
+
+---
+
+## See Also
+
+- [{Related Module}]({link})
+- [{External Docs}]({link})
+```
+
+## Step 5: Add Frontmatter (if .ragtime/ output)
+
+```yaml
+---
+namespace: app
+type: architecture
+component: {from path}
+source: generate-docs
+confidence: medium
+confidence_reason: ai-generated
+---
+```
+
+## Step 6: Write and Report
+
+```
+Generating documentation...
+
+  ✓ src/auth/jwt.py → docs/api/auth/jwt.md
+    - JWTManager class
+    - create_token, validate_token functions
+
+  ✓ src/auth/sessions.py → docs/api/auth/sessions.md
+    - SessionStore class
+    - Redis integration details
+
+  ✓ src/db/models.py → docs/api/db/models.md
+    - User, Claim, Shift models
+    - Relationships documented
+```
+
+## Step 7: Summary
+
+```
+───────────────────────────────────────────
+✅ DOCUMENTATION COMPLETE
+───────────────────────────────────────────
+
+Generated {count} documentation files
+
+Coverage:
+  - {n} classes documented
+  - {n} functions documented
+  - {n} with examples
+
+Output: {output_path}/
+
+Next steps:
+  - Review the generated docs
+  - Add any missing context
+  - Run 'ragtime index' to make searchable
+```
+
+## Best Practices
+
+When writing docs:
+
+1. **Start with the "why"** - Don't just describe what, explain purpose
+2. **Include real examples** - Show actual usage, not abstract patterns
+3. **Document edge cases** - What happens with null? Empty arrays?
+4. **Link related concepts** - Help readers navigate
+5. **Keep it scannable** - Use headers, tables, code blocks
+
+## Example
+
+For this code:
+
+```python
+class RateLimiter:
+    """Rate limiting using token bucket algorithm."""
+
+    def __init__(self, requests_per_minute: int = 60):
+        self.rpm = requests_per_minute
+        self.tokens = requests_per_minute
+        self.last_update = time.time()
+
+    def allow(self, cost: int = 1) -> bool:
+        """Check if request is allowed, consuming tokens if so."""
+        self._refill()
+        if self.tokens >= cost:
+            self.tokens -= cost
+            return True
+        return False
+```
+
+Generate:
+
+```markdown
+# RateLimiter
+
+> **File:** `src/middleware/rate_limit.py`
+
+## Overview
+
+Implements rate limiting using the token bucket algorithm. Use this to protect
+APIs from abuse by limiting how many requests a client can make per minute.
+
+## Quick Start
+
+\`\`\`python
+limiter = RateLimiter(requests_per_minute=100)
+
+@app.before_request
+def check_rate_limit():
+    if not limiter.allow():
+        return {"error": "Rate limit exceeded"}, 429
+\`\`\`
+
+---
+
+## API Reference
+
+### `RateLimiter`
+
+A token bucket rate limiter. Tokens refill continuously over time, allowing
+for burst traffic while maintaining an average rate limit.
+
+#### Constructor
+
+\`\`\`python
+RateLimiter(requests_per_minute: int = 60)
+\`\`\`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `requests_per_minute` | `int` | `60` | Maximum requests allowed per minute |
+
+#### Methods
+
+##### `allow(cost: int = 1) -> bool`
+
+Check if a request should be allowed. If allowed, consumes tokens from the bucket.
+
+**Parameters:**
+- `cost` (`int`): Number of tokens this request costs. Use higher values for
+  expensive operations.
+
+**Returns:** `True` if the request is allowed, `False` if rate limited.
+
+**Example:**
+\`\`\`python
+# Normal request
+if limiter.allow():
+    process_request()
+
+# Expensive operation (costs 5 tokens)
+if limiter.allow(cost=5):
+    run_expensive_query()
+\`\`\`
+
+**Notes:**
+- Tokens refill continuously, not all at once
+- Thread-safe for single-process use
+- For distributed systems, use Redis-backed rate limiting instead
+```