Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
Add CLAUDE.md generation and fix MCP tool reliability
RaghavChamadiyafd0b65efafb7
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 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 ma12. [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 updatedMCP 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 Language1. **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 Provider1. **Create `packages/core/providers/<name>.py`**diff --git a/docs/AUTO_SYNC.md b/docs/AUTO_SYNC.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mddeleted file mode 100644index 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.pynew file mode 100644index 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 Nonediff --git a/packages/cli/src/repowise/cli/commands/init_cmd.py b/packages/cli/src/repowise/cli/commands/init_cmd.pyindex 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_configsave_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.pyindex 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 statestate["last_sync_commit"] = headstate["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.pyindex 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_commandfrom repowise.cli.commands.decision_cmd import decision_groupfrom repowise.cli.commands.doctor_cmd import doctor_commandfrom repowise.cli.commands.export_cmd import export_command+from repowise.cli.commands.claude_md_cmd import claude_md_commandfrom repowise.cli.commands.init_cmd import init_commandfrom repowise.cli.commands.mcp_cmd import mcp_commandfrom 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__.pyindex 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__.pynew file mode 100644index 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.pynew file mode 100644index 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)+ raisediff --git a/packages/core/src/repowise/core/generation/editor_files/claude_md.py b/packages/core/src/repowise/core/generation/editor_files/claude_md.pynew file mode 100644index 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.pynew file mode 100644index 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.0diff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.pynew file mode 100644index 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.pynew file mode 100644index 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 commandsdiff --git a/packages/core/src/repowise/core/generation/page_generator.py b/packages/core/src/repowise/core/generation/page_generator.pyindex 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 Falsepath = 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 Truediff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2new file mode 100644index 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.pyindex 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 = modelself._task_type = task_typeself._output_dimensionality = output_dimensionality+ self._timeout = timeout+ self._client: object | None = None # cached; created once on first embed()@propertydef 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.pyindex 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()@propertydef dimensions(self) -> int:@@ -74,14 +80,19 @@ class OpenAIEmbedder:if not texts:return []- api_key = self._api_keymodel = self._model+ timeout = self._timeoutdef _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.pyindex 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 InMemoryVectorStorefrom 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__.pyindex 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.pyindex 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 annotationsimport osfrom contextlib import asynccontextmanager+from typing import Anyfrom mcp.server.fastmcp import FastMCPfrom 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()++@asynccontextmanagerasync 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.dbif _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.pyindex 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 asynciofrom typing import Anyfrom 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 = Nonediff --git a/packages/server/src/repowise/server/mcp_server/tool_context.py b/packages/server/src/repowise/server/mcp_server/tool_context.pyindex 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 = targetif 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"] = targetdiff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex 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 selectfrom repowise.core.persistence.database import get_session@@ -33,13 +35,28 @@ async def search_codebase(# Ensure repo existsawait _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 limitresults = []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):passif not results:try:diff --git a/packages/server/src/repowise/server/routers/claude_md.py b/packages/server/src/repowise/server/routers/claude_md.pynew file mode 100644index 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.pynew file mode 100644index 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 == writtendiff --git a/tests/unit/generation/test_editor_file_fetcher.py b/tests/unit/generation/test_editor_file_fetcher.pynew file mode 100644index 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.pynew file mode 100644index 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