milens 0.6.4 → 0.6.6

package/README.md

@@ -7,8 +7,9 @@
   <a href="https://www.npmjs.com/package/milens"><img src="https://img.shields.io/npm/v/milens" alt="npm"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node"></a>
   <a href="https://github.com/fuze210699/milens/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
-  <img src="https://img.shields.io/badge/tools-33-purple" alt="33 tools">
-  <img src="https://img.shields.io/badge/prompts-6-orange" alt="6 prompts">
+  <img src="https://img.shields.io/badge/tools-41-purple" alt="41 tools">
+  <img src="https://img.shields.io/badge/languages-12-blue" alt="12 languages">
+  <img src="https://img.shields.io/badge/prompts-7-orange" alt="7 prompts">
   <img src="https://img.shields.io/badge/security-50%2B-red" alt="50+ rules">
   <img src="https://img.shields.io/badge/harnesses-7-lightgrey" alt="7 harnesses">
 </p>
@@ -19,62 +20,60 @@
   <a href="https://github.com/fuze210699/milens">⭐ Star</a> ·
   <a href="https://github.com/sponsors/fuze210699">💖 Sponsor</a> ·
   <a href="https://github.com/fuze210699/milens/discussions">💬 Discussions</a> ·
-  <a href="https://github.com/fuze210699/milens/blob/main/docs/pricing.md">Pro $19/seat</a>
+  <a href="https://github.com/fuze210699/milens/blob/main/docs/pricing.md">Pro $1/seat</a>
 </p>
 
 ---
 
-## The Problem
+## Quick Install
 
-AI coding agents are powerful — but they don't truly know your codebase.
-
-**What happens every session:**
-
-1. Agent edits `UserService.validate()`
-2. Doesn't know 47 functions depend on its return type
-3. **Breaking changes ship to production**
-
-The deeper issue: agents waste **70% of their context window** just trying to understand the codebase. Reading files one by one. Grep'ing for references. Tracing call chains manually. Every session starts from zero — last session's discoveries are gone.
-
-After 10-20 AI sessions, the codebase accumulates dead code, untested hubs, and forgotten security gaps. The agent gets slower, more confused, and more expensive — while the developer burns tokens and patience.
-
----
-
-## Without Milens vs With Milens
-
-| Situation | Without Milens | With Milens |
-|---|---|---|
-| **Understand a new codebase** | Agent reads 15 files blind (~30,000 tokens) | `codebase_summary()` — 500 tokens, complete overview |
-| **Edit a function safely** | No idea what depends on it. Hope it doesn't break. | `impact({target, depth: 3})` — exact blast radius before every edit |
-| **Find all references** | Grep 5 times, read 8 files, miss template usages | `context({name})` — incoming + outgoing, one call |
-| **Review a PR** | Read diff, guess risk, miss hidden dependencies | `review_pr()` — every symbol scored CRITICAL/HIGH/MEDIUM/LOW |
-| **Security audit** | 10 manual greps for secrets, injections, unicode | `security_scan()` — 50 rules, one tool call |
-| **Start a new session** | Zero context. Re-learn everything from scratch. | `recall()` — agent remembers every past bug, caveat, and pattern |
-| **Write tests** | Guess what needs testing. Guess how to mock. | `test_plan()` — mock strategy + 3 scenarios + coverage gaps sorted by risk |
-| **Find dead code** | Manual search. "Is this still used? I'm not sure." | `find_dead_code()` — every exported symbol with zero references |
-
-**Average savings: ~70% fewer tokens per session. ~50% faster task completion.**
+```bash
+npx milens init --profile full
+npx milens analyze -p . --force
+```
 
 ---
 
 ## What is Milens?
 
-Milens gives AI coding agents **instant code intelligence**. Instead of reading 15 files to understand a codebase, your agent calls one tool and gets the full picture in 500 tokens.
+Milens builds a **knowledge graph** of your codebase — functions, classes, imports, calls, and inheritance chains — then exposes it through 41 MCP tools. AI agents query the graph instead of reading files.
+
+- **Parse 12 languages.** Tree-sitter WASM — TS, JS, Python, Java, Go, Rust, PHP, Ruby, Vue, HTML, CSS, Markdown.
+- **Query instantly.** FTS5 + recursive CTE — all in SQLite, no API calls.
+- **Edit safely.** Blast radius before every change. Symbol-level PR review with cross-file impact.
+- **Scan once.** 50+ security rules in one call instead of multiple greps.
+- **Learn continuously.** Annotations persist across sessions. High-confidence patterns can be promoted to rules.
+- **Dual-path resolver.** Legacy proximity + scope-graph compared for parity.
+- **Verify accuracy.** 8 test projects with expected.json validate precision/recall across all languages.
 
-It builds a **knowledge graph** of your entire project — every function, class, import, call, and inheritance chain — then exposes it through 33 MCP tools. Agents query the graph instead of searching files. The result: **70% fewer tokens** per session, **zero broken dependencies**, and a system that **learns from every session**.
+Fully offline. Zero telemetry. MCP server on `127.0.0.1`. Get started with `npx milens init`.
 
-- **Analyze once.** Tree-sitter parses 12 languages into a SQLite knowledge graph.
-- **Query instantly.** FTS5 search, recursive CTE traversal, vector similarity — all in-database.
-- **Edit safely.** Every tool returns a blast radius before you change anything.
-- **Scan automatically.** 50+ security rules run in one call, not ten greps.
-- **Learn continuously.** Annotations persist across sessions. Patterns auto-promote to rules.
+---
 
