purecontext-mcp 1.5.0 → 1.5.2

package/BENCHMARKS.md

@@ -0,0 +1,153 @@
+# Benchmarks
+
+PureContext is benchmarked on **87 real-world open-source projects** spanning 29 language groups. This page reports measured search precision so you can decide whether PureContext fits your stack before installing.
+
+The benchmarks are reproducible — every project, query set, and result file lives in the `benchmarks/` directory of the source repository.
+
+---
+
+## Methodology
+
+For each project:
+
+1. **Index it** with PureContext.
+2. **Run 25 ground-truth queries** drawn from real symbol names and natural-language descriptions of what each symbol does. Ground-truth answers are the curated "correct" symbols a developer would expect.
+3. **Score three metrics:**
+   - **P@1** (Precision at rank 1): the correct symbol is the top result.
+   - **P@3** (Precision at rank 3): the correct symbol is in the top 3.
+   - **R@5** (Recall at top 5): the correct symbol appears anywhere in the top 5.
+
+P@1 is the most demanding metric — it measures how often the *first* answer is the right one without the agent having to scroll through alternatives. P@3 and R@5 reflect what an agent actually consumes in a real session.
+
+Ground-truth query sets are intentionally curated by hand (`benchmarks/<project>/queries.json`), not auto-generated, and can be inspected or extended.
+
+---
+
+## Per-language averages
+
+Group averages over all benchmarked projects in each language.
+
+| Language group | Projects | P@1 | P@3 | R@5 |
+|----------------|---------:|----:|----:|----:|
+| GraphQL | 3 | **65%** | 81% | 87% |
+| Nix | 2 | **60%** | 74% | 76% |
+| GDScript | 2 | **58%** | 78% | 88% |
+| Terraform / HCL | 2 | **53%** | 64% | 67% |
+| Protobuf | 3 | **51%** | 51% | 60% |
+| TypeScript / JavaScript | 4 | **44%** | 57% | 61% |
+| Lua | 2 | **36%** | 56% | 64% |
+| PHP | 2 | **36%** | 54% | 58% |
+| Python | 2 | **34%** | 46% | 56% |
+| Rust | 2 | **34%** | 50% | 60% |
+| OpenAPI / YAML | 3 | **31%** | 32% | 36% |
+| Kotlin | 2 | **30%** | 36% | 40% |
+| Go | 1 | **28%** | 56% | 76% |
+| Java | 1 | **24%** | 32% | 44% |
+| SQL | 3 | **23%** | 44% | 52% |
+| C / C++ | 6 | **13%** | 22% | 30% |
+| Scala | 2 | 12% | 20% | 32% |
+| Swift | 3 | 11% | 19% | 23% |
+| Ruby | 4 | 10% | 16% | 20% |
+| C# / .NET | 2 | 10% | 16% | 18% |
+| Dart / Flutter | 2 | 8% | 14% | 18% |
+| Objective-C | 3 | 5% | 11% | 16% |
+| Haskell | 2 | 0% | 16% | 22% |
+
+Numbers are averages across the projects in each row. Bold P@1 values mark groups where PureContext consistently produces the right answer at rank 1 on a non-trivial fraction of queries.
+
+---
+
+## Per-project highlights
+
+Selected projects from the full set of 87 — full results in `benchmarks/<project>/results/purecontext.json`.
+
+| Project | Language / framework | P@1 | P@3 | R@5 | Symbols indexed |
+|---------|----------------------|----:|----:|----:|----------------:|
+| nestjs-ecommerce-api | TypeScript / NestJS | 84% | 100% | 100% | 3,314 |
+| terraform-aws-eks | Terraform / HCL | 84% | 92% | 96% | 1,589 |
+| dialogic | GDScript | 84% | 100% | 100% | 3,025 |
+| grpc-proto | Protobuf | 72% | 80% | 92% | 260 |
+| saleor | GraphQL / Python | 72% | 88% | 96% | 27,719 |
+| graphql-code-generator | TypeScript / GraphQL | 72% | 84% | 84% | 3,602 |
+| terraform-aws-components | Terraform / HCL | 68% | 80% | 84% | 14,914 |
+| kubernetes-openapi | OpenAPI / YAML | 64% | 68% | 80% | 4,739 |
+| eu-za-tebe | PHP / CodeIgniter | 60% | 72% | 72% | 5,575 |
+| envoy | Protobuf / C++ | 60% | 60% | 68% | 44,739 |
+| home-manager | Nix | 60% | 72% | 76% | 9,023 |
+| flake-utils | Nix | 60% | 76% | 76% | 50 |
+| kurirfe | JavaScript / Nuxt | 56% | 60% | 64% | 382 |
+| love | C++ / Lua | 52% | 80% | 88% | 26,165 |
+| graphql-engine | GraphQL / Rust / Haskell | 52% | 72% | 80% | 40,417 |
+| maven | XML / Java | 48% | 52% | 56% | 15,284 |
+| jaffle-shop | SQL / dbt | 44% | 80% | 84% | 54 |
+| ecrad | Fortran | 44% | 60% | 64% | 684 |
+| ktor | Kotlin | 44% | 48% | 52% | 11,974 |
+| tokio | Rust | 40% | 60% | 72% | 2,799 |
+| phoenix | Elixir / Phoenix | 36% | 64% | 76% | 1,317 |
+| neovim | Lua / C | 36% | 68% | 80% | 9,514 |
+| kong | Lua / Kong | 36% | 52% | 56% | 4,210 |
+| sqitch | Perl | 36% | 60% | 72% | 1,143 |
+| rabbitmq-server | Erlang | 36% | 48% | 52% | 32,585 |
+| angular-realworld | Angular / TypeScript | 36% | 68% | 72% | 127 |
+| jhipster-sample-app | Angular / TypeScript | 32% | 36% | 48% | 1,302 |
+| godot-demo-projects | GDScript | 32% | 56% | 76% | 3,274 |
+| stripe-openapi | OpenAPI / YAML | 28% | 28% | 28% | 43,078 |
+| listmonk | Go | 28% | 56% | 76% | 966 |
+| serde | Rust | 28% | 40% | 48% | 293 |
+| emqx | Erlang | 28% | 32% | 36% | 43,147 |
+| infisical | React / TypeScript | 8% | 28% | 36% | 27,295 |
+
+The TypeScript/NestJS result (84% P@1, 100% P@3) is the strongest single-project number — NestJS routes and providers map cleanly to the decorator-based extraction in PureContext's framework adapter.
+
+---
+
+## Where PureContext wins clearly
+
+**Framework-aware extraction.** Adapters for NestJS, Terraform, Protobuf, GraphQL, and dbt-style SQL pull domain symbols (routes, resources, services, schemas, models) out as first-class entries rather than relying on generic function/class extraction. This is where the highest P@1 numbers come from.
+
+**Cross-language identifier aliases.** Neovim's C API (`nvim_open_win`) is called from Lua as `vim.api.nvim_open_win`. PureContext stores the Lua alias as an FTS token so semantic queries find the C implementation (36% P@1 on neovim).
+
+**Handler depth where it matters.** Ruby DSL macros (`has_many`, `belongs_to`, `before_action`), Rust impl methods stored as bare names with identity-exact ranking, Erlang functions stored without arity suffix, and ObjC selectors built as `setObject:forKey:` — each lift dynamic-language search precision substantially.
+
+**IaC and schema languages.** Terraform/HCL extraction (resources, modules, variables, outputs) and OpenAPI handler with hyphen-aware regex give PureContext competitive numbers on infrastructure repos that traditional code-search tools miss.
+
+## Where PureContext currently scores low
+
+These are honest gaps, tracked as P1 work:
+
+- **Swift (11% P@1).** Generic type parameters are stripped and protocol types lack semantic summaries. Concept-based queries like *"protocol that describes how application state evolves"* fail to match `Reducer<State, Action>`.
+- **Scala (12% P@1).** Heavily generic types (`ZIO[R, E, A]`, `ZLayer[RIn, E, ROut]`) have no FTS overlap with their semantic descriptions; `given`/`using` instances are not extracted.
+- **Haskell (0% P@1, 16% P@3).** Record types and functions have no docstrings by default; FTS content is name-tokens only. Symbols enter the top-5 (R@5 = 22%) but never rank first.
+- **Objective-C (5% P@1).** The handler was strengthened in 1.5.0 (full `@interface`/`@protocol` extraction and selector building) — numbers will rise on the next benchmark cycle.
+- **Large monorepos with abstract type queries (flutter SDK, novu).** Queries like *"abstract widget that owns mutable state"* don't tokenize against `StatefulWidget` without semantic embeddings on top. Improving this requires summary enrichment, not ranker tweaks.
+
+---
+
+## Token efficiency
+
+PureContext achieves near-100% token reduction versus the naive "read every source file" baseline on every benchmarked project. Token savings are not the main differentiator — what matters is **whether the returned symbols are correct**, which is what the P@1 / P@3 / R@5 numbers above measure.
+
+---
+
+## Reproducing the benchmark
+
+```bash
+git clone https://github.com/goranocokoljic/pure-context
+cd pure-context
+npm install
+npm run build
+npm run benchmark -- --project nestjs-ecommerce-api
+```
+
+Results are written to `benchmarks/<project>/results/purecontext.json`. Ground-truth query sets live in `benchmarks/<project>/queries.json` and can be inspected, extended, or replaced.
+
+---
+
+## Limitations of these numbers
+
+- **25 queries per project is a small sample.** Group averages over multiple projects are more reliable than any single project's score.
+- **Ground-truth queries are biased toward what humans ask AI agents** — symbol lookups by name and short natural-language descriptions. They do not measure agent-driven graph traversal (`get_blast_radius`, `get_call_hierarchy`, etc.), which is where most of the real value in an MCP server shows up in production agent loops.
+- **Numbers reflect PureContext 1.5.0 (May 2026).** Each release shifts results — re-run the benchmark before making decisions on stale data.
+- **Project mix is convenience-sampled.** Projects were selected to cover language and framework breadth, not weighted by GitHub popularity or download counts. Some categories (Web/TypeScript, IaC) are deliberately over-represented; mobile and embedded categories are under-represented.
+
+The full per-project breakdown including symbol counts, indexing speeds, and language-group narratives is generated from the same benchmark runs and lives in the `dev-docs/benchmarks/` directory of the source repository (gitignored from npm releases).

