devcouncil 0.4.0 → 0.4.2

package/README.md

@@ -1,26 +1,64 @@
 # DevCouncil: The Gated AI Orchestrator
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/bharathvbcr/DevCouncil/main/src/devcouncil/assets/devcouncil_logo_premium.png" alt="DevCouncil Logo" width="300">
+  <img src="https://raw.githubusercontent.com/bharathvbcr/DevCouncil/main/src/devcouncil/assets/devcouncil_social_preview.jpg" alt="DevCouncil gated AI orchestration" width="720">
 </p>
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![uv](https://img.shields.io/badge/managed%20by-uv-purple.svg)](https://github.com/astral-sh/uv)
 
-**"DevCouncil should not merely generate code. It should make AI-generated work prove that it satisfied the original intent."**
+## OpenAI Build Week 2026
 
-DevCouncil is a high-integrity command-line orchestration platform for AI-assisted software development. It turns AI implementation from a black-box generation task into a gated engineering workflow where every change is authorized, verified, and traceable back to a requirement.
+Coding agents -- including Codex and other prompt-taking CLIs -- often claim success without proving that the change satisfied the original requirements. DevCouncil turns that claim into a gated engineering workflow: every change is scoped, verified, and traceable back to a requirement. Model confidence is not the final authority; evidence is.
 
-DevCouncil does not replace coding agents. Its primary native path is Claude Code, followed by Codex CLI; it also works beside OpenCode, Google Antigravity CLI, Warp/Oz, Cursor, Aider, and bring-your-own prompt-taking CLIs. It owns the plan, task scope, verification loop, repair prompts, and evidence trail.
+### What judges should see
+
+1. **Provider-free red-to-green evidence gate** -- install once, then watch a controlled sample fail verification and pass after a real fix, with no API keys.
+2. **Self-contained interactive code graph** -- open the packed `demo.html` artifact and navigate filters, path highlighting, and neighborhoods (no blank canvas).
+3. **Codex / MCP agent-control path** -- status, diffs, and task tools stay correct under real project-sized JSON so an agent can resume from evidence instead of chat memory.
+
+### Judge path (package: `devcouncil@0.4.2`)
+
+DevCouncil supports macOS, Linux, and Windows. Requires Node.js 18+, Python 3.12+, and Git. No model provider key is needed for the deterministic demos below.
+
+```bash
+# Install the Build Week release:
+npm install -g devcouncil@0.4.2
+devcouncil --help
+
+# Core demo: red verdict -> apply fix -> green verdict (no API keys)
+devcouncil-build-week-demo
+# Equivalent: bash "$(npm root -g)/devcouncil/scripts/build-week-demo.sh"
+
+# Interactive graph artifact (self-contained HTML)
+mkdir -p /tmp/devcouncil-judge-demo
+dev graph demo --project-root /tmp/devcouncil-judge-demo --json
+# Open /tmp/devcouncil-judge-demo/.devcouncil/graph/demo.html
+```
+
+Checkout fallback: clone the repo and run `bash scripts/build-week-demo.sh` (`uv sync --group dev` if you need a local `dev`).
+
+### Eligible Build Week work
+
+DevCouncil existed before OpenAI Build Week. This submission covers only meaningful extensions on or after **July 13, 2026**. Eligible history begins at commit `6f5bd73` (baseline before eligible work: `3cfd5d1`). Major themes:
+
+- canonical SQLite code-intelligence index, multi-language grammars, incremental watching, graph queries/community detection, and a self-contained interactive code-graph artifact (including a ForceGraph compatibility fix for the packed demo);
+- stronger deterministic verification: stop gates, claim checking, diff-to-evidence coverage, task leases, PDG/corpus checks, bounded repair, machine-readable next actions;
+- deeper CLI, MCP, dashboard, coding-agent, and CI integration, plus the installable npm release path aimed at `0.4.2` for judges.
+
+During Build Week, Codex and GPT-5.6 were used as an engineering partner to map paths, challenge claims, run install/browser checks, implement focused repairs, and verify behavior. The maintainer set requirements, scope, and acceptance evidence. The primary Codex `/feedback` session ID is on the Devpost submission. This does **not** claim that all eligible code was authored exclusively by Codex/GPT-5.6.
+
+See [docs/build-week-demo.md](docs/build-week-demo.md) for the provider-free demo walkthrough.
 
 ## Documentation
 
+- [Build Week demo](docs/build-week-demo.md): provider-free red-to-green judge script.
 - [Quickstart](docs/quickstart.md): shortest install-to-first-task path.
 - [Daily workflow](docs/workflow.md): manual sidecar loop, verification, repair, rollback, and `dev watch`.
 - [Coding CLI integration](docs/coding-cli-integration.md): tiers, Claude Code, Codex, OpenCode, Antigravity, Cursor, Grok Build, Aider, MCP, hooks, stop gate / claim checks, and automated executors (Gemini deprecated).
 - [CLI command reference](docs/cli-reference.md): available `dev` commands.
-- [Repo map & code graph](docs/code-graph.md): `dev map` / `dev graph` — navigation, dead code, blast radius, PDG (opt-in), HTML visualizer.
+- [Repo map & code graph](docs/code-graph.md): `dev map` / `dev graph` -- navigation, dead code, blast radius, PDG (opt-in), HTML visualizer.
 - [Corpus side index](docs/corpus.md): `dev corpus` for docs/PDFs/images and optional verify gates.
 - [Hero loop](docs/hero-loop.md): certified Claude Code + MCP closed loop, leases, rigor, and `dev check --verify` on-ramp.
 - [Architecture](docs/architecture.md): components, artifact graph, state machine, gating policy, and gated execution.
@@ -152,7 +190,11 @@ DevCouncil is an application layer around coding agents. It does not just emit p
 ### Workflow Features
 
 - **Repository onboarding:** `dev setup` initializes `.devcouncil/`, generates the repo map + `AGENTS.md`/`CLAUDE.md` guides, scaffolds applicable engineering skills, runs environment checks, offers integration setup, and prints the next useful commands. Use `--skip-map` / `--skip-skills` to opt out, or `--scaffold-ci` to also write a starter GitHub Actions workflow. **`dev boot "goal"`** chains setup, `dev integrate --apply`, optional CI scaffold flags, and `dev go` in one command (see [quickstart](docs/quickstart.md)).
-- **Repository mapping:** `dev map` writes `.devcouncil/repo_map.json` and a symbol-level `.devcouncil/graph/code_graph.json`, identifies important files and subsystems, filters generated/temp files, and keeps managed `AGENTS.md` / `CLAUDE.md` workspace guides synchronized. Subsystems, entry points, neighbors, and important surfaces are inferred generically for **any** repository — grouped from the directory tree and ranked by an import-graph in-degree. Freshness uses git HEAD, tracked-file hash, and a content fingerprint so plain edits mark the map stale; a **missing map is stale** (fail-closed on hard rigor). Post-tool-use hooks and `dev map --watch` refresh incrementally. Unified analyze entry: `dev graph ingest`. Query with `dev graph query|trace|dead|search|cypher|html`. Liveness lists are capped at 5000 per list and 256 dependents per file (truncation metadata when hit). The map is also generated automatically on first init.
+- **Repository mapping:** `dev map` writes `.devcouncil/repo_map.json` and a symbol-level `.devcouncil/graph/code_graph.json`, identifies important files and subsystems, filters generated/temp files, and keeps managed `AGENTS.md` / `CLAUDE.md` workspace guides synchronized. Subsystems, entry points, neighbors, and important surfaces are inferred generically for **any** repository — grouped from the directory tree and ranked by an import-graph in-degree. Freshness uses git HEAD, tracked-file hash, and a content fingerprint so plain edits mark the map stale; a **missing map is stale** (fail-closed on hard rigor). Post-tool-use hooks and `dev map --watch` refresh incrementally. Unified analyze entry: `dev graph ingest`. Query with `dev graph query|trace|dead|search|cypher|html`. Liveness lists are capped at 5000 per list and 256 dependents per file (truncation metadata when hit). The map is also generated automatically on first init. (See [docs/code-graph.md](docs/code-graph.md) for details).
+  
+  <p align="center">
+    <img src="docs/graph_preview.png" alt="Repository Code Graph Preview" width="600">
+  </p>
 - **Engineering skills:** `dev skills` lists the bundled skills and shows which apply to the repository; `dev skills scaffold` writes them into `.claude/skills/<name>/SKILL.md`. A merged always-on `core-engineering` skill (think-before-coding, simplicity, surgical changes, goal-driven execution, evidence-grounded communication) plus domain skills (Android, iOS, Windows, web, AI training) that brief the agent on current SDKs, deprecations, and tooling before coding. Applicable skills are also embedded into `dev prompt` output.
 - **CI scaffolding:** `dev scaffold-ci` writes a starter `.github/workflows/devcouncil.yml` derived from the configured test/lint/typecheck commands, filtered to the detected language stack; it never overwrites existing CI unless `--force`. Run `dev scaffold-ci --evidence` to generate `.github/workflows/devcouncil-evidence.yml` which automates verifying PRs and uploading evidence JSON and HTML reports.
 - **Planning council:** `dev plan` turns a goal into requirements, acceptance criteria, assumptions, critique findings, and executable tasks. When advisory gaps remain, the project stays in `AWAITING_USER_DECISIONS` until you run `dev approve` (or `dev e2e`/`dev go --force`).

package/examples/build-week-demo/README.md

@@ -0,0 +1,13 @@
+# Build Week calculator sample
+
+Tiny provider-free sample used by `scripts/build-week-demo.sh`.
+
+| File | Role |
+|---|---|
+| `calc.py` | Correct calculator (green / repaired state) |
+| `broken_calc.py` | Deliberate `sub` bug used for the red evidence-gate pass |
+| `test_calc.py` | Regression checks proving `add` and `sub` |
+
+The demo script copies these into an isolated git repository, runs
+`dev check --verify` (no API keys), applies the repair, and reruns to a
+compiled zero-gap pass. See [docs/build-week-demo.md](../../docs/build-week-demo.md) and the fixture index in [examples/README.md](../README.md).

package/examples/build-week-demo/broken_calc.py

@@ -0,0 +1,11 @@
+"""Deliberately buggy calculator used only for the demo's red evidence-gate pass."""
+
+
+def add(a: int, b: int) -> int:
+    """Return the sum of ``a`` and ``b``."""
+    return a + b
+
+
+def sub(a: int, b: int) -> int:
+    """Intended to return ``a`` minus ``b`` — intentionally wrong for the demo."""
+    return a + b

package/examples/build-week-demo/calc.py

@@ -0,0 +1,11 @@
+"""Tiny calculator sample for the provider-free Build Week demo."""
+
+
+def add(a: int, b: int) -> int:
+    """Return the sum of ``a`` and ``b``."""
+    return a + b
+
+
+def sub(a: int, b: int) -> int:
+    """Return ``a`` minus ``b``."""
+    return a - b

package/examples/build-week-demo/test_calc.py

@@ -0,0 +1,21 @@
+"""Regression checks for the Build Week calculator demo."""
+
+from calc import add, sub
+
+
+def test_add() -> None:
+    assert add(2, 3) == 5
+
+
+def test_sub() -> None:
+    assert sub(5, 3) == 2
+
+
+def main() -> None:
+    test_add()
+    test_sub()
+    print("ok")
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devcouncil",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Gated orchestrator for AI-assisted software development",
   "license": "Apache-2.0",
   "homepage": "https://github.com/bharathvbcr/DevCouncil#readme",
@@ -21,7 +21,8 @@
   ],
   "bin": {
     "devcouncil": "bin/devcouncil.js",
-    "dev": "bin/devcouncil.js"
+    "dev": "bin/devcouncil.js",
+    "devcouncil-build-week-demo": "scripts/build-week-demo.sh"
   },
   "files": [
     "bin/",
@@ -35,6 +36,8 @@
     "packages/codeintel-grammars/pyproject.toml",
     "packages/codeintel-grammars/hatch_build.py",
     "packages/codeintel-grammars/src/devcouncil_codeintel_grammars/__init__.py",
+    "scripts/build-week-demo.sh",
+    "examples/build-week-demo/**",
     "pyproject.toml",
     "uv.lock",
     "README.md",
@@ -47,6 +50,8 @@
     "pack:check": "npm pack --dry-run",
     "smoke:wheel": "uv run python scripts/check-wheel-assets.py",
     "smoke:package": "node scripts/npm-runtime-smoke.mjs",
+    "smoke:registry": "node scripts/npm-registry-smoke.mjs",
+    "demo:build-week": "bash scripts/build-week-demo.sh",
     "test": "uv run pytest",
     "lint": "uv run ruff check .",
     "typecheck": "uv run mypy src",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devcouncil"
-version = "0.4.0"
+version = "0.4.2"
 description = "Gated orchestrator for AI-assisted software development"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -11,7 +11,7 @@ dependencies = [
     "pyyaml>=6.0.1",
     "sqlmodel>=0.0.19",
     "httpx>=0.27.0",
-    "gitpython>=3.1.49",
+    "gitpython>=3.1.53",
     "mcp>=1.27.2",
     "gepa>=0.1.1",
     "watchdog>=4.0.0",

package/scripts/build-week-demo.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# Provider-free red→green evidence-gate demo for OpenAI Build Week judges.
+#
+# Creates an isolated calculator git repo, runs `dev check --verify` against a
+# deliberately buggy change (blocking / red), applies the real repair + regression
+# test, then reruns to a compiled zero-gap (green) pass. No API keys required.
+#
+# Usage (checkout):
+#   bash scripts/build-week-demo.sh
+#
+# From npm global install (preferred judge path):
+#   npm install -g devcouncil@0.4.2
+#   devcouncil-build-week-demo
+#
+# Optional:
+#   BUILD_WEEK_DEMO_ROOT=/tmp/my-demo bash scripts/build-week-demo.sh
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SAMPLE_DIR="${REPO_ROOT}/examples/build-week-demo"
+GOAL='sub returns a - b'
+TEST_CMD='python test_calc.py'
+
+if [[ ! -f "${SAMPLE_DIR}/calc.py" || ! -f "${SAMPLE_DIR}/broken_calc.py" || ! -f "${SAMPLE_DIR}/test_calc.py" ]]; then
+  echo "error: missing sample files under ${SAMPLE_DIR}" >&2
+  exit 2
+fi
+
+resolve_dev() {
+  if [[ -n "${DEVCOUNCIL_DEV_BIN:-}" && -x "${DEVCOUNCIL_DEV_BIN}" ]]; then
+    printf '%s\n' "${DEVCOUNCIL_DEV_BIN}"
+    return
+  fi
+  if [[ -x "${REPO_ROOT}/.venv/bin/dev" ]]; then
+    printf '%s\n' "${REPO_ROOT}/.venv/bin/dev"
+    return
+  fi
+  if command -v dev >/dev/null 2>&1; then
+    command -v dev
+    return
+  fi
+  if [[ -x "${REPO_ROOT}/.venv/bin/python" ]]; then
+    printf '%s\n' "${REPO_ROOT}/.venv/bin/python -m devcouncil"
+    return
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    printf '%s\n' "python3 -m devcouncil"
+    return
+  fi
+  echo "error: could not find a DevCouncil CLI (dev / python -m devcouncil)" >&2
+  exit 2
+}
+
+DEV_BIN="$(resolve_dev)"
+# shellcheck disable=SC2206
+DEV=( ${DEV_BIN} )
+
+PROVIDER_FREE_ENV=(
+  -u OPENAI_API_KEY
+  -u ANTHROPIC_API_KEY
+  -u OPENROUTER_API_KEY
+  -u GEMINI_API_KEY
+  -u GOOGLE_API_KEY
+  -u AZURE_OPENAI_API_KEY
+  -u COHERE_API_KEY
+  -u MISTRAL_API_KEY
+  -u GROQ_API_KEY
+  -u DEEPSEEK_API_KEY
+  -u TOGETHER_API_KEY
+  -u FIREWORKS_API_KEY
+  -u XAI_API_KEY
+  -u DEVCOUNCIL_API_KEY
+)
+
+run_check() {
+  local label="$1"
+  echo
+  echo "────────────────────────────────────────────────────────────"
+  echo " ${label}"
+  echo "────────────────────────────────────────────────────────────"
+  # Keep set +e through return: a non-zero return under set -e aborts the script.
+  set +e
+  env "${PROVIDER_FREE_ENV[@]}" "${DEV[@]}" check --verify \
+    --project-root "${DEMO_ROOT}" \
+    --goal "${GOAL}" \
+    --test "${TEST_CMD}"
+  local rc=$?
+  return "${rc}"
+}
+
+if [[ -n "${BUILD_WEEK_DEMO_ROOT:-}" ]]; then
+  DEMO_ROOT="${BUILD_WEEK_DEMO_ROOT}"
+  rm -rf "${DEMO_ROOT}"
+  mkdir -p "${DEMO_ROOT}"
+else
+  _tmp="${TMPDIR:-/tmp}"
+  DEMO_ROOT="$(mktemp -d "${_tmp%/}/devcouncil-build-week-demo.XXXXXX")"
+  unset _tmp
+fi
+
+echo "DevCouncil Build Week demo"
+echo "  CLI:              ${DEV_BIN}"
+echo "  Sample templates: ${SAMPLE_DIR}"
+echo "  Generated repo:   ${DEMO_ROOT}"
+echo
+echo "Judges: leave this path open to inspect the repaired working tree."
+
+cd "${DEMO_ROOT}"
+git init -q
+git config user.email "build-week-demo@devcouncil.local"
+git config user.name "DevCouncil Build Week Demo"
+
+cat > calc.py <<'EOF'
+def add(a: int, b: int) -> int:
+    return a + b
+EOF
+git add calc.py
+git commit -q -m "baseline: add()"
+
+cp "${SAMPLE_DIR}/broken_calc.py" calc.py
+cp "${SAMPLE_DIR}/test_calc.py" test_calc.py
+
+echo
+echo ">>> Phase 1: RED — expect a blocking evidence-gate failure"
+START_TS="${SECONDS}"
+set +e
+run_check "RED verdict (blocking gaps expected)"
+RED_RC=$?
+set -e
+
+if [[ "${RED_RC}" -eq 0 ]]; then
+  echo
+  echo "error: expected RED (non-zero) from dev check --verify, got exit 0" >&2
+  echo "Generated repo left at: ${DEMO_ROOT}" >&2
+  exit 1
+fi
+
+echo
+echo "RED confirmed (exit ${RED_RC}): blocking gaps — change is not verified."
+
+cp "${SAMPLE_DIR}/calc.py" calc.py
+
+echo
+echo ">>> Phase 2: GREEN — apply repair + regression test, expect zero-gap pass"
+set +e
+run_check "GREEN verdict (compiled, zero blocking gaps expected)"
+GREEN_RC=$?
+set -e
+
+if [[ "${GREEN_RC}" -ne 0 ]]; then
+  echo
+  echo "error: expected GREEN (exit 0) after repair, got exit ${GREEN_RC}" >&2
+  echo "Generated repo left at: ${DEMO_ROOT}" >&2
+  exit 1
+fi
+
+GREEN_JSON_FILE="${DEMO_ROOT}/.devcouncil-demo-green.json"
+set +e
+env "${PROVIDER_FREE_ENV[@]}" "${DEV[@]}" check --verify \
+  --project-root "${DEMO_ROOT}" \
+  --goal "${GOAL}" \
+  --test "${TEST_CMD}" \
+  --json > "${GREEN_JSON_FILE}"
+JSON_RC=$?
+set -e
+if [[ "${JSON_RC}" -ne 0 ]]; then
+  echo "error: green JSON re-check failed with exit ${JSON_RC}" >&2
+  exit 1
+fi
+
+python3 - "${GREEN_JSON_FILE}" <<'PY'
+import json, sys
+from pathlib import Path
+payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
+if not payload.get("verified", False):
+    raise SystemExit("green JSON missing verified=true")
+if int(payload.get("blocking_gap_count", 1)) != 0:
+    raise SystemExit(f"green JSON still has blocking gaps: {payload.get('blocking_gap_count')}")
+if int(payload.get("gap_count", 1)) != 0:
+    raise SystemExit(f"green JSON still has gaps: {payload.get('gap_count')}")
+mode = str(payload.get("verification_mode", ""))
+if mode != "compiled":
+    raise SystemExit(f"expected verification_mode=compiled, got {mode!r}")
+print(f"JSON confirmed: verified=true, gaps=0, mode={mode}")
+PY
+
+ELAPSED=$((SECONDS - START_TS))
+echo
+echo "════════════════════════════════════════════════════════════"
+echo " Demo complete: RED then GREEN in ${ELAPSED}s"
+echo " Generated repository (inspect me):"
+echo "   ${DEMO_ROOT}"
+echo "════════════════════════════════════════════════════════════"
+
+if [[ "${ELAPSED}" -gt 60 ]]; then
+  echo "warning: demo took ${ELAPSED}s (>60s target after package install)" >&2
+fi
+
+exit 0

package/src/devcouncil/cli/commands/watch.py

@@ -210,23 +210,20 @@ def status(
 
     if payload["pending_signal_items"]:
         table = Table(title="Pending Agent Responses")
-        table.add_column("Client", style="cyan")
+        table.add_column("ID", style="cyan")
+        table.add_column("Client")
         table.add_column("Task")
-        table.add_column("Transcript", overflow="fold")
-        table.add_column("Review Command", overflow="fold")
         for signal in payload["pending_signal_items"]:
             table.add_row(
+                signal.get("id") or "",
                 signal.get("client") or "",
                 signal.get("task_id") or "(unscoped)",
-                signal.get("transcript_path") or "",
-                signal.get("review_command") or "",
             )
         console.print(table)
-        commands = [signal.get("review_command") for signal in payload["pending_signal_items"] if signal.get("review_command")]
-        if commands:
-            console.print("[cyan]Pending review commands:[/cyan]")
-            for command in commands:
-                console.print(command)
+        console.print(
+            "[dim]Sensitive transcript paths and review commands: "
+            "`dev watch signals` / `dev watch review`.[/dim]"
+        )
 
 
 @app.command("resolve")

package/src/devcouncil/indexing/viz.py

@@ -47,7 +47,7 @@ def _vendor_js() -> str:
         "nodeVal:function(){return this},linkColor:function(){return this},"
         "linkDirectionalParticles:function(){return this},"
         "linkDirectionalParticleWidth:function(){return this},"
-        "onNodeClick:function(){return this},onNodeDblClick:function(){return this},"
+        "onNodeClick:function(){return this},"
         "width:function(){return this},height:function(){return this},_missing:true};};"
     )
 
@@ -321,6 +321,8 @@ label {{ color:var(--muted); font-size:12px; display:block; }}
 label.inline {{ display:flex; align-items:center; gap:6px; margin:4px 0; }}
 label.inline input {{ width:auto; margin:0; }}
 #detail {{ margin-top:8px; font-size:12px; color:var(--muted); white-space:pre-wrap; }}
+.interaction-hint {{ margin:8px 0; padding:8px; border:1px solid #334155; border-radius:4px; background:#0f1419; color:var(--fg); font-size:12px; line-height:1.45; }}
+#counts {{ margin:8px 0 4px; font-size:12px; color:var(--accent); font-weight:600; }}
 .flag-dead {{ color:var(--dead); }}
 .badge-entry {{ color:var(--entry); font-weight:600; }}
 .list {{ list-style:none; padding:0; margin:0; font-size:12px; }}
@@ -342,6 +344,8 @@ label.inline input {{ width:auto; margin:0; }}
   </div>
   <div id="panel-graph" class="panel active">
     <h1>DevCouncil Code Graph</h1>
+    <div id="counts" aria-live="polite">Nodes: -- · Edges: -- · Filtered: --</div>
+    <div class="interaction-hint" id="interactionHint"><strong>Click</strong> a node for details. <strong>Select two nodes</strong> to highlight the shortest path. <strong>Double-click</strong> a node to expand its neighborhood.</div>
     <label>Mode</label>
     <select id="mode"><option value="file">File-level</option><option value="symbol">Symbol-level</option></select>
     <label>Search</label>
@@ -360,7 +364,7 @@ label.inline input {{ width:auto; margin:0; }}
     <label>Dead confidence</label>
     <select id="deadConf"><option value="">(any)</option><option>extracted</option><option>inferred</option><option>ambiguous</option></select>
     <div class="row"><button class="primary" id="reset">Reset view</button><button class="primary" id="clearPath">Clear path</button></div>
-    <div id="detail">Click a node for details. Select two nodes to highlight shortest path. Double-click to expand neighborhood.</div>
+    <div id="detail" class="muted">Select a node to inspect callers, callees, and path state.</div>
   </div>
   <div id="panel-dead" class="panel">
     <h1>Dead code</h1>
@@ -565,7 +569,16 @@ const g = Graph(elem)
     if (pathHighlight.size && pathHighlight.has(s) && pathHighlight.has(t)) return 3;
     return 1.5;
   }})
-  .onNodeClick(n => {{
+  .onNodeClick((n, event) => {{
+    // ForceGraph exposes click events but no double-click chain method.
+    // The native event detail increments for a double click, so use it to
+    // preserve neighbor expansion without depending on a nonexistent API.
+    if (event && event.detail >= 2) {{
+      const links = activePayload().links;
+      expandIds = neighborExpand(n.id, links, 1);
+      redraw();
+      return;
+    }}
     showDetail(n);
     if (selected.length === 1 && selected[0] === n.id) {{ selected = []; pathHighlight = new Set(); redraw(); return; }}
     if (selected.length >= 2) selected = [];
@@ -577,18 +590,31 @@ const g = Graph(elem)
       showDetail(n);
     }}
     redraw();
-  }})
-  .onNodeDblClick(n => {{
-    const links = activePayload().links;
-    expandIds = neighborExpand(n.id, links, 1);
-    redraw();
   }});
 
+function updateCounts(fd) {{
+ const totalNodes = (activePayload().nodes || []).length;
+ const totalEdges = (activePayload().links || []).length;
+ const shownNodes = (fd.nodes || []).length;
+ const shownEdges = (fd.links || []).length;
+ const el = document.getElementById("counts");
+ if (el) el.textContent = "Nodes: " + shownNodes + " / " + totalNodes + " · Edges: " + shownEdges + " / " + totalEdges + " · Filtered: " + Math.max(0, totalNodes - shownNodes) + (expandIds ? " · neighborhood focus" : "");
+}}
+
+function fitView() {{
+  if (g && typeof g.zoomToFit === 'function') {{
+    requestAnimationFrame(() => {{
+      try {{ g.zoomToFit(400, 40); }} catch (err) {{ /* vendor stub */ }}
+    }});
+  }}
+}}
+
 function redraw() {{
-  const fd = filtered();
-  g.graphData(fd);
-  g.nodeAutoColorBy(n => colorKey(n));
-  g.width(elem.clientWidth).height(elem.clientHeight);
+ const fd = filtered();
+ g.graphData(fd);
+ g.nodeAutoColorBy(n => colorKey(n));
+ g.width(elem.clientWidth).height(elem.clientHeight);
+ updateCounts(fd);
 }}
 
 function renderDeadList() {{
@@ -720,6 +746,7 @@ document.getElementById('reset').addEventListener('click', () => {{
   selected = [];
   pathHighlight = new Set();
   redraw();
+  fitView();
 }});
 document.getElementById('clearPath').addEventListener('click', () => {{
   selected = [];
@@ -730,6 +757,7 @@ window.addEventListener('resize', () => g.width(elem.clientWidth).height(elem.cl
 if (!g || typeof g.zoomToFit !== 'function') document.getElementById('vendorWarn').style.display = 'block';
 refillArea();
 redraw();
+fitView();
 renderDeadList();
 renderCommunities();
 renderProcesses();

package/src/devcouncil/integrations/mcp/handlers/cli_gate.py

@@ -38,6 +38,6 @@ async def handle_cli(root: Path, arguments: dict) -> list[TextContent]:
     if forbidden:
         return error_text("forbidden flag(s) through MCP: " + ", ".join(forbidden), code="forbidden_flags", flags=forbidden)
     try:
-        return json_text(run_cli_command(args, root))
+        return json_text(run_cli_command(args, root, truncate=True))
     except Exception as exc:
         return error_text(str(exc), code="cli_execution_error")