-Fully offline. Zero telemetry. Localhost-only MCP server. One command to bootstrap.
+## Architecture
 
 ```
-npx milens init --profile full
+Source files (12 languages)
+  │
+  ▼
+Parser ── tree-sitter WASM → CST
+  │
+  ▼
+Analyzer ── extractFromTree() + dual-path resolver
+  │           ├── Legacy: proximity-based (resolveLinksWithStats)
+  │           └── Scope:  scope-graph-based (resolveWithScopes) → parity check
+  │
+  ▼
+Store ──── SQLite + FTS5 (symbols, links, metadata, embeddings)
+  │
+  ▼
+Server ─── MCP stdio/HTTP (41 tools)
+  │
+  ├── AI Agent (MCP client)
+  └── CLI (terminal)
 ```
 
+
 ---
 
 ## Quick Start
@@ -105,340 +104,260 @@ Then connect your editor:
 ```bash
 # Claude Code
 claude mcp add milens -- npx -y milens serve -p .
+```
 
+<details>
+<summary><b>More editors</b> — Cursor, OpenCode, Codex, Gemini, Zed</summary>
+
+```bash
 # Cursor — .cursor/mcp.json
 { "mcpServers": { "milens": { "command": "npx", "args": ["-y", "milens", "serve", "-p", "."] } } }
 
 # OpenCode — .opencode/config.json
 { "mcp": { "milens": { "command": "npx", "args": ["-y", "milens", "serve"] } } }
-```
 
-Open your AI agent. It auto-loads `AGENTS.md` with codebase context. You're ready.
-
----
+# Codex — .codex/config.toml
+[mcp_servers.milens]
+command = "npx"
+args = ["-y", "milens", "serve", "-p", "."]
 
-## Architecture
+# Gemini — .gemini/settings.json
+{ "mcpServers": { "milens": { "command": "npx", "args": ["-y", "milens", "serve", "-p", "."] } } }
 
-```
-                         npx milens init
-                               │
-              ┌────────────────┼────────────────┐
-              ▼                ▼                ▼
-         ANALYZE           GENERATE           CONFIGURE
-    tree-sitter parse     AGENTS.md         security rules
-    resolve imports       skill files       pre-commit hooks
-    build graph          adapter packs      CI templates
-              │                │                │
-              └────────────────┼────────────────┘
-                               ▼
-                       milens serve
-                               │
-              ┌────────────────┼────────────────┐
-              ▼                ▼                ▼
-         33 MCP TOOLS    6 SUB-AGENT     50+ SECURITY
-       query, impact,     PROMPTS            RULES
-       context, trace,   planner,         secrets, injection,
-       review_pr, ...    reviewer, ...    unicode, crypto, ...
-                               │
-                               ▼
-                        AI CODING AGENT
-              ┌────────────────┼────────────────┐
-              ▼                ▼                ▼
-         CODE SAFELY     REVIEW AUTO      LEARN CONTINUOUSLY
-       edit_check()    review_pr()      annotate → recall
-       impact()        security_scan()  evolve → promote
+# Zed — .zed/settings.json
+{ "mcp_servers": { "milens": { "command": "npx", "args": ["-y", "milens", "serve", "-p", "."] } } }
 ```
 
