feat(mcp, docs) Remove file watcher triggering full reindex on every change. Improve docs

Author: PatrickSys

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.2.1 (2025-12-07)
+
+### Removed
+
+- File watcher feature removed (will be reintroduced with incremental indexing support)
+
+---
+
 ## 1.2.0 (2025-12-06)
 
 ### Added
@@ -14,15 +22,11 @@
   - `topUsed` array shows usage ratios (e.g., `@mycompany/ui: 847` vs `primeng: 3`)
   - Exposes tsconfig paths so AI can identify internal vs external imports
 
-- **Enhanced `get_indexing_status`**: Now includes file watcher stats and pending changes
-  - Shows `pendingChanges` count (files changed since last index)
-  - Provides actionable hints for re-indexing decisions
-
-- **`incrementalOnly` option for `refresh_index`**: API ready for Phase 2 incremental indexing
+- **`incrementalOnly` option for `refresh_index`**: API ready for incremental indexing
 
 ### Changed
 
-- **Framework-agnostic architecture clarified**: Works on ANY project, Angular as first specialized analyzer
+- **Framework-agnostic architecture**: Works on ANY project, Angular as first specialized analyzer
   - Generic analyzer supports 32 file extensions (JS, TS, Python, Java, Go, Rust, etc.)
   - Angular patterns (inject, signals, standalone) are specialized intelligence, not a requirement
 
@@ -33,22 +37,19 @@
 
 - **Indexer now forwards patterns generically**: Keeps core framework-agnostic
 
-- README updated with correct "works on any project" messaging
-
-
 ---
 
 ## 1.1.0 (2025-12-05)
 
 ### Added
-- **Testing framework detection**: Detects Jest, Jasmine/Karma, Vitest, Cypress, Playwright from actual code patterns (not just package.json)
-- **Golden Files**: Surfaces files that demonstrate all team patterns together—one file for AI to mimic
+- **Testing framework detection**: Detects Jest, Jasmine/Karma, Vitest, Cypress, Playwright from actual code patterns
+- **Golden Files**: Surfaces files that demonstrate all team patterns together
 - **Wrapper recommendations**: Exposes library wrapper detection in `get_team_patterns` response
 - **Test utilities tracking**: Detects ng-mocks, MSW, Testing Library usage
 
 ### Changed
-- Framework-agnostic indexer: Pattern detection moved into framework analyzers, indexer just forwards
-- Test files now parsed for pattern detection (`parseTests: true`)
+- Framework-agnostic indexer: Pattern detection moved into framework analyzers
+- Test files now parsed for pattern detection
 
 ### Removed
 - `get_analyzer_info` tool: Provided no user value—pure implementation details that wasted context window
@@ -67,8 +68,3 @@ Initial release.
 - LanceDB vector storage
 - Auto-indexes on startup
 - No API keys required, runs 100% locally
-
-**Known limitations:**
-
-- Angular only (React/Vue analyzers not yet implemented)
-- Full re-index on every restart (no incremental indexing yet)

MOTIVATION.md

@@ -1,10 +1,10 @@
 # Motivation: Why This Exists
 
-> **TL;DR**: AI coding assistants are smart but generic. They don't know YOUR codebase's patterns. This MCP gives them that context.
+> **TL;DR**: AI coding assistants are smart but generic. They don't know YOUR codebase's patterns, conventions, or context. This MCP gives them that context.
 
 ---
 
-## The Problem (Validated by Research)
+## The Problem
 
 ### Industry Pain Points
 
@@ -32,10 +32,10 @@
 
 | Feature | Why It Matters |
 |---------|----------------|
-| **Pattern Frequency Detection** | "97% use inject(), 3% constructor" — AI knows the consensus |
-| **Internal Library Discovery** | "Use @company/ui-toolkit not primeng directly" — wrapper detection |
+| **Pattern Frequency Detection** | "97% use inject(), 3% constructor" - AI knows the consensus |
+| **Internal Library Discovery** | "Use @company/ui-toolkit not primeng directly" - wrapper detection |
 | **Golden Files** | Real examples showing patterns in context, not isolated snippets |
-| **Testing Framework Detection** | "Write Jest tests, not Jasmine" — detected from actual spec files |
+| **Testing Framework Detection** | "Write Jest tests, not Jasmine" - detected from actual spec files |
 
 ### Complementary Positioning
 
@@ -54,41 +54,40 @@ We're honest about what we don't solve:
 | **Pattern frequency ≠ pattern quality** | 97% usage could be technical debt. We show consensus, not correctness. |
 | **Stale index risk** | Manual re-indexing required. Lazy indexing planned (Phase 1.6). |
 | **Framework coverage** | Angular-specialized now. React/Vue analyzers extensible. |
-| **LLM context placement** | We provide data. LLM/client determines how to use it. |
+| **LLM context placement** | We provide structured data. How the AI uses it depends on the client (Cursor, Claude, etc.). |
 
 ---
 
 ## Key Learnings (From Building This)
 
-1. **Statistical detection isn't enough** — Saying "97% use inject()" is useless if AI doesn't see HOW to use it. Golden Files with real examples solved this.
+1. **Statistical detection isn't enough** - Saying "97% use inject()" is useless if AI doesn't see HOW to use it. Golden Files with real examples solved this.
 
-2. **Complementary, not replacement** — We work WITH AGENTS.md, not against it. Different layers of context.
+2. **Complementary, not replacement** - We work WITH AGENTS.md, not against it. Different layers of context.
 
-3. **Simplicity beats completeness** — Dropped features that added complexity without clear value (dependency graphs, violation detection). Focus on core patterns.
+3. **Simplicity beats completeness** - Dropped features that added complexity without clear value (dependency graphs, violation detection). Focus on core patterns.
 
