milens 0.6.3 → 0.6.5

package/README.md

@@ -1,620 +1,523 @@
 <p align="center">
-  <strong>milens</strong><br>
-  <em>Code Intelligence Engine for AI Agents</em>
+  <strong>Milens</strong><br>
+  <em>AI-DOS — The Operating System for AI-Driven Development</em>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/milens"><img src="https://img.shields.io/npm/v/milens" alt="npm version"></a>
-  <a href="https://github.com/fuze210699/milens/blob/develop/LICENSE"><img src="https://img.shields.io/badge/license-PolyForm--Noncommercial-blue" alt="License: PolyForm Noncommercial"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js >= 20"></a>
-  <img src="https://img.shields.io/badge/languages-12-orange" alt="12 Languages">
-  <img src="https://img.shields.io/badge/MCP_tools-32-purple" alt="32 MCP Tools">
-</p>
-
-<p align="center">
-  <strong>Index any codebase → Knowledge graph → AI agents that never miss code</strong>
-</p>
-
-<p align="center">
-  <a href="#the-problem">Why?</a> •
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#mcp-tools">MCP Tools</a> •
-  <a href="#tool-examples">Examples</a> •
-  <a href="#editor-setup">Editors</a> •
-  <a href="#supported-languages">Languages</a>
+  <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-41-purple" alt="41 tools">
+  <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>
 
 ---
 
-## The Problem
-
-You're burning tokens and premium requests on tasks that milens can handle at a fraction of the cost. Every time your agent explores a codebase — reading files one by one, searching for references, tracing call chains — you're paying for what a pre-built knowledge graph delivers instantly.
-
-**Why not let milens save your wallet?**
-
-One `milens analyze` replaces dozens of agent tool calls. Instead of the agent spending 10+ steps to map out a function's dependencies, `impact()` returns the full blast radius in a single call.
-
-If you're concerned about security, read our [Security & Privacy](#security--privacy) guarantees — milens is fully offline, zero telemetry, localhost-only.
-
-### How milens Solves This
-
 <p align="center">
-  <img src="https://raw.githubusercontent.com/fuze210699/milens/develop/docs/diagram1.svg" alt="Without milens vs With milens comparison" width="700">
+  <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 $1/seat</a>
 </p>
 
-milens builds a **pre-indexed knowledge graph** at analysis time — resolving every import, call, and inheritance chain — so that any tool query returns the full dependency picture instantly, without multi-step exploration.
-
 ---
 
-## Quick Start
+## Quick Install
 
 ```bash
-npx milens analyze                          # index your codebase
+npx milens init --profile full
+npx milens analyze -p . --force
 ```
 
