feat: prepare v1.5.0 trust and indexing foundation

AGENTS.md

@@ -1,6 +1,15 @@
 # Agent Instructions
 
-## Internal Documentation
+## Codebase Context
+
+**At start of each task:** Call `get_memory` to load team conventions.
+
+**CRITICAL:** When user says "remember this" or "record this":
+- STOP immediately and call `remember` tool FIRST
+- DO NOT proceed with other actions until memory is recorded
+- This is a blocking requirement, not optional
+
+## Internal Documentation (Submodule)
 
 This repository uses a private git submodule for internal notes.
 
@@ -20,6 +29,6 @@ git pull --recurse-submodules
 git submodule update --remote --merge
 ```
 
-### Privacy & Security
+### Privacy
 
-The `internal-docs` repository is **Private**. It returns a 404 to unauthenticated users/APIs. Access requires a GitHub PAT or SSH keys with repository permissions.
+The `internal-docs` repository is private. It returns a 404 to unauthenticated users. Access requires a GitHub PAT or SSH keys with repository permissions.

MOTIVATION.md

@@ -1,6 +1,6 @@
 # Motivation: Why This Exists
 
-> **TL;DR**: AI coding assistants are smart but dangerous. Without guidance, they "vibe code" their way into technical debt. This MCP gives them **Context** (to know your patterns) and **Wisdom** (to keep your codebase healthy).
+> **TL;DR**: AI coding assistants increase throughput but often degrade stability. Without codebase context, they generate code that works but violates team conventions and architectural rules. This MCP provides structured pattern data and recorded rationale so agents produce code that fits.
 
 ---
 
@@ -28,7 +28,7 @@ AI drastically increases **Throughput** (more code/hour) but often kills **Stabi
 
 ## What This Does
 
-We provide **Active Context**—not just raw data, but the *judgment* of a Senior Engineer.
+This MCP provides **active context** - not raw data, but structured intelligence derived from actual codebase state.
 
 ### 1. Pattern Discovery (The "Map")
 - **Frequency Detection**: "97% use `inject()`, 3% use `constructor`." (Consensus)
@@ -40,19 +40,18 @@ We provide **Active Context**—not just raw data, but the *judgment* of a Senio
 - **Health Context**: "⚠️ Careful, `UserService.ts` is a high-churn hotspot with circular dependencies. Add tests."
 
 ### Works with AGENTS.md
-> **AGENTS.md is the Law. MCP is the Map.**
-- **AGENTS.md** says: "We prefer functional functional programming."
-- **MCP** shows: "Here are the 5 most recent functional patterns we actually used."
+- **AGENTS.md** defines intent: "Use functional patterns."
+- **MCP** provides evidence: "Here are the 5 most recent functional patterns actually used."
 
 ---
 
 ## Known Limitations
 
 | Limitation | Mitigation |
 |------------|--------|
-| **Pattern frequency ≠ pattern quality** | We added **Pattern Momentum** (Rise/Fall trends) to fix this. |
+| **Pattern frequency ≠ pattern quality** | **Pattern Momentum** (Rise/Fall trends) distinguishes adoption direction from raw count. |
 | **Stale index risk** | Manual re-indexing required for now. |
-| **Framework coverage** | Angular-specialized. React/Vue analyzers extensible. |
+| **Framework coverage** | Deep analysis for Angular. Generic analyzer covers 30+ languages. React/Vue specialized analyzers extensible. |
 | **File-level trend detection** | Trend is based on file modification date, not line-by-line content. A recently modified file may still contain legacy patterns on specific lines. Future: AST-based line-level detection. |
 
 ---
@@ -61,7 +60,7 @@ We provide **Active Context**—not just raw data, but the *judgment* of a Senio
 
 1.  **Context alone is dangerous**: Giving AI "all the context" just confuses it or teaches it bad habits (Search Contamination).
 2.  **Decisions > Data**: AI needs *guidance* ("Use X"), not just *options* ("Here is X and Y").
-3.  **Governance through Discovery**: We don't need to block PRs to be useful. If we show the AI that a pattern is "Declining" and "Dangerous," it self-corrects.
+3.  **Governance through Discovery**: Blocking PRs is not required. If the AI sees that a pattern is "Declining" and "Dangerous," it self-corrects.
 
 ---
 
@@ -76,7 +75,3 @@ We provide **Active Context**—not just raw data, but the *judgment* of a Senio
 - **Search Contamination**: Without MCP, models copied legacy patterns 40% of the time.
 - **Momentum Success**: With "Trending" signals, models adopted modern patterns even when they were the minority (3%).
 
----
-
-*Last updated: December 2025*
-

README.md

@@ -1,45 +1,183 @@
 # codebase-context
 
-**AI coding agents don't know your codebase. This MCP fixes that.**
+[![npm version](https://img.shields.io/npm/v/codebase-context)](https://www.npmjs.com/package/codebase-context) [![license](https://img.shields.io/npm/l/codebase-context)](./LICENSE) [![node](https://img.shields.io/node/v/codebase-context)](./package.json)
 
-Your team has internal libraries, naming conventions, and patterns that external AI models have never seen. This MCP server gives AI assistants real-time visibility into your codebase: which libraries your team actually uses, how often, and where to find canonical examples.
+A second brain for AI coding agents. MCP server that remembers team decisions, tracks pattern evolution, and guides every edit with evidence.
 
 ## Quick Start
 
-Add this to your MCP client config (Claude Desktop, VS Code, Cursor, etc.).
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "codebase-context": {
+      "command": "npx",
+      "args": ["-y", "codebase-context", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add `.vscode/mcp.json` to your project root:
 
 ```json