-### Four-Layer Stack
+</details>
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  PLATFORM LAYER                                         │
-│  GitHub App · npm · 7 adapter packs · Desktop Dashboard │
-│  Pricing: Free / Pro ($19/seat) / Enterprise            │
-├─────────────────────────────────────────────────────────┤
-│  AUTOMATION LAYER                                       │
-│  6 Hooks (SessionStart, SessionEnd, PreCommit, ...)     │
-│  Auto-annotate · Auto-recall · Watch mode               │
-│  Scheduled evolve (cron/schtasks) · Pre-commit hooks    │
-├─────────────────────────────────────────────────────────┤
-│  WORKFLOW LAYER                                         │
-│  6 Sub-agent Prompts (planner, reviewer, tester, ...)   │
-│  6 Skill files · AGENTS.md auto-generator               │
-│  Selective profiles (minimal/standard/full)             │
-├─────────────────────────────────────────────────────────┤
-│  INTELLIGENCE LAYER                                     │
-│  Knowledge Graph (SQLite+FTS5) · 33 MCP Tools            │
-│  Memory (annotations+sessions) · Learning (confidence)  │
-│  50+ Security Rules (OWASP) · 7 Metrics (TER, CQI, ...) │
-└─────────────────────────────────────────────────────────┘
-```
+Open your AI agent. It auto-loads `AGENTS.md` with codebase context. You're ready.
 
-### Pipeline
+---
 
-| Stage | What Happens | Technology |
+## Without Milens vs With Milens
+
+| Situation | Without Milens | With Milens |
 |---|---|---|
-| **Scan** | Discover source files by extension | Node.js `fs` |
-| **Parse** | Extract symbols, imports, calls, heritage | tree-sitter WASM (12 languages) |
-| **Resolve** | Match imports to files, calls to definitions | Cross-file linker |
-| **Enrich** | Compute roles, heat scores, domain clusters | Union-find + PageRank-like |
-| **Persist** | Store everything in SQLite | better-sqlite3 + FTS5 |
-| **Serve** | Expose via MCP protocol | stdio + StreamableHTTP |
-| **Learn** | Annotate → confidence score → promote → skill | SQLite + evolution log |
-| **Scan** | 50+ regex rules across all files | Built-in security engine |
-
-### Design Principles
-
-| Principle | Implementation |
-|---|---|
-| **One parse, infinite queries** | Knowledge graph pre-computed at analyze time |
-| **Zero network** | Everything offline. No API calls. No telemetry. |
-| **Token-compact** | `name [kind] file:line` format saves 40-60% tokens |
-| **Incremental** | SHA-256 file hashing. Only changed files re-parsed. |
-| **In-database traversal** | Recursive CTEs for graph queries. No full graph in memory. |
-| **Localhost only** | HTTP binds 127.0.0.1. No network exposure. |
-| **MCP standard** | Works with any MCP-compatible agent. No vendor lock-in. |
+| **Understand a new codebase** | Agent reads many files blind | `codebase_summary()` — compact overview |
+| **Edit a function safely** | No idea what depends on it | `impact({target, depth: 3})` — exact blast radius |
+| **Find all references** | Grep multiple times, read several files | `context({name})` — incoming + outgoing, one call |
+| **Review a PR** | Read diff, guess risk | `review_pr()` — changed symbols scored by blast radius + test coverage |
+| **Review a PR accurately** | Review guesses which functions changed | Symbol-level diff via git show — flags only actually changed symbols |
+| **Clean uninstall** | Manually delete files, hooks, configs | `milens uninstall` — scan 11 categories, interactive or auto |
+| **Security audit** | Multiple manual greps | `security_scan()` — 50+ rules, one tool call |
+| **Start a new session** | Zero context | `recall()` — retrieves past annotations |
+| **Write tests** | Guess what needs testing | `test_plan()` — dependency-aware strategy + scenarios |
+| **Find dead code** | Manual search | `find_dead_code()` — exported symbols with zero references |
+
+*And many more — see [real-world scenarios →](docs/scenarios.html)*
 
 ---
 
-## MCP Tools (33)
-
-### Search & Navigation
+## Features
 
-| Tool | Does |
+| Feature | Description |
 |---|---|
-| `query` | FTS5 full-text search for symbol definitions |
-| `grep` | Regex search across ALL project files (code, configs, docs, templates) |
-| `context` | 360° view: who calls this + what this depends on |
-| `get_file_symbols` | Every symbol in a file with ref/dep counts |
-| `get_type_hierarchy` | Full inheritance tree — ancestors + descendants |
+| **Code Intelligence** | 41 MCP tools — search, impact, context, trace, routes |
+| **Security Scanner** | 50+ rules across 9 categories + dependency audit |
+| **Sub-Agent Prompts** | 7 prompts — plan, review, tdd, security, architect, debug, dead_code_remove |
+| **CLI Workflows** | 7 commands — tdd, review, plan, onboard, security-scan, refactor, handoff |
+| **Uninstall** | Full cleanup — 11 trace categories, interactive or auto |
+| **Metrics** | 7 metrics — TER, LR, CQI, BRR, TCGR, DCER, CTR |
+| **Learning Engine** | Annotate → Recall → Evolve — confidence-based annotations |
+| **12 Languages** | TS, JS, Python, Java, Go, Rust, PHP, Ruby, Vue, HTML, CSS, Markdown |
+| **Cross-Language Linking** | HTML class → CSS selectors, Vue template → script symbols |
+| **Type Bindings & MRO** | Infer types from constructors. C3, first-wins, ruby-mixin strategies |
+| **Accuracy Validation** | 8 test projects with expected.json for precision/recall |
+| **Symbol-Level PR Diff** | `review_pr` diffs actual symbols between commits, not entire files |
+| **7 Editor Adapters** | Claude Code, Cursor, Copilot, OpenCode, Codex, Gemini, Zed |
 
-### Safety & Impact
+---
 
-| Tool | Does |
-|---|---|
-| `impact` | Blast radius: depth 1-3 traversal showing what breaks |
-| `edit_check` | Pre-edit safety: callers, re-exports, test coverage, warnings |
-| `detect_changes` | Git diff → which symbols changed + their dependents |
-| `find_dead_code` | Exported symbols with zero incoming references |
-| `overview` | context + impact + grep combined in one call |
+## CLI Commands
 
-### Understanding Code
+### Core
 
-| Tool | Does |
+| Command | Description |
 |---|---|
-| `smart_context` | Intent-aware context: `edit` / `debug` / `test` / `understand` |
-| `trace` | Full execution path from entrypoints to target (or reverse) |
-| `routes` | Auto-detect API endpoints across 11 frameworks |
-| `explain_relationship` | Shortest dependency chain between any two symbols |
-| `domains` | Module clusters based on cross-file dependency graph |
+| `init` | Bootstrap milens: index + AGENTS.md + skills + hooks |
+| `analyze` | Index a codebase: parse symbols, resolve dependencies, build search index |
+| `serve` | Start MCP server (stdio/HTTP) |
+| `watch` | Watch files for changes and auto re-index |
+| `status` | Show index status |
 
-### Review & Testing
+### Search & Inspect
 
-| Tool | Does |
+| Command | Description |
 |---|---|
-| `review_pr` | Scores every changed symbol CRITICAL/HIGH/MEDIUM/LOW |
-| `review_symbol` | Deep-dive: role, heat, dependents, test status, recommendation |
-| `codebase_summary` | ~500 token overview for session bootstrap |
-| `test_plan` | Mock strategy + 3+ test scenarios based on dependencies |
-| `test_coverage_gaps` | Untested symbols sorted by risk |
-| `test_impact` | Maps changed code → which test files to run |
+| `search <query>` | Search symbols by name |
+| `inspect <symbol>` | 360° view: refs, deps, hierarchy |
+| `impact <symbol>` | Blast radius: what breaks if this symbol changes? |
 
-### Memory & Sessions
+### Maintenance
 
-| Tool | Does |
+| Command | Description |
 |---|---|
-| `annotate` | Save observation about a symbol (persists forever) |
-| `recall` | Retrieve past annotations by symbol, key, agent, or session |
-| `session_start` | Begin new session with agent identity |
-| `session_context` | Session metadata + tool calls + annotations |
-| `session_end` | Close session, record stats |
-| `handoff` | Transfer all context from one agent session to another |
+| `clean` | Remove index for a repository |
+| `uninstall` | Remove all milens traces: injected blocks, generated files, hooks, cron, database, registry, MCP configs, deps, env vars |
+| `upgrade` | Upgrade milens: clear npx cache, rebuild index while keeping annotations/sessions |
+| `list` | List all indexed repositories |
 
 ### Security
 
-| Tool | Does |
+| Command | Description |
 |---|---|
-| `security_scan` | **50+ rules in one call.** Scopes: secrets, injection, unicode, dangerous, config, data-leak, crypto, auth, file-access |
+| `security scan` | Scan project for vulnerabilities (50+ rules, scope/severity filterable) |
+| `security deps` | Audit dependencies for known vulnerabilities |
 
-### Overview & Similarity
+### Quality & Evolution
 
-| Tool | Does |
+| Command | Description |
 |---|---|
-| `status` | Index stats, test coverage %, link accuracy |
-| `repos` | List all indexed repositories |
-| `semantic_search` | Meaning-based symbol search (FTS5 + vector hybrid) |
-| `find_similar` | Symbols with shared callers/callees (topological similarity) |
+| `metrics` | Compute code quality and efficiency metrics |
+| `evolve` | Promote high-confidence annotations to rules/skills |
+| `orchestrate` | Full review cycle: detect changes → risk → coverage gaps → dead code |
 
-### Developer
+### Workflows
 
-| Tool | Does |
+| Command | Description |
 |---|---|
-| `ast_explore` | Parse code snippet → S-expression AST tree |
-| `test_query` | Test a tree-sitter query against code |
+| `workflow tdd` | Test coverage gaps + risk-prioritized untested symbols |
+| `workflow review` | PR risk analysis — git diff + heat scoring |
+| `workflow plan` | Codebase summary — domains, top hubs |
+| `workflow onboard` | Onboarding report — structure, entry points |
+| `workflow security-scan` | Full security audit |
+| `workflow refactor` | Dead code detection + candidates |
+| `workflow handoff` | Session knowledge summary |
 
----
+### Hooks
 
-## Tool Output Examples
+| Command | Description |
+|---|---|
+| `hooks enable` | Turn on all hooks |
+| `hooks disable` | Turn off hooks |
+| `hooks profile <name>` | Apply hook presets (minimal, standard, full) |
 
-### Context — 360° Symbol View
+### Dashboard
 
-```
-context({name: "AuthService"})
+| Command | Description |
+|---|---|
+| `dashboard` | Open usage analytics dashboard in browser |
 