package/FULL-INSTALLATION-GUIDE.md

@@ -0,0 +1,341 @@
+# Installation
+
+
+## Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | >= 18.0.0 | 18, 20, and 22 are tested |
+| npm | >= 9.0.0 | Ships with Node 18+ |
+| Git | any | Required only for `index_repo` (remote repo cloning) |
+
+## Install via npm (recommended)
+
+```bash
+npm install -g purecontext-mcp@latest
+```
+
+After this, `purecontext-mcp` is available as a global command.
+
+If you prefer not to install globally, use `npx` to run without installing:
+
+```bash
+npx purecontext-mcp@latest
+```
+
+`npx` downloads the package on first use and caches it. This is the recommended approach for most AI client integrations because it picks up new versions automatically without a manual upgrade step.
+
+## Prebuilt binaries
+
+PureContext uses `better-sqlite3` for SQLite access. Pre-built native binaries are bundled for:
+
+| Platform | Node 18 | Node 20 | Node 22 |
+|----------|---------|---------|---------|
+| Windows x64 | ✓ | ✓ | ✓ |
+| macOS x64 | ✓ | ✓ | ✓ |
+| macOS arm64 | ✓ | ✓ | ✓ |
+| Linux x64 | ✓ | ✓ | ✓ |
+| Linux arm64 | ✓ | ✓ | ✓ |
+
+When a prebuilt binary matches your platform, `npm install` completes without any native compilation. No Python, no `node-gyp`, no build tools needed.
+
+If your platform/Node combination is not in the table above, `npm install` will attempt a native compile. You will need:
+- Python 3.x
+- A C++ compiler (MSVC on Windows, clang/gcc on macOS/Linux)
+- `node-gyp`: `npm install -g node-gyp`
+
+---
+
+## Connecting to your AI client
+
+PureContext works with any MCP-compatible AI client. Choose the setup that matches your environment.
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add purecontext-mcp -- npx purecontext-mcp@latest
+```
+
+Verify:
+
+```bash
+claude mcp list
+# purecontext-mcp   connected   npx purecontext-mcp
+```
+
+### Claude Desktop
+
+Edit `~/.claude/claude_desktop_config.json` (create it if it doesn't exist):
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "npx",
+      "args": ["purecontext-mcp@latest"]
+    }
+  }
+}
+```
+
+If you installed globally (`npm install -g purecontext-mcp`), you can use the binary directly:
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "purecontext-mcp@latest"
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the file.
+
+### Cursor
+
+Create or edit `.cursor/mcp.json` in your project directory for a project-scoped connection, or `~/.cursor/mcp.json` for a global one:
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "npx",
+      "args": ["purecontext-mcp@latest"]
+    }
+  }
+}
+```
+
+Reload the Cursor window after saving (`Ctrl+Shift+P` → "Developer: Reload Window").
+
+### Windsurf
+
+Open Windsurf Settings and navigate to the MCP section, or edit the MCP configuration file directly:
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "command": "npx",
+      "args": ["purecontext-mcp@latest"]
+    }
+  }
+}
+```
+
+### VS Code (with MCP support)
+
+Create `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "purecontext": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["purecontext-mcp@latest"]
+    }
+  }
+}
+```
+
+### Connecting to a shared team server (HTTP)
+
+If your team runs a shared PureContext server, connect with an HTTP transport instead of launching a local process. The config format is the same across all clients — only the transport section changes:
+
+**Claude Code CLI:**
+
+```bash
+claude mcp add purecontext-shared \
+  --transport http \
+  --url https://purecontext.yourcompany.com/mcp/sse \
+  --header "Authorization: Bearer pctx_yourpersonalkey"
+```
+
+**Claude Desktop / Cursor / Windsurf (config file):**
+
+```json
+{
+  "mcpServers": {
+    "purecontext": {
+      "transport": "http",
+      "url": "https://purecontext.yourcompany.com/mcp/sse",
+      "headers": {
+        "Authorization": "Bearer pctx_yourpersonalkey"
+      }
+    }
+  }
+}
+```
+
+Your API key is issued by your team's PureContext administrator. See [Team Setup](15-team-setup.md) for how to deploy and manage a shared server.
+
+---
+
+## Teaching your AI agent to use PureContext well
+
+Installing PureContext gives your AI agent access to the tools. Adding the agent instructions tells it *how* to use them efficiently — which tool to pick for each situation, in what order to call them, and what patterns to avoid.
+
+Without them, an AI agent given access to PureContext may default to reading entire files (wasting tokens) rather than using `search_symbols`, or may not know to call `list_repos` first to get the `repoId` required by every tool. The instructions encode the correct workflow: check if indexed → search by name or meaning → retrieve source only for what you'll use.
+
+### Recommended: `purecontext-mcp install`
+
+PureContext ships with a multi-IDE installer that writes the workflow rules into the conventions file each tool expects. Run it once inside your project root:
+
+```bash
+npx purecontext-mcp install all
+```
+
+This auto-detects which AI tools are configured in the project (by looking for marker files such as `.cursor/`, `.windsurfrules`, `CLAUDE.md`, `.continue/`, etc.) and installs the rules for each.
+
+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
+npx purecontext-mcp install all --scope=local    # this project only
+npx purecontext-mcp install all --scope=global   # user-level, all projects
+npx purecontext-mcp install all --scope=both     # both places at once
+```
+
+For a single tool:
+
+```bash
+npx purecontext-mcp install cursor --scope=global
+npx purecontext-mcp install windsurf
+npx purecontext-mcp install continue
+# ...etc.
+```
+
+Useful flags:
+
+```bash
+npx purecontext-mcp install --list           # show detection state, write nothing
+npx purecontext-mcp install all --dry-run    # preview which writers would run
+```
+
+### Supported tools
+
+| Tool | Local | Global | Notes |
+|------|-------|--------|-------|
+| `claude` | `CLAUDE.md` in project | `~/.claude/CLAUDE.md` + hooks | Global installs PostToolUse re-index, PreCompact snapshot, and edit guard. |
+| `cursor` | `.cursor/rules/purecontext.mdc` | `~/.cursor/rules/purecontext.mdc` | MDC frontmatter with `alwaysApply: true`. |
+| `windsurf` | `.windsurfrules` | `~/.windsurfrules` | Marked block appended or replaced in place. |
+| `continue` | `.continue/config.json` | `~/.continue/config.json` | JSON-aware merge; other fields are preserved. |
+| `cline` | `.clinerules` | local only | No known global config path. |
+| `roo-code` | `.roo/rules-code.md` | local only | No known global config path. |
+| `vscode` | `.github/copilot-instructions.md` | local only | Picked up by GitHub Copilot in VS Code. |
+| `claude-desktop` | always global | always global | Merges MCP server entry; leaves other servers untouched. |
+
+### Idempotency
+
+Every writer is safe to re-run. The Markdown writers wrap their content in HTML comment markers:
+
+```html
+<!-- purecontext-mcp-start -->
+... PureContext workflow rules ...
+<!-- purecontext-mcp-end -->
+```
+
+On re-run, the marked block is replaced in place. Anything outside the markers (your own rules, other tools' rules) is preserved. The JSON writers (`continue`, `claude-desktop`) parse and merge structurally rather than re-emitting the whole file.
+
+### Manual install (if you'd rather paste)
+
+The two source-of-truth files are at the repository root:
+
+- **`AGENT_INSTRUCTIONS_SHORT.md`** — Compact (~2 KB). Mandatory first step, tool selection table, core rules, common usage patterns. Use for agents with limited system prompt space.
+- **`AGENT_INSTRUCTIONS.md`** — Full (~15 KB). Adds parameter notes, every usage pattern, known limitations, decision trees, anti-patterns. Use for complex multi-step workflows.
+
+To use these manually:
+
+```bash
+# Claude Code
+cat AGENT_INSTRUCTIONS_SHORT.md >> CLAUDE.md
+
+# Cursor — paste into .cursorrules or via Cursor Settings → Rules
+# Windsurf — paste into .windsurfrules or workspace memory
+# Anything else — paste into whatever rule/memory config it supports
+```
+
+---
+
+## Verifying the installation
+
+```bash
+purecontext-mcp --version
+# 1.x.x
+
+purecontext-mcp config --check
+# ✓ Node.js 20.11.0
+# ✓ SQLite (better-sqlite3 9.x)
+# ✓ Grammar: tree-sitter-typescript.wasm
+# ✓ Grammar: tree-sitter-javascript.wasm
+# ... (all 34 grammars)
+# ✓ Config: ~/.purecontext/config.json
+```
+
+`config --check` validates the installation, verifies all grammar files are present, and reports the effective configuration.
+
+## Upgrading
+
+Run the command that matches how you installed PureContext:
+
+**Installed with Volta:**
+```bash
+volta install purecontext-mcp
+```
+
+**Installed with npm globally:**
+```bash
+npm install -g purecontext-mcp@latest
+```
+
+**Running via npx (no global install):** npx may serve a cached older version. Force the latest:
+```bash
+npx purecontext-mcp@latest
+```
+To always get the latest version automatically, use `purecontext-mcp@latest` in your MCP client config instead of the bare package name.
+
+**Installed from source:**
+```bash
+cd /path/to/purecontext-mcp
+git pull
+npm install
+npm run build
+```
+
+> **Note:** `npm update -g purecontext-mcp` does not work reliably — use `npm install -g purecontext-mcp@latest` instead.
+
+Index files (SQLite databases) are forward-compatible within a major version. After upgrading from `1.x` to `1.y`, existing indexes continue to work. A major version upgrade (e.g., `1.x` → `2.0`) may require a re-index — the CLI will warn if it detects an incompatible index version.
+
+## Install from source
+
+Use this when contributing, testing unreleased features, or running a local build.
+
+```bash
+git clone <repository-url> purecontext-mcp
+cd purecontext-mcp
+npm install
+npm run build
+npm link   # makes 'purecontext-mcp' available globally from this build
+```
+
+## Uninstalling
+
+```bash
+npm uninstall -g purecontext-mcp
+```
+
+This removes the binaries. Index files and configuration are not removed. To clean everything up:
+
+```bash
+rm -rf ~/.purecontext   # Removes indexes, config, savings stats
+```

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.
 
@@ -19,11 +20,11 @@ But token savings are the mechanism, not the point. The point is that AI gets be
 
 ```bash
 # 1. Connect to Claude Code (no global install needed)
