contextpro-mcp 0.0.0-stage → 1.4.0

package/build/tools/test-map.js

@@ -0,0 +1,75 @@
+// Map source files to their test files using import graph and naming conventions
+// FEATURE: TestMap — which tests cover which code
+import { getDB } from "../core/db.js";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { findTestsForFiles, isTestFile } from "./retrieval-helpers.js";
+import { isSupportedFile } from "../core/parser.js";
+const execFileAsync = promisify(execFile);
+async function getChangedFiles(rootDir) {
+    try {
+        const [{ stdout: unstaged }, { stdout: staged }, { stdout: untracked }] = await Promise.all([
+            execFileAsync("git", ["diff", "--name-only"], { cwd: rootDir, timeout: 5000 }),
+            execFileAsync("git", ["diff", "--name-only", "--cached"], { cwd: rootDir, timeout: 5000 }),
+            execFileAsync("git", ["ls-files", "--others", "--exclude-standard"], { cwd: rootDir, timeout: 5000 }),
+        ]);
+        const dirty = [...new Set(`${unstaged}\n${staged}\n${untracked}`.trim().split("\n").filter((l) => l.trim()))]
+            .filter(isSourceTarget);
+        if (dirty.length > 0)
+            return dirty;
+        const { stdout: recent } = await execFileAsync("git", ["diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "HEAD"], { cwd: rootDir, timeout: 5000 });
+        return [...new Set(recent.trim().split("\n").filter((line) => line.trim()))].filter(isSourceTarget);
+    }
+    catch {
+        return [];
+    }
+}
+function isSourceTarget(path) {
+    return !path.startsWith(".contextpro/")
+        && !path.startsWith(".contextplus/")
+        && !isTestFile(path)
+        && isSupportedFile(path);
+}
+export async function getTestMap(options) {
+    const db = await getDB(options.rootDir);
+    let targetFiles = [];
+    if (options.changed) {
+        targetFiles = await getChangedFiles(options.rootDir);
+        targetFiles = targetFiles.filter(isSourceTarget);
+    }
+    else if (options.file) {
+        targetFiles = [options.file];
+    }
+    else if (options.symbol) {
+        const symbols = db.searchSymbolsByName(options.symbol);
+        const fileIds = [...new Set(symbols.map((s) => s.file_id))];
+        const allDbFiles = db.getAllFiles();
+        targetFiles = fileIds.map((id) => allDbFiles.find((f) => f.id === id)?.path).filter(Boolean);
+    }
+    if (targetFiles.length === 0) {
+        return options.changed ? "No changed or recently committed source files to map." : "No target files specified. Use file, symbol, or changed parameter.";
+    }
+    const lines = [`=== Test Map ===`, ""];
+    for (const file of targetFiles) {
+        const allTests = await findTestsForFiles(options.rootDir, [file]);
+        lines.push(`${file}:`);
+        if (allTests.length > 0) {
+            for (const test of allTests) {
+                lines.push(`  → ${test.path} (${test.reason}, ${Math.round(test.score * 100)}%)`);
+            }
+        }
+        else {
+            lines.push("  ⚠ No tests found");
+        }
+        lines.push("");
+    }
+    const totalMapped = targetFiles.length;
+    let withTests = 0;
+    for (const file of targetFiles) {
+        if ((await findTestsForFiles(options.rootDir, [file])).length > 0)
+            withTests++;
+    }
+    lines.push(`Coverage: ${withTests}/${totalMapped} files have tests`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=test-map.js.map

package/build/tools/test-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-map.js","sourceRoot":"","sources":["../../src/tools/test-map.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,26 @@
+# Documentation
+
+## Current guides
+
+| Document | Purpose |
+| --- | --- |
+| [README](../README.md) | Capabilities, quick start and evidence limits |
+| [Install](../INSTALL.md) | Local launch and client configuration; native repair |
+| [Configuration](configuration.md) | Current defaults and optional providers |
+| [Agent guide](../agent-guide.md) | On-demand MCP workflow reference |
+| [Project instructions](../INSTRUCTIONS.md) | Short policy to append to client rules |
+| [Architecture](architecture.md) | Runtime, workers, storage and source boundaries |
+| [Maintenance](maintenance.md) | Builds, validation, documentation checks and cleanup |
+| [Status](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/STATUS.md) | Verified implementation state |
+| [Roadmap](roadmaps/contextpro-roadmap.md) | Remaining work and acceptance gates |
+| [Contributing](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/CONTRIBUTING.md) / [support](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/SUPPORT.md) | Community setup and reporting |
+| [Security](../SECURITY.md) / [conduct](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/CODE_OF_CONDUCT.md) | Trust boundaries and community expectations |
+| [Comparisons](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/docs/comparison.md) | Fair measurements and publication standards |
+| [Releases](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/docs/releasing.md) / [launch checklist](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/docs/launch/checklist.md) | Versioning, publication and visibility gates |
+| [Benchmarks](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/docs/benchmarks/README.md) | Measurements and their methodological limits |
+
+## Historical records
+
+[CHANGELOG](../CHANGELOG.md) retains dated history. Raw benchmark data recorded on private repositories is not published.
+
+`agent-instructions.md` is the tiny MCP manifest hint. `agent-guide.md` is served as `contextpro://instructions`.

package/docs/architecture.md

@@ -0,0 +1,35 @@
+# Runtime architecture
+
+ContextPro runs an MCP stdio server from `src/index.ts`. Each request resolves a verified project/worktree root. `src/tools/register-tools.ts` owns schemas and handlers; `src/core/tool-profile.ts` controls the initial catalog and discovery enables experts for the session.
+
+## Retrieval path
+
+1. Direct `context` targets read bounded current source without search or embeddings. Discovery queries use the index and ranking paths.
+2. Graph-backed tools pass through freshness checks. The walker respects exclusions; fingerprints identify suspicious files, hashes verify content, and coordinated writers repair structural rows.
+3. Retrieval combines lexical evidence with optional existing vectors. Task packets and source slices select bounded evidence and expose omissions rather than pretending selection is exhaustive. Query-based source selection also combines named-identifier text hits with concrete path topics and existing directory prefixes. Bounded interior windows follow exact-name evidence in packing order; no inferred relationship becomes a compiler reference. Exact targets and semantic-only evaluations bypass these lexical hints.
+4. Artifacts and prior packet IDs support reuse. A client must still possess a baseline before requesting a delta.
+
+## Process boundaries
+
+- The MCP parent handles transport, root routing, request bookkeeping and tool dispatch.
+- `parser-process.ts` and `parser-worker.ts` isolate Tree-sitter WASM; regex fallback is lower precision and syntax validation can reject when parsing is unavailable.
+- `typescript-reference-process.ts` and its worker isolate TypeScript language services. Versioned snapshots and project configurations support reuse. References distinguish direct calls, imports, definitions and other occurrences.
+- Embedding and optional chat requests use independent provider configuration. Retrieval deadlines and lexical fallback limit some provider failures; they do not prove every possible native failure is recoverable.
+
+## Storage and freshness
+
+Each project's `.contextpro/index.db` uses SQLite WAL and sqlite-vec. Schema v7 adds ctime to file fingerprints. Source rows, symbols, imports and calls are updated transactionally per file from the same source read. Index generations invalidate derived context. Background watching is backed by periodic reconciliation, which continues after watcher failure.
+
+The directory also holds configuration, memory-related state, artifacts and restore points. It must not be treated as one disposable cache. Native libraries live separately in an ABI-specific user cache. The workspace registry records known projects for routing.
+
+No single operation atomically snapshots every file of an arbitrarily changing worktree. Explicit scope, stale/incomplete warnings and post-edit compiler/tests are part of the evidence contract.
+
+## Evidence and edits
+
+Compiler-resolved TS/JS references, imported SCIP evidence, AST-derived structure and textual/heuristic candidates are distinct. Reflection, unindexed/generated files, runtime injection and other repositories can be outside the returned scope. Imported SCIP revision validation remains planned.
+
+Source mutations check expected revisions, reject disallowed paths/symlinks, serialize project writes and preserve restore points. Multi-file publication can partially succeed and reports recovery details. ContextPro's rename is textual; compiler-backed reference lookup does not turn it into a semantic rename engine.
+
+## Documentation surfaces
+
+`agent-instructions.md` is deliberately tiny because clients can repeat it in tool context. `agent-guide.md` is the on-demand MCP resource. `INSTRUCTIONS.md` is the concise project policy. Raw benchmarks are outside the runtime's normal instruction path.

package/docs/configuration.md

@@ -0,0 +1,178 @@
+# Configuration reference
+
+Defaults below describe this checkout's MCP launch path. Set environment variables in the client that launches the server, then restart it. `src/core/provider-config.ts`, `src/core/tool-profile.ts` and `src/index.ts` are the implementation sources; legacy aliases remain accepted where implemented, but new configurations should use `CONTEXTPRO_*`.
+
+## Profiles
+
+`CONTEXTPRO_TOOL_PROFILE` defaults to `workflow` (14 initial tools). `lean` advertises `context`, `exact_references` and `discover_tools`; `core` includes common editing/graph operations; `full` advertises everything. Existing custom profiles survive `init`. Discovering or enabling tools does not execute them. Enabling returns schemas; hosts without catalog updates can use `discover_tools({root,call:{name,arguments}})` for tools marked `callable` (reads and indexing, never source edits). The target schema and normal request routing still apply. Use `full` for other experts on those hosts.
+
+## Providers
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `CONTEXTPRO_PROVIDER` | `ollama` | Local Ollama or the OpenAI-compatible backend |
+| `CONTEXTPRO_BASE_URL` | `https://api.openai.com/v1` | Compatible endpoint base; ensure it supports the operation requested |
+| `CONTEXTPRO_API_KEY` | unset | Compatible endpoint credential; inject without committing |
+| `CONTEXTPRO_EMBED_MODEL` | `nomic-embed-text:latest` locally; `text-embedding-3-small` for compatible backend | Embedding identity; reindex after changing it |
+| `CONTEXTPRO_CHAT_PROVIDER` | embedding provider | Separate chat backend selection; key/base URL remain shared |
+| `CONTEXTPRO_CHAT_MODEL` | provider fallback when chat is invoked | Optional explicit selection; fallback names are `gemma4:12b` and `gpt-4o-mini`, not a promise of endpoint availability |
+| `CONTEXTPRO_CHAT_RERANK` | off | Opt in to reranking the top eight planning/connected candidates with current bounded source snippets; model call deadline 1.5 seconds, deterministic fallback |
+| `CONTEXTPRO_FEATURE_SUMMARIES` | off | Allow explicit `feature_brief` preparation to generate citation-checked model interpretations; 30-second deadline. Ordinary context discovery only reuses valid cached briefs |
+| `CONTEXTPRO_AUTO_HUBS` | off | Opt in to chat-assisted hub generation during reindex |
+| `OLLAMA_HOST` | `http://127.0.0.1:11434` | Local Ollama endpoint |
+
+Compatible-provider aliases select the same API implementation; an alias does not guarantee that a vendor supports embeddings or a particular model. Check your endpoint's capabilities. Explicit chat operations can use configured credentials and fallback models; an omitted chat-model variable is not a universal disable switch.
+
+Hosted requests can contain source/context material. The coding agent's model usage and ContextPro's optional provider usage are independent. Normal direct source/structural reads do not require chat inference.
+
+For provider-free discovery use `search(preset:"keyword_only")` or direct `context(targets:[...])`. Set `CONTEXTPRO_REINDEX_NO_EMBED=true` or pass `reindex(no_embed:true)` to skip corpus embedding generation; that setting alone does not prohibit query embeddings on a later hybrid search. Memory embedding/search operations have their own provider requirements.
+
+## Indexing and retrieval
+
+| Variable | Launch default | Purpose |
+| --- | --- | --- |
+| `CONTEXTPRO_CONNECTED_CONTEXT` | off | Experimental shared `context`/`task_pack` retrieval: reciprocal-rank fusion, one-hop connected evidence, at most 32 candidate files. Explicit task-pack graph settings override its defaults |
+| `CONTEXTPRO_EMBED_TRACKER` | `lazy` | Start tracking when needed; `eager` starts at boot; `off` disables the background tracker |
+| `CONTEXTPRO_EMBED_TRACKER_DEBOUNCE_MS` | `700` | Debounce changes; tracker helper enforces a 500 ms minimum |
+| `CONTEXTPRO_EMBED_TRACKER_MAX_FILES` | `8` | Per-tick changes, clamped to 5–10 |
+| `CONTEXTPRO_RECONCILE_INTERVAL_MS` | `30000` | Background reconciliation interval, at least 5000 ms; idle scheduling may skip ticks while watching works |
+| `CONTEXTPRO_RECONCILE_MAX_FILES` | `40` | Repair budget per sweep |
+| `CONTEXTPRO_AUTO_REFRESH` | enabled | Pre-query structural freshness gate, including search/context discovery; false leaves warnings and skips automatic maintenance |
+| `CONTEXTPRO_REFRESH` | metadata fast path | Set `hash` to hash every source during quick refresh |
+| `CONTEXTPRO_QUICKREFRESH_MAX_FILES` | `30` | Quick-refresh threshold; the structural gate can fall back to a full structural refresh |
+| `CONTEXTPRO_REINDEX_NO_EMBED` | off | Skip eager corpus embeddings |
+| `CONTEXTPRO_QUERY_EMBED_TIMEOUT_MS` | `1500` | Query-embedding budget, clamped to 100–10000 ms |
+| `CONTEXTPRO_EMBED_BATCH_SIZE` | `32` local / `8` compatible | Inputs per embedding request, clamped to 1–128 |
+| `CONTEXTPRO_EMBED_CHUNK_CHARS` | `2000` | Embedding chunk size, clamped to 256–8000 characters |
+| `CONTEXTPRO_MAX_FILE_SIZE` | `5242880` | Full-reindex source size cap in bytes |
+| `CONTEXTPRO_MAX_EMBED_FILE_SIZE` | `51200` | File embedding size cap in bytes |
+
+Normal refresh compares size, full mtime and ctime, then hashes suspicious files. Hashing and parsing share a verified read. Freshness warnings describe remaining drift or failure, not merely the number of files already repaired. Watcher failure keeps periodic reconciliation alive when the tracker is enabled.
+
+Interactive retrieval reuses existing vectors rather than generating a corpus on demand. A failed query embedding can fall back to keyword ranking; explicit semantic-only requests still need semantic evidence.
+
+Query-based `context` responses include a `source_context` ID. Pass it as
+`previous_context_id` only while holding the complete prior packet. Compatible
+requests return added, changed and removed source ranges. Different roots,
+queries, settings or budgets, missing artifacts and incomplete deliveries recover
+with a full response. Omit the ID after compaction. Exact `targets` remain
+stateless, index-independent reads and reject `previous_context_id`.
+
+The discoverable `feature_brief` expert accepts `query`, optional `refresh`, and
+`max_tokens` (512–12000, default 2000; UTF-8 bytes/4). Its deterministic facts cite
+source ranges. Optional model interpretations are labeled separately; citation
+validation does not verify the claims themselves. Cached briefs validate source
+hashes, dependency membership, generator/model identity and retrieval settings
+(adaptive mode, reranking and embedding identity) before reuse. Neither
+briefs nor deltas imply exhaustive repository coverage. Use `artifact_read` for
+full stored packets. Both experts support compatibility dispatch through
+`discover_tools`; the lean catalog remains three tools.
+
+Local full-text search stores full source for indexed files, so text beyond the
+embedding summary is searchable. This increases the regenerable database size;
+embedding inputs and response budgets remain bounded separately. The extraction
+stamp automatically rebuilds older summary-only indexes on the next structural
+freshness check. Unicode query tokens and phrase matching use that local index.
+Default natural-language `context` discovery considers twelve ranked files before
+packing bounded source ranges; exact identifiers consider four. These candidate
+counts are independent of `max_tokens` and do not imply complete scope coverage.
+
+## Runtime and reporting
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `CONTEXTPRO_NATIVE_AUTO_REPAIR` | `true` | Isolated per-runtime binding repair; npm/network needed for a cache miss |
+| `CONTEXTPRO_NATIVE_CACHE_DIR` | `~/.cache/contextpro/native` | Stable ABI/platform/architecture/libc/dependency cache |
+| `CONTEXTPRO_EFFICIENCY_FOOTER` | `false` | Legacy per-call estimated footer; prefer reporting only when requested |
+| `CONTEXTPRO_PROJECT_ID` | derived | Project identity override |
+| `CONTEXTPRO_CLIENT_ID` | unset | Optional client grouping |
+| `CONTEXTPRO_SESSION_ID` | unset | Session metadata for scoped memory |
+| `CONTEXTPRO_SESSION_SOURCE` | `mcp` | Session source label |
+| `CONTEXTPRO_INSTRUCTIONS_REMOTE` | `false` | Optional trusted remote instructions; bundled guide is the normal path |
+| `CONTEXTPRO_INSTRUCTIONS_REMOTE_URL` | `https://contextpro.dev/api/instructions` | Remote source when enabled |
+| `CONTEXTPRO_ALLOW_UNSAFE_ROOT` | `false` | Override root/home-level root checks; ordinary project roots need no override |
+| `CONTEXTPRO_REFERENCE_HEAP_MB` | `1024` | Reference-worker JavaScript heap ceiling (not preallocated); integer 256–4096, invalid values use 1024; restart the host after changing |
+
+The TypeScript reference worker retains at most one project and releases completed
+compiler graphs between configurations in a monorepo. Single-project queries
+reuse their compiler. Other limits are 60-second idle disposal, a 30-second active
+request deadline and 20,000 input files. Heap exhaustion returns a specific error
+with the configured limit. Parser requests have a 15-second deadline and separate
+queue/source limits. These are not whole-machine resource guarantees.
+
+Query-based `context` in both default and connected modes adds at most eight
+source candidates corroborated by a named identifier and path topics, or an
+existing relative directory prefix plus a topic. Each of up to eight identifier
+hints examines at most 64 local text hits. The shared source collector selects
+bounded interior windows; connected packets remain capped at 32 candidate files.
+These are lexical hints, not binding-resolved references or hard scope filters.
+No additional chat/embedding calls are introduced. Exact target reads remain
+stateless, and semantic-only evaluation bypasses these lexical candidates.
+
+Lexical discovery retains quoted phrases and compound keys, and treats tests and
+translation catalogs as secondary evidence unless requested. SQL files participate
+in source-text search and freshness checks; SQL binding references and structural
+symbol extraction are not provided by this text fallback. Source budgets still
+allow omissions, especially for broad questions spanning many modules.
+
+Discovery includes source under `.github/` and `.maestro/`, including nested app
+directories. Project and nested `.gitignore`/`.contextproignore` rules still
+apply. Other hidden entries, dependency/build directories and symlinks remain
+excluded from discovery; use exact targets for a known source outside that scope.
+
+See [installation](../INSTALL.md) for launch examples and [maintenance](maintenance.md) for test/runtime and disk-cleanup guidance.
+
+## Optional benchmark tracing
+
+`CONTEXTPRO_PROVIDER_TRACE_PATH` optionally records local JSONL events containing
+provider/model identity, call duration, status and provider-reported input/output
+counts. It records no prompts, source or credentials. Missing counts stay null;
+local embeddings commonly report input counts without output counts. These
+events are separate from the coding agent's usage and are not billing estimates.
+
+Set `CONTEXTPRO_TOOL_TRACE_PATH` to an absolute local JSONL path before starting the server. Tracing is off by default and adds no MCP response text. Each event records tool arguments, status, a session/request ID, total server duration, preparation (root verification/freshness/waits), handler execution and postprocessing. Spans can overlap; their sum is not elapsed agent time.
+
+The trace caps each argument payload at 8 KiB and the file at 64 MiB, redacts common credential/content keys and requires a private regular destination file (created with mode 0600). Query strings and paths can still contain private information; keep raw traces local. Write failures are best-effort and produce a stderr warning. A missing or partial trace is unavailable evidence, not zero execution time. See the [benchmark procedure](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/docs/benchmarks/methodology.md).
+## Experimental development context
+
+`contextpro daemon start|status|stop` manages an optional private local compute service. Set `CONTEXTPRO_DAEMON=true` in each MCP process to share freshness/indexing, TypeScript compiler work and configured Python analysis. Build, Node ABI and provider/runtime configuration must match. Incompatibility, crashes and unavailable services fall back to local computation. The service expires after five idle minutes; Windows currently uses local compute because a private Unix socket is required. `CONTEXTPRO_RUNTIME_DIR` overrides the default `~/.contextpro/runtime` directory for isolated installations. Stop a running service using its original build/configuration before upgrading it.
+
+`context` accepts a query-only `intent` hint: `auto`, `lookup`, `change`, `debug`, `review`, or `overview`. Supplying it enables adaptive retrieval for that call. `CONTEXTPRO_ADAPTIVE_CONTEXT=true` enables inferred intent for query calls. Omit both to retain the existing selector. Exact targets remain stateless and reject an intent hint.
+
+Change/debug/review requests reuse the connected evidence retriever for implementations, callers, dependencies and tests. Configuration and contract candidates are labelled by path; these are structural/textual hints, not compiler proof. Missing evidence and output omissions do not establish absence. Response budgets and source delta IDs retain their existing contracts.
+
+These intents also inspect at most twelve matching task-risk candidates lexically and return up to two current records within the existing output budget. Notes cite their memory IDs and remain textual claims. Stale, unverified and superseded risk notes are excluded; unavailable and omitted risk evidence are explicit. Changed notes invalidate context reuse. Ordinary lookup requests do not perform this memory search.
+
+## Verifiable memory and host checks
+
+`memory_record_task` accepts `source_evidence: [{file, hash?, start?, end?}]`, `supersedes: [memory_id]` and `validation_refs: [artifact_id]`. Source references capture whole-file SHA-256 hashes, the canonical worktree root and Git revision, plus configuration and dependency-manifest evidence. Existing `files` also bind source evidence; deleted legacy file references remain recordable as explicitly unverified. Explicit structured references reject unavailable files and invalid line ranges. Each task record is immutable history: recording the same task again creates another record. Explicit supersession preserves the old record and its evidence.
+
+Retrieval labels records `current`, `stale`, `unverified` or `superseded`. Stale and superseded conclusions do not enter automatic task recommendations. Manual memory search/listing retains them, with lexical fallback when embeddings are unavailable. Legacy records migrate logically as `unverified`; no destructive migration is required. A returned `handoff` artifact contains completed work, remaining risks, assumptions, source references and validation state. Read it through `artifact_read`; current source/supersession and validation applicability are rechecked alongside the historical payload.
+
+Referenced validation receipts also affect task-memory applicability: a stale receipt makes its conclusion stale, and an unavailable receipt makes it unverified. A current source hash alone does not renew an old validation conclusion.
+
+Call `validate_scope` after edits and before running checks. Its snapshot covers ignore-aware workspace files, configuration and manifests; ignored dependencies, build outputs and unsaved buffers are outside that snapshot. Run checks in the coding host, then call `validation_record({root, snapshot_id, command, exit_code, runtime, evidence?})`. Results are explicitly host-reported. Source/configuration/membership/revision changes invalidate applicability; recommended commands never count as executed checks. Snapshots cap at 20,000 files and fail rather than silently truncate evidence.
+
+Evidence snapshots include authored hidden files and directories, including `.eslintrc.json` and `.babelrc`, while honoring nested ignore rules, dependency/cache exclusions and symlink protections. Their contents are hashed, not copied into the evidence record. Configuration-bound memory and rename previews use the same policy. Older snapshots that omitted these inputs become stale when compared with the expanded inventory; take a new snapshot and rerun the checks.
+
+Rollback: previous builds ignore the additive metadata/artifacts. Retain records for inspection; do not infer that an older build validates them. Writes require an enabled specialist tool or the full profile; the discovery dispatcher does not execute memory/validation writes.
+
+## Local teamwork
+
+Discover `team_status` and `team_task` when coordination is needed. The three-tool lean catalog is unchanged. `team_status` shows dependencies, ready task IDs, ownership, expiry and recent history. `team_task` supports `create`, `update`, `claim`, `renew`, `release`, `block`, `complete` and `handoff`. Claims require an explicit `owner`; individual-file leases expire after five minutes and must be renewed while working. Dependency cycles and incomplete prerequisites reject claims. A same-worktree file conflict fails atomically; overlap in another worktree returns a warning. Leases are advisory and do not prevent external editors from writing.
+
+The SQLite ledger lives under `~/.contextpro/teams`, keyed by canonical Git common directory (canonical root outside Git). `CONTEXTPRO_TEAM_DIR` permits isolated test installations. Expired ownership is reclaimable, with tasks, events and handoff links retained. `handoff_id` links an existing handoff artifact from that worktree. ContextPro never spawns agents or sends messages. To roll back, stop invoking the tools and retain the independent ledger; existing source indexes are unchanged.
+
+Each event retains its task/lease/handoff snapshot in `details`, so a later handoff does not erase earlier references. Inspect a task with `team_status({task_id})`; paginate with `before_event_id: olderEventsBefore` and optional `event_limit` (1–50, default 20). Existing ledgers receive an additive `details` column; old events have empty details and remain readable by previous builds.
+
+## Compiler diagnostics and rename
+
+Discover `compiler_diagnostics({root,files})` for TypeScript/JavaScript or configured Python diagnostics. TypeScript reuses the bounded compiler worker. For Python, set `CONTEXTPRO_PYRIGHT_COMMAND` to an installed `pyright-langserver` executable; ContextPro invokes it with `--stdio`, without shell execution or runtime downloads. Integration tests pin MIT-licensed Pyright `1.1.414`. `CONTEXTPRO_PYTHON_PATH` optionally specifies an interpreter; normal `pyrightconfig.json` / `pyproject.toml` settings, including virtual environments, apply. Python sessions cap at two canonical roots, serialize a bounded queue, use a 1 GiB JavaScript heap limit and expire after 60 idle seconds. Unconfigured Python exact references retain explicitly labelled heuristic/SCIP evidence; configured LSP errors do not silently turn into heuristic success.
+
+For compiler-backed edits, request `rename_preview({root,file,line,column,new_name,max_tokens?})` using one-based positions. Inspect its immutable artifact and then invoke `rename_apply({root,preview_id})`. TS/JS uses compiler rename locations (including alias prefix/suffix edits); Python uses Pyright's prepare/rename operations. Unsupported operations reject. Apply verifies workspace membership, revision and every affected file hash, creates a restore point, and publishes only the previewed edits. Limits are 100 files, 5,000 edits and an 8 MiB artifact. A concurrent outside writer can still cause partial publication; the error identifies completed files and the restore point. Run diagnostics/tests after application: a compiler-generated rename is not proof of behavioral correctness.
+
+The older `rename_symbol` remains an explicitly textual compatibility tool. It is never a silent fallback for `rename_apply`. Rollback: unset Python configuration and stop using the added specialist tools; source restoration uses the returned restore point. Stop the shared service before rebuilding, then restart it with matching build, parser/compiler dependencies, Node ABI and environment. Shared compute remains opt-in.
+
+Python cache identity includes the configured executable, npm Pyright package/server content and version, interpreter setting, relevant configuration and dependency manifests. Installation or manifest changes restart the session. Shared-service compatibility also includes the configured Python installation identity.
+
+Each Python operation checks the hashes and membership of ignore-aware workspace `.py` and `.pyi` files, not only the requested files. Changes notify Pyright and advance requested document versions so diagnostics must reflect refreshed imports; deleted imports also lose any old open-document overlay. The freshness inventory caps at 20,000 files, requested open files at 1,000, and existing operation deadlines still apply. Ignored dependency installations and external source trees remain outside this inventory.

package/docs/maintenance.md

@@ -0,0 +1,77 @@
+# Maintenance and cleanup
+
+## Build and validate
+
+The package uses an npm lockfile. Use Node to launch MCP and the same executable across clients where possible. The full test suite also needs Git and ripgrep (`rg`) for its offline native-search baseline; see [contributor setup](https://github.com/AlaeddineMessadi/contextpro-mcp/blob/main/CONTRIBUTING.md#development-setup).
+
+```sh
+npm ci
+npm run build
+npm test
+npm run docs:check
+npm pack --dry-run
+```
+
+If tests use temporary HOME directories and Node differs from the shared native installation, pin the existing isolated cache explicitly:
+
+```sh
+CONTEXTPRO_NATIVE_CACHE_DIR="$HOME/.cache/contextpro/native" npm test
+```
+
+Repair a missing compatible cache with the failing runtime's `doctor --fix`; do not rebuild shared native modules for one client. `test:demo` and `test:all` include optional demo/provider scenarios; inspect their requirements before running them. The maintained `test/main/` suite replaces the removed one-off `scripts/autonomous-verify.mjs` audit probe.
+
+Direct imports of built tool modules inherit the shell environment, not the MCP client's configuration. When validating a real project, use the client's provider/model settings as well as its Node runtime: a different model identity can clear regenerable vectors. Prefer temporary fixtures for isolated probes.
+
+## Recover semantic search
+
+A fresh structural index means files, symbols and imports are current. Automatic
+query refreshes intentionally skip corpus embeddings. They do not populate a
+missing semantic index. A semantic rebuild under a different provider/model
+invalidates incompatible vectors, including when the models share a dimension.
+Structural-only refreshes preserve the existing vector-space identity; workers
+with a different model use lexical evidence instead of comparing incompatible vectors.
+
+Use the same intended embedding provider/model in each client. Inspect
+`status({root:"/absolute/project/root",format:"json"})`: check `embeddings`,
+including the stored model, stale reason, counts, skipped flag and last error.
+With that provider available, run
+`reindex({root:"/absolute/project/root",no_embed:false,auto_hubs:false})`.
+Also unset `CONTEXTPRO_REINDEX_NO_EMBED`, which overrides the argument.
+In the lean catalog, discover the current schema with
+`discover_tools({root:"/absolute/project/root",enable:["status","reindex"]})`;
+if the client does not refresh its catalog, execute through
+`discover_tools({root:"/absolute/project/root",call:{name:"reindex",arguments:{no_embed:false,auto_hubs:false}}})`.
+
+Rebuild each affected project/worktree once. Large local corpora can take several
+minutes. If a client times out, check status for an ongoing rebuild before starting
+another one. After completion, verify nonzero file/identifier vectors, no stale
+flag or embedding error, and replay a representative query. A weak semantic match
+with healthy vectors alone is not a reason to rebuild. Existing MCP processes need
+reconnecting to load new server code or changed client model settings.
+
+## Documentation source of truth
+
+- `README.md`: concise entry point; link to detailed guides instead of repeating every environment setting.
+- `INSTALL.md` and `docs/configuration.md`: launch/setup and current defaults.
+- `agent-instructions.md`: tiny manifest hint; keep it under the existing regression-test limit.
+- `agent-guide.md`: detailed MCP instructions resource.
+- `INSTRUCTIONS.md`: project policy.
+- `STATUS.md` / roadmap: current state and pending work. Historical results belong in dated reports.
+
+`npm run docs:check` verifies local links in current documentation.
+
+Keep `AGENTS.md` and `CLAUDE.md` aligned with the managed template in `src/core/agent-setup.ts` if changing the installer policy. Never expand the manifest into the full guide merely for convenience.
+
+## What can be removed
+
+| Path/data | Cleanup rule |
+| --- | --- |
+| `.DS_Store`, temporary logs, `*.tsbuildinfo` | Regenerable metadata; remove when not needed for diagnosis |
+| `build/` | Rebuildable, but live MCP workers load files here; stop clients before deleting |
+| `graft/` | Regenerable structural index; keep it while active agents use it |
+| `node_modules/` | Reinstallable, but active clients/apps depend on it; do not purge |
+| `.contextpro/` | **Mixed durable state and caches. Do not delete wholesale.** Inspect artifacts, memory, configuration and restore points separately |
+| `~/.cache/contextpro/native` | Shared per-runtime native bindings; removing live runtimes' entries can break clients or force repairs |
+| Dated benchmark JSON | Retain evidence; old paths in raw records are historical observations |
+
+Use the `gc` tool's own current schema and inspect its result when reclaiming supported artifacts/restore points. Do not infer that every old file is safe to delete.

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "contextpro-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Local-first MCP code intelligence: bounded source context, exact references, and evidence-aware coding workflows.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlaeddineMessadi/contextpro-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlaeddineMessadi/contextpro-mcp/issues"
+  },
+  "homepage": "https://github.com/AlaeddineMessadi/contextpro-mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-intelligence",
+    "coding-agent",
+    "semantic-search",
+    "scip",
+    "lsp",
+    "rag"
+  ],
+  "engines": {
+    "node": ">=20 <27"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "INSTALL.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "SECURITY.md",
+    "INSTRUCTIONS.md",
+    "agent-instructions.md",
+    "agent-guide.md",
+    "docs/configuration.md",
+    "docs/architecture.md",
+    "docs/maintenance.md"
+  ],
+  "bin": {
+    "contextpro-mcp": "./build/index.js",
+    "contextpro": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "prepack": "npm run build",
+    "pack:dry": "npm pack --dry-run",
+    "pretest": "npm run build",
+    "test": "node --test test/main/*.test.mjs",
+    "test:demo": "node --test test/demo/*.demo.mjs",
+    "test:all": "node --test test/main/*.test.mjs test/demo/*.demo.mjs",
+    "typecheck": "tsc --noEmit",
+    "bench:retrieval": "npm run build && node scripts/benchmark-retrieval.mjs",
+    "docs:check": "node scripts/check-docs.mjs",
+    "release:check": "node scripts/check-release.mjs",
+    "pack:check": "node scripts/check-package.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "better-sqlite3": "^12.10.0",
+    "ignore": "^7.0.14",
+    "ml-matrix": "^6.15.1",
+    "ollama": "^0.6.4",
+    "p-limit": "^7.3.3",
+    "sqlite-vec": "^0.1.9",
+    "tree-sitter-wasms": "^0.1.13",
+    "typescript": "^5.9.3",
+    "vscode-jsonrpc": "10.0.0",
+    "web-tree-sitter": "^0.20.8",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^26.6.5",
+    "pyright": "1.1.414"
+  }
+}