-Then add the MCP server to your editor ([setup below](#editor-setup)) and your agent immediately gets 32 code intelligence tools.
-
 ---
 
-## CLI Commands
-
-### `milens analyze` — Index a codebase
-
-Parse all source files, resolve cross-file dependencies, and build a searchable knowledge graph.
-
-```bash
-milens analyze                              # index current directory
-milens analyze -p /path/to/repo             # index a specific repo
-milens analyze -p . --force                 # full re-index (ignore cache)
-milens analyze -p . --force --verbose       # full re-index with detailed progress
-```
-
-**Output:** A `.milens/milens.db` SQLite database containing every symbol, relationship, and search index.
-
-**Incremental mode:** By default, only re-parses files whose SHA-256 hash has changed since the last run.
-
-#### Generating AI skill files
-
-Skill files teach your AI agent the codebase structure — key symbols, entry points, cross-area dependencies — without reading every file.
+## What is Milens?
 
-```bash
-milens analyze -p . --skills                # generate for all editors
-milens analyze -p . --skills-copilot        # GitHub Copilot only
-milens analyze -p . --skills-cursor         # Cursor only
-milens analyze -p . --skills-claude         # Claude Code only
-milens analyze -p . --skills-agents         # AGENTS.md only
-milens analyze -p . --skills-windsurf       # Windsurf only
-```
-
-| Flag | Output files |
-|---|---|
-| `--skills-copilot` | `.github/instructions/*.instructions.md` + `.github/copilot-instructions.md` |
-| `--skills-cursor` | `.cursor/rules/*.mdc` + `.cursor/index.mdc` |
-| `--skills-claude` | `.claude/skills/generated/*/SKILL.md` + `.claude/rules/*.md` + `CLAUDE.md` |
-| `--skills-agents` | `.agents/skills/*/SKILL.md` + `AGENTS.md` |
-| `--skills-windsurf` | `.windsurfrules` |
+Milens is a code intelligence platform that gives AI coding agents instant understanding of your codebase. 41 MCP tools, 7 sub-agent prompts, 7 CLI workflows, and 50 security rules. It builds a knowledge graph of your entire project — every function, class, import, call, and inheritance chain — then exposes it through MCP tools. Agents query the graph instead of searching files. **70% fewer tokens** per session, **zero broken dependencies**, and a system that **learns from every session**.
 
-> Root config files use `<!-- milens:start/end -->` markers for **idempotent injection** — re-running replaces the milens section without overwriting your custom content.
+- **Analyze once.** Tree-sitter parses 12 languages into a SQLite knowledge graph.
+- **Query instantly.** FTS5 search, recursive CTE traversal — 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.
 
-**Team Collaboration Notes:**
-
-- ✅ **Instruction files are safe to commit** - They use `<workspaceRoot>` placeholder instead of absolute paths
-- ✅ **No merge conflicts** - No machine-specific information (username, absolute paths, etc.)
-- ✅ **Consistent AI assistance** - All team members get the same codebase intelligence
-- ⚠️ **Database is gitignored** - `.milens/*.db` files are local; each developer runs `npx milens analyze` after clone
-
-See [`.milens/README.md`](https://github.com/fuze210699/milens/blob/develop/.milens/README.md) for more details on the index directory.
+Fully offline. Zero telemetry. Localhost-only MCP server. One command to bootstrap.
 
 ---
 
-### `milens search` — Find symbols by name
-
-Full-text search (BM25) across all indexed symbol names and file paths.
+## Architecture
 
-```bash
-milens search "UserService"                 # search for symbols
-milens search "auth" --limit 50             # increase result limit (default: 20)
-milens search "handler" -p /path/to/repo    # search in a specific repo
 ```
+                         npx milens init
+                               │
+                         ┌─────▼──────┐
+                         │  Analyzer   │  ── Parse 12 langs
+                         └─────┬──────┘       (tree-sitter WASM)
+                               │
+                         ┌─────▼──────┐
+                         │   Store     │  ── SQLite + FTS5
+                         └─────┬──────┘       (symbols, links, metadata)
+                               │
+                         ┌─────▼──────┐
+                         │   Server    │  ── MCP stdio/HTTP
+                         └─────┬──────┘       41 tools
+                               │
+                    ┌──────────┴──────────┐
+                    ▼                     ▼
+              AI Agent (MCP)        CLI (terminal)
 
-**Output format:** `name [kind] file:line (exported)`
-
-```
-AuthService [class] src/auth.ts:15 (exported)
-hashPassword [function] src/auth.ts:3 (exported)
+Pipeline stages: Parser (tree-sitter CST) → Analyzer (symbol extraction + dependency resolution) → Store (SQLite insert + index) → Server (MCP tool dispatch)
 ```
 
 ---
 
-### `milens inspect` — 360° symbol view
-
-Show everything about a symbol: who calls it (incoming) and what it depends on (outgoing).
+## Quick Start
 
 ```bash
-milens inspect "AuthService"
-milens inspect "resolveLinks" -p .
+npm install -g milens                     # install globally
+cd your-project
+milens init --profile full --interactive   # bootstrap everything
 ```
 
-**Output:**
+That single command analyzes your codebase, builds a knowledge graph, generates `AGENTS.md`, installs skill files, configures security rules, and sets up pre-commit hooks.
 
-```
-AuthService [class] src/auth.ts:15
-  incoming:
-    calls: handleLogin (src/routes.ts)
-    calls: UserController (src/controllers/user.ts)
-  outgoing:
-    imports: User (src/models.ts)
-    calls: hashPassword (src/auth.ts)
-    calls: createUser (src/models.ts)
-```
-
----
-
-### `milens impact` — Blast radius analysis
-
-Recursively trace what depends on a symbol (upstream) or what a symbol depends on (downstream).
+Then connect your editor:
 
-```bash
-milens impact "createUser"                  # upstream: what breaks if this changes?
-milens impact "UserModel" -d downstream     # downstream: what does this depend on?
-milens impact "searchSymbols" --depth 2     # limit traversal depth (default: 3)
+```json
+// .vscode/mcp.json — VS Code / Copilot
+{
+  "servers": {
+    "milens": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "milens", "serve", "-p", "${workspaceFolder}"]
+    }
+  }
+}
 ```
 
-**Output:**
-
-```
-TARGET: createUser [function] src/models.ts:42
-  [depth 1] AuthService [class] src/auth.ts:15 (calls)
-  [depth 1] UserController [class] src/controllers/user.ts:8 (calls)
-  [depth 2] handleLogin [function] src/routes.ts:23 (calls)
-```
+```bash
+# Claude Code
+claude mcp add milens -- npx -y milens serve -p .
 
-**Depth meaning:**
-- Depth 1 = **WILL BREAK** — direct callers/dependents
-- Depth 2 = **LIKELY AFFECTED** — indirect dependents
-- Depth 3 = **MAY NEED TESTING** — transitive dependents
+# 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"] } } }
 
-### `milens serve` — Start MCP server
+# Codex — .codex/config.toml
+[mcp_servers.milens]
+command = "npx"
+args = ["-y", "milens", "serve", "-p", "."]
 
-Expose the knowledge graph to AI agents via the Model Context Protocol.
+# Gemini — .gemini/settings.json
+{ "mcpServers": { "milens": { "command": "npx", "args": ["-y", "milens", "serve", "-p", "."] } } }
 
-```bash
-milens serve                                # stdio transport (for editors)
-milens serve -p /path/to/repo               # serve a specific repo
-milens serve --http                         # HTTP transport on port 3100
-milens serve --http --port 8080             # HTTP on custom port
+# Zed — .zed/settings.json
+{ "mcp_servers": { "milens": { "command": "npx", "args": ["-y", "milens", "serve", "-p", "."] } } }
 ```
 
-**stdio mode** (default): Used by editors like VS Code, Cursor, and Claude Code. The agent communicates through stdin/stdout.
-
-**HTTP mode**: Used by remote agents or custom integrations. Binds to `127.0.0.1` only — no network exposure.
-
-Endpoint: `POST http://localhost:3100/mcp`
+Open your AI agent. It auto-loads `AGENTS.md` with codebase context. You're ready.
 
 ---
 
-### `milens status` — Show index stats
-
-```bash
-milens status                               # current directory
-milens status -p /path/to/repo              # specific repo
-```
+## Without Milens vs With Milens
 
-**Output:**
+| Situation | Without Milens | With Milens |
+|---|---|---|
+| **Understand a new codebase** | Agent reads 15 files blind (~30,000 tokens) | `codebase_summary()` — 500 tokens |
+| **Edit a function safely** | No idea what depends on it | `impact({target, depth: 3})` — exact blast radius |
+| **Find all references** | Grep 5 times, read 8 files | `context({name})` — incoming + outgoing, one call |
+| **Review a PR** | Read diff, guess risk | `review_pr()` — every symbol scored CRITICAL/HIGH/MEDIUM/LOW |
+| **Security audit** | 10 manual greps | `security_scan()` — 50 rules, one tool call |
+| **Start a new session** | Zero context | `recall()` — agent remembers every past lesson |
+| **Write tests** | Guess what needs testing | `test_plan()` — mock strategy + 3 scenarios |
+| **Find dead code** | Manual search | `find_dead_code()` — every symbol with zero references |
 
-```
-Repository: /home/user/my-project
-Database:   /home/user/my-project/.milens/milens.db
-Indexed:    2026-04-11T10:30:00Z
-Symbols:    210
-Links:      348
-Files:      30
-```
+**Average savings: ~70% fewer tokens per session. ~50% faster task completion.**
 
 ---
 
-### `milens list` — List all indexed repositories
-
-```bash
-milens list
-```
+## Features at a Glance
 
-**Output:**
+| Feature | Description |
+|---|---|
+| 🔍 Code Intelligence | 41 MCP tools — query, impact, context, trace, routes |
+| 🛡️ Security Scanner | 50 rules, 9 categories, OWASP-mapped, 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 |
+| 📊 Metrics | 7 quantified metrics — TER, LR, CQI, BRR, TCGR, DCER, CTR |
+| 🧠 Learning Engine | Annotate → Recall → Evolve — confidence-based knowledge base |
+| 🔌 12 Languages | TS, JS, Python, Java, Go, Rust, PHP, Ruby, Vue, HTML, CSS, Markdown |
+| 🖥️ 7 Editors | Claude Code, Cursor, Copilot, OpenCode, Codex, Gemini CLI, Zed |
 
-```
-3 indexed repositories:
+---
 
-  /home/user/project-a
-    DB:      /home/user/project-a/.milens/milens.db
-    Indexed: 2026-04-11T10:30:00Z
+## CLI Commands
 
-  /home/user/project-b
-    DB:      /home/user/project-b/.milens/milens.db
-    Indexed: 2026-04-10T15:22:00Z
-```
+### Core
 
----
+| Command | Description |
+|---|---|
+| `analyze` | Index codebase into knowledge graph |
+| `serve` | Start MCP server (stdio/HTTP) |
+| `search` | FTS5 search across symbols |
+| `status` | Index health check |
+| `metrics` | 7-metric quality report |
+| `init` | Bootstrap project with profile presets |
+| `watch` | Auto-reindex on file changes |
 
-### `milens clean` — Remove index
+### Workflows
 
-```bash
-milens clean                                # remove index for current directory
-milens clean -p /path/to/repo               # remove index for specific repo
-milens clean --all                          # remove ALL indexes
-```
+| Command | Description |
+|---|---|
+| `milens workflow tdd` | Test coverage gaps + risk-prioritized untested symbols |
+| `milens workflow review` | PR risk analysis — git diff + heat scoring |
+| `milens workflow plan` | Codebase summary — domains, top hubs |
+| `milens workflow onboard` | Onboarding report — structure, entry points, next steps |
+| `milens workflow security-scan` | Full security audit with all 50 rules |
+| `milens workflow refactor` | Dead code detection + candidates |
+| `milens workflow handoff` | Session knowledge summary + promotable annotations |
 
----
+### Security
 
-### `milens dashboard` — Usage analytics
+| Command | Description |
+|---|---|
+| `security scan` | Scan for vulnerabilities (scope, severity filterable) |
+| `security deps` | Audit dependencies against offline CVE database |
 
-Open a browser-based dashboard showing tool usage statistics, token savings, and response times.
+### Maintenance
 
-```bash
-milens dashboard                            # open on port 3200
-milens dashboard --port 8080                # custom port
-```
+| Command | Description |
+|---|---|
+| `evolve` | Promote high-confidence annotations to rules/skills |
+| `hooks` | Session lifecycle hook management |
 
 ---
 
 ## MCP Tools
 
-When the MCP server is running, your AI agent gets these 32 tools:
+### Search & Navigation
 
-### Search & Navigate
-
-| Tool | What It Does | Example |
-|---|---|---|
-| `query` | Symbol search (FTS5 full-text) | `query({query: "UserService"})` |
-| `grep` | Text search ALL files — code, templates, configs, docs | `grep({pattern: "TODO", scope: "all"})` |
-| `context` | 360° symbol view — incoming refs + outgoing deps | `context({name: "AuthService"})` |
-| `get_file_symbols` | All symbols in a file with ref/dep counts | `get_file_symbols({file: "src/auth.ts"})` |
-| `get_type_hierarchy` | Inheritance/implementation tree | `get_type_hierarchy({name: "BaseController"})` |
+| Tool | Description |
+|---|---|
+| `query` | Find symbol definitions by name (FTS5) |
+| `grep` | Text search ALL files (templates, styles, 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 |
+| `find_similar` | Find symbols similar by topology |
 
 ### Impact & Safety
 
-| Tool | What It Does | Example |
-|---|---|---|
-| `impact` | Blast radius: what breaks if this changes? | `impact({target: "createUser"})` |
-| `edit_check` | Pre-edit safety: callers + exports + test coverage + ⚠ warnings | `edit_check({name: "resolveLinks"})` |
-| `detect_changes` | Git diff → affected symbols + direct dependents | `detect_changes({})` |
-| `find_dead_code` | Exported symbols with zero references | `find_dead_code({})` |
-
-### Understanding
-
-| Tool | What It Does | Example |
-|---|---|---|
-| `smart_context` | Intent-aware context: `understand`/`edit`/`debug`/`test` | `smart_context({name: "analyze", intent: "edit"})` |
-| `trace` | Execution flow: call chains to/from entrypoints | `trace({to: "searchSymbols"})` |
-| `routes` | Detect framework routes/endpoints (11 frameworks) | `routes({})` |
-| `explain_relationship` | Shortest path between two symbols | `explain_relationship({from: "A", to: "B"})` |
-| `overview` | Combined context + impact + grep in ONE call | `overview({name: "Database"})` |
+| Tool | Description |
+|---|---|
+| `impact` | Blast radius: what breaks if target changes |
+| `edit_check` | Pre-edit safety: callers + export status + re-export chains |
+| `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 — detects regressions |
 
-### Codebase Overview
+### Review & Testing
 
-| Tool | What It Does | Example |
-|---|---|---|
-| `domains` | Domain clusters — groups of files forming logical modules | `domains({})` |
-| `repos` | List all indexed repositories | `repos({})` |
-| `status` | Index stats, domains, test coverage, accuracy report | `status({})` |
+| Tool | Description |
+|---|---|
+| `review_pr` | PR risk assessment: scored by blast radius + test coverage |
+| `review_symbol` | Single symbol deep-dive: role, heat, dependents, risk |
+| `codebase_summary` | Compact ~500 token overview |
+| `test_plan` | Dependency-aware test plan: mocks, strategies, scenarios |
+| `test_generate` | Auto-generate test file with framework detection |
+| `test_coverage_gaps` | Untested exported symbols sorted by risk |
+| `test_impact` | Which tests to run for current changes |
 
-### Developer Tools
+### Orchestration
 
-| Tool | What It Does | Example |
-|---|---|---|
-| `ast_explore` | Parse code snippet → S-expression AST tree | `ast_explore({code: "const x = 1", language: "typescript"})` |
-| `test_query` | Test tree-sitter query against code snippet | `test_query({query: "(identifier) @name", code: "const x = 1", language: "typescript"})` |
+| Tool | Description |
+|---|---|
+| `orchestrate` | Full cycle: changes → risk → gaps → dead code → action plan |
 
-### Review & Risk Assessment
+### Understanding
 
-| Tool | What It Does | Example |
-|---|---|---|
-| `review_pr` | PR risk assessment: scores changed symbols by blast radius + test coverage | `review_pr({})` |
-| `review_symbol` | Single symbol risk: role, heat, dependents, test status | `review_symbol({name: "AuthService"})` |
-| `codebase_summary` | High-level bootstrapping context: domains, key symbols, coverage | `codebase_summary({})` |
+| Tool | Description |
+|---|---|
+| `smart_context` | Intent-aware context: understand/edit/debug/test |
+| `trace` | Execution flow: call chains from entrypoints to target |
+| `routes` | Detect framework routes/endpoints |
+| `explain_relationship` | Shortest dependency path between two symbols |
+| `domains` | Domain clusters: files forming logical modules |
 
-### Testing
+### Memory & Sessions
 
-| Tool | What It Does | Example |
-|---|---|---|
-| `test_plan` | Dependency-aware test plan: mocks, strategies, suggested tests | `test_plan({name: "createUser"})` |
-| `test_coverage_gaps` | Untested exported symbols sorted by risk | `test_coverage_gaps({})` |
-| `test_impact` | Maps git changes → test files to run | `test_impact({})` |
+| Tool | Description |
+|---|---|
+| `annotate` | Record a note about a symbol (persists across sessions) |
+| `recall` | Retrieve annotations from past sessions |
+| `session_start` | Register agent session |
+| `session_end` | End session and record stats |
+| `session_context` | Get session metadata + annotations |
+| `handoff` | Transfer context between agent sessions |
 
-### Annotations & Sessions
+### Security
 
-| Tool | What It Does | Example |
-|---|---|---|
-| `annotate` | Store observation/note about a symbol (persists across sessions) | `annotate({symbol: "AuthService", key: "note", value: "needs refactor"})` |
-| `recall` | Retrieve annotations by symbol, key, agent, or session | `recall({symbol: "AuthService"})` |
-| `session_start` | Register agent session for multi-agent coordination | `session_start({agent: "copilot"})` |
-| `session_context` | Get session metadata + annotations | `session_context({})` |
-| `handoff` | Transfer context between agent sessions | `handoff({from_session: "abc", to_session: "def"})` |
+| Tool | Description |
+|---|---|
+| `security_scan` | Scan for vulnerabilities (50+ rules, 9 categories) |
+| `fix_apply` | Apply security fix to a file (creates backup) |
 
-### Search & Similarity
+### Hooks
 
-| Tool | What It Does | Example |
-|---|---|---|
-| `semantic_search` | Hybrid FTS5 + vector cosine similarity search | `semantic_search({query: "authentication flow"})` |
-| `find_similar` | Find symbols similar by embedding proximity | `find_similar({name: "AuthService"})` |
+| Tool | Description |
+|---|---|
+| `hook_onFileChange` | Re-analyze changed files + impact summary |
+| `hook_preCompact` | Save metrics snapshot before context compaction |
+| `hook_postCompact` | Restore context by recalling annotations |
 
-> `semantic_search` and `find_similar` require `milens analyze --embeddings` to generate vector embeddings.
+### Developer
 
-### Resources & Prompts
+| Tool | Description |
+|---|---|
+| `ast_explore` | Parse code snippet to S-expression AST tree |
+| `test_query` | Run tree-sitter query against code snippet |
 
-**4 Resources:** `milens://overview`, `milens://symbol/{name}`, `milens://file/{path}`, `milens://domain/{name}`
+### Overview
 
-**3 Guided Prompts:** `delete-feature`, `refactor-symbol`, `explore-symbol` — each triggers a multi-step workflow using the tools above.
+| Tool | Description |
+|---|---|
+| `status` | Index stats: symbols, links, files, coverage |
+| `repos` | List all indexed repositories |
 
 ---
 
-## Tool Examples
-
-### Impact Analysis
-
-```
-impact({target: "createUser"})
-
-TARGET: createUser [function] src/models.ts:42
+## Sub-Agent Prompts
 
-  [depth 1] AuthService [class] src/auth.ts:15 (calls)
-  [depth 1] UserController [class] src/controllers/user.ts:8 (calls)
-  [depth 2] handleLogin [function] src/routes.ts:23 (calls)
-
-3 dependents across 2 depths
-```
-
-### Context (360° Symbol View)
-
-```
-context({name: "AuthService"})
+| Prompt | Purpose |
+|---|---|
+| `milens-planner` | 5-step implementation planning with blast radius |
+| `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 |
 
-AuthService [class] src/auth.ts:15 (exported)
+---
 
-incoming (3):
-  calls: handleLogin [function] src/routes.ts:23
-  calls: UserController [class] src/controllers/user.ts:8
-  imports: authRouter [variable] src/routes.ts:1
+## Security (50+ Rules)
 
-outgoing (3):
-  imports: User [class] src/models.ts:5
-  calls: hashPassword [function] src/auth.ts:3
-  calls: createUser [function] src/models.ts:42
-```
+All 50 rules map to **OWASP Top 10 (2021)**. One tool call covers what used to take 10 manual greps.
 
-### Edit Check (Pre-Edit Safety)
+| Category | Rules | Detects |
+|---|---|---|
+| **secrets** | 10 | AWS keys, GitHub tokens, OpenAI keys, private keys, hardcoded passwords |
+| **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 |
+| **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 |
+| **file-access** | 2 | Path traversal, unsafe file reads |
 
+```bash
+milens security scan --scope secrets --severity HIGH --format json
+milens security deps                    # Offline CVE check (35 CVEs, 5 ecosystems)
 ```
-edit_check({name: "resolveLinks"})
 
-resolveLinks [function] src/analyzer/resolver.ts:45 (exported)
+From an AI agent: `security_scan({scope: "all", severity: "HIGH"})`
 
-callers (2):
-  analyze [function] src/analyzer/engine.ts:89
-  resolveLinksForFile [function] src/analyzer/resolver.ts:120
+---
 
-re-exported via:
-  src/analyzer/index.ts:3
+## Supported Languages
 
-✓ has test coverage
-⚠ 2 direct callers will be affected
-```
+12 languages through tree-sitter:
+
+| Language | Files | Imports | Calls | Heritage |
+|---|---|---|---|---|
+| TypeScript | `.ts` `.tsx` | ESM + CJS + 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.
 
-### Smart Context (Intent-Aware)
+---
 
-```
-smart_context({name: "UserService", intent: "edit"})
-
-UserService [class] src/services/user.ts:10 (exported)
-role: hub | heat: 0.85
-
-callers (5):
-  handleLogin, handleRegister, UserController, AdminController, testUserService
-direct dependencies (3):
-  User [class], hashPassword [function], db [variable]
-indirect dependents (depth 2): 8 symbols
-re-exported via: src/services/index.ts:2
-✓ has test coverage
-```
+## Editor Adapters
 
-### Routes Detection
+Milens works with any MCP-compatible agent:
 
-```
-routes({})
+| Harness | Config File | Recommended Profile |
+|---|---|---|
+| **Claude Code** | `.claude/mcp.json` | standard |
+| **OpenCode** | `.opencode/config.json` | standard |
+| **VS Code / Copilot** | `.vscode/mcp.json` | standard |
+| **Cursor** | `.cursorrules` | standard |
+| **Codex** | `.codex/codex.md` | standard |
+| **Gemini** | `.gemini/context.md` | minimal (10 tools) |
+| **Zed** | `.zed/settings.json` | minimal |
 
-11 routes detected:
+Each adapter is in the `adapters/` directory with ready-to-copy config files and agent instructions.
 
-[express]
-  GET     /api/users  (src/routes/users.ts:12) → getUsers [function]
-  POST    /api/users  (src/routes/users.ts:25) → createUser [function]
+### Profile Selection
 
-[nestjs]
-  GET     /auth/login (src/auth/auth.controller.ts:15) → login [method]
+```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                  # 41 tools — everything
 ```
 
 ---
 
-## Editor Setup
+## Metrics
 
-### Editor Support
+Seven quantified metrics for AI-driven development:
 
-| Editor | MCP | Skills |
+| Metric | Full Name | What It Tracks |
 |---|---|---|
-| **VS Code / Copilot** | ✓ | ✓ |
-| **Cursor** | ✓ | ✓ |
-| **Claude Code** | ✓ | ✓ |
-| **Windsurf** | ✓ | ✓ |
-| **Codex** | ✓ | — |
-
-### VS Code / GitHub Copilot
+| **TER** | Token Efficiency Ratio | Useful tokens ÷ total tokens |
+| **LR** | Learning Rate | Savings gained ÷ savings possible |
+| **CQI** | Code Quality Index | Coverage + security + coupling + docs |
+| **BRR** | Bug Recurrence Rate | Bugs repeated ÷ total fixed |
+| **TCGR** | Test Coverage Growth Rate | Weekly coverage improvement |
+| **DCER** | Dead Code Elimination Rate | Dead symbols ÷ total exported |
+| **CTR** | Cycle Time Reduction | Time saved vs manual approach |
 
 ```bash
-npx milens analyze -p .                     # index your repo (run once)
+milens metrics
 ```
 
-Add to `.vscode/mcp.json`:
-
-```json
-{
-  "servers": {
-    "milens": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "milens", "serve", "-p", "${workspaceFolder}"]
-    }
-  }
-}
-```
-
-<details>
-<summary><strong>Other Editors</strong></summary>
+---
 
-#### Cursor
+## Learning & Evolution
 
-Add to `.cursor/mcp.json`:
+The system gets smarter every session:
 
-```json
-{
-  "mcpServers": {
-    "milens": {
-      "command": "npx",
-      "args": ["-y", "milens", "serve", "-p", "."]
-    }
-  }
-}
 ```
+SESSION 1:  Agent finds bug in createUser()
+            → annotate({symbol: "createUser", key: "bug", value: "Call createUser() before normalizeEmail()"})
+            → confidence: 0.5
 
-#### Claude Code
+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
 
-```bash
-claude mcp add milens -- npx -y milens serve -p .
+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
 ```
 
-#### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "milens": {
-      "command": "npx",
-      "args": ["-y", "milens", "serve", "-p", "."]
-    }
-  }
-}
-```
+---
 