-AuthService [class] src/auth.ts:15 (exported)
-role: hub | heat: 0.85
+---
 
-incoming (3):
-  calls: handleLogin [function] src/routes.ts:23
-  calls: UserController [class] src/controllers/user.ts:8
-  imports: authRouter [variable] src/routes.ts:1
+## MCP Tools
 
-outgoing (3):
-  imports: User [class] src/models.ts:5
-  calls: hashPassword [function] src/auth.ts:3
-  calls: createUser [function] src/models.ts:42
-```
+### Search & Navigation
 
-### Impact — Blast Radius
+| Tool | Description |
+|---|---|
+| `query` | Find symbol definitions by name (FTS5) |
+| `grep` | Text search across all files — code, templates, configs, docs |
+| `context` | 360° view: incoming refs + outgoing deps |
+| `get_file_symbols` | All symbols in a file |
+| `get_type_hierarchy` | Inheritance/implementation tree |
+| `semantic_search` | Hybrid FTS5 + vector search (requires `--embeddings`) |
+| `find_similar` | Find symbols topologically similar |
 
-```
-impact({target: "createUser", direction: "upstream", depth: 3})
+### Impact & Safety
 
-TARGET: createUser [function] src/models.ts:42
+| Tool | Description |
+|---|---|
+| `impact` | Blast radius — what breaks if this symbol changes? |
+| `edit_check` | Pre-edit safety: callers, export status, re-export chains, warnings |
+| `overview` | Combined context + impact + grep in one call |
+| `detect_changes` | Git diff → affected symbols + dependents |
+| `find_dead_code` | Exported symbols with zero incoming references |
+| `pre_commit_check` | Pre-commit risk: review_pr + dead code + coverage gaps |
+| `compare_impact` | Compare impact graph before/after edit |
 
-  [depth 1] WILL BREAK:
-    AuthService [class] src/auth.ts:15 (calls)
-    UserController [class] src/controllers/user.ts:8 (calls)
+### Review & Testing
 
-  [depth 2] LIKELY AFFECTED:
-    handleLogin [function] src/routes.ts:23 (calls)
-    handleRegister [function] src/routes.ts:45 (calls)
+| Tool | Description |
+|---|---|
+| `review_pr` | PR risk assessment: symbol-level diff via git show, cross-file impact |
+| `review_symbol` | Single symbol deep-dive: role, heat, dependents, test status, risk |
+| `codebase_summary` | Compact codebase overview: domains, top hubs, coverage |
+| `test_plan` | Dependency-aware test strategy: mocks, scenarios |
+| `test_generate` | Auto-generate test file with framework detection |
+| `test_coverage_gaps` | Untested exported symbols sorted by risk |
+| `test_impact` | Map code changes to which test files to run |
 
-  [depth 3] MAY NEED TESTING:
-    authRouter [variable] src/routes.ts:1 (imports)
-    adminDashboard [function] src/admin.ts:10 (calls)
+### Orchestration
 
-5 dependents across 3 depths
-```
+| Tool | Description |
+|---|---|
+| `orchestrate` | detect_changes → review_pr → impact → coverage gaps → dead code → action plan |
 
-### Review PR — Risk Assessment
+### Understanding
 
-```
-review_pr({})
+| Tool | Description |
+|---|---|
+| `smart_context` | Intent-aware: understand/edit/debug/test |
+| `trace` | Execution flow: call chains from entrypoints to target |
+| `routes` | Detect framework routes/endpoints (Express, FastAPI, NestJS, etc.) |
+| `explain_relationship` | Shortest dependency path between two symbols |
+| `domains` | Domain clusters: files forming logical modules |
 
