devworkspace 0.3.3 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,59 @@
 
 All notable changes are documented here. This project follows [Semantic Versioning](https://semver.org/). Workspace schema changes are called out under **Breaking**.
 
+## [0.4.1] - 2026-11-03
+
+### Fixed
+- **Integration Test Reliability in Clean Environments**:
+  - Automatically compile the CLI on-demand (`ensureCliBuilt`) in `tests/integration/mcp-stdio.test.ts` when running in clean CI runners or coverage workflows where `dist/cli/main.js` has not yet been built.
+- **Documentation & Onboarding Clarity**:
+  - Rewrote `README.md` with a plain-English mental model, architecture flowchart, beginner-friendly quick start, and explicit separation of traditional file instructions from MCP integration.
+  - Documented tool invocation semantics, testing scope disclaimers, and system `PATH` configuration requirements.
+
+## [0.4.0] - 2026-11-03
+
+### Added
+- **Model Context Protocol (MCP) Server (`devworkspace mcp serve`)**:
+  - Implemented local-first Model Context Protocol (MCP 2024-11-05) server running strictly over stdio with zero runtime dependencies.
+  - Zero open network ports, zero external telemetry or cloud dependencies, and complete offline execution.
+  - Fully implements the MCP lifecycle: enforces initialization handshake (`initialize` -> `notifications/initialized`) before serving general tool requests, with clean rejection code `-32600` (`INVALID_REQUEST`) for uninitialized requests.
+  - Robust stdio transport supporting single-settle promise resolution, clean shutdown, and graceful stdin error/EPIPE handling.
+- **Deterministic MCP Context Tools**:
+  - `get_project_overview`: Summarizes repository architecture, detected language stack, UI/backend frameworks, context health, and verification capabilities.
+  - `get_task_context`: Generates progressive, role-sliced context (`explorer`, `tester`, `reviewer`) with deterministic keyword retrieval, ADR matching, and mandatory safety rule retention.
+  - `get_file_context`: Exposes workspace-relative file contents bounded to 32KB per call with associated DevWorkspace knowledge facts.
+- **AI Coding Agent Setup (`devworkspace mcp setup` / `devworkspace setup --agent`)**:
+  - Automated configuration generator for **Claude Code** (`.mcp.json` and `CLAUDE.md`), **OpenAI Codex** (`mcp.json` and `AGENTS.md`), and **Google Antigravity** (`.antigravity/mcp.json` and `.antigravity/rules`).
+  - Supports `--check` dry-run mode for previewing configuration changes without modifying disk.
+  - Dedicated MCP section markers (`<!-- devworkspace-mcp:start -->` / `<!-- devworkspace-mcp:end -->`) guaranteeing complete coexistence with standard agent instructions (`devworkspace agent install`), preserving custom user content byte-for-byte, and seamlessly migrating legacy MCP blocks.
+- **Security Boundaries & Defense-in-Depth Protections**:
+  - Strict workspace-root enforcement (`resolveInside`, `assertNoSymlinkEscape`) blocking path traversal (`..`), absolute paths, and symlink escapes.
+  - Secret file exclusion policy refusing credentials, environment files (`.env*`), private keys, tokens, and keystores.
+  - Automatic pattern-based secret redaction masking credentials (`[REDACTED:<type>]`) in returned source context.
+  - Prompt-injection resistance demarcating retrieved content with `=== BEGIN UNTRUSTED DEVWORKSPACE CONTEXT ===` delimiters.
+- **Documentation & Verification Suite**:
+  - Added comprehensive MCP architecture and security documentation in `docs/mcp.md` and updated `docs/agents.md` and `README.md`.
+  - Added unit test suites (`tests/unit/mcp.test.ts`, `tests/unit/mcp-setup.test.ts`) and subprocess stdio integration test (`tests/integration/mcp-stdio.test.ts`).
+  - Added CLI smoke tests in `scripts/smoke.mjs` verifying help texts and check modes.
+
+## [0.3.4] - 2026-11-03
+
+### Added
+- **Deterministic Context Accuracy Evaluation Framework (`npm run eval:accuracy`)**:
+  - Introduced offline, zero-dependency benchmark engine and dataset in `scripts/eval/` covering 10 engineering archetypes across 4 context roles (`default`, `explorer`, `tester`, `reviewer`).
+  - Evaluates mathematical precision, recall, F1-score, 100% safety-retention, verification coverage, and byte/token payload efficiency against ground-truth facts, decisions, and checks.
+  - Automated CI integration tests in `tests/integration/context-accuracy.test.ts` to prevent context retrieval regressions.
+- **Semantic Retrieval & Terminology Normalization**:
+  - Deterministic word stemming (`normalizeStem`) handling standard English inflectional suffixes (`-ies`, `-es`, `-s`, `-ing`, `-tion`, `-ed`).
+  - Explicit engineering domain synonym clusters (`DOMAIN_SYNONYMS`) bridging common developer terminology to repository facts for database schema, migrations, ORM, SQL, auth, tenancy, billing precision, REST APIs, and UI pagination.
+- **Structural Path Guard & Package-Scoped Context Selection**:
+  - Excludes generic code structural suffixes and directory names (`PATH_STRUCTURAL_TERMS`: `backend`, `frontend`, `service`, `controller`, `dto`, `worker`, etc.) from source file path matching to eliminate false-positive fact retrieval collisions across unrelated modules.
+  - Detects single-package targets (`backend` vs `frontend`) and suppresses cross-package noise facts and global layout dumps while preserving safety rules and verification contracts.
+  - Accurately preserves cross-package context for multi-package monorepo tasks.
+- **Enhanced Architectural Decision (ADR) Matching**:
+  - Matches prompt queries against complete decision content including titles, context, decisions, consequences, and file references.
+  - Filtered through weak-keyword suppressors (`WEAK_TERMS`) to prevent false-positive ADR collisions on generic words like `error`, `check`, or `data`.
+
 ## [0.3.3] - 2026-11-03
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # DevWorkspace
 
-A **project-local AI engineering layer** for existing repositories. DevWorkspace gives an AI coding agent (Claude Code first) a small, portable, evidence-backed memory of your project, a task and verification discipline, and safety rails, without moving your project, creating an account, or needing an API key.
+DevWorkspace is a **local-first engineering memory and verification layer** for software repositories. It provides AI coding agents (such as Claude Code, OpenAI Codex, Cursor, GitHub Copilot, and Google Antigravity) with a small, evidence-backed model of your project's architecture, verification commands, and safety boundaries—without sending your code to a third-party service, creating an account, or requiring an API key.
 
 ```bash
 cd my-project
@@ -8,138 +8,268 @@ npx devworkspace init
 npx devworkspace analyze
 ```
 
-## What problem does it solve?
+---
 
-AI coding sessions start cold. The agent re-discovers your architecture, re-reads the same files, forgets decisions, runs the wrong tests, and sometimes declares victory while the build is red. DevWorkspace stores *knowledge* (not code) in `.devworkspace/`, keeps it honest (provenance, confidence, staleness), and installs a thin set of instructions that make the agent load context progressively, classify work, verify it, and update memory sparingly.
+## What Problem Does It Solve?
 
-## What it is not
+AI coding sessions start cold. Agents repeatedly re-read the same directory trees, infer incorrect architectural assumptions, forget past decisions, run the wrong test suites, or claim tasks are complete while the build is failing.
 
-DevWorkspace is not an LLM, an IDE, a Git client, a vector database, a code-graph engine, a test framework, a model router, or a cloud service. It orchestrates tools that already exist:
+DevWorkspace solves this by:
+1. **Storing durable knowledge, not code:** Captures facts, decisions, and verification contracts in `.devworkspace/`.
+2. **Keeping context honest:** Tracks evidence sources, confidence ratings, and staleness so outdated assumptions are flagged.
+3. **Establishing operating rules:** Injects progressive context loading, Git safety rules (preventing destructive resets), and verification gates into agent workflows.
 
-| Concern | Provided by |
-| --- | --- |
-| Structural code understanding | [Graphify](https://github.com/Graphify-Labs/graphify) |
-| Engineering workflows (spec, plan, build, test, review, ship) | [Agent Skills](https://github.com/addyosmani/agent-skills) |
-| Quality, simplification, debt review | [Ponytail](https://github.com/DietrichGebert/ponytail) |
-| Model routing (optional, not used in V1) | [OmniRoute](https://github.com/diegosouzapw/OmniRoute) |
-| Correctness | **Your tests** |
+---
 
-DevWorkspace decides *when and why* a workflow applies. Those projects provide *how*.
+## How It Works
 
-## Requirements
+```mermaid
+flowchart LR
+  subgraph Local ["Your Local Machine"]
+    Repo["Repository Code & Manifests"] --> DW["DevWorkspace (.devworkspace/)"]
+    DW -->|"MCP stdio tools"| Agent["AI Coding Agent"]
+    DW -->|"Markdown instructions"| Agent
+    Agent -->|"Execute verification"| Gate["Tests, Lint & Typecheck"]
+  end
+  subgraph Cloud ["External AI Provider"]
+    Agent -.->|"Context in prompts"| Model["Cloud LLM (Anthropic / OpenAI / Google)"]
+  end
+```
+
+1. **Discover & Record:** Reads package manifests, configs, and file structure offline to construct a deterministic testing contract (`commands.json`) and discovery report.
+2. **Equip the Agent:** Exposes project context either via the local **Model Context Protocol (MCP)** server or via **file-based instruction blocks** (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`).
+3. **Enforce Verification:** Holds the agent accountable to your real test suites, linters, and typecheckers before marking work complete.
+
+---
 
-Node.js **20.11 or newer**. Works on Windows, macOS and Linux. Git is optional but strongly recommended.
+## Quick Start
 
-## Install
+### Prerequisites
+Node.js **20.11 or newer**. Works on Windows, macOS, and Linux. Git is strongly recommended.
 
+### Step 1: Initialize the Workspace
 ```bash
-npx devworkspace init          # no install needed
-# or
-npm install -g devworkspace
-devworkspace init
+cd my-project
+npx devworkspace init
 ```
+Creates `.devworkspace/` with a nested `.gitignore` for machine-local state. It never modifies your source files and is safe to run multiple times.
 
-## Quick start
+### Step 2: Analyze Project Structure & Testing Contract
+```bash
+npx devworkspace analyze
+```
+Scans dependencies, frameworks, entry points, and scripts. Generates detected facts and your project's verification contract.
+
+### Step 3: Connect Your Coding Agent
+Choose the integration method that fits your agent (both can coexist safely):
 
+- **Option A: Model Context Protocol (MCP)** — Recommended for Claude Code, Codex, and Antigravity:
+  ```bash
+  npx devworkspace setup --agent claude-code
+  ```
+- **Option B: File-Based Instructions** — For Cursor, Copilot, Codex, and Claude:
+  ```bash
+  npx devworkspace agent install --agent all
+  ```
+
+### Step 4: Verify Workspace Readiness
 ```bash
-cd my-project
-npx devworkspace init          # safe local setup; creates .devworkspace/
-npx devworkspace analyze       # deterministic discovery + onboarding prompt
+npx devworkspace doctor
 ```
+Checks workspace health, instruction files, and testing contract consistency. When it reports `Core workspace: READY`, your project is ready for development.
 
-Optionally install the helper tools in one command (it shows what it will do first):
+---
+
+## Connecting Your Agent: Two Approaches
+
+DevWorkspace supports two ways to equip AI coding agents with project context. You can use either or both:
+
+| Capability | Approach A: Model Context Protocol (MCP) | Approach B: File-Based Instructions |
+| --- | --- | --- |
+| **How it works** | Runs a local stdio server exposing structured tools | Injects managed Markdown sections into instruction files |
+| **Target files** | `.mcp.json`, `mcp.json`, `.antigravity/mcp.json` | `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, Copilot instructions |
+| **Context retrieval** | Agent invokes tools directly (`get_task_context`, etc.) | Agent reads rules and runs CLI commands (`devworkspace context`) |
+| **Best suited for** | Claude Code, OpenAI Codex, Google Antigravity | Cursor, GitHub Copilot, Codex, Claude Code |
+| **CLI command** | `devworkspace setup --agent <name>` | `devworkspace agent install --agent <name>` |
+
+### Seamless Coexistence
+Both approaches can be used simultaneously in the same repository. DevWorkspace uses distinct HTML comment markers:
+- **Standard CLI rules:** `<!-- devworkspace:start -->` ... `<!-- devworkspace:end -->`
+- **MCP instructions:** `<!-- devworkspace-mcp:start -->` ... `<!-- devworkspace-mcp:end -->`
+
+Neither command will overwrite or interfere with the other, and custom developer notes outside the markers are preserved byte-for-byte.
+
+---
+
+## Model Context Protocol (MCP) Integration
+
+DevWorkspace includes a local-first Model Context Protocol (MCP 2024-11-05) server that enables compatible AI agents to query repository context dynamically over standard input/output (stdio).
+
+### Agent Configuration Commands
 
 ```bash
-npx devworkspace setup --integrations --dry-run
-npx devworkspace setup --integrations --yes
+# Configure Claude Code (.mcp.json and CLAUDE.md)
+npx devworkspace setup --agent claude-code
+
+# Configure OpenAI Codex (mcp.json and AGENTS.md)
+npx devworkspace setup --agent codex
+
+# Configure Google Antigravity (.antigravity/mcp.json and .antigravity/rules)
+npx devworkspace setup --agent antigravity
+
+# Configure all supported MCP agents at once
+npx devworkspace setup --agent all
+
+# Preview configuration changes without writing files (dry run)
+npx devworkspace setup --agent claude-code --check
+
+# Run the stdio MCP server directly
+devworkspace mcp serve
 ```
 
-Then:
+### Available MCP Tools
+
+Once configured, the following tools are available to the agent:
+
+1. **`get_project_overview`**: Returns the detected language stack, UI/backend frameworks, context health, and verification contract capabilities. Call at the start of a session or when exploring repository architecture.
+2. **`get_task_context`**: Generates progressive, role-sliced context tailored to specific requests (`explorer` for entry points, `tester` for test contracts, `reviewer` for ADRs and security rules). Preserves critical safety rules for all queries.
+3. **`get_file_context`**: Reads workspace-relative files bounded to 32KB per call with associated knowledge facts. Enforces path containment and automatically blocks credential files.
+
+### Important Notes on MCP Usage
 
-1. Open `.devworkspace/analysis/onboarding-prompt.md`.
-2. **Paste it into Claude Code** (or Claude in VS Code) in this project.
-3. Let Claude finish and verify the onboarding. It inspects the real repository, runs `devworkspace agent install`, writes concise knowledge, checks the testing contract and reports unknowns and warnings.
-4. Run `npx devworkspace doctor`. It should say `READY`.
+- **Tool Invocation Depends on the Agent:** Registering the MCP server makes tools *available* to your coding agent. Whether and when the agent invokes a tool depends on the user's prompt, the agent's internal system prompt, and the model's decision-making. You can prompt the agent directly: *"Use get_project_overview to inspect this project"* or *"Call get_task_context for this bug fix"*.
+- **Automated Tests vs. Live Agent Sessions:** DevWorkspace's MCP server and stdio transport are verified with automated subprocess integration and protocol test suites. However, interactive tool calling in proprietary desktop or terminal sessions (such as closed GUI builds of Claude Code, Codex, or Antigravity) has not been tested in live interactive client sessions and depends on each client's specific implementation.
+- **PATH Requirement:** Generated configurations specify `"command": "devworkspace"`. Ensure `devworkspace` is in your environment `PATH` (e.g. `npm install -g devworkspace`). If running locally without global binaries, change the command in `.mcp.json` / `mcp.json` / `.antigravity/mcp.json` to `"npx"` with arguments `["-y", "devworkspace", "mcp", "serve"]`.
 
-`analyze` does **not** call an AI. A CLI cannot drive an existing Claude chat, so DevWorkspace does the deterministic part itself and hands the reasoning part to Claude through a prompt you paste.
+Full MCP technical manual and debugging options: [docs/mcp.md](docs/mcp.md).
 
-## Integrations (Graphify, Agent Skills, Ponytail)
+---
 
-`devworkspace setup --integrations` installs and **verifies** them; `devworkspace integrations status` re-checks the real state at any time; `devworkspace doctor` reports core workspace health and integration health separately. Only project-local steps run without `--yes`; installing the Graphify tool for your user, user-scope installs and registry packages need `--yes`. Existing `CLAUDE.md`, `.claude` settings and skills are protected and restored if a tool would damage them. Some tools need a Claude Code restart afterwards, and that is reported as `RESTART_REQUIRED` rather than success. Details, scopes, limits and what was verified live: [docs/integrations.md](docs/integrations.md).
+## Daily Workflow
 
-## Daily workflow
+When working with an AI agent in your repository:
 
-Just talk to Claude:
+> *"Fix the invoice total rounding error in the billing service."*
+>
+> *"Add supplier management REST API endpoints."*
+>
+> *"Explain how tenant isolation middleware works."*
 
-> Fix the quotation email bug.
-> Add Responsible Person to Leads.
-> Explain how authentication works.
+The installed instructions direct the agent to follow a proportionate workflow:
+- **Questions:** Read-only inspection; runs no tests.
+- **Bug fixes:** Write a regression test first, implement the fix, and run verified checks.
+- **Refactoring:** Establish a passing test baseline before making modifications.
+- **Explicit constraints:** Constraints like *"only explain"*, *"don't commit"*, or *"no e2e"* are strictly respected.
 
-The installed instructions tell Claude to classify the request and apply a proportionate workflow. A question is read-only and runs no tests. A bug gets a regression test, a fix, and the verification your testing contract requires. A refactor records a test baseline first. You can override at any time: *"only explain"*, *"don't commit"*, *"don't run e2e"*. Overrides are honoured and recorded.
+### Common Daily Workflow Commands
 
-Useful commands any time:
+For everyday development with an AI agent:
 
 ```bash
-devworkspace status        # health, branch, knowledge, active tasks, verification commands
-devworkspace context       # what DevWorkspace believes (facts, decisions, testing contract)
-devworkspace refresh       # re-check knowledge against the repository; mark stale items
-devworkspace doctor        # check workspace, integrations, security, portability
+devworkspace status                  # Inspect workspace health, active tasks, and verification checks
+devworkspace context --for "<task>"  # Retrieve role-tailored context for a specific request
+devworkspace doctor                  # Run diagnostic and portability checks
+devworkspace refresh                 # Re-check repository evidence after pulling or large edits
 ```
 
-## Commands
-
-| Command | Purpose |
-| --- | --- |
-| `init` | Create `.devworkspace/` (idempotent, never touches source) |
-| `setup` | One-command setup: initialize workspace, discover commands, verify diagnostics, optionally install integrations (`--integrations`) |
-| `integrations` | `status` (observed, never assumed) and `repair` |
-| `analyze` | Deterministic discovery; writes `discovery.json`, testing contract, onboarding prompt |
-| `agent install` | Add managed instruction blocks for your coding agent (`--agent claude\|codex\|cursor\|copilot\|all`) |
-| `agent list` | Show supported and detected coding agent integrations and their capabilities |
-| `status` | Concise overview, read-only (`--deep` also runs the integration health checks; `--json` for tooling) |
-| `doctor` | Health, security and portability checks (`--fix`, `--strict`, `--json`) |
-| `refresh` | Incremental staleness check; writes a refresh prompt when AI re-validation is needed |
-| `context` | Show stored knowledge (`--topic` filters facts and the testing contract; safety rules are always shown; `--full`) |
-| `fact` | `add` / `verify` / `remove` / `list` project knowledge with provenance |
-| `feature` | `list` / `show` / `validate` / `add` feature-level map connecting frontend, backend, database and tests |
-| `graph` | `status` and `trace` bounded knowledge-graph navigation with node and edge verification |
-| `task` | `new` / `list` / `show` / `status` / `update` / `run` / `verify` / `tests` / `attest` with a package-aware completion gate |
-| `testenv` | `declare` / `list` / `revoke` a test environment so database-touching checks may run (local, never committed) |
-| `decision` | Append-only, human-readable decision records |
-| `session` | Save short session summaries (never transcripts) |
-| `export` / `import` | Move portable knowledge between machines safely |
-| `reset` | Delete `.devworkspace/` to start fresh (`--yes` to confirm, `--include-agent-files` to also remove managed agent instruction blocks/skills) |
-| `migrate` | Upgrade workspace files to the current schema, with backups |
-
-Global flags: `--json`, `--cwd <dir>`, `--dry-run` (where it applies), `--debug`, `--no-color`, `--ascii`.
-
-**Exit codes:** `0` success · `1` failure · `2` usage error · `3` warnings (only with `--strict` on `status`/`doctor`) · `130`/`143` interrupted. Integrations that are not installed are *warnings*, never failures, so CI can use `devworkspace doctor` and fail only on real problems.
+### Command Reference
 
-## Portability
+| Command | Summary | Guide |
+| --- | --- | --- |
+| `init` | Create `.devworkspace/` in the project (safe to re-run) | [Getting Started](docs/getting-started.md) |
+| `setup` | One-command setup: initialize, discover contracts, configure agents | [Getting Started](docs/getting-started.md) |
+| `analyze` | Deterministic repository discovery and onboarding analysis | [Architecture](docs/architecture.md) |
+| `status` | Concise health, Git branch, knowledge, and verification overview | [Getting Started](docs/getting-started.md) |
+| `doctor` | Workspace, security, portability, and integration diagnostics | [Troubleshooting](docs/troubleshooting.md) |
+| `context` | Task-aware context retrieval with optional role slicing | [Task Routing](docs/routing.md) |
+| `refresh` | Re-check repository evidence and mark stale knowledge | [Knowledge Model](docs/knowledge.md) |
+| `task` | Engineering task tracking with completion verification gate | [Testing Contract](docs/testing.md) |
+| `agent` | Manage agent instructions (`agent install`, `agent list`) | [Agent Integrations](docs/agents.md) |
+| `mcp` | Stdio Model Context Protocol server (`serve`) and agent setup (`setup`) | [MCP Guide](docs/mcp.md) |
+| `integrations` | Inspect and repair optional helper tools (Graphify, Skills, Ponytail) | [Integrations](docs/integrations.md) |
+| `fact` | Record, verify, list, or remove project facts with provenance | [Knowledge Model](docs/knowledge.md) |
+| `feature` | End-to-end feature map tracing across routes, services, and tests | [Getting Started](docs/getting-started.md) |
+| `graph` | Inspect and trace Graphify knowledge graphs | [Integrations](docs/integrations.md) |
+| `decision` | Append-only architectural decision records (ADRs) | [Architecture](docs/architecture.md) |
+| `session` | Record concise session summaries (never transcripts) | [Getting Started](docs/getting-started.md) |
+| `testenv` | Declare local test environment for database-touching checks | [Testing Contract](docs/testing.md) |
+| `export` | Export portable project knowledge to a bundle | [Portability](docs/portability.md) |
+| `import` | Safely import an export bundle without silent overwrites | [Portability](docs/portability.md) |
+| `reset` | Reset `.devworkspace/` (optional `--include-agent-files`) | [Getting Started](docs/getting-started.md) |
+| `migrate` | Upgrade workspace files to current schema with backups | [Getting Started](docs/getting-started.md) |
+
+Global flags supported across commands: `--json`, `--cwd <dir>`, `--dry-run`, `--debug`, `--no-color`, `--ascii`.
+
+Exit codes: `0` success · `1` failure · `2` usage error · `3` warnings (with `--strict`) · `130`/`143` interrupted.
+
+---
+
+## Security, Privacy & Data Transmission
 
-Commit `.devworkspace/` (machine-local state in `.devworkspace/local/` is ignored by a nested `.gitignore`). On another computer: clone, then `devworkspace doctor`. Project identity is a random ID in `project.json`, never a path, so moving `D:\Company\CRM` to `C:\Projects\CRM` changes nothing. Details: [docs/portability.md](docs/portability.md).
+DevWorkspace enforces defense-in-depth safety controls:
+
+### Local DevWorkspace Protections
+- **Zero Network Listeners:** DevWorkspace never opens HTTP or TCP ports. MCP runs strictly over local stdio child processes.
+- **No Telemetry or Cloud Accounts:** DevWorkspace does not collect analytics or transmit data to DevWorkspace servers.
+- **Credential Protection:** Credential files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, tokens, keystores) are barred from reads. If an allowed source file contains API keys or tokens, patterns are automatically masked with `[REDACTED:<type>]`.
+- **Workspace Boundary Enforcement:** Paths are validated with canonical checks (`resolveInside`) and symlink escape verification (`assertNoSymlinkEscape`). Directory traversal (`..`) and absolute paths are rejected.
+- **Prompt-Injection Defense:** All retrieved context is demarcated with `=== BEGIN UNTRUSTED DEVWORKSPACE CONTEXT ===` headers, instructing the agent to treat repository content as untrusted evidence rather than executable instructions.
+
+### AI Provider Notice
+When an AI coding agent invokes DevWorkspace MCP tools or reads project files, that context enters the agent's context window and is transmitted to the external cloud LLM provider powering that agent (such as Anthropic, OpenAI, or Google). DevWorkspace governs what leaves your local files, while your AI provider's terms and privacy policies govern data processed in their cloud.
+
+Full security and threat model: [docs/security.md](docs/security.md).
+
+---
+
+## Ecosystem & Helper Tools
+
+DevWorkspace decides *when and why* engineering workflows apply. It can optionally orchestrate external helper tools:
+
+| Concern | Tool | Status |
+| --- | --- | --- |
+| Structural code understanding | [Graphify](https://github.com/Graphify-Labs/graphify) | Optional integration (`setup --integrations`) |
+| Engineering skill workflows | [Agent Skills](https://github.com/addyosmani/agent-skills) | Optional integration (`setup --integrations`) |
+| Code quality & debt review | [Ponytail](https://github.com/DietrichGebert/ponytail) | Optional integration (`setup --integrations`) |
+| Correctness & verification | **Your test suites** | Discovered deterministically in `commands.json` |
+
+Details on scopes, prerequisites, and integration health checks: [docs/integrations.md](docs/integrations.md).
+
+---
+
+## Portability
 
-## Security and privacy
+Commit `.devworkspace/` to your version control system (machine-local files in `.devworkspace/local/` are ignored automatically). On another workstation, clone the repository and run `npx devworkspace doctor`. Project identity is managed via a UUID in `project.json` rather than hardcoded file paths, so repository paths can change without breaking project state. Full guide: [docs/portability.md](docs/portability.md).
 
-- Credential files (`.env*`, keys, `credentials.*`, …) are **never read**; only their presence is recorded. Secret-looking values are refused by every write path and redacted from logs.
-- Repository content is treated as **untrusted data**, and the generated instructions say so, to resist prompt injection.
-- Subprocesses use argument arrays, never a shell. Imports are validated before anything is written.
-- DevWorkspace itself sends nothing anywhere and has no telemetry. Generated prompts will, of course, cause *your chosen AI agent* to read repository files.
+---
 
-Details: [docs/security.md](docs/security.md).
+## Limitations
 
-## Limitations (V1)
+- **Language Scope:** Manifest and command discovery supports Node.js, Python, Go, Rust, Java, and PHP projects.
+- **Client Environments:** Standard stdio protocol handling is verified via automated tests, but live interactive invocation depends on individual third-party agent desktop or CLI releases.
+- **Model Prerogative:** MCP tool availability does not force an agent to invoke a tool; invocation depends on model planning and prompt specificity.
+- **Integration Prerequisites:** Integrations like Graphify require Python 3.10+ or `uv` and explicit user authorization (`--yes`).
 
-- Multi-agent support includes typed adapters for Claude Code, OpenAI Codex (`AGENTS.md`), Cursor (`.cursor/rules` and `.cursorrules`), and GitHub Copilot (`.github/copilot-instructions.md`).
-- Integration setup needs prerequisites (Python 3.10+ or uv for Graphify; the Claude Code CLI for native plugins, otherwise portable skills with fewer capabilities) and sometimes your approval. It was not run end to end against GitHub on macOS/Linux; see the verification notes in [docs/integrations.md](docs/integrations.md).
-- DevWorkspace does not build Graphify's graph (that uses the model) or uninstall anything.
-- Deep analysis is not attempted for any language; discovery covers manifests, structure and commands for Node, Python, Go, Rust, Java and PHP projects.
-- The routing classifier is a keyword heuristic used to *propose* a type. The agent decides.
-- Token savings are not claimed. See [docs/benchmarking.md](docs/benchmarking.md) for how to measure them.
+---
 
 ## Documentation
 
-[Getting started](docs/getting-started.md) · [Architecture](docs/architecture.md) · [Agents](docs/agents.md) · [Knowledge model](docs/knowledge.md) · [Testing contract](docs/testing.md) · [Security & privacy](docs/security.md) · [Integrations](docs/integrations.md) · [Claude](docs/claude.md) · [Routing](docs/routing.md) · [Portability](docs/portability.md) · [Benchmarking](docs/benchmarking.md) · [Troubleshooting](docs/troubleshooting.md) · [Contributing](docs/contributing.md)
+- [Getting Started](docs/getting-started.md)
+- [Architecture & Design](docs/architecture.md)
+- [Model Context Protocol (MCP)](docs/mcp.md)
+- [Coding Agent Integrations](docs/agents.md)
+- [Knowledge & Context Model](docs/knowledge.md)
+- [Testing & Verification Contract](docs/testing.md)
+- [Security & Threat Model](docs/security.md)
+- [Integrations (Graphify, Skills, Ponytail)](docs/integrations.md)
+- [Claude Code Guide](docs/claude.md)
+- [Task Routing & Roles](docs/routing.md)
+- [Portability & Git](docs/portability.md)
+- [Benchmarking & Evaluation](docs/benchmarking.md)
+- [Troubleshooting Guide](docs/troubleshooting.md)
+- [Contributing](docs/contributing.md)
+
+---
 
 ## License
 

package/dist/cli/args.d.ts

@@ -276,5 +276,6 @@ export interface ParsedArgs {
 export declare function parseCli(argv: string[]): ParsedArgs;
 export declare function str(v: ParsedArgs['values'], k: string): string | undefined;
 export declare function bool(v: ParsedArgs['values'], k: string): boolean;
+export declare function isCheckOrDryRun(v: ParsedArgs['values']): boolean;
 export declare function list(v: ParsedArgs['values'], k: string): string[];
 export declare function int(v: ParsedArgs['values'], k: string): number | undefined;

package/dist/cli/args.js

@@ -87,7 +87,16 @@ export const OPTIONS = {
 };
 export function parseCli(argv) {
     try {
-        const { values, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+        const normalizedArgv = argv.map((arg, idx) => {
+            if (arg === '--check') {
+                const next = argv[idx + 1];
+                if (!next || next.startsWith('-')) {
+                    return '--check=true';
+                }
+            }
+            return arg;
+        });
+        const { values, positionals } = parseArgs({ args: normalizedArgv, options: OPTIONS, allowPositionals: true, strict: true });
         return { positionals, values: values };
     }
     catch (e) {
@@ -103,6 +112,12 @@ export function str(v, k) {
 export function bool(v, k) {
     return v[k] === true;
 }
+export function isCheckOrDryRun(v) {
+    if (bool(v, 'dry-run'))
+        return true;
+    const checks = list(v, 'check');
+    return checks.includes('true');
+}
 export function list(v, k) {
     const x = v[k];
     return Array.isArray(x) ? x : [];

package/dist/cli/args.js.map

@@ -1 +1 @@
-{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"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","sourcesContent":["import { parseArgs } from 'node:util';\nimport { DevWorkspaceError } from '../errors/index.js';\n\ntype OptionSpec = { type: 'boolean' | 'string'; short?: string; multiple?: boolean };\n\n/** Every flag the CLI understands. Unknown flags are rejected so typos never silently do nothing. */\nexport const OPTIONS = {\n  help: { type: 'boolean', short: 'h' },\n  version: { type: 'boolean', short: 'v' },\n  json: { type: 'boolean' },\n  debug: { type: 'boolean' },\n  'no-color': { type: 'boolean' },\n  ascii: { type: 'boolean' },\n  'dry-run': { type: 'boolean' },\n  yes: { type: 'boolean', short: 'y' },\n  'include-agent-files': { type: 'boolean' },\n  integrations: { type: 'boolean' },\n  'with-integrations': { type: 'boolean' },\n  only: { type: 'string', multiple: true },\n  scope: { type: 'string' },\n  restarted: { type: 'boolean' },\n  quick: { type: 'boolean' },\n  cwd: { type: 'string' },\n  root: { type: 'string' },\n  fix: { type: 'boolean' },\n  strict: { type: 'boolean' },\n  out: { type: 'string', short: 'o' },\n  overwrite: { type: 'boolean' },\n  'allow-different-project': { type: 'boolean' },\n  topic: { type: 'string' },\n  full: { type: 'boolean' },\n  all: { type: 'boolean' },\n  agent: { type: 'string' },\n  type: { type: 'string' },\n  title: { type: 'string' },\n  key: { type: 'string' },\n  value: { type: 'string' },\n  source: { type: 'string' },\n  'source-type': { type: 'string' },\n  file: { type: 'string', multiple: true },\n  confidence: { type: 'string' },\n  status: { type: 'string' },\n  reason: { type: 'string' },\n  detail: { type: 'string' },\n  note: { type: 'string' },\n  phase: { type: 'string' },\n  passed: { type: 'string' },\n  failed: { type: 'string' },\n  criteria: { type: 'string', multiple: true },\n  plan: { type: 'string', multiple: true },\n  area: { type: 'string', multiple: true },\n  'decision-note': { type: 'string', multiple: true },\n  summary: { type: 'string' },\n  blocker: { type: 'string', multiple: true },\n  'clear-blockers': { type: 'boolean' },\n  require: { type: 'string', multiple: true },\n  'user-work-intact': { type: 'boolean' },\n  'knowledge-reviewed': { type: 'boolean' },\n  'final-state-inspected': { type: 'boolean' },\n  context: { type: 'string' },\n  for: { type: 'string' },\n  role: { type: 'string' },\n  decision: { type: 'string' },\n  consequences: { type: 'string' },\n  supersedes: { type: 'string' },\n  goal: { type: 'string' },\n  done: { type: 'string', multiple: true },\n  'tests-run': { type: 'string', multiple: true },\n  remaining: { type: 'string', multiple: true },\n  next: { type: 'string' },\n  task: { type: 'string' },\n  limit: { type: 'string' },\n  package: { type: 'string' },\n  check: { type: 'string', multiple: true },\n  target: { type: 'string' },\n  timeout: { type: 'string' },\n  deep: { type: 'boolean' },\n  id: { type: 'string' },\n  name: { type: 'string' },\n  description: { type: 'string' },\n  symbol: { type: 'string' },\n  entry: { type: 'string', multiple: true },\n  route: { type: 'string', multiple: true },\n  service: { type: 'string', multiple: true },\n  model: { type: 'string', multiple: true },\n  test: { type: 'string', multiple: true },\n  tag: { type: 'string', multiple: true },\n  from: { type: 'string' },\n  depth: { type: 'string' },\n} as const satisfies Record<string, OptionSpec>;\n\nexport interface ParsedArgs {\n  positionals: string[];\n  values: Record<string, string | boolean | string[] | undefined>;\n}\n\nexport function parseCli(argv: string[]): ParsedArgs {\n  try {\n    const { values, positionals } = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });\n    return { positionals, values: values as ParsedArgs['values'] };\n  } catch (e) {\n    throw new DevWorkspaceError('USAGE', (e as Error).message.replace(/^Unknown option/, 'Unknown option'), {\n      hint: 'Run \"devworkspace --help\" or \"devworkspace <command> --help\".',\n    });\n  }\n}\n\nexport function str(v: ParsedArgs['values'], k: string): string | undefined {\n  const x = v[k];\n  return typeof x === 'string' ? x : undefined;\n}\n\nexport function bool(v: ParsedArgs['values'], k: string): boolean {\n  return v[k] === true;\n}\n\nexport function list(v: ParsedArgs['values'], k: string): string[] {\n  const x = v[k];\n  return Array.isArray(x) ? x : [];\n}\n\nexport function int(v: ParsedArgs['values'], k: string): number | undefined {\n  const s = str(v, k);\n  if (s === undefined) return undefined;\n  const n = Number(s);\n  if (!Number.isInteger(n)) throw new DevWorkspaceError('USAGE', `--${k} must be an integer (got \"${s}\").`);\n  return n;\n}\n"]}
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"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","sourcesContent":["import { parseArgs } from 'node:util';\nimport { DevWorkspaceError } from '../errors/index.js';\n\ntype OptionSpec = { type: 'boolean' | 'string'; short?: string; multiple?: boolean };\n\n/** Every flag the CLI understands. Unknown flags are rejected so typos never silently do nothing. */\nexport const OPTIONS = {\n  help: { type: 'boolean', short: 'h' },\n  version: { type: 'boolean', short: 'v' },\n  json: { type: 'boolean' },\n  debug: { type: 'boolean' },\n  'no-color': { type: 'boolean' },\n  ascii: { type: 'boolean' },\n  'dry-run': { type: 'boolean' },\n  yes: { type: 'boolean', short: 'y' },\n  'include-agent-files': { type: 'boolean' },\n  integrations: { type: 'boolean' },\n  'with-integrations': { type: 'boolean' },\n  only: { type: 'string', multiple: true },\n  scope: { type: 'string' },\n  restarted: { type: 'boolean' },\n  quick: { type: 'boolean' },\n  cwd: { type: 'string' },\n  root: { type: 'string' },\n  fix: { type: 'boolean' },\n  strict: { type: 'boolean' },\n  out: { type: 'string', short: 'o' },\n  overwrite: { type: 'boolean' },\n  'allow-different-project': { type: 'boolean' },\n  topic: { type: 'string' },\n  full: { type: 'boolean' },\n  all: { type: 'boolean' },\n  agent: { type: 'string' },\n  type: { type: 'string' },\n  title: { type: 'string' },\n  key: { type: 'string' },\n  value: { type: 'string' },\n  source: { type: 'string' },\n  'source-type': { type: 'string' },\n  file: { type: 'string', multiple: true },\n  confidence: { type: 'string' },\n  status: { type: 'string' },\n  reason: { type: 'string' },\n  detail: { type: 'string' },\n  note: { type: 'string' },\n  phase: { type: 'string' },\n  passed: { type: 'string' },\n  failed: { type: 'string' },\n  criteria: { type: 'string', multiple: true },\n  plan: { type: 'string', multiple: true },\n  area: { type: 'string', multiple: true },\n  'decision-note': { type: 'string', multiple: true },\n  summary: { type: 'string' },\n  blocker: { type: 'string', multiple: true },\n  'clear-blockers': { type: 'boolean' },\n  require: { type: 'string', multiple: true },\n  'user-work-intact': { type: 'boolean' },\n  'knowledge-reviewed': { type: 'boolean' },\n  'final-state-inspected': { type: 'boolean' },\n  context: { type: 'string' },\n  for: { type: 'string' },\n  role: { type: 'string' },\n  decision: { type: 'string' },\n  consequences: { type: 'string' },\n  supersedes: { type: 'string' },\n  goal: { type: 'string' },\n  done: { type: 'string', multiple: true },\n  'tests-run': { type: 'string', multiple: true },\n  remaining: { type: 'string', multiple: true },\n  next: { type: 'string' },\n  task: { type: 'string' },\n  limit: { type: 'string' },\n  package: { type: 'string' },\n  check: { type: 'string', multiple: true },\n  target: { type: 'string' },\n  timeout: { type: 'string' },\n  deep: { type: 'boolean' },\n  id: { type: 'string' },\n  name: { type: 'string' },\n  description: { type: 'string' },\n  symbol: { type: 'string' },\n  entry: { type: 'string', multiple: true },\n  route: { type: 'string', multiple: true },\n  service: { type: 'string', multiple: true },\n  model: { type: 'string', multiple: true },\n  test: { type: 'string', multiple: true },\n  tag: { type: 'string', multiple: true },\n  from: { type: 'string' },\n  depth: { type: 'string' },\n} as const satisfies Record<string, OptionSpec>;\n\nexport interface ParsedArgs {\n  positionals: string[];\n  values: Record<string, string | boolean | string[] | undefined>;\n}\n\nexport function parseCli(argv: string[]): ParsedArgs {\n  try {\n    const normalizedArgv = argv.map((arg, idx) => {\n      if (arg === '--check') {\n        const next = argv[idx + 1];\n        if (!next || next.startsWith('-')) {\n          return '--check=true';\n        }\n      }\n      return arg;\n    });\n    const { values, positionals } = parseArgs({ args: normalizedArgv, options: OPTIONS, allowPositionals: true, strict: true });\n    return { positionals, values: values as ParsedArgs['values'] };\n  } catch (e) {\n    throw new DevWorkspaceError('USAGE', (e as Error).message.replace(/^Unknown option/, 'Unknown option'), {\n      hint: 'Run \"devworkspace --help\" or \"devworkspace <command> --help\".',\n    });\n  }\n}\n\nexport function str(v: ParsedArgs['values'], k: string): string | undefined {\n  const x = v[k];\n  return typeof x === 'string' ? x : undefined;\n}\n\nexport function bool(v: ParsedArgs['values'], k: string): boolean {\n  return v[k] === true;\n}\n\nexport function isCheckOrDryRun(v: ParsedArgs['values']): boolean {\n  if (bool(v, 'dry-run')) return true;\n  const checks = list(v, 'check');\n  return checks.includes('true');\n}\n\nexport function list(v: ParsedArgs['values'], k: string): string[] {\n  const x = v[k];\n  return Array.isArray(x) ? x : [];\n}\n\nexport function int(v: ParsedArgs['values'], k: string): number | undefined {\n  const s = str(v, k);\n  if (s === undefined) return undefined;\n  const n = Number(s);\n  if (!Number.isInteger(n)) throw new DevWorkspaceError('USAGE', `--${k} must be an integer (got \"${s}\").`);\n  return n;\n}\n"]}

package/dist/cli/help.js

@@ -22,9 +22,12 @@ export const COMMANDS = [
         summary: 'Single-command repository setup (inspect, initialize, discover contract & validate)',
         usage: [
             'devworkspace setup',
+            'devworkspace setup --agent claude-code|codex|antigravity|all [--check]',
             'devworkspace setup --integrations [--yes] [--dry-run] [--scope project|user] [--only graphify,agent-skills,ponytail]',
         ],
         options: [
+            ['--agent <name>', 'configure MCP integration for agent (claude-code, codex, antigravity, all)'],
+            ['--check', 'with --agent: validate and plan without writing files'],
             ['--integrations', 'set up external integrations (Graphify, Agent Skills, Ponytail)'],
             ['--dry-run', 'show exactly what would run; changes nothing'],
             ['--yes', 'with --integrations: approve machine-level and third-party installs'],
@@ -32,7 +35,13 @@ export const COMMANDS = [
             ['--only <ids>', 'comma-separated: graphify, agent-skills, ponytail'],
             ...COMMON,
         ],
-        examples: ['devworkspace setup', 'devworkspace setup --json', 'devworkspace setup --integrations --yes'],
+        examples: [
+            'devworkspace setup',
+            'devworkspace setup --agent claude-code',
+            'devworkspace setup --agent antigravity --check',
+            'devworkspace setup --json',
+            'devworkspace setup --integrations --yes',
+        ],
     },
     {
         name: 'integrations',
@@ -264,6 +273,24 @@ export const COMMANDS = [
         options: [['--dry-run', 'list what would be migrated'], ...COMMON],
         examples: ['devworkspace migrate'],
     },
+    {
+        name: 'mcp',
+        summary: 'Local-first Model Context Protocol (MCP) server and agent configuration',
+        usage: [
+            'devworkspace mcp serve [--debug]',
+            'devworkspace mcp setup [--agent claude-code|codex|antigravity|all] [--check]',
+        ],
+        options: [
+            ['--agent <name>', 'agent to configure (claude-code, codex, antigravity, all)'],
+            ['--check', 'validate and plan configuration without modifying files'],
+            ...COMMON,
+        ],
+        examples: [
+            'devworkspace mcp serve',
+            'devworkspace mcp setup --agent claude-code',
+            'devworkspace mcp setup --agent antigravity --check',
+        ],
+    },
 ];
 export function topHelp(version) {
     const w = Math.max(...COMMANDS.map((c) => c.name.length));