purecontext-mcp 1.2.0 → 1.5.1

package/LANGUAGE-SUPPORT.md

@@ -0,0 +1,144 @@
+# Language Support
+
+PureContext indexes **34 languages** out of the box, plus a small set of regex-based handlers for stylesheets. Every grammar is bundled as a WASM file — no separate install, no native compilation, no language servers to start. When you point it at a polyglot repo, all handlers run in parallel.
+
+This page is the user-facing tour: what's supported, what gets pulled out, and what to expect from each major category. For parameter-level details (every node kind, every signature shape), see the [reference manual](docs/07-language-support.md).
+
+---
+
+## The full list
+
+### Web and application languages
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | functions, classes, methods, consts, types, interfaces, enums — full type annotations in signatures |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | functions, classes, methods, exported consts |
+| Python | `.py` | functions, classes, methods, module-level consts — docstrings used as summaries |
+| PHP | `.php` | functions, classes, interfaces, traits, enums, methods, properties, constants — PHP 8 attributes supported |
+| Ruby | `.rb` | functions, classes, methods, modules, constants |
+| Go | `.go` | functions, methods (bare names, no receiver prefix), structs, interfaces, consts, types — unexported names are skipped |
+| Java | `.java` | classes, interfaces, enums, methods (including package-private), inner classes |
+| Kotlin | `.kt`, `.kts` | functions, extension functions, classes, interfaces, objects, enums, typealiases — KDoc summaries |
+| C# | `.cs` | classes, interfaces, enums, structs, records, methods, properties, consts |
+| Scala | `.scala`, `.sc` | classes, traits, objects, case classes, functions, methods, types, enums |
+| Dart | `.dart` | classes, mixins, extensions, enums, functions, methods — `_`-prefixed names are skipped |
+| Swift | `.swift` | classes, structs, protocols, actors, extensions, methods, enums |
+| Elixir | `.ex`, `.exs` | modules, functions, macros, structs, protocols |
+| Haskell | `.hs`, `.lhs` | functions, data types, typeclasses, instances, type aliases, newtypes |
+| Lua | `.lua` | functions, methods, consts |
+| R | `.r`, `.R`, `.Rmd` | functions, consts, S3/S4/R6 classes — Roxygen2 doc comments |
+| Perl | `.pl`, `.pm` | functions, packages |
+| Groovy | `.groovy` | functions, classes, methods |
+| Erlang | `.erl`, `.hrl` | functions, modules |
+| Gleam | `.gleam` | functions, types |
+
+### Systems languages
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| C | `.c`, `.h` | functions, structs, enums, macros, types — `static` functions skipped (translation-unit internal) |
+| C++ | `.cpp`, `.cxx`, `.cc`, `.hpp`, `.hxx`, `.hh` | All C kinds plus namespaces, templates, template classes with export macros |
+| Rust | `.rs` | functions, methods (bare names), structs, enums, traits, consts, types — `pub` filter for impl methods |
+| Fortran | `.f90`, `.f95`, `.for`, `.f` | functions, subroutines, modules |
+| Objective-C | `.m`, `.h` | functions, classes, methods |
+
+### Scripting and game
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| Bash | `.sh`, `.bash` | functions |
+| GDScript | `.gd` | functions, classes, signals |
+
+### Infrastructure and config
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| Terraform / HCL | `.tf`, `.hcl` | resources, modules, variables, outputs |
+| Nix | `.nix` | functions, attributes |
+
+### Data and API
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| SQL | `.sql` | tables, views, functions, procedures |
+| Protobuf | `.proto` | messages, services, enums, RPCs |
+| GraphQL | `.graphql`, `.gql` | types, queries, mutations, subscriptions, fragments |
+| OpenAPI / YAML | `.yaml`, `.yml` | endpoints, schemas (OpenAPI detected by content) |
+| XML | `.xml` | elements (configurable patterns — opt-in) |
+
+### Stylesheets (regex-based, no WASM grammar)
+
+CSS-family languages don't have a stable tree-sitter grammar, so PureContext extracts a focused subset using regex. Only named, reusable constructs are indexed — plain selectors are skipped because they would flood the index with noise.
+
+| Language | Extensions | What you get |
+|----------|-----------|-------------|
+| SCSS / SASS | `.scss`, `.sass` | `@mixin`, `@function`, top-level `$variables`, `%placeholders`, `@keyframes` |
+| LESS | `.less` | `.mixin(@params)`, top-level `@variables`, `@keyframes` |
+| CSS | `.css` | `--custom-properties` (opt-in via `indexing.cssVariables: true`) |
+
+---
+
+## What gets indexed for every language
+
+Regardless of language, every symbol you find through `search_symbols` carries:
+
+- **Name** — the identifier as it appears in source
+- **Kind** — function, class, method, route, component, etc.
+- **Byte offsets** — `startByte` / `endByte` for precise source retrieval; no need to re-read the whole file to grab a function body
+- **Signature** — a one-line declaration with the full type information available in that language
+- **Summary** — sourced from the docstring/JSDoc/Javadoc/Roxygen comment if present, otherwise inferred from framework context (route path, ORM table, etc.), otherwise a one-line AI summary, otherwise the signature itself
+- **Import / dependency edges** — used by the dependency graph, blast radius, and cycle detection tools
+
+The summary chain (docstring → framework inference → AI → signature fallback) is what makes search across an undocumented codebase still work. See [AI Summaries](AI-SUMMARIES.md) for how to enable LLM summaries on legacy projects.
+
+---
+
+## What is filtered out automatically
+
+Some things you don't want in the index — they bloat it and pollute search results. PureContext excludes:
+
+- Standard build and dependency directories: `node_modules/`, `.git/`, `dist/`, `build/`, `target/`, `.next/`, `.nuxt/`, `.claude/`
+- Lock files (`*.lock`) and environment files (`.env*`)
+- Binary files (detected by null-byte scanning of the first 8 KB — works without a hardcoded extension list)
+- Files larger than 1 MB (raise the limit with `maxFileSizeBytes` in config)
+- Secret files: `*.pem`, `*.key`, `id_rsa`, `credentials.json`, `serviceAccountKey*.json`
+
+It also respects language-level visibility:
+
+- **Go**: unexported names (lowercase first letter)
+- **C**: `static` functions (translation-unit internal)
+- **Java / C# / PHP**: `private` members
+- **Dart**: `_`-prefixed names
+
+Public API tools (`get_public_api`) rely on these rules being applied consistently — they assume the index already reflects what is externally visible.
+
+---
+
+## Known limitations
+
+- **TypeScript `.tsx`** uses a separate `tree-sitter-tsx` grammar from `.ts`. Both are bundled.
+- **Python stubs** (`.pyi`) are not indexed — only `.py` files.
+- **Terraform** `dynamic` blocks with complex expressions may not be fully extracted.
+- **XML** element extraction uses configurable patterns rather than indexing every tag — turn it on per project if you need it.
+- **CSS** custom properties (`--foo`) are off by default; enable with `indexing.cssVariables: true` when you have a design system worth indexing.
+
+---
+
+## Adding a new language
+
+If a grammar you care about is missing, the path to support is straightforward:
+
+1. Add a new file in `src/handlers/`, implementing `LanguageHandler`
+2. Bundle the `.wasm` grammar in `grammars/`
+3. Register the handler in the language dispatcher
+4. Add tests against fixture files in `test/handlers/`
+
+Regex-only handlers (like SCSS) skip step 2 entirely — they return `null` from `grammarPath()`.
+
+See `docs/25-architecture-overview.md` for the three-layer design (Core → Handlers → Adapters) and the conventions every handler follows.
+
+---
+
+→ Full parameter-level reference: [docs/07-language-support.md](docs/07-language-support.md)
+→ Adapter layer that adds framework-specific symbols on top: [FRAMEWORK-ADAPTERS.md](FRAMEWORK-ADAPTERS.md)

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/purecontext-mcp.svg)](https://www.npmjs.com/package/purecontext-mcp)
 [![Stable](https://img.shields.io/badge/stability-stable-brightgreen.svg)](docs/27-api-stability.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 **Stop burning context tokens reading whole files.** PureContext MCP indexes your codebase and lets AI agents retrieve exactly the code they need — a single function, a class, a route definition — without loading hundreds of irrelevant lines first.
 
@@ -18,8 +19,12 @@ But token savings are the mechanism, not the point. The point is that AI gets be
 ## Quick start
 
 ```bash
-# Connect to Claude Code (no global install needed)
-claude mcp add purecontext-mcp -- npx purecontext-mcp
+# 1. Connect to Claude Code (no global install needed)
+claude mcp add purecontext-mcp -- npx purecontext-mcp@latest
+
+# 2. Inside your project, install the workflow rules
+#    (auto-detects Claude / Cursor / Windsurf / Continue / Cline / Roo Code / VS Code / Claude Desktop)
+npx purecontext-mcp@latest install all
 ```
 
 Then in a Claude Code conversation:
@@ -32,6 +37,45 @@ That's it. Claude will index your codebase and you can start navigating it by na
 
 ---
 
+## What this looks like in practice
+
+A typical "find and understand" conversation, before vs. after:
+
+**Without PureContext**
+
+```
+You:    Where do we handle Stripe webhook signature verification?
+Claude: I'll search the codebase.
+        [reads src/api/webhooks/stripe.ts — 412 lines, ~3,100 tokens]
+        [reads src/lib/stripe-client.ts    — 287 lines, ~2,150 tokens]
+        [reads src/middleware/webhook.ts   — 198 lines, ~1,490 tokens]
+        Verification happens in verifyStripeSignature() at line 87 of stripe.ts.
+        Total context used: ~6,740 tokens
+```
+
+**With PureContext**
+
+```
+You:    Where do we handle Stripe webhook signature verification?
+Claude: search_symbols(query: "stripe webhook signature")
+        → 3 matches, 78 tokens
+        get_symbol_source(symbolId: "verifyStripeSignature")
+        → 32 lines, 180 tokens
+        verifyStripeSignature() at src/api/webhooks/stripe.ts:87.
+        It uses the timing-safe HMAC check from Stripe's SDK with a 5-minute tolerance.
+        Total context used: ~258 tokens — 96% less
+```
+
+The agent stays in the conversation and can keep going (blast radius, related tests, change planning) instead of running out of context after one file read.
+
+---
+
+## Measured search precision
+
+PureContext is benchmarked on **87 real-world open-source projects** with 25 curated ground-truth queries each. Top-rank precision (P@1) reaches 84% on NestJS, 84% on Terraform, 72% on Protobuf and GraphQL, 60% on Nix, 52% on LÖVE (Lua/C++), and 40% on Tokio (Rust). Full per-language tables, methodology, and reproduction steps are in [BENCHMARKS.md](BENCHMARKS.md).
+
+---
+
 ## Documentation
 
 ### User Guide — start here
@@ -54,6 +98,8 @@ The guide explains what PureContext does, why each feature exists, and how to us
 | [Visualizing Code Structure](VISUALIZING-CODE.md) | Mermaid/DOT diagrams, architecture snapshots |
 | [AST-Level Search](AST-SEARCH.md) | Node types, signatures, decorators, complexity |
 | [Code Intelligence](CODE-INTELLIGENCE.md) | Entry points, public API, TODOs, coverage |
+| [Language Support](LANGUAGE-SUPPORT.md) | All 34 supported languages and what's extracted |
+| [Framework Adapters](FRAMEWORK-ADAPTERS.md) | Vue, React, Django, Spring, Rails, Flutter, ORMs, and more |
 | [Using PureContext with a Team](TEAM-SETUP.md) | Shared server, enterprise setup |
 
 **Real-world workflows:**
@@ -69,17 +115,45 @@ The guide explains what PureContext does, why each feature exists, and how to us
 
 ### Reference Manual
 
-Parameter-level documentation for every tool, configuration option, language, framework adapter, and deployment option.
-
-You should start from docs/README.md.
+Parameter-level documentation for every tool, configuration option, language, framework adapter, and deployment option lives in [`docs/README.md`](docs/README.md). The reference manual is cross-linked with the user guide above — every topic has both a narrative and a reference page where one helps.
 
 ---
 
 ## What it indexes
 
-**34 languages** including TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, Kotlin, Swift, Dart, C, C++, Elixir, Haskell, Scala, R, Bash, Terraform, Protobuf, GraphQL, SQL, and more.
+### Languages
+
+**34 languages** via bundled tree-sitter WASM grammars — no separate install required.
 
-**Framework-aware extraction** for Vue, React, Nuxt, Next.js, Angular, NestJS, Express, Fastify, Django, FastAPI, Flask, Gin, Rails, Laravel, Spring Boot, and more. Routes, components, hooks, models, and middleware are extracted as first-class symbols.
+| Category | Languages |
+|----------|-----------|
+| Web / Application | TypeScript, JavaScript, Python, PHP, Ruby, Go, Java, Kotlin, C#, Scala, Dart, Swift, Elixir, Haskell, Lua, R, Perl, Groovy, Erlang, Gleam |
+| Systems | C, C++, Rust, Fortran, Objective-C |
+| Scripting & Game | Bash, GDScript |
+| Infrastructure & Config | Terraform / HCL, Nix |
+| Data & API | SQL, Protobuf, GraphQL, OpenAPI / YAML, XML |
+| Styling (regex-based) | SCSS, SASS, LESS, CSS |
+
+→ [Language Support guide](LANGUAGE-SUPPORT.md) · [Full reference](docs/07-language-support.md)
+
+### Frameworks
+
+**Framework-aware extraction** — routes, components, hooks, models, ORM entities, and middleware are pulled out as first-class symbols (not just functions and classes).
+
+| Stack | Frameworks |
+|-------|-----------|
+| JavaScript / TypeScript | Vue 3, React, Nuxt, Next.js (Pages + App Router), Angular, NestJS, Express, Fastify |
+| Python | Django, FastAPI, Flask |
+| Go | Gin, Echo, Fiber |
+| PHP | Laravel, Symfony |
+| Ruby | Rails, Sinatra |
+| Java | Spring Boot, Micronaut, Quarkus |
+| Kotlin | Ktor, Spring (Kotlin) |
+| Rust | Axum, Actix-web, Rocket |
+| Mobile | Flutter |
+| ORMs | Hibernate, SQLAlchemy, Django ORM, Prisma, TypeORM |
+
+→ [Framework Adapters guide](FRAMEWORK-ADAPTERS.md) · [Full reference](docs/08-framework-adapters.md)
 
 ---
 
@@ -180,22 +254,86 @@ If your team runs a shared PureContext server, connect with an HTTP transport in
 
 Installing PureContext gives your agent the tools. Adding the agent instructions tells it *how* to use them — which tool to pick for each task, in what order, and what to avoid.
 
-Two instruction files are provided at the repository root:
+Without these instructions, an agent may default to reading entire files rather than using `search_symbols`, or may not know to call `list_repos` first to get the repository ID required by every tool.
 
-**`AGENT_INSTRUCTIONS_SHORT.md`** — ~2 KB. The mandatory workflow, tool selection table, core rules, and common patterns. Use this for agents with limited system prompt space.
+### One-command install (recommended)
 
-**`AGENT_INSTRUCTIONS.md`** — ~15 KB. Adds detailed parameter notes, every usage pattern, decision trees, and anti-patterns. Use this for complex multi-step workflows.
+Run this once inside your project directory:
 
-**Claude Code** — add to your project's `CLAUDE.md`:
+```bash
+npx purecontext-mcp@latest install all
+```
+
+This auto-detects which AI coding tools you have set up in the project and writes the PureContext workflow rules to the right place for each. Re-running is safe — every writer is idempotent (managed blocks are marked and replaced rather than appended).
+
+When no `--scope` flag is given, the CLI prompts you to choose where to install:
+
+```
+Where should PureContext be installed?
+  1) Local  — this project only
+  2) Global — all projects (user-level config)
+  3) Both
+```
+
+Pass `--scope` to skip the prompt:
 
 ```bash
-cat AGENT_INSTRUCTIONS_SHORT.md >> CLAUDE.md
+npx purecontext-mcp@latest install all --scope=local    # this project only
+npx purecontext-mcp@latest install all --scope=global   # user-level, all projects
+npx purecontext-mcp@latest install all --scope=both     # both places at once
 ```
 
-**Cursor** — paste into `.cursorrules` or via Cursor Settings → Rules.
+For a single tool:
 
-**Windsurf** — paste into your workspace memory or rules configuration.
+```bash
+npx purecontext-mcp@latest install <tool> --scope=global
+```
 
-**Any other agent** — paste into whatever system prompt or memory configuration it supports.
+To preview without writing files:
 
-Without these instructions, an agent may default to reading entire files rather than using `search_symbols`, or may not know to call `list_repos` first to get the repository ID required by every tool.
+```bash
+npx purecontext-mcp@latest install all --dry-run
+npx purecontext-mcp@latest install --list      # show which IDEs were detected
+```
+
+Supported tools and where each one writes:
+
+| Tool | Local | Global |
+|------|-------|--------|
+| `claude` | `CLAUDE.md` in project | `~/.claude/CLAUDE.md` + hooks |
+| `cursor` | `.cursor/rules/purecontext.mdc` | `~/.cursor/rules/purecontext.mdc` |
+| `windsurf` | `.windsurfrules` | `~/.windsurfrules` |
+| `continue` | `.continue/config.json` | `~/.continue/config.json` |
+| `cline` | `.clinerules` | local only |
+| `roo-code` | `.roo/rules-code.md` | local only |
+| `vscode` | `.github/copilot-instructions.md` | local only |
+| `claude-desktop` | always global | always global |
+
+### Manual install
+
+If you'd rather paste the rules yourself, three instruction files are at the repository root:
+
+- **[`AGENT_INSTRUCTIONS_SHORT.md`](AGENT_INSTRUCTIONS_SHORT.md)** — ~2 KB. Mandatory workflow, tool selection table, core rules. Use for agents with limited system-prompt space.
+- **[`AGENT_INSTRUCTIONS.md`](AGENT_INSTRUCTIONS.md)** — ~15 KB. Adds parameter notes, decision trees, anti-patterns.
+- **[`AGENT_REFERENCE.md`](AGENT_REFERENCE.md)** — ~30 KB. Full tool reference with every parameter, every navigation pattern, and every known limitation. Installed automatically by `hooks --install`; read this when an agent needs the canonical answer.
+
+Paste the contents into whatever system prompt, memory, or rules configuration your agent uses.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/goranocokoljic/pure-context](https://github.com/goranocokoljic/pure-context). Before opening a feature PR, please open an issue to discuss the design — the three-layer architecture (Core → Handlers → Adapters) has hard rules about dependency direction that are easy to violate accidentally. See [`CLAUDE.md`](CLAUDE.md) at the project root for the architectural conventions.
+
+For language or framework adapters: pick a real-world repository, add a 25-query ground-truth file in `benchmarks/<project>/queries.json`, and include benchmark numbers (P@1 / P@3 / R@5) in the PR description so reviewers can confirm the change is a net improvement.
+
+## Support
+
+- **Bug reports and feature requests:** [GitHub Issues](https://github.com/goranocokoljic/pure-context/issues)
+- **Questions about MCP integration:** Open a Discussion on the repository
+- **Changelog:** [CHANGELOG.md](CHANGELOG.md)
+- **Stability and semver policy:** [docs/27-api-stability.md](docs/27-api-stability.md)

package/USER-GUIDE.md

@@ -2,53 +2,61 @@
 
 This guide explains what PureContext does, why it changes the way you work with code, and how to use its features effectively. Each section focuses on a capability area with real examples and concrete workflows.
 
-For parameter-level documentation — every tool input, output, and flag — see the [Reference Manual](../docs/README.md).
+For parameter-level documentation — every tool input, output, and flag — see the [Reference Manual](docs/README.md).
 
 ---
 
 ## Start here
 
-- [Why PureContext](why-purecontext.md) — The full case: what actually improves when AI has precise context instead of bulk context, who benefits, and what PureContext does not do
+- [Why PureContext](WHY-PURECONTEXT.md) — The full case: what actually improves when AI has precise context instead of bulk context, who benefits, and what PureContext does not do
 
 ---
 
 ## Core capabilities
 
-- [Navigating a New Codebase](navigating-new-code.md) — How to orient yourself on day one, find entry points, trace a feature, and build a mental model without reading files at random
+- [Navigating a New Codebase](NAVIGATING-NEW-CODE.md) — How to orient yourself on day one, find entry points, trace a feature, and build a mental model without reading files at random
 
-- [Finding Code](finding-code.md) — Three search modes with examples: by name when you know it, by meaning when you don't, and by content when you need grep. Includes tips for when each fails.
+- [Finding Code](FINDING-CODE.md) — Three search modes with examples: by name when you know it, by meaning when you don't, and by content when you need grep. Includes tips for when each fails.
 
-- [Making Changes Safely](safe-changes.md) — Blast radius analysis before touching anything, context bundles for understanding dependencies, the full pre-change workflow, and architectural violation detection
+- [Making Changes Safely](SAFE-CHANGES.md) — Blast radius analysis before touching anything, context bundles for understanding dependencies, the full pre-change workflow, and architectural violation detection
 
-- [Understanding Code Relationships](understanding-relationships.md) — Call hierarchies, class hierarchies, interface implementations, circular dependency detection, and coupling maps
+- [Understanding Code Relationships](UNDERSTANDING-RELATIONSHIPS.md) — Call hierarchies, class hierarchies, interface implementations, circular dependency detection, and coupling maps
 
-- [Refactoring Safely](refactoring-safely.md) — Pre-flight checks before renaming, deleting, or moving symbols. Sequenced, risk-annotated refactoring plans for structural changes.
+- [Refactoring Safely](REFACTORING-SAFELY.md) — Pre-flight checks before renaming, deleting, or moving symbols. Sequenced, risk-annotated refactoring plans for structural changes.
 
-- [Understanding Code History](code-history.md) — Symbol-level git history (not file-level), churn analysis for identifying risk, ownership mapping, and PR analysis before you read a diff
+- [Understanding Code History](CODE-HISTORY.md) — Symbol-level git history (not file-level), churn analysis for identifying risk, ownership mapping, and PR analysis before you read a diff
 
 ---
 
 ## Features worth knowing
 
-- [The Web UI](web-ui.md) — When to leave the chat and use the browser: visual dependency graphs, the architecture heatmap, symbol timelines, and what each is actually useful for
+- [The Web UI](WEB-UI.md) — When to leave the chat and use the browser: visual dependency graphs, the architecture heatmap, symbol timelines, and what each is actually useful for
 
-- [AI Summaries](ai-summaries.md) — How symbol descriptions are generated, why they matter for search quality and AI accuracy, what they cost, and when to enable them
+- [AI Summaries](AI-SUMMARIES.md) — How symbol descriptions are generated, why they matter for search quality and AI accuracy, what they cost, and when to enable them
 
-- [Code Health & Architecture Analysis](code-health.md) — Quality metrics, anti-pattern detection, auto-generated architecture docs, CI enforcement, and finding refactoring opportunities before they become crises
+- [Code Health & Architecture Analysis](CODE-HEALTH.md) — Quality metrics, anti-pattern detection, auto-generated architecture docs, CI enforcement, and finding refactoring opportunities before they become crises
 
-- [Health Dashboards & Debt Reporting](health-dashboards.md) — Five-axis health radar, before/after PR comparisons, and comprehensive debt reports with prioritized action items
+- [Health Dashboards & Debt Reporting](HEALTH-DASHBOARDS.md) — Five-axis health radar, before/after PR comparisons, and comprehensive debt reports with prioritized action items
 
-- [Visualizing Code Structure](visualizing-code.md) — Mermaid and DOT diagrams of import graphs, call graphs, class hierarchies, and dependency matrices. Architecture snapshots for tracking structural change over time.
+- [Visualizing Code Structure](VISUALIZING-CODE.md) — Mermaid and DOT diagrams of import graphs, call graphs, class hierarchies, and dependency matrices. Architecture snapshots for tracking structural change over time.
 
-- [AST-Level Search](ast-search.md) — Find any tree-sitter node type, search by type signature pattern, find symbols by decorator, and filter by complexity thresholds
+- [AST-Level Search](AST-SEARCH.md) — Find any tree-sitter node type, search by type signature pattern, find symbols by decorator, and filter by complexity thresholds
 
-- [Code Intelligence](code-intelligence.md) — Entry points, public API surface, TODO inventory, complexity hotspots, type graphs, untested symbols, and coverage mapping
+- [Code Intelligence](CODE-INTELLIGENCE.md) — Entry points, public API surface, TODO inventory, complexity hotspots, type graphs, untested symbols, and coverage mapping
+
+---
+
+## Language and framework coverage
+
+- [Language Support](LANGUAGE-SUPPORT.md) — All 34 supported languages plus regex-based stylesheet handlers: what's extracted, what's filtered, and known limitations
+
+- [Framework Adapters](FRAMEWORK-ADAPTERS.md) — Routes, components, and ORM entities pulled out as first-class symbols for Vue, React, Nuxt, Next.js, Angular, NestJS, Django, FastAPI, Flask, Spring Boot, Rails, Laravel, Flutter, and more
 
 ---
 
 ## For teams and enterprise
 
-- [Using PureContext with a Team](team-setup.md) — Why a shared server is fundamentally different from local use, how to set it up, how to keep the index current automatically, and what enterprise deployments need to consider
+- [Using PureContext with a Team](TEAM-SETUP.md) — Why a shared server is fundamentally different from local use, how to set it up, how to keep the index current automatically, and what enterprise deployments need to consider
 
 ---
 
@@ -56,16 +64,16 @@ For parameter-level documentation — every tool input, output, and flag — see
 
 Complete end-to-end examples showing how PureContext fits into real development situations:
 
-- [Onboarding to a New Codebase](workflow-onboarding.md) — First day on a 6,000-file microservices platform: from zero understanding to bug found and fix scoped in 15 minutes
+- [Onboarding to a New Codebase](WORKFLOW-ONBOARDING.md) — First day on a 6,000-file microservices platform: from zero understanding to bug found and fix scoped in 15 minutes
 
-- [Refactoring Legacy Code](workflow-refactoring.md) — Replacing a custom JWT implementation in a 6-year-old Django monolith: discovery, hidden dependencies, migration planning, and verification
+- [Refactoring Legacy Code](WORKFLOW-REFACTORING.md) — Replacing a custom JWT implementation in a 6-year-old Django monolith: discovery, hidden dependencies, migration planning, and verification
 
-- [Reviewing a Pull Request](workflow-pr-review.md) — A 40-file authentication migration PR: structured review in 45 minutes that found two real issues before reading most of the diff
+- [Reviewing a Pull Request](WORKFLOW-PR-REVIEW.md) — A 40-file authentication migration PR: structured review in 45 minutes that found two real issues before reading most of the diff
 
-- [Running a Tech Debt Sprint](workflow-tech-debt.md) — Full lifecycle of a two-week debt reduction sprint: assessment, planning, safe execution, and proving the improvement with snapshots
+- [Running a Tech Debt Sprint](WORKFLOW-TECH-DEBT.md) — Full lifecycle of a two-week debt reduction sprint: assessment, planning, safe execution, and proving the improvement with snapshots
 
 ---
 
 ## Reference Manual
 
-The [Reference Manual](../docs/README.md) covers every tool, configuration option, language, framework adapter, and deployment option in detail. Use it when you need the exact parameter name, the full list of symbol kinds, or the Docker Compose configuration.
+The [Reference Manual](docs/README.md) covers every tool, configuration option, language, framework adapter, and deployment option in detail. Use it when you need the exact parameter name, the full list of symbol kinds, or the Docker Compose configuration.

package/dist/cli/hooks.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `purecontext-mcp hooks --install` / `hooks --list`
+ * `purecontext-mcp hook-pretooluse|hook-posttooluse|hook-precompact|hook-worktree-create|hook-worktree-remove`
+ *
+ * Merges hook entries into ~/.claude/settings.json using CLI-style commands
+ * (npx purecontext-mcp hook-*) so no scripts need to be copied to ~/.claude/hooks/.
+ * Also injects PureContext agent instructions into ~/.claude/CLAUDE.md.
+ */
+export declare function cmdHooksInstall(): void;
+export declare function cmdHooksList(): void;
+export declare function mergeSettings(): void;
+export declare function injectClaudeMd(): void;
+/** PreToolUse: warn before Edit/Write/MultiEdit. */
+export declare function cmdHookPreToolUse(): Promise<void>;
+/** PostToolUse: re-index the repo after Edit/Write/MultiEdit. */
+export declare function cmdHookPostToolUse(): Promise<void>;
+/** PreCompact: inject session snapshot before context compaction. */
+export declare function cmdHookPreCompact(): Promise<void>;
+/** WorktreeCreate: auto-index a new agent worktree. */
+export declare function cmdHookWorktreeCreate(): Promise<void>;
+/** WorktreeRemove: fires when an agent worktree is removed. No-op for now. */
+export declare function cmdHookWorktreeRemove(): Promise<void>;
+/** TaskCompleted: surface post-task diagnostics and remind about available tools. */
+export declare function cmdHookTaskCompleted(): Promise<void>;
+/** SubagentStart: inject condensed repo orientation for spawned subagents. */
+export declare function cmdHookSubagentStart(): Promise<void>;
+export declare function runHooksCommand(args: string[]): void;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/cli/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA0IH,wBAAgB,eAAe,IAAI,IAAI,CAetC;AAED,wBAAgB,YAAY,IAAI,IAAI,CAenC;AAID,wBAAgB,aAAa,IAAI,IAAI,CAoDpC;AA6BD,wBAAgB,cAAc,IAAI,IAAI,CAuBrC;AAuCD,oDAAoD;AACpD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAoBvD;AAED,iEAAiE;AACjE,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CA8BxD;AA6DD,qEAAqE;AACrE,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBvD;AAED,uDAAuD;AACvD,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAkB3D;AAED,8EAA8E;AAC9E,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3D;AAyED,qFAAqF;AACrF,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAwC1D;AAED,8EAA8E;AAC9E,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CA8C1D;AAID,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAUpD"}