-PR Risk Assessment (vs HEAD):
-  6 changed files, 12 affected symbols
+### Memory & Sessions
 
-  handlePayment [function] src/payment.ts:30 — heat:92 deps:15 test:no → CRITICAL(85)
-  checkoutRoute [function] src/routes/checkout.ts:5 — heat:78 deps:8 test:yes → HIGH(58)
-  UserModel [class] src/models.ts:20 — heat:65 deps:3 test:yes → MEDIUM(35)
-  formatCurrency [function] src/utils.ts:45 — heat:10 deps:0 test:no → LOW(15)
+| Tool | Description |
+|---|---|
+| `annotate` | Record a note about a symbol (persists across sessions) |
+| `recall` | Retrieve annotations from past sessions |
+| `session_start` | Register agent session for multi-agent coordination |
+| `session_end` | End session and record stats |
+| `session_context` | Get session metadata + annotations |
+| `handoff` | Transfer context between agent sessions |
 
-Summary: CRITICAL=1 HIGH=2 MEDIUM=4 LOW=5
-```
+### Security
 
-### Security Scan — 50 Rules at Once
+| Tool | Description |
+|---|---|
+| `security_scan` | Scan for vulnerabilities — 50+ rules, 9 categories |
+| `fix_apply` | Apply security fix to a file (creates backup) |
 
-```
-security_scan({scope: "all", severity: "HIGH"})
+### Hooks
 
-{
-  "summary": {
-    "totalScanned": 1240,
-    "findings": 8,
-    "bySeverity": { "CRITICAL": 1, "HIGH": 3, "MEDIUM": 4 },
-    "score": 78
-  },
-  "findings": [
-    {
-      "ruleId": "SEC-001",
-      "category": "secrets",
-      "severity": "CRITICAL",
-      "owasp": "A02:2021",
-      "file": "src/config.ts",
-      "line": 15,
-      "match": "password = 'admin123'",
-      "fix": "Move to environment variable: process.env.DB_PASSWORD"
-    },
-    {
-      "ruleId": "SEC-011",
-      "category": "injection",
-      "severity": "HIGH",
-      "owasp": "A03:2021",
-      "file": "src/routes/admin.ts",
-      "line": 42,
-      "match": "eval(userInput)",
-      "fix": "Replace eval() with a safe parser or validator"
-    }
-  ]
-}
-```
+| Tool | Description |
+|---|---|
+| `hook_onFileChange` | Trigger when files are modified → impact summary |
+| `hook_preCompact` | Save metrics snapshot before context compaction |
+| `hook_postCompact` | Restore context by recalling annotations after compaction |
 
----
+### Codebase Overview
 
-## Sub-agent Prompts (6)
+| Tool | Description |
+|---|---|
+| `status` | Index stats: symbols, links, files, coverage, staleness |
+| `repos` | List all indexed repositories with summary stats |
 
-Instead of chaining 5-10 tools manually, your agent calls one prompt:
+### Developer
 
-| Prompt | Input | Workflow |
-|---|---|---|
-| `milens-planner` | Feature description | Research → Analyze Target → Predict Impact → Plan Tests → **Implementation Plan** |
-| `milens-reviewer` | Change description | Scan PR → Deep-dive Symbols → Find Dead Code → Text Search → **Review Report** |
-| `milens-tester` | Symbol name | Find Gaps → Generate Plan → Implement → Verify → **Coverage Report** |
-| `milens-architect` | (none) | Overview → Domains → Routes → Hierarchy → Connections → **Architecture Analysis** |
-| `milens-security` | (none) | Scan PR → Secrets → Unicode → Dangerous → Data Leak → **Security Audit** |
-| `milens-debugger` | Target + error | Context → Trace Execution → Impact → Find Relationship → **Root Cause Analysis** |
+| Tool | Description |
+|---|---|
+| `ast_explore` | Parse code snippet to S-expression AST tree |
+| `test_query` | Run tree-sitter query against code snippet |
 
 ---
 
-## CLI Commands
+## Sub-Agent Prompts
 
-```
-milens init [--profile minimal|standard|full] [--interactive]    Bootstrap a project
-milens analyze [-p .] [--force] [--skills] [--embeddings]        Index a codebase
-milens serve [-p .] [--http] [--port 3100] [--profile minimal]   Start MCP server
-milens workflow <name>                                            Run predefined pipeline
-milens security scan [--scope secrets] [--severity HIGH]          Security audit
-milens security deps                                              Dependency CVE check
-milens hooks enable|disable|list|profile                          Manage automation
-milens watch [--debounce 2000]                                    Auto re-index on change
-milens evolve [--schedule install|uninstall|status]               Promote learned patterns
-milens metrics                                                    TER, CQI, BRR, CTR...
-milens search <query> [--limit 50]                                Find symbols
-milens inspect <symbol>                                           Incoming + outgoing deps
-milens impact <symbol> [-d downstream] [--depth 2]                Blast radius
-milens status [-p .]                                              Index health
-milens list                                                       All indexed repos
-milens clean [-p .] [--all]                                       Remove index
-milens dashboard [--port 8080]                                    Usage analytics
-```
-
-### Workflow Examples
-
-```bash
-milens workflow tdd                          # Find test gaps → plan → verify
-milens workflow review                       # PR review → risk scores → dead code
-milens workflow plan "Add Stripe billing"    # Full implementation plan
-milens workflow onboard                      # Session startup checklist
-milens workflow security-scan                # All 50 rules at once
-```
-
-### Profile Selection
-
-Control how many tools are active to optimize token overhead:
-
-```bash
-MILENS_PROFILE=minimal milens serve          # 10 tools — ~500 token overhead
-MILENS_PROFILE=standard milens serve         # 25 tools — full daily coding
-milens serve --profile full                  # 33 tools — everything
-```
+| Prompt | Purpose |
+|---|---|
+| `milens-planner` | Implementation planning with blast radius + test strategy |
+| `milens-reviewer` | PR review — risk scan → deep dive → dead code → security |
+| `milens-tester` | TDD — coverage gaps → test plans → implement → verify |
+| `milens-security` | Security audit — secrets, injection, unicode, crypto, config |
+| `milens-architect` | Architecture analysis — domains, routes, coupling, hierarchy |
+| `milens-debugger` | Root cause analysis — trace → blast radius → hypotheses → fixes |
+| `dead_code_remove` | Safe dead code removal with impact verification |
 
 ---
 
 ## Security (50+ Rules)
 
-All 50 rules map to **OWASP Top 10 (2021)**. One tool call covers what used to take 10 manual greps.
+Rules cover common vulnerability patterns. One `security_scan()` call replaces multiple manual greps.
 
 | Category | Rules | Detects |
 |---|---|---|
@@ -446,107 +365,30 @@ All 50 rules map to **OWASP Top 10 (2021)**. One tool call covers what used to t
 | **injection** | 9 | SQL injection, XSS, command injection, `eval()`, `exec()`, dangerous DOM |
 | **unicode** | 4 | Zero-width chars, bidi override, homoglyph attacks |
 | **dangerous** | 7 | `os.system`, `subprocess shell`, unsafe deserialization, `spawn shell` |
-| **config** | 5 | CORS wildcards, insecure cookies, debug mode, `--dangerously-skip-permissions` |
+| **config** | 5 | CORS wildcards, insecure cookies, debug mode |
 | **data-leak** | 5 | `console.log` of secrets, hardcoded URLs |
 | **crypto** | 4 | MD5, SHA1, `Math.random()` for crypto, hardcoded salt/IV |
-| **auth** | 4 | String comparison, missing middleware, JWT without expiry, session in URL |
+| **auth** | 4 | String comparison, missing middleware, JWT without expiry |
 | **file-access** | 2 | Path traversal, unsafe file reads |
 
 ```bash
 milens security scan --scope secrets --severity HIGH --format json
