Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

Add PyPI packaging, README, LICENSE, user guide, and publish workflow

RaghavChamadiyaa4a0185b53c8
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 000000000..36e66288e
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+ push:
+ tags: ['v*']
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ name: Build distribution
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+
+ - name: Install build tools
+ run: pip install build
+
+ - name: Build sdist and wheel
+ run: python -m build
+
+ - name: Upload dist artifacts
+ uses: actions/upload-artifact@v4
+ with:
+ name: dist
+ path: dist/
+
+ publish:
+ name: Publish to PyPI
+ needs: build
+ runs-on: ubuntu-latest
+ environment: pypi
+ permissions:
+ id-token: write # trusted publishing (OIDC)
+
+ steps:
+ - name: Download dist artifacts
+ uses: actions/download-artifact@v4
+ with:
+ name: dist
+ path: dist/
+
+ - name: Publish to PyPI
+ uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/.gitignore b/.gitignore
index 6ee77acce..0f47b4daa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -114,3 +114,6 @@ ehthumbs.db
# repowise API keys (local)
.repowise/.env
+
+# Private release notes
+docs/PYPI_RELEASE.md
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 000000000..a5f1123c6
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,17 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2024-2026 Raghav Chamadiya and contributors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 000000000..d472033af
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,2 @@
+recursive-include packages/core/src/repowise/core/ingestion/queries *.scm
+recursive-include packages/core/src/repowise/core/generation/templates *.j2
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..fa99d5ba2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+# repowise
+
+**Codebase intelligence for developers and AI.**
+
+repowise generates and maintains a structured, hierarchical wiki for any codebase.
+It keeps documentation accurate as code changes and exposes everything through an
+MCP server so AI coding assistants can query it in real time.
+
+[![PyPI version](https://img.shields.io/pypi/v/repowise.svg)](https://pypi.org/project/repowise/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://pypi.org/project/repowise/)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-purple.svg)](https://github.com/RaghavChamadiya/repowise/blob/main/LICENSE)
+
+## Features
+
+- **Automatic documentation** — generates module, file, and symbol-level docs from source code
+- **Git intelligence** — tracks churn hotspots, ownership, bus factor, and change patterns
+- **Dead code detection** — finds confirmed unused exports, functions, and types
+- **Decision intelligence** — captures *why* code is structured the way it is
+- **MCP server** — 8 tools for AI assistants (Claude Code, Cursor, Windsurf, etc.)
+- **REST API + Web UI** — browse the wiki, search, and explore architecture diagrams
+- **Codebase chat** — ask questions about your codebase in natural language
+- **Multi-language** — Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Kotlin, Ruby
+
+## Install
+
+```bash
+pip install repowise
+```
+
+LLM providers are optional — install only the one you need:
+
+```bash
+pip install "repowise[anthropic]" # Claude models
+pip install "repowise[openai]" # GPT models
+pip install "repowise[gemini]" # Gemini models
+pip install "repowise[litellm]" # 100+ providers via LiteLLM
+pip install "repowise[all]" # Everything
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY="sk-ant-..." # or OPENAI_API_KEY, GEMINI_API_KEY
+
+# Generate documentation for your codebase
+cd /path/to/your-repo
+repowise init
+
+# Keep docs in sync after code changes
+repowise update
+
+# Start the MCP server for AI assistants
+repowise mcp
+
+# Browse the wiki in your browser
+repowise serve
+```
+
+## How It Works
+
+1. **Ingestion** — parses every file using tree-sitter, extracts symbols, imports, and builds a dependency graph
+2. **Analysis** — computes git signals (churn, ownership, recency), detects dead code, identifies architectural decisions
+3. **Generation** — sends structured prompts to an LLM to produce wiki pages at every level of the hierarchy
+4. **Persistence** — stores everything in SQLite (or PostgreSQL) with full-text and vector search
+5. **Serving** — exposes the wiki through REST API, MCP server, and web UI
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `repowise init` | Generate full wiki documentation for a codebase |
+| `repowise update` | Incrementally sync wiki after code changes |
+| `repowise watch` | Auto-update wiki on file saves |
+| `repowise search` | Full-text, semantic, or symbol search |
+| `repowise mcp` | Start MCP server for AI editors |
+| `repowise serve` | Start web UI server |
+| `repowise dead-code` | Detect unused/unreachable code |
+| `repowise decision` | Manage architectural decision records |
+| `repowise generate-claude-md` | Generate CLAUDE.md for editor context |
+| `repowise export` | Export pages to markdown/html/json |
+| `repowise reindex` | Rebuild vector search index |
+| `repowise status` | Show sync state and page counts |
+| `repowise doctor` | Run health checks on wiki setup |
+
+## MCP Tools for AI Editors
+
+Once connected via `repowise mcp`, your AI editor gets 8 tools:
+
+| Tool | What it does |
+|------|-------------|
+| `get_overview` | Architecture summary, key modules, entry points, git health |
+| `get_context` | Rich context for files/symbols — docs, ownership, decisions, freshness |
+| `get_risk` | Modification risk — hotspot score, dependents, bus factor, trend |
+| `get_why` | Why code is structured this way — decisions, git archaeology |
+| `search_codebase` | Semantic search with git freshness boosting |
+| `get_dependency_path` | How two modules connect through the dependency graph |
+| `get_dead_code` | Tiered dead code report grouped by confidence |
+| `get_architecture_diagram` | Mermaid diagram with optional churn heat map |
+
+Works with Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible editor.
+
+## Web UI
+
+repowise includes a full web dashboard (Next.js + React + D3.js) with:
+
+- **Wiki browser** — AI-generated docs with syntax highlighting, Mermaid diagrams, and git history sidebar
+- **Dependency graph** — interactive force-directed visualization (handles 2000+ nodes)
+- **Codebase chat** — ask questions about your code in natural language
+- **Search** — full-text and semantic search with global command palette (Ctrl+K)
+- **Symbol index** — searchable table of every function, class, and method
+- **Coverage dashboard** — freshness breakdown with one-click regeneration
+- **Ownership view** — contributor attribution and bus factor risk detection
+- **Hotspots** — ranked high-churn files with commit history
+- **Dead code finder** — unused code with confidence scores and bulk actions
+- **Decision tracker** — architectural decisions with health monitoring
+
+See the [User Guide](https://github.com/RaghavChamadiya/repowise/blob/main/docs/USER_GUIDE.md#web-ui) for setup instructions.
+
+## Requirements
+
+- Python 3.11+
+- Git (for repository analysis)
+- An LLM API key (for documentation generation — not needed for analysis-only mode)
+- Node.js 20+ (only if running the web UI frontend)
+
+## Documentation
+
+- [User Guide](https://github.com/RaghavChamadiya/repowise/blob/main/docs/USER_GUIDE.md) — complete CLI reference, web UI guide, workflows, and troubleshooting
+- [Architecture Guide](https://github.com/RaghavChamadiya/repowise/blob/main/docs/ARCHITECTURE.md) — how the system is built and why each piece exists
+- [Core Library](https://github.com/RaghavChamadiya/repowise/blob/main/packages/core/README.md) — ingestion, generation, persistence, providers
+- [CLI Package](https://github.com/RaghavChamadiya/repowise/blob/main/packages/cli/README.md) — all commands with every flag documented
+- [Server & MCP Tools](https://github.com/RaghavChamadiya/repowise/blob/main/packages/server/README.md) — REST API endpoints, MCP tools, webhooks, scheduler
+- [Web Frontend](https://github.com/RaghavChamadiya/repowise/blob/main/packages/web/README.md) — every page and component
+
+## Contributing
+
+Contributions are welcome. Please read the [Architecture Guide](https://github.com/RaghavChamadiya/repowise/blob/main/docs/ARCHITECTURE.md) before submitting PRs.
+
+```bash
+# Development setup
+git clone https://github.com/RaghavChamadiya/repowise.git
+cd repowise
+uv sync # Python dependencies
+npm install # Web frontend dependencies
+pytest # Run tests
+ruff check packages/ tests/ # Lint
+```
+
+## License
+
+AGPL-3.0 — see [LICENSE](https://github.com/RaghavChamadiya/repowise/blob/main/LICENSE) for details.
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
new file mode 100644
index 000000000..d58a29a3c
--- /dev/null
+++ b/docs/USER_GUIDE.md
@@ -0,0 +1,777 @@
+# Repowise User Guide
+
+Everything you need to know to install, use, and get the most out of repowise.
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Getting Started](#getting-started)
+3. [CLI Command Reference](#cli-command-reference)
+ - [init](#repowise-init)
+ - [update](#repowise-update)
+ - [watch](#repowise-watch)
+ - [search](#repowise-search)
+ - [mcp](#repowise-mcp)
+ - [serve](#repowise-serve)
+ - [dead-code](#repowise-dead-code)
+ - [decision](#repowise-decision)
+ - [generate-claude-md](#repowise-generate-claude-md)
+ - [export](#repowise-export)
+ - [reindex](#repowise-reindex)
+ - [status](#repowise-status)
+ - [doctor](#repowise-doctor)
+4. [Web UI](#web-ui)
+5. [MCP Integration with AI Editors](#mcp-integration-with-ai-editors)
+6. [Environment Variables](#environment-variables)
+7. [Common Workflows](#common-workflows)
+8. [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install repowise
+```
+
+This installs the core engine, CLI, server, and MCP tools. No LLM provider SDK is included by default — install only the one you need:
+
+```bash
+pip install "repowise[anthropic]" # Claude (Anthropic)
+pip install "repowise[openai]" # GPT (OpenAI)
+pip install "repowise[gemini]" # Gemini (Google)
+pip install "repowise[litellm]" # 100+ providers via LiteLLM (Together, Groq, Azure, Bedrock, etc.)
+pip install "repowise[all]" # All LLM providers + PostgreSQL support
+```
+
+If you plan to use PostgreSQL instead of the default SQLite:
+
+```bash
+pip install "repowise[postgres]"
+```
+
+### Requirements
+
+- Python 3.11 or later
+- Git (repowise analyzes your repository's git history)
+- An LLM API key (for documentation generation — not needed for analysis-only mode)
+
+### Verify Installation
+
+```bash
+repowise --version
+repowise --help
+```
+
+---
+
+## Getting Started
+
+### 1. Set your API key
+
+```bash
+# Pick one:
+export ANTHROPIC_API_KEY="sk-ant-..."
+export OPENAI_API_KEY="sk-..."
+export GEMINI_API_KEY="..."
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:ANTHROPIC_API_KEY = "sk-ant-..."
+```
+
+### 2. Initialize your codebase
+
+```bash
+cd /path/to/your-repo
+repowise init
+```
+
+In interactive mode, repowise asks you to choose:
+
+- **Index-only** — free, no LLM. Parses code, builds dependency graph, indexes git history. Useful for analysis without documentation generation.
+- **Full** — uses your chosen LLM to generate human-readable wiki pages for every file and module.
+- **Advanced** — fine-tune every option (concurrency, exclusions, commit limits, etc.)
+
+A typical first run on a medium codebase (~500 files) takes 5-15 minutes and costs $1-5 depending on the provider.
+
+### 3. Start using the wiki
+
+After init completes, you have several ways to access the generated documentation:
+
+```bash
+repowise search "authentication" # Search from the terminal
+repowise serve # Browse in a web UI at localhost:7337
+repowise mcp # Connect to Claude Code, Cursor, etc.
+```
+
+### What gets created
+
+```
+your-repo/
+├── .repowise/
+│ ├── wiki.db # SQLite database with all pages, symbols, graph, git data
+│ ├── state.json # Sync metadata (last commit, pages, tokens used)
+│ ├── config.yaml # Saved configuration (provider, model, excludes)
+│ ├── .env # Saved API keys (gitignored)
+│ └── lancedb/ # Vector store for semantic search
+└── CLAUDE.md # Auto-generated codebase context for AI editors
+```
+
+---
+
+## CLI Command Reference
+
+### `repowise init`
+
+Generate complete wiki documentation for a codebase. This is the starting point.
+
+```bash
+repowise init [PATH]
+```
+
+**What it does (4 phases):**
+
+1. **Ingestion** — walks every file, parses AST with tree-sitter, builds a dependency graph, indexes git history (churn, hotspots, ownership, bus factor)
+2. **Analysis** — detects dead code, extracts architectural decisions from inline markers, READMEs, and git history
+3. **Generation** — sends structured prompts to the LLM, generates file-level, module-level, and repo-level wiki pages, plus architecture diagrams
+4. **Persistence** — stores everything in `.repowise/wiki.db`, builds search indexes, generates `CLAUDE.md`
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--provider` | LLM provider: `anthropic`, `openai`, `gemini`, `ollama`, `mock`. Auto-detected from env vars if not set. |
+| `--model` | Model name override (e.g., `claude-sonnet-4-6`, `gpt-5.4-nano`) |
+| `--embedder` | Embedder for semantic search: `gemini`, `openai`, `mock`. Auto-detected from env vars. |
+| `--index-only` | Skip LLM generation entirely. Only parse, build graph, and index git. Free. |
+| `--dry-run` | Show generation plan and cost estimate without running anything. |
+| `--test-run` | Generate docs for only the top 10 files (by PageRank) — quick validation. |
+| `--skip-tests` | Exclude test files from documentation generation. |
+| `--skip-infra` | Exclude infrastructure files (Dockerfiles, Makefiles, Terraform, shell scripts). |
+| `--exclude / -x` | Gitignore-style exclusion patterns. Repeatable: `-x vendor/ -x "*.generated.*"` |
+| `--concurrency` | Max concurrent LLM calls (default: 5). Higher = faster but more API pressure. |
+| `--resume` | Resume from the last checkpoint if a previous run was interrupted. |
+| `--force` | Regenerate all pages even if they already exist. |
+| `--commit-limit` | Max commits to analyze per file (default: 500, max: 5000). Saved to config. |
+| `--follow-renames` | Track file renames in git history (slower but more accurate). |
+| `--no-claude-md` | Don't generate `CLAUDE.md` at the end. |
+| `--yes / -y` | Skip cost confirmation prompt (auto-confirms if cost > $2). |
+
+**Examples:**
+
+```bash
+# Interactive mode (asks questions)
+repowise init
+
+# Fully automated
+repowise init --provider anthropic --model claude-sonnet-4-6 --yes
+
+# Just index, no LLM cost
+repowise init --index-only
+
+# Preview what will happen
+repowise init --provider openai --dry-run
+
+# Quick test with 10 files
+repowise init --provider gemini --test-run
+
+# Exclude vendor and generated code
+repowise init -x vendor/ -x "*.gen.go" -x "**/__generated__/**"
+```
+
+---
+
+### `repowise update`
+
+Incrementally update wiki pages for files that changed since the last sync.
+
+```bash
+repowise update [PATH]
+```
+
+Much faster and cheaper than a full `init` — only regenerates pages for changed files and their dependents.
+
+**How it works:**
+
+1. Diffs `HEAD` against the last sync commit (stored in `state.json`)
+2. Re-parses changed files and rebuilds the dependency graph
+3. Determines affected pages (direct changes + dependents via cascade analysis)
+4. Regenerates only those pages
+5. Updates `state.json` and `CLAUDE.md`
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--provider` | Override LLM provider for this run |
+| `--model` | Override model |
+| `--since` | Git ref to diff from (overrides `state.json`). Example: `--since v1.0.0` |
+| `--cascade-budget` | Max pages to regenerate per run (default: 30). Prevents runaway regeneration. |
+| `--dry-run` | Show what would be updated without regenerating. |
+
+**Examples:**
+
+```bash
+# Update after pulling changes
+git pull
+repowise update
+
+# See what changed without regenerating
+repowise update --dry-run
+
+# Update since a specific tag
+repowise update --since v2.0.0
+
+# Limit regeneration scope
+repowise update --cascade-budget 10
+```
+
+---
+
+### `repowise watch`
+
+Watch for file changes and automatically update wiki pages.
+
+```bash
+repowise watch [PATH]
+```
+
+Runs continuously. Uses filesystem events (via watchdog) to detect saves, debounces them, and triggers `repowise update` automatically. Press `Ctrl+C` to stop.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--provider` | LLM provider |
+| `--model` | Model override |
+| `--debounce` | Debounce delay in milliseconds (default: 2000). Collects changes for this long before triggering an update. |
+
+**Example:**
+
+```bash
+# Start watching — wiki syncs as you code
+repowise watch --debounce 3000
+```
+
+---
+
+### `repowise search`
+
+Search wiki pages by keyword, meaning, or symbol name.
+
+```bash
+repowise search QUERY [PATH]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--mode` | Search mode: `fulltext` (default), `semantic`, `symbol` |
+| `--limit` | Max results (default: 10) |
+
+**Search modes:**
+
+- **fulltext** — SQLite FTS. Fast, exact keyword matching.
+- **semantic** — Vector similarity search via LanceDB. Understands meaning ("how does auth work?" finds authentication code even without the word "auth"). Falls back to fulltext if vector store is unavailable.
+- **symbol** — Searches the symbol index (function names, class names, etc.) with fuzzy matching.
+
+**Examples:**
+
+```bash
+# Keyword search
+repowise search "rate limiting"
+
+# Semantic search — understands intent
+repowise search "how are errors handled" --mode semantic
+
+# Find a symbol
+repowise search "AuthService" --mode symbol --limit 20
+```
+
+---
+
+### `repowise mcp`
+
+Start the MCP (Model Context Protocol) server for AI editor integration.
+
+```bash
+repowise mcp [PATH]
+```
+
+This is how you connect repowise to Claude Code, Cursor, Cline, Windsurf, and other MCP-compatible editors.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--transport` | Protocol: `stdio` (default, for editors) or `sse` (for web clients) |
+| `--port` | Port for SSE transport (default: 7338) |
+
+**MCP tools exposed (8 tools):**
+
+| Tool | What it does |
+|------|-------------|
+| `get_overview` | Repository architecture summary, key modules, entry points, git health |
+| `get_context` | Complete context for files/modules/symbols — docs, ownership, decisions, freshness |
+| `get_risk` | Modification risk assessment — hotspot score, dependents, bus factor, trend |
+| `get_why` | Why code is structured the way it is — architectural decisions, git archaeology |
+| `search_codebase` | Semantic search over wiki with git freshness boosting |
+| `get_dependency_path` | Find how two modules connect through the dependency graph |
+| `get_dead_code` | Tiered dead code report grouped by confidence |
+| `get_architecture_diagram` | Mermaid diagram with optional churn heat map |
+
+See [MCP Integration](#mcp-integration-with-ai-editors) for setup instructions.
+
+---
+
+### `repowise serve`
+
+Start a local web server for browsing the wiki in your browser.
+
+```bash
+repowise serve [PATH]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--port` | Port (default: 7337) |
+| `--host` | Host (default: 127.0.0.1) |
+| `--workers` | Uvicorn workers (default: 1) |
+
+Opens a FastAPI server with a REST API. Pair with the web frontend for a full UI experience (see [Web UI](#web-ui)).
+
+---
+
+### `repowise dead-code`
+
+Detect dead and unused code in your codebase.
+
+```bash
+repowise dead-code [PATH]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--min-confidence` | Minimum confidence threshold (default: 0.4) |
+| `--safe-only` | Only show findings marked safe to delete |
+| `--kind` | Filter: `unreachable_file`, `unused_export`, `unused_internal`, `zombie_package` |
+| `--format` | Output: `table` (default), `json`, `md` |
+
+**Examples:**
+
+```bash
+# Show all findings
+repowise dead-code
+
+# Only safe-to-delete items
+repowise dead-code --safe-only --min-confidence 0.8
+
+# JSON output for scripting
+repowise dead-code --format json
+
+# Only unused exports
+repowise dead-code --kind unused_export
+```
+
+---
+
+### `repowise decision`
+
+Manage architectural decision records. Repowise automatically extracts decisions from inline markers (`// DECISION: ...`), READMEs, and git history. You can also add them manually.
+
+**Subcommands:**
+
+```bash
+repowise decision list [PATH] # List decisions
+repowise decision show ID [PATH] # Show full details of a decision
+repowise decision add [PATH] # Interactively add a new decision
+repowise decision confirm ID [PATH] # Confirm a proposed decision (set to active)
+repowise decision dismiss ID [PATH] # Delete a proposed decision
+repowise decision deprecate ID [PATH] # Mark as deprecated
+repowise decision health [PATH] # Decision health dashboard
+```
+
+**List options:**
+
+| Flag | Description |
+|------|-------------|
+| `--status` | Filter: `active`, `proposed`, `deprecated`, `superseded`, `all` |
+| `--source` | Filter: `git_archaeology`, `inline_marker`, `readme_mining`, `cli`, `all` |
+| `--proposed` | Shortcut for `--status proposed` |
+| `--stale-only` | Only show stale decisions |
+
+**Examples:**
+
+```bash
+# See all active decisions
+repowise decision list --status active
+
+# Review auto-extracted proposals
+repowise decision list --proposed
+
+# Decision health overview
+repowise decision health
+
+# Confirm a proposed decision
+repowise decision confirm abc123
+
+# Deprecate, replaced by another
+repowise decision deprecate abc123 --superseded-by def456
+```
+
+---
+
+### `repowise generate-claude-md`
+
+Generate or update `CLAUDE.md` with codebase intelligence.
+
+```bash
+repowise generate-claude-md [PATH]
+```
+
+`CLAUDE.md` gives AI editors (Claude Code, Cursor, etc.) instant context about your codebase — architecture, key modules, hotspots, entry points, and conventions.
+
+If you have custom instructions at the top of your `CLAUDE.md`, they are preserved. Only the auto-generated section (between markers) is updated.
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--output / -o` | Custom output path (default: `CLAUDE.md` in repo root) |
+| `--stdout` | Print to stdout instead of file |
+
+---
+
+### `repowise export`
+
+Export wiki pages to files.
+
+```bash
+repowise export [PATH]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--format` | `markdown` (default), `html`, `json` |
+| `--output / -o` | Output directory (default: `.repowise/export`) |
+
+**Examples:**
+
+```bash
+# Export all pages as markdown files
+repowise export
+
+# Export as a single JSON file
+repowise export --format json --output ./wiki-export/
+
+# Export as HTML
+repowise export --format html
+```
+
+---
+
+### `repowise reindex`
+
+Rebuild vector search index from existing wiki pages. Useful after changing embedders or if the vector store gets corrupted.
+
+```bash
+repowise reindex [PATH]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--embedder` | Embedder: `gemini`, `openai`, `auto` (default: auto-detect from config) |
+| `--batch-size` | Pages per embedding batch (default: 20) |
+
+---
+
+### `repowise status`
+
+Show wiki sync state and page statistics.
+
+```bash
+repowise status [PATH]
+```
+
+Displays: last sync commit, total pages, pages by type, provider used, total tokens consumed.
+
+---
+
+### `repowise doctor`
+
+Run health checks on the wiki setup.
+
+```bash
+repowise doctor [PATH]
+```
+
+Checks:
+- Git repository valid
+- `.repowise/` directory exists
+- Database connectable with page count
+- `state.json` valid
+- Providers installed and importable
+- Stale page count
+
+---
+
+## Web UI
+
+Repowise includes a full web dashboard built with Next.js, React, and D3.js. It requires Node.js 20+ and runs alongside the backend server.
+
+### Starting the Web UI
+
+**Terminal 1 — Backend:**
+
+```bash
+cd /path/to/your-repo
+repowise serve --port 7337
+```
+
+**Terminal 2 — Frontend:**
+
+```bash
+cd /path/to/repowise # the repowise source repo
+npm install # first time only
+REPOWISE_API_URL=http://localhost:7337 npm run dev --workspace packages/web
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:REPOWISE_API_URL = "http://localhost:7337"
+npm run dev --workspace packages/web
+```
+
+Open **http://localhost:3000** in your browser.
+
+### Pages & Features
+
+**Dashboard** (`/`)
+Home page with aggregate stats (total pages, fresh/stale counts, dead code findings), a list of indexed repositories, and recent job status.
+
+**Wiki Browser** (`/repos/[id]/wiki/...`)
+The heart of repowise. Browse AI-generated documentation for every file and module. Each page includes:
+- Rendered markdown with syntax-highlighted code blocks and Mermaid diagrams
+- Sticky table of contents
+- Freshness badge (fresh / stale / outdated)
+- Git history sidebar — commits, churn percentile, top authors, co-change partners, hotspot indicator
+- Regenerate button for stale pages
+
+**Dependency Graph** (`/repos/[id]/graph`)
+Interactive force-directed graph rendered on HTML Canvas with D3.js. Handles 2000+ nodes. Six view modes:
+- **Module view** — hierarchical organization
+- **Ego graph** — neighborhood of a selected node
+- **Architecture view** — entry point reachability
+- **Dead code view** — highlights unreachable files
+- **Hot files view** — commit activity heatmap
+- **Full graph** — everything
+
+Supports pan, zoom, click-to-inspect, path finding between nodes, filtering by language, and PNG export.
+
+**Search** (`/repos/[id]/search`)
+Full-text and semantic search with result cards showing snippets, confidence scores, and links. A global command palette (`Ctrl+K` / `Cmd+K`) is accessible from any page for quick navigation.
+
+**Symbol Index** (`/repos/[id]/symbols`)
+Searchable, sortable table of every extracted symbol (functions, classes, methods, interfaces). Click any row for the full signature, docstring, and source location.
+
+**Documentation Coverage** (`/repos/[id]/coverage`)
+Donut chart and table showing freshness breakdown. Regenerate stale pages directly from the UI.
+
+**Code Ownership** (`/repos/[id]/ownership`)
+Contributor attribution by module or file. Highlights knowledge silos (bus factor risk) where one person owns >80% of a module.
+
+**Hotspots** (`/repos/[id]/hotspots`)
+Ranked table of high-churn files with commit counts, churn percentile bars, and owner attribution.
+
+**Dead Code** (`/repos/[id]/dead-code`)
+Findings grouped by category (unreachable files, unused exports, zombie packages) with confidence scores, line counts, and safe-to-delete badges. Bulk operations for resolving or acknowledging findings.
+
+**Architectural Decisions** (`/repos/[id]/decisions`)
+Browse and manage extracted decisions. View full rationale, affected files, health score, and status.
+
+**Codebase Chat** (`/repos/[id]/chat`)
+Ask questions about your codebase in natural language. Streaming responses powered by your configured LLM with real-time tool call visualization. The chat uses the same MCP tools as editor integrations.
+
+**Settings** (`/settings`)
+Configure API connection, default provider/model, embedder, and view webhook/MCP setup instructions.
+
+---
+
+## MCP Integration with AI Editors
+
+### Claude Code
+
+Add to your project's `.claude/settings.json` or run:
+
+```bash
+repowise mcp /path/to/your-repo --transport stdio
+```
+
+Claude Code auto-detects the `.repowise/.mcp.json` generated by `repowise init`.
+
+### Cursor / Windsurf / Cline
+
+Add an MCP server entry pointing to:
+
+```json
+{
+ "command": "repowise",
+ "args": ["mcp", "/path/to/your-repo", "--transport", "stdio"]
+}
+```
+
+### Web-based MCP clients
+
+```bash
+repowise mcp /path/to/your-repo --transport sse --port 7338
+```
+
+Connect to `http://localhost:7338/sse`.
+
+### What AI editors can do with MCP
+
+Once connected, your AI editor can:
+- Get an architecture overview before starting any task
+- Fetch rich context for files before reading/modifying them (docs, ownership, decisions, freshness)
+- Assess modification risk before changing hotspot files
+- Understand *why* code is structured a certain way (architectural decisions)
+- Search the wiki semantically ("how do we handle retries?")
+- Trace dependency paths between modules
+- Find dead code to clean up
+- Generate architecture diagrams
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ANTHROPIC_API_KEY` | If using Anthropic | Anthropic API key |
+| `OPENAI_API_KEY` | If using OpenAI | OpenAI API key |
+| `GEMINI_API_KEY` | If using Gemini | Google Gemini API key |
+| `REPOWISE_DB_URL` | No | Database URL override (default: `.repowise/wiki.db`) |
+| `REPOWISE_EMBEDDER` | No | Embedder for semantic search: `gemini`, `openai`, `mock` |
+| `REPOWISE_API_URL` | Frontend only | Backend URL for the web UI (default: `http://localhost:7337`) |
+| `REPOWISE_API_KEY` | No | Optional API key to protect the server |
+
+---
+
+## Common Workflows
+
+### First-time setup for a new project
+
+```bash
+pip install "repowise[anthropic]"
+export ANTHROPIC_API_KEY="sk-ant-..."
+cd /path/to/your-project
+repowise init
+```
+
+### Daily development workflow
+
+```bash
+# Option A: Manual update after pulling
+git pull
+repowise update
+
+# Option B: Continuous sync while coding
+repowise watch
+```
+
+### Before a code review
+
+```bash
+# Check what's at risk
+repowise dead-code --safe-only
+
+# Review decision health
+repowise decision health
+
+# See hotspots
+repowise status
+```
+
+### Team onboarding
+
+```bash
+# Generate full wiki for the new team member
+repowise init --provider openai
+
+# They can browse it
+repowise serve
+
+# Or use it in their editor
+repowise mcp --transport stdio
+```
+
+### CI/CD integration
+
+```bash
+# Index-only in CI (free, no LLM calls)
+repowise init --index-only
+
+# Export docs as markdown for static hosting
+repowise export --format markdown --output ./docs/wiki/
+```
+
+### Switching LLM providers
+
+```bash
+# Re-generate with a different provider
+repowise init --provider openai --model gpt-5.4-nano --force
+
+# Or just change the model for future updates
+# (edit .repowise/config.yaml, then:)
+repowise update --provider gemini
+```
+
+---
+
+## Troubleshooting
+
+**"Provider X requires the Y package"**
+Install the optional dependency: `pip install "repowise[anthropic]"` (or openai, gemini, litellm).
+
+**Empty search results with semantic mode**
+Check that an embedder is configured. Run `repowise reindex --embedder gemini` to rebuild the vector store.
+
+**"embedder.mock_active" warning**
+Set `REPOWISE_EMBEDDER=gemini` (or `openai`) for real vector search. Mock embedder produces random vectors — semantic search won't work meaningfully.
+
+**Stale pages after code changes**
+Run `repowise update` to sync. Or use `repowise watch` for automatic syncing.
+
+**Cost seems high**
+Use `--dry-run` to see the cost estimate first. Use `--test-run` to validate with just 10 files. Use `--skip-tests --skip-infra` to reduce scope. Lower `--concurrency` to slow down API usage.
+
+**init was interrupted**
+Run `repowise init --resume` to pick up where it left off.
+
+**Vector store corrupted**
+Run `repowise reindex` to rebuild from existing wiki pages.
+
+**Doctor says database has 0 pages**
+The init either failed or was run with `--index-only`. Run `repowise init` with a provider to generate pages.
+
+**Frontend shows empty repo list**
+Make sure `REPOWISE_DB_URL` (or `REPOWISE_API_URL` for the frontend) points to the correct database. The backend and frontend must point to the same wiki DB.
+
+**CORS errors in the browser**
+Ensure both the backend (`repowise serve`) and frontend (`npm run dev`) are running. The backend allows all origins by default.
diff --git a/packages/cli/pyproject.toml b/packages/cli/pyproject.toml
index 6c83b5d7c..271356ff7 100644
--- a/packages/cli/pyproject.toml
+++ b/packages/cli/pyproject.toml
@@ -1,43 +1,6 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "repowise-cli"
-version = "0.1.0"
-description = "repowise CLI — generate and maintain codebase documentation from the command line"
-readme = "README.md"
-requires-python = ">=3.11"
-license = { text = "Apache-2.0" }
-keywords = ["documentation", "codebase", "wiki", "cli"]
-classifiers = [
- "Development Status :: 3 - Alpha",
- "Intended Audience :: Developers",
- "License :: OSI Approved :: Apache Software License",
- "Programming Language :: Python :: 3",
- "Programming Language :: Python :: 3.11",
- "Programming Language :: Python :: 3.12",
- "Programming Language :: Python :: 3.13",
- "Environment :: Console",
- "Topic :: Software Development :: Documentation",
-]
-dependencies = [
- "repowise-core",
- "repowise-server",
- # CLI framework
- "click>=8.1,<9",
- # Terminal formatting
- "rich>=13,<14",
- # Filesystem watching (for `repowise watch`)
- "watchdog>=4,<5",
-]
-
-[project.scripts]
-repowise = "repowise.cli.main:cli"
-
-[project.urls]
-Homepage = "https://github.com/repowise-ai/repowise"
-Repository = "https://github.com/repowise-ai/repowise"
+# ---------------------------------------------------------------------------
+# repowise-cli — per-package config (packaging is handled by root pyproject.toml)
+# ---------------------------------------------------------------------------
[tool.hatch.build.targets.wheel]
packages = ["src/repowise"]
diff --git a/packages/cli/src/repowise/cli/__init__.py b/packages/cli/src/repowise/cli/__init__.py
index 72c199013..5c94627a9 100644
--- a/packages/cli/src/repowise/cli/__init__.py
+++ b/packages/cli/src/repowise/cli/__init__.py
@@ -6,4 +6,4 @@ git signals, dead code detection, architectural decisions, and
AI-generated documentation.
"""
-__version__ = "0.1.0"
+__version__ = "0.1.1"
diff --git a/packages/core/pyproject.toml b/packages/core/pyproject.toml
index be3f237e8..9ab44ce38 100644
--- a/packages/core/pyproject.toml
+++ b/packages/core/pyproject.toml
@@ -1,85 +1,9 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "repowise-core"
-version = "0.1.0"
-description = "repowise core: ingestion pipeline, dependency graph, and documentation generation engine"
-readme = "README.md"
-requires-python = ">=3.11"
-license = { text = "Apache-2.0" }
-keywords = ["documentation", "codebase", "wiki", "llm", "ai"]
-classifiers = [
- "Development Status :: 3 - Alpha",
- "Intended Audience :: Developers",
- "License :: OSI Approved :: Apache Software License",
- "Programming Language :: Python :: 3",
- "Programming Language :: Python :: 3.11",
- "Programming Language :: Python :: 3.12",
- "Programming Language :: Python :: 3.13",
- "Topic :: Software Development :: Documentation",
- "Typing :: Typed",
-]
-dependencies = [
- # HTTP client (used by all providers)
- "httpx>=0.27,<1",
- # LLM providers
- "anthropic>=0.40,<1",
- "openai>=1.50,<2",
- "litellm>=1.50,<2",
- # AST parsing
- "tree-sitter>=0.23,<1",
- "tree-sitter-python>=0.23,<1",
- "tree-sitter-typescript>=0.23,<1",
- "tree-sitter-javascript>=0.23,<1",
- "tree-sitter-go>=0.23,<1",
- "tree-sitter-rust>=0.23,<1",
- "tree-sitter-java>=0.23,<1",
- "tree-sitter-cpp>=0.23,<1",
- # Dependency graph
- "networkx>=3.3,<4",
- "scipy>=1.11,<2",
- # Template rendering
- "jinja2>=3.1,<4",
- # File filtering
- "pathspec>=0.12,<1",
- # Structured logging
- "structlog>=24,<25",
- # Database (async)
- "sqlalchemy[asyncio]>=2.0,<3",
- "aiosqlite>=0.20,<1",
- "alembic>=1.13,<2",
- # Data validation
- "pydantic>=2.8,<3",
- # Retry logic
- "tenacity>=9,<10",
- # Git operations (ChangeDetector)
- "gitpython>=3.1,<4",
- # YAML parsing (OpenAPI handler)
- "pyyaml>=6.0,<7",
- # Gemini provider + embedder
- "google-genai>=1.0,<2",
- # Vector search (LanceDB — pure Python wheel, no C++ build tools)
- "lancedb>=0.12,<1",
-]
-
-[project.optional-dependencies]
-# pgvector backend — only needed when DATABASE_URL is PostgreSQL.
-# Install with: uv pip install repowise-core[pgvector]
-pgvector = [
- "pgvector>=0.3,<1",
- "asyncpg>=0.29,<1",
-]
-
-[project.urls]
-Homepage = "https://github.com/repowise-ai/repowise"
-Repository = "https://github.com/repowise-ai/repowise"
-Issues = "https://github.com/repowise-ai/repowise/issues"
+# ---------------------------------------------------------------------------
+# repowise-core — per-package config (packaging is handled by root pyproject.toml)
+# ---------------------------------------------------------------------------
[tool.hatch.build.targets.wheel]
-# Namespace package: src/repowise has no __init__.py
-# Hatchling ships the repowise/core/ slice of the repowise namespace
+# Retained for local hatchling dev builds if needed
packages = ["src/repowise"]
[tool.uv]
diff --git a/packages/core/src/repowise/core/__init__.py b/packages/core/src/repowise/core/__init__.py
index d46a4c5e7..192ade773 100644
--- a/packages/core/src/repowise/core/__init__.py
+++ b/packages/core/src/repowise/core/__init__.py
@@ -6,4 +6,4 @@ generation engine. This is the heart of repowise — all other packages depend o
Namespace package: repowise.core is part of the repowise namespace.
"""
-__version__ = "0.1.0"
+__version__ = "0.1.1"
diff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.py
index 98d925c12..3e864724c 100644
--- a/packages/core/src/repowise/core/ingestion/parser.py
+++ b/packages/core/src/repowise/core/ingestion/parser.py
@@ -36,7 +36,7 @@ from .models import FileInfo, Import, ParsedFile, Symbol
log = structlog.get_logger(__name__)
-QUERIES_DIR = Path(__file__).parent.parent.parent.parent.parent / "queries"
+QUERIES_DIR = Path(__file__).parent / "queries"
# Languages that intentionally have no AST parser. These are data, config,
# markup, or query files — there are no code symbols to extract, and that is
diff --git a/packages/core/src/repowise/core/ingestion/queries/c.scm b/packages/core/src/repowise/core/ingestion/queries/c.scm
new file mode 100644
index 000000000..8bbc2d100
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/c.scm
@@ -0,0 +1,35 @@
+; =============================================================================
+; repowise — C symbol and import queries
+; Uses the tree-sitter-cpp grammar (superset of C)
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+(function_definition
+ declarator: (function_declarator
+ declarator: (identifier) @symbol.name
+ parameters: (parameter_list) @symbol.params
+ )
+) @symbol.def
+
+(struct_specifier
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+(enum_specifier
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports (#include directives)
+; ---------------------------------------------------------------------------
+
+(preproc_include
+ path: (system_lib_string) @import.module
+) @import.statement
+
+(preproc_include
+ path: (string_literal) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/cpp.scm b/packages/core/src/repowise/core/ingestion/queries/cpp.scm
new file mode 100644
index 000000000..da57ec9fe
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/cpp.scm
@@ -0,0 +1,62 @@
+; =============================================================================
+; repowise — C++ symbol and import queries
+; tree-sitter-cpp >= 0.23
+; (Also used for .c files — C is a subset of this grammar for our purposes)
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+; Function definition: ReturnType funcName(params) { body }
+; The name is nested inside function_declarator
+(function_definition
+ declarator: (function_declarator
+ declarator: (identifier) @symbol.name
+ parameters: (parameter_list) @symbol.params
+ )
+) @symbol.def
+
+; Qualified function definition: ReturnType ClassName::method(params) { }
+(function_definition
+ declarator: (function_declarator
+ declarator: (qualified_identifier
+ name: (identifier) @symbol.name
+ )
+ parameters: (parameter_list) @symbol.params
+ )
+) @symbol.def
+
+; Class
+(class_specifier
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; Struct
+(struct_specifier
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; Enum (type_identifier is a direct child, not a named field in this grammar)
+(enum_specifier
+ (type_identifier) @symbol.name
+) @symbol.def
+
+; Namespace
+(namespace_definition
+ name: (namespace_identifier) @symbol.name
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports (#include directives)
+; ---------------------------------------------------------------------------
+
+; #include <header>
+(preproc_include
+ path: (system_lib_string) @import.module
+) @import.statement
+
+; #include "local_header"
+(preproc_include
+ path: (string_literal) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/go.scm b/packages/core/src/repowise/core/ingestion/queries/go.scm
new file mode 100644
index 000000000..432409d04
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/go.scm
@@ -0,0 +1,36 @@
+; =============================================================================
+; repowise — Go symbol and import queries
+; tree-sitter-go >= 0.23
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+; Top-level function
+(function_declaration
+ name: (identifier) @symbol.name
+ parameters: (parameter_list) @symbol.params
+) @symbol.def
+
+; Method with receiver — @symbol.receiver is used to determine parent type
+(method_declaration
+ receiver: (parameter_list) @symbol.receiver
+ name: (field_identifier) @symbol.name
+ parameters: (parameter_list) @symbol.params
+) @symbol.def
+
+; Type declaration (struct, interface, alias)
+; type_spec is always inside type_declaration
+(type_spec
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports
+; ---------------------------------------------------------------------------
+
+; Single import: import "fmt"
+(import_spec
+ (interpreted_string_literal) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/java.scm b/packages/core/src/repowise/core/ingestion/queries/java.scm
new file mode 100644
index 000000000..a3d7428e7
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/java.scm
@@ -0,0 +1,44 @@
+; =============================================================================
+; repowise — Java symbol and import queries
+; tree-sitter-java >= 0.23
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+(class_declaration
+ name: (identifier) @symbol.name
+) @symbol.def
+
+(interface_declaration
+ name: (identifier) @symbol.name
+) @symbol.def
+
+(enum_declaration
+ name: (identifier) @symbol.name
+) @symbol.def
+
+(method_declaration
+ name: (identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+(constructor_declaration
+ name: (identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+; Public modifier capture
+(method_declaration
+ (modifiers) @symbol.modifiers
+ name: (identifier) @symbol.name
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports
+; ---------------------------------------------------------------------------
+
+(import_declaration
+ (scoped_identifier) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/javascript.scm b/packages/core/src/repowise/core/ingestion/queries/javascript.scm
new file mode 100644
index 000000000..503866a29
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/javascript.scm
@@ -0,0 +1,45 @@
+; =============================================================================
+; repowise — JavaScript symbol and import queries
+; tree-sitter-javascript >= 0.23
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+(function_declaration
+ name: (identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+(generator_function_declaration
+ name: (identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+(class_declaration
+ name: (identifier) @symbol.name
+) @symbol.def
+
+(method_definition
+ name: (property_identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+; Arrow function assigned to const/let
+(lexical_declaration
+ (variable_declarator
+ name: (identifier) @symbol.name
+ value: (arrow_function
+ parameters: (formal_parameters) @symbol.params
+ )
+ )
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports
+; ---------------------------------------------------------------------------
+
+(import_statement
+ source: (string) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/kotlin.scm b/packages/core/src/repowise/core/ingestion/queries/kotlin.scm
new file mode 100644
index 000000000..6190b04ab
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/kotlin.scm
@@ -0,0 +1,25 @@
+; =============================================================================
+; repowise — Kotlin symbol and import queries
+; tree-sitter-kotlin (install separately if needed)
+; =============================================================================
+
+(function_declaration
+ (simple_identifier) @symbol.name
+ (function_value_parameters) @symbol.params
+) @symbol.def
+
+(class_declaration
+ (type_identifier) @symbol.name
+) @symbol.def
+
+(object_declaration
+ (type_identifier) @symbol.name
+) @symbol.def
+
+(interface_declaration
+ (type_identifier) @symbol.name
+) @symbol.def
+
+(import_header
+ (identifier) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/python.scm b/packages/core/src/repowise/core/ingestion/queries/python.scm
new file mode 100644
index 000000000..6558b115b
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/python.scm
@@ -0,0 +1,59 @@
+; =============================================================================
+; repowise — Python symbol and import queries
+; tree-sitter-python >= 0.23
+;
+; Capture name conventions (shared across ALL language query files):
+; @symbol.def — the full definition node (used for line numbers, kind)
+; @symbol.name — the name identifier node
+; @symbol.params — parameter list node (optional)
+; @symbol.modifiers — decorator / visibility modifier nodes (optional)
+; @import.statement — the full import node
+; @import.module — the module path being imported from
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+; Function (covers both regular and async — in tree-sitter-python >= 0.23
+; async functions share the function_definition node type)
+(function_definition
+ name: (identifier) @symbol.name
+ parameters: (parameters) @symbol.params
+) @symbol.def
+
+; Class
+(class_definition
+ name: (identifier) @symbol.name
+) @symbol.def
+
+; Decorated function or class — captures the decorator as a modifier
+(decorated_definition
+ (decorator) @symbol.modifiers
+ (function_definition
+ name: (identifier) @symbol.name
+ parameters: (parameters) @symbol.params
+ ) @symbol.def
+)
+
+(decorated_definition
+ (decorator) @symbol.modifiers
+ (class_definition
+ name: (identifier) @symbol.name
+ ) @symbol.def
+)
+
+; ---------------------------------------------------------------------------
+; Imports
+; ---------------------------------------------------------------------------
+
+; from x.y import a, b
+; from . import x
+(import_from_statement
+ module_name: (_) @import.module
+) @import.statement
+
+; import x.y.z
+(import_statement
+ name: (_) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/ruby.scm b/packages/core/src/repowise/core/ingestion/queries/ruby.scm
new file mode 100644
index 000000000..05de0efcd
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/ruby.scm
@@ -0,0 +1,30 @@
+; =============================================================================
+; repowise — Ruby symbol and import queries
+; tree-sitter-ruby (install separately if needed)
+; =============================================================================
+
+(method
+ name: (identifier) @symbol.name
+ parameters: (method_parameters)? @symbol.params
+) @symbol.def
+
+(singleton_method
+ name: (identifier) @symbol.name
+) @symbol.def
+
+(class
+ name: (constant) @symbol.name
+) @symbol.def
+
+(module
+ name: (constant) @symbol.name
+) @symbol.def
+
+; require 'module' / require_relative './sibling'
+(call
+ method: (identifier) @_require_method
+ arguments: (argument_list
+ (string (string_content) @import.module)
+ )
+ (#match? @_require_method "^require")
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/rust.scm b/packages/core/src/repowise/core/ingestion/queries/rust.scm
new file mode 100644
index 000000000..f0367a84d
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/rust.scm
@@ -0,0 +1,56 @@
+; =============================================================================
+; repowise — Rust symbol and import queries
+; tree-sitter-rust >= 0.23
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+(function_item
+ name: (identifier) @symbol.name
+ parameters: (parameters) @symbol.params
+) @symbol.def
+
+(struct_item
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+(enum_item
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+(trait_item
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; impl block — the "type" field identifies what is being implemented
+(impl_item
+ type: (type_identifier) @symbol.name
+) @symbol.def
+
+(const_item
+ name: (identifier) @symbol.name
+) @symbol.def
+
+(type_item
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+(mod_item
+ name: (identifier) @symbol.name
+) @symbol.def
+
+; pub visibility modifier
+(function_item
+ (visibility_modifier) @symbol.modifiers
+ name: (identifier) @symbol.name
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports
+; ---------------------------------------------------------------------------
+
+(use_declaration
+ argument: (_) @import.module
+) @import.statement
diff --git a/packages/core/src/repowise/core/ingestion/queries/typescript.scm b/packages/core/src/repowise/core/ingestion/queries/typescript.scm
new file mode 100644
index 000000000..a02f871b1
--- /dev/null
+++ b/packages/core/src/repowise/core/ingestion/queries/typescript.scm
@@ -0,0 +1,78 @@
+; =============================================================================
+; repowise — TypeScript symbol and import queries
+; tree-sitter-typescript >= 0.23
+; =============================================================================
+
+; ---------------------------------------------------------------------------
+; Symbols
+; ---------------------------------------------------------------------------
+
+; Top-level function declaration
+(function_declaration
+ name: (identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+; Generator function
+(generator_function_declaration
+ name: (identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+; Class declaration
+(class_declaration
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; Abstract class
+(abstract_class_declaration
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; Interface
+(interface_declaration
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; Type alias
+(type_alias_declaration
+ name: (type_identifier) @symbol.name
+) @symbol.def
+
+; Enum
+(enum_declaration
+ name: (identifier) @symbol.name
+) @symbol.def
+
+; Method inside class body
+(method_definition
+ name: (property_identifier) @symbol.name
+ parameters: (formal_parameters) @symbol.params
+) @symbol.def
+
+; Arrow function assigned to const/let: const foo = (...) => { }
+(lexical_declaration
+ (variable_declarator
+ name: (identifier) @symbol.name
+ value: (arrow_function
+ parameters: (formal_parameters) @symbol.params
+ )
+ )
+) @symbol.def
+
+; Public method accessor modifier capture
+(method_definition
+ (accessibility_modifier) @symbol.modifiers
+ name: (property_identifier) @symbol.name
+) @symbol.def
+
+; ---------------------------------------------------------------------------
+; Imports
+; ---------------------------------------------------------------------------
+
+; import { A, B } from "./module"
+; import type { T } from "./types"
+; import DefaultExport from "module"
+(import_statement
+ source: (string) @import.module
+) @import.statement
diff --git a/packages/server/pyproject.toml b/packages/server/pyproject.toml
index 0c60f1ddb..b06e1c017 100644
--- a/packages/server/pyproject.toml
+++ b/packages/server/pyproject.toml
@@ -1,42 +1,6 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "repowise-server"
-version = "0.1.0"
-description = "repowise server — FastAPI REST API, webhook handlers, and MCP server"
-readme = "README.md"
-requires-python = ">=3.11"
-license = { text = "Apache-2.0" }
-keywords = ["documentation", "api", "mcp", "fastapi", "webhooks"]
-classifiers = [
- "Development Status :: 3 - Alpha",
- "Intended Audience :: Developers",
- "License :: OSI Approved :: Apache Software License",
- "Programming Language :: Python :: 3",
- "Programming Language :: Python :: 3.11",
- "Programming Language :: Python :: 3.12",
- "Programming Language :: Python :: 3.13",
- "Framework :: FastAPI",
- "Topic :: Software Development :: Documentation",
-]
-dependencies = [
- "repowise-core",
- # Web framework
- "fastapi>=0.115,<1",
- "uvicorn[standard]>=0.32,<1",
- # MCP Python SDK
- "mcp>=1.0,<2",
- # Background task scheduling
- "apscheduler>=3.10,<4",
- # Webhook signature verification
- "cryptography>=43,<44",
-]
-
-[project.urls]
-Homepage = "https://github.com/repowise-ai/repowise"
-Repository = "https://github.com/repowise-ai/repowise"
+# ---------------------------------------------------------------------------
+# repowise-server — per-package config (packaging is handled by root pyproject.toml)
+# ---------------------------------------------------------------------------
[tool.hatch.build.targets.wheel]
packages = ["src/repowise"]
diff --git a/packages/server/src/repowise/server/__init__.py b/packages/server/src/repowise/server/__init__.py
index 98ce29293..ea40201b6 100644
--- a/packages/server/src/repowise/server/__init__.py
+++ b/packages/server/src/repowise/server/__init__.py
@@ -7,4 +7,4 @@ Provides:
- Background job scheduler (APScheduler)
"""
-__version__ = "0.1.0"
+__version__ = "0.1.1"
diff --git a/pyproject.toml b/pyproject.toml
index 4d2333d5a..040243c3c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,3 +1,152 @@
+# ---------------------------------------------------------------------------
+# repowise — unified PyPI package
+# ---------------------------------------------------------------------------
+[build-system]
+requires = ["setuptools>=75"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "repowise"
+version = "0.1.1"
+description = "Codebase intelligence for developers and AI — generates and maintains a structured wiki for any codebase"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "AGPL-3.0-only"
+keywords = ["documentation", "codebase", "wiki", "llm", "ai", "mcp"]
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Intended Audience :: Developers",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Programming Language :: Python :: 3.13",
+ "Environment :: Console",
+ "Framework :: FastAPI",
+ "Topic :: Software Development :: Documentation",
+ "Typing :: Typed",
+]
+
+# ---------------------------------------------------------------------------
+# Core dependencies — everything needed for analysis + generation + CLI + server.
+# LLM/embedding provider SDKs are optional (see [project.optional-dependencies]).
+# ---------------------------------------------------------------------------
+dependencies = [
+ # HTTP client
+ "httpx>=0.27,<1",
+ # AST parsing
+ "tree-sitter>=0.23,<1",
+ "tree-sitter-python>=0.23,<1",
+ "tree-sitter-typescript>=0.23,<1",
+ "tree-sitter-javascript>=0.23,<1",
+ "tree-sitter-go>=0.23,<1",
+ "tree-sitter-rust>=0.23,<1",
+ "tree-sitter-java>=0.23,<1",
+ "tree-sitter-cpp>=0.23,<1",
+ # Dependency graph
+ "networkx>=3.3,<4",
+ "scipy>=1.11,<2",
+ # Template rendering
+ "jinja2>=3.1,<4",
+ # File filtering
+ "pathspec>=0.12,<1",
+ # Structured logging
+ "structlog>=24,<25",
+ # Database (async)
+ "sqlalchemy[asyncio]>=2.0,<3",
+ "aiosqlite>=0.20,<1",
+ "alembic>=1.13,<2",
+ # Data validation
+ "pydantic>=2.8,<3",
+ # Retry logic
+ "tenacity>=9,<10",
+ # Git operations
+ "gitpython>=3.1,<4",
+ # YAML parsing
+ "pyyaml>=6.0,<7",
+ # Vector search (LanceDB — pure Python wheel)
+ "lancedb>=0.12,<1",
+ # CLI
+ "click>=8.1,<9",
+ "rich>=13,<14",
+ "watchdog>=4,<5",
+ # Server
+ "fastapi>=0.115,<1",
+ "uvicorn[standard]>=0.32,<1",
+ "mcp>=1.0,<2",
+ "apscheduler>=3.10,<4",
+ "cryptography>=43,<44",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40,<1"]
+openai = ["openai>=1.50,<2"]
+gemini = ["google-genai>=1.0,<2"]
+litellm = ["litellm>=1.50,<2"]
+postgres = [
+ "pgvector>=0.3,<1",
+ "asyncpg>=0.29,<1",
+]
+all = [
+ "repowise[anthropic,openai,gemini,litellm,postgres]",
+]
+dev = [
+ "pytest>=8,<9",
+ "pytest-asyncio>=0.23,<1",
+ "pytest-snapshot>=0.9,<1",
+ "respx>=0.21,<1",
+ "time-machine>=2.14,<3",
+ "ruff>=0.6,<1",
+ "mypy>=1.11,<2",
+ "types-networkx>=3.3,<4",
+ "build>=1.0",
+]
+
+[project.scripts]
+repowise = "repowise.cli.main:cli"
+
+[project.urls]
+Homepage = "https://github.com/RaghavChamadiya/repowise"
+Repository = "https://github.com/RaghavChamadiya/repowise"
+Issues = "https://github.com/RaghavChamadiya/repowise/issues"
+Documentation = "https://github.com/RaghavChamadiya/repowise/blob/main/docs/USER_GUIDE.md"
+
+# ---------------------------------------------------------------------------
+# setuptools — explicit package-dir mapping across three src/ directories
+# ---------------------------------------------------------------------------
+[tool.setuptools.package-dir]
+"repowise.core" = "packages/core/src/repowise/core"
+"repowise.cli" = "packages/cli/src/repowise/cli"
+"repowise.server" = "packages/server/src/repowise/server"
+
+[tool.setuptools]
+packages = [
+ # core
+ "repowise.core",
+ "repowise.core.analysis",
+ "repowise.core.generation",
+ "repowise.core.generation.editor_files",
+ "repowise.core.ingestion",
+ "repowise.core.ingestion.parsers",
+ "repowise.core.persistence",
+ "repowise.core.providers",
+ "repowise.core.providers.llm",
+ "repowise.core.providers.embedding",
+ # cli
+ "repowise.cli",
+ "repowise.cli.commands",
+ # server
+ "repowise.server",
+ "repowise.server.routers",
+ "repowise.server.mcp_server",
+]
+
+[tool.setuptools.package-data]
+"repowise.core.ingestion" = ["queries/*.scm"]
+"repowise.core.generation" = ["templates/*.j2"]
+
+# ---------------------------------------------------------------------------
+# uv workspace (kept for local development)
+# ---------------------------------------------------------------------------
[tool.uv.workspace]
members = [
"packages/core",