@gempack/squad-mcp 0.3.1 → 0.6.0

package/INSTALL.md

@@ -0,0 +1,554 @@
+# Installation guide
+
+This guide walks through installing `squad-mcp` in every supported host: Claude Code (as a plugin), and any other MCP-capable client (Claude Desktop, Cursor, Warp, Continue, etc.) via the npm package.
+
+After install you get:
+
+- 23 deterministic MCP tools (Claude Code exposes them as `mcp__squad__*`; other hosts may use a different prefix). Counts grow as new features land — the running server is authoritative; call `tools/list` to see the live count.
+- 12 MCP resources (`agent://*`, `severity://*`)
+- 3 MCP prompts (`squad_orchestration`, `agent_advisory`, `consolidator`)
+- 4 slash commands — Claude Code only:
+  - `/squad <task>` — implementation workflow
+  - `/squad-review [target]` — advisory-only review of an existing diff/branch/PR
+  - `/brainstorm <topic>` — pre-implementation research
+  - `/commit-suggest` — Conventional Commits message suggester (read-only)
+- Two on-disk stores under `.squad/` (versioned in git):
+  - `.squad/tasks.json` — atomic tasks decomposed from a PRD (see [`Tasks`](#path-d--using-the-tasks-store))
+  - `.squad/learnings.jsonl` — accept/reject decisions on past advisory findings (see [`Learnings`](#path-e--using-the-learnings-store))
+- Optional repo configuration in [`.squad.yaml`](#repo-configuration--squadyaml) (weights, skip paths, disabled agents, learnings/tasks paths, PR-posting policy).
+
+## Prerequisites
+
+- Node.js 20+ on `PATH`. Both the npm path and the Claude Code plugin path shell out to `node` (the plugin manifest runs `node ${CLAUDE_PLUGIN_ROOT}/dist/index.js`); CI tests on Node 20 and 22.
+- A host that speaks MCP (Claude Code, Claude Desktop, Cursor, Warp, Continue, …)
+- Git available on `PATH` (used by `detect_changed_files`)
+
+Verify Node:
+
+```bash
+node --version   # v20+
+```
+
+## Path A — Claude Code plugin (recommended)
+
+The plugin bundles the MCP server, the slash commands, and the agent definitions behind a single install. No JSON config to edit.
+
+1. **Add the marketplace.** In a Claude Code session, paste:
+
+   ```text
+   /plugin marketplace add ggemba/squad-mcp
+   ```
+
+   Wait for `marketplace added`.
+
+2. **Install the plugin.**
+
+   ```text
+   /plugin install squad@gempack
+   ```
+
+   Wait for `plugin installed`.
+
+3. **Restart Claude Code** (close and reopen). The slash-command registry is populated at startup, so the new `/squad` and `/squad-review` commands and the `squad` MCP server only become available after a restart.
+
+4. **Verify the install.** In a fresh prompt:
+   - Type `/squad ` (with the trailing space) — the autocomplete should suggest `/squad <task description>`.
+   - Type `/squad-review` — same check.
+   - Open Settings → MCP. You should see `squad` listed and connected.
+   - Ask Claude to call the `list_agents` tool from the `squad` MCP server. It should return 9 agents (`product-owner`, `tech-lead-planner`, `tech-lead-consolidator`, `senior-architect`, `senior-dba`, `senior-developer`, `senior-dev-reviewer`, `senior-dev-security`, `senior-qa`).
+
+5. **Use it.**
+
+   ```text
+   /squad add a /health endpoint that returns build SHA and uptime
+   /squad-review
+   /squad-review 1234        # PR number
+   /squad-review feature/x   # branch
+   ```
+
+   `/squad` runs the full Phase 0–12 orchestration (classify → score risk → pick agents → plan → Gate 1 → advisory squad → Gate 2 → implement → consolidate). `/squad-review` is review-only — it never implements, commits, or pushes.
+
+### Updating the plugin
+
+```text
+/plugin update squad@gempack
+```
+
+Then restart Claude Code.
+
+### Uninstalling
+
+```text
+/plugin uninstall squad@gempack
+/plugin marketplace remove gempack
+```
+
+## Path B — npm package (any MCP client)
+
+Use this path for hosts that don't have a plugin marketplace (Claude Desktop, Cursor, Warp, Continue, etc.) or when you want the MCP server only without the slash commands.
+
+> **Path B vs Path A — what each path provides:** Path A (Claude Code plugin) registers agents, skills, slash commands, and the MCP server via the plugin manifest. Path B (npm package) ships **only the MCP server** (`dist/index.js`); slash commands and native subagents are Claude Code-specific concepts and don't apply to non-Claude-Code MCP clients. Those clients access the same agent definitions via MCP `agent://…` resources or the `get_agent_definition` tool exposed by the server.
+>
+> If you're running Claude Code, **always prefer Path A**. Path B exists for clients without a Claude-Code plugin layer (Claude Desktop, Cursor, Warp, Continue).
+
+The package is published as [`@gempack/squad-mcp`](https://www.npmjs.com/package/@gempack/squad-mcp). You don't need to install it globally — `npx` will fetch and cache it on first run.
+
+### Version pinning and provenance
+
+The default `npx -y @gempack/squad-mcp` resolves to the latest published version on every host launch. To pin a specific version, append `@<version>`:
+
+```bash
+npx -y @gempack/squad-mcp@0.6.0
+```
+
+Releases are published from CI with [npm provenance](https://docs.npmjs.com/generating-provenance-statements). Verify the published tarball before configuring a host:
+
+```bash
+npm audit signatures @gempack/squad-mcp
+```
+
+Pin in your host config the same way (e.g. `args: ["-y", "@gempack/squad-mcp@0.6.0"]`).
+
+> **Note:** the per-host examples below use the unpinned default (`@gempack/squad-mcp`) for readability. For production setups, replace `@gempack/squad-mcp` with `@gempack/squad-mcp@<version>` in every host's `args` array.
+
+### Smoke test
+
+Verify the binary downloads and runs:
+
+```bash
+npx -y @gempack/squad-mcp
+```
+
+The server starts on stdio and waits silently for JSON-RPC on stdin (Ctrl+C to exit). Any error during `npx` resolution prints to stderr.
+
+### Claude Desktop
+
+Edit the config file:
+
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json` (unofficial — not all Claude Desktop builds support Linux). Flatpak builds sandbox `~/.config/`; check `~/.var/app/com.anthropic.Claude/config/Claude/` if the standard path doesn't load. Snap builds use `~/snap/claude/current/.config/Claude/`.
+
+Add (or merge) the `squad` entry:
+
+```json
+{
+  "mcpServers": {
+    "squad": {
+      "command": "npx",
+      "args": ["-y", "@gempack/squad-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. In a chat, the MCP indicator (hammer icon) should show the `squad` server with its tools.
+
+### Cursor
+
+Workspace-scoped: create `.cursor/mcp.json` in the repo root.
+Global: open Cursor Settings → MCP and add the same JSON.
+
+```json
+{
+  "mcpServers": {
+    "squad": {
+      "command": "npx",
+      "args": ["-y", "@gempack/squad-mcp"]
+    }
+  }
+}
+```
+
+Reload Cursor. The `squad` server appears under Settings → MCP. Tools become callable from chat.
+
+### Warp
+
+Settings → MCP servers → Add server.
+
+- **Name:** `squad`
+- **Command:** `npx`
+- **Args:** `["-y", "@gempack/squad-mcp"]`. If your Warp build's UI takes a single space-separated string instead, enter `-y @gempack/squad-mcp`.
+
+Save. The server status should turn green.
+
+### Continue (VS Code / JetBrains)
+
+In `~/.continue/config.json` (or the workspace equivalent):
+
+```json
+{
+  "mcpServers": {
+    "squad": {
+      "command": "npx",
+      "args": ["-y", "@gempack/squad-mcp"]
+    }
+  }
+}
+```
+
+Reload the Continue extension.
+
+> Older Continue releases (pre-1.x) used `experimental.modelContextProtocolServers` with a `transport` envelope. If your build does not pick up the `mcpServers` key, check the [Continue MCP docs](https://docs.continue.dev/customize/deep-dives/mcp) for the schema your version expects.
+
+### Any other MCP client
+
+Same shape. The server is a stdio MCP server. Command + args:
+
+```text
+command: npx
+args:    -y @gempack/squad-mcp
+```
+
+Most hosts accept either a JSON config block or a UI form with these two fields.
+
+### Faster startup / offline / corporate-proxy setups
+
+Install once globally and reference the binary by name (avoids the per-launch `npx` resolution):
+
+```bash
+npm install -g @gempack/squad-mcp
+```
+
+Then in any host config, replace `command: npx` + `args: ["-y", "@gempack/squad-mcp"]` with:
+
+```json
+{
+  "command": "squad-mcp",
+  "args": []
+}
+```
+
+This also works behind a registry proxy that rejects on-the-fly `npx` lookups.
+
+## Path C — From source (development)
+
+```bash
+git clone https://github.com/ggemba/squad-mcp.git
+cd squad-mcp
+npm install
+npm run build
+node dist/index.js   # speaks MCP over stdio
+```
+
+To point a host at your local build, replace `command: npx, args: -y @gempack/squad-mcp` with:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/squad-mcp/dist/index.js"]
+}
+```
+
+## Repo configuration — `.squad.yaml`
+
+Drop a `.squad.yaml` (or `.squad.yml`) at the workspace root to override defaults per-project. Versioned with the code. Picked up automatically by the composers (`compose_squad_workflow`, `compose_advisory_bundle`).
+
+All keys optional; partial files merge with package defaults. Cached by mtime — long-running MCP servers pick up edits without restart.
+
+```yaml
+# .squad.yaml — example for a regulated fintech backend
+
+# Rubric weights (must sum to 100 across the agents you list).
+weights:
+  senior-dev-security: 30
+  senior-dba: 22
+  senior-developer: 20
+  senior-architect: 15
+  senior-qa: 13
+
+# Per-dimension flag threshold (default 75).
+threshold: 80
+
+# Quality floor: APPROVED with weighted score below this becomes CHANGES_REQUIRED.
+min_score: 75
+
+# Files excluded from advisory.
+skip_paths:
+  - "docs/**"
+  - "**/*.md"
+  - "**/generated/**"
+
+# Agents not relevant for this repo.
+disable_agents:
+  - product-owner
+
+# Tasks store (Path D below).
+tasks:
+  path: .squad/tasks.json
+  enabled: true
+
+# Learnings store (Path E below).
+learnings:
+  path: .squad/learnings.jsonl
+  max_recent: 50
+  enabled: true
+
+# PR posting (used by /squad-review with PR refs).
+pr_posting:
+  auto_post: false
+  request_changes_below_score: 60
+  omit_attribution_footer: false
+```
+
+Validation is strict: weights must sum to 100, unknown agent names rejected, threshold/min_score 0-100. `force_agents` in tool calls still wins over `disable_agents`.
+
+## Path D — Using the tasks store
+
+The squad's biggest source of token bloat is re-analysing the whole repo on every prompt. The tasks store fixes that: a PRD is decomposed into atomic tasks up front; the squad runs against ONE task's narrowed scope at a time.
+
+**Decompose a PRD (Claude Code):**
+
+```
+/squad-tasks docs/my-prd.md
+```
+
+The skill:
+
+1. Calls `compose_prd_parse` with the PRD text.
+2. Decomposes via the host LLM (no provider keys on the server).
+3. Shows you the parsed tasks; waits for your "record".
+4. Calls `record_tasks` only after confirmation.
+
+**Work tasks:**
+
+```
+/squad-next        # picks the highest-priority ready task
+/squad-task 5      # explicit pick by id
+```
+
+For each task, `slice_files_for_task` narrows the changed-files list to the task's `scope` glob; `compose_squad_workflow` runs against that slice with `agent_hints` as `force_agents` so only the relevant specialists wake up. When done, the skill flips status via `update_task_status`.
+
+**CLI for non-MCP environments:**
+
+```bash
+echo '[{"title":"Add CSRF","scope":"src/api/**"}]' | node tools/record-tasks.mjs
+node tools/list-tasks.mjs --status pending
+node tools/next-task.mjs --json
+node tools/update-task-status.mjs --task 5 --status done
+```
+
+The tasks file (`.squad/tasks.json` by default) is intended to live in git so the team's decomposition ships with the repo.
+
+## Path E — Using the learnings store
+
+Once `/squad-review` produces a verdict, you can record per-finding decisions (accept / reject + reason) into `.squad/learnings.jsonl`. Future advisory runs read the recent tail and inject it into agent + consolidator prompts so the squad stops re-raising findings the team has already considered.
+
+**Record a decision (Claude Code):**
+
+```
+record reject senior-dev-security "missing CSRF on POST /api/refund"
+  reason: CSRF terminated at API gateway
+  scope: src/api/**
+```
+
+The skill restates the decision and waits for explicit confirmation before calling `record_learning`. Per-finding authorisation is required — silence or "thanks" is not authorisation.
+
+**CLI helper:**
+
+```bash
+node tools/record-learning.mjs --reject \
+  --agent senior-dev-security \
+  --finding "missing CSRF on POST /api/refund" \
+  --reason "CSRF terminated at API gateway" \
+  --scope "src/api/**" \
+  --pr 42
+```
+
+The journal is append-only by design — corrections are appended, never amended.
+
+## Path F — Posting `/squad-review` to GitHub PRs
+
+When `/squad-review #42` runs, the verdict + scorecard can be posted to the PR via `gh pr review`. Default behaviour: dry-run + confirmation.
+
+```bash
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42 --dry-run
+# review the body, then:
+echo '<consolidation JSON>' | node tools/post-review.mjs --pr 42
+```
+
+The CLI maps verdict → `gh` action deterministically (APPROVED → `--approve`, CHANGES_REQUIRED → `--comment`, REJECTED → `--request-changes`). Set `pr_posting.auto_post: true` in `.squad.yaml` to skip the second confirmation, but the skill still always shows the body before posting.
+
+Inviolable: never amend or delete a posted review through this skill (re-run for a fresh review); never post `--request-changes` on a PR you do not own without explicit user instruction.
+
+## Local override of agent definitions
+
+The bundled agent markdowns can be overridden without forking. The loader picks ONE local override directory:
+
+- If `SQUAD_AGENTS_DIR` is set, that path is used **exclusively** (the platform default is not consulted).
+- Otherwise: `%APPDATA%\squad-mcp\agents` on Windows, `$XDG_CONFIG_HOME/squad-mcp/agents` on Unix (falls back to `~/.config/squad-mcp/agents` if `XDG_CONFIG_HOME` is unset).
+
+Per-file resolution: if the agent's `*.md` exists in the chosen local directory, it wins. Otherwise, the embedded default bundled in the package is used.
+
+**Security: override files are agent system prompts.** Files in the local override directory are loaded verbatim and rendered into the LLM's context with full agent authority. Treat the directory as code:
+
+- It must be writable only by the running user.
+- Never place it on a shared volume, network mount, or world-writable path.
+- `SQUAD_AGENTS_DIR` must never be set from untrusted input (env files, CI variables sourced from PRs, etc.).
+
+### Allowlist (since v0.4.0)
+
+The override directory is validated at load time. It must resolve (after symlink realpath) inside one of these user-controlled prefixes:
+
+- `os.homedir()` — your home directory
+- `APPDATA` and `LOCALAPPDATA` (Windows)
+- `XDG_CONFIG_HOME` or `~/.config` (Unix)
+- `process.cwd()` — the host's working directory at launch
+
+UNC paths (`\\server\share\…`) and device-namespace paths (`\\?\…`, `\\.\…`) on Windows are rejected before any filesystem access. Per-file symlinks that escape the override directory silently fall back to the embedded default for that file.
+
+If the validation fails, the MCP server throws `OVERRIDE_REJECTED` on the first tool call that resolves an agent. The host shows the structured error so the misconfiguration surfaces immediately rather than degrading silently.
+
+### Escape hatch: SQUAD_AGENTS_ALLOW_UNSAFE
+
+For power users on unusual paths (NixOS, custom CI runners, `/opt/…`), set `SQUAD_AGENTS_ALLOW_UNSAFE=1` in the environment that launches the MCP host. This bypasses the allowlist while still rejecting malformed input (NUL bytes, ADS markers, tilde-prefixed paths). Every load logs a warn-level banner so the decision stays auditable.
+
+### Filesystem permissions (since v0.4.0)
+
+`init_local_config` creates the override directory and copied agent files with restrictive permissions:
+
+- **Unix:** directory is `chmod 0o700` (user-only rwx) and each agent file is `chmod 0o600` (user-only rw). The explicit `chmod` overrides any permissive `umask`.
+- **Windows:** `%APPDATA%` typically inherits a user-only DACL on stand-alone profiles, and the loader does not verify Windows ACLs at runtime. On managed, domain-joined, or VDI machines the inherited DACL may be broader; verify with `icacls "$env:APPDATA\squad-mcp\agents"` if the host is multi-user. For custom `SQUAD_AGENTS_DIR` paths outside `APPDATA`, the directory inherits the parent's DACL — set the ACL explicitly before pointing the env var there.
+
+`agent-loader` checks the resolved override directory at startup and emits a `warn`-level log once per process if it is world-writable (`mode & 0o002 !== 0` on Unix). To remediate:
+
+```bash
+chmod 700 "$SQUAD_AGENTS_DIR"
+chmod 600 "$SQUAD_AGENTS_DIR"/*.md
+```
+
+The warning does not block the override — it is advisory. Override files are still loaded and used.
+
+Seed the local directory with editable copies:
+
+```text
+Call the `init_local_config` MCP tool from your host.
+```
+
+Then edit any `*.md` in that directory. Restart the host (or reconnect the MCP server) to pick up changes.
+
+## Optional hardening — commit-suggest skill
+
+The `commit-suggest` skill is read-only by spec and never adds AI co-author trailers, but the rule is enforced at the prompt layer only — a sufficiently adversarial prompt-injection or model regression could violate it. For repos where you want a structural guarantee, install the bundled `commit-msg` hook:
+
+```bash
+# Per-repo install
+cp tools/git-hooks/commit-msg .git/hooks/commit-msg
+chmod +x .git/hooks/commit-msg
+
+# Or repo-wide enforcement on every clone (preferred):
+git config core.hooksPath tools/git-hooks
+```
+
+The hook rejects any commit whose message contains `Co-Authored-By: Claude/Anthropic/GPT/OpenAI/Gemini/Copilot/AI`, `Generated with [Claude Code]`, `Made by AI`, or `<noreply@anthropic.com>` trailers. Comment lines (`#`-prefixed) are ignored so commit-message templates can still document the rule.
+
+For host-level enforcement of read-only behavior during `/commit-suggest` invocations, add a `permissions.deny` block to your Claude Code project settings. Example `.claude/settings.json` snippet:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(git commit*)",
+      "Bash(git add*)",
+      "Bash(git push*)",
+      "Bash(git reset*)",
+      "Bash(git rebase*)",
+      "Bash(git merge*)",
+      "Bash(git checkout*)",
+      "Bash(git switch*)",
+      "Bash(git stash*)",
+      "Bash(git tag*)",
+      "Bash(git branch*)",
+      "Bash(git apply*)",
+      "Bash(git cherry-pick*)",
+      "Bash(git revert*)",
+      "Bash(git rm*)",
+      "Bash(git mv*)",
+      "Bash(git restore*)",
+      "Bash(git clean*)",
+      "Bash(git update-ref*)"
+    ]
+  }
+}
+```
+
+Both layers compose: prompt rule, `permissions.deny`, and the `commit-msg` hook. A tampered skill or a prompt-injection attempt has to defeat all three.
+
+## Bundled skills
+
+The plugin ships these skills under `skills/` (auto-registered when the plugin is enabled):
+
+| Skill            | Trigger                                                                                         | Purpose                                                                                                                                                                                                                           |
+| ---------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `squad`          | `/squad <task>`, `/squad-review [tgt]`, `/squad-tasks <prd>`, `/squad-next`, `/squad-task <id>` | Single skill, three modes. Implement runs the full orchestration. Review runs the advisory portion only on an existing diff/branch/PR. Tasks decomposes a PRD into atomic tasks and runs the squad on one task's scope at a time. |
+| `commit-suggest` | `/commit-suggest`                                                                               | Read-only Conventional Commits message suggester. No AI co-author trailers.                                                                                                                                                       |
+| `brainstorm`     | `/brainstorm <topic>`                                                                           | Pre-implementation exploration. Web research + multi-agent perspectives + options matrix with cited sources. Produces no code.                                                                                                    |
+
+Workflow positioning:
+
+```
+/brainstorm   ->  decide what to build (research + options)
+     v
+/squad        ->  implement what was decided
+     v
+/squad-review ->  review what was implemented
+     v
+/commit-suggest -> craft the commit message
+```
+
+`/brainstorm` examples:
+
+```
+/brainstorm choosing between SQLite and PostgreSQL for a desktop app
+-> Default depth: medium (~6 web queries + 2-3 agents)
+
+/brainstorm --depth deep how to design idempotent payment retries
+-> 10+ queries + 4 agents + tech-lead consolidator
+
+/brainstorm --no-web should we extract this module into a separate package
+-> Agents-only (offline / repo-internal topic)
+
+/brainstorm --focus security how to store API keys in a desktop app
+-> Forces senior-dev-security as the primary specialist
+```
+
+## Verification checklist
+
+After install, regardless of host:
+
+- [ ] `squad` MCP server shows as connected in the host's MCP settings.
+- [ ] `list_agents` tool returns 9 agents (names: `product-owner`, `tech-lead-planner`, `tech-lead-consolidator`, `senior-architect`, `senior-dba`, `senior-developer`, `senior-dev-reviewer`, `senior-dev-security`, `senior-qa`).
+- [ ] `compose_squad_workflow` with arguments `{"workspace_root": "<absolute path to a git repo>", "user_prompt": "smoke"}` returns `work_type`, `risk`, `squad.agents`. Requires a git repo with at least one prior commit (the tool defaults `base_ref` to `HEAD~1` internally). **`workspace_root` must be an absolute path** — relative paths are rejected with `PATH_INVALID`.
+- [ ] Resources `agent://senior-architect` and `severity://_severity-and-ownership` are readable.
+- [ ] (Claude Code only) `/squad`, `/squad-review`, `/brainstorm`, and `/commit-suggest` autocomplete.
+
+## Troubleshooting
+
+**`/plugin marketplace add` fails with "not found".**
+Make sure you typed `ggemba/squad-mcp` exactly. The marketplace manifest lives at `.claude-plugin/marketplace.json` on the `main` branch of that repo.
+
+**Plugin installed but `/squad` does not appear.**
+Restart Claude Code. The slash command registry is populated at startup. If still missing, run `/plugin list` and confirm `squad@gempack` is listed and enabled.
+
+**MCP server shows as failed / disconnected.**
+Check the host's MCP log:
+
+- Claude Code: Help → Show Logs → MCP.
+- Claude Desktop: `%APPDATA%\Claude\logs\mcp-server-squad.log` (Windows), `~/Library/Logs/Claude/mcp-server-squad.log` (macOS), `~/.config/Claude/logs/mcp-server-squad.log` (Linux — note that Claude Desktop on Linux is unofficial; verify your build).
+
+The log can include workspace file paths and `git diff` output. Review and redact before sharing for support.
+
+Common causes: Node not on `PATH`, corporate proxy blocking npm, or `npx` cache permission errors. Run `npx -y @gempack/squad-mcp` in a terminal to surface the real error.
+
+**`detect_changed_files` returns an error.**
+The tool runs `git diff --name-status --no-renames` (renames are reported as add+delete pairs) and is hardened: 10s timeout, 1MB stdout cap, allowlisted subcommands only. Verify `git --version` works and the workspace is a git repo. Refs must satisfy: matches `^[a-zA-Z0-9_/][a-zA-Z0-9_./-]*$`, max 200 chars, no leading `-`, no trailing `.`, must not contain `..`, `@{`, or `.lock`.
+
+**Tools work but the agents look wrong.**
+You probably have a stale local override. If `SQUAD_AGENTS_DIR` is set, only that directory is consulted; otherwise check `%APPDATA%\squad-mcp\agents` (Windows) or `$XDG_CONFIG_HOME/squad-mcp/agents` / `~/.config/squad-mcp/agents` (Unix). Delete or edit the file — the loader prefers the local copy over the bundled defaults.
+
+**Tools missing on Cursor / Warp after editing JSON.**
+Both hosts cache the MCP server list. Fully quit and relaunch (not just reload window).
+
+## Where to file issues
+
+<https://github.com/ggemba/squad-mcp/issues> — include host name + version, OS, Node version, and the relevant log excerpt.