devworkspace 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes are documented here. This project follows [Semantic Versioning](https://semver.org/). Workspace schema changes are called out under **Breaking**.
 
+## [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

@@ -67,6 +67,29 @@ Then:
 
 `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).
 
+## Model Context Protocol (MCP) Server
+
+DevWorkspace includes a local-first Model Context Protocol (MCP) server so AI coding agents can retrieve project architecture, role-based task context, and file metadata automatically:
+
+```bash
+# Configure Claude Code (.mcp.json + CLAUDE.md)
+devworkspace setup --agent claude-code
+
+# Configure OpenAI Codex (mcp.json + AGENTS.md)
+devworkspace setup --agent codex
+
+# Configure Google Antigravity (.antigravity/mcp.json + rules)
+devworkspace setup --agent antigravity
+
+# Preview configuration without writing files
+devworkspace setup --agent claude-code --check
+
+# Run the local stdio MCP server directly
+devworkspace mcp serve
+```
+
+MCP runs strictly over stdio, opens zero network ports, enforces workspace boundaries, redacts secrets, and operates without third-party cloud services or LLM API keys. Full guide: [docs/mcp.md](docs/mcp.md).
+
 ## Daily workflow
 
 Just talk to Claude:
@@ -110,6 +133,7 @@ devworkspace doctor        # check workspace, integrations, security, portabilit
 | `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 |
+| `mcp` | Local-first Model Context Protocol server (`serve`) and agent setup (`setup`) |
 
 Global flags: `--json`, `--cwd <dir>`, `--dry-run` (where it applies), `--debug`, `--no-color`, `--ascii`.
 

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));

package/dist/cli/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,GAAuB;IACjC,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IACrC,CAAC,aAAa,EAAE,4BAA4B,CAAC;IAC7C,CAAC,SAAS,EAAE,kCAAkC,CAAC;CAChD,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAkB;IACrC;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,+DAA+D;QACxE,KAAK,EAAE,CAAC,mGAAmG,CAAC;QAC5G,OAAO,EAAE;YACP,CAAC,cAAc,EAAE,4DAA4D,CAAC;YAC9E,CAAC,WAAW,EAAE,4BAA4B,CAAC;YAC3C,CAAC,qBAAqB,EAAE,4EAA4E,CAAC;YACrG,CAAC,OAAO,EAAE,0EAA0E,CAAC;YACrF,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,uBAAuB,EAAE,iDAAiD,CAAC;KACvF;IACD;QACE,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,qFAAqF;QAC9F,KAAK,EAAE;YACL,oBAAoB;YACpB,sHAAsH;SACvH;QACD,OAAO,EAAE;YACP,CAAC,gBAAgB,EAAE,iEAAiE,CAAC;YACrF,CAAC,WAAW,EAAE,8CAA8C,CAAC;YAC7D,CAAC,OAAO,EAAE,qEAAqE,CAAC;YAChF,CAAC,sBAAsB,EAAE,uDAAuD,CAAC;YACjF,CAAC,cAAc,EAAE,mDAAmD,CAAC;YACrE,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,oBAAoB,EAAE,2BAA2B,EAAE,yCAAyC,CAAC;KACzG;IACD;QACE,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,qEAAqE;QAC9E,KAAK,EAAE;YACL,qEAAqE;YACrE,4FAA4F;SAC7F;QACD,OAAO,EAAE;YACP,CAAC,SAAS,EAAE,mEAAmE,CAAC;YAChF,CAAC,aAAa,EAAE,kEAAkE,CAAC;YACnF,CAAC,UAAU,EAAE,sDAAsD,CAAC;YACpE,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,kCAAkC,EAAE,wCAAwC,CAAC;KACzF;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,4EAA4E;QACrF,KAAK,EAAE,CAAC,kCAAkC,CAAC;QAC3C,OAAO,EAAE,CAAC,CAAC,WAAW,EAAE,2CAA2C,CAAC,EAAE,GAAG,MAAM,CAAC;QAChF,QAAQ,EAAE,CAAC,sBAAsB,EAAE,6BAA6B,CAAC;KAClE;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,6EAA6E;QACtF,KAAK,EAAE,CAAC,uDAAuD,CAAC;QAChE,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,sCAAsC,CAAC,EAAE,CAAC,QAAQ,EAAE,2DAA2D,CAAC,EAAE,GAAG,MAAM,CAAC;QACnJ,QAAQ,EAAE,CAAC,qBAAqB,EAAE,4BAA4B,CAAC;KAChE;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,6DAA6D;QACtE,KAAK,EAAE,CAAC,oGAAoG,CAAC;QAC7G,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,4DAA4D,CAAC,EAAE,CAAC,UAAU,EAAE,gCAAgC,CAAC,EAAE,GAAG,MAAM,CAAC;QAC7I,QAAQ,EAAE,CAAC,qBAAqB,EAAE,qCAAqC,CAAC;KACzE;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,kFAAkF;QAC3F,KAAK,EAAE,CAAC,0GAA0G,CAAC;QACnH,OAAO,EAAE,CAAC,CAAC,WAAW,EAAE,wCAAwC,CAAC,EAAE,GAAG,MAAM,CAAC;QAC7E,QAAQ,EAAE,CAAC,sBAAsB,CAAC;KACnC;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,mDAAmD;QAC5D,KAAK,EAAE,CAAC,wGAAwG,CAAC;QACjH,OAAO,EAAE;YACP,CAAC,iBAAiB,EAAE,4HAA4H,CAAC;YACjJ,CAAC,eAAe,EAAE,mFAAmF,CAAC;YACtG,CAAC,gBAAgB,EAAE,2FAA2F,CAAC;YAC/G,CAAC,QAAQ,EAAE,uCAAuC,CAAC;YACnD,GAAG,MAAM;SACV;QACD,QAAQ,EAAE;YACR,mCAAmC;YACnC,iEAAiE;YACjE,sEAAsE;YACtE,iEAAiE;YACjE,4EAA4E;SAC7E;KACF;IACD;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,uDAAuD;QAChE,KAAK,EAAE;YACL,8LAA8L;YAC9L,gCAAgC;YAChC,gCAAgC;YAChC,wBAAwB;SACzB;QACD,OAAO,EAAE;YACP,CAAC,OAAO,EAAE,+CAA+C,CAAC;YAC1D,CAAC,SAAS,EAAE,sDAAsD,CAAC;YACnE,CAAC,eAAe,EAAE,0EAA0E,CAAC;YAC7F,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,2LAA2L,CAAC;KACxM;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,gEAAgE;QACzE,KAAK,EAAE;YACL,2BAA2B;YAC3B,gCAAgC;YAChC,+BAA+B;YAC/B,wKAAwK;SACzK;QACD,OAAO,EAAE;YACP,CAAC,WAAW,EAAE,4CAA4C,CAAC;YAC3D,CAAC,eAAe,EAAE,qCAAqC,CAAC;YACxD,CAAC,gBAAgB,EAAE,wCAAwC,CAAC;YAC5D,CAAC,gBAAgB,EAAE,4CAA4C,CAAC;YAChE,CAAC,kBAAkB,EAAE,mCAAmC,CAAC;YACzD,CAAC,gBAAgB,EAAE,yCAAyC,CAAC;YAC7D,CAAC,eAAe,EAAE,6BAA6B,CAAC;YAChD,CAAC,gBAAgB,EAAE,sEAAsE,CAAC;YAC1F,GAAG,MAAM;SACV;QACD,QAAQ,EAAE;YACR,2BAA2B;YAC3B,sCAAsC;YACtC,+BAA+B;YAC/B,mKAAmK;SACpK;KACF;IACD;QACE,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,6CAA6C;QACtD,KAAK,EAAE;YACL,2BAA2B;YAC3B,8DAA8D;SAC/D;QACD,OAAO,EAAE;YACP,CAAC,qBAAqB,EAAE,sDAAsD,CAAC;YAC/E,CAAC,aAAa,EAAE,2CAA2C,CAAC;YAC5D,GAAG,MAAM;SACV;QACD,QAAQ,EAAE;YACR,2BAA2B;YAC3B,sDAAsD;SACvD;KACF;IACD;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,gDAAgD;QACzD,KAAK,EAAE;YACL,4DAA4D;YAC5D,qEAAqE;YACrE,6BAA6B;YAC7B,wDAAwD;YACxD,qJAAqJ;YACrJ,qIAAqI;YACrI,wKAAwK;YACxK,+EAA+E;YAC/E,qGAAqG;SACtG;QACD,OAAO,EAAE;YACP,CAAC,OAAO,EAAE,yBAAyB,CAAC;YACpC,CAAC,iBAAiB,EAAE,gGAAgG,CAAC;YACrH,CAAC,qBAAqB,EAAE,gDAAgD,CAAC;YACzE,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,iDAAiD,EAAE,qDAAqD,EAAE,oDAAoD,CAAC;KAC3K;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,yFAAyF;QAClG,KAAK,EAAE;YACL,iIAAiI;YACjI,2BAA2B;YAC3B,6CAA6C;SAC9C;QACD,OAAO,EAAE;YACP,CAAC,iBAAiB,EAAE,0CAA0C,CAAC;YAC/D,CAAC,cAAc,EAAE,2CAA2C,CAAC;YAC7D,CAAC,iBAAiB,EAAE,6DAA6D,CAAC;YAClF,CAAC,OAAO,EAAE,iDAAiD,CAAC;YAC5D,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,qHAAqH,CAAC;KAClI;IACD;QACE,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,sEAAsE;QAC/E,KAAK,EAAE;YACL,0GAA0G;YAC1G,4BAA4B;YAC5B,gCAAgC;SACjC;QACD,OAAO,EAAE,MAAM;QACf,QAAQ,EAAE,CAAC,4BAA4B,CAAC;KACzC;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,0DAA0D;QACnE,KAAK,EAAE;YACL,oKAAoK;YACpK,2BAA2B;SAC5B;QACD,OAAO,EAAE,MAAM;QACf,QAAQ,EAAE,CAAC,kGAAkG,CAAC;KAC/G;IACD;QACE,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,mEAAmE;QAC5E,KAAK,EAAE;YACL,kFAAkF;YAClF,yBAAyB;SAC1B;QACD,OAAO,EAAE;YACP,CAAC,cAAc,EAAE,yEAAyE,CAAC;YAC3F,CAAC,WAAW,EAAE,qCAAqC,CAAC;YACpD,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,2CAA2C,EAAE,kDAAkD,EAAE,yBAAyB,CAAC;KACvI;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,oDAAoD;QAC7D,KAAK,EAAE,CAAC,gDAAgD,CAAC;QACzD,OAAO,EAAE,CAAC,CAAC,cAAc,EAAE,wDAAwD,CAAC,EAAE,GAAG,MAAM,CAAC;QAChG,QAAQ,EAAE,CAAC,0CAA0C,CAAC;KACvD;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,uEAAuE;QAChF,KAAK,EAAE,CAAC,kFAAkF,CAAC;QAC3F,OAAO,EAAE,CAAC,CAAC,aAAa,EAAE,kDAAkD,CAAC,EAAE,CAAC,WAAW,EAAE,wBAAwB,CAAC,EAAE,GAAG,MAAM,CAAC;QAClI,QAAQ,EAAE,CAAC,8CAA8C,CAAC;KAC3D;IACD;QACE,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,oFAAoF;QAC7F,KAAK,EAAE,CAAC,oDAAoD,CAAC;QAC7D,OAAO,EAAE;YACP,CAAC,OAAO,EAAE,qEAAqE,CAAC;YAChF,CAAC,uBAAuB,EAAE,iFAAiF,CAAC;YAC5G,CAAC,WAAW,EAAE,oBAAoB,CAAC;YACnC,GAAG,MAAM;SACV;QACD,QAAQ,EAAE,CAAC,oBAAoB,EAAE,0BAA0B,EAAE,qEAAqE,CAAC;KACpI;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,8DAA8D;QACvE,KAAK,EAAE,CAAC,kCAAkC,CAAC;QAC3C,OAAO,EAAE,CAAC,CAAC,WAAW,EAAE,6BAA6B,CAAC,EAAE,GAAG,MAAM,CAAC;QAClE,QAAQ,EAAE,CAAC,sBAAsB,CAAC;KACnC;CACF,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1D,OAAO;QACL,gBAAgB,OAAO,2CAA2C;QAClE,EAAE;QACF,yCAAyC;QACzC,EAAE;QACF,WAAW;QACX,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;QAC/D,EAAE;QACF,cAAc;QACd,iBAAiB;QACjB,yBAAyB;QACzB,4BAA4B;QAC5B,wEAAwE;QACxE,EAAE;QACF,sFAAsF;QACtF,+FAA+F;QAC/F,oJAAoJ;QACpJ,kDAAkD;KACnD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAc;IACxC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,OAAO;QACL,gBAAgB,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,OAAO,EAAE;QACvC,EAAE;QACF,QAAQ;QACR,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,EAAE;QACF,UAAU;QACV,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,EAAE;QACF,WAAW;QACX,GAAG,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;KACnC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC","sourcesContent":["export interface CommandHelp {\n  name: string;\n  summary: string;\n  usage: string[];\n  options: [string, string][];\n  examples: string[];\n}\n\nconst COMMON: [string, string][] = [\n  ['--json', 'machine-readable output'],\n  ['--cwd <dir>', 'run as if started in <dir>'],\n  ['--debug', 'show stack traces and debug logs'],\n];\n\nexport const COMMANDS: CommandHelp[] = [\n  {\n    name: 'init',\n    summary: 'Create .devworkspace/ in the current project (safe to re-run)',\n    usage: ['devworkspace init [--root <dir>] [--dry-run] [--with-integrations [--yes] [--scope project|user]]'],\n    options: [\n      ['--root <dir>', 'project root (default: Git top-level or current directory)'],\n      ['--dry-run', 'show what would be created'],\n      ['--with-integrations', 'then run the same integration setup as \"devworkspace setup --integrations\"'],\n      ['--yes', 'with --with-integrations: approve machine-level and third-party installs'],\n      ...COMMON,\n    ],\n    examples: ['npx devworkspace init', 'npx devworkspace init --with-integrations --yes'],\n  },\n  {\n    name: 'setup',\n    summary: 'Single-command repository setup (inspect, initialize, discover contract & validate)',\n    usage: [\n      'devworkspace setup',\n      'devworkspace setup --integrations [--yes] [--dry-run] [--scope project|user] [--only graphify,agent-skills,ponytail]',\n    ],\n    options: [\n      ['--integrations', 'set up external integrations (Graphify, Agent Skills, Ponytail)'],\n      ['--dry-run', 'show exactly what would run; changes nothing'],\n      ['--yes', 'with --integrations: approve machine-level and third-party installs'],\n      ['--scope project|user', 'where to install (default: project; user needs --yes)'],\n      ['--only <ids>', 'comma-separated: graphify, agent-skills, ponytail'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace setup', 'devworkspace setup --json', 'devworkspace setup --integrations --yes'],\n  },\n  {\n    name: 'integrations',\n    summary: 'Show or repair the integration installation (observed, not assumed)',\n    usage: [\n      'devworkspace integrations status [--quick] [--restarted] [--strict]',\n      'devworkspace integrations repair [--yes] [--dry-run] [--only <ids>] [--scope project|user]',\n    ],\n    options: [\n      ['--quick', 'only look at files and PATH (fast, but nothing can show VERIFIED)'],\n      ['--restarted', 'record that you restarted Claude Code, clearing RESTART_REQUIRED'],\n      ['--strict', 'exit 3 unless every required integration is VERIFIED'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace integrations status', 'devworkspace integrations repair --yes'],\n  },\n  {\n    name: 'analyze',\n    summary: 'Deterministic repository discovery + generate the Claude onboarding prompt',\n    usage: ['devworkspace analyze [--dry-run]'],\n    options: [['--dry-run', 'discover and report without writing files'], ...COMMON],\n    examples: ['devworkspace analyze', 'devworkspace analyze --json'],\n  },\n  {\n    name: 'status',\n    summary: 'Concise overview: health, Git, knowledge, tasks, integrations, verification',\n    usage: ['devworkspace status [--strict] [--deep]   (read-only)'],\n    options: [['--strict', 'exit 3 when anything needs attention'], ['--deep', 'also run the integration health checks (what doctor does)'], ...COMMON],\n    examples: ['devworkspace status', 'devworkspace status --json'],\n  },\n  {\n    name: 'doctor',\n    summary: 'Check the workspace, integrations, security and portability',\n    usage: ['devworkspace doctor [--fix] [--strict]   (core workspace and integrations are reported separately)'],\n    options: [['--fix', 'safely create missing folders/ignore rules (never deletes)'], ['--strict', 'exit 3 when there are warnings'], ...COMMON],\n    examples: ['devworkspace doctor', 'devworkspace doctor --json --strict'],\n  },\n  {\n    name: 'refresh',\n    summary: 'Re-derive deterministic facts and mark knowledge stale when its evidence changed',\n    usage: ['devworkspace refresh [--dry-run]   (writes discovery files and detector facts; --dry-run writes nothing)'],\n    options: [['--dry-run', 'report stale knowledge without writing'], ...COMMON],\n    examples: ['devworkspace refresh'],\n  },\n  {\n    name: 'context',\n    summary: 'Show what DevWorkspace believes about the project',\n    usage: ['devworkspace context [--for <request>] [--role <explorer|tester|reviewer>] [--topic <prefix>] [--full]'],\n    options: [\n      ['--for <request>', 'task-aware context: only what this request needs, each item with the reason it is included (safety rules are always shown)'],\n      ['--role <role>', 'role-sliced context for AI workflows: explorer, tester, reviewer (requires --for)'],\n      ['--topic <text>', 'only facts and testing-contract entries that match <text> (safety rules are always shown)'],\n      ['--full', 'also print .devworkspace/context/*.md'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace context --topic auth',\n      'devworkspace context --for \"fix the invoice total rounding bug\"',\n      'devworkspace context --for \"fix memory leak in auth\" --role explorer',\n      'devworkspace context --for \"add regression tests\" --role tester',\n      'devworkspace context --for \"review authentication changes\" --role reviewer',\n    ],\n  },\n  {\n    name: 'fact',\n    summary: 'Record, verify or remove a piece of project knowledge',\n    usage: [\n      'devworkspace fact add --key <key> --value <text> --source <desc> [--file <rel path>]... [--source-type ai|user|file|git] [--confidence HIGH|MEDIUM|LOW] [--status VERIFIED|INFERRED|UNKNOWN]',\n      'devworkspace fact verify <key>',\n      'devworkspace fact remove <key>',\n      'devworkspace fact list',\n    ],\n    options: [\n      ['--key', 'lowercase dotted key, e.g. auth.session-store'],\n      ['--value', 'one concise sentence (no secrets, no absolute paths)'],\n      ['--file <path>', 'repository file that evidences the fact (repeatable); used for staleness'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace fact add --key auth.sessions --value \"Sessions live in Redis\" --source \"src/auth/session.ts\" --file src/auth/session.ts --source-type ai --confidence HIGH --status VERIFIED'],\n  },\n  {\n    name: 'feature',\n    summary: 'Manage feature-level knowledge and end-to-end component traces',\n    usage: [\n      'devworkspace feature list',\n      'devworkspace feature show <id>',\n      'devworkspace feature validate',\n      'devworkspace feature add --id <id> --name <name> [--entry <path>...] [--route <path>...] [--service <path>...] [--model <path>...] [--test <path>...] [--symbol <sym>]',\n    ],\n    options: [\n      ['--id <id>', 'unique feature identifier, e.g. auth.login'],\n      ['--name <name>', 'human-readable name for the feature'],\n      ['--entry <path>', 'frontend entry point path (repeatable)'],\n      ['--route <path>', 'backend route/controller path (repeatable)'],\n      ['--service <path>', 'backend service path (repeatable)'],\n      ['--model <path>', 'database model/schema path (repeatable)'],\n      ['--test <path>', 'test file path (repeatable)'],\n      ['--symbol <sym>', 'symbol name (function, class, endpoint) to verify in component files'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace feature list',\n      'devworkspace feature show auth.login',\n      'devworkspace feature validate',\n      'devworkspace feature add --id auth.login --name \"User Authentication\" --entry frontend/src/pages/Login.tsx --route backend/src/routes/auth.ts --symbol authRoutes',\n    ],\n  },\n  {\n    name: 'graph',\n    summary: 'Inspect and trace Graphify knowledge graphs',\n    usage: [\n      'devworkspace graph status',\n      'devworkspace graph trace [--from <path|query>] [--depth <n>]',\n    ],\n    options: [\n      ['--from <path|query>', 'starting node file path or symbol name to trace from'],\n      ['--depth <n>', 'maximum traversal depth (1-10, default 2)'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace graph status',\n      'devworkspace graph trace --from src/api.ts --depth 3',\n    ],\n  },\n  {\n    name: 'task',\n    summary: 'Track engineering tasks with a completion gate',\n    usage: [\n      'devworkspace task new \"<request>\" [--type BUG|FEATURE|...]',\n      'devworkspace task list [--all]          (alias: devworkspace tasks)',\n      'devworkspace task show <id>',\n      'devworkspace task status <id> <STATUS> [--note <text>]',\n      'devworkspace task update <id> [--title ..] [--criteria ..]... [--plan ..]... [--area ..]... [--blocker ..]... [--require <check>]... [--summary ..]',\n      'devworkspace task run <id> <check> [--package <dir>] [--timeout <seconds>]   (executes the contract command; read-only checks only)',\n      'devworkspace task verify <id> <check> pass|fail|skip|pending [--package <dir>] [--reason user-override] [--detail <text>]   (records a report, not an executed result)',\n      'devworkspace task tests <id> --phase baseline|after --passed <n> --failed <n>',\n      'devworkspace task attest <id> [--user-work-intact] [--knowledge-reviewed] [--final-state-inspected]',\n    ],\n    options: [\n      ['--all', 'include completed tasks'],\n      ['--package <dir>', 'with run/verify: the package the result belongs to (default: every changed package / the root)'],\n      ['--timeout <seconds>', 'with run: per-command time limit (default 600)'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace task run T-20260101-ab12 typecheck', 'devworkspace task new \"Fix the quotation email bug\"', 'devworkspace task status T-20260101-ab12 COMPLETED'],\n  },\n  {\n    name: 'testenv',\n    summary: 'Declare a test environment so database-touching checks may run (local, never committed)',\n    usage: [\n      'devworkspace testenv declare --package <dir> --check integration|security|e2e|unit [--check ...] --target \"<description>\" --yes',\n      'devworkspace testenv list',\n      'devworkspace testenv revoke --package <dir>',\n    ],\n    options: [\n      ['--package <dir>', 'package directory the declaration covers'],\n      ['--check <id>', 'check the declaration allows (repeatable)'],\n      ['--target <text>', 'words describing the environment, never a connection string'],\n      ['--yes', 'confirm that running those checks there is safe'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace testenv declare --package backend --check integration --target \"disposable docker compose stack\" --yes'],\n  },\n  {\n    name: 'decision',\n    summary: 'Record architectural/project decisions (append-only, human-readable)',\n    usage: [\n      'devworkspace decision add --title <t> --context <c> --decision <d> --consequences <q> [--supersedes <n>]',\n      'devworkspace decision list',\n      'devworkspace decision show <n>',\n    ],\n    options: COMMON,\n    examples: ['devworkspace decision list'],\n  },\n  {\n    name: 'session',\n    summary: 'Save or list short session summaries (never transcripts)',\n    usage: [\n      'devworkspace session save --goal <g> [--done <x>]... [--area <a>]... [--tests-run <t>]... [--decision-note <d>]... [--remaining <r>]... [--next <n>] [--task <id>]',\n      'devworkspace session list',\n    ],\n    options: COMMON,\n    examples: ['devworkspace session save --goal \"Fix login bug\" --done \"Added regression test\" --next \"Run e2e\"'],\n  },\n  {\n    name: 'agent',\n    summary: 'Manage coding agent integrations (claude, codex, cursor, copilot)',\n    usage: [\n      'devworkspace agent install [--agent claude|codex|cursor|copilot|all] [--dry-run]',\n      'devworkspace agent list',\n    ],\n    options: [\n      ['--agent <id>', 'agent adapter: claude, codex, cursor, copilot, or all (default: claude)'],\n      ['--dry-run', 'preview the files that would change'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace agent install --agent cursor', 'devworkspace agent install --agent all --dry-run', 'devworkspace agent list'],\n  },\n  {\n    name: 'export',\n    summary: 'Export portable project knowledge to a JSON bundle',\n    usage: ['devworkspace export [--out <file>] [--dry-run]'],\n    options: [['--out <file>', 'output path (default: devworkspace-export-<date>.json)'], ...COMMON],\n    examples: ['devworkspace export --out knowledge.json'],\n  },\n  {\n    name: 'import',\n    summary: 'Safely import an export bundle (validated; never silently overwrites)',\n    usage: ['devworkspace import <file> [--dry-run] [--overwrite] [--allow-different-project]'],\n    options: [['--overwrite', 'replace differing local files (backups are kept)'], ['--dry-run', 'show what would change'], ...COMMON],\n    examples: ['devworkspace import knowledge.json --dry-run'],\n  },\n  {\n    name: 'reset',\n    summary: 'Delete .devworkspace/ so you can start again with init (shows a plan unless --yes)',\n    usage: ['devworkspace reset [--include-agent-files] [--yes]'],\n    options: [\n      ['--yes', 'actually delete (without it, reset only shows what it would remove)'],\n      ['--include-agent-files', 'also remove managed DevWorkspace blocks and skills from agent instruction files'],\n      ['--dry-run', 'show the plan only'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace reset', 'devworkspace reset --yes', 'devworkspace reset --yes --include-agent-files && devworkspace init'],\n  },\n  {\n    name: 'migrate',\n    summary: 'Upgrade workspace files to the current schema (with backups)',\n    usage: ['devworkspace migrate [--dry-run]'],\n    options: [['--dry-run', 'list what would be migrated'], ...COMMON],\n    examples: ['devworkspace migrate'],\n  },\n];\n\nexport function topHelp(version: string): string {\n  const w = Math.max(...COMMANDS.map((c) => c.name.length));\n  return [\n    `devworkspace ${version} - project-local AI engineering workspace`,\n    '',\n    'Usage: devworkspace <command> [options]',\n    '',\n    'Commands:',\n    ...COMMANDS.map((c) => `  ${c.name.padEnd(w + 2)}${c.summary}`),\n    '',\n    'Quick start:',\n    '  cd my-project',\n    '  npx devworkspace init',\n    '  npx devworkspace analyze',\n    '  # paste .devworkspace/analysis/onboarding-prompt.md into Claude Code',\n    '',\n    'Global options: --json  --cwd <dir>  --debug  --no-color  --ascii  --help  --version',\n    '(DevWorkspace never prompts interactively; destructive commands such as reset require --yes.)',\n    'Exit codes: 0 ok · 1 failure · 2 usage error or approval needed · 3 warnings (--strict) or setup finished but not fully verified · 130 interrupted',\n    'Run \"devworkspace <command> --help\" for details.',\n  ].join('\\n');\n}\n\nexport function commandHelp(c: CommandHelp): string {\n  const w = Math.max(...c.options.map(([o]) => o.length));\n  return [\n    `devworkspace ${c.name} - ${c.summary}`,\n    '',\n    'Usage:',\n    ...c.usage.map((u) => `  ${u}`),\n    '',\n    'Options:',\n    ...c.options.map(([o, d]) => `  ${o.padEnd(w + 2)}${d}`),\n    '',\n    'Examples:',\n    ...c.examples.map((e) => `  ${e}`),\n  ].join('\\n');\n}\n"]}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"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","sourcesContent":["export interface CommandHelp {\n  name: string;\n  summary: string;\n  usage: string[];\n  options: [string, string][];\n  examples: string[];\n}\n\nconst COMMON: [string, string][] = [\n  ['--json', 'machine-readable output'],\n  ['--cwd <dir>', 'run as if started in <dir>'],\n  ['--debug', 'show stack traces and debug logs'],\n];\n\nexport const COMMANDS: CommandHelp[] = [\n  {\n    name: 'init',\n    summary: 'Create .devworkspace/ in the current project (safe to re-run)',\n    usage: ['devworkspace init [--root <dir>] [--dry-run] [--with-integrations [--yes] [--scope project|user]]'],\n    options: [\n      ['--root <dir>', 'project root (default: Git top-level or current directory)'],\n      ['--dry-run', 'show what would be created'],\n      ['--with-integrations', 'then run the same integration setup as \"devworkspace setup --integrations\"'],\n      ['--yes', 'with --with-integrations: approve machine-level and third-party installs'],\n      ...COMMON,\n    ],\n    examples: ['npx devworkspace init', 'npx devworkspace init --with-integrations --yes'],\n  },\n  {\n    name: 'setup',\n    summary: 'Single-command repository setup (inspect, initialize, discover contract & validate)',\n    usage: [\n      'devworkspace setup',\n      'devworkspace setup --agent claude-code|codex|antigravity|all [--check]',\n      'devworkspace setup --integrations [--yes] [--dry-run] [--scope project|user] [--only graphify,agent-skills,ponytail]',\n    ],\n    options: [\n      ['--agent <name>', 'configure MCP integration for agent (claude-code, codex, antigravity, all)'],\n      ['--check', 'with --agent: validate and plan without writing files'],\n      ['--integrations', 'set up external integrations (Graphify, Agent Skills, Ponytail)'],\n      ['--dry-run', 'show exactly what would run; changes nothing'],\n      ['--yes', 'with --integrations: approve machine-level and third-party installs'],\n      ['--scope project|user', 'where to install (default: project; user needs --yes)'],\n      ['--only <ids>', 'comma-separated: graphify, agent-skills, ponytail'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace setup',\n      'devworkspace setup --agent claude-code',\n      'devworkspace setup --agent antigravity --check',\n      'devworkspace setup --json',\n      'devworkspace setup --integrations --yes',\n    ],\n  },\n  {\n    name: 'integrations',\n    summary: 'Show or repair the integration installation (observed, not assumed)',\n    usage: [\n      'devworkspace integrations status [--quick] [--restarted] [--strict]',\n      'devworkspace integrations repair [--yes] [--dry-run] [--only <ids>] [--scope project|user]',\n    ],\n    options: [\n      ['--quick', 'only look at files and PATH (fast, but nothing can show VERIFIED)'],\n      ['--restarted', 'record that you restarted Claude Code, clearing RESTART_REQUIRED'],\n      ['--strict', 'exit 3 unless every required integration is VERIFIED'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace integrations status', 'devworkspace integrations repair --yes'],\n  },\n  {\n    name: 'analyze',\n    summary: 'Deterministic repository discovery + generate the Claude onboarding prompt',\n    usage: ['devworkspace analyze [--dry-run]'],\n    options: [['--dry-run', 'discover and report without writing files'], ...COMMON],\n    examples: ['devworkspace analyze', 'devworkspace analyze --json'],\n  },\n  {\n    name: 'status',\n    summary: 'Concise overview: health, Git, knowledge, tasks, integrations, verification',\n    usage: ['devworkspace status [--strict] [--deep]   (read-only)'],\n    options: [['--strict', 'exit 3 when anything needs attention'], ['--deep', 'also run the integration health checks (what doctor does)'], ...COMMON],\n    examples: ['devworkspace status', 'devworkspace status --json'],\n  },\n  {\n    name: 'doctor',\n    summary: 'Check the workspace, integrations, security and portability',\n    usage: ['devworkspace doctor [--fix] [--strict]   (core workspace and integrations are reported separately)'],\n    options: [['--fix', 'safely create missing folders/ignore rules (never deletes)'], ['--strict', 'exit 3 when there are warnings'], ...COMMON],\n    examples: ['devworkspace doctor', 'devworkspace doctor --json --strict'],\n  },\n  {\n    name: 'refresh',\n    summary: 'Re-derive deterministic facts and mark knowledge stale when its evidence changed',\n    usage: ['devworkspace refresh [--dry-run]   (writes discovery files and detector facts; --dry-run writes nothing)'],\n    options: [['--dry-run', 'report stale knowledge without writing'], ...COMMON],\n    examples: ['devworkspace refresh'],\n  },\n  {\n    name: 'context',\n    summary: 'Show what DevWorkspace believes about the project',\n    usage: ['devworkspace context [--for <request>] [--role <explorer|tester|reviewer>] [--topic <prefix>] [--full]'],\n    options: [\n      ['--for <request>', 'task-aware context: only what this request needs, each item with the reason it is included (safety rules are always shown)'],\n      ['--role <role>', 'role-sliced context for AI workflows: explorer, tester, reviewer (requires --for)'],\n      ['--topic <text>', 'only facts and testing-contract entries that match <text> (safety rules are always shown)'],\n      ['--full', 'also print .devworkspace/context/*.md'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace context --topic auth',\n      'devworkspace context --for \"fix the invoice total rounding bug\"',\n      'devworkspace context --for \"fix memory leak in auth\" --role explorer',\n      'devworkspace context --for \"add regression tests\" --role tester',\n      'devworkspace context --for \"review authentication changes\" --role reviewer',\n    ],\n  },\n  {\n    name: 'fact',\n    summary: 'Record, verify or remove a piece of project knowledge',\n    usage: [\n      'devworkspace fact add --key <key> --value <text> --source <desc> [--file <rel path>]... [--source-type ai|user|file|git] [--confidence HIGH|MEDIUM|LOW] [--status VERIFIED|INFERRED|UNKNOWN]',\n      'devworkspace fact verify <key>',\n      'devworkspace fact remove <key>',\n      'devworkspace fact list',\n    ],\n    options: [\n      ['--key', 'lowercase dotted key, e.g. auth.session-store'],\n      ['--value', 'one concise sentence (no secrets, no absolute paths)'],\n      ['--file <path>', 'repository file that evidences the fact (repeatable); used for staleness'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace fact add --key auth.sessions --value \"Sessions live in Redis\" --source \"src/auth/session.ts\" --file src/auth/session.ts --source-type ai --confidence HIGH --status VERIFIED'],\n  },\n  {\n    name: 'feature',\n    summary: 'Manage feature-level knowledge and end-to-end component traces',\n    usage: [\n      'devworkspace feature list',\n      'devworkspace feature show <id>',\n      'devworkspace feature validate',\n      'devworkspace feature add --id <id> --name <name> [--entry <path>...] [--route <path>...] [--service <path>...] [--model <path>...] [--test <path>...] [--symbol <sym>]',\n    ],\n    options: [\n      ['--id <id>', 'unique feature identifier, e.g. auth.login'],\n      ['--name <name>', 'human-readable name for the feature'],\n      ['--entry <path>', 'frontend entry point path (repeatable)'],\n      ['--route <path>', 'backend route/controller path (repeatable)'],\n      ['--service <path>', 'backend service path (repeatable)'],\n      ['--model <path>', 'database model/schema path (repeatable)'],\n      ['--test <path>', 'test file path (repeatable)'],\n      ['--symbol <sym>', 'symbol name (function, class, endpoint) to verify in component files'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace feature list',\n      'devworkspace feature show auth.login',\n      'devworkspace feature validate',\n      'devworkspace feature add --id auth.login --name \"User Authentication\" --entry frontend/src/pages/Login.tsx --route backend/src/routes/auth.ts --symbol authRoutes',\n    ],\n  },\n  {\n    name: 'graph',\n    summary: 'Inspect and trace Graphify knowledge graphs',\n    usage: [\n      'devworkspace graph status',\n      'devworkspace graph trace [--from <path|query>] [--depth <n>]',\n    ],\n    options: [\n      ['--from <path|query>', 'starting node file path or symbol name to trace from'],\n      ['--depth <n>', 'maximum traversal depth (1-10, default 2)'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace graph status',\n      'devworkspace graph trace --from src/api.ts --depth 3',\n    ],\n  },\n  {\n    name: 'task',\n    summary: 'Track engineering tasks with a completion gate',\n    usage: [\n      'devworkspace task new \"<request>\" [--type BUG|FEATURE|...]',\n      'devworkspace task list [--all]          (alias: devworkspace tasks)',\n      'devworkspace task show <id>',\n      'devworkspace task status <id> <STATUS> [--note <text>]',\n      'devworkspace task update <id> [--title ..] [--criteria ..]... [--plan ..]... [--area ..]... [--blocker ..]... [--require <check>]... [--summary ..]',\n      'devworkspace task run <id> <check> [--package <dir>] [--timeout <seconds>]   (executes the contract command; read-only checks only)',\n      'devworkspace task verify <id> <check> pass|fail|skip|pending [--package <dir>] [--reason user-override] [--detail <text>]   (records a report, not an executed result)',\n      'devworkspace task tests <id> --phase baseline|after --passed <n> --failed <n>',\n      'devworkspace task attest <id> [--user-work-intact] [--knowledge-reviewed] [--final-state-inspected]',\n    ],\n    options: [\n      ['--all', 'include completed tasks'],\n      ['--package <dir>', 'with run/verify: the package the result belongs to (default: every changed package / the root)'],\n      ['--timeout <seconds>', 'with run: per-command time limit (default 600)'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace task run T-20260101-ab12 typecheck', 'devworkspace task new \"Fix the quotation email bug\"', 'devworkspace task status T-20260101-ab12 COMPLETED'],\n  },\n  {\n    name: 'testenv',\n    summary: 'Declare a test environment so database-touching checks may run (local, never committed)',\n    usage: [\n      'devworkspace testenv declare --package <dir> --check integration|security|e2e|unit [--check ...] --target \"<description>\" --yes',\n      'devworkspace testenv list',\n      'devworkspace testenv revoke --package <dir>',\n    ],\n    options: [\n      ['--package <dir>', 'package directory the declaration covers'],\n      ['--check <id>', 'check the declaration allows (repeatable)'],\n      ['--target <text>', 'words describing the environment, never a connection string'],\n      ['--yes', 'confirm that running those checks there is safe'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace testenv declare --package backend --check integration --target \"disposable docker compose stack\" --yes'],\n  },\n  {\n    name: 'decision',\n    summary: 'Record architectural/project decisions (append-only, human-readable)',\n    usage: [\n      'devworkspace decision add --title <t> --context <c> --decision <d> --consequences <q> [--supersedes <n>]',\n      'devworkspace decision list',\n      'devworkspace decision show <n>',\n    ],\n    options: COMMON,\n    examples: ['devworkspace decision list'],\n  },\n  {\n    name: 'session',\n    summary: 'Save or list short session summaries (never transcripts)',\n    usage: [\n      'devworkspace session save --goal <g> [--done <x>]... [--area <a>]... [--tests-run <t>]... [--decision-note <d>]... [--remaining <r>]... [--next <n>] [--task <id>]',\n      'devworkspace session list',\n    ],\n    options: COMMON,\n    examples: ['devworkspace session save --goal \"Fix login bug\" --done \"Added regression test\" --next \"Run e2e\"'],\n  },\n  {\n    name: 'agent',\n    summary: 'Manage coding agent integrations (claude, codex, cursor, copilot)',\n    usage: [\n      'devworkspace agent install [--agent claude|codex|cursor|copilot|all] [--dry-run]',\n      'devworkspace agent list',\n    ],\n    options: [\n      ['--agent <id>', 'agent adapter: claude, codex, cursor, copilot, or all (default: claude)'],\n      ['--dry-run', 'preview the files that would change'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace agent install --agent cursor', 'devworkspace agent install --agent all --dry-run', 'devworkspace agent list'],\n  },\n  {\n    name: 'export',\n    summary: 'Export portable project knowledge to a JSON bundle',\n    usage: ['devworkspace export [--out <file>] [--dry-run]'],\n    options: [['--out <file>', 'output path (default: devworkspace-export-<date>.json)'], ...COMMON],\n    examples: ['devworkspace export --out knowledge.json'],\n  },\n  {\n    name: 'import',\n    summary: 'Safely import an export bundle (validated; never silently overwrites)',\n    usage: ['devworkspace import <file> [--dry-run] [--overwrite] [--allow-different-project]'],\n    options: [['--overwrite', 'replace differing local files (backups are kept)'], ['--dry-run', 'show what would change'], ...COMMON],\n    examples: ['devworkspace import knowledge.json --dry-run'],\n  },\n  {\n    name: 'reset',\n    summary: 'Delete .devworkspace/ so you can start again with init (shows a plan unless --yes)',\n    usage: ['devworkspace reset [--include-agent-files] [--yes]'],\n    options: [\n      ['--yes', 'actually delete (without it, reset only shows what it would remove)'],\n      ['--include-agent-files', 'also remove managed DevWorkspace blocks and skills from agent instruction files'],\n      ['--dry-run', 'show the plan only'],\n      ...COMMON,\n    ],\n    examples: ['devworkspace reset', 'devworkspace reset --yes', 'devworkspace reset --yes --include-agent-files && devworkspace init'],\n  },\n  {\n    name: 'migrate',\n    summary: 'Upgrade workspace files to the current schema (with backups)',\n    usage: ['devworkspace migrate [--dry-run]'],\n    options: [['--dry-run', 'list what would be migrated'], ...COMMON],\n    examples: ['devworkspace migrate'],\n  },\n  {\n    name: 'mcp',\n    summary: 'Local-first Model Context Protocol (MCP) server and agent configuration',\n    usage: [\n      'devworkspace mcp serve [--debug]',\n      'devworkspace mcp setup [--agent claude-code|codex|antigravity|all] [--check]',\n    ],\n    options: [\n      ['--agent <name>', 'agent to configure (claude-code, codex, antigravity, all)'],\n      ['--check', 'validate and plan configuration without modifying files'],\n      ...COMMON,\n    ],\n    examples: [\n      'devworkspace mcp serve',\n      'devworkspace mcp setup --agent claude-code',\n      'devworkspace mcp setup --agent antigravity --check',\n    ],\n  },\n];\n\nexport function topHelp(version: string): string {\n  const w = Math.max(...COMMANDS.map((c) => c.name.length));\n  return [\n    `devworkspace ${version} - project-local AI engineering workspace`,\n    '',\n    'Usage: devworkspace <command> [options]',\n    '',\n    'Commands:',\n    ...COMMANDS.map((c) => `  ${c.name.padEnd(w + 2)}${c.summary}`),\n    '',\n    'Quick start:',\n    '  cd my-project',\n    '  npx devworkspace init',\n    '  npx devworkspace analyze',\n    '  # paste .devworkspace/analysis/onboarding-prompt.md into Claude Code',\n    '',\n    'Global options: --json  --cwd <dir>  --debug  --no-color  --ascii  --help  --version',\n    '(DevWorkspace never prompts interactively; destructive commands such as reset require --yes.)',\n    'Exit codes: 0 ok · 1 failure · 2 usage error or approval needed · 3 warnings (--strict) or setup finished but not fully verified · 130 interrupted',\n    'Run \"devworkspace <command> --help\" for details.',\n  ].join('\\n');\n}\n\nexport function commandHelp(c: CommandHelp): string {\n  const w = Math.max(...c.options.map(([o]) => o.length));\n  return [\n    `devworkspace ${c.name} - ${c.summary}`,\n    '',\n    'Usage:',\n    ...c.usage.map((u) => `  ${u}`),\n    '',\n    'Options:',\n    ...c.options.map(([o, d]) => `  ${o.padEnd(w + 2)}${d}`),\n    '',\n    'Examples:',\n    ...c.examples.map((e) => `  ${e}`),\n  ].join('\\n');\n}\n"]}

package/dist/cli/render.d.ts

@@ -18,6 +18,7 @@ import type { FeatureItem, FeatureValidationReport } from '../features/types.js'
 import type { FeatureSummary } from '../services/features.js';
 import type { ProjectSetupResult } from '../services/setup.js';
 import type { GraphStatusResult, GraphTraceResult } from '../services/graph.js';
+import type { McpSetupResult } from '../mcp/setup.js';
 export interface Style {
     ok(s: string): string;
     warn(s: string): string;
@@ -52,6 +53,7 @@ export declare function renderTaskBrief(s: Style, t: Task, change: string, gate:
 export declare function renderTaskRun(s: Style, r: RunCheckResult, gate: GateResult, next: string): string;
 export declare function renderTask(s: Style, t: Task, gate?: GateResult, next?: string): string;
 export declare function renderAgentInstall(s: Style, r: AgentInstallResult): string;
+export declare function renderMcpSetup(s: Style, r: McpSetupResult): string;
 export declare function renderAgentList(s: Style, agents: AgentInfo[]): string;
 export declare function renderExport(s: Style, r: ExportResult): string;
 export declare function renderImport(s: Style, r: ImportResult): string;

package/dist/cli/render.js

@@ -335,6 +335,16 @@ export function renderAgentInstall(s, r) {
         L.push(`  ${s.warn(s.sym.warn)} ${r.conflicts} conflict(s) left untouched; resolve by hand and re-run.`);
     return L.join('\n');
 }
+export function renderMcpSetup(s, r) {
+    const L = [r.check ? `${s.sym.info} Check mode (dry run): no files were written.` : `${s.ok(s.sym.ok)} MCP setup completed for ${r.agent}.`];
+    for (const c of r.changes) {
+        const mark = c.kind === 'conflict' ? s.warn(s.sym.warn) : c.kind === 'unchanged' ? s.sym.info : s.ok(s.sym.ok);
+        L.push(`  ${mark} ${c.kind.toUpperCase().padEnd(9)} ${c.path}  - ${c.note}`);
+    }
+    if (r.conflicts > 0)
+        L.push(`  ${s.warn(s.sym.warn)} ${r.conflicts} conflict(s) left untouched; resolve by hand and re-run.`);
+    return L.join('\n');
+}
 export function renderAgentList(s, agents) {
     const L = ['Supported coding agent integrations:'];
     for (const a of agents) {