-"mcpServers": {
-  "codebase-context": {
-    "command": "npx",
-    "args": ["codebase-context", "/path/to/your/project"]
+{
+  "servers": {
+    "codebase-context": {
+      "command": "npx",
+      "args": ["-y", "codebase-context", "${workspaceFolder}"]
+    }
   }
 }
 ```
 
-If your environment prompts on first run, use `npx --yes ...` (or `npx -y ...`) to auto-confirm.
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "codebase-context": {
+      "command": "npx",
+      "args": ["-y", "codebase-context", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Open Settings > MCP and add:
+
+```json
+{
+  "mcpServers": {
+    "codebase-context": {
+      "command": "npx",
+      "args": ["-y", "codebase-context", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+No config file needed. Add to `.claude/settings.json` or run:
+
+```bash
+claude mcp add codebase-context -- npx -y codebase-context /path/to/your/project
+```
+
+## What Makes It a Second Brain
+
+Other tools help AI find code. This one helps AI make the right decisions — by remembering what your team does, tracking how patterns evolve, and warning before mistakes repeat.
 
-## What You Get
+### Remembers
 
-- **Internal library discovery** → `@mycompany/ui-toolkit`: 847 uses vs `primeng`: 3 uses
-- **Pattern frequencies** → `inject()`: 97%, `constructor()`: 3%
-- **Pattern momentum** → `Signals`: Rising (last used 2 days ago) vs `RxJS`: Declining (180+ days)
-- **Golden file examples** → Real implementations showing all patterns together
-- **Testing conventions** → `Jest`: 74%, `Playwright`: 6%
-- **Framework patterns** → Angular signals, standalone components, etc.
-- **Circular dependency detection** → Find toxic import cycles between files
-- **Memory system** → Record "why" behind choices so AI doesn't repeat mistakes
+Decisions, rationale, and past failures persist across sessions. Not just what the team does — why.
+
+- Internal library usage: `@mycompany/ui-toolkit` (847 uses) vs `primeng` (3 uses) — and _why_ the wrapper exists
+- "Tried direct PrimeNG toast, broke event system" — recorded as a failure memory, surfaced before the next agent repeats it
+- Conventions from git history auto-extracted: `refactor:`, `migrate:`, `fix:`, `revert:` commits become memories with zero manual effort
+
+### Reasons
+
+Quantified pattern analysis with trend direction. Not "use inject()" — "97% of the team uses inject(), and it's rising."
+
+- `inject()`: 97% adoption vs `constructor()`: 3% — with trend direction (rising/declining)
+- `Signals`: rising (last used 2 days ago) vs `RxJS BehaviorSubject`: declining (180+ days)
+- Golden files: real implementations scoring highest on modern pattern density — canonical examples to follow
+- Pattern conflicts detected: when two approaches in the same category both exceed 20% adoption
+
+### Protects
+
+Before an edit happens, the agent gets a preflight briefing: what to use, what to avoid, what broke last time.
+
+- Preflight card on `search_codebase` with `intent: "edit"` — risk level, preferred/avoid patterns, failure warnings, golden files, impact candidates
+- Failure memories bump risk level and surface as explicit warnings
+- Confidence decay: memories age (90-day or 180-day half-life). Stale guidance gets flagged, not blindly trusted
+- Epistemic stress detection: when evidence is contradictory, stale, or too thin, the preflight card says "insufficient evidence" instead of guessing
+
+### Discovers
+
+Hybrid search (BM25 keyword 30% + vector embeddings 70%) with structured filters across 30+ languages:
+
+- **Framework**: Angular, React, Vue
+- **Language**: TypeScript, JavaScript, Python, Go, Rust, and 25+ more
+- **Component type**: component, service, directive, guard, interceptor, pipe
+- **Architectural layer**: presentation, business, data, state, core, shared
+- Circular dependency detection, style guide auto-detection, architectural layer classification
+
+## Measured Results
+
+Tested against a real enterprise Angular codebase (~30k files):
+
+| What was measured                  | Result                                                   |
+| ---------------------------------- | -------------------------------------------------------- |
+| Internal library detection         | 336 uses of `@company/ui-toolkit` vs 3 direct PrimeNG   |
+| DI pattern consensus               | 98% `inject()` adoption detected, constructor DI flagged |
+| Test framework detection           | 74% Jest, 26% Jasmine/Karma, per-module awareness        |
+| Wrapper discovery                  | `ToastEventService`, `DialogComponent` surfaced over raw |
+| Golden file identification         | Top 5 files scoring 4-6 modern patterns each             |
+
+Without this context, AI agents default to generic patterns: raw PrimeNG imports, constructor injection, Jasmine syntax. With the second brain active, generated code matches the existing codebase on first attempt.
 
 ## How It Works
 
-When generating code, the agent checks your patterns first:
+The difference in practice:
 
-| Without MCP                              | With MCP                             |
+| Without second brain                     | With second brain                    |
 | ---------------------------------------- | ------------------------------------ |
 | Uses `constructor(private svc: Service)` | Uses `inject()` (97% team adoption)  |
 | Suggests `primeng/button` directly       | Uses `@mycompany/ui-toolkit` wrapper |
 | Generic Jest setup                       | Your team's actual test utilities    |
 
+### Preflight Card
+
+When using `search_codebase` with `intent: "edit"`, `"refactor"`, or `"migrate"`, the response includes a preflight card alongside search results:
+
+```json
+{
+  "preflight": {
+    "intent": "refactor",
+    "riskLevel": "medium",
+    "confidence": "fresh",
+    "evidenceLock": {
+      "mode": "triangulated",
+      "status": "pass",
+      "readyToEdit": true,
+      "score": 100,
+      "sources": [
+        { "source": "code", "strength": "strong", "count": 5 },
+        { "source": "patterns", "strength": "strong", "count": 3 },
+        { "source": "memories", "strength": "strong", "count": 2 }
+      ]
+    },
+    "preferredPatterns": [
+      { "pattern": "inject() function", "category": "dependencyInjection", "adoption": "98%", "trend": "Rising" }
+    ],
+    "avoidPatterns": [
+      { "pattern": "Constructor injection", "category": "dependencyInjection", "adoption": "2%", "trend": "Declining" }
+    ],
+    "goldenFiles": [
+      { "file": "src/features/auth/auth.service.ts", "score": 6 }
+    ],
+    "failureWarnings": [
+      { "memory": "Direct PrimeNG toast broke event system", "reason": "Must use ToastEventService" }
+    ]
+  },
+  "results": [...]
+}
+```
+
+One call. The second brain composes patterns, memories, failures, and risk into a single response.
+
 ### Tip: Auto-invoke in your rules
 
 Add this to your `.cursorrules`, `CLAUDE.md`, or `AGENTS.md`:
@@ -59,18 +197,22 @@ Now the agent checks patterns automatically instead of waiting for you to ask.
 
 ## Tools
 
-| Tool                           | Purpose                                       |
-| ------------------------------ | --------------------------------------------- |
-| `search_codebase`              | Semantic + keyword hybrid search              |
-| `get_component_usage`          | Find where a library/component is used        |
-| `get_team_patterns`            | Pattern frequencies + canonical examples      |
-| `get_codebase_metadata`        | Project structure overview                    |
-| `get_indexing_status`          | Indexing progress + last stats                |
-| `get_style_guide`              | Query style guide rules                       |
-| `detect_circular_dependencies` | Find import cycles between files              |
-| `remember`                     | Record memory (conventions/decisions/gotchas) |
-| `get_memory`                   | Query recorded memory by category/keyword     |
-| `refresh_index`                | Re-index the codebase                         |
+| Tool                           | Purpose                                                              |
+| ------------------------------ | -------------------------------------------------------------------- |
+| `search_codebase`              | Hybrid search with filters. Pass `intent: "edit"` for preflight card |
+| `get_component_usage`          | Find where a library/component is used                               |
+| `get_team_patterns`            | Pattern frequencies, golden files, conflict detection                |
+| `get_codebase_metadata`        | Project structure overview                                           |
+| `get_indexing_status`          | Indexing progress + last stats                                       |
+| `get_style_guide`              | Query style guide rules                                              |
+| `detect_circular_dependencies` | Find import cycles between files                                     |
+| `remember`                     | Record memory (conventions/decisions/gotchas/failures)               |
+| `get_memory`                   | Query memory with confidence decay scoring                           |
+| `refresh_index`                | Re-index the codebase + extract git memories                         |
+
+## Language Support
+
+The Angular analyzer provides deep framework-specific analysis (signals, standalone components, control flow syntax, lifecycle hooks, DI patterns). A generic analyzer covers 30+ languages and file types as a fallback: JavaScript, TypeScript, Python, Java, Kotlin, C/C++, C#, Go, Rust, PHP, Ruby, Swift, Scala, Shell, and common config/markup formats.
 
 ## File Structure
 
@@ -97,22 +239,27 @@ The MCP creates the following structure in your project:
 Patterns tell you _what_ the team does ("97% use inject"), but not _why_ ("standalone compatibility"). Use `remember` to capture rationale that prevents repeated mistakes:
 
 ```typescript
-// AI won't change this again after recording the decision
 remember({
   type: 'decision',
   category: 'dependencies',
   memory: 'Use node-linker: hoisted, not isolated',
-  reason:
-    "Some packages don't declare transitive deps. Isolated forces manual package.json additions."
+  reason: "Some packages don't declare transitive deps."
 });
 ```
 
-Memories surface automatically in `search_codebase` results and `get_team_patterns` responses.
+**Memory types:** `convention` (style rules), `decision` (architecture choices), `gotcha` (things that break), `failure` (tried X, failed because Y).
+
+**Confidence decay:** Memories age. Conventions never decay. Decisions have a 180-day half-life. Gotchas and failures have a 90-day half-life. Memories below 30% confidence are flagged as stale in `get_memory` responses.
+
+**Git auto-extraction:** During indexing, conventional commits (`refactor:`, `migrate:`, `fix:`, `revert:`) from the last 90 days are auto-recorded as memories. Zero manual effort.
+
+**Pattern conflicts:** `get_team_patterns` detects when two patterns in the same category are both above 20% adoption with different trends, and surfaces them as conflicts with both sides.
+
+Memories surface automatically in `search_codebase` results, `get_team_patterns` responses, and preflight cards.
 
-**Early baseline — known quirks:**
+**Known quirks:**
 
 - Agents may bundle multiple things into one entry
-- Duplicates can happen if you record the same thing twice
 - Edit `.codebase-context/memory.json` directly to clean up
 - Be explicit: "Remember this: use X not Y"
 
@@ -125,19 +272,19 @@ Memories surface automatically in `search_codebase` results and `get_team_patter
 | `CODEBASE_ROOT`          | -              | Project root to index (CLI arg takes precedence)                               |
 | `CODEBASE_CONTEXT_DEBUG` | -              | Set to `1` to enable verbose logging (startup messages, analyzer registration) |
 
-## Performance Note
+## Performance
 
-This tool runs **locally** on your machine using your hardware.
+This tool runs locally on your machine.
 
-- **Initial Indexing**: The first run works hard. It may take several minutes (e.g., ~2-5 mins for 30k files) to compute embeddings for your entire codebase.
-- **Caching**: Subsequent queries are instant (milliseconds).
-- **Updates**: Currently, `refresh_index` re-scans the codebase. True incremental indexing (processing only changed files) is on the roadmap.
+- **Initial indexing**: First run may take several minutes (e.g., 2-5 min for 30k files) to compute embeddings.
+- **Subsequent queries**: Instant (milliseconds) from cache.
+- **Updates**: `refresh_index` re-scans the codebase. True incremental indexing (processing only changed files) is on the roadmap.
 
 ## Links
 
-- 📄 [Motivation](./MOTIVATION.md) — Why this exists, research, learnings
-- 📋 [Changelog](./CHANGELOG.md) — Version history
-- 🤝 [Contributing](./CONTRIBUTING.md) — How to add analyzers
+- [Motivation](./MOTIVATION.md) — Research and design rationale
+- [Changelog](./CHANGELOG.md) — Version history
+- [Contributing](./CONTRIBUTING.md) — How to add analyzers
 
 ## License