-claude mcp add purecontext-mcp -- npx purecontext-mcp
+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 install all
+npx purecontext-mcp@latest install all
 ```
 
 Then in a Claude Code conversation:
@@ -36,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
@@ -75,9 +115,7 @@ 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.
 
 ---
 
@@ -223,7 +261,7 @@ Without these instructions, an agent may default to reading entire files rather
 Run this once inside your project directory:
 
 ```bash
-npx purecontext-mcp install all
+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).
@@ -240,22 +278,22 @@ Where should PureContext be installed?
 Pass `--scope` to skip the prompt:
 
 ```bash
-npx purecontext-mcp install all --scope=local    # this project only
-npx purecontext-mcp install all --scope=global   # user-level, all projects
-npx purecontext-mcp install all --scope=both     # both places at once
+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
 ```
 
 For a single tool:
 
 ```bash
-npx purecontext-mcp install <tool> --scope=global
+npx purecontext-mcp@latest install <tool> --scope=global
 ```
 
 To preview without writing files:
 
 ```bash
-npx purecontext-mcp install all --dry-run
-npx purecontext-mcp install --list      # show which IDEs were detected
+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:
@@ -273,9 +311,29 @@ Supported tools and where each one writes:
 
 ### Manual install
 
-If you'd rather paste the rules yourself, two instruction files are at the repository root:
+If you'd rather paste the rules yourself, three instruction files are at the repository root:
 
-- **`AGENT_INSTRUCTIONS_SHORT.md`** — ~2 KB. Mandatory workflow, tool selection table, core rules.
-- **`AGENT_INSTRUCTIONS.md`** — ~15 KB. Adds parameter notes, decision trees, anti-patterns.
+- **[`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)