-4. **Human-led, not autonomous** — Research shows autonomous agents fail 65-85% of the time. We optimize for human+AI collaboration.
+4. **Human-led, not autonomous** - Research shows autonomous agents have ~30-35% success rate on multi-step tasks ([Thoughtworks Technology Radar](https://www.thoughtworks.com/radar), arXiv papers). We optimize for human+AI collaboration.
 
 ---
 
-## Claim Validation Status
+## Sources
 
-| Claim | Evidence | Status |
-|-------|----------|--------|
-| "63.3% cite lack of context" | Stack Overflow 2024 Survey | ✅ Cited |
-| "AI doubles code churn" | GitClear 2024 Report | ✅ Cited |
-| "97% inject() usage" | Pattern detection on indexed enterprise codebase | ✅ Validated |
-| "Reduces AI corrections" | 5-use-case methodology planned | ⏳ In Progress |
-| "X% token reduction" | To be measured | ⏳ Pending |
+### Industry Research
 
----
+1. [Stack Overflow 2024 Developer Survey - AI Section](https://survey.stackoverflow.co/2024/ai) - 65,000+ respondents
+2. [GitClear 2024 AI Code Quality Report](https://www.gitclear.com/) - Code churn analysis
+3. [DORA State of DevOps 2024](https://dora.dev/research/2024/dora-report/) - Code churn as quality metric
+4. [Anthropic MCP](https://modelcontextprotocol.io/) - Protocol specification
 
-## Sources
+### Academic Papers (arxiv)
+
+5. [Grounded AI for Code Review](https://arxiv.org/abs/2510.10290) - "Every AI-generated comment must be anchored to deterministic signals"
+6. [Code Digital Twin](https://arxiv.org/abs/2503.07967) - "Tacit knowledge is embedded in developer experience, not code"
+7. [CACE: Context-Aware Eviction](https://arxiv.org/abs/2506.18796) - Multi-factor file scoring for context efficiency
+
+### Internal Validation
 
-1. [Stack Overflow 2024 Developer Survey - AI Section](https://survey.stackoverflow.co/2024/ai) — 65,000+ respondents
-2. [GitClear 2024 AI Code Quality Report](https://www.gitclear.com/) — Code churn analysis
-3. [DORA State of DevOps 2024](https://dora.dev/research/2024/dora-report/) — Code churn as quality metric
-4. [Anthropic MCP](https://modelcontextprotocol.io/) — Protocol specification
-5. Internal validation on enterprise Angular medium-sized codebase
+8. Enterprise Angular codebase (611 files): inject 98%, Jest 74%, wrapper detection working
 
 ---
 

README.md

@@ -100,8 +100,8 @@ AGENTS.md tells the AI what you *want*. We show what you *actually do*—and sur
 | `search_codebase` | Semantic + keyword hybrid search |
 | `get_codebase_metadata` | Project structure + patterns summary |
 | `get_style_guide` | Style guide content lookup |
-| `get_indexing_status` | Index state + file watcher status + pending changes |
-| `refresh_index` | Re-index (supports `incrementalOnly: true` for faster updates) |
+| `get_indexing_status` | Index state and progress |
+| `refresh_index` | Re-index the codebase (supports `incrementalOnly: true` for Phase 2) |
 
 
 
@@ -133,8 +133,6 @@ AGENTS.md tells the AI what you *want*. We show what you *actually do*—and sur
 
 > **Current focus**: JS/TS codebases with Angular as the primary specialized analyzer. The architecture is designed to be language-agnostic with pluggable analyzers—that's the mid-term vision.
 
-File watcher auto-enabled by default. Disable with `WATCH_FILES=false`.
-
 ---
 
 ## Setup
@@ -183,7 +181,6 @@ Or if installed globally:
 |----------|---------|-------------|
 | `EMBEDDING_PROVIDER` | `transformers` | Set to `openai` to use OpenAI's API (faster, lighter) or `transformers` for local (private, free). |
 | `OPENAI_API_KEY` | - | Required if provider is `openai`. |
-| `WATCH_FILES` | `true` | Set to `false` to disable the file watcher. |
 
 **Why use OpenAI?**
 - **Faster**: No need to download/run local 100MB+ models.
@@ -213,15 +210,15 @@ We stay focused. Here's what we deliberately exclude:
 | **Specialized patterns are Angular-only** | MVP | React/Vue specialists are planned. The pluggable architecture makes this extensible. |
 | **Single repo** | MVP | Multi-repo (Nx workspaces) planned. For now, point it at one repo at a time. |
 | **Pattern frequency ≠ correctness** | By design | We show team consensus, not "right" patterns. 97% inject() usage doesn't mean inject() is correct—it means that's what your team does. Combine with AGENTS.md for intent. |
-| **Index goes stale** | MVP | Re-index manually with `refresh_index` or restart the MCP. File watcher catches most changes, but major refactors need a full re-index. Lazy incremental indexing planned. |
+| **Index goes stale** | MVP | Re-index manually with `refresh_index` or restart the MCP. Incremental indexing planned for Phase 2. |
 | **First index can be slow** | Depends | Uses local embeddings by default (downloads ~100MB model). Use `EMBEDDING_PROVIDER=openai` for faster startup if privacy isn't a concern. |
 
 
 ---
 
 ## Why This Exists
 
-📄 **[Motivation](./MOTIVATION.md)** — The research and pain points that led to this
+📄 **[Motivation](./MOTIVATION.md)** - The research and pain points that led to this
 
 ## License