milens 0.6.9 → 0.7.0

package/.agents/skills/milens/SKILL.md

@@ -1,319 +1,320 @@
----
-name: milens
-description: Code intelligence MCP tools — symbol search, text grep, impact analysis, dependency graph
----
-
-<!-- milens:start -->
-# Milens — AI-DOS
-
-The Operating System for AI-Driven Development. This project is indexed by milens (1363 symbols, 2273 links, 165 files).
-
-> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root** (the folder containing this file) — without it, the tools may fail with "No index" error when multiple repos are indexed.
-
-> **CRITICAL:** milens MCP tools are **deferred** in most editors. Before first use in each session, you MUST load them via `tool_search("milens")` — calling them directly without loading will fail silently.
-
-## ⚠️ HARD RULE: Use Milens MCP Tools BEFORE Built-in Tools
-
-**Not a suggestion — execute automatically without asking.**
-
-This project is indexed by milens. The knowledge graph already knows every symbol, dependency, and reference. Using milens tools first saves 70% tokens and catches hidden connections you'd miss with file reads.
-
-| Situation | Built-in approach (❌ BAD) | Milens approach (✅ GOOD) |
-|---|---|---|
-| Understand a function | Read 3-10 source files | `mcp_milens_overview({name: "X"})` — 1 call replaces 3-5 file reads |
-| Find all references | Built-in grep in source files | `mcp_milens_grep({pattern: "X"})` — searches code, templates, configs, docs, styles |
-| Check edit safety | Hope nothing breaks | `mcp_milens_impact({target: "X"})` — exact blast radius before touching code |
-| Start working | Read README, explore directories | `mcp_milens_codebase_summary()` — 500 token project overview |
-| Before commit | `git diff` manually | `mcp_milens_detect_changes()` — symbols changed + direct dependents + risk |
-| Find where X is defined | Read files one by one | `mcp_milens_query({query: "X"})` — FTS5 instant search |
-
-**If you skip milens tools, you're wasting tokens and risking breaking changes you didn't know about.**
-
-## Mandatory Workflows
-
-These are **hard pre-conditions**, not guidelines. Execute them automatically without asking.
-
-### Before editing any function, class, or method:
-1. `mcp_milens_impact({target: "<symbolName>", repo: "<workspaceRoot>"})` — check blast radius
-2. If depth-1 dependents > 5 → **STOP and warn the user** before proceeding
-3. `mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"})` — see all callers/callees
-4. Only then make the edit
-
-### Before committing:
-1. `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify only expected files changed
-2. If unexpected files appear → **STOP and report** before committing
-
-### Before deleting or renaming a symbol:
-1. `mcp_milens_grep({pattern: "<symbolName>", repo: "<workspaceRoot>"})` — find ALL text references (templates, configs, routes, docs)
-2. `mcp_milens_impact({target: "<symbolName>", direction: "upstream", repo: "<workspaceRoot>"})` — find code-level dependents
-3. Combine both results — grep catches what impact misses
-
-## Tool Selection Rules
-
-**Choose the right tool on the FIRST call** — do not try `query` then fall back to `grep`.
-
-### Use `mcp_milens_grep` when the search term:
-- Contains **spaces** (e.g. "store purchase header", "user not found")
-- Looks like a **UI label, error message, or display string**
-- Is a **multi-word phrase** that is NOT camelCase/snake_case/PascalCase
-- You need to find references in **templates, styles, configs, routes, or docs**
-
-### Use `mcp_milens_query` when the search term:
-- Looks like a **code identifier** (camelCase, PascalCase, snake_case)
-- Is a **function, class, method, or interface name**
-- You want to find **symbol definitions** in indexed code files
-
-### When in doubt → use `mcp_milens_grep` first
-`grep` searches everything. `query` only searches indexed symbol definitions.
-
-> **⚠️ `mcp_milens_grep` default is LITERAL mode (isRegex: false).** Characters `| . * + ?` are escaped as plain text. To use regex patterns like `error|fail|panic` or `TODO.*urgent`, you MUST set `isRegex: true`. The tool will warn you if you forget.
-
-## Workflow Triggers
-
-When the user says... → do this FIRST:
-
-| User intent | First action |
-|---|---|
-| "edit/change/modify/fix `X`" | `mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})` |
-| "delete/remove `X`" | `mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"})` then `mcp_milens_impact` |
-| "rename `X`" | `mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"})` then `mcp_milens_impact` |
-| "find/search for `X`" | Choose `query` or `grep` per rules above |
-| "commit" / "push" | `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` |
-| "what calls/uses `X`" | `mcp_milens_context({name: "X", repo: "<workspaceRoot>"})` |
-| "what happens if I change `X`" | `mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})` |
-| "how are `A` and `B` connected" | `mcp_milens_explain_relationship({from: "A", to: "B", repo: "<workspaceRoot>"})` |
-| "explore/understand `X`" | `mcp_milens_context({name: "X", repo: "<workspaceRoot>"})` |
-| "update/write docs for `X`" | `mcp_milens_grep({pattern: "X", include: "**/*.md"})` — find existing docs mentioning X, then `mcp_milens_context({name: "X"})` for full symbol info |
-| "research/explore docs" | `mcp_milens_get_file_symbols({file: "<doc.md>"})` — see document outline (headings as sections) |
-| "what docs mention `X`" | `mcp_milens_grep({pattern: "X", include: "**/*.md"})` — find all markdown references |
-| "review this PR" | `mcp_milens_review_pr({repo: "<workspaceRoot>"})` — risk assessment for changed files |
-| "is `X` risky to change" | `mcp_milens_review_symbol({name: "X", repo: "<workspaceRoot>"})` |
-| "write tests for `X`" | `mcp_milens_test_plan({name: "X", repo: "<workspaceRoot>"})` — deps, mocks, suggested tests |
-| "what needs tests" | `mcp_milens_test_coverage_gaps({repo: "<workspaceRoot>"})` — untested symbols by risk |
-| "which tests to run" | `mcp_milens_test_impact({repo: "<workspaceRoot>"})` — maps changes → test files |
-| "remember/note that `X`..." | `mcp_milens_annotate({symbol: "X", key: "note", value: "...", repo: "<workspaceRoot>"})` |
-| "what do we know about `X`" | `mcp_milens_recall({symbol: "X", repo: "<workspaceRoot>"})` |
-| "start new session" | `mcp_milens_session_start({agent: "...", repo: "<workspaceRoot>"})` |
-| "find code like `X`" | `mcp_milens_find_similar({name: "X", repo: "<workspaceRoot>"})` |
-| "search for `concept`" | `mcp_milens_semantic_search({query: "concept", repo: "<workspaceRoot>"})` |
-| "generate tests for `X`" | `mcp_milens_test_generate({symbol: "X", repo: "<workspaceRoot>"})` |
-| "fix security issue in `X`" | `mcp_milens_fix_apply({ruleId, file, line, repo: "<workspaceRoot>"})` |
-| "remove dead code" | `mcp_milens_find_dead_code()` then `dead_code_remove` prompt |
-| "orchestrate/check changes" | `mcp_milens_orchestrate({repo: "<workspaceRoot>"})` |
-| "compare impact of `X`" | `mcp_milens_compare_impact({name: "X", action: "snapshot"|"compare", repo: "<workspaceRoot>"})` |
-| "check pre-commit" | `mcp_milens_pre_commit_check({repo: "<workspaceRoot>"})` |
-| "save/restore context" | `mcp_milens_hook_preCompact()` / `mcp_milens_hook_postCompact()` |
-| "scan security / audit security" | `mcp_milens_security_scan({repo: "<workspaceRoot>"})` — full audit across all 50+ rules |
-| "end session" / "finish work" | `mcp_milens_session_end({session_id: "..."})` — record stats, trigger onSessionEnd hook |
-| "what did session X do" | `mcp_milens_session_context({session_id: "..."})` — get annotations + tool calls |
-| "file changed to X" | `mcp_milens_hook_onFileChange({files: ["path/to/file"], repo: "<workspaceRoot>"})` |
-
-### Domain-aware skill triggers:
-| User intent | Skill to load |
-|---|---|
-| "I'm working on authentication/security" | Load `milens-security` skill + `mcp_milens_security_scan()` |
-| "I need to understand the parser" | Load `milens-parser` skill + `mcp_milens_get_file_symbols({file: "src/parser/"})` |
-| "I'm debugging a server issue" | Load `milens-server` skill + `mcp_milens_trace()` |
-| "I'm working with the database" | Load `milens-store` skill + `mcp_milens_get_file_symbols({file: "src/store/"})` |
-| "I need to write tests for this" | Load `milens-tdd` skill + `mcp_milens_test_plan()` |
-| "I'm planning a feature" | Load `milens-plan` skill + `mcp_milens_codebase_summary()` |
-| "I need to refactor this" | Load `milens-refactor-clean` skill + `mcp_milens_impact()` |
-| "Review my code changes" | Load `milens-code-review` skill + `mcp_milens_review_pr()` |
-
-## Annotation Guide — Building a Smarter Codebase
-
-Every time you discover something important about a symbol, annotate it. The system learns across sessions — your note today saves tokens tomorrow.
-
-### When to annotate:
-- Found a bug pattern? → `mcp_milens_annotate({symbol: "X", key: "bug", value: "..."})`
-- Discovered an architecture rule? → `mcp_milens_annotate({symbol: "X", key: "architecture", value: "..."})`
-- Learned how to test something? → `mcp_milens_annotate({symbol: "X", key: "test", value: "..."})`
-- Found a security issue? → `mcp_milens_annotate({symbol: "X", key: "security", value: "..."})`
-- Noted a hidden dependency? → `mcp_milens_annotate({symbol: "X", key: "dependency", value: "..."})`
-
-### Annotation keys reference:
-| Key | Use when | Example value |
-|-----|----------|---------------|
-| `bug` | Known bug, not yet fixed | "NullPointerException when users is empty array" |
-| `security` | Security vulnerability | "No CSRF token validation on this endpoint" |
-| `architecture` | Design pattern, constraint | "Service is a singleton — don't instantiate directly" |
-| `test` | Testing knowledge | "Must mock Database.getConnection() before testing" |
-| `dependency` | Hidden coupling | "Imports from deprecated module old-auth.js" |
-| `refactor` | Future refactoring notes | "Split into validateEmail() + normalizeEmail()" |
-| `workflow` | Process knowledge | "Must restart dev server after modifying this file" |
-| `note` | General observation | "This function is called from cron job at 3AM" |
-
-### Learning lifecycle:
-1. **Session 1:** `annotate()` → confidence 0.5
-2. **Session 2:** `recall()` sees it again → confidence 0.7
-3. **Session 5:** confidence hits 0.8 → `milens evolve` promotes it to SKILL.md
-
-### Annotate triggers:
-| User says... | Tool call |
-|---|---|
-| "found a bug in X" | `mcp_milens_annotate({symbol: "X", key: "bug", value: "describe the bug"})` |
-| "X has a security issue" | `mcp_milens_annotate({symbol: "X", key: "security", value: "describe the issue"})` |
-| "learned how X works" | `mcp_milens_annotate({symbol: "X", key: "note", value: "key insight"})` |
-| "X depends on Y internally" | `mcp_milens_annotate({symbol: "X", key: "dependency", value: "depends on Y for Z"})` |
-| "X needs refactoring later" | `mcp_milens_annotate({symbol: "X", key: "refactor", value: "plan"})` |
-
-### At session end, ALWAYS:
-1. `mcp_milens_recall({})` — review annotations you found useful
-2. `mcp_milens_annotate({symbol: "X", key: "...", value: "..."})` — save new discoveries from this session
-
-## Problem → Solution — When You're Stuck
-
-| You're trying to... | Do this FIRST |
-|---|---|
-| Understand the codebase | `mcp_milens_codebase_summary()` then `mcp_milens_domains()` |
-| Understand a specific function | `mcp_milens_context({name: "functionName"})` |
-| Find where something is defined | `mcp_milens_query({query: "ClassName"})` |
-| Find ALL references to something | `mcp_milens_grep({pattern: "ClassName"})` |
-| Check if editing is safe | `mcp_milens_impact({target: "functionName"})` |
-| Edit with confidence | `mcp_milens_overview({name: "functionName"})` — context+impact+grep in 1 call |
-| Know which tests to run | `mcp_milens_test_impact()` — maps changes to test files |
-| Find what needs testing most | `mcp_milens_test_coverage_gaps()` — sorted by risk |
-| Get a test strategy | `mcp_milens_test_plan({name: "functionName"})` — mocks + scenarios |
-| Review your changes | `mcp_milens_review_pr()` — risk scores for changed symbols |
-| Check for security issues | `mcp_milens_security_scan()` — 50+ rules in one call |
-| Remove dead code safely | `mcp_milens_find_dead_code()` then use `dead_code_remove` prompt |
-| Trace how code executes | `mcp_milens_trace({name: "functionName", direction: "to"})` |
-| Find API endpoints | `mcp_milens_routes()` — auto-detect across 7 frameworks |
-| See class hierarchy | `mcp_milens_get_type_hierarchy({name: "ClassName"})` |
-| Compare impact before/after | `mcp_milens_compare_impact({name: "X", action: "snapshot"})` before, then `compare` after |
-| Get a full picture fast | `mcp_milens_orchestrate()` — runs detect+review+impact+gaps+dead code |
-| Remember something important | `mcp_milens_annotate({symbol: "X", key: "...", value: "..."})` |
-| Recall past knowledge | `mcp_milens_recall({symbol: "X"})` |
-| Start a new session properly | `mcp_milens_session_start({agent: "..."})` → `mcp_milens_recall()` → `mcp_milens_codebase_summary()` |
-| End a session properly | `mcp_milens_detect_changes()` → `mcp_milens_review_pr()` → annotate → `mcp_milens_session_end()` |
-| Transfer work to another agent | `mcp_milens_handoff({from_session: "...", to_agent: "...", context: "..."})` |
-| Debug a crash / exception | `mcp_milens_trace({name: "crashingFunction"})` + `mcp_milens_context()` + `mcp_milens_impact()` |
-
-## Session Lifecycle
-
-### Start EVERY session:
-1. `mcp_milens_session_start({agent: "your-agent-name"})` — register session
-2. `mcp_milens_recall({})` — what did we learn last time?
-3. `mcp_milens_codebase_summary()` — refresh project context in 500 tokens
-
-### End EVERY session:
-1. `mcp_milens_detect_changes()` — verify changes
-2. `mcp_milens_review_pr()` — risk assessment
-3. `mcp_milens_annotate({...})` — save key discoveries from this session
-4. `mcp_milens_session_end({session_id: "..."})` — record stats
-
-Milens indexes **Markdown files** (.md, .mdx) — headings become `section` symbols with parent-child hierarchy, and local links become cross-file references.
-
-### Researching or exploring documentation:
-1. `mcp_milens_get_file_symbols({file: "README.md", repo: "<workspaceRoot>"})` — see the full heading outline (TOC) of any doc
-2. `mcp_milens_query({query: "<topic>"})` — search section headings across all docs and code
-3. `mcp_milens_grep({pattern: "<keyword>", include: "**/*.md"})` — text search within docs only
-
-### Before updating documentation:
-1. `mcp_milens_get_file_symbols({file: "<doc.md>"})` — understand document structure first
-2. If documenting a code symbol: `mcp_milens_context({name: "<symbolName>"})` — get full symbol info (signature, callers, deps)
-3. `mcp_milens_grep({pattern: "<symbolName>", include: "**/*.md"})` — check if other docs already reference it
-
-### After renaming/deleting a code symbol:
-- `mcp_milens_grep({pattern: "<oldName>", include: "**/*.md"})` — find docs that need updating (milens indexes markdown links as cross-file references)
-
-## Never Do
-
-- NEVER edit a symbol without first running `mcp_milens_impact` on it.
-- NEVER delete or rename without running both `mcp_milens_grep` and `mcp_milens_impact`.
-- NEVER commit without running `mcp_milens_detect_changes()`.
-- NEVER call milens MCP tools without the `repo` parameter.
-- NEVER use `mcp_milens_query` for multi-word display text or UI labels — use `mcp_milens_grep`.
-
----
-
-## Reference
-
-### ⭐ Core Tools — Use Every Session (8)
-
-| Tool | Purpose |
-|---|---|
-| `mcp_milens_overview` | **Use this first.** Combined context + impact + grep. 1 call replaces 3-5 file reads. |
-| `mcp_milens_impact` | Blast radius BEFORE editing. Shows what WILL BREAK. |
-| `mcp_milens_edit_check` | Pre-edit safety: callers + exports + re-export chains + test coverage |
-| `mcp_milens_context` | 360° view: all callers + all callees. Instant dependency graph. |
-| `mcp_milens_query` | Find symbol definitions by name (FTS5 instant search) |
-| `mcp_milens_grep` | Search ALL files for any text (templates, configs, docs, styles) |
-| `mcp_milens_detect_changes` | Pre-commit: which symbols changed + dependents + risk scores |
-| `mcp_milens_codebase_summary` | Project overview in ~500 tokens. Use instead of reading README. |
-
-### 🔧 Situational Tools — Use When Needed (15)
-
-| Tool | Purpose | Use when... |
-|---|---|---|
-| `mcp_milens_review_pr` | PR risk assessment | Before opening PR |
-| `mcp_milens_review_symbol` | Single symbol deep-dive | Symbol is flagged CRITICAL/HIGH |
-| `mcp_milens_test_plan` | Mock strategy + >=3 test scenarios | Writing new tests |
-| `mcp_milens_test_coverage_gaps` | Untested symbols sorted by risk | Finding test priorities |
-| `mcp_milens_test_impact` | Maps changes → test files | After making edits |
-| `mcp_milens_test_generate` | Auto-generate test file | Starting tests from scratch |
-| `mcp_milens_security_scan` | 50+ security rules | Security audit requested |
-| `mcp_milens_trace` | Call chains from entrypoints | Debugging execution flow |
-| `mcp_milens_routes` | Framework routes/endpoints | Finding API endpoints |
-| `mcp_milens_smart_context` | Intent-aware context | Understand/edit/debug/test modes |
-| `mcp_milens_domains` | Domain clusters | Understanding module structure |
-| `mcp_milens_explain_relationship` | Shortest dependency path | How A connects to B |
-| `mcp_milens_get_type_hierarchy` | Inheritance tree | Class/interface exploration |
-| `mcp_milens_find_dead_code` | Unused exported symbols | Before major refactors |
-| `mcp_milens_find_similar` | Symbols with shared callers/callees | Finding refactor patterns |
-
-### 📚 Advanced Tools — Reference (19)
-
-| Tool | Purpose |
-|---|---|
-| `mcp_milens_status` | Index health: symbols, links, files, coverage, staleness |
-| `mcp_milens_repos` | List all indexed repositories |
-| `mcp_milens_annotate` | Record observations about symbols (persists across sessions) |
-| `mcp_milens_recall` | Retrieve annotations from past sessions |
-| `mcp_milens_session_start` | Register agent session |
-| `mcp_milens_session_end` | End session and record stats |
-| `mcp_milens_session_context` | Get session metadata + annotations |
-| `mcp_milens_handoff` | Transfer context between agent sessions |
-| `mcp_milens_orchestrate` | Full cycle: detect → review → impact → gaps → dead code |
-| `mcp_milens_pre_commit_check` | Pre-commit risk scan |
-| `mcp_milens_compare_impact` | Compare impact graph before/after edit |
-| `mcp_milens_semantic_search` | Hybrid FTS5 + vector search |
-| `mcp_milens_fix_apply` | Apply security fix to a file |
-| `mcp_milens_hook_preCompact` | Save metrics before context compaction |
-| `mcp_milens_hook_postCompact` | Restore context after compaction |
-| `mcp_milens_hook_onFileChange` | Trigger on file change hook |
-| `mcp_milens_ast_explore` | Parse code to AST S-expression |
-| `mcp_milens_test_query` | Test tree-sitter query patterns |
-| `mcp_milens_get_file_symbols` | All symbols in a file with ref/dep counts |
-
-### Keeping the Index Fresh
-
-After significant code changes: `npx milens analyze -p . --force` (replace `.` with your project root if running from a different directory)
-
-### Skills
-
-| Task | Read this skill file |
-|------|---------------------|
-| General milens tools reference | `.agents/skills/milens/SKILL.md` |
-| Work in the Adapters area | `.agents/skills/adapters/SKILL.md` |
-| Work in the Root area | `.agents/skills/root/SKILL.md` |
-| Work in the Apps area | `.agents/skills/apps/SKILL.md` |
-| Work in the Docs area | `.agents/skills/docs/SKILL.md` |
-| Work in the Test area | `.agents/skills/test/SKILL.md` |
-| Work in the Scripts area | `.agents/skills/scripts/SKILL.md` |
-| Work in the Analyzer area | `.agents/skills/analyzer/SKILL.md` |
-| Work in the Orchestrator area | `.agents/skills/orchestrator/SKILL.md` |
-| Work in the Parser area | `.agents/skills/parser/SKILL.md` |
-| Work in the Security area | `.agents/skills/security/SKILL.md` |
-| Work in the Server area | `.agents/skills/server/SKILL.md` |
-| Work in the Store area | `.agents/skills/store/SKILL.md` |
-| Execute milens-plan workflow | `.agents/skills/milens-plan/SKILL.md` |
-| Execute milens-code-review workflow | `.agents/skills/milens-code-review/SKILL.md` |
-| Execute milens-tdd workflow | `.agents/skills/milens-tdd/SKILL.md` |
-| Execute milens-security-review workflow | `.agents/skills/milens-security-review/SKILL.md` |
-| Execute milens-refactor-clean workflow | `.agents/skills/milens-refactor-clean/SKILL.md` |
-| Execute milens-eval workflow | `.agents/skills/milens-eval/SKILL.md` |
-| Execute milens-architect workflow | `.agents/skills/milens-architect/SKILL.md` |
-| Execute milens-debugger workflow | `.agents/skills/milens-debugger/SKILL.md` |
-
+---
+name: milens
+description: Code intelligence MCP tools — symbol search, text grep, impact analysis, dependency graph
+---
+
+<!-- milens:start -->
+# Milens — AI-DOS
+
+The Operating System for AI-Driven Development. This project is indexed by milens (1366 symbols, 2347 links, 166 files).
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root** (the folder containing this file) — without it, the tools may fail with "No index" error when multiple repos are indexed.
+
+> **CRITICAL:** milens MCP tools are **deferred** in most editors. Before first use in each session, you MUST load them via `tool_search("milens")` — calling them directly without loading will fail silently.
+
+## ⚠️ HARD RULE: Use Milens MCP Tools BEFORE Built-in Tools
+
+**Not a suggestion — execute automatically without asking.**
+
+This project is indexed by milens. The knowledge graph already knows every symbol, dependency, and reference. Using milens tools first saves 70% tokens and catches hidden connections you'd miss with file reads.
+
+| Situation | Built-in approach (❌ BAD) | Milens approach (✅ GOOD) |
+|---|---|---|
+| Understand a function | Read 3-10 source files | `mcp_milens_overview({name: "X"})` — 1 call replaces 3-5 file reads |
+| Find all references | Built-in grep in source files | `mcp_milens_grep({pattern: "X"})` — searches code, templates, configs, docs, styles |
+| Check edit safety | Hope nothing breaks | `mcp_milens_impact({target: "X"})` — exact blast radius before touching code |
+| Start working | Read README, explore directories | `mcp_milens_codebase_summary()` — 500 token project overview |
+| Before commit | `git diff` manually | `mcp_milens_detect_changes()` — symbols changed + direct dependents + risk |
+| Find where X is defined | Read files one by one | `mcp_milens_query({query: "X"})` — FTS5 instant search |
+
+**If you skip milens tools, you're wasting tokens and risking breaking changes you didn't know about.**
+
+## Mandatory Workflows
+
+These are **hard pre-conditions**, not guidelines. Execute them automatically without asking.
+
+### Before editing any function, class, or method:
+1. `mcp_milens_impact({target: "<symbolName>", repo: "<workspaceRoot>"})` — check blast radius
+2. If depth-1 dependents > 5 → **STOP and warn the user** before proceeding
+3. `mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"})` — see all callers/callees
+4. Only then make the edit
+
+### Before committing:
+1. `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify only expected files changed
+2. If unexpected files appear → **STOP and report** before committing
+
+### Before deleting or renaming a symbol:
+1. `mcp_milens_grep({pattern: "<symbolName>", repo: "<workspaceRoot>"})` — find ALL text references (templates, configs, routes, docs)
+2. `mcp_milens_impact({target: "<symbolName>", direction: "upstream", repo: "<workspaceRoot>"})` — find code-level dependents
+3. Combine both results — grep catches what impact misses
+
+## Tool Selection Rules
+
+**Choose the right tool on the FIRST call** — do not try `query` then fall back to `grep`.
+
+### Use `mcp_milens_grep` when the search term:
+- Contains **spaces** (e.g. "store purchase header", "user not found")
+- Looks like a **UI label, error message, or display string**
+- Is a **multi-word phrase** that is NOT camelCase/snake_case/PascalCase
+- You need to find references in **templates, styles, configs, routes, or docs**
+
+### Use `mcp_milens_query` when the search term:
+- Looks like a **code identifier** (camelCase, PascalCase, snake_case)
+- Is a **function, class, method, or interface name**
+- You want to find **symbol definitions** in indexed code files
+
+### When in doubt → use `mcp_milens_grep` first
+`grep` searches everything. `query` only searches indexed symbol definitions.
+
+> **⚠️ `mcp_milens_grep` default is LITERAL mode (isRegex: false).** Characters `| . * + ?` are escaped as plain text. To use regex patterns like `error|fail|panic` or `TODO.*urgent`, you MUST set `isRegex: true`. The tool will warn you if you forget.
+
+## Workflow Triggers
+
+When the user says... → do this FIRST:
+
+| User intent | First action |
+|---|---|
+| "edit/change/modify/fix `X`" | `mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})` |
+| "delete/remove `X`" | `mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"})` then `mcp_milens_impact` |
+| "rename `X`" | `mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"})` then `mcp_milens_impact` |
+| "find/search for `X`" | Choose `query` or `grep` per rules above |
+| "commit" / "push" | `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` |
+| "what calls/uses `X`" | `mcp_milens_context({name: "X", repo: "<workspaceRoot>"})` |
+| "what happens if I change `X`" | `mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})` |
+| "how are `A` and `B` connected" | `mcp_milens_explain_relationship({from: "A", to: "B", repo: "<workspaceRoot>"})` |
+| "explore/understand `X`" | `mcp_milens_context({name: "X", repo: "<workspaceRoot>"})` |
+| "update/write docs for `X`" | `mcp_milens_grep({pattern: "X", include: "**/*.md"})` — find existing docs mentioning X, then `mcp_milens_context({name: "X"})` for full symbol info |
+| "research/explore docs" | `mcp_milens_get_file_symbols({file: "<doc.md>"})` — see document outline (headings as sections) |
+| "what docs mention `X`" | `mcp_milens_grep({pattern: "X", include: "**/*.md"})` — find all markdown references |
+| "review this PR" | `mcp_milens_review_pr({repo: "<workspaceRoot>"})` — risk assessment for changed files |
+| "is `X` risky to change" | `mcp_milens_review_symbol({name: "X", repo: "<workspaceRoot>"})` |
+| "write tests for `X`" | `mcp_milens_test_plan({name: "X", repo: "<workspaceRoot>"})` — deps, mocks, suggested tests |
+| "what needs tests" | `mcp_milens_test_coverage_gaps({repo: "<workspaceRoot>"})` — untested symbols by risk |
+| "which tests to run" | `mcp_milens_test_impact({repo: "<workspaceRoot>"})` — maps changes → test files |
+| "remember/note that `X`..." | `mcp_milens_annotate({symbol: "X", key: "note", value: "...", repo: "<workspaceRoot>"})` |
+| "what do we know about `X`" | `mcp_milens_recall({symbol: "X", repo: "<workspaceRoot>"})` |
+| "start new session" | `mcp_milens_session_start({agent: "...", repo: "<workspaceRoot>"})` |
+| "find code like `X`" | `mcp_milens_find_similar({name: "X", repo: "<workspaceRoot>"})` |
+| "search for `concept`" | `mcp_milens_semantic_search({query: "concept", repo: "<workspaceRoot>"})` |
+| "generate tests for `X`" | `mcp_milens_test_generate({symbol: "X", repo: "<workspaceRoot>"})` |
+| "fix security issue in `X`" | `mcp_milens_fix_apply({ruleId, file, line, repo: "<workspaceRoot>"})` |
+| "remove dead code" | `mcp_milens_find_dead_code()` then `dead_code_remove` prompt |
+| "orchestrate/check changes" | `mcp_milens_orchestrate({repo: "<workspaceRoot>"})` |
+| "compare impact of `X`" | `mcp_milens_compare_impact({name: "X", action: "snapshot"|"compare", repo: "<workspaceRoot>"})` |
+| "check pre-commit" | `mcp_milens_pre_commit_check({repo: "<workspaceRoot>"})` |
+| "save/restore context" | `mcp_milens_hook_preCompact()` / `mcp_milens_hook_postCompact()` |
+| "scan security / audit security" | `mcp_milens_security_scan({repo: "<workspaceRoot>"})` — full audit across all 50+ rules |
+| "end session" / "finish work" | `mcp_milens_session_end({session_id: "..."})` — record stats, trigger onSessionEnd hook |
+| "what did session X do" | `mcp_milens_session_context({session_id: "..."})` — get annotations + tool calls |
+| "file changed to X" | `mcp_milens_hook_onFileChange({files: ["path/to/file"], repo: "<workspaceRoot>"})` |
+
+### Domain-aware skill triggers:
+| User intent | Skill to load |
+|---|---|
+| "I'm working on authentication/security" | Load `milens-security` skill + `mcp_milens_security_scan()` |
+| "I need to understand the parser" | Load `milens-parser` skill + `mcp_milens_get_file_symbols({file: "src/parser/"})` |
+| "I'm debugging a server issue" | Load `milens-server` skill + `mcp_milens_trace()` |
+| "I'm working with the database" | Load `milens-store` skill + `mcp_milens_get_file_symbols({file: "src/store/"})` |
+| "I need to write tests for this" | Load `milens-tdd` skill + `mcp_milens_test_plan()` |
+| "I'm planning a feature" | Load `milens-plan` skill + `mcp_milens_codebase_summary()` |
+| "I need to refactor this" | Load `milens-refactor-clean` skill + `mcp_milens_impact()` |
+| "Review my code changes" | Load `milens-code-review` skill + `mcp_milens_review_pr()` |
+
+## Annotation Guide — Building a Smarter Codebase
+
+Every time you discover something important about a symbol, annotate it. The system learns across sessions — your note today saves tokens tomorrow.
+
+### When to annotate:
+- Found a bug pattern? → `mcp_milens_annotate({symbol: "X", key: "bug", value: "..."})`
+- Discovered an architecture rule? → `mcp_milens_annotate({symbol: "X", key: "architecture", value: "..."})`
+- Learned how to test something? → `mcp_milens_annotate({symbol: "X", key: "test", value: "..."})`
+- Found a security issue? → `mcp_milens_annotate({symbol: "X", key: "security", value: "..."})`
+- Noted a hidden dependency? → `mcp_milens_annotate({symbol: "X", key: "dependency", value: "..."})`
+
+### Annotation keys reference:
+| Key | Use when | Example value |
+|-----|----------|---------------|
+| `bug` | Known bug, not yet fixed | "NullPointerException when users is empty array" |
+| `security` | Security vulnerability | "No CSRF token validation on this endpoint" |
+| `architecture` | Design pattern, constraint | "Service is a singleton — don't instantiate directly" |
+| `test` | Testing knowledge | "Must mock Database.getConnection() before testing" |
+| `dependency` | Hidden coupling | "Imports from deprecated module old-auth.js" |
+| `refactor` | Future refactoring notes | "Split into validateEmail() + normalizeEmail()" |
+| `workflow` | Process knowledge | "Must restart dev server after modifying this file" |
+| `note` | General observation | "This function is called from cron job at 3AM" |
+
+### Learning lifecycle:
+1. **Session 1:** `annotate()` → confidence 0.5
+2. **Session 2:** `recall()` sees it again → confidence 0.7
+3. **Session 5:** confidence hits 0.8 → `milens evolve` promotes it to SKILL.md
+
+### Annotate triggers:
+| User says... | Tool call |
+|---|---|
+| "found a bug in X" | `mcp_milens_annotate({symbol: "X", key: "bug", value: "describe the bug"})` |
+| "X has a security issue" | `mcp_milens_annotate({symbol: "X", key: "security", value: "describe the issue"})` |
+| "learned how X works" | `mcp_milens_annotate({symbol: "X", key: "note", value: "key insight"})` |
+| "X depends on Y internally" | `mcp_milens_annotate({symbol: "X", key: "dependency", value: "depends on Y for Z"})` |
+| "X needs refactoring later" | `mcp_milens_annotate({symbol: "X", key: "refactor", value: "plan"})` |
+
+### At session end, ALWAYS:
+1. `mcp_milens_recall({})` — review annotations you found useful
+2. `mcp_milens_annotate({symbol: "X", key: "...", value: "..."})` — save new discoveries from this session
+
+## Problem → Solution — When You're Stuck
+
+| You're trying to... | Do this FIRST |
+|---|---|
+| Understand the codebase | `mcp_milens_codebase_summary()` then `mcp_milens_domains()` |
+| Understand a specific function | `mcp_milens_context({name: "functionName"})` |
+| Find where something is defined | `mcp_milens_query({query: "ClassName"})` |
+| Find ALL references to something | `mcp_milens_grep({pattern: "ClassName"})` |
+| Check if editing is safe | `mcp_milens_impact({target: "functionName"})` |
+| Edit with confidence | `mcp_milens_overview({name: "functionName"})` — context+impact+grep in 1 call |
+| Know which tests to run | `mcp_milens_test_impact()` — maps changes to test files |
+| Find what needs testing most | `mcp_milens_test_coverage_gaps()` — sorted by risk |
+| Get a test strategy | `mcp_milens_test_plan({name: "functionName"})` — mocks + scenarios |
+| Review your changes | `mcp_milens_review_pr()` — risk scores for changed symbols |
+| Check for security issues | `mcp_milens_security_scan()` — 50+ rules in one call |
+| Remove dead code safely | `mcp_milens_find_dead_code()` then use `dead_code_remove` prompt |
+| Trace how code executes | `mcp_milens_trace({name: "functionName", direction: "to"})` |
+| Find API endpoints | `mcp_milens_routes()` — auto-detect across 7 frameworks |
+| See class hierarchy | `mcp_milens_get_type_hierarchy({name: "ClassName"})` |
+| Compare impact before/after | `mcp_milens_compare_impact({name: "X", action: "snapshot"})` before, then `compare` after |
+| Get a full picture fast | `mcp_milens_orchestrate()` — runs detect+review+impact+gaps+dead code |
+| Remember something important | `mcp_milens_annotate({symbol: "X", key: "...", value: "..."})` |
+| Recall past knowledge | `mcp_milens_recall({symbol: "X"})` |
+| Start a new session properly | `mcp_milens_session_start({agent: "..."})` → `mcp_milens_recall()` → `mcp_milens_codebase_summary()` |
+| End a session properly | `mcp_milens_detect_changes()` → `mcp_milens_review_pr()` → annotate → `mcp_milens_session_end()` |
+| Transfer work to another agent | `mcp_milens_handoff({from_session: "...", to_agent: "...", context: "..."})` |
+| Debug a crash / exception | `mcp_milens_trace({name: "crashingFunction"})` + `mcp_milens_context()` + `mcp_milens_impact()` |
+
+## Session Lifecycle
+
+### Start EVERY session:
+1. `mcp_milens_session_start({agent: "your-agent-name"})` — register session
+2. `mcp_milens_recall({})` — what did we learn last time?
+3. `mcp_milens_codebase_summary()` — refresh project context in 500 tokens
+
+### End EVERY session:
+1. `mcp_milens_detect_changes()` — verify changes
+2. `mcp_milens_review_pr()` — risk assessment
+3. `mcp_milens_annotate({...})` — save key discoveries from this session
+4. `mcp_milens_session_end({session_id: "..."})` — record stats
+
+Milens indexes **Markdown files** (.md, .mdx) — headings become `section` symbols with parent-child hierarchy, and local links become cross-file references.
+
+### Researching or exploring documentation:
+1. `mcp_milens_get_file_symbols({file: "README.md", repo: "<workspaceRoot>"})` — see the full heading outline (TOC) of any doc
+2. `mcp_milens_query({query: "<topic>"})` — search section headings across all docs and code
+3. `mcp_milens_grep({pattern: "<keyword>", include: "**/*.md"})` — text search within docs only
+
+### Before updating documentation:
+1. `mcp_milens_get_file_symbols({file: "<doc.md>"})` — understand document structure first
+2. If documenting a code symbol: `mcp_milens_context({name: "<symbolName>"})` — get full symbol info (signature, callers, deps)
+3. `mcp_milens_grep({pattern: "<symbolName>", include: "**/*.md"})` — check if other docs already reference it
+
+### After renaming/deleting a code symbol:
+- `mcp_milens_grep({pattern: "<oldName>", include: "**/*.md"})` — find docs that need updating (milens indexes markdown links as cross-file references)
+
+## Never Do
+
+- NEVER edit a symbol without first running `mcp_milens_impact` on it.
+- NEVER delete or rename without running both `mcp_milens_grep` and `mcp_milens_impact`.
+- NEVER commit without running `mcp_milens_detect_changes()`.
+- NEVER call milens MCP tools without the `repo` parameter.
+- NEVER use `mcp_milens_query` for multi-word display text or UI labels — use `mcp_milens_grep`.
+
+---
+
+## Reference
+
+### ⭐ Core Tools — Use Every Session (8)
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_overview` | **Use this first.** Combined context + impact + grep. 1 call replaces 3-5 file reads. |
+| `mcp_milens_impact` | Blast radius BEFORE editing. Shows what WILL BREAK. |
+| `mcp_milens_edit_check` | Pre-edit safety: callers + exports + re-export chains + test coverage |
+| `mcp_milens_context` | 360° view: all callers + all callees. Instant dependency graph. |
+| `mcp_milens_query` | Find symbol definitions by name (FTS5 instant search) |
+| `mcp_milens_grep` | Search ALL files for any text (templates, configs, docs, styles) |
+| `mcp_milens_detect_changes` | Pre-commit: which symbols changed + dependents + risk scores |
+| `mcp_milens_codebase_summary` | Project overview in ~500 tokens. Use instead of reading README. |
+
+### 🔧 Situational Tools — Use When Needed (15)
+
+| Tool | Purpose | Use when... |
+|---|---|---|
+| `mcp_milens_review_pr` | PR risk assessment | Before opening PR |
+| `mcp_milens_review_symbol` | Single symbol deep-dive | Symbol is flagged CRITICAL/HIGH |
+| `mcp_milens_test_plan` | Mock strategy + >=3 test scenarios | Writing new tests |
+| `mcp_milens_test_coverage_gaps` | Untested symbols sorted by risk | Finding test priorities |
+| `mcp_milens_test_impact` | Maps changes → test files | After making edits |
+| `mcp_milens_test_generate` | Auto-generate test file | Starting tests from scratch |
+| `mcp_milens_security_scan` | 50+ security rules | Security audit requested |
+| `mcp_milens_trace` | Call chains from entrypoints | Debugging execution flow |
+| `mcp_milens_routes` | Framework routes/endpoints | Finding API endpoints |
+| `mcp_milens_smart_context` | Intent-aware context | Understand/edit/debug/test modes |
+| `mcp_milens_domains` | Domain clusters | Understanding module structure |
+| `mcp_milens_explain_relationship` | Shortest dependency path | How A connects to B |
+| `mcp_milens_get_type_hierarchy` | Inheritance tree | Class/interface exploration |
+| `mcp_milens_find_dead_code` | Unused exported symbols | Before major refactors |
+| `mcp_milens_find_similar` | Symbols with shared callers/callees | Finding refactor patterns |
+
+### 📚 Advanced Tools — Reference (19)
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_status` | Index health: symbols, links, files, coverage, staleness |
+| `mcp_milens_repos` | List all indexed repositories |
+| `mcp_milens_annotate` | Record observations about symbols (persists across sessions) |
+| `mcp_milens_recall` | Retrieve annotations from past sessions |
+| `mcp_milens_session_start` | Register agent session |
+| `mcp_milens_session_end` | End session and record stats |
+| `mcp_milens_session_context` | Get session metadata + annotations |
+| `mcp_milens_handoff` | Transfer context between agent sessions |
+| `mcp_milens_orchestrate` | Full cycle: detect → review → impact → gaps → dead code |
+| `mcp_milens_pre_commit_check` | Pre-commit risk scan |
+| `mcp_milens_compare_impact` | Compare impact graph before/after edit |
+| `mcp_milens_semantic_search` | Hybrid FTS5 + vector search |
+| `mcp_milens_fix_apply` | Apply security fix to a file |
+| `mcp_milens_hook_preCompact` | Save metrics before context compaction |
+| `mcp_milens_hook_postCompact` | Restore context after compaction |
+| `mcp_milens_hook_onFileChange` | Trigger on file change hook |
+| `mcp_milens_ast_explore` | Parse code to AST S-expression |
+| `mcp_milens_test_query` | Test tree-sitter query patterns |
+| `mcp_milens_get_file_symbols` | All symbols in a file with ref/dep counts |
+
+### Keeping the Index Fresh
+
+After significant code changes: `npx milens analyze -p . --force` (replace `.` with your project root if running from a different directory)
+
+### Skills
+
+| Task | Read this skill file |
+|------|---------------------|
+| General milens tools reference | `.agents/skills/milens/SKILL.md` |
+| Work in the Adapters area | `.agents/skills/adapters/SKILL.md` |
+| Work in the Root area | `.agents/skills/root/SKILL.md` |
+| Work in the Apps area | `.agents/skills/apps/SKILL.md` |
+| Work in the Docs area | `.agents/skills/docs/SKILL.md` |
+| Work in the Test area | `.agents/skills/test/SKILL.md` |
+| Work in the Scripts area | `.agents/skills/scripts/SKILL.md` |
+| Work in the Analyzer area | `.agents/skills/analyzer/SKILL.md` |
+| Work in the Orchestrator area | `.agents/skills/orchestrator/SKILL.md` |
+| Work in the Parser area | `.agents/skills/parser/SKILL.md` |
+| Work in the Security area | `.agents/skills/security/SKILL.md` |
+| Work in the Server area | `.agents/skills/server/SKILL.md` |
+| Work in the Store area | `.agents/skills/store/SKILL.md` |
+| Work in the Ui area | `.agents/skills/ui/SKILL.md` |
+| Execute milens-plan workflow | `.agents/skills/milens-plan/SKILL.md` |
+| Execute milens-code-review workflow | `.agents/skills/milens-code-review/SKILL.md` |
+| Execute milens-tdd workflow | `.agents/skills/milens-tdd/SKILL.md` |
+| Execute milens-security-review workflow | `.agents/skills/milens-security-review/SKILL.md` |
+| Execute milens-refactor-clean workflow | `.agents/skills/milens-refactor-clean/SKILL.md` |
+| Execute milens-eval workflow | `.agents/skills/milens-eval/SKILL.md` |
+| Execute milens-architect workflow | `.agents/skills/milens-architect/SKILL.md` |
+| Execute milens-debugger workflow | `.agents/skills/milens-debugger/SKILL.md` |
+
 <!-- milens:end -->