purecontext-mcp 1.1.1 → 1.1.2

package/docs/dev/PHASE16_TASKS.md

@@ -1,314 +0,0 @@
-# Phase 16 — npm Release Readiness
-
-**Goal**: Ship PureContext MCP as a production-quality npm package that installs cleanly for end users on any platform, any supported Node.js version, without requiring build tools. Bump to v1.0.0.
-
-**Scope rationale**: The project is feature-complete through Phase 15. The single largest blocker to public release is `better-sqlite3`, a native C++ addon that compiles a `.node` binary tied to a specific Node ABI. Users on a different Node version than what was used to build the package see a cryptic "binding not found" error on first run. The fix is prebuilt binaries: build once per target matrix in CI, ship the binaries with the package, and let `node-pre-gyp` pick the right one at install time. Beyond that, the package needs a proper `files` allowlist, a clean prepublish gate, automated GitHub Actions CI, and a semantically versioned v1.0.0 release.
-
-**Target install experience:**
-```bash
-npm install -g purecontext-mcp   # no node-gyp, no Python, no build tools
-purecontext-mcp                  # works immediately
-```
-
----
-
-## Task 119: Prebuilt Binaries for better-sqlite3
-
-Fix the native module distribution problem so `better-sqlite3` works on install without requiring the user to have build tools.
-
-**Root cause**: `better-sqlite3` ships a native `.node` addon compiled against a specific Node ABI version. When the user's Node version differs from the build machine, the addon fails to load. The npm package currently relies on a postinstall compile step which requires Python, node-gyp, and platform build tools — none of which most developers have.
-
-**Approach — prebuild + node-pre-gyp:**
-
-1. Use `@mapbox/node-pre-gyp` to download a prebuilt binary at install time instead of compiling.
-2. Build binaries in CI for the target matrix (Task 120) and upload them to GitHub Releases.
-3. Configure `better-sqlite3`'s `binary` field to point to the GitHub Releases download URL.
-
-However: `better-sqlite3` itself already uses `node-pre-gyp` internally. The cleanest approach is to use [`better-sqlite3-multiple-ciphers`](https://www.npmjs.com/package/better-sqlite3-multiple-ciphers) — no, simpler: use the `better-sqlite3` prebuilt download infrastructure directly by pinning a version that has prebuilds for all target Node versions and adding a postinstall that pulls from their releases.
-
-**Recommended approach — `@vscode/sqlite3` or direct prebuildify:**
-
-Switch to using `prebuildify` to build and bundle binaries directly in the package:
-
-- Add `prebuildify` as a devDependency.
-- Add a `build` npm script: `prebuildify --napi --strip` — builds NAPI-based binaries (NAPI binaries are ABI-stable across Node versions ≥ 6, eliminating the ABI version problem entirely).
-- Add prebuilt binaries for: Node 18, 20, 22 × Windows x64, macOS x64, macOS arm64, Linux x64, Linux arm64.
-- Binaries are committed to `prebuilds/` and shipped inside the npm package via the `files` field.
-- `better-sqlite3` will automatically use the prebuilt binary if found in `prebuilds/`.
-
-**Deliverables:**
-
-- `package.json`:
-  - Add `prebuildify` and `node-gyp` to `devDependencies`.
-  - Add script: `"prebuild": "prebuildify --napi --strip --targets node@18 node@20 node@22"`.
-  - Add script: `"install": "node-pre-gyp install --fallback-to-build || true"` — graceful fallback if prebuilt not available.
-  - Add `prebuilds/` to the `files` array (Task 121 sets this up).
-
-- `.github/workflows/prebuild.yml` (created in Task 120):
-  - Triggered on release tag push.
-  - Matrix: `os: [ubuntu-latest, windows-latest, macos-latest]`.
-  - Each job: `npm run prebuild`, uploads artifacts to the GitHub Release.
-
-- `scripts/check-sqlite.js` (new file):
-  - Runs at the end of install. Attempts `require('better-sqlite3')`. If it fails, prints a clear error message with a link to the GitHub issue tracker and instructions for manual build (`npm run rebuild`).
-  - Exits with code 0 even on failure (so `npm install` does not fail completely).
-
-- `package.json`:
-  - Add `"postinstall": "node scripts/check-sqlite.js"`.
-
-**Verification matrix (must all pass before Task 120):**
-```bash
-# Test locally with nvm
-nvm use 18 && npm install && node -e "require('better-sqlite3')"
-nvm use 20 && npm install && node -e "require('better-sqlite3')"
-nvm use 22 && npm install && node -e "require('better-sqlite3')"
-```
-
-**Tests:**
-
-- `test/core/sqlite-load.test.ts`:
-  - Imports `better-sqlite3` and opens an in-memory database. Assert it loads without error.
-  - Creates a table, inserts a row, selects it back. Assert round-trip works.
-  - This test serves as the canary: if it fails in CI, the binary is broken for that platform.
-
-**Verify:** `npm pack` on each target platform. Install from the tarball (`npm install ./purecontext-mcp-*.tgz`). Run `purecontext-mcp --version`. No compile step occurs.
-
----
-
-## Task 120: GitHub Actions CI Pipeline
-
-Set up automated CI that tests on every push/PR and builds + publishes prebuilt binaries on release tags.
-
-**Deliverables:**
-
-- `.github/workflows/ci.yml`:
-  ```yaml
-  name: CI
-  on: [push, pull_request]
-  jobs:
-    test:
-      strategy:
-        matrix:
-          os: [ubuntu-latest, windows-latest, macos-latest]
-          node: ['18', '20', '22']
-      runs-on: ${{ matrix.os }}
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/setup-node@v4
-          with: { node-version: ${{ matrix.node }} }
-        - run: npm ci
-        - run: npm run build
-        - run: npm test
-  ```
-  - Total: 9 matrix jobs per push (3 OS × 3 Node versions).
-  - Test failures on any combination block the PR.
-
-- `.github/workflows/release.yml`:
-  ```yaml
-  name: Release
-  on:
-    push:
-      tags: ['v*']
-  jobs:
-    prebuild:
-      strategy:
-        matrix:
-          os: [ubuntu-latest, windows-latest, macos-latest]
-      runs-on: ${{ matrix.os }}
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/setup-node@v4
-          with: { node-version: '20', registry-url: 'https://registry.npmjs.org' }
-        - run: npm ci
-        - run: npm run prebuild
-        - uses: actions/upload-release-asset@v1
-          # uploads prebuilt .node files to the GitHub Release
-
-    publish:
-      needs: prebuild
-      runs-on: ubuntu-latest
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/setup-node@v4
-          with: { node-version: '20', registry-url: 'https://registry.npmjs.org' }
-        - run: npm ci
-        - run: npm run build
-        - run: npm publish
-          env: { NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} }
-  ```
-
-- `.github/workflows/benchmarks.yml`:
-  - Runs `npm run bench:purecontext` weekly (cron: `0 6 * * 1`).
-  - Posts benchmark results as a commit comment on the default branch.
-  - Fails if indexing speed regresses > 20% vs baseline in `benchmarks/results/baseline.json`.
-
-- `.github/PULL_REQUEST_TEMPLATE.md`:
-  - Checklist: tests pass, no new lint errors, type-check clean, performance not regressed.
-
-- `README.md`:
-  - Add CI badge: `[![CI](https://github.com/org/purecontext-mcp/actions/workflows/ci.yml/badge.svg)](...)`.
-  - Add npm version badge.
-
-**Key technical notes:**
-- `secrets.NPM_TOKEN` must be set in the GitHub repo settings before the first release.
-- Windows CI catches path separator bugs (forward vs. backslash in file paths) that Linux/macOS tests miss — this is why all 3 OS are in the matrix.
-- The release workflow only runs on `v*` tags. Pushing `v1.0.0` triggers both prebuild and publish automatically.
-
-**Verify:** Open a PR against the repo. All 9 CI jobs pass. Tag `v0.9.0-rc1` and verify the release workflow runs (without actually publishing — use `--dry-run` flag first).
-
-**Tests:** CI itself is the test. Additionally:
-- `test/core/path-normalization.test.ts`: assert all file paths stored in the DB use forward slashes regardless of platform. This is the most common cross-platform bug.
-
----
-
-## Task 121: Package Hygiene — files, exports, prepublish
-
-Ensure only the right files are published to npm. Currently the package has no `files` field — `npm publish` would include test fixtures, benchmark harnesses, docs, and dev tooling, making the package unnecessarily large.
-
-**Current package size estimate (unpacked):** ~50MB (grammars alone are ~15MB, reference/ would be ~20MB if not gitignored, test fixtures ~5MB).
-
-**Target published size:** < 20MB (grammars + compiled JS + UI bundle + prebuilds).
-
-**Deliverables:**
-
-- `package.json`:
-  - Add `files` array (explicit allowlist — safer than `.npmignore`):
-    ```json
-    "files": [
-      "dist/",
-      "grammars/",
-      "prebuilds/",
-      "src/ui/dist/",
-      "scripts/check-sqlite.js"
-    ]
-    ```
-  - Add `"prepublishOnly": "npm run build && npm test"` — prevents publishing broken builds.
-  - Add `"engines"` field (already exists, verify it's accurate):
-    ```json
-    "engines": { "node": ">=18.0.0" }
-    ```
-  - Add `"repository"` field pointing to the GitHub repo.
-  - Add `"bugs"` field with GitHub Issues URL.
-  - Add `"homepage"` field with GitHub repo URL.
-  - Add `"keywords"`: `["mcp", "model-context-protocol", "code-navigation", "tree-sitter", "typescript", "ai", "llm", "claude"]`.
-  - Set `"license": "MIT"`.
-
-- `LICENSE` (new file):
-  - MIT license text with current year and author name.
-
-- `package.json`:
-  - Verify `"bin"` field: `{ "purecontext-mcp": "./dist/index.js" }` — already set, confirm it points to compiled output not source.
-  - Verify `"main"`: `"./dist/index.js"` — already set.
-  - Add `"exports"` field for modern Node module resolution:
-    ```json
-    "exports": {
-      ".": "./dist/index.js",
-      "./package.json": "./package.json"
-    }
-    ```
-
-- `dist/index.js` shebang check:
-  - The entry point must start with `#!/usr/bin/env node` so it's executable as a CLI.
-  - Verify `src/index.ts` has this shebang and that TypeScript preserves it in the output.
-
-- `.npmignore` (as a safety net, even though `files` takes precedence):
-  - List: `src/`, `test/`, `benchmarks/`, `docs/`, `reference/`, `*.ts` (source), `tsconfig.json`, `vitest.config.ts`, `.github/`, `playwright.config.ts`.
-
-- `scripts/verify-package.sh`:
-  - Runs `npm pack --dry-run` and asserts the listed files match the expected set.
-  - Checks that `dist/` exists and is non-empty (build ran).
-  - Checks that `grammars/*.wasm` files are included.
-  - Intended to be run manually before release, not in CI.
-
-**Key technical notes:**
-- `files` in `package.json` is an allowlist: only files matching these patterns are included. Everything else is excluded. `.npmignore` is a denylist and only applies when `files` is absent.
-- The `prebuilds/` directory from Task 119 must be in `files` — it won't be in `dist/`.
-- UI dist output is at `src/ui/dist/` (Vite outputs there) — must be included separately.
-
-**Verify:**
-```bash
-npm pack --dry-run 2>&1 | head -40  # inspect file list
-npm pack                             # create .tgz
-tar -tzf purecontext-mcp-*.tgz | head -30  # verify contents
-```
-Confirm: no `test/`, no `node_modules/`, no `.ts` source files, no `benchmarks/`. Confirm: `dist/`, `grammars/`, `src/ui/dist/` present.
-
-**Tests:**
-- `test/release/package-contents.test.ts`:
-  - Reads the output of `npm pack --dry-run` (or parses a `.tgz`).
-  - Asserts required files are present: `dist/index.js`, `grammars/tree-sitter-typescript.wasm`.
-  - Asserts excluded files are absent: `test/`, `benchmarks/`, `.ts` source files.
-  - Asserts `package.json` has all required fields: `name`, `version`, `bin`, `engines`, `license`, `repository`.
-
----
-
-## Task 122: Version 1.0.0 and CHANGELOG
-
-Bump the version, write a CHANGELOG, and document the public API contract.
-
-**Deliverables:**
-
-- `package.json`:
-  - Bump `"version"` from `"0.1.0"` to `"1.0.0"`.
-
-- `CHANGELOG.md`:
-  - Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
-  - Sections: `[1.0.0] - 2026-xx-xx`, with sub-sections Added / Changed / Fixed.
-  - List all 15 phases as "Added" at a high level (not per-task detail):
-    - Core symbol indexing (TypeScript, JavaScript)
-    - 12+ language support (Python, Go, Rust, Java, C/C++, C#, Swift, Kotlin, Dart, Elixir, Haskell, Scala, R, PHP, Lua, Ruby)
-    - Framework adapters (Vue, Nuxt, React, Next.js, Angular, Express, Fastify, Django, FastAPI, Flask, SQLAlchemy, Prisma, Axum, Actix-web, Echo, Fiber, Gin, Spring, Hibernate)
-    - Dependency graph (blast radius, find importers, dead code detection)
-    - Semantic search (HNSW vector index)
-    - FTS5 keyword search with relevance ranking
-    - Multi-tenant rate limiting
-    - Web UI
-    - Worker thread pool for enterprise repos (10k–50k files)
-
-- `docs/API_STABILITY.md`:
-  - Documents which MCP tool names and parameters are stable (public API contract).
-  - Lists all 12 tools with their stable input/output schemas.
-  - States: "Tool names, required parameters, and top-level response fields will not change in 1.x. Optional parameters and new response fields may be added."
-  - Notes which config fields are stable.
-
-- `README.md`:
-  - Add version badge and "Stable" label.
-  - Add a "What's New in 1.0" section linking to CHANGELOG.
-  - Verify all Quick Start instructions still work against v1.0 (re-test manually).
-
-**Key technical notes:**
-- `1.0.0` signals stability. After this, follow semver strictly: breaking tool API changes → 2.0.0, new tools/fields → 1.x.0, bug fixes → 1.0.x.
-- The CHANGELOG is the document future contributors read to understand the project's history. Write it for humans, not machines.
-
-**Verify:** `purecontext-mcp --version` outputs `1.0.0`. `npm info purecontext-mcp version` returns `1.0.0` after publish. CHANGELOG renders correctly on GitHub.
-
-**Tests:** None for this task (documentation only). The prepublish script in Task 121 acts as the gate.
-
----
-
-## Order of Execution
-
-```
-Task 119: Prebuilt binaries              ████████░░  Critical path blocker
-Task 120: GitHub Actions CI              ████████░░  Required before publish (parallel with 119)
-Task 121: Package hygiene                ██████░░░░  Run after 119 (depends on prebuilds/ dir)
-Task 122: Version 1.0.0 + CHANGELOG      ██░░░░░░░░  Final step (after 119–121 all green)
-```
-
-**Critical path:** 119 + 120 in parallel → 121 → 122 → tag `v1.0.0` → CI publishes automatically.
-
----
-
-## Phase 16 Completion
-
-**Before Phase 16:**
-- `npm install purecontext-mcp` fails for ~60% of users (Node version mismatch with native addon).
-- No CI — broken commits can be pushed.
-- No `files` field — `npm publish` would include ~50MB of tests and benchmarks.
-- Version `0.1.0` signals "not stable".
-
-**After Phase 16:**
-- `npm install -g purecontext-mcp` works on Node 18/20/22, Windows/macOS/Linux, no build tools required.
-- 9-job CI matrix catches regressions before merge.
-- Published package is lean (< 20MB), contains only runtime files.
-- Version `1.0.0` published to npm with public API contract documented.

package/docs/dev/PHASE17_TASKS.md

@@ -1,321 +0,0 @@
-# Phase 17 — Public Launch Polish
-
-**Goal**: Make PureContext production-grade for public users — better error messages, discoverable configuration, telemetry for understanding adoption, and a raised default `fileLimit` with clear documentation. This phase is about the first-hour experience of a new user who installed from npm and is trying to index their project.
-
-**Scope rationale**: Phase 16 ensures the package installs. Phase 17 ensures it works well once installed. The most common failure modes for new users are: (1) hitting the 1000-file limit silently, (2) getting cryptic errors with no actionable message, (3) not knowing what configuration options exist, and (4) us (the maintainers) having no visibility into adoption or which languages/frameworks are actually being used. This phase fixes all four.
-
-**Target first-hour experience:**
-```
-User installs → indexes project → gets helpful output → finds what they need
-If something goes wrong → error message tells them exactly what to fix
-If they hit a limit → they're told they hit it and how to raise it
-```
-
----
-
-## Task 123: Raise fileLimit Default and Enforce it Gracefully
-
-The current default `fileLimit: 1000` is too low for real-world projects and fails silently (indexing stops at 1000 without telling the user).
-
-**Problem**: A typical React/Next.js project has 2000–5000 files after `node_modules` exclusion. A user indexing such a project with default config gets partial results with no warning. This is the most common source of "search doesn't find my file" bug reports.
-
-**Deliverables:**
-
-- `src/config/config-schema.ts`:
-  - Raise default `fileLimit` from `1000` to `10000`.
-  - Add `maxFileSize` config option (default: `512KB`) — files larger than this are skipped during indexing (log at debug level, not silently).
-  - Add `concurrency` config option (default: `Math.min(os.cpus().length, 8)`) — exposes the Phase 15 worker pool setting to users.
-
-- `src/core/index-manager.ts`:
-  - When `fileLimit` is reached during indexing, add a `LimitReachedWarning` to `IndexResult.warnings`:
-    ```
-    fileLimit of 10000 reached — 3241 files were skipped.
-    Raise 'fileLimit' in ~/.purecontext/config.json to index the full project.
-    ```
-  - `IndexResult` already has an `errors` array — add a parallel `warnings: string[]` field.
-  - Log the warning at `warn` level (not just buried in result).
-
-- `src/server/tools/index-repo.ts` (and the `index_folder` MCP tool response):
-  - Include `warnings` from `IndexResult` in the tool response JSON so the AI agent sees them.
-  - Include `filesSkipped` count in the response (how many files were above the limit).
-
-- `src/config/cli.ts` — `config --init` output:
-  - The generated `config.json` should include all options with inline comments explaining each:
-    ```json5
-    {
-      // Maximum number of files to index per project. Raise for large monorepos.
-      "fileLimit": 10000,
-      // Worker threads for parallel parsing. Default: CPU count up to 8.
-      "concurrency": 8,
-      // Additional glob patterns to exclude (on top of node_modules, .git, dist)
-      "excludePatterns": []
-    }
-    ```
-  - Use JSON5 or write a JS config file if inline comments are desired, or use a separate `config.json.example` with comments and write a clean `config.json` without comments.
-
-**Key technical notes:**
-- `10000` is not a hard limit — it's a default. Users can set it to `0` (unlimited) in config. Document this.
-- Files skipped due to `maxFileSize` should be logged at `debug` level only (too noisy at `warn`). Files skipped due to `fileLimit` should be logged at `warn`.
-- The `warnings` field on `IndexResult` should be used for non-fatal issues that affect completeness (limit reached, skipped binary files, parse errors on specific files). Errors are for things that stopped indexing entirely.
-
-**Tests:**
-
-- `test/core/file-limit.test.ts`:
-  - Create a fixture with 15 files. Set `fileLimit: 10`. Index it. Assert `IndexResult.warnings` contains the limit message. Assert `filesSkipped = 5`. Assert only 10 files appear in DB.
-  - Set `fileLimit: 0` (unlimited). Index. Assert all 15 files indexed, no warning.
-  - `maxFileSize: 1` (1 byte) — assert all files skipped due to size, warning emitted.
-
-- `test/config/defaults.test.ts`:
-  - Assert default `fileLimit` is 10000.
-  - Assert default `concurrency` equals `Math.min(os.cpus().length, 8)`.
-  - Assert config validates with no errors on a minimal `{}` config (all fields have defaults).
-
-**Verify:** Index a project with > 1000 files. Confirm no warning appears (default is now 10000). Set `fileLimit: 5` in config. Re-index. Confirm warning appears in tool response and logs.
-
----
-
-## Task 124: Actionable Error Messages
-
-Replace cryptic internal errors with messages that tell users exactly what went wrong and how to fix it.
-
-**Problem**: Current error messages expose internal implementation details or stack traces. Examples observed in test output:
-- `"tries: ['...better_sqlite3.node', ...]"` — means Node version mismatch, but user sees a path list.
-- Parse errors on binary files surface as tree-sitter exceptions.
-- Missing grammar files show a generic module resolution error.
-
-**Deliverables:**
-
-- `src/core/errors.ts`:
-  - Add error classes with `userMessage` and `suggestion` fields:
-    ```typescript
-    class NativeDependencyError extends PureContextError {
-      userMessage = "PureContext could not load its SQLite driver.";
-      suggestion = "This is usually a Node.js version mismatch. Try: npm rebuild better-sqlite3\nIf that fails, please open an issue at https://github.com/org/purecontext-mcp/issues";
-    }
-
-    class GrammarNotFoundError extends PureContextError {
-      userMessage = `Grammar file not found for language: ${language}`;
-      suggestion = "Try reinstalling: npm install -g purecontext-mcp@latest";
-    }
-
-    class ProjectTooLargeError extends PureContextError {
-      userMessage = `Project has ${fileCount} files, which exceeds fileLimit (${limit}).`;
-      suggestion = `Raise fileLimit in ~/.purecontext/config.json:\n  { "fileLimit": ${fileCount + 1000} }`;
-    }
-
-    class ConfigValidationError extends PureContextError {
-      userMessage: string;  // constructed from Zod error details
-      suggestion = "Run 'purecontext-mcp config --check' to validate your config file.";
-    }
-    ```
-
-- `src/index.ts` (entry point):
-  - Top-level error handler: catch any `PureContextError`, print `error.userMessage` and `error.suggestion` to stderr in a formatted box, then exit 1.
-  - Catch non-PureContext errors (unexpected): print "Unexpected error — please report this at [issues URL]" with the stack trace.
-
-- `src/core/db/schema.ts`:
-  - Wrap the `better-sqlite3` require in a try/catch. On failure, throw `NativeDependencyError`.
-
-- `src/server/mcp-server.ts`:
-  - Tool handlers: when a known error is thrown, return it as a structured MCP error response (not a server crash). Include `userMessage` in the MCP error detail.
-
-- `src/config/config-loader.ts`:
-  - Wrap Zod parse errors: instead of exposing Zod's raw error path/message, format as:
-    ```
-    Config error in ~/.purecontext/config.json:
-      fileLimit: Expected number, received string
-    Run 'purecontext-mcp config --check' for full validation.
-    ```
-
-**Key technical notes:**
-- `userMessage` should be a complete sentence readable by a non-expert developer.
-- `suggestion` should be a specific, actionable command or config change — not "see documentation."
-- Never expose internal file paths, stack traces, or node_modules internals in user-facing messages.
-- The top-level error formatter should use a box style for visibility:
-  ```
-  ┌─ PureContext Error ───────────────────────────────────────┐
-  │ Could not load SQLite driver.                              │
-  │                                                           │
-  │ Try: npm rebuild better-sqlite3                           │
-  │ Still broken? https://github.com/org/purecontext-mcp/issues │
-  └───────────────────────────────────────────────────────────┘
-  ```
-
-**Tests:**
-
-- `test/core/error-messages.test.ts`:
-  - `NativeDependencyError` has non-empty `userMessage` and `suggestion`.
-  - `ConfigValidationError` built from a Zod error formats the field path and expected type into a readable sentence.
-  - Top-level handler test: mock a thrown `PureContextError`, capture stderr, assert box format is present.
-  - Tool handler: when `GrammarNotFoundError` thrown, MCP response includes `userMessage` in error detail (not stack trace).
-
-**Verify:** Delete a grammar file. Run `purecontext-mcp`. Assert user sees the formatted error box, not a raw exception.
-
----
-
-## Task 125: `--version` Flag and Startup Diagnostics
-
-Add a `--version` flag and a startup diagnostic mode so users can quickly verify their installation.
-
-**Deliverables:**
-
-- `src/config/cli.ts`:
-  - Add `--version` / `-v` flag: prints `purecontext-mcp 1.0.0` and exits 0.
-  - Add `--health` flag: runs a quick self-check and prints results:
-    ```
-    purecontext-mcp 1.0.0
-    ✓ Node.js 20.11.0 (supported)
-    ✓ better-sqlite3 loaded (prebuilt binary)
-    ✓ Grammars: 15 languages available
-    ✓ Config: ~/.purecontext/config.json (valid)
-    ✓ Index dir: ~/.purecontext/indexes/ (exists, 3 repos indexed)
-    ```
-    If any check fails, show ✗ with the actionable error message from Task 124.
-  - Add the health check to `config --check` output as a preamble.
-
-- `src/index.ts`:
-  - Parse `--version` and `--health` before attempting to start the MCP server.
-  - If neither flag is present and stdin is a TTY (not being piped from Claude), print a startup hint:
-    ```
-    purecontext-mcp v1.0.0 — ready for MCP connections (stdio)
-    Run with --help for usage, --health to verify installation.
-    ```
-    (Suppress this when stdin is piped — don't pollute MCP protocol stream.)
-
-- `src/server/tools/_meta.ts`:
-  - The existing `_meta` tool response: add `serverVersion` field so AI agents can see what version they're connected to.
-
-**Key technical notes:**
-- The startup hint must only print to stderr (or not at all) when stdin is being piped — any stdout output before the MCP server starts will corrupt the stdio protocol stream.
-- `process.stdin.isTTY` is `undefined` when piped, `true` when interactive terminal.
-- The `--health` grammar check should attempt to load each language's WASM grammar (via the parse dispatcher) and report which ones succeed. This catches partial installs.
-
-**Tests:**
-
-- `test/cli/version.test.ts`:
-  - Spawn `purecontext-mcp --version`. Assert stdout contains `1.0.0`. Assert exit code 0.
-  - Spawn `purecontext-mcp --health`. Assert stdout contains all 5 check lines. Assert exit code 0 when everything works.
-  - Mock a missing grammar file. Spawn `--health`. Assert the grammar line shows ✗ and exit code 1.
-
-**Verify:** `purecontext-mcp --version` outputs `purecontext-mcp 1.0.0`. `purecontext-mcp --health` shows all green checks on a clean install.
-
----
-
-## Task 126: Opt-in Telemetry
-
-Add anonymous opt-in telemetry so maintainers can understand which languages, adapters, and features are actually being used in the wild.
-
-**Design principles:**
-- **Opt-in, not opt-out.** No data is sent unless the user explicitly enables it.
-- **No PII.** No file paths, symbol names, repo names, or content. Only aggregate counts and enums.
-- **Transparent.** The exact payload is documented in the README and logged at `debug` level on every send.
-- **Local-only by default.** Telemetry events are batched in a local file and only sent when the user opts in.
-
-**What is collected (when opted in):**
-```json
-{
-  "event": "index_complete",
-  "version": "1.0.0",
-  "nodeVersion": "20.11.0",
-  "platform": "linux",
-  "languages": ["typescript", "javascript"],
-  "adapterNames": ["vue", "nuxt"],
-  "fileCount": 342,
-  "symbolCount": 4821,
-  "durationMs": 1240,
-  "workerCount": 4
-}
-```
-
-**What is never collected:** file paths, symbol names, repo names, source code, user names, IP addresses.
-
-**Deliverables:**
-
-- `src/core/telemetry.ts` (new file):
-  ```typescript
-  export interface TelemetryEvent { event: string; [key: string]: unknown; }
-  export async function track(event: TelemetryEvent): Promise<void>
-  export function isTelemetryEnabled(): boolean
-  ```
-  - Reads `telemetry.enabled` from config (default: `false`).
-  - If disabled: logs at `debug` level what would have been sent, returns immediately.
-  - If enabled: appends event to `~/.purecontext/telemetry.jsonl` (local log always), then sends to the telemetry endpoint (a simple POST to a URL configurable in config, defaults to `https://telemetry.purecontext.dev/v1/event`).
-  - Never throws: wraps all network calls in try/catch, silently discards network errors.
-  - Includes a `sessionId`: random UUID generated once per process start (not persisted — no cross-session tracking).
-
-- `src/config/config-schema.ts`:
-  - Add `telemetry` section:
-    ```typescript
-    telemetry: {
-      enabled: boolean;         // default: false
-      endpoint?: string;        // default: 'https://telemetry.purecontext.dev/v1/event'
-    }
-    ```
-
-- `src/core/index-manager.ts`:
-  - After successful `indexFolder`, call `track({ event: 'index_complete', languages, adapterNames, fileCount, symbolCount, durationMs, workerCount })`.
-
-- `src/server/mcp-server.ts`:
-  - On startup, call `track({ event: 'server_start', version, platform, nodeVersion })`.
-
-- First-run prompt (opt-in mechanism):
-  - `src/config/cli.ts` — `config --init`:
-    - After writing the config file, print:
-      ```
-      Help improve PureContext by sharing anonymous usage stats?
-      This sends only aggregate counts (languages used, file counts, timing).
-      No code, file names, or personal data is ever collected.
-
-      Enable telemetry? (y/N): _
-      ```
-    - If user answers `y`: write `"telemetry": { "enabled": true }` to config.
-    - If `N` or enter: write `"telemetry": { "enabled": false }` to config.
-    - This prompt only appears during `--init`, never again.
-
-- `docs/TELEMETRY.md`:
-  - Documents exactly what is collected, what is not, how to enable/disable, and where data is sent.
-  - Links from README.
-
-**Key technical notes:**
-- The telemetry endpoint (`https://telemetry.purecontext.dev`) does not need to exist for Phase 17 — the `track()` function will simply log to the local file and fail the network request silently.
-- The local `~/.purecontext/telemetry.jsonl` file is always written when telemetry is enabled — this lets the user inspect exactly what is being sent.
-- `isTelemetryEnabled()` must be synchronous (used in conditionals). Config is loaded at startup.
-
-**Tests:**
-
-- `test/core/telemetry.test.ts`:
-  - With `enabled: false`: `track()` does not make any network calls. Logs at debug. Returns immediately.
-  - With `enabled: true` and mocked fetch: `track()` sends POST with correct payload shape. No PII fields present.
-  - Network error: `track()` does not throw, does not affect caller.
-  - Payload never contains file paths or symbol names (even if accidentally passed).
-
-**Verify:** Set `telemetry.enabled: true` in config. Index a project. Inspect `~/.purecontext/telemetry.jsonl`. Assert it contains one `index_complete` event with correct fields. Assert no file paths in payload.
-
----
-
-## Order of Execution
-
-```
-Task 123: Raise fileLimit + warnings      ████░░░░░░  Quick win, most user-visible
-Task 124: Actionable error messages       ████████░░  Core polish (parallel with 123)
-Task 125: --version + health check        ██░░░░░░░░  Independent, fast
-Task 126: Opt-in telemetry                ██████░░░░  After 123/124 (needs config schema)
-```
-
-All four tasks are largely independent. Tasks 123 and 124 are the highest priority — they fix the most common new-user friction. Tasks 125 and 126 can be done in parallel after 123/124.
-
----
-
-## Phase 17 Completion
-
-**Before Phase 17 (new user experience):**
-- Indexes 1000 files silently, user wonders why their symbols are missing.
-- `better-sqlite3` failure shows a path list, user has no idea what to do.
-- No way to check if the installation is working.
-- No visibility into what users actually use.
-
-**After Phase 17:**
-- `fileLimit: 10000` default; clear warning when reached with exact config change needed.
-- Errors show a formatted box with a user message and a specific command to fix.
-- `--health` shows green checkmarks for all components.
-- Opt-in telemetry tells maintainers which languages and adapters to prioritize.