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 CLAUDE.md generation and fix MCP tool reliability

RaghavChamadiyafd0b65efafb7
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a615182e1..7862d93d6 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -37,8 +37,9 @@ For per-package detail (installation, full API reference, all CLI flags, file ma
12. [Codebase Chat](#12-codebase-chat)
13. [Data Flow Diagrams](#13-data-flow-diagrams)
14. [Key Design Decisions](#14-key-design-decisions)
-15. [Adding a New Language](#15-adding-a-new-language)
-16. [Adding a New LLM Provider](#16-adding-a-new-llm-provider)
+15. [Editor File Generation](#15-editor-file-generation)
+16. [Adding a New Language](#16-adding-a-new-language)
+17. [Adding a New LLM Provider](#17-adding-a-new-llm-provider)
---
@@ -124,7 +125,13 @@ repowise/
│ │ │ │ ├── context_assembler.py# context assembly (RAG + graph + git + source)
│ │ │ │ ├── job_system.py # resumable job state machine
│ │ │ │ ├── models.py # GeneratedPage, GenerationConfig, PageType, etc.
-│ │ │ │ └── templates/ # Jinja2 prompt templates (one per page type)
+│ │ │ │ ├── templates/ # Jinja2 prompt templates (one per page type)
+│ │ │ │ └── editor_files/ # CLAUDE.md / cursor.md generation (no LLM)
+│ │ │ │ ├── base.py # BaseEditorFileGenerator (marker-merge, atomic write)
+│ │ │ │ ├── data.py # EditorFileData + sub-dataclasses (frozen)
+│ │ │ │ ├── fetcher.py # EditorFileDataFetcher (DB → EditorFileData)
+│ │ │ │ ├── tech_stack.py # filesystem tech stack + build command detection
+│ │ │ │ └── claude_md.py # ClaudeMdGenerator subclass
│ │ │ ├── persistence/
│ │ │ │ ├── models.py # SQLAlchemy ORM models
│ │ │ │ ├── crud.py # async CRUD layer
@@ -155,14 +162,14 @@ repowise/
│ │
│ ├── server/ # Python: FastAPI REST API + MCP server
│ │ └── src/repowise/server/
-│ │ ├── api/ # FastAPI routers (repos, pages, jobs, symbols, graph, git, dead-code, decisions, search)
-│ │ ├── mcp_server.py # MCP server (8 tools)
+│ │ ├── routers/ # FastAPI routers (repos, pages, jobs, symbols, graph, git, dead-code, decisions, search, claude-md)
+│ │ ├── mcp_server/ # MCP server package (8 tools, split into focused modules)
│ │ ├── webhooks/ # GitHub + GitLab handlers
│ │ └── scheduler.py # APScheduler background jobs
│ │
│ ├── cli/ # Python: repowise CLI (click + rich)
│ │ └── src/repowise/cli/
-│ │ └── commands/ # init, update, watch, serve, search, export, status, doctor, dead-code, decision, mcp, reindex
+│ │ └── commands/ # init, update, watch, serve, search, export, status, doctor, dead-code, decision, mcp, reindex, generate-claude-md
│ │
│ └── web/ # Next.js 15 frontend
│ ├── src/app/ # App Router pages (dashboard, wiki, search, graph, symbols, …)
@@ -926,7 +933,7 @@ repowise decision health # health summary
| `core/analysis/decision_extractor.py` | All 4 capture sources + staleness computation |
| `core/persistence/models.py` | `DecisionRecord` ORM model |
| `core/persistence/crud.py` | 8 decision CRUD functions |
-| `server/mcp_server.py` | MCP tool `get_why` (3-mode: search, path, health dashboard) |
+| `server/mcp_server/tool_why.py` | MCP tool `get_why` (3-mode: search, path, health dashboard) |
| `server/routers/decisions.py` | REST API endpoints |
| `cli/commands/decision_cmd.py` | CLI command group (7 subcommands) |
@@ -991,6 +998,8 @@ Key routers:
- `/api/repos/{id}/dead-code` — dead code findings (GET list, POST trigger analysis)
- `/api/repos/{id}/dead-code/summary` — aggregate dead code stats
- `/api/dead-code/{finding_id}` — PATCH to resolve/acknowledge findings
+- `/api/repos/{id}/claude-md` — GET preview of generated CLAUDE.md section (JSON, no disk write)
+- `/api/repos/{id}/claude-md/generate` — POST to regenerate and write CLAUDE.md to disk
- `/health` — liveness + readiness (checks DB + provider)
- `/metrics` — Prometheus-compatible metrics (job counts, token totals, stale count)
@@ -1133,6 +1142,7 @@ JobSystem
▼
.repowise/state.json updated
MCP config printed
+ CLAUDE.md generated (EditorFileDataFetcher → ClaudeMdGenerator, no LLM)
Summary shown (pages, tokens, cost, time)
```
@@ -1342,7 +1352,47 @@ and the vector store embed (LanceDB or pgvector) can overlap with the next file'
---
-## 15. Adding a New Language
+## 15. Editor File Generation
+
+See [`docs/EDITOR_FILES.md`](EDITOR_FILES.md) for the complete reference covering
+architecture, all data sources, how the marker-merge system works, and how to add
+support for a new editor file (cursor.md, copilot-instructions.md, etc.).
+
+**Quick summary:** repowise can generate and maintain AI-editor configuration files
+(CLAUDE.md, cursor.md, etc.) from the already-indexed codebase data — no LLM calls.
+The system uses HTML comment markers to split the file into a user-owned section and
+a Repowise-managed section. The user section is never touched.
+
+The feature runs automatically after `repowise init` and `repowise update`, and can
+also be run standalone:
+
+```
+repowise generate-claude-md [PATH]
+```
+
+Config opt-out:
+```yaml
+# .repowise/config.yaml
+editor_files:
+ claude_md: false
+```
+
+Key files:
+
+| File | Purpose |
+|------|---------|
+| `core/generation/editor_files/base.py` | `BaseEditorFileGenerator` — marker-merge logic shared by all editor-file generators |
+| `core/generation/editor_files/data.py` | `EditorFileData` frozen dataclass — the data contract between fetcher and template |
+| `core/generation/editor_files/fetcher.py` | `EditorFileDataFetcher` — queries DB for architecture summary, modules, hotspots, decisions |
+| `core/generation/editor_files/tech_stack.py` | Filesystem scan for languages, frameworks, build commands |
+| `core/generation/editor_files/claude_md.py` | `ClaudeMdGenerator` — 30-line subclass that binds filename + template |
+| `core/generation/templates/claude_md.j2` | Jinja2 template for the Repowise-managed section |
+| `cli/commands/claude_md_cmd.py` | `repowise generate-claude-md` CLI command |
+| `server/routers/claude_md.py` | `GET/POST /api/repos/{id}/claude-md` REST endpoints |
+
+---
+
+## 16. Adding a New Language
1. **Write `packages/core/queries/<language>.scm`**
@@ -1384,7 +1434,7 @@ and the vector store embed (LanceDB or pgvector) can overlap with the next file'
---
-## 16. Adding a New LLM Provider
+## 17. Adding a New LLM Provider
1. **Create `packages/core/providers/<name>.py`**
diff --git a/docs/AUTO_SYNC.md b/docs/AUTO_SYNC.md
new file mode 100644
index 000000000..65a433d5e
--- /dev/null
+++ b/docs/AUTO_SYNC.md
@@ -0,0 +1,238 @@
+# Keeping Your Wiki in Sync
+
+repowise can automatically update your wiki whenever code changes. Choose the
+method that fits your setup.
+
+| Method | Best for | Requires server? |
+|--------|----------|-----------------|
+| [Post-commit hook](#1-post-commit-git-hook) | Solo developers, local repos | No |
+| [File watcher](#2-file-watcher) | Local development, rapid iteration | No |
+| [GitHub webhook](#3-github-webhook) | Teams, CI/CD, hosted repos | Yes |
+| [GitLab webhook](#4-gitlab-webhook) | Teams, CI/CD, hosted repos | Yes |
+| [Polling fallback](#5-polling-fallback) | Safety net for missed webhooks | Yes |
+
+---
+
+## 1. Post-Commit Git Hook
+
+Runs `repowise update` in the background after every local commit. Your
+terminal is never blocked.
+
+### Setup
+
+```bash
+cat > .git/hooks/post-commit << 'EOF'
+#!/bin/sh
+echo "[repowise] Triggering wiki update..."
+(
+ cd "$(git rev-parse --show-toplevel)" || exit 1
+ repowise update > /tmp/repowise-update.log 2>&1
+) &
+exit 0
+EOF
+chmod +x .git/hooks/post-commit
+```
+
+> **Windows (Git Bash):** If `repowise` isn't on your bash PATH (e.g. installed
+> via `uv`), replace the `repowise update` line with:
+> ```bash
+> powershell.exe -Command "uv run repowise update" > /tmp/repowise-update.log 2>&1
+> ```
+
+### What happens
+
+1. You run `git commit`
+2. The hook fires in the background
+3. `repowise update` diffs the new commit against the last synced commit
+4. Only affected pages are regenerated (typically 3-10 for a small commit)
+5. Output is logged to `/tmp/repowise-update.log`
+
+### Check the last run
+
+```bash
+cat /tmp/repowise-update.log
+```
+
+### Remove the hook
+
+```bash
+rm .git/hooks/post-commit
+```
+
+---
+
+## 2. File Watcher
+
+Watches your working directory for file saves and auto-updates. Useful during
+active development when you want the wiki to stay current without committing.
+
+```bash
+repowise watch # watch current directory
+repowise watch /path/to/repo
+repowise watch --debounce 5000 # wait 5s after last change (default: 2s)
+```
+
+Press `Ctrl+C` to stop.
+
+Changes to files inside `.repowise/` are ignored to prevent update loops.
+
+---
+
+## 3. GitHub Webhook
+
+For teams or hosted deployments. GitHub sends a push event to your repowise
+server, which triggers an incremental update.
+
+### Prerequisites
+
+- repowise server running and reachable from the internet (or GitHub's network)
+- A webhook secret (recommended for production)
+
+### Start the server
+
+```bash
+repowise serve # http://localhost:7337
+repowise serve --host 0.0.0.0 --port 8080 # custom bind
+```
+
+### Configure the webhook secret
+
+```bash
+export REPOWISE_GITHUB_WEBHOOK_SECRET="your-secret-here"
+```
+
+### Add the webhook in GitHub
+
+1. Go to your repo **Settings > Webhooks > Add webhook**
+2. **Payload URL:** `https://your-server.example.com/api/webhooks/github`
+3. **Content type:** `application/json`
+4. **Secret:** the same value you set in `REPOWISE_GITHUB_WEBHOOK_SECRET`
+5. **Events:** select **Just the push event**
+6. Click **Add webhook**
+
+### Verify it works
+
+Push a commit and check the webhook delivery in GitHub (Settings > Webhooks >
+Recent Deliveries). You should see a `200` response with:
+
+```json
+{
+ "event_id": "...",
+ "status": "accepted"
+}
+```
+
+### Security
+
+When `REPOWISE_GITHUB_WEBHOOK_SECRET` is set, every incoming request is
+verified using HMAC-SHA256 against the `X-Hub-Signature-256` header. Requests
+with invalid or missing signatures are rejected with `401 Unauthorized`.
+
+If the secret is **not** set, signature verification is skipped (convenient for
+local development, but not recommended for production).
+
+---
+
+## 4. GitLab Webhook
+
+Same concept as GitHub, different endpoint and auth mechanism.
+
+### Configure the webhook token
+
+```bash
+export REPOWISE_GITLAB_WEBHOOK_TOKEN="your-token-here"
+```
+
+### Add the webhook in GitLab
+
+1. Go to your project **Settings > Webhooks**
+2. **URL:** `https://your-server.example.com/api/webhooks/gitlab`
+3. **Secret token:** the same value you set in `REPOWISE_GITLAB_WEBHOOK_TOKEN`
+4. **Trigger:** enable **Push events**
+5. Click **Add webhook**
+
+### Security
+
+When `REPOWISE_GITLAB_WEBHOOK_TOKEN` is set, the server compares it against
+the `X-Gitlab-Token` header using constant-time comparison. Invalid tokens are
+rejected with `401 Unauthorized`.
+
+---
+
+## 5. Polling Fallback
+
+When the server is running, a background job polls all registered repositories
+every 15 minutes. If new commits are detected that weren't caught by webhooks
+(e.g. webhook delivery failed), it triggers an incremental update automatically.
+
+No configuration needed -- this runs automatically when you start the server
+with `repowise serve`.
+
+---
+
+## How Incremental Updates Work
+
+Regardless of which trigger method you use, the update process is the same:
+
+1. **Diff** -- compare the new HEAD against the last synced commit
+2. **Detect affected pages** -- find directly changed files, then cascade to
+ files that import them (1-hop), capped at 30 pages per run
+3. **Regenerate** -- call the LLM only for affected pages
+4. **Persist** -- update the database and search index
+5. **Save state** -- record the new HEAD as the last synced commit
+
+A typical single-commit update touches 3-10 pages and completes in under a
+minute.
+
+### Dry run
+
+To see what would be updated without actually regenerating:
+
+```bash
+repowise update --dry-run
+```
+
+### Manual update
+
+```bash
+repowise update # diff since last sync
+repowise update --since abc123 # diff from a specific commit
+repowise update --cascade-budget 50 # allow more cascade pages (default: 30)
+```
+
+---
+
+## Environment Variables Reference
+
+| Variable | Used by | Description |
+|----------|---------|-------------|
+| `GEMINI_API_KEY` | CLI | API key for Gemini LLM provider |
+| `OPENAI_API_KEY` | CLI | API key for OpenAI LLM provider |
+| `ANTHROPIC_API_KEY` | CLI | API key for Anthropic LLM provider |
+| `REPOWISE_GITHUB_WEBHOOK_SECRET` | Server | HMAC secret for GitHub webhook verification |
+| `REPOWISE_GITLAB_WEBHOOK_TOKEN` | Server | Token for GitLab webhook verification |
+| `REPOWISE_DB_URL` | Server | Database URL (default: local SQLite) |
+| `REPOWISE_API_KEY` | Server | Bearer token for API authentication |
+
+API keys can also be stored in `.repowise/.env` (auto-gitignored) during
+`repowise init`. The `update` and `reindex` commands load this file
+automatically.
+
+---
+
+## Troubleshooting
+
+**"No previous sync found"** -- Run `repowise init` first to create the
+initial wiki before using any auto-sync method.
+
+**"Already up to date"** -- The wiki is already synced to the latest commit.
+Nothing to do.
+
+**Hook doesn't fire** -- Make sure the hook file is executable:
+`chmod +x .git/hooks/post-commit`
+
+**Webhook returns 401** -- Check that the secret/token matches between your
+git hosting provider and the environment variable on the server.
+
+**Update is slow** -- If you're catching up on many commits, the first update
+may take longer. Subsequent single-commit updates are fast (~30-60s).
diff --git a/docs/EDITOR_FILES.md b/docs/EDITOR_FILES.md
new file mode 100644
index 000000000..02c11a459
--- /dev/null
+++ b/docs/EDITOR_FILES.md
@@ -0,0 +1,498 @@
+# Editor File Generation
+
+repowise can generate and maintain AI-editor configuration files — CLAUDE.md,
+cursor.md, and similar — from the already-indexed codebase data. No LLM calls
+are made. All content is derived from the repowise SQL database and filesystem
+manifests.
+
+---
+
+## Table of Contents
+
+1. [Why this exists](#1-why-this-exists)
+2. [How it works](#2-how-it-works)
+3. [The two-section file structure](#3-the-two-section-file-structure)
+4. [What goes into the Repowise section](#4-what-goes-into-the-repowise-section)
+5. [Data sources](#5-data-sources)
+6. [File reference](#6-file-reference)
+7. [CLI usage](#7-cli-usage)
+8. [REST API](#8-rest-api)
+9. [Configuration](#9-configuration)
+10. [Adding a new editor file](#10-adding-a-new-editor-file)
+
+---
+
+## 1. Why this exists
+
+Claude Code reads `CLAUDE.md` on every session start but does not proactively
+call MCP tools — even when an MCP server is configured. Users have to explicitly
+tell Claude Code to "use MCP" every time.
+
+By embedding codebase intelligence and MCP workflow guidance directly into
+`CLAUDE.md`, Claude Code treats it as project context and naturally reaches for
+Repowise tools without being prompted.
+
+The same principle applies to Cursor's `.cursor/rules` / `cursor.md`, GitHub
+Copilot's `.github/copilot-instructions.md`, and any other file an AI editor
+auto-loads at session start.
+
+---
+
+## 2. How it works
+
+```
+repowise init (or update)
+ │
+ ▼
+All wiki pages and git metadata already persisted in DB
+ │
+ ▼
+EditorFileDataFetcher
+ Queries DB for: architecture summary, top modules by PageRank,
+ entry points, hotspot files, active decision records
+ Scans filesystem for: tech stack, build commands
+ Returns: EditorFileData (frozen dataclass, no DB types)
+ │
+ ▼
+ClaudeMdGenerator.write(repo_path, data)
+ Renders claude_md.j2 template with EditorFileData
+ Reads existing CLAUDE.md (if any)
+ Merges: user content preserved, Repowise section replaced
+ Writes atomically (temp file + rename)
+ │
+ ▼
+CLAUDE.md written to repo root
+```
+
+**Key properties:**
+- Runs after `_persist()` completes, so all data is current
+- Best-effort in `repowise update` — never fails the command
+- Instant — no LLM calls, typically < 200ms
+- Idempotent — re-running produces identical output if data hasn't changed
+- Deterministic — lists sorted by stable keys (PageRank desc, path asc as tiebreaker)
+
+---
+
+## 3. The two-section file structure
+
+```markdown
+# CLAUDE.md
+
+<!-- Add your custom instructions below.
+ Repowise will never modify anything outside the REPOWISE markers. -->
+<!-- Examples: coding style rules, test commands, workflow preferences -->
+
+[user's own content — untouched by repowise]
+
+<!-- REPOWISE:START — Do not edit below this line. Auto-generated by Repowise. -->
+## Codebase Intelligence — myrepo (Repowise)
+
+[auto-generated content]
+<!-- REPOWISE:END -->
+```
+
+**Merge rules (applied in `BaseEditorFileGenerator.write()`):**
+
+| Situation | Action |
+|-----------|--------|
+| No CLAUDE.md exists | Create with user placeholder + Repowise section |
+| File exists, no markers | Append Repowise section at bottom; leave existing content untouched |
+| File exists with markers | Replace only the content between `REPOWISE:START` and `REPOWISE:END` |
+
+The regex used for marker replacement:
+
+```python
+pattern = re.escape(MARKER_START) + r".*?" + re.escape(MARKER_END)
+re.sub(pattern, new_wrapped_content, existing, flags=re.DOTALL)
+```
+
+This is the entire preservation strategy. The only way to lose user content is
+to manually insert text *inside* the `REPOWISE:START` / `REPOWISE:END` block,
+which the placeholder comment warns against.
+
+---
+
+## 4. What goes into the Repowise section
+
+The section has three parts. Total target length: **150–250 lines**. Conciseness
+is intentional — research shows AI assistants ignore bloated configuration files.
+
+### Part 1: Codebase Intelligence
+
+Auto-generated from indexed data. Updates on every `repowise update`.
+
+| Sub-section | Source | Cap |
+|-------------|--------|-----|
+| Architecture summary | First 4 sentences from `repo_overview` wiki page | 4 sentences |
+| Key Modules | `module_page` pages sorted by PageRank desc, joined with git_metadata for owner | Top 10 |
+| Entry Points | `graph_nodes` where `is_entry_point=True`, sorted by PageRank desc | Top 10 |
+| Tech Stack | Filesystem scan (package.json, pyproject.toml, Cargo.toml, go.mod, etc.) | All detected |
+| Hotspots | `git_metadata` where `is_hotspot=True`, sorted by `churn_percentile` desc | Top 5 |
+
+### Part 2: MCP Tools Workflow Guide
+
+**Static** — the same text for every repo. Hardcoded in `claude_md.j2`. Teaches
+Claude Code *when* to call each MCP tool using natural workflow framing rather than
+imperatives.
+
+This is the most important part. The phrasing matters: "Starting a new task?
+Call `get_overview()` first" is more effective than "ALWAYS call `get_overview()`
+before doing anything."
+
+### Part 3: Codebase Conventions
+
+Auto-generated from indexed data.
+
+| Sub-section | Source | Cap |
+|-------------|--------|-----|
+| Architectural Decisions | `decision_records` where `status='active'`, sorted by `staleness_score` asc | Top 8 |
+| Commands | Filesystem scan: `package.json` scripts, `Makefile` targets, `pyproject.toml` pytest/ruff | All detected |
+
+---
+
+## 5. Data sources
+
+### Database queries (in `EditorFileDataFetcher`)
+
+**Architecture summary** (`_get_architecture_summary`)
+```python
+crud.list_pages(session, repo_id, page_type="repo_overview", limit=1)
+# → extracts first 4 sentences, strips markdown headers/code fences
+```
+
+**Key modules** (`_get_key_modules`)
+```python
+SELECT page, GraphNode.pagerank, GraphNode.symbol_count
+FROM wiki_pages
+JOIN graph_nodes ON graph_nodes.node_id = wiki_pages.target_path
+WHERE wiki_pages.page_type = 'module_page'
+ AND wiki_pages.repository_id = :repo_id
+ORDER BY graph_nodes.pagerank DESC NULLS LAST
+LIMIT 10
+# → owner resolved via separate git_metadata lookup
+```
+
+**Entry points** (`_get_entry_points`)
+```python
+SELECT node_id FROM graph_nodes
+WHERE repository_id = :repo_id AND is_entry_point = TRUE
+ORDER BY pagerank DESC
+LIMIT 10
+```
+
+**Hotspots** (`_get_hotspots`)
+```python
+SELECT file_path, churn_percentile, commit_count_90d, primary_owner_name
+FROM git_metadata
+WHERE repository_id = :repo_id AND is_hotspot = TRUE
+ORDER BY churn_percentile DESC, file_path ASC -- deterministic tie-break
+LIMIT 5
+```
+
+**Active decisions** (`_get_decisions`)
+```python
+SELECT * FROM decision_records
+WHERE repository_id = :repo_id AND status = 'active'
+ORDER BY staleness_score ASC
+LIMIT 8
+# → uses first 100 chars of rationale field
+```
+
+**Average confidence** (`_get_avg_confidence`)
+```python
+SELECT AVG(confidence) FROM wiki_pages WHERE repository_id = :repo_id
+```
+
+### Filesystem scan (in `tech_stack.py`)
+
+`detect_tech_stack(repo_path)` scans the repo root for:
+
+| File | Detects |
+|------|---------|
+| `package.json` | Node.js, TypeScript, React, Next.js, Vue, Express, Prisma, Tailwind, … |
+| `pyproject.toml` / `setup.py` | Python, FastAPI, Django, Flask, SQLAlchemy, Celery, … |
+| `Cargo.toml` | Rust |
+| `go.mod` | Go (extracts version from `go X.Y` directive) |
+| `pom.xml` / `build.gradle` | Java / Kotlin + Maven / Gradle |
+| `Gemfile` | Ruby |
+| `composer.json` | PHP |
+| `Dockerfile` | Docker |
+| `docker-compose.yml` | Docker Compose |
+
+`detect_build_commands(repo_path)` returns a dict with keys from:
+`build`, `test`, `lint`, `dev`, `format`, `typecheck`.
+
+Priority: `package.json` scripts → `pyproject.toml` → `Makefile`. Each key is
+only set once — the first source wins.
+
+---
+
+## 6. File reference
+
+```
+packages/core/src/repowise/core/generation/editor_files/
+├── __init__.py Exports: ClaudeMdGenerator, EditorFileData, EditorFileDataFetcher
+├── base.py BaseEditorFileGenerator — marker-merge logic, Jinja2 setup, atomic write
+├── data.py Frozen dataclasses: EditorFileData, TechStackItem, KeyModule,
+│ HotspotFile, DecisionSummary
+├── fetcher.py EditorFileDataFetcher — all DB queries + filesystem calls
+├── tech_stack.py detect_tech_stack(), detect_build_commands()
+└── claude_md.py ClaudeMdGenerator — filename, marker_tag, template_name, user_placeholder
+
+packages/core/src/repowise/core/generation/templates/
+└── claude_md.j2 Jinja2 template for the Repowise-managed section
+
+packages/cli/src/repowise/cli/commands/
+├── claude_md_cmd.py `repowise generate-claude-md` command
+└── init_cmd.py _maybe_generate_claude_md(), _write_claude_md_async() helpers
+
+packages/server/src/repowise/server/routers/
+└── claude_md.py GET/POST /api/repos/{repo_id}/claude-md
+
+tests/unit/generation/
+├── test_editor_file_base.py Marker-merge logic, idempotency, file structure
+├── test_editor_file_fetcher.py DB query correctness with in-memory SQLite
+└── test_tech_stack.py Filesystem detection with tmp_path fixtures
+```
+
+### Class hierarchy
+
+```
+BaseEditorFileGenerator (base.py)
+│ filename: str — abstract property
+│ marker_tag: str — abstract property
+│ template_name: str — abstract property
+│ user_placeholder: str — abstract property
+│ render(data) → str
+│ write(repo_path, data) → Path
+│ render_full(repo_path, data) → str
+│
+└── ClaudeMdGenerator (claude_md.py)
+ filename = "CLAUDE.md"
+ marker_tag = "REPOWISE"
+ template_name = "claude_md.j2"
+ user_placeholder = "# CLAUDE.md\n\n<!-- ... -->\n"
+```
+
+### Data flow
+
+```
+EditorFileDataFetcher.fetch()
+ │ AsyncSession + repo_id + repo_path
+ │
+ ├── crud.get_repository() → repo.name
+ ├── _get_architecture_summary() → str (2-4 sentences)
+ ├── _get_key_modules() → list[KeyModule]
+ ├── _get_entry_points() → list[str]
+ ├── detect_tech_stack() → list[TechStackItem]
+ ├── _get_hotspots() → list[HotspotFile]
+ ├── _get_decisions() → list[DecisionSummary]
+ ├── detect_build_commands() → dict[str, str]
+ └── _get_avg_confidence() → float
+ │
+ ▼
+EditorFileData (frozen dataclass)
+ │
+ ▼
+BaseEditorFileGenerator.render(data)
+ │ Jinja2 template rendered with data
+ ▼
+str (managed section content, without markers)
+ │
+ ▼
+BaseEditorFileGenerator.write(repo_path, data)
+ │ Wraps with markers, merges with existing file
+ ▼
+Path (written file)
+```
+
+---
+
+## 7. CLI usage
+
+```
+repowise generate-claude-md [PATH]
+ PATH Repo root to generate for (default: current directory)
+ --output FILE Write to a custom path instead of CLAUDE.md in repo root
+ --stdout Print generated content to stdout (does not write a file)
+```
+
+Examples:
+
+```bash
+# Generate CLAUDE.md for the current directory
+repowise generate-claude-md .
+
+# Preview what would be written without touching the file
+repowise generate-claude-md . --stdout
+
+# Write to a custom path
+repowise generate-claude-md /path/to/repo --output /tmp/preview.md
+```
+
+**Auto-generation during `init` and `update`:**
+
+`repowise init` generates CLAUDE.md after the persistence phase completes.
+`repowise update` regenerates it (best-effort) after each incremental sync.
+
+Both can be disabled:
+
+```bash
+# Skip CLAUDE.md on this init run and persist the preference to config
+repowise init --no-claude-md .
+```
+
+---
+
+## 8. REST API
+
+### `GET /api/repos/{repo_id}/claude-md`
+
+Returns the generated Repowise section as JSON. Does not write to disk.
+Useful for web UI preview.
+
+```json
+{
+ "content": "## Codebase Intelligence — myrepo (Repowise)\n...",
+ "generated_at": "2026-03-28",
+ "repo_name": "myrepo",
+ "sections": ["Architecture", "Key Modules", "Entry Points", "Tech Stack",
+ "Hotspots (High Churn)", "Repowise MCP Tools", "Codebase Conventions"]
+}
+```
+
+### `POST /api/repos/{repo_id}/claude-md/generate`
+
+Regenerates CLAUDE.md and writes it to the repository's `local_path` on disk.
+Returns 422 if `local_path` is not accessible from the server.
+
+```json
+{
+ "status": "generated",
+ "path": "/home/user/myrepo/CLAUDE.md",
+ "generated_at": "2026-03-28"
+}
+```
+
+---
+
+## 9. Configuration
+
+```yaml
+# .repowise/config.yaml
+editor_files:
+ claude_md: true # default: true. Set false to disable entirely.
+```
+
+The `--no-claude-md` CLI flag sets `editor_files.claude_md: false` in
+`config.yaml` and all future `repowise update` runs will skip it.
+
+---
+
+## 10. Adding a new editor file
+
+Example: adding `cursor.md` support.
+
+### Step 1 — Create the subclass
+
+**`packages/core/src/repowise/core/generation/editor_files/cursor_md.py`**
+
+```python
+from .base import BaseEditorFileGenerator
+
+class CursorMdGenerator(BaseEditorFileGenerator):
+ filename = "cursor.md"
+ marker_tag = "REPOWISE"
+ template_name = "cursor_md.j2"
+ user_placeholder = (
+ "# cursor.md\n\n"
+ "<!-- Add your Cursor rules below. "
+ "Repowise will never modify anything outside the REPOWISE markers. -->\n"
+ )
+```
+
+That's the entire subclass. All merge logic, atomic write, Jinja2 setup, and
+`render()` / `write()` / `render_full()` are inherited from `BaseEditorFileGenerator`.
+
+### Step 2 — Create the template
+
+**`packages/core/src/repowise/core/generation/templates/cursor_md.j2`**
+
+The template receives `data` (an `EditorFileData` instance). All fields are
+the same as `claude_md.j2` — the fetcher is shared. Write cursor-specific
+framing around the same data.
+
+Minimal starting point:
+
+```jinja2
+## Project Context (Repowise)
+Last indexed: {{ data.indexed_at }}.
+
+{% if data.architecture_summary %}
+### Architecture
+{{ data.architecture_summary }}
+{% endif %}
+
+### Key Files
+{% for ep in data.entry_points %}
+- `{{ ep }}`
+{% endfor %}
+```
+
+### Step 3 — Add config key
+
+```yaml
+# .repowise/config.yaml
+editor_files:
+ claude_md: true
+ cursor_md: true # NEW
+```
+
+### Step 4 — Export from the subpackage
+
+**`packages/core/src/repowise/core/generation/editor_files/__init__.py`**
+
+```python
+from .cursor_md import CursorMdGenerator # add this line
+```
+
+### Step 5 — Hook into init and update
+
+In `_maybe_generate_claude_md()` (or extract a more generic
+`_maybe_generate_editor_files()` helper):
+
+```python
+# After existing CLAUDE.md generation
+if cfg.get("editor_files", {}).get("cursor_md", False): # default off
+ from repowise.core.generation.editor_files import CursorMdGenerator
+ CursorMdGenerator().write(repo_path, data)
+```
+
+Since `data` is already fetched by this point (reuse from CLAUDE.md generation),
+the cursor.md write costs only the template render — no extra DB queries.
+
+### Step 6 — Add a REST endpoint (optional)
+
+Follow `packages/server/src/repowise/server/routers/claude_md.py` exactly.
+Swap `ClaudeMdGenerator` for `CursorMdGenerator`. Register the router in `app.py`.
+
+### Step 7 — Add tests
+
+Follow `tests/unit/generation/test_editor_file_base.py`. The `_TestGenerator`
+fixture already tests `BaseEditorFileGenerator` behavior — add a test that
+instantiates `CursorMdGenerator` directly to verify the filename/marker_tag/
+template_name properties and that the template renders without error.
+
+---
+
+### What you do NOT need to do
+
+- Write any DB queries — `EditorFileDataFetcher` and `EditorFileData` are shared.
+- Write any file I/O or merge logic — `BaseEditorFileGenerator` handles everything.
+- Register a new CLI command — use `generate-claude-md` as a reference if you
+ want a standalone command, but it is not required.
+- Update the ORM schema — no new tables needed.
+
+The only required artifacts for a new editor file are:
+1. A 10–30 line subclass (`*.py`)
+2. A Jinja2 template (`*.j2`)
diff --git a/docs/MCP_FIX_PLAN.md b/docs/MCP_FIX_PLAN.md
deleted file mode 100644
index 28d142fec..000000000
--- a/docs/MCP_FIX_PLAN.md
+++ /dev/null
@@ -1,562 +0,0 @@
-# MCP Tools Fix Plan
-
-Based on: [MCP_TOOLS_TEST_REPORT.md](./MCP_TOOLS_TEST_REPORT.md)
-
----
-
-## Phase 1: Low-Hanging Fruit (Quick Wins)
-
-These fixes are localized, low-risk, and can be done independently.
-
----
-
-### 1.1 — Shorter node labels in architecture diagrams
-
-**Issue:** Node IDs like `packages_core_src_repowise_core_persistence_models_py` are unreadable in rendered diagrams.
-
-**File:** `packages/server/src/repowise/server/mcp_server.py` — lines 2347, 2353
-
-**Current:**
-```python
-lines.append(f' {src}["{e.source_node_id}"]')
-```
-
-**Fix:** Extract a short label (filename or `parent/filename`) from the full node ID:
-```python
-def _short_label(node_id: str) -> str:
- """e.g. 'packages/core/src/.../models.py' → 'persistence/models.py'"""
- parts = node_id.replace("\\", "/").split("/")
- if len(parts) >= 2:
- return "/".join(parts[-2:])
- return parts[-1]
-
-# In diagram builder:
-lines.append(f' {src}["{_short_label(e.source_node_id)}"]')
-```
-
-**Effort:** ~15 min | **Risk:** None — cosmetic change
-
----
-
-### 1.2 — Exclude test fixtures from entry points
-
-**Issue:** `go_pkg/main.go` and `rust_pkg/src/lib.rs` from `tests/fixtures/` appear as entry points in `get_overview`.
-
-**File:** `packages/server/src/repowise/server/mcp_server.py` — lines 477-484
-
-**Current:** Queries `GraphNode.is_entry_point == True` with no test exclusion.
-
-**Fix:** Add filter to exclude nodes under test/fixture directories:
-```python
-result = await session.execute(
- select(GraphNode).where(
- GraphNode.repository_id == repository.id,
- GraphNode.is_entry_point == True,
- GraphNode.is_test == False, # Add this
- )
-)
-entry_nodes = result.scalars().all()
-
-# Then also filter fixture paths in Python:
-entry_nodes = [
- n for n in entry_nodes
- if "fixture" not in n.node_id.lower()
- and "test_data" not in n.node_id.lower()
-]
-```
-
-**Also check:** `GraphNode` model has `is_test` column. Verify at:
-- `packages/core/src/repowise/core/persistence/models.py` — `GraphNode` model
-- `packages/core/src/repowise/core/ingestion/graph.py` — line ~65 where `is_test` is stored
-
-**Effort:** ~20 min | **Risk:** Low
-
----
-
-### 1.3 — Add framework-loaded files to dead code skip list
-
-**Issue:** `conftest.py` (pytest), `alembic/env.py` (alembic), `__main__.py` flagged as dead code.
-
-**File:** `packages/core/src/repowise/core/analysis/dead_code.py` — lines 71-77
-
-**Current:**
-```python
-_NEVER_FLAG_PATTERNS = (
- "*__init__.py",
- "*migrations*",
- "*schema*",
- "*seed*",
- "*.d.ts",
-)
-```
-
-**Fix:** Extend the list:
-```python
-_NEVER_FLAG_PATTERNS = (
- "*__init__.py",
- "*__main__.py", # Python entry points
- "*conftest.py", # pytest auto-loaded
- "*alembic/env.py", # Alembic migration framework
- "*manage.py", # Django management
- "*wsgi.py", # WSGI entry points
- "*asgi.py", # ASGI entry points
- "*migrations*",
- "*schema*",
- "*seed*",
- "*.d.ts",
-)
-```
-
-**Effort:** ~10 min | **Risk:** None — adds safety, doesn't remove anything
-
----
-
-### 1.4 — Exclude test fixture directories from dead code findings
-
-**Issue:** Files in `tests/fixtures/sample_repo/` flagged as dead with `"File has no importers"`.
-
-**File:** `packages/core/src/repowise/core/analysis/dead_code.py` — line 227
-
-**Current:** Checks `is_test` flag but test fixtures aren't always tagged as test files (they're sample data, not test code).
-
-**Fix:** Add fixture directory check in `_detect_unreachable_files`:
-```python
-# After the is_test check at line 227-228:
-if self._is_fixture_path(str(node)):
- continue
-
-# New method:
-_FIXTURE_PATTERNS = ("fixture", "testdata", "test_data", "mock_data", "sample_repo")
-
-def _is_fixture_path(self, path: str) -> bool:
- path_lower = path.lower()
- return any(pat in path_lower for pat in self._FIXTURE_PATTERNS)
-```
-
-**Effort:** ~15 min | **Risk:** Low — may miss some genuine dead code in fixture-named dirs, but that's the safer direction
-
----
-
-### 1.5 — Remove or label hardcoded `confidence_score: 1.0` in search results
-
-**Issue:** `confidence_score` is always `1.0` (from `Page.confidence` default) or `None`. Provides no signal.
-
-**File:** `packages/server/src/repowise/server/mcp_server.py` — line 1743
-
-**Current:** `item["confidence_score"] = info[0] if info else None` — reads from `Page.confidence` which defaults to `1.0`.
-
-**Fix (option A — quick):** Remove the field entirely from search output since it's not useful:
-```python
-# Remove confidence_score from the output dict at line 1711
-# Remove the batch lookup for confidence at lines 1718-1726
-```
-
-**Fix (option B — meaningful):** Replace with a normalized relevance indicator derived from the actual search score distribution:
-```python
-if output:
- max_score = max(item["relevance_score"] for item in output if item.get("relevance_score"))
- for item in output:
- raw = item.get("relevance_score", 0) or 0
- item["confidence_score"] = round(raw / max_score, 2) if max_score > 0 else 0.0
-```
-
-**Effort:** ~20 min | **Risk:** Low — consumers may check for this field, but it was always 1.0 so no one is branching on it
-
----
-
-### 1.6 — Clip external nodes at module boundary in diagrams
-
-**Issue:** Module-scoped diagram for `packages/core` includes files from `packages/server` and `tests/fixtures` because it follows imports across boundaries.
-
-**File:** `packages/server/src/repowise/server/mcp_server.py` — around line 2343
-
-**Current:** All edges in `relevant_edges` are rendered, including cross-module ones.
-
-**Fix:** For module-scoped diagrams, replace external nodes with a single `external` stub:
-```python
-# When building the edge list for module scope:
-for e in relevant_edges[:50]:
- src_id = e.source_node_id
- tgt_id = e.target_node_id
- # Clip cross-module edges
- if path and not src_id.startswith(path):
- src_id = "external"
- if path and not tgt_id.startswith(path):
- tgt_id = "external"
- # ... render with clipped IDs
-```
-
-**Effort:** ~30 min | **Risk:** Low
-
----
-
-## Phase 2: Important Data Quality Fixes
-
-These require more careful changes but fix the most impactful quality issues.
-
----
-
-### 2.1 — `get_why` timeout wrapper for all modes
-
-**Issue:** File-path mode and health dashboard mode hang indefinitely. 2 of 4 test calls had to be cancelled.
-
-**Files:**
-- `packages/server/src/repowise/server/mcp_server.py` — lines 1230-1269 (Mode 1), 1272-1333 (Mode 2), 1335-1474 (Mode 3)
-
-**Root causes:**
-1. **Mode 2 (path):** `all_git_meta` at line 1292-1297 loads entire `GitMetadata` table with no LIMIT. For large repos this is slow.
-2. **`_git_archaeology_fallback`** at lines 1549-1574: Iterates all git metadata with an O(files × commits) inner loop. No timeout wrapper.
-3. **Mode 3 (NL + targets):** Repeats the same unbounded git metadata load at lines 1443-1448.
-
-**Fix — multi-layered:**
-
-**A. Add overall timeout to the `get_why` handler:**
-```python
-async def get_why(query: str | None = None, targets: list[str] | None = None, repo: str | None = None):
- try:
- return await asyncio.wait_for(_get_why_impl(query, targets, repo), timeout=30.0)
- except asyncio.TimeoutError:
- return {"error": "get_why timed out after 30s", "mode": "timeout", "query": query}
-```
-
-**B. Limit the `all_git_meta` query:**
-```python
-# Line 1292-1296: Add LIMIT
-all_git_res = await session.execute(
- select(GitMetadata).where(
- GitMetadata.repository_id == repository.id,
- ).limit(500) # Cap cross-file search space
-)
-```
-
-**C. Add timeout to `_git_archaeology_fallback`:**
-```python
-async def _git_archaeology_fallback(...) -> dict:
- try:
- return await asyncio.wait_for(_git_archaeology_impl(...), timeout=10.0)
- except asyncio.TimeoutError:
- return {"triggered": True, "summary": "Git archaeology timed out.", ...}
-```
-
-**D. Limit the cross-file loop iteration:**
-```python
-# Line 1549: Cap iteration
-for gm in all_git_meta[:500]:
-```
-
-**Effort:** ~1-2 hours | **Risk:** Medium — timeout values need tuning. Test with large repos.
-
----
-
-### 2.2 — Filter `get_why` decisions by relevance
-
-**Issue:** Query "why does the parser use tree-sitter?" returns decisions about Jinja2, SQLite, streaming protocol. Core promise broken.
-
-**File:** `packages/server/src/repowise/server/mcp_server.py` — lines 1369-1375
-
-**Root cause:** `_score_decision` (line 1477) does simple word overlap. Words like "use", "parser" match too broadly. Any decision mentioning common words gets a nonzero score, and all nonzero decisions are returned.
-
-**Fix — add minimum score threshold:**
-```python
-# After scoring all decisions (line 1374):
-scored_decisions.sort(key=lambda t: t[0], reverse=True)
-
-# Add threshold: require at least 2 keyword matches worth of score
-MIN_DECISION_SCORE = 3.0 # At least one title match or two field matches
-scored_decisions = [(s, d) for s, d in scored_decisions if s >= MIN_DECISION_SCORE]
-
-keyword_matches = [d for _, d in scored_decisions[:8]]
-```
-
-**Also improve `_score_decision`:**
-```python
-def _score_decision(d, query_words, target_files):
- if not query_words:
- return 1.0 if target_files else 0.0
-
- # Require at least 2 matching words for non-title fields (reduces noise)
- matching_word_count = 0
- for weight, text in fields:
- for word in query_words:
- if word in text:
- matching_word_count += 1
- score += weight
-
- # Penalize if only 1 word matched across all fields (too loose)
- if matching_word_count == 1 and score < 3.0:
- score *= 0.3
-
- return score
-```
-
-**Effort:** ~1 hour | **Risk:** Medium — threshold tuning needed. Too high → misses real matches.
-
----
-
-### 2.3 — Search relevance threshold for nonsense queries
-
-**Issue:** Gibberish query `"xyznonexistent gibberish query"` returns 3 results with scores 2.4-3.4 and no low-confidence indicator.
-
-**File:** `packages/server/src/repowise/server/mcp_server.py` — after line 1715
-
-**Fix:** Add a minimum relevance score threshold and a flag:
-```python
-output = output[:limit]
-
-# Filter results below relevance threshold
-MIN_RELEVANCE = 1.5 # Tuned: real matches typically score 3+
-if output:
- top_score = output[0]["relevance_score"] if output[0].get("relevance_score") else 0
- if top_score < MIN_RELEVANCE:
- return {"results": [], "low_confidence": True,
- "message": "No results met the relevance threshold."}
-```
-
-**Alternative — softer approach:** Keep results but add a flag:
-```python
-LOW_CONFIDENCE_THRESHOLD = 2.0
-low_confidence = all(
- (item.get("relevance_score") or 0) < LOW_CONFIDENCE_THRESHOLD
- for item in output
-)
-return {"results": output, "low_confidence": low_confidence}
-```
-
-**Effort:** ~30 min | **Risk:** Low — threshold needs calibration against real queries
-
----
-
-### 2.4 — Fix ownership attribution gaps
-
-**Issue:** Files with clear git history show `primary_owner: null` across `get_context`, `get_risk`, and `get_dead_code`.
-
-**Files:**
-- `packages/core/src/repowise/core/ingestion/git_indexer.py` — lines 250-262, 410-527
-
-**Root causes identified:**
-1. **45-second per-file timeout** (line 161, 250-254): If git blame takes >45s, file returns with all-null ownership fields. On Windows especially, blame can be slow for large files.
-2. **Blame-only for files ≤100KB** (line 521): Large files skip blame entirely.
-3. **Empty commit list** (line 437-439): If `_get_commits()` returns empty (e.g. file only in working tree, not committed), all fields stay null.
-
-**Fix — multi-part:**
-
-**A. Increase blame timeout or make it configurable:**
-```python
-_FILE_INDEX_TIMEOUT_SECS: float = 90.0 # Up from 45
-```
-
-**B. Ensure commit-based ownership is preserved even when blame fails:**
-```python
-# In _index_file, after lines 498-503 (commit-based owner set):
-commit_owner_name = top_authors[0]["name"]
-commit_owner_email = top_authors[0]["email"]
-commit_owner_pct = top_authors[0]["commit_count"] / total_commits
-
-# Lines 514-527: Only override if blame succeeds
-try:
- blame_result = await self._get_blame_ownership(...)
- if blame_result[0] is not None: # Only override if blame returned data
- meta["primary_owner_name"] = blame_result[0]
- ...
-except Exception:
- pass # Keep commit-based ownership as fallback
-```
-
-**C. On timeout, still save partial data:** Instead of returning just `{"file_path": file_path}` on timeout, save whatever partial ownership data was already computed.
-
-**D. Surface `last_change` data properly** (related issue from test report):
-- Check `get_context` handler for `last_change` with `date: null, days_ago: 0`
-- Ensure `GitMetadata.last_commit_at` is populated even when blame fails
-
-**Effort:** ~2-3 hours | **Risk:** Medium — timeout changes may slow init on large repos
-
----
-
-### 2.5 — Populate `affected_files` for README-mined decisions
-
-**Issue:** All README-sourced decisions have `affected_files: []`, making target-aware `get_why` non-functional.
-
-**File:** `packages/core/src/repowise/core/analysis/decision_extractor.py` — lines 464-529
-
-**Root cause:** `mine_readme_docs()` at lines 519-521 uses `_infer_modules_from_text()` for `affected_modules` but never sets `affected_files`. Unlike `scan_inline_markers()` (which calls `_get_neighbors()`) and `mine_git_archaeology()` (which uses `commit_files`), README mining has no file-level resolution.
-
-**Fix:** After setting `affected_modules`, resolve module paths to actual files:
-```python
-# After line 521:
-d.affected_modules = self._infer_modules_from_text(section_text)
-
-# New: resolve modules to files
-affected_files = set()
-for mod in d.affected_modules:
- for node in self._graph.nodes():
- if str(node).startswith(mod + "/") or str(node) == mod:
- affected_files.add(str(node))
- if len(affected_files) >= 20:
- break
-d.affected_files = list(affected_files)
-```
-
-**Effort:** ~1 hour | **Risk:** Medium — may produce noisy file lists if modules are broad
-
----
-
-## Phase 3: Deeper Structural Improvements
-
-These require more design consideration and testing.
-
----
-
-### 3.1 — Meaningful confidence scores across tools
-
-**Issue:** Flat confidence values: `1.0` in search, `0.6` in decisions, `0.7` in dead code. No differentiation.
-
-**Current state by tool:**
-
-| Tool | Source | Value | Location |
-|------|--------|-------|----------|
-| `search_codebase` | `Page.confidence` | Default `1.0`, linear decay over 30 days | `models.py:112` |
-| `get_why` | `DecisionRecord.confidence` | Hardcoded per source type | `decision_extractor.py` |
-| `get_dead_code` | Dead code analyzer | `1.0` / `0.7` / `0.4` by commit recency | `dead_code.py:259-265` |
-
-**Fix approach:**
-
-**A. Decisions:** Vary by source + evidence quality:
-- `inline_marker` (code comments): 0.95 — developer explicitly wrote this
-- `adr_file` (dedicated ADR docs): 0.90
-- `git_archaeology` (commit messages): 0.70 — inferred, not explicit
-- `readme_mining` (README text): 0.60 — weakest signal
-
-Already partially implemented in `decision_extractor.py` — verify values are actually differentiated and flowing through.
-
-**B. Dead code:** Add more signals to vary confidence:
-```python
-# Beyond just commit recency, factor in:
-# - File age (older untouched files more likely dead)
-# - Number of symbols (single-function files more likely dead)
-# - Owner still active in repo (if owner left, higher chance dead)
-```
-
-**C. Search:** Already addressed in 1.5 — either remove the field or make it score-relative.
-
-**Effort:** ~3-4 hours total | **Risk:** Medium — needs calibration
-
----
-
-### 3.2 — Consistent response formats for `get_architecture_diagram`
-
-**Issue:** Repo-scope returns markdown + embedded mermaid. Module-scope returns pure mermaid. Inconsistent.
-
-**File:** `packages/server/src/repowise/server/mcp_server.py` — `get_architecture_diagram` handler
-
-**Fix:** Standardize both to return the same structure:
-```python
-{
- "diagram_type": "flowchart",
- "mermaid_syntax": "...",
- "description": "...",
- "metadata": {
- "scope": "repo" | "module",
- "path": null | "packages/core",
- "node_count": 15,
- "edge_count": 23,
- }
-}
-```
-
-For repo-scope, generate a mermaid diagram from the module-level graph rather than returning the pre-generated architecture page.
-
-**Effort:** ~2 hours | **Risk:** Low-medium — repo-scope currently returns richer content (prose + diagram). Switching to pure diagram loses context. Consider returning both.
-
----
-
-### 3.3 — `get_why` decision relevance: semantic filtering
-
-**Issue:** Keyword scoring alone is too noisy. Words like "use" and "parser" match too broadly.
-
-**Beyond the threshold fix in 2.2**, improve the actual scoring:
-
-**A. Use the semantic search as primary ranker, not keyword:**
-```python
-# Current: keyword first, semantic second
-# Better: semantic first, keyword to fill gaps
-
-decision_results = await _decision_store.search(query, limit=10)
-# Only fall back to keyword scoring if semantic search returns < 3 results
-if len(decision_results) < 3:
- # keyword fallback...
-```
-
-**B. Require multi-word phrase matching, not just individual words:**
-```python
-# Instead of checking each word independently:
-# "tree sitter" should match as a phrase, not "tree" and "sitter" separately
-import re
-bigrams = [f"{words[i]} {words[i+1]}" for i in range(len(words)-1)]
-for bigram in bigrams:
- if bigram in text:
- score += weight * 2 # Phrase match worth more
-```
-
-**C. Negative signal: if decision text mentions the query topic 0 times but other topics 5+ times, it's irrelevant.**
-
-**Effort:** ~3-4 hours | **Risk:** Medium — changes ranking behavior significantly, needs A/B comparison
-
----
-
-### 3.4 — `change_magnitude` staleness in `get_risk`
-
-**Issue:** `git_indexer.py` shows `lines_added_90d: 0` despite being committed this week.
-
-**Root cause:** Git metadata is computed at `init`/`update` time. If the wiki hasn't been updated since the commits, the 90-day window is stale.
-
-**Fix options:**
-1. **Live git check:** On `get_risk` calls, optionally run a quick `git log --since=90.days` for the queried files to get fresh counts.
-2. **Show data freshness:** Include `"data_as_of": "2026-03-20"` (last indexing time) so consumers know the data age.
-3. **Periodic reindex:** Already exists via `update` command — document that `get_risk` data freshness depends on reindexing cadence.
-
-**Effort:** ~2 hours for option 2 (quick), ~4 hours for option 1 (live) | **Risk:** Option 1 adds latency
-
----
-
-## Fix Priority Matrix
-
-| # | Fix | Phase | Effort | Impact | Dependencies |
-|---|-----|-------|--------|--------|-------------|
-| 1.1 | Short diagram labels | 1 | 15m | Low | None |
-| 1.2 | Exclude test fixtures from entry points | 1 | 20m | Low-Med | Check GraphNode model |
-| 1.3 | Framework files in dead code skip list | 1 | 10m | Low | None |
-| 1.4 | Fixture dirs in dead code | 1 | 15m | Low | None |
-| 1.5 | Fix/remove confidence_score in search | 1 | 20m | Med | None |
-| 1.6 | Clip external nodes in diagrams | 1 | 30m | Low | None |
-| 2.1 | `get_why` timeout wrapper | 2 | 1-2h | **High** | None |
-| 2.2 | Decision relevance threshold | 2 | 1h | **High** | None |
-| 2.3 | Search relevance threshold | 2 | 30m | Med | None |
-| 2.4 | Ownership attribution gaps | 2 | 2-3h | **High** | git_indexer changes |
-| 2.5 | Populate `affected_files` for README decisions | 2 | 1h | Med | decision_extractor |
-| 3.1 | Meaningful confidence scores | 3 | 3-4h | Med | Multiple files |
-| 3.2 | Consistent diagram response format | 3 | 2h | Low | None |
-| 3.3 | Semantic decision filtering | 3 | 3-4h | Med | 2.2 first |
-| 3.4 | Fresh change_magnitude data | 3 | 2-4h | Med | None |
-
----
-
-## Recommended Execution Order
-
-1. **Do Phase 1 all at once** — small, independent fixes across 4 files. ~2 hours total.
-2. **Do 2.1 (timeouts) first in Phase 2** — this is the only reliability blocker.
-3. **Do 2.2 + 2.3 (relevance thresholds)** — quick score gating.
-4. **Do 2.4 (ownership)** — most impactful data quality fix, needs testing.
-5. **Do 2.5 (affected_files)** — unlocks target-aware `get_why`.
-6. **Phase 3 as time allows** — these are quality-of-life improvements.
-
----
-
-## Files to Modify
-
-| File | Fixes |
-|------|-------|
-| `packages/server/src/repowise/server/mcp_server.py` | 1.1, 1.2, 1.5, 1.6, 2.1, 2.2, 2.3 |
-| `packages/core/src/repowise/core/analysis/dead_code.py` | 1.3, 1.4, 3.1 (dead code confidence) |
-| `packages/core/src/repowise/core/ingestion/git_indexer.py` | 2.4 |
-| `packages/core/src/repowise/core/analysis/decision_extractor.py` | 2.5, 3.1 (decision confidence) |
diff --git a/packages/cli/src/repowise/cli/commands/claude_md_cmd.py b/packages/cli/src/repowise/cli/commands/claude_md_cmd.py
new file mode 100644
index 000000000..7afd2dd49
--- /dev/null
+++ b/packages/cli/src/repowise/cli/commands/claude_md_cmd.py
@@ -0,0 +1,103 @@
+"""repowise generate-claude-md — generate/update CLAUDE.md for a repository."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from repowise.cli.helpers import (
+ ensure_repowise_dir,
+ get_db_url_for_repo,
+ run_async,
+)
+
+
[email protected]("generate-claude-md")
[email protected]("path", required=False, default=None)
+ "--output",
+ "output_path",
+ default=None,
+ metavar="FILE",
+ help="Write to a custom path (default: CLAUDE.md in the repo root).",
+)
+ "--stdout",
+ "to_stdout",
+ is_flag=True,
+ default=False,
+ help="Print generated content to stdout instead of writing a file.",
+)
+def claude_md_command(
+ path: str | None,
+ output_path: str | None,
+ to_stdout: bool,
+) -> None:
+ """Generate or update CLAUDE.md with codebase intelligence context.
+
+ PATH defaults to the current directory.
+
+ The file is split into two sections:
+ - Your custom instructions (above the REPOWISE markers) — never modified.
+ - Repowise-managed section (between markers) — auto-updated from the index.
+
+ Run 'repowise init' or 'repowise update' to keep it current automatically.
+ """
+ repo_path = Path(path).resolve() if path else Path.cwd()
+ ensure_repowise_dir(repo_path)
+
+ try:
+ content = run_async(_generate(repo_path, output_path, to_stdout))
+ except Exception as exc: # noqa: BLE001
+ raise click.ClickException(str(exc)) from exc
+
+ if to_stdout:
+ click.echo(content, nl=False)
+
+
+async def _generate(
+ repo_path: Path,
+ output_path: str | None,
+ to_stdout: bool,
+) -> str | None:
+ from repowise.core.generation.editor_files import ClaudeMdGenerator, EditorFileDataFetcher
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ )
+ from repowise.core.persistence.crud import get_repository_by_path
+
+ url = get_db_url_for_repo(repo_path)
+ engine = create_engine(url)
+ await init_db(engine)
+ sf = create_session_factory(engine)
+
+ try:
+ async with get_session(sf) as session:
+ repo = await get_repository_by_path(session, str(repo_path))
+ if repo is None:
+ raise click.ClickException(
+ f"Repository not found in index. Run 'repowise init' first."
+ )
+ fetcher = EditorFileDataFetcher(session, repo.id, repo_path)
+ data = await fetcher.fetch()
+ finally:
+ await engine.dispose()
+
+ gen = ClaudeMdGenerator()
+
+ if to_stdout:
+ return gen.render_full(repo_path, data)
+
+ dest = Path(output_path).resolve() if output_path else None
+ written = gen.write(dest.parent if dest else repo_path, data)
+ if dest and dest != written:
+ # Custom output path differs from default filename in same dir
+ written.rename(dest)
+ written = dest
+
+ click.echo(f"CLAUDE.md updated: {written}")
+ return None
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd.py b/packages/cli/src/repowise/cli/commands/init_cmd.py
index 8bed83be3..1ffaf2e1d 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd.py
@@ -28,6 +28,68 @@ from repowise.cli.helpers import (
)
+def _maybe_generate_claude_md(
+ console_obj: Any,
+ repo_path: Path,
+ *,
+ no_claude_md: bool = False,
+) -> None:
+ """Generate CLAUDE.md if enabled in config and not opted out."""
+ cfg = load_config(repo_path)
+ enabled = cfg.get("editor_files", {}).get("claude_md", True)
+ if no_claude_md:
+ # Persist opt-out so 'repowise update' respects it
+ ef_cfg = dict(cfg.get("editor_files", {}))
+ ef_cfg["claude_md"] = False
+ cfg["editor_files"] = ef_cfg
+ try:
+ import yaml # type: ignore[import-untyped]
+ cfg_path = repo_path / ".repowise" / "config.yaml"
+ cfg_path.write_text(
+ yaml.dump(cfg, default_flow_style=False, sort_keys=False),
+ encoding="utf-8",
+ )
+ except ImportError:
+ pass
+ return
+ if not enabled:
+ return
+ try:
+ with console_obj.status(" Generating CLAUDE.md…", spinner="dots"):
+ run_async(_write_claude_md_async(repo_path))
+ console_obj.print(" [green]✓[/green] CLAUDE.md updated")
+ except Exception as exc: # noqa: BLE001
+ console_obj.print(f" [yellow]CLAUDE.md skipped: {exc}[/yellow]")
+
+
+async def _write_claude_md_async(repo_path: Path) -> None:
+ """Fetch data from DB and write CLAUDE.md (async helper)."""
+ from repowise.core.generation.editor_files import ClaudeMdGenerator, EditorFileDataFetcher
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ )
+ from repowise.core.persistence.crud import get_repository_by_path
+ from repowise.cli.helpers import get_db_url_for_repo
+
+ url = get_db_url_for_repo(repo_path)
+ engine = create_engine(url)
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ try:
+ async with get_session(sf) as session:
+ repo = await get_repository_by_path(session, str(repo_path))
+ if repo is None:
+ return # Not indexed yet — skip silently
+ fetcher = EditorFileDataFetcher(session, repo.id, repo_path)
+ data = await fetcher.fetch()
+ finally:
+ await engine.dispose()
+ ClaudeMdGenerator().write(repo_path, data)
+
+
async def _persist_index_only(
repo_path: Path,
repo_name: str,
@@ -184,6 +246,13 @@ def _resolve_embedder(embedder_flag: str | None) -> str:
default=False,
help="Use git log --follow to track files across renames (slower but more accurate history). Saved to config.",
)
+ "--no-claude-md",
+ "no_claude_md",
+ is_flag=True,
+ default=False,
+ help="Skip generating CLAUDE.md. Saves 'editor_files.claude_md: false' to config.",
+)
def init_command(
path: str | None,
provider_name: str | None,
@@ -201,6 +270,7 @@ def init_command(
exclude: tuple[str, ...],
commit_limit: int | None,
follow_renames: bool,
+ no_claude_md: bool,
) -> None:
"""Generate wiki documentation for a codebase.
@@ -586,6 +656,9 @@ def init_command(
from repowise.cli.mcp_config import save_mcp_config
save_mcp_config(repo_path)
+ # CLAUDE.md (index-only: structural data is available)
+ _maybe_generate_claude_md(console, repo_path, no_claude_md=no_claude_md)
+
elapsed = time.monotonic() - start
# Collect stats for the completion panel
@@ -855,6 +928,9 @@ def init_command(
run_async(_persist())
console.print(" [green]✓[/green] Database updated")
+ # ---- CLAUDE.md ----
+ _maybe_generate_claude_md(console, repo_path, no_claude_md=no_claude_md)
+
# ---- State ----
# Query actual DB page count (not just current job's pages)
async def _count_db_pages() -> int:
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd.py b/packages/cli/src/repowise/cli/commands/update_cmd.py
index 4a7f97f06..cd37fd061 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd.py
@@ -260,6 +260,41 @@ def update_command(
run_async(_persist())
+ # ---- CLAUDE.md (best-effort) ----
+ cfg = load_config(repo_path)
+ if cfg.get("editor_files", {}).get("claude_md", True):
+ try:
+ from pathlib import Path as _Path
+ from repowise.core.generation.editor_files import ClaudeMdGenerator, EditorFileDataFetcher
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ )
+ from repowise.core.persistence.crud import get_repository_by_path
+ from repowise.cli.helpers import get_db_url_for_repo
+
+ async def _update_claude_md() -> None:
+ url = get_db_url_for_repo(repo_path)
+ engine = create_engine(url)
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ try:
+ async with get_session(sf) as session:
+ repo_rec = await get_repository_by_path(session, str(repo_path))
+ if repo_rec is None:
+ return
+ fetcher = EditorFileDataFetcher(session, repo_rec.id, repo_path)
+ data = await fetcher.fetch()
+ finally:
+ await engine.dispose()
+ ClaudeMdGenerator().write(repo_path, data)
+
+ run_async(_update_claude_md())
+ except Exception:
+ pass # CLAUDE.md update must never fail the update command
+
# Update state
state["last_sync_commit"] = head
state["total_pages"] = state.get("total_pages", 0) + len(generated_pages)
diff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.py
index 8a992f12f..634f12fd8 100644
--- a/packages/cli/src/repowise/cli/main.py
+++ b/packages/cli/src/repowise/cli/main.py
@@ -9,6 +9,7 @@ from repowise.cli.commands.dead_code_cmd import dead_code_command
from repowise.cli.commands.decision_cmd import decision_group
from repowise.cli.commands.doctor_cmd import doctor_command
from repowise.cli.commands.export_cmd import export_command
+from repowise.cli.commands.claude_md_cmd import claude_md_command
from repowise.cli.commands.init_cmd import init_command
from repowise.cli.commands.mcp_cmd import mcp_command
from repowise.cli.commands.reindex_cmd import reindex_command
@@ -26,6 +27,7 @@ def cli() -> None:
cli.add_command(init_command)
+cli.add_command(claude_md_command)
cli.add_command(update_command)
cli.add_command(dead_code_command)
cli.add_command(decision_group)
diff --git a/packages/core/src/repowise/core/generation/__init__.py b/packages/core/src/repowise/core/generation/__init__.py
index 512ea3df1..dea45212b 100644
--- a/packages/core/src/repowise/core/generation/__init__.py
+++ b/packages/core/src/repowise/core/generation/__init__.py
@@ -35,9 +35,26 @@ from .models import (
compute_source_hash,
decay_confidence,
)
+from .editor_files import (
+ ClaudeMdGenerator,
+ DecisionSummary,
+ EditorFileData,
+ EditorFileDataFetcher,
+ HotspotFile,
+ KeyModule,
+ TechStackItem,
+)
from .page_generator import PageGenerator, SYSTEM_PROMPTS
__all__ = [
+ # editor files
+ "ClaudeMdGenerator",
+ "EditorFileData",
+ "TechStackItem",
+ "KeyModule",
+ "HotspotFile",
+ "DecisionSummary",
+ "EditorFileDataFetcher",
# models
"PageType",
"GENERATION_LEVELS",
diff --git a/packages/core/src/repowise/core/generation/editor_files/__init__.py b/packages/core/src/repowise/core/generation/editor_files/__init__.py
new file mode 100644
index 000000000..afa85b9ab
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/editor_files/__init__.py
@@ -0,0 +1,30 @@
+"""Editor-file generators for repowise.
+
+Provides generators that create and maintain AI-editor configuration files
+(CLAUDE.md, cursor.md, etc.) from already-indexed codebase data.
+
+No LLM calls are made — all content is derived from the repowise DB.
+"""
+
+from .claude_md import ClaudeMdGenerator
+from .data import (
+ DecisionSummary,
+ EditorFileData,
+ HotspotFile,
+ KeyModule,
+ TechStackItem,
+)
+from .fetcher import EditorFileDataFetcher
+
+__all__ = [
+ # Generators
+ "ClaudeMdGenerator",
+ # Data containers
+ "EditorFileData",
+ "TechStackItem",
+ "KeyModule",
+ "HotspotFile",
+ "DecisionSummary",
+ # Fetcher
+ "EditorFileDataFetcher",
+]
diff --git a/packages/core/src/repowise/core/generation/editor_files/base.py b/packages/core/src/repowise/core/generation/editor_files/base.py
new file mode 100644
index 000000000..03cc7c90e
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/editor_files/base.py
@@ -0,0 +1,130 @@
+"""Abstract base class for editor-file generators (CLAUDE.md, cursor.md, etc.).
+
+Handles the marker-based merge strategy so subclasses only need to define
+the filename, marker tag, template name, and user placeholder text.
+
+Merge rules:
+ - No existing file → create with placeholder + Repowise section
+ - File without markers → append Repowise section at bottom
+ - File with markers → replace ONLY content between markers
+"""
+
+from __future__ import annotations
+
+import re
+import tempfile
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+import jinja2
+
+from .data import EditorFileData
+
+
+class BaseEditorFileGenerator(ABC):
+ """Base class for generating and maintaining editor configuration files."""
+
+ #: Format strings for the HTML comment markers. {tag} is replaced by marker_tag.
+ MARKER_START_FMT = (
+ "<!-- {tag}:START — Do not edit below this line. "
+ "Auto-generated by Repowise. -->"
+ )
+ MARKER_END_FMT = "<!-- {tag}:END -->"
+
+ def __init__(self) -> None:
+ templates_dir = Path(__file__).resolve().parent.parent / "templates"
+ self._jinja_env = jinja2.Environment(
+ loader=jinja2.FileSystemLoader(str(templates_dir)),
+ undefined=jinja2.StrictUndefined,
+ keep_trailing_newline=True,
+ trim_blocks=True,
+ lstrip_blocks=True,
+ )
+
+ # ------------------------------------------------------------------
+ # Abstract interface — subclasses define these
+ # ------------------------------------------------------------------
+
+ @property
+ @abstractmethod
+ def filename(self) -> str:
+ """Output filename, e.g. 'CLAUDE.md'."""
+
+ @property
+ @abstractmethod
+ def marker_tag(self) -> str:
+ """Marker tag prefix, e.g. 'REPOWISE'. Used in START/END comments."""
+
+ @property
+ @abstractmethod
+ def template_name(self) -> str:
+ """Jinja2 template file name, e.g. 'claude_md.j2'."""
+
+ @property
+ @abstractmethod
+ def user_placeholder(self) -> str:
+ """Content written above the Repowise section when creating a new file."""
+
+ # ------------------------------------------------------------------
+ # Public API
+ # ------------------------------------------------------------------
+
+ def render(self, data: EditorFileData) -> str:
+ """Render just the managed section content (without markers)."""
+ template = self._jinja_env.get_template(self.template_name)
+ return template.render(data=data)
+
+ def write(self, repo_path: Path, data: EditorFileData) -> Path:
+ """Write the file to *repo_path*, preserving user content outside markers.
+
+ Returns the path of the written file.
+ """
+ target = repo_path / self.filename
+ marker_start = self.MARKER_START_FMT.format(tag=self.marker_tag)
+ marker_end = self.MARKER_END_FMT.format(tag=self.marker_tag)
+
+ managed = self.render(data)
+ wrapped = f"{marker_start}\n{managed}\n{marker_end}"
+
+ if not target.exists():
+ content = f"{self.user_placeholder}\n{wrapped}\n"
+ else:
+ existing = target.read_text(encoding="utf-8")
+ if marker_start in existing:
+ # Replace the managed section in-place
+ pattern = re.escape(marker_start) + r".*?" + re.escape(marker_end)
+ content = re.sub(pattern, wrapped, existing, flags=re.DOTALL)
+ else:
+ # Append managed section; preserve all existing content
+ content = existing.rstrip() + "\n\n" + wrapped + "\n"
+
+ _atomic_write(target, content)
+ return target
+
+ def render_full(self, repo_path: Path, data: EditorFileData) -> str:
+ """Return what the full file would look like without writing to disk."""
+ marker_start = self.MARKER_START_FMT.format(tag=self.marker_tag)
+ marker_end = self.MARKER_END_FMT.format(tag=self.marker_tag)
+ managed = self.render(data)
+ wrapped = f"{marker_start}\n{managed}\n{marker_end}"
+ target = repo_path / self.filename
+ if not target.exists():
+ return f"{self.user_placeholder}\n{wrapped}\n"
+ existing = target.read_text(encoding="utf-8")
+ if marker_start in existing:
+ pattern = re.escape(marker_start) + r".*?" + re.escape(marker_end)
+ return re.sub(pattern, wrapped, existing, flags=re.DOTALL)
+ return existing.rstrip() + "\n\n" + wrapped + "\n"
+
+
+def _atomic_write(path: Path, content: str) -> None:
+ """Write *content* to *path* atomically via a temp file + rename."""
+ parent = path.parent
+ fd, tmp = tempfile.mkstemp(dir=parent, suffix=".tmp")
+ try:
+ with open(fd, "w", encoding="utf-8", newline="\n") as f:
+ f.write(content)
+ Path(tmp).replace(path)
+ except Exception:
+ Path(tmp).unlink(missing_ok=True)
+ raise
diff --git a/packages/core/src/repowise/core/generation/editor_files/claude_md.py b/packages/core/src/repowise/core/generation/editor_files/claude_md.py
new file mode 100644
index 000000000..7502aa571
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/editor_files/claude_md.py
@@ -0,0 +1,25 @@
+"""ClaudeMdGenerator — generates and maintains CLAUDE.md for a repository."""
+
+from __future__ import annotations
+
+from .base import BaseEditorFileGenerator
+
+
+class ClaudeMdGenerator(BaseEditorFileGenerator):
+ """Generates and maintains the CLAUDE.md file.
+
+ The file has two sections:
+ - User section (above the REPOWISE markers): never touched by Repowise.
+ - Repowise section (between markers): auto-generated from indexed data.
+ """
+
+ filename = "CLAUDE.md"
+ marker_tag = "REPOWISE"
+ template_name = "claude_md.j2"
+ user_placeholder = (
+ "# CLAUDE.md\n\n"
+ "<!-- Add your custom instructions below. "
+ "Repowise will never modify anything outside the REPOWISE markers. -->\n"
+ "<!-- Examples: coding style rules, test commands, "
+ "workflow preferences, constraints -->\n"
+ )
diff --git a/packages/core/src/repowise/core/generation/editor_files/data.py b/packages/core/src/repowise/core/generation/editor_files/data.py
new file mode 100644
index 000000000..87b728799
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/editor_files/data.py
@@ -0,0 +1,54 @@
+"""Data containers for editor-file generators.
+
+These frozen dataclasses decouple DB fetching from template rendering.
+All fields use basic Python types so they can be constructed directly in tests
+without any DB or filesystem dependency.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class TechStackItem:
+ name: str
+ version: str | None
+ category: str # "language" | "framework" | "database" | "infra"
+
+
+@dataclass(frozen=True)
+class KeyModule:
+ name: str # display name, e.g. "src/api"
+ purpose: str # short description (~80 chars)
+ file_count: int
+ owner: str | None
+
+
+@dataclass(frozen=True)
+class HotspotFile:
+ path: str
+ churn_percentile: float
+ commit_count_90d: int
+ owner: str | None
+
+
+@dataclass(frozen=True)
+class DecisionSummary:
+ title: str
+ status: str # active | deprecated | superseded | proposed
+ rationale: str # first ~100 chars of decision.rationale
+
+
+@dataclass(frozen=True)
+class EditorFileData:
+ repo_name: str
+ indexed_at: str # date only: "2026-03-28"
+ architecture_summary: str # 2-4 sentences from repo_overview page
+ key_modules: list[KeyModule] = field(default_factory=list)
+ entry_points: list[str] = field(default_factory=list)
+ tech_stack: list[TechStackItem] = field(default_factory=list)
+ hotspots: list[HotspotFile] = field(default_factory=list)
+ decisions: list[DecisionSummary] = field(default_factory=list)
+ build_commands: dict[str, str] = field(default_factory=dict)
+ avg_confidence: float = 0.0
diff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.py
new file mode 100644
index 000000000..c3b127d97
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/editor_files/fetcher.py
@@ -0,0 +1,235 @@
+"""EditorFileDataFetcher: queries the repowise DB and returns EditorFileData.
+
+All queries operate on already-persisted data — no LLM calls required.
+Uses the existing CRUD layer where possible; raw selects for aggregate queries.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.persistence import crud
+from repowise.core.persistence.models import (
+ DecisionRecord,
+ GitMetadata,
+ GraphNode,
+ Page,
+)
+
+from .data import DecisionSummary, EditorFileData, HotspotFile, KeyModule
+from .tech_stack import detect_build_commands, detect_tech_stack
+
+# Maximum items per section to keep CLAUDE.md within ~200 lines
+_MAX_MODULES = 10
+_MAX_ENTRY_POINTS = 10
+_MAX_HOTSPOTS = 5
+_MAX_DECISIONS = 8
+
+
+class EditorFileDataFetcher:
+ """Fetches all data needed to render an editor-file template."""
+
+ def __init__(
+ self,
+ session: AsyncSession,
+ repo_id: str,
+ repo_path: Path,
+ ) -> None:
+ self._session = session
+ self._repo_id = repo_id
+ self._repo_path = repo_path
+
+ async def fetch(self) -> EditorFileData:
+ """Run all queries and return a populated EditorFileData."""
+ repo = await crud.get_repository(self._session, self._repo_id)
+ repo_name = repo.name if repo else self._repo_path.name
+
+ return EditorFileData(
+ repo_name=repo_name,
+ indexed_at=datetime.now(timezone.utc).strftime("%Y-%m-%d"),
+ architecture_summary=await self._get_architecture_summary(),
+ key_modules=await self._get_key_modules(),
+ entry_points=await self._get_entry_points(),
+ tech_stack=detect_tech_stack(self._repo_path),
+ hotspots=await self._get_hotspots(),
+ decisions=await self._get_decisions(),
+ build_commands=detect_build_commands(self._repo_path),
+ avg_confidence=await self._get_avg_confidence(),
+ )
+
+ # ------------------------------------------------------------------
+ # Private helpers
+ # ------------------------------------------------------------------
+
+ async def _get_architecture_summary(self) -> str:
+ """Extract 2-4 sentences from the repo_overview wiki page."""
+ pages = await crud.list_pages(
+ self._session,
+ self._repo_id,
+ page_type="repo_overview",
+ limit=1,
+ )
+ if not pages:
+ return ""
+ content = pages[0].content or ""
+ return _extract_sentences(content, max_sentences=4)
+
+ async def _get_key_modules(self) -> list[KeyModule]:
+ """Top modules by PageRank with owner from git metadata."""
+ # Fetch module pages sorted by their target_path (proxy for PageRank
+ # ordering is applied by joining with graph_nodes).
+ pages_result = await self._session.execute(
+ select(Page, GraphNode.pagerank, GraphNode.symbol_count)
+ .join(
+ GraphNode,
+ (GraphNode.repository_id == Page.repository_id)
+ & (GraphNode.node_id == Page.target_path),
+ isouter=True,
+ )
+ .where(
+ Page.repository_id == self._repo_id,
+ Page.page_type == "module_page",
+ )
+ .order_by(GraphNode.pagerank.desc().nulls_last())
+ .limit(_MAX_MODULES)
+ )
+ rows = pages_result.all()
+
+ if not rows:
+ return []
+
+ # Build a lookup of primary owners from git_metadata
+ target_paths = [row[0].target_path for row in rows]
+ owner_map = await self._get_owners_for_paths(target_paths)
+
+ modules: list[KeyModule] = []
+ for page, pagerank, symbol_count in rows:
+ purpose = _extract_sentences(page.content or "", max_sentences=1)
+ purpose = purpose[:80].rstrip(".") if purpose else ""
+ modules.append(
+ KeyModule(
+ name=page.target_path,
+ purpose=purpose,
+ file_count=symbol_count or 0,
+ owner=owner_map.get(page.target_path),
+ )
+ )
+ return modules
+
+ async def _get_entry_points(self) -> list[str]:
+ """Files tagged as entry points, sorted by PageRank desc."""
+ result = await self._session.execute(
+ select(GraphNode.node_id)
+ .where(
+ GraphNode.repository_id == self._repo_id,
+ GraphNode.is_entry_point == True, # noqa: E712
+ )
+ .order_by(GraphNode.pagerank.desc())
+ .limit(_MAX_ENTRY_POINTS)
+ )
+ return [row[0] for row in result.all()]
+
+ async def _get_hotspots(self) -> list[HotspotFile]:
+ """Top hotspot files by churn_percentile with owner info."""
+ result = await self._session.execute(
+ select(
+ GitMetadata.file_path,
+ GitMetadata.churn_percentile,
+ GitMetadata.commit_count_90d,
+ GitMetadata.primary_owner_name,
+ )
+ .where(
+ GitMetadata.repository_id == self._repo_id,
+ GitMetadata.is_hotspot == True, # noqa: E712
+ )
+ .order_by(
+ GitMetadata.churn_percentile.desc(),
+ GitMetadata.file_path.asc(), # deterministic tie-break
+ )
+ .limit(_MAX_HOTSPOTS)
+ )
+ return [
+ HotspotFile(
+ path=row[0],
+ churn_percentile=round(row[1] * 100, 1), # stored as 0.0–1.0
+ commit_count_90d=row[2],
+ owner=row[3],
+ )
+ for row in result.all()
+ ]
+
+ async def _get_decisions(self) -> list[DecisionSummary]:
+ """Active decision records, least-stale first."""
+ result = await self._session.execute(
+ select(DecisionRecord)
+ .where(
+ DecisionRecord.repository_id == self._repo_id,
+ DecisionRecord.status == "active",
+ )
+ .order_by(DecisionRecord.staleness_score.asc())
+ .limit(_MAX_DECISIONS)
+ )
+ records = list(result.scalars().all())
+ summaries: list[DecisionSummary] = []
+ for rec in records:
+ rationale = (rec.rationale or rec.decision or "").strip()
+ rationale = rationale[:100].rstrip(".,;") if rationale else ""
+ summaries.append(
+ DecisionSummary(
+ title=rec.title,
+ status=rec.status,
+ rationale=rationale,
+ )
+ )
+ return summaries
+
+ async def _get_avg_confidence(self) -> float:
+ """Average confidence score across all wiki pages for this repo."""
+ result = await self._session.execute(
+ select(func.avg(Page.confidence)).where(
+ Page.repository_id == self._repo_id,
+ )
+ )
+ avg = result.scalar_one_or_none()
+ return round(float(avg), 2) if avg is not None else 0.0
+
+ async def _get_owners_for_paths(self, paths: list[str]) -> dict[str, str]:
+ """Return {path: primary_owner_name} for the given paths."""
+ if not paths:
+ return {}
+ result = await self._session.execute(
+ select(GitMetadata.file_path, GitMetadata.primary_owner_name)
+ .where(
+ GitMetadata.repository_id == self._repo_id,
+ GitMetadata.file_path.in_(paths),
+ GitMetadata.primary_owner_name.isnot(None),
+ )
+ )
+ return {row[0]: row[1] for row in result.all()}
+
+
+# ------------------------------------------------------------------
+# Utility
+# ------------------------------------------------------------------
+
+def _extract_sentences(text: str, max_sentences: int) -> str:
+ """Return up to *max_sentences* sentences from the start of *text*.
+
+ Strips markdown headers/code fences so only prose remains.
+ """
+ # Remove markdown headers and code fences
+ text = re.sub(r"^#{1,6}\s+.*$", "", text, flags=re.MULTILINE)
+ text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+ text = re.sub(r"`([^`]+)`", r"\1", text) # strip backticks, keep text
+ text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text) # links → text
+ text = text.strip()
+
+ # Split on sentence boundaries
+ sentences = re.split(r"(?<=[.!?])\s+", text)
+ sentences = [s.strip() for s in sentences if s.strip() and len(s.strip()) > 10]
+ return " ".join(sentences[:max_sentences])
diff --git a/packages/core/src/repowise/core/generation/editor_files/tech_stack.py b/packages/core/src/repowise/core/generation/editor_files/tech_stack.py
new file mode 100644
index 000000000..7039749e0
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/editor_files/tech_stack.py
@@ -0,0 +1,203 @@
+"""Filesystem-based tech stack and build command detection.
+
+No DB or network dependencies — scans manifest files in the repo root.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from .data import TechStackItem
+
+# Node.js framework/library signatures to detect from package.json dependencies
+_NODE_FRAMEWORKS: dict[str, tuple[str, str]] = {
+ "next": ("Next.js", "framework"),
+ "react": ("React", "framework"),
+ "vue": ("Vue.js", "framework"),
+ "svelte": ("Svelte", "framework"),
+ "@angular/core": ("Angular", "framework"),
+ "express": ("Express", "framework"),
+ "fastify": ("Fastify", "framework"),
+ "hono": ("Hono", "framework"),
+ "nestjs": ("NestJS", "framework"),
+ "@nestjs/core": ("NestJS", "framework"),
+ "prisma": ("Prisma", "database"),
+ "@prisma/client": ("Prisma", "database"),
+ "drizzle-orm": ("Drizzle ORM", "database"),
+ "typeorm": ("TypeORM", "database"),
+ "mongoose": ("Mongoose", "database"),
+ "sequelize": ("Sequelize", "database"),
+ "tailwindcss": ("Tailwind CSS", "framework"),
+ "vite": ("Vite", "infra"),
+ "webpack": ("Webpack", "infra"),
+ "turbo": ("Turborepo", "infra"),
+}
+
+# Python framework/library keywords in pyproject.toml / requirements.txt
+_PYTHON_FRAMEWORKS: dict[str, tuple[str, str]] = {
+ "fastapi": ("FastAPI", "framework"),
+ "django": ("Django", "framework"),
+ "flask": ("Flask", "framework"),
+ "starlette": ("Starlette", "framework"),
+ "litestar": ("Litestar", "framework"),
+ "sqlalchemy": ("SQLAlchemy", "database"),
+ "alembic": ("Alembic", "database"),
+ "celery": ("Celery", "infra"),
+ "pydantic": ("Pydantic", "framework"),
+ "aiohttp": ("aiohttp", "framework"),
+ "httpx": ("HTTPX", "framework"),
+ "torch": ("PyTorch", "framework"),
+ "tensorflow": ("TensorFlow", "framework"),
+}
+
+
+def detect_tech_stack(repo_path: Path) -> list[TechStackItem]:
+ """Detect languages, frameworks, and infra tools from manifest files.
+
+ Scans repo root and one level deep for common manifest files.
+ Returns items sorted by category then name.
+ """
+ items: dict[str, TechStackItem] = {}
+
+ def add(name: str, version: str | None, category: str) -> None:
+ if name not in items:
+ items[name] = TechStackItem(name=name, version=version, category=category)
+
+ # --- package.json (Node.js) ---
+ pkg_json = repo_path / "package.json"
+ if pkg_json.exists():
+ try:
+ pkg = json.loads(pkg_json.read_text(encoding="utf-8"))
+ # Detect Node version from engines field
+ node_ver = pkg.get("engines", {}).get("node")
+ add("Node.js", node_ver, "language")
+ all_deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+ for dep_key, (display, cat) in _NODE_FRAMEWORKS.items():
+ if dep_key in all_deps:
+ raw = all_deps[dep_key].lstrip("^~>=")
+ add(display, raw or None, cat)
+ if "typescript" in all_deps or (repo_path / "tsconfig.json").exists():
+ ts_ver = all_deps.get("typescript", "").lstrip("^~>=") or None
+ add("TypeScript", ts_ver, "language")
+ except Exception:
+ pass
+
+ # --- pyproject.toml / setup.py (Python) ---
+ pyproject = repo_path / "pyproject.toml"
+ setup_py = repo_path / "setup.py"
+ if pyproject.exists() or setup_py.exists():
+ add("Python", None, "language")
+ if pyproject.exists():
+ text = pyproject.read_text(encoding="utf-8").lower()
+ for dep_key, (display, cat) in _PYTHON_FRAMEWORKS.items():
+ if dep_key in text:
+ add(display, None, cat)
+
+ # --- Cargo.toml (Rust) ---
+ if (repo_path / "Cargo.toml").exists():
+ add("Rust", None, "language")
+
+ # --- go.mod (Go) ---
+ go_mod = repo_path / "go.mod"
+ if go_mod.exists():
+ text = go_mod.read_text(encoding="utf-8")
+ ver_match = re.search(r"^go\s+(\S+)", text, re.MULTILINE)
+ add("Go", ver_match.group(1) if ver_match else None, "language")
+
+ # --- pom.xml / build.gradle (Java/Kotlin) ---
+ if (repo_path / "pom.xml").exists():
+ add("Java", None, "language")
+ add("Maven", None, "infra")
+ if (repo_path / "build.gradle").exists() or (repo_path / "build.gradle.kts").exists():
+ add("Kotlin" if (repo_path / "build.gradle.kts").exists() else "Java", None, "language")
+ add("Gradle", None, "infra")
+
+ # --- Gemfile (Ruby) ---
+ if (repo_path / "Gemfile").exists():
+ add("Ruby", None, "language")
+
+ # --- composer.json (PHP) ---
+ if (repo_path / "composer.json").exists():
+ add("PHP", None, "language")
+
+ # --- Docker ---
+ if (repo_path / "Dockerfile").exists():
+ add("Docker", None, "infra")
+ if (repo_path / "docker-compose.yml").exists() or (repo_path / "docker-compose.yaml").exists():
+ add("Docker Compose", None, "infra")
+
+ return sorted(items.values(), key=lambda x: (x.category, x.name))
+
+
+def detect_build_commands(repo_path: Path) -> dict[str, str]:
+ """Detect common build/test/lint commands from manifest files.
+
+ Returns a dict with keys from: build, test, lint, dev, format, typecheck.
+ Only includes keys where a command was actually detected.
+ """
+ commands: dict[str, str] = {}
+
+ # --- package.json scripts ---
+ pkg_json = repo_path / "package.json"
+ if pkg_json.exists():
+ try:
+ pkg = json.loads(pkg_json.read_text(encoding="utf-8"))
+ scripts = pkg.get("scripts", {})
+ _map = {
+ "build": ["build"],
+ "test": ["test", "jest", "vitest"],
+ "lint": ["lint"],
+ "dev": ["dev", "start:dev", "start"],
+ "format": ["format", "prettier"],
+ "typecheck": ["typecheck", "type-check", "tsc"],
+ }
+ runner = "npm run" if not (repo_path / "pnpm-lock.yaml").exists() else "pnpm"
+ if (repo_path / "yarn.lock").exists():
+ runner = "yarn"
+ for key, candidates in _map.items():
+ for cand in candidates:
+ if cand in scripts:
+ commands[key] = f"{runner} {cand}"
+ break
+ except Exception:
+ pass
+
+ # --- pyproject.toml ---
+ pyproject = repo_path / "pyproject.toml"
+ if pyproject.exists():
+ text = pyproject.read_text(encoding="utf-8")
+ if "test" not in commands and ("pytest" in text or "[tool.pytest" in text):
+ commands["test"] = "pytest"
+ if "lint" not in commands and "ruff" in text:
+ commands["lint"] = "ruff check ."
+ if "format" not in commands and "ruff" in text and "format" in text:
+ commands["format"] = "ruff format ."
+ if "typecheck" not in commands and "mypy" in text:
+ commands["typecheck"] = "mypy ."
+
+ # --- Makefile (first-level .PHONY or obvious targets) ---
+ makefile = repo_path / "Makefile"
+ if makefile.exists():
+ try:
+ mk_text = makefile.read_text(encoding="utf-8")
+ target_pat = re.compile(r"^([a-z][a-z0-9_-]*):", re.MULTILINE)
+ mk_targets = set(target_pat.findall(mk_text))
+ _make_map = {
+ "build": ["build"],
+ "test": ["test", "tests"],
+ "lint": ["lint"],
+ "dev": ["dev", "run"],
+ "format": ["fmt", "format"],
+ }
+ for key, candidates in _make_map.items():
+ if key not in commands:
+ for cand in candidates:
+ if cand in mk_targets:
+ commands[key] = f"make {cand}"
+ break
+ except Exception:
+ pass
+
+ return commands
diff --git a/packages/core/src/repowise/core/generation/page_generator.py b/packages/core/src/repowise/core/generation/page_generator.py
index 005ec9cd1..993dcec35 100644
--- a/packages/core/src/repowise/core/generation/page_generator.py
+++ b/packages/core/src/repowise/core/generation/page_generator.py
@@ -881,16 +881,33 @@ def _is_significant_file(
) -> bool:
"""Return True if this code file deserves its own file_page.
- A file is significant if it:
- - Has at least config.file_page_min_symbols symbols, AND
- - Is an entry point, OR in the top PageRank percentile, OR is a bridge file
- (non-zero betweenness centrality).
+ A file is significant if it is connected/important in the dependency graph
+ (entry point, top PageRank percentile, or bridge file) AND has enough
+ content to document.
+
+ The symbol requirement is waived for files with no original definitions
+ (state modules, __init__ re-exporters, config files) that are still heavily
+ imported — these are architecturally important even without function bodies.
+ Package __init__.py files with any symbols are always included since they
+ are the public interface of their module.
"""
- if len(parsed.symbols) < config.file_page_min_symbols:
- return False
path = parsed.file_info.path
- return (
- parsed.file_info.is_entry_point
- or pagerank.get(path, 0.0) >= pr_threshold
- or betweenness.get(path, 0.0) > 0.0
- )
+ pr = pagerank.get(path, 0.0)
+ bet = betweenness.get(path, 0.0)
+ is_entry = parsed.file_info.is_entry_point
+
+ # F3: package __init__.py files are module interfaces — always include
+ # if they have any symbols (re-exports, __getattr__, etc.)
+ if path.endswith("__init__.py") and len(parsed.symbols) > 0:
+ return True
+
+ # Must appear significant in the graph
+ if not (is_entry or pr >= pr_threshold or bet > 0.0):
+ return False
+
+ # F2: waive symbol requirement for connected files with no original
+ # definitions (e.g. state/config modules imported by many files)
+ if len(parsed.symbols) < config.file_page_min_symbols:
+ return is_entry or pr >= pr_threshold
+
+ return True
diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2
new file mode 100644
index 000000000..d6560780b
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2
@@ -0,0 +1,87 @@
+## Codebase Intelligence — {{ data.repo_name }} (Repowise)
+
+This project is indexed by [Repowise](https://repowise.dev) — a codebase intelligence layer.
+Last indexed: {{ data.indexed_at }}{% if data.avg_confidence %}. Confidence: {{ (data.avg_confidence * 100) | int }}%.{% endif %}
+
+{% if data.architecture_summary %}
+### Architecture
+{{ data.architecture_summary }}
+{% endif %}
+{% if data.key_modules %}
+### Key Modules
+| Module | Purpose | Owner |
+|--------|---------|-------|
+{% for mod in data.key_modules %}
+| `{{ mod.name }}` | {{ mod.purpose or "—" }} | {{ mod.owner or "—" }} |
+{% endfor %}
+{% endif %}
+{% if data.entry_points %}
+### Entry Points
+{% for ep in data.entry_points %}
+- `{{ ep }}`
+{% endfor %}
+{% endif %}
+{% if data.tech_stack %}
+### Tech Stack
+{% set langs = data.tech_stack | selectattr("category", "eq", "language") | list %}
+{% set frameworks = data.tech_stack | selectattr("category", "eq", "framework") | list %}
+{% set infra = data.tech_stack | selectattr("category", "eq", "infra") | list %}
+{% set dbs = data.tech_stack | selectattr("category", "eq", "database") | list %}
+{% if langs %}**Languages:** {{ langs | map(attribute="name") | join(", ") }}{% endif %}
+
+{% if frameworks %}**Frameworks:** {{ frameworks | map(attribute="name") | join(", ") }}{% endif %}
+
+{% if dbs %}**Databases:** {{ dbs | map(attribute="name") | join(", ") }}{% endif %}
+
+{% if infra %}**Infra:** {{ infra | map(attribute="name") | join(", ") }}{% endif %}
+{% endif %}
+{% if data.hotspots %}
+### Hotspots (High Churn)
+| File | Churn | 90d Commits | Owner |
+|------|-------|-------------|-------|
+{% for h in data.hotspots %}
+| `{{ h.path }}` | {{ h.churn_percentile }}th %ile | {{ h.commit_count_90d }} | {{ h.owner or "—" }} |
+{% endfor %}
+{% endif %}
+
+### Repowise MCP Tools
+
+This project has a Repowise MCP server configured. Use these tools to understand the codebase before reading raw source files — they provide richer context including documentation, ownership, history, and architectural decisions.
+
+**Recommended workflow:**
+
+1. Starting a new task? Call `get_overview()` first to understand the architecture.
+2. Before reading/modifying files, call `get_context(targets=["path/to/file.py"])` — faster and richer than reading source directly.
+3. Before making changes, call `get_risk(targets=["path/to/file.py"])` to understand impact and hotspot status.
+4. Don't know where something lives? Call `search_codebase(query="authentication flow")`.
+5. Need to understand why code is structured a certain way? Call `get_why(query="why JWT over sessions")`.
+6. Need to understand how two modules connect? Call `get_dependency_path(source="src/auth", target="src/db")`.
+7. Before cleanup tasks, call `get_dead_code()` to find confirmed unused code.
+8. For documentation or diagrams, call `get_architecture_diagram(scope="src/auth")`.
+
+| Tool | When to use |
+|------|------------|
+| `get_overview()` | First call on unfamiliar codebase or new task |
+| `get_context(targets=[...])` | Before reading or modifying specific files/symbols |
+| `get_risk(targets=[...])` | Before changing files — assess blast radius |
+| `get_why(query="...")` | Before architectural changes — find decisions |
+| `search_codebase(query="...")` | Don't know where something lives |
+| `get_dependency_path(source=..., target=...)` | Understand connections between modules |
+| `get_dead_code()` | Before cleanup or refactoring |
+| `get_architecture_diagram(scope=...)` | Need a visual of the structure |
+{% if data.decisions or data.build_commands %}
+
+### Codebase Conventions
+{% if data.decisions %}
+**Architectural Decisions:**
+{% for d in data.decisions %}
+- **{{ d.title }}**: {{ d.rationale }}{% if d.rationale %}.{% endif %}
+{% endfor %}
+{% endif %}
+{% if data.build_commands %}
+**Commands:**
+{% for label, cmd in data.build_commands.items() %}
+- {{ label | capitalize }}: `{{ cmd }}`
+{% endfor %}
+{% endif %}
+{% endif %}
diff --git a/packages/core/src/repowise/core/persistence/gemini_embedder.py b/packages/core/src/repowise/core/persistence/gemini_embedder.py
index 9d651196f..b2b48f3ba 100644
--- a/packages/core/src/repowise/core/persistence/gemini_embedder.py
+++ b/packages/core/src/repowise/core/persistence/gemini_embedder.py
@@ -41,12 +41,17 @@ class GeminiEmbedder:
output_dimensionality: Override output vector size (default: 768, max: 3072).
"""
+ # Default timeout for embedding API calls (seconds).
+ # Prevents search_codebase from hanging on slow / unreachable API.
+ _DEFAULT_TIMEOUT: float = 10.0
+
def __init__(
self,
api_key: str | None = None,
model: str = "gemini-embedding-001",
task_type: str = "SEMANTIC_SIMILARITY",
output_dimensionality: int = 768,
+ timeout: float = _DEFAULT_TIMEOUT,
) -> None:
self._api_key = api_key or os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")
if not self._api_key:
@@ -56,6 +61,8 @@ class GeminiEmbedder:
self._model = model
self._task_type = task_type
self._output_dimensionality = output_dimensionality
+ self._timeout = timeout
+ self._client: object | None = None # cached; created once on first embed()
@property
def dimensions(self) -> int:
@@ -76,19 +83,34 @@ class GeminiEmbedder:
if not texts:
return []
+ api_key = self._api_key
+ model = self._model
+ task_type = self._task_type
+ output_dimensionality = self._output_dimensionality
+ timeout = self._timeout
+
def _embed_sync() -> list[list[float]]:
from google import genai # type: ignore[import-untyped]
from google.genai import types as genai_types # type: ignore[import-untyped]
- client = genai.Client(api_key=self._api_key)
+ # Cache client — create once, reuse across calls.
+ if self._client is None:
+ try:
+ http_options = genai_types.HttpOptions(timeout=int(timeout * 1000))
+ except Exception:
+ http_options = None # older SDK versions may not support this
+ kwargs: dict = {"api_key": api_key}
+ if http_options is not None:
+ kwargs["http_options"] = http_options
+ self._client = genai.Client(**kwargs)
config = genai_types.EmbedContentConfig(
- task_type=self._task_type,
- output_dimensionality=self._output_dimensionality,
+ task_type=task_type,
+ output_dimensionality=output_dimensionality,
)
- result = client.models.embed_content(
- model=self._model,
+ result = self._client.models.embed_content( # type: ignore[union-attr]
+ model=model,
contents=texts,
config=config,
)
diff --git a/packages/core/src/repowise/core/persistence/openai_embedder.py b/packages/core/src/repowise/core/persistence/openai_embedder.py
index 73390f7b9..09b39d01f 100644
--- a/packages/core/src/repowise/core/persistence/openai_embedder.py
+++ b/packages/core/src/repowise/core/persistence/openai_embedder.py
@@ -43,10 +43,14 @@ class OpenAIEmbedder:
"text-embedding-ada-002": 1536,
}
+ # Default timeout for embedding API calls (seconds).
+ _DEFAULT_TIMEOUT: float = 10.0
+
def __init__(
self,
api_key: str | None = None,
model: str = "text-embedding-3-small",
+ timeout: float = _DEFAULT_TIMEOUT,
) -> None:
self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
if not self._api_key:
@@ -54,6 +58,8 @@ class OpenAIEmbedder:
"OpenAI API key required. Pass api_key= or set OPENAI_API_KEY env var."
)
self._model = model
+ self._timeout = timeout
+ self._client: object | None = None # cached; created once on first embed()
@property
def dimensions(self) -> int:
@@ -74,14 +80,19 @@ class OpenAIEmbedder:
if not texts:
return []
- api_key = self._api_key
model = self._model
+ timeout = self._timeout
def _embed_sync() -> list[list[float]]:
import openai # type: ignore[import-untyped]
- client = openai.OpenAI(api_key=api_key)
- response = client.embeddings.create(model=model, input=texts)
+ # Cache client — create once with timeout, reuse across calls.
+ if self._client is None:
+ self._client = openai.OpenAI(
+ api_key=self._api_key,
+ timeout=timeout,
+ )
+ response = self._client.embeddings.create(model=model, input=texts) # type: ignore[union-attr]
raw_vectors = [list(item.embedding) for item in response.data]
return [_l2_normalize(v) for v in raw_vectors]
diff --git a/packages/server/src/repowise/server/app.py b/packages/server/src/repowise/server/app.py
index 8d1880aeb..aab612f78 100644
--- a/packages/server/src/repowise/server/app.py
+++ b/packages/server/src/repowise/server/app.py
@@ -27,6 +27,7 @@ from repowise.core.persistence.vector_store import InMemoryVectorStore
from repowise.server import __version__
from repowise.server.routers import (
chat,
+ claude_md,
dead_code,
decisions,
git,
@@ -157,6 +158,7 @@ def create_app() -> FastAPI:
app.include_router(webhooks.router)
app.include_router(git.router)
app.include_router(dead_code.router)
+ app.include_router(claude_md.router)
app.include_router(decisions.router)
app.include_router(chat.router)
app.include_router(providers.router)
diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.py
index 1fb91627e..8b92140e5 100644
--- a/packages/server/src/repowise/server/mcp_server/__init__.py
+++ b/packages/server/src/repowise/server/mcp_server/__init__.py
@@ -53,6 +53,7 @@ from repowise.server.mcp_server.tool_diagram import get_architecture_diagram #
_STATE_NAMES = frozenset({
"_session_factory", "_vector_store", "_decision_store", "_fts", "_repo_path",
+ "_vector_store_ready",
})
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index a3e34bd24..a22094a33 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import os
from contextlib import asynccontextmanager
+from typing import Any
from mcp.server.fastmcp import FastMCP
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
@@ -49,9 +50,81 @@ def _resolve_embedder():
return MockEmbedder()
+async def _load_vector_stores(repo_path: str | None) -> None:
+ """Load embedder + vector stores in the background.
+
+ Runs as an asyncio.Task started from _lifespan so the MCP server
+ starts accepting connections immediately. tool_search awaits
+ _state._vector_store_ready before performing a search.
+
+ We pre-warm the LanceDB connection here so the first search() call
+ never hits a cold import or connection. Specifically:
+
+ 1. `import lancedb` is deferred to asyncio.to_thread — the first-time
+ import loads Rust/Arrow DLLs which can block the event loop for
+ tens of seconds on Windows (AV scanning). Running it in a thread
+ keeps the event loop responsive.
+ 2. `_ensure_connected()` is called here so LanceDB opens the table
+ before the first search. Subsequent search() calls see
+ self._db is not None and skip the blocking import entirely.
+ """
+ import asyncio as _asyncio
+ import logging as _logging
+ _log = _logging.getLogger("repowise.mcp")
+ try:
+ embedder = _resolve_embedder()
+ vector_store: Any = InMemoryVectorStore(embedder=embedder)
+ decision_store: Any = InMemoryVectorStore(embedder=embedder)
+
+ try:
+ # Step 1 — import lancedb in a thread to keep event loop free.
+ await _asyncio.to_thread(__import__, "lancedb")
+
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+
+ if repo_path:
+ from pathlib import Path
+
+ lance_dir = Path(repo_path) / ".repowise" / "lancedb"
+ if lance_dir.exists():
+ vs = LanceDBVectorStore(str(lance_dir), embedder=embedder)
+ ds = LanceDBVectorStore(
+ str(lance_dir), embedder=embedder, table_name="decision_records"
+ )
+ # Step 2 — pre-connect so first search() is instant.
+ await vs._ensure_connected()
+ await ds._ensure_connected()
+ vector_store = vs
+ decision_store = ds
+ except ImportError:
+ pass
+ except Exception:
+ _log.warning("LanceDB pre-connect failed — using InMemory fallback")
+
+ _state._vector_store = vector_store
+ _state._decision_store = decision_store
+ except Exception:
+ _log.exception("Failed to load vector stores — falling back to MockEmbedder")
+ _state._vector_store = InMemoryVectorStore(embedder=MockEmbedder())
+ _state._decision_store = InMemoryVectorStore(embedder=MockEmbedder())
+ finally:
+ if _state._vector_store_ready is not None:
+ _state._vector_store_ready.set()
+
+
@asynccontextmanager
async def _lifespan(server: FastMCP):
- """Initialize DB engine, session factory, vector store, FTS on startup."""
+ """Initialize DB engine, session factory, and FTS synchronously on startup.
+
+ Vector store / LanceDB loading is deferred to a background asyncio task so
+ the server starts accepting tool calls immediately. search_codebase awaits
+ _state._vector_store_ready before querying the vector store.
+ """
+ import asyncio
+ import logging as _logging
+
+ _log = _logging.getLogger("repowise.mcp")
+
db_url = os.environ.get(
"REPOWISE_DATABASE_URL", "sqlite+aiosqlite:///repowise.db"
)
@@ -59,9 +132,7 @@ async def _lifespan(server: FastMCP):
# If a repo path was configured, try .repowise/wiki.db
if _state._repo_path:
from pathlib import Path
- import logging as _logging
- _log = _logging.getLogger("repowise.mcp")
repowise_dir = Path(_state._repo_path) / ".repowise"
if not repowise_dir.exists():
_log.warning(
@@ -82,6 +153,7 @@ async def _lifespan(server: FastMCP):
if db_url.startswith("sqlite"):
connect_args["check_same_thread"] = False
+ _log.info("repowise MCP: initialising database…")
engine = create_async_engine(db_url, connect_args=connect_args)
await init_db(engine)
@@ -92,33 +164,25 @@ async def _lifespan(server: FastMCP):
_state._fts = FullTextSearch(engine)
await _state._fts.ensure_index()
- # Resolve real embedder from env/config instead of always using MockEmbedder
- embedder = _resolve_embedder()
- _state._vector_store = InMemoryVectorStore(embedder=embedder)
+ # Seed InMemory placeholders so tools that don't need vector search
+ # can start immediately, before the background load completes.
+ _state._vector_store = InMemoryVectorStore(embedder=MockEmbedder())
+ _state._decision_store = InMemoryVectorStore(embedder=MockEmbedder())
- # Try to load LanceDB if available
- try:
- from repowise.core.persistence.vector_store import LanceDBVectorStore
+ # Defer embedder resolution + LanceDB open to a background task so
+ # the server starts accepting connections without blocking on disk I/O.
+ _state._vector_store_ready = asyncio.Event()
+ _bg_task = asyncio.create_task(_load_vector_stores(_state._repo_path))
+ _log.info("repowise MCP: ready (vector stores loading in background)")
- if _state._repo_path:
- from pathlib import Path
+ yield
- lance_dir = Path(_state._repo_path) / ".repowise" / "lancedb"
- if lance_dir.exists():
- _state._vector_store = LanceDBVectorStore(
- str(lance_dir), embedder=embedder
- )
- _state._decision_store = LanceDBVectorStore(
- str(lance_dir), embedder=embedder, table_name="decision_records"
- )
- except ImportError:
+ _bg_task.cancel()
+ try:
+ await _bg_task
+ except (asyncio.CancelledError, Exception):
pass
- if _state._decision_store is None:
- _state._decision_store = InMemoryVectorStore(embedder=embedder)
-
- yield
-
await engine.dispose()
await _state._vector_store.close()
if _state._decision_store is not None:
diff --git a/packages/server/src/repowise/server/mcp_server/_state.py b/packages/server/src/repowise/server/mcp_server/_state.py
index 1da9ed8a6..7fa640417 100644
--- a/packages/server/src/repowise/server/mcp_server/_state.py
+++ b/packages/server/src/repowise/server/mcp_server/_state.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import asyncio
from typing import Any
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
@@ -11,3 +12,6 @@ _vector_store: Any = None
_decision_store: Any = None
_fts: Any = None
_repo_path: str | None = None
+# Set to an asyncio.Event by _lifespan; signals that vector stores are loaded.
+# tool_search awaits this before searching to avoid racing a background load.
+_vector_store_ready: asyncio.Event | None = None
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context.py b/packages/server/src/repowise/server/mcp_server/tool_context.py
index a32fd47dc..93ab4fc82 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context.py
@@ -100,6 +100,44 @@ async def _resolve_one_target(
file_path_for_git = target
if target_type is None:
+ # F1: check git_metadata — file may exist but have no wiki page
+ res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path == target,
+ )
+ )
+ meta = res.scalar_one_or_none()
+ if meta:
+ return {
+ "target": target,
+ "error": (
+ f"'{target}' exists in the repository but has no wiki page. "
+ "This usually means the file has too few symbols or is below "
+ "the PageRank threshold. Run `repowise update` to regenerate docs."
+ ),
+ "exists_in_git": True,
+ "last_commit_at": meta.last_commit_at.isoformat() if meta.last_commit_at else None,
+ "primary_owner": meta.primary_owner_name,
+ "is_hotspot": meta.is_hotspot,
+ }
+
+ # F5: fuzzy path suggestions — match by filename or partial path
+ tail = target.rsplit("/", 1)[-1]
+ res = await session.execute(
+ select(GitMetadata.file_path).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path.contains(tail),
+ ).limit(5)
+ )
+ suggestions = [row[0] for row in res.all() if row[0] != target]
+ if suggestions:
+ return {
+ "target": target,
+ "error": f"Target not found: '{target}'",
+ "suggestions": suggestions,
+ }
+
return {"target": target, "error": f"Target not found: '{target}'"}
result_data["target"] = target
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.py
index a6ab4faa9..c43472fc4 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py
@@ -2,6 +2,8 @@
from __future__ import annotations
+import asyncio
+
from sqlalchemy import select
from repowise.core.persistence.database import get_session
@@ -33,13 +35,28 @@ async def search_codebase(
# Ensure repo exists
await _get_repo(session, repo)
- # Try semantic search first, fall back to fulltext
- # Over-fetch when filtering by page_type to avoid returning 0 results
+ # Wait for the background task to finish loading and pre-connecting the
+ # vector stores. The task imports lancedb in a thread (avoids blocking
+ # the event loop with DLL loading) and calls _ensure_connected() so the
+ # first search() call hits a warm connection. Typically completes in
+ # under a second for a local LanceDB; 30 s timeout is a hard safety net.
+ if _state._vector_store_ready is not None:
+ try:
+ await asyncio.wait_for(_state._vector_store_ready.wait(), timeout=30.0)
+ except asyncio.TimeoutError:
+ pass
+
+ # Try semantic search, fall back to FTS.
+ # Over-fetch when filtering by page_type to avoid returning 0 results.
+ # 8 s safety-net timeout covers any remaining Gemini API latency.
fetch_limit = limit * 3 if page_type else limit
results = []
try:
- results = await _state._vector_store.search(query, limit=fetch_limit)
- except Exception:
+ results = await asyncio.wait_for(
+ _state._vector_store.search(query, limit=fetch_limit),
+ timeout=8.0,
+ )
+ except (asyncio.TimeoutError, Exception):
pass
if not results:
try:
diff --git a/packages/server/src/repowise/server/routers/claude_md.py b/packages/server/src/repowise/server/routers/claude_md.py
new file mode 100644
index 000000000..acc60b9c9
--- /dev/null
+++ b/packages/server/src/repowise/server/routers/claude_md.py
@@ -0,0 +1,84 @@
+"""/api/repos/{repo_id}/claude-md — CLAUDE.md generation endpoints."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.generation.editor_files import ClaudeMdGenerator, EditorFileDataFetcher
+from repowise.core.persistence import crud
+from repowise.server.deps import get_db_session, verify_api_key
+
+router = APIRouter(
+ tags=["claude-md"],
+ dependencies=[Depends(verify_api_key)],
+)
+
+
[email protected]("/api/repos/{repo_id}/claude-md")
+async def get_claude_md(
+ repo_id: str,
+ session: AsyncSession = Depends(get_db_session),
+) -> dict:
+ """Return the Repowise-managed CLAUDE.md section as JSON.
+
+ Does not write to disk — useful for previewing in the web UI.
+ """
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+
+ repo_path = Path(repo.local_path) if repo.local_path else Path(".")
+ fetcher = EditorFileDataFetcher(session, repo_id, repo_path)
+ data = await fetcher.fetch()
+
+ gen = ClaudeMdGenerator()
+ section_content = gen.render(data)
+
+ return {
+ "content": section_content,
+ "generated_at": data.indexed_at,
+ "repo_name": data.repo_name,
+ "sections": _detect_sections(section_content),
+ }
+
+
[email protected]("/api/repos/{repo_id}/claude-md/generate", status_code=202)
+async def generate_claude_md(
+ repo_id: str,
+ session: AsyncSession = Depends(get_db_session),
+) -> dict:
+ """Regenerate CLAUDE.md and write it to the repository root.
+
+ Returns the generated content. Runs synchronously (fast — no LLM calls).
+ """
+ repo = await crud.get_repository(session, repo_id)
+ if repo is None:
+ raise HTTPException(status_code=404, detail="Repository not found")
+
+ repo_path = Path(repo.local_path)
+ if not repo_path.exists():
+ raise HTTPException(
+ status_code=422,
+ detail=f"Repository path not accessible: {repo_path}",
+ )
+
+ fetcher = EditorFileDataFetcher(session, repo_id, repo_path)
+ data = await fetcher.fetch()
+
+ gen = ClaudeMdGenerator()
+ written = gen.write(repo_path, data)
+
+ return {
+ "status": "generated",
+ "path": str(written),
+ "generated_at": data.indexed_at,
+ }
+
+
+def _detect_sections(content: str) -> list[str]:
+ """Return the markdown H3 section names present in the content."""
+ import re
+ return re.findall(r"^### (.+)$", content, re.MULTILINE)
diff --git a/tests/unit/generation/test_editor_file_base.py b/tests/unit/generation/test_editor_file_base.py
new file mode 100644
index 000000000..a4c4e0a94
--- /dev/null
+++ b/tests/unit/generation/test_editor_file_base.py
@@ -0,0 +1,158 @@
+"""Unit tests for BaseEditorFileGenerator marker-merge logic."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.core.generation.editor_files.base import BaseEditorFileGenerator
+from repowise.core.generation.editor_files.data import EditorFileData
+
+
+# ---------------------------------------------------------------------------
+# Minimal concrete subclass for testing
+# ---------------------------------------------------------------------------
+
+class _TestGenerator(BaseEditorFileGenerator):
+ filename = "TEST.md"
+ marker_tag = "REPOWISE"
+ template_name = "claude_md.j2"
+ user_placeholder = "# TEST.md\n\n<!-- user content here -->\n"
+
+
+def _minimal_data() -> EditorFileData:
+ return EditorFileData(
+ repo_name="test-repo",
+ indexed_at="2026-03-28",
+ architecture_summary="A test repo.",
+ )
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+def gen():
+ return _TestGenerator()
+
+
+def test_render_returns_non_empty_string(gen):
+ data = _minimal_data()
+ result = gen.render(data)
+ assert isinstance(result, str)
+ assert len(result) > 0
+
+
+def test_render_contains_repo_name(gen):
+ data = _minimal_data()
+ result = gen.render(data)
+ assert "test-repo" in result
+
+
+def test_write_creates_new_file(gen, tmp_path):
+ data = _minimal_data()
+ written = gen.write(tmp_path, data)
+ assert written.exists()
+ content = written.read_text(encoding="utf-8")
+ assert "<!-- REPOWISE:START" in content
+ assert "<!-- REPOWISE:END -->" in content
+ assert "<!-- user content here -->" in content # placeholder present
+
+
+def test_write_new_file_has_correct_structure(gen, tmp_path):
+ data = _minimal_data()
+ gen.write(tmp_path, data)
+ content = (tmp_path / "TEST.md").read_text(encoding="utf-8")
+ start_idx = content.index("<!-- REPOWISE:START")
+ end_idx = content.index("<!-- REPOWISE:END -->")
+ assert start_idx < end_idx
+ # User placeholder is BEFORE the markers
+ placeholder_idx = content.index("<!-- user content here -->")
+ assert placeholder_idx < start_idx
+
+
+def test_write_preserves_user_content_when_no_markers(gen, tmp_path):
+ target = tmp_path / "TEST.md"
+ user_content = "# My Project\n\nDo not touch this content!\n"
+ target.write_text(user_content, encoding="utf-8")
+
+ data = _minimal_data()
+ gen.write(tmp_path, data)
+
+ content = target.read_text(encoding="utf-8")
+ assert "Do not touch this content!" in content
+ assert "<!-- REPOWISE:START" in content
+
+
+def test_write_appends_when_no_markers(gen, tmp_path):
+ target = tmp_path / "TEST.md"
+ target.write_text("# Existing\n\nsome content", encoding="utf-8")
+
+ gen.write(tmp_path, _minimal_data())
+ content = target.read_text(encoding="utf-8")
+
+ # Existing content is BEFORE the markers
+ existing_idx = content.index("# Existing")
+ marker_idx = content.index("<!-- REPOWISE:START")
+ assert existing_idx < marker_idx
+
+
+def test_write_replaces_between_markers(gen, tmp_path):
+ marker_start = gen.MARKER_START_FMT.format(tag=gen.marker_tag)
+ marker_end = gen.MARKER_END_FMT.format(tag=gen.marker_tag)
+ target = tmp_path / "TEST.md"
+ old_content = (
+ "# My notes\n\nUser section.\n\n"
+ f"{marker_start}\n## Old Content\nOld managed content.\n{marker_end}\n"
+ )
+ target.write_text(old_content, encoding="utf-8")
+
+ gen.write(tmp_path, _minimal_data())
+ new_content = target.read_text(encoding="utf-8")
+
+ assert "User section." in new_content
+ assert "Old managed content." not in new_content
+ assert "test-repo" in new_content # new managed content present
+
+
+def test_write_replaces_only_managed_section(gen, tmp_path):
+ marker_start = gen.MARKER_START_FMT.format(tag=gen.marker_tag)
+ marker_end = gen.MARKER_END_FMT.format(tag=gen.marker_tag)
+ target = tmp_path / "TEST.md"
+ target.write_text(
+ f"# User notes\n\nKeep this.\n\n{marker_start}\nold\n{marker_end}\n",
+ encoding="utf-8",
+ )
+
+ gen.write(tmp_path, _minimal_data())
+ content = target.read_text(encoding="utf-8")
+
+ assert "Keep this." in content
+ assert content.count("<!-- REPOWISE:START") == 1
+ assert content.count("<!-- REPOWISE:END -->") == 1
+
+
+def test_write_is_idempotent(gen, tmp_path):
+ data = _minimal_data()
+ gen.write(tmp_path, data)
+ first = (tmp_path / "TEST.md").read_text(encoding="utf-8")
+
+ gen.write(tmp_path, data)
+ second = (tmp_path / "TEST.md").read_text(encoding="utf-8")
+
+ assert first == second
+
+
+def test_write_returns_path(gen, tmp_path):
+ result = gen.write(tmp_path, _minimal_data())
+ assert result == tmp_path / "TEST.md"
+
+
+def test_render_full_matches_write_output(gen, tmp_path):
+ data = _minimal_data()
+ preview = gen.render_full(tmp_path, data)
+ gen.write(tmp_path, data)
+ written = (tmp_path / "TEST.md").read_text(encoding="utf-8")
+ assert preview == written
diff --git a/tests/unit/generation/test_editor_file_fetcher.py b/tests/unit/generation/test_editor_file_fetcher.py
new file mode 100644
index 000000000..f1cf0adfa
--- /dev/null
+++ b/tests/unit/generation/test_editor_file_fetcher.py
@@ -0,0 +1,243 @@
+"""Unit tests for EditorFileDataFetcher DB queries."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import StaticPool
+
+from repowise.core.generation.editor_files.fetcher import EditorFileDataFetcher
+from repowise.core.persistence.crud import upsert_repository
+from repowise.core.persistence.database import init_db
+from repowise.core.persistence.models import (
+ DecisionRecord,
+ GitMetadata,
+ GraphNode,
+ Page,
+)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+async def async_engine():
+ engine = create_async_engine(
+ "sqlite+aiosqlite:///:memory:",
+ connect_args={"check_same_thread": False},
+ poolclass=StaticPool,
+ )
+ await init_db(engine)
+ yield engine
+ await engine.dispose()
+
+
+async def session(async_engine):
+ factory = async_sessionmaker(async_engine, expire_on_commit=False, class_=AsyncSession)
+ async with factory() as sess:
+ yield sess
+
+
+async def repo(session):
+ r = await upsert_repository(
+ session,
+ name="test-repo",
+ local_path="/tmp/test-repo",
+ url="",
+ )
+ await session.commit()
+ return r
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _now() -> datetime:
+ return datetime.now(timezone.utc)
+
+
+async def _add_graph_node(session, repo_id, node_id, *, is_entry_point=False, pagerank=0.1):
+ node = GraphNode(
+ repository_id=repo_id,
+ node_id=node_id,
+ node_type="file",
+ language="python",
+ is_entry_point=is_entry_point,
+ pagerank=pagerank,
+ )
+ session.add(node)
+ await session.flush()
+ return node
+
+
+async def _add_page(session, repo_id, page_id, page_type, target_path, content):
+ page = Page(
+ id=page_id,
+ repository_id=repo_id,
+ page_type=page_type,
+ title=target_path,
+ content=content,
+ target_path=target_path,
+ source_hash="abc",
+ model_name="mock",
+ provider_name="mock",
+ generation_level=0,
+ confidence=0.9,
+ freshness_status="fresh",
+ created_at=_now(),
+ updated_at=_now(),
+ )
+ session.add(page)
+ await session.flush()
+ return page
+
+
+async def _add_git_meta(session, repo_id, file_path, *, is_hotspot=False, churn_pct=0.5, owner=None):
+ gm = GitMetadata(
+ repository_id=repo_id,
+ file_path=file_path,
+ is_hotspot=is_hotspot,
+ churn_percentile=churn_pct,
+ commit_count_90d=10,
+ primary_owner_name=owner,
+ )
+ session.add(gm)
+ await session.flush()
+ return gm
+
+
+async def _add_decision(session, repo_id, title, status="active", rationale="Some reason"):
+ dr = DecisionRecord(
+ repository_id=repo_id,
+ title=title,
+ status=status,
+ rationale=rationale,
+ decision="Decided to use X",
+ context="Context here",
+ source="inline_marker",
+ staleness_score=0.0,
+ )
+ session.add(dr)
+ await session.flush()
+ return dr
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+async def test_fetch_empty_db_returns_defaults(session, repo, tmp_path):
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ assert data.repo_name == "test-repo"
+ assert data.architecture_summary == ""
+ assert data.key_modules == []
+ assert data.entry_points == []
+ assert data.hotspots == []
+ assert data.decisions == []
+ assert data.avg_confidence == 0.0
+
+
+async def test_fetch_repo_name(session, repo, tmp_path):
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+ assert data.repo_name == "test-repo"
+
+
+async def test_fetch_architecture_summary(session, repo, tmp_path):
+ content = (
+ "## Overview\n\n"
+ "This is a FastAPI application. It handles user authentication. "
+ "PostgreSQL is used for persistence. Redis backs the cache.\n"
+ )
+ await _add_page(session, repo.id, "repo_overview:.", "repo_overview", ".", content)
+ await session.commit()
+
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ assert data.architecture_summary != ""
+ assert "FastAPI" in data.architecture_summary
+
+
+async def test_fetch_entry_points(session, repo, tmp_path):
+ await _add_graph_node(session, repo.id, "src/main.py", is_entry_point=True, pagerank=0.8)
+ await _add_graph_node(session, repo.id, "src/worker.py", is_entry_point=True, pagerank=0.3)
+ await _add_graph_node(session, repo.id, "src/utils.py", is_entry_point=False)
+ await session.commit()
+
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ assert "src/main.py" in data.entry_points
+ assert "src/worker.py" in data.entry_points
+ assert "src/utils.py" not in data.entry_points
+
+
+async def test_fetch_entry_points_sorted_by_pagerank(session, repo, tmp_path):
+ await _add_graph_node(session, repo.id, "src/low.py", is_entry_point=True, pagerank=0.1)
+ await _add_graph_node(session, repo.id, "src/high.py", is_entry_point=True, pagerank=0.9)
+ await session.commit()
+
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ assert data.entry_points[0] == "src/high.py"
+
+
+async def test_fetch_hotspots(session, repo, tmp_path):
+ await _add_git_meta(session, repo.id, "src/billing.py", is_hotspot=True, churn_pct=0.95, owner="@alice")
+ await _add_git_meta(session, repo.id, "src/utils.py", is_hotspot=False, churn_pct=0.10)
+ await session.commit()
+
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ assert len(data.hotspots) == 1
+ assert data.hotspots[0].path == "src/billing.py"
+ assert data.hotspots[0].owner == "@alice"
+ assert data.hotspots[0].churn_percentile == 95.0 # stored 0.95 → displayed 95.0
+
+
+async def test_fetch_active_decisions_only(session, repo, tmp_path):
+ await _add_decision(session, repo.id, "Use JWT", status="active")
+ await _add_decision(session, repo.id, "Old choice", status="deprecated")
+ await session.commit()
+
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ titles = [d.title for d in data.decisions]
+ assert "Use JWT" in titles
+ assert "Old choice" not in titles
+
+
+async def test_fetch_avg_confidence(session, repo, tmp_path):
+ await _add_page(session, repo.id, "file_page:src/a.py", "file_page", "src/a.py", "content")
+ # Update confidence manually
+ from sqlalchemy import update
+ await session.execute(
+ update(Page).where(Page.id == "file_page:src/a.py").values(confidence=0.8)
+ )
+ await session.commit()
+
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ assert data.avg_confidence == pytest.approx(0.8, abs=0.01)
+
+
+async def test_fetch_indexed_at_is_date_string(session, repo, tmp_path):
+ fetcher = EditorFileDataFetcher(session, repo.id, tmp_path)
+ data = await fetcher.fetch()
+
+ import re
+ assert re.match(r"^\d{4}-\d{2}-\d{2}$", data.indexed_at)
diff --git a/tests/unit/generation/test_tech_stack.py b/tests/unit/generation/test_tech_stack.py
new file mode 100644
index 000000000..c057e114d
--- /dev/null
+++ b/tests/unit/generation/test_tech_stack.py
@@ -0,0 +1,162 @@
+"""Unit tests for tech stack and build command detection."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from repowise.core.generation.editor_files.tech_stack import (
+ detect_build_commands,
+ detect_tech_stack,
+)
+
+
+# ---------------------------------------------------------------------------
+# detect_tech_stack
+# ---------------------------------------------------------------------------
+
+def test_empty_directory_returns_empty_list(tmp_path):
+ result = detect_tech_stack(tmp_path)
+ assert result == []
+
+
+def test_detects_python_from_pyproject(tmp_path):
+ (tmp_path / "pyproject.toml").write_text(
+ '[project]\nname = "myapp"\n', encoding="utf-8"
+ )
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "Python" in names
+
+
+def test_detects_fastapi_from_pyproject(tmp_path):
+ (tmp_path / "pyproject.toml").write_text(
+ '[project]\ndependencies = ["fastapi>=0.100"]\n', encoding="utf-8"
+ )
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "FastAPI" in names
+
+
+def test_detects_nodejs_from_package_json(tmp_path):
+ pkg = {"name": "myapp", "engines": {"node": "20"}, "dependencies": {}}
+ (tmp_path / "package.json").write_text(json.dumps(pkg), encoding="utf-8")
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "Node.js" in names
+
+
+def test_detects_react_from_package_json(tmp_path):
+ pkg = {
+ "name": "myapp",
+ "dependencies": {"react": "^18.0.0", "react-dom": "^18.0.0"},
+ }
+ (tmp_path / "package.json").write_text(json.dumps(pkg), encoding="utf-8")
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "React" in names
+
+
+def test_detects_typescript_from_tsconfig(tmp_path):
+ (tmp_path / "package.json").write_text(
+ json.dumps({"name": "app", "dependencies": {}}), encoding="utf-8"
+ )
+ (tmp_path / "tsconfig.json").write_text("{}", encoding="utf-8")
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "TypeScript" in names
+
+
+def test_detects_rust_from_cargo_toml(tmp_path):
+ (tmp_path / "Cargo.toml").write_text(
+ '[package]\nname = "myapp"\nversion = "0.1.0"\n', encoding="utf-8"
+ )
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "Rust" in names
+
+
+def test_detects_go_from_go_mod(tmp_path):
+ (tmp_path / "go.mod").write_text(
+ "module myapp\n\ngo 1.22\n", encoding="utf-8"
+ )
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "Go" in names
+ go_item = next(i for i in items if i.name == "Go")
+ assert go_item.version == "1.22"
+
+
+def test_detects_docker(tmp_path):
+ (tmp_path / "Dockerfile").write_text("FROM python:3.12\n", encoding="utf-8")
+ items = detect_tech_stack(tmp_path)
+ names = [i.name for i in items]
+ assert "Docker" in names
+
+
+def test_returns_sorted_by_category_then_name(tmp_path):
+ (tmp_path / "pyproject.toml").write_text(
+ '[project]\ndependencies = ["fastapi", "sqlalchemy"]\n', encoding="utf-8"
+ )
+ items = detect_tech_stack(tmp_path)
+ # Verify sort order: categories should be grouped
+ categories = [i.category for i in items]
+ assert categories == sorted(categories) or len(set(categories)) == 1
+
+
+# ---------------------------------------------------------------------------
+# detect_build_commands
+# ---------------------------------------------------------------------------
+
+def test_empty_directory_returns_empty_dict(tmp_path):
+ result = detect_build_commands(tmp_path)
+ assert result == {}
+
+
+def test_detects_pytest_from_pyproject(tmp_path):
+ (tmp_path / "pyproject.toml").write_text(
+ "[tool.pytest.ini_options]\ntestpaths = ['tests']\n", encoding="utf-8"
+ )
+ cmds = detect_build_commands(tmp_path)
+ assert "test" in cmds
+ assert "pytest" in cmds["test"]
+
+
+def test_detects_ruff_from_pyproject(tmp_path):
+ (tmp_path / "pyproject.toml").write_text(
+ "[tool.ruff]\nline-length = 88\n", encoding="utf-8"
+ )
+ cmds = detect_build_commands(tmp_path)
+ assert "lint" in cmds
+ assert "ruff" in cmds["lint"]
+
+
+def test_detects_npm_scripts(tmp_path):
+ pkg = {
+ "name": "myapp",
+ "scripts": {"build": "tsc", "test": "jest", "lint": "eslint src/"},
+ }
+ (tmp_path / "package.json").write_text(json.dumps(pkg), encoding="utf-8")
+ cmds = detect_build_commands(tmp_path)
+ assert "build" in cmds
+ assert "test" in cmds
+ assert "lint" in cmds
+
+
+def test_detects_pnpm_when_lockfile_present(tmp_path):
+ pkg = {"name": "app", "scripts": {"test": "vitest"}}
+ (tmp_path / "package.json").write_text(json.dumps(pkg), encoding="utf-8")
+ (tmp_path / "pnpm-lock.yaml").write_text("", encoding="utf-8")
+ cmds = detect_build_commands(tmp_path)
+ assert cmds.get("test", "").startswith("pnpm")
+
+
+def test_detects_makefile_targets(tmp_path):
+ makefile = "build:\n\tgo build ./...\n\ntest:\n\tgo test ./...\n\nlint:\n\tgolangci-lint run\n"
+ (tmp_path / "Makefile").write_text(makefile, encoding="utf-8")
+ cmds = detect_build_commands(tmp_path)
+ assert "build" in cmds
+ assert cmds["build"] == "make build"
+ assert "test" in cmds