-milens security deps                    # Offline CVE check (34 known vulns, 5 ecosystems)
+milens security deps                    # Offline CVE database check
 ```
 
 From an AI agent: `security_scan({scope: "all", severity: "HIGH"})`
 
 ---
 
-## Hook System (6 Triggers)
-
-Automation so your agent never forgets:
-
-| Hook | When | Default Action |
-|---|---|---|
-| `onSessionStart` | Agent begins work | Refresh index + codebase_summary + recall past warnings |
-| `onSessionEnd` | Agent finishes | detect_changes + review_pr + auto-annotate changed symbols |
-| `onPreCommit` | Before `git commit` | detect_changes + review_pr + find_dead_code |
-| `onFileChange` | Files modified | Re-analyze changed files + impact on affected symbols |
-| `onPreCompact` | Before context window compaction | Save codebase_summary snapshot |
-| `onPostCompact` | After compaction | recall annotations to restore lost context |
-
-```bash
-milens hooks enable                          # Turn on all hooks
-milens hooks profile standard                # Preset: SessionStart, SessionEnd, PreCommit
-milens hooks disable --hook preCommit        # Turn off one hook
-```
-
----
-
-## Learning & Evolution
-
-The system gets smarter every session:
-
-```
-SESSION 1:  Agent finds bug in createUser()
-            → annotate({symbol: "createUser", key: "bug", value: "Call createUser() before normalizeEmail()"})
-            → confidence: 0.5
-
-SESSION 2:  Agent auto-recalls the annotation
-            → "I know createUser() has a known issue. I'll handle the order correctly."
-            → Bug avoided. confidence ↑ 0.7
-
-SESSION 5:  Confidence reaches 0.9
-            → milens evolve promotes it to .agents/skills/milens-bug/SKILL.md
-            → Now enforced as a rule for every future session
-```
-
-```bash
-milens evolve                           # Promote high-confidence patterns now
-milens evolve --schedule install        # Auto-run weekly (cron/schtasks)
-```
-
 ---
 
-## Supported Languages
-
-12 languages through tree-sitter:
-
-| Language | Files | Imports | Calls | Heritage |
-|---|---|---|---|---|
-| TypeScript | `.ts` `.tsx` | ESM + CJS + decorators | ✓ + decorators | extends / implements |
-| JavaScript | `.js` `.jsx` `.mjs` `.cjs` | ESM + CJS | ✓ | extends |
-| Python | `.py` | import + relative | ✓ + decorators | extends |
-| Java | `.java` | import + static | ✓ + annotations | extends / implements |
-| Go | `.go` | import + go.mod | ✓ | embedding |
-| Rust | `.rs` | use | ✓ + macros | trait impl |
-| PHP | `.php` | use + include | ✓ + static, new | extends + traits |
-| Ruby | `.rb` | require | ✓ | extends |
-| Vue | `.vue` | ESM | ✓ template refs | extends |
-| HTML | `.html` `.htm` | `<script src>` `<link>` | ✓ inline | — |
-| CSS | `.css` | `@import` | — | — |
-| Markdown | `.md` `.mdx` | local `[links]()` | — | headings as sections |
-
-**Framework detection** (via `routes()`)**: Express, FastAPI, NestJS, Flask, Django, Go net/http, Gin, PHP Laravel, Rails, Sinatra, Spring.
-
----
-
-## Editor & Harness Support
-
-Milens works with any MCP-compatible agent. Two ways to use:
-
-| | MCP Server | CLI |
-|---|---|---|
-| **What** | Real-time tools for AI agents during coding | Direct commands from terminal |
-| **For** | Daily development with AI agents | Scripts, CI/CD, one-off analysis |
-| **Setup** | Add MCP config to editor | `npm install -g milens` |
-| **Tools** | All 33 tools + 6 prompts | Full CLI command set |
-| **Example** | Agent calls `impact()` before editing | `milens security scan --scope secrets` |
+## Editor Adapters
 
-**Harness adapters available for 7 editors:**
+Milens works with any MCP-compatible agent:
 
 | Harness | Config File | Recommended Profile |
 |---|---|---|
-| **Claude Code** | `.claude/mcp.json` | standard (25 tools) |
+| **Claude Code** | `.claude/mcp.json` | standard |
 | **OpenCode** | `.opencode/config.json` | standard |
 | **VS Code / Copilot** | `.vscode/mcp.json` | standard |
 | **Cursor** | `.cursorrules` | standard |
@@ -556,28 +398,20 @@ Milens works with any MCP-compatible agent. Two ways to use:
 
 Each adapter is in the `adapters/` directory with ready-to-copy config files and agent instructions.
 
+### Profile Selection
+
+```bash
+MILENS_PROFILE=minimal milens serve          # 10 tools — lighter footprint
+MILENS_PROFILE=standard milens serve         # 25 tools — full daily coding
+milens serve --profile full                  # 41 tools — everything
+```
+
 ---
 
 ## Metrics
 
 Seven quantified metrics for AI-driven development:
 
-```
-$ milens metrics
-
-╔══════════════════════════════════════════════╗
-║         Milens Metrics Report               ║
-╠══════════════════════════════════════════════╣
-║ TER:   Token Efficiency Ratio       0.85     ║
-║ LR:    Learning Rate                0.59     ║
-║ CQI:   Code Quality Index           7.2/10   ║
-║ BRR:   Bug Recurrence Rate          8%       ║
-║ TCGR:  Test Coverage Growth Rate    5.2%/wk  ║
-║ DCER:  Dead Code Elimination Rate   3%       ║
-║ CTR:   Cycle Time Reduction         67%      ║
-╚══════════════════════════════════════════════╝
-```
-
 | Metric | Full Name | What It Tracks |
 |---|---|---|
 | **TER** | Token Efficiency Ratio | Useful tokens ÷ total tokens |
@@ -588,98 +422,88 @@ $ milens metrics
 | **DCER** | Dead Code Elimination Rate | Dead symbols ÷ total exported |
 | **CTR** | Cycle Time Reduction | Time saved vs manual approach |
 
----
-
-## Security & Privacy
-
-**Zero network. Zero telemetry. Zero data leaving your machine.**
-
-| Layer | Guarantee |
-|---|---|
-| **Data** | Index stored in `.milens/` per repo (gitignored). No source code in registry. |
-| **Network** | HTTP binds `127.0.0.1` only. No outbound connections. |
-| **Input** | User regex validated against ReDoS. FTS5 tokens quoted as literals. |
-| **File access** | All paths bounded to repo root. No traversal possible. |
-| **Git** | `execFileSync` with arg arrays. No shell interpolation. |
-| **Embeddings** | Optional. Generated locally via Xenova transformers. No API calls. |
+```bash
+milens metrics
+```
 
 ---
 
-## Pricing
-
-| Tier | Price | Key Features |
-|---|---|---|
-| **Free** | $0 | All 33 tools, public repos, 50+ security rules, CLI, community support. MIT core. |
-| **Pro** | $19/seat/mo | Private repos, GitHub App, advanced scanning, priority support, custom skills |
-| **Enterprise** | Contact | SSO/SAML, audit logging, on-prem, custom rules, SLAs, rollout consulting |
-
-OSS stays free forever. [Full pricing details →](docs/pricing.md)
+## Learning & Evolution
 
----
+The system gets smarter every session:
 
-## What's New in v0.7.0
+```
+SESSION 1:  Agent finds bug in createUser()
+            → annotate({symbol: "createUser", key: "bug", value: "Call createUser() before normalizeEmail()"})
+            → confidence: 0.5
 