-#### Codex
+## Hook System (6 Triggers)
 
-Add to `.codex/config.toml`:
+| 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 |
 
-```toml
-[mcp_servers.milens]
-command = "npx"
-args = ["-y", "milens", "serve", "-p", "."]
+```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
 ```
 
-</details>
-
----
-
-## Supported Languages
-
-| Language | Extensions | Imports | Calls | Heritage | Frameworks |
-|---|---|---|---|---|---|
-| TypeScript | `.ts` `.tsx` | ✓ ESM + require | ✓ + decorators | ✓ extends/implements | NestJS, React JSX |
-| JavaScript | `.js` `.jsx` `.mjs` `.cjs` | ✓ ESM + require | ✓ | ✓ | React JSX, Express |
-| Python | `.py` | ✓ + relative | ✓ + decorators | ✓ | FastAPI, Flask, Django |
-| Java | `.java` | ✓ + static | ✓ + annotations, new | ✓ | Spring |
-| Go | `.go` | ✓ + go.mod | ✓ | ✓ embedding | net/http, Gin |
-| Rust | `.rs` | ✓ | ✓ + macros | ✓ | — |
-| PHP | `.php` | ✓ + include | ✓ + static, new | ✓ + traits | Laravel |
-| Ruby | `.rb` | ✓ | ✓ | ✓ | Rails, Sinatra |
-| Vue | `.vue` | ✓ | ✓ template refs | ✓ | Vue 3 SFC |
-| HTML | `.html` `.htm` | ✓ `<script src>` `<link>` | ✓ inline `<script>` | — | — |
-| CSS | `.css` | ✓ `@import` | — | — | Custom properties |
-| Markdown | `.md` `.mdx` | ✓ local `[links]()` | — | — | Headings → section symbols, parent-child hierarchy |
-
 ---
 
-## Architecture
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/fuze210699/milens/develop/docs/diagram2.svg" alt="milens architecture: Indexing Pipeline → MCP Server → AI Agent" width="700">
-</p>
+## Pricing
 
-### How it works
+| Tier | Price | Key Features |
+|---|---|---|
+| **Free** | $0 | All 41 tools, 7 prompts, 7 workflows, 50+ security rules, CLI, community support. MIT core. |
 
-1. **Scan** — find all source files matching supported extensions
-2. **Parse** — tree-sitter extracts symbols (functions, classes, methods, etc.) and raw references (imports, calls, extends)
-3. **Resolve** — cross-file link resolution: match import paths to files, match call names to symbol definitions
-4. **Enrich** — compute roles (entrypoint/hub/utility/leaf), heat scores, domain clusters
-5. **Persist** — store everything in SQLite with FTS5 search and recursive CTEs for graph traversal
+[Full pricing details →](docs/pricing.md)
 
-### Multi-Repo
+---
 
-milens uses a global registry (`~/.milens/`) — one MCP server serves all indexed repos. Pass `repo` to target a specific one when multiple are registered.
+## Changelog
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/fuze210699/milens/develop/docs/diagram3.svg" alt="Multi-repo architecture" width="500">
-</p>
+### v0.6.5 (May 2026)
 
-### Design Decisions
+- 14 new test files (168 → 554 tests, 23% → 58% coverage)
+- 7 CLI workflow commands: tdd, review, plan, onboard, security-scan, refactor, handoff
+- Enhanced orchestrator with snapshot persistence
+- Compare impact for regression detection
+- Coverage thresholds in vitest.config.ts
+- CI/CD: milens-ci-test.yml workflow
+- 41 MCP tools in full profile (up from 33)
 
-| Decision | Rationale |
-|---|---|
-| **Declarative LangSpec** | Each language = 1 config object with tree-sitter queries. One universal extractor for all 12 languages |
-| **SQLite + recursive CTE** | Impact analysis runs entirely in the database — no full graph in memory |
-| **Token-compact output** | `name [kind] file:line` format — saves 40-60% tokens for AI |
-| **Incremental by hash** | SHA-256 file hashing — only changed files get re-parsed |
-| **Localhost-only HTTP** | Binds `127.0.0.1` — no network exposure without explicit intent |
+### v0.6.0 (March 2026)
 
-### Tech Stack
+- 41 MCP tools, 7 sub-agent prompts
+- Learning engine: annotate → recall → evolve
+- Offline CVE database with 35+ CVEs across 5 ecosystems
+- 7 editor harness adapters
+- Hook system with 6 event triggers
 
-| Layer | Technology |
-|---|---|
-| **Runtime** | Node.js ≥ 20 |
-| **Language** | TypeScript (ESM) |
-| **Parsing** | tree-sitter (WASM bindings) |
-| **Database** | SQLite (better-sqlite3) + FTS5 |
-| **Graph traversal** | Recursive CTEs |
-| **Agent protocol** | MCP (stdio + StreamableHTTP) |
-| **Testing** | Vitest (136 tests) |
+[Full changelog →](https://github.com/fuze210699/milens/releases)
 
 ---
 
 ## Security & Privacy
 
-milens is **offline by design** — zero network calls, zero telemetry.
+**Zero network. Zero telemetry. Zero data leaving your machine.**
 
-| Layer | Protection |
+| Layer | Guarantee |
 |---|---|
-| **Data locality** | Index lives in `.milens/` per repo (gitignored). No source code stored in registry |
-| **HTTP transport** | Binds to `127.0.0.1` only — requires explicit `--http` flag |
-| **User-supplied regex** | Validated against ReDoS patterns |
-| **FTS5 queries** | Each token quoted as a literal — no query injection |
-| **File access** | All reads bounded to the repo root — no path traversal |
-| **Git integration** | `execFileSync` with argument arrays — no shell interpolation |
+| **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. |
 
 ---
 
 ## Development
 
 ```bash
