purecontext-mcp 1.5.0 → 1.5.2

package/USER-GUIDE.md

@@ -2,47 +2,47 @@
 
 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
 
 ---
 
@@ -56,7 +56,7 @@ For parameter-level documentation — every tool input, output, and flag — see
 
 ## 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
 
 ---
 
@@ -64,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/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.5.0";
+export declare const VERSION = "1.5.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '1.5.0';
+export const VERSION = '1.5.2';
 //# sourceMappingURL=version.js.map

package/docs/02-installation.md

@@ -1,5 +1,10 @@
-# Installation
+# Installation — Reference
 
+This is the reference page for installation: prerequisites, prebuilt-binary support matrix, verification commands, and upgrade paths.
+
+For the **user-friendly walkthrough** — per-IDE setup, agent-instructions installer, team server connection — see [`FULL-INSTALLATION-GUIDE.md`](../FULL-INSTALLATION-GUIDE.md) at the project root.
+
+---
 
 ## Prerequisites
 
@@ -7,357 +12,78 @@
 |-------------|---------|-------|
 | 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) |
+| Git | any | Required only for `index_repo` (cloning remote repositories) |
 
-## Install via npm (recommended)
-
-```bash
-npm install -g purecontext-mcp
-```
-
-After this, `purecontext-mcp` is available as a global command.
+---
 
-If you prefer not to install globally, use `npx` to run without installing:
+## Install commands
 
 ```bash
-npx purecontext-mcp
+# Recommended: run via npx (no global install needed)
+npx purecontext-mcp@latest
+
+# Or install globally
+npm install -g 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.
+The `@latest` tag is recommended in AI-client configurations so new versions are picked up without manual upgrade steps.
+
+---
 
-## Prebuilt binaries
+## Prebuilt binary support matrix
 
-PureContext uses `better-sqlite3` for SQLite access. Pre-built native binaries are bundled for:
+`better-sqlite3` is the only native dependency. Prebuilt 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
-```
-
-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"]
-    }
-  }
-}
-```
-
-If you installed globally (`npm install -g purecontext-mcp`), you can use the binary directly:
-
-```json
-{
-  "mcpServers": {
-    "purecontext": {
-      "command": "purecontext-mcp"
-    }
-  }
-}
-```
-
-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"]
-    }
-  }
-}
-```
-
-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"]
-    }
-  }
-}
-```
-
-### VS Code (with MCP support)
-
-Create `.vscode/mcp.json` in your project:
-
-```json
-{
-  "servers": {
-    "purecontext": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["purecontext-mcp"]
-    }
-  }
-}
-```
-
-### 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.
+When your platform matches a row above, `npm install` completes with zero native compilation. For unsupported combinations, `npm install` falls back to a source build, which requires Python 3.x, a C++ toolchain, and `node-gyp`.
 
 ---
 
-## 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 registers seven hook events — see [Claude Code hooks](#claude-code-hooks) below. |
-| `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. |
-
-### Claude Code hooks
-
-When you run `npx purecontext-mcp install claude` (or the standalone `npx purecontext-mcp hooks --install`), PureContext registers seven hook events in `~/.claude/settings.json`. Each hook is a CLI-style command — no scripts are copied to `~/.claude/hooks/`; the hook logic lives inside the installed package and updates automatically when you upgrade.
-
-| Hook event | Command | What it does |
-|------------|---------|--------------|
-| `PostToolUse` | `hook-posttooluse` | Re-indexes files modified by Edit/Write/MultiEdit |
-| `PreToolUse` | `hook-pretooluse` | Soft edit guard — suggests read tools before editing unread files |
-| `PreCompact` | `hook-precompact` | Injects the list of indexed repos before context is compacted |
-| `WorktreeCreate` | `hook-worktree-create` | Auto-indexes a newly created agent worktree |
-| `WorktreeRemove` | `hook-worktree-remove` | Fires when an agent worktree is removed (reserved for cleanup) |
-| `TaskCompleted` | `hook-taskcompleted` | Post-task diagnostics: complexity hotspots, TODO count, suggested tools |
-| `SubagentStart` | `hook-subagentstart` | Injects a condensed repo orientation for newly spawned subagents |
-
-Running `hooks --install` more than once is safe. It replaces existing PureContext entries (including old `.mjs`-path style entries from versions prior to 1.8.0) while leaving other tools' hooks untouched.
-
-To see the current registration status without making changes:
-
-```bash
-npx purecontext-mcp hooks --list
-```
-
-### 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
+## Verification
 
 ```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.
+`config --check` validates the install: confirms Node and SQLite versions, verifies all 34 grammar WASM files load, and reports the effective configuration.
 
-**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.
+## Upgrade matrix
 
-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.
+| How you installed | Command to upgrade |
+|-------------------|--------------------|
+| Volta | `volta install purecontext-mcp` |
+| npm global | `npm install -g purecontext-mcp@latest` |
+| npx (cached) | `npx purecontext-mcp@latest` (forces a fresh fetch) |
+| Source / clone | `git pull && npm install && npm run build` |
 
-## Install from source
+> `npm update -g` is not reliable for this package — use `npm install -g ...@latest`.
 
-Use this when contributing, testing unreleased features, or running a local build.
+**Index compatibility:** SQLite indexes are forward-compatible within a major version (`1.x` → `1.y` keeps existing indexes). Major upgrades (`1.x` → `2.0`) may require a re-index; the CLI warns when it detects an incompatible index.
 
-```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
+## Uninstall
 
 ```bash
 npm uninstall -g purecontext-mcp
+rm -rf ~/.purecontext   # removes indexes, config, savings stats
 ```
 
-This removes the binaries. Index files and configuration are not removed. To clean everything up:
+---
 
-```bash
-rm -rf ~/.purecontext   # Removes indexes, config, savings stats
-```
+## Related reference
+
+- [Configuration](04-configuration.md) — full `config.json` schema and environment variable overrides
+- [CLI Reference](05-cli-reference.md) — every command and flag
+- [Transport Modes](14-transport-modes.md) — stdio vs HTTP/SSE deployment
+- [Team Setup & Multi-Tenant](15-team-setup.md) — reference for shared-server config