-- **6 Sub-agent MCP Prompts** — planner, reviewer, tester, architect, security-auditor, debugger. One prompt replaces 5-10 chained tool calls.
-- **50+ Built-in Security Rules** — OWASP Top 10 mapped. `security_scan()` replaces 10 manual greps. Dependency audit for 5 ecosystems.
-- **Hook System** — 6 event triggers (SessionStart, SessionEnd, PreCommit, FileChange, PreCompact, PostCompact). Auto-annotate, auto-recall.
-- **`milens init`** — One-command bootstrap: analyze + AGENTS.md + skill files + security rules + pre-commit hooks.
-- **`milens workflow`** — 7 predefined pipelines: tdd, review, plan, security-scan, refactor, onboard, handoff.
-- **Selective Profiles** — `minimal` (10 tools), `standard` (25), `full` (33). Control token overhead.
-- **Watch Mode** — Auto re-index on file changes. `milens watch`.
-- **Scheduled Evolve** — Auto-promote high-confidence patterns to skills. `milens evolve --schedule install`.
-- **7 Harness Adapters** — Claude Code, OpenCode, Codex, Cursor, Copilot, Gemini, Zed.
-- **GitHub App** — Probot-based app for automated PR review and `/milens analyze` on repos.
-- **Desktop Dashboard** — Electron-based desktop app with 6 tabs (Overview, Domains, Learning, Metrics, Security, Settings).
-- **Interactive Installer** — `milens init --interactive` walks through every option step by step.
+SESSION 2:  Agent auto-recalls the annotation
+            → "I know createUser() has a known issue. I'll handle the order correctly."
+            → Bug avoided. confidence ↑ 0.7
 