-npm install              # install dependencies
-npm run build            # tsc → dist/
-npm test                 # vitest (136 tests)
-npm run lint             # tsc --noEmit
-npm run self-analyze     # index this repo
-npm run self-serve       # start MCP server on port 3100
+git clone https://github.com/fuze210699/milens.git
+cd milens
+npm install
+npm run build          # tsc → dist/
+npm test               # vitest (554 tests, 30 test files)
+npm run lint           # tsc --noEmit
+npm run self-analyze   # Index milens with milens
+npm run self-serve     # Start MCP on port 3100
 ```
 
+**Tech Stack:** TypeScript (ESM) · tree-sitter (WASM) · SQLite (better-sqlite3 + FTS5) · MCP SDK · Vitest · Commander
+
 ---
 
 ## License
 
-[PolyForm Noncommercial 1.0.0](https://github.com/fuze210699/milens/blob/develop/LICENSE)
+Core (analyzer, parser, store, CLI, MCP tools): **MIT License**
+Advanced features (GitHub App, enterprise): Commercial license
+See [LICENSE](LICENSE) for details.
+
+---
 
-Architectural inspiration from [GitNexus](https://github.com/abhigyanpatwari/GitNexus) by Abhigyan Patwari.
+<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/pricing.md">Pricing</a> ·
+  <a href="https://github.com/fuze210699/milens/blob/main/CONTRIBUTING.md">Contribute</a>
+</p>