-[Full changelog →](https://github.com/fuze210699/milens/releases)
+SESSION 5:  Confidence reaches 0.9
+            → milens evolve promotes it to .agents/skills/milens-bug/SKILL.md
+            → Now enforced as a rule for every future session
+```
 
 ---
 
-## Environment Variables
+## Hook System (6 Triggers)
 
-| Variable | Default | Effect |
+| Hook | When | Default Action |
 |---|---|---|
-| `MILENS_PROFILE` | (unset = full) | Tool set: `minimal` (10 tools), `standard` (25), `full` (33) |
-| `MILENS_VERSION` | (from package.json) | Override version reported in MCP server metadata |
-
-Use in MCP config:
-```json
-{
-  "mcpServers": {
-    "milens": {
-      "command": "npx",
-      "args": ["-y", "milens", "serve"],
-      "env": { "MILENS_PROFILE": "standard" }
-    }
-  }
-}
-```
+| `onSessionStart` | Agent begins work | Refresh index + codebase_summary + recall past warnings |
+| `onSessionEnd` | Agent finishes | detect_changes + review_pr + auto-annotate changed symbols |
+| `onPreCommit` | Before `git commit` | detect_changes + review_pr + find_dead_code |
+| `onFileChange` | Files modified | Re-analyze changed files + impact on affected symbols |
+| `onPreCompact` | Before context window compaction | Save codebase_summary snapshot |
+| `onPostCompact` | After compaction | recall annotations to restore lost context |
 
-Or from CLI:
 ```bash
-MILENS_PROFILE=minimal milens serve
+milens hooks enable                          # Turn on all hooks
+milens hooks profile standard                # Preset: SessionStart, SessionEnd, PreCommit
+milens hooks disable --hook preCommit        # Turn off one hook
 ```
 
 ---
 
-## Development
+## Security & Privacy
 
-```bash
-git clone https://github.com/fuze210699/milens.git
-cd milens
-npm install
-npm run build          # tsc → dist/
-npm test               # vitest (136 tests)
-npm run lint           # tsc --noEmit
-npm run self-analyze   # Index milens with milens
-npm run self-serve     # Start MCP on port 3100
-```
+Milens runs entirely on your machine. **No network calls. No telemetry. No data ever leaves your device.**
+
+| What you worry about | How milens protects you |
+|---|---|
+| Source code leaking | Index stored in `.milens/` per repo, gitignored by default. Registry tracks repo paths only — zero source code stored. |
+| Network calls | MCP server binds `127.0.0.1` exclusively. No outbound connections. Works fully offline. |
+| Shell injection | All system calls use `execFileSync` with argument arrays — no string interpolation into shell. |
+| Path traversal | File paths bounded to repo root. Symlinks outside root are rejected. |
+| Dependency CVEs | Optional `security deps` audit against offline CVE database. No external API calls. |
+| Embeddings privacy | Optional. Generated locally via Xenova transformers. No data sent to any service. |
+| Input attacks | Regex validated against ReDoS. FTS5 tokens passed as SQLite literals. |
 
-**Tech Stack:** TypeScript (ESM) · tree-sitter (WASM) · SQLite (better-sqlite3 + FTS5) · MCP SDK · Vitest · Commander
+Everything that touches your code stays on your filesystem. Built for production use with zero trust required.
 
 ---
 
+## Supported Languages
+
+<p align="center">
+  <img src="https://img.shields.io/badge/TypeScript-.ts%20.tsx-3178C6?logo=typescript&logoColor=white" alt="TS">
+  <img src="https://img.shields.io/badge/JavaScript-.js%20.jsx-F7DF1E?logo=javascript&logoColor=black" alt="JS">
+  <img src="https://img.shields.io/badge/Python-.py-3776AB?logo=python&logoColor=white" alt="PY">
+  <img src="https://img.shields.io/badge/Java-.java-ED8B00?logo=openjdk&logoColor=white" alt="Java">
+  <img src="https://img.shields.io/badge/Go-.go-00ADD8?logo=go&logoColor=white" alt="Go">
+  <img src="https://img.shields.io/badge/Rust-.rs-000000?logo=rust&logoColor=white" alt="Rust">
+  <img src="https://img.shields.io/badge/PHP-.php-777BB4?logo=php&logoColor=white" alt="PHP">
+  <img src="https://img.shields.io/badge/Ruby-.rb%20.rake-CC342D?logo=ruby&logoColor=white" alt="Ruby">
+  <img src="https://img.shields.io/badge/Vue-.vue-4FC08D?logo=vuedotjs&logoColor=white" alt="Vue">
+  <img src="https://img.shields.io/badge/HTML-.html%20.htm-E34F26?logo=html5&logoColor=white" alt="HTML">
+  <img src="https://img.shields.io/badge/CSS-.css-1572B6?logo=css3&logoColor=white" alt="CSS">
+  <img src="https://img.shields.io/badge/Markdown-.md%20.mdx-000000?logo=markdown&logoColor=white" alt="MD">
+</p>
+
+12 languages parsed via tree-sitter WASM. [Full support details →](docs/languages.md)
+
 ## License
 
 Core (analyzer, parser, store, CLI, MCP tools): **MIT License**
@@ -691,6 +515,9 @@ See [LICENSE](LICENSE) for details.
 <p align="center">
   <a href="https://github.com/fuze210699/milens">GitHub</a> ·
   <a href="https://github.com/fuze210699/milens/tree/main/docs">Docs</a> ·
+  <a href="https://github.com/fuze210699/milens/blob/main/docs/cli.md">CLI</a> ·
+  <a href="https://github.com/fuze210699/milens/blob/main/docs/accuracy.md">Accuracy</a> ·
+  <a href="https://github.com/fuze210699/milens/blob/main/docs/languages.md">Languages</a> ·
   <a href="https://github.com/fuze210699/milens/blob/main/docs/pricing.md">Pricing</a> ·
   <a href="https://github.com/fuze210699/milens/blob/main/CONTRIBUTING.md">Contribute</a>
 </p>