@mcptoolshop/claude-synergy 0.0.0 → 1.0.0

package/synergies/02-mcp-server-portability.md

@@ -0,0 +1,33 @@
+---
+name: mcp-server-portability
+title: One MCP server, every Anthropic surface
+products: [claude-code, claude-api, claude-cowork, claude-chat]
+trigger: User built an MCP server for one surface and wants it available everywhere
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# One MCP server, every Anthropic surface
+
+**Why it works:** MCP (Model Context Protocol) is the universal extension surface. The same server binary that registers in Claude Code's `.mcp.json` also plugs into Claude API (via MCP connector), Cowork (via plugin marketplace), and Claude.ai (via consumer MCP connectors). Build once, deploy everywhere.
+
+**Workflow:**
+
+1. Build the MCP server (stdio or HTTP/SSE; any language) following the [MCP spec](https://modelcontextprotocol.io)
+2. **Claude Code:** add to `.mcp.json` (project) or user `~/.claude/settings.json` (global)
+3. **Claude API:** include via [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) in Messages requests (beta since 2025-05-22)
+4. **Cowork:** publish to [claude-plugins-official](https://github.com/anthropics/claude-plugins-official) or [knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) with `.mcp.json` declaration in the plugin manifest
+5. **Claude.ai:** for consumer use, the chat product surfaces MCP connectors directly (varies by tier)
+6. **Private network:** for self-hosted MCP servers behind a firewall, use [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) (Research Preview 2026-05-19) to connect Managed Agents
+
+**Evidence:**
+
+- [Claude API release notes 2026-05-19](https://platform.claude.com/docs/en/release-notes/overview#may-19-2026): "MCP tunnels is now available as a Research Preview, so you can connect to MCP servers in your private network"
+- [Claude API release notes 2025-05-22](https://platform.claude.com/docs/en/release-notes/overview#may-22-2025): MCP connector public beta launch
+- [anthropics/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) — Cowork plugin marketplace; many entries are MCP-server-shaped
+
+**Caveats:**
+
+- Stdio servers need a runtime on the target (Node, Python, etc.); HTTP/SSE servers are more portable but need hosting
+- Some surfaces have additional auth requirements (vault credentials for Managed Agents; OAuth flows for Cowork team-shared servers)
+- As of [claude-agent-sdk-python v0.2.82 (2026-05-15)](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.82) MCP servers connect non-blocking by default; if your server *must* be ready in turn 1, mark `alwaysLoad: true`

package/synergies/03-design-to-code-bundle.md

@@ -0,0 +1,33 @@
+---
+name: design-to-code-bundle
+title: Claude Design canvas → Claude Code bundle handoff
+products: [claude-design, claude-code]
+trigger: User has a visual mockup or design iteration in Claude Design and wants to turn it into a working app
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# Claude Design canvas → Claude Code bundle handoff
+
+**Why it works:** Claude Design (research preview launched 2026-04-17 at [claude.ai/design](https://claude.ai/design)) is purpose-built for visual iteration on a multi-file canvas — designers, marketers, anyone iterating on look-and-feel. Claude Code is purpose-built for codebase work — wiring, logic, tests, deploys. The handoff bundle bridges them: design exports a `.zip` with HTML + assets + structure that Code can consume natively.
+
+**Workflow:**
+
+1. **Start in Design** at claude.ai/design — open a project, drop in HTML/screenshots/brand assets, iterate on the canvas with chat-on-the-left
+2. Iterate visually until shape is right (Design is Opus 4.7-powered specifically for this)
+3. **Export bundle** — Design produces a `.zip` containing standalone HTML + assets, or PDF/PPTX/Canva for non-code surfaces
+4. **Open bundle in Claude Code** — drop the `.zip` into a working directory, unzip, point Code at it
+5. Code takes over: wire up backend, add tests, deploy. Design's HTML is the spec
+6. **(Reverse direction)** Generate HTML/components in Code, paste/load into Design for visual iteration when stuck on design intent
+
+**Evidence:**
+
+- [Claude Design skill description](C:/Users/mikey/.claude/skills/claude-design/SKILL.md): "exports to standalone HTML / PDF / PPTX / Canva / .zip, hands off to Claude Code via a packaged bundle"
+- [Anthropic Apps release notes 2026-04-17](https://support.claude.com/en/articles/12138966-release-notes): "Claude Design, a new Anthropic Labs product for visual collaboration including designs, prototypes, slides, and one-pagers"
+- Powered by Opus 4.7 specifically for visual iteration
+
+**Caveats:**
+
+- Design is a research preview; not on the Free tier (Pro / Max / Team / Enterprise only)
+- Design is independently metered (weekly · Claude Design line in usage panel) — separate from API/Code limits
+- The bundle is a snapshot; round-trip iteration (Design → Code → Design) requires manual re-import

package/synergies/04-computer-use-cross-surface.md

@@ -0,0 +1,33 @@
+---
+name: computer-use-cross-surface
+title: Computer Use across Code / API / Claude.ai / Cowork
+products: [claude-code, claude-api, claude-chat, claude-cowork]
+trigger: User needs browser/desktop automation and wants to choose the right surface for prototyping vs production
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# Computer Use across Code / API / Claude.ai / Cowork
+
+**Why it works:** Computer Use is one underlying capability with four delivery surfaces. Pick the surface that matches stage and access model: Code MCP for prototyping with full local control, API for production headless automation, Claude.ai Pro/Max for ad-hoc tasks with zero setup, Cowork for team workflows on shared screens.
+
+**Workflow:**
+
+1. **Prototype in Claude Code** via the `computer-use` MCP server — fast iteration, all the typical Code tooling (skills, hooks, memory) available alongside
+2. **Test in Claude.ai (Pro/Max)** — no setup, single-turn or short multi-turn tasks; good for verifying the agent's perception of the screen is correct
+3. **Graduate to Claude API** for production: use the `computer_20250124` tool with the `computer-use-2025-01-24` beta header. Headless, scalable, billed per-call
+4. **Distribute via Cowork** for team workflows — Cowork added Computer Use research preview on 2026-03-23, enabling shared-screen team automation
+5. The agent prompt and skill definitions can stay constant across surfaces; only the invocation path changes
+
+**Evidence:**
+
+- [Anthropic Apps release notes 2026-03-23](https://support.claude.com/en/articles/12138966-release-notes): "Computer use research preview in Cowork and Claude Code + Dispatch improvements... Give Claude access to computer use for Pro and Max plans"
+- [Claude API release notes 2025-02-24](https://platform.claude.com/docs/en/release-notes/overview#february-24th-2025): `computer_20250124` updated tool with "hold_key, left_mouse_down, left_mouse_up, scroll, triple_click, wait" commands
+- [computer-use MCP available in Code](https://code.claude.com/docs/en/agent-view) — see MCP servers list
+
+**Caveats:**
+
+- Computer Use carries real safety considerations — agents can take destructive actions; always start with read-only scope (`request_access` tier "read") and escalate
+- Tier-"read" browsers and tier-"click" terminals/IDEs limit what computer-use can do inside them per the global computer-use protocol (see [user CLAUDE.md](C:/Users/mikey/.claude/CLAUDE.md) for the rule)
+- Cost differs significantly across surfaces — Claude.ai is included in Pro/Max; API is per-call; Code MCP is included in the Code subscription
+- Link-clicking via computer use is disallowed for safety; use the claude-in-chrome MCP for verified link navigation

package/synergies/05-ollama-cost-shifting.md

@@ -0,0 +1,36 @@
+---
+name: ollama-cost-shifting
+title: Local Ollama as cost-shifting compute partner
+products: [claude-code, ollama-intern-mcp]
+trigger: User has bulk analysis to run (repo scans, summarization, fixture generation) and wants to conserve Claude tokens for judgment
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# Local Ollama as cost-shifting compute partner
+
+**Why it works:** Claude is premium reasoning + judgment, priced accordingly. Local Ollama (running on Mike's 5080 / M5 Max) is effectively free compute, capable enough for bulk text tasks. The synergy is splitting the work: Claude orchestrates and decides, Ollama executes the long-tail.
+
+This is a Mike-specific synergy (not an Anthropic-product synergy) because the bridge tool is Mike's own [`ollama-intern-mcp`](F:/AI/ollama-intern-mcp) — but the *pattern* generalizes to any locally-hosted small model.
+
+**Workflow:**
+
+1. Claude Code session needs bulk work done (analyze 50 files, summarize a 100k-line log, generate test fixtures)
+2. Claude invokes `ollama-intern-mcp` tools via MCP — `ollama_extract`, `ollama_batch`, `ollama_pack` etc. (28 primitive tools, frozen v1.0.2)
+3. Ollama (8B, 12B, 70B depending on task) does the heavy lift locally — no API tokens consumed
+4. Returns structured output to Claude
+5. Claude reviews, integrates findings, makes the judgment call
+6. **(Optional) Hermes integration** — for longer-context summarization workloads, ollama-intern-mcp can route to a Hermes model with extended context
+
+**Evidence:**
+
+- [ollama-intern-mcp skill description](C:/Users/mikey/.claude/skills/ollama-intern/SKILL.md): "28 frozen primitive tools (15 atoms + 3 briefs + 3 packs + 7 artifact tools) for delegating bulk analysis to a local Ollama model. Hermes integration, incident pack, change pack, repo pack, delegate to 8B"
+- [Self-hosted sandboxes for Claude Managed Agents (2026-05-19)](https://platform.claude.com/docs/en/release-notes/overview#may-19-2026) — same pattern at the API layer; Anthropic now supports self-hosted execution sandboxes for Managed Agents
+- TranslateGemma 12B local pattern proven for translation workloads ([global CLAUDE.md translation rule](C:/Users/mikey/.claude/CLAUDE.md))
+
+**Caveats:**
+
+- Local model quality is the floor — don't delegate judgment-grade tasks to 8B and expect Claude-quality output
+- Cold-load latency for Ollama models can dwarf the work itself for small jobs; warm the model before batch dispatch
+- Cross-rig setup matters — M5 Max has 128GB unified memory (TRELLIS.2 1024³ capable), 5080 has 16GB VRAM; task routing should respect rig capability
+- When this graduates to API Managed Agents (per the 2026-05-19 self-hosted sandbox launch), the *same architectural pattern* applies — Anthropic-orchestrated agent, self-hosted execution

package/synergies/06-agent-sdk-graduation.md

@@ -0,0 +1,34 @@
+---
+name: agent-sdk-graduation
+title: Prototype in Claude Code, graduate to standalone Agent SDK app
+products: [claude-code, claude-agent-sdk-python, claude-agent-sdk-typescript]
+trigger: User has a working agentic workflow in Claude Code CLI and wants to ship it as a standalone product or backend service
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# Prototype in Claude Code, graduate to standalone Agent SDK app
+
+**Why it works:** Claude Code IS an Agent SDK app — it's built on `claude-agent-sdk-typescript` (v0.3.147 = parity with Code 2.1.147). The agent behavior you prototype in the CLI is byte-identical to what you'd ship via the SDK, because they share the same bundled binary. Graduation is mostly packaging + UI choice, not re-engineering.
+
+**Workflow:**
+
+1. **Prototype in Claude Code CLI.** Build skills, hooks, MCP servers, tune prompts. Use Code's full ergonomics (memory, agents view, /goal, transcript).
+2. **Identify what's stable.** Pin to a known-good Claude Code CLI version (the SDK release notes show which CLI version each SDK release bundles)
+3. **Pick the SDK** — `claude-agent-sdk-python` for Python/data-heavy/Ollama-adjacent shops, `claude-agent-sdk-typescript` for web/Bun/Node deployments
+4. **Translate session config to SDK options.** Skills directory, MCP server config, permission rules, hooks — all the same shape, just declared in code instead of `~/.claude/`
+5. **Add the UI layer** the CLI didn't need: HTTP API, web UI, scheduled jobs, queue workers, etc.
+6. **Optional: self-hosted sandbox.** For production agent workloads, run via [Claude Managed Agents with a self-hosted sandbox](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) (2026-05-19) instead of Anthropic-hosted
+
+**Evidence:**
+
+- [claude-agent-sdk-typescript v0.3.147 release](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.147): "Updated to parity with Claude Code v2.1.147"
+- [claude-agent-sdk-python releases](https://github.com/anthropics/claude-agent-sdk-python/releases) — bundled CLI version visible in each release body
+- [Claude Managed Agents launch (2026-04-08)](https://platform.claude.com/docs/en/release-notes/overview#april-8-2026): "fully managed agent harness for running Claude as an autonomous agent with secure sandboxing, built-in tools, and server-sent event streaming"
+
+**Caveats:**
+
+- 🚨 **Breaking change to audit before graduation:** [claude-agent-sdk-python v0.2.82 (2026-05-15)](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.82) replaced `TodoWrite` with `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` in headless+SDK mode. Anything wrapping the event stream and parsing `TodoWrite` is broken. See [URGENT_FINDINGS.md](../URGENT_FINDINGS.md).
+- MCP server connect is non-blocking by default since v0.2.82 — mark `alwaysLoad: true` for servers required in turn 1, or set `MCP_CONNECTION_NONBLOCKING=0` to revert
+- SDK release cadence is high (often daily); pin to a specific version, don't track latest in production
+- The TypeScript SDK has multiple sub-packages tagged differently (`sdk-vX.Y.Z`, `vertex-sdk-vX.Y.Z`, `bedrock-sdk-vX.Y.Z`) — pick the right one for your deployment target

package/synergies/07-code-review-in-ci.md

@@ -0,0 +1,33 @@
+---
+name: code-review-in-ci
+title: /code-review in GitHub Actions for automated PR review
+products: [claude-code, claude-code-action, claude-code-security-review]
+trigger: User wants Claude to review every PR in a repo using their existing local skills/hooks/conventions
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# /code-review in GitHub Actions for automated PR review
+
+**Why it works:** The same skills, hooks, and conventions that run when you invoke `/code-review` locally also run when [claude-code-action](https://github.com/anthropics/claude-code-action) runs Claude Code in CI. The agent behaves identically because it IS the same binary, with the same skills loaded from your repo. The `--comment` flag added in 2.1.147 posts findings as inline GitHub PR review comments — closing the loop.
+
+**Workflow:**
+
+1. **Local: tune `/code-review` against your codebase.** Run with different effort levels (`/code-review low`, `/code-review high`) until findings match your taste. Adjust skills in `.claude/skills/` to encode codebase-specific patterns ("don't flag X; do flag Y").
+2. **Configure** [`claude-code-action`](https://github.com/anthropics/claude-code-action) in `.github/workflows/`. The action checks out the repo, including `.claude/`, so it picks up the same skills/hooks
+3. **In the workflow step**, invoke `/code-review high --comment` (or whatever effort level you tuned to). Findings post as inline PR review comments on the changed lines
+4. **(Optional) Layer with** [claude-code-security-review](https://github.com/anthropics/claude-code-security-review) for a security-specific second pass — different effort tuning, different findings
+5. Iterate on the workflow until the comment quality is what you want; the local-vs-CI loop is fast because they share the same Claude Code binary
+
+**Evidence:**
+
+- [Claude Code 2.1.147 release notes](https://code.claude.com/docs/en/changelog#2-1-147): "Renamed `/simplify` to `/code-review`. It now reports correctness bugs at a chosen effort level (e.g., `/code-review high`); pass `--comment` to post findings as inline GitHub PR comments. The old cleanup-and-fix behavior has been removed"
+- [anthropics/claude-code-action](https://github.com/anthropics/claude-code-action) — official GH Action that runs Claude Code in CI
+- [anthropics/claude-code-security-review](https://github.com/anthropics/claude-code-security-review) — security-specific review action
+
+**Caveats:**
+
+- ⚠️ **Anything referencing `/simplify` in your skill files or hook configs now invokes a renamed command with different semantics** (was "cleanup-and-fix"; is now "report correctness bugs"). Grep your `.claude/` tree for `/simplify` before relying on this synergy. See [URGENT_FINDINGS.md](../URGENT_FINDINGS.md).
+- The action consumes Claude API tokens billed to whatever account is configured — protect with workflow concurrency limits + branch filters
+- Token cost per PR scales with diff size and effort level; budget accordingly
+- `--comment` requires the action to have GitHub write permissions on the PR (`pull-requests: write` in the workflow `permissions:` block)

package/synergies/08-universal-skill-md-format.md

@@ -0,0 +1,46 @@
+---
+name: universal-skill-md-format
+title: One SKILL.md file, three agent surfaces (Claude Code + Cursor + Codex)
+products: [claude-code, cursor, codex]
+trigger: User has a skill in `~/.claude/skills/<name>/` and wants it discoverable across multiple agents on the same machine
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# One SKILL.md file, three agent surfaces
+
+**Why it works:** Cursor explicitly treats Agent Skills as an open standard. Per [cursor.com/docs/context/skills](https://cursor.com/docs/context/skills), Cursor scans these directories at startup:
+
+- `.cursor/skills/` (project)
+- `~/.cursor/skills/` (user)
+- `.agents/skills/` + `~/.agents/skills/` (generic agent format)
+- **`.claude/skills/` + `~/.claude/skills/`** ← reads Claude Code skills directly
+- **`.codex/skills/` + `~/.codex/skills/`** ← reads OpenAI Codex skills directly
+
+Same SKILL.md + YAML frontmatter format. No duplication, no symlinking, no per-product config.
+
+**Workflow:**
+
+1. Author your skill once at `~/.claude/skills/<name>/SKILL.md` with proper frontmatter:
+   ```yaml
+   ---
+   name: my-skill
+   description: When to invoke this skill
+   ---
+   # My Skill
+   ...
+   ```
+2. Start Cursor — it picks up the skill automatically. Same for Codex if installed.
+3. Updates to the SKILL.md file are reflected in all three agents on next session.
+
+**Evidence:**
+
+- [Cursor Agent Skills docs](https://cursor.com/docs/context/skills) — direct quote: "Agent Skills is an open standard for extending AI agents with specialized capabilities."
+- [Cursor blog: agent best practices](https://cursor.com/blog/agent-best-practices) — distinguishes Skills (capability packs) from Rules (always-on context) from Agents (entry points)
+- [Anthropic Skills launch (2025-10-16)](https://platform.claude.com/docs/en/release-notes/overview#october-16-2025) — original definition
+
+**Caveats:**
+
+- **Use portable tools.** Bash + python + node are universally available; Claude-Code-specific tool names (`mcp__ccd_*`, `Skill` tool dispatcher) won't run in Cursor.
+- **Format compatibility is one-way today.** Cursor reads Claude/Codex skills, but Claude Code doesn't yet read `~/.cursor/skills/`. If you want true bidirectional portability, author in `~/.claude/skills/` as the canonical home.
+- **Frontmatter conventions differ slightly.** Anthropic's `description` field is rendered prose; Cursor's `name` + `description` are picked up the same way. Test in both surfaces before relying on advanced fields.

package/synergies/09-mcp-across-seven-surfaces.md

@@ -0,0 +1,48 @@
+---
+name: mcp-across-seven-surfaces
+title: One MCP server binary, seven agent surfaces
+products: [claude-code, cursor, continue-dev, copilot, windsurf, cody-enterprise, claude-api]
+trigger: User built an MCP server and wants it available in every IDE/agent surface they use
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# One MCP server binary, seven agent surfaces
+
+**Why it works:** MCP is the universal extension surface. As of mid-2026, MCP servers (stdio or HTTP/SSE) are consumable by:
+
+| Surface | Config location | Wrapper key | Notes |
+|---|---|---|---|
+| **Claude Code** | `.mcp.json` (project) or `~/.claude/settings.json` | `mcpServers` | Full support, ToolSearch for large catalogs |
+| **Cursor** | `.cursor/mcp.json` or `~/.cursor/mcp.json` | `mcpServers` | 40-80 tool cap per session |
+| **Continue.dev** | `.continue/mcpServers/*.json` | `mcpServers` | **Agent mode only** (not Chat/Edit) |
+| **GitHub Copilot** | `.vscode/mcp.json` (VS Code) or `mcp.json` | **`servers`** | ⚠️ wrapper key differs from everyone else |
+| **Windsurf (Cognition)** | Cascade MCP panel | `mcpServers` | First-class; MCP Marketplace; 100-tool cap |
+| **Sourcegraph Cody Enterprise** | extension settings | `mcpServers` | Free/Pro plans deprecated 2025-07-23; Enterprise only |
+| **Claude API (Managed Agents)** | MCP connector beta header | n/a (request body) | Beta; private-network access via MCP tunnels (2026-05-19) |
+
+Value shape is identical across all: `{ command, args, env }` for stdio, `{ url, headers }` for HTTP/SSE.
+
+**Workflow:**
+
+1. Build the MCP server (any language; use one of the [official SDKs](https://github.com/modelcontextprotocol)).
+2. Register in each client's config using the right wrapper key (`mcpServers` for 6 of 7; `servers` for Copilot).
+3. The same binary serves every surface.
+
+**Evidence:**
+
+- [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)
+- [Cursor MCP setup](https://forum.cursor.com/t/what-are-the-capabilities-of-mcp-json/63130)
+- [Continue.dev MCP deep-dive](https://docs.continue.dev/customize/deep-dives/mcp) — JSON config support added 2025-09-29, accepts Claude Desktop's `claude_desktop_config.json` byte-identically
+- [GitHub Copilot MCP docs](https://docs.github.com/copilot/customizing-copilot/using-model-context-protocol/extending-copilot-chat-with-mcp) — uses `"servers"` key
+- [Windsurf Cascade MCP](https://docs.windsurf.com/windsurf/cascade/mcp)
+- [Cody MCP integration](https://sourcegraph.com/blog/cody-supports-anthropic-model-context-protocol)
+- [MCP Tunnels (Claude API 2026-05-19)](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview)
+
+**Caveats / gotchas:**
+
+- **Copilot uses `"servers"` not `"mcpServers"`.** Copy-pasting Claude Code's `.mcp.json` into Copilot's `.vscode/mcp.json` will fail silently — strip the outer wrapper key.
+- **Continue.dev MCP only fires in Agent mode.** Chat/Edit modes don't see MCP tools.
+- **Tool count caps vary.** Cursor 40-80, Windsurf 100, others unbounded. Curate per-surface if you bundle a large catalog.
+- **Auth differs.** Claude Managed Agents needs vault credentials; Copilot enterprise has registry URL + access-control policy; Cursor stores keys locally per OS.
+- **Transports differ.** Stdio is universal. HTTP supported by Code/Copilot/Continue/Windsurf/API. SSE supported by Continue/Windsurf (Copilot's docs reference it but HTTP is the documented modern remote transport).

package/synergies/10-anthropic-byok-across-surfaces.md

@@ -0,0 +1,46 @@
+---
+name: anthropic-byok-across-surfaces
+title: One ANTHROPIC_API_KEY powers Claude across seven editors
+products: [claude-code, cursor, continue-dev, aider, copilot, cody-enterprise, claude-api]
+trigger: User on Claude Max or Anthropic API tier wants unified billing across multiple editors
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# One ANTHROPIC_API_KEY powers Claude across seven editors
+
+**Why it works:** BYOK (Bring Your Own Key) support is widespread enough now that one Anthropic API key from `console.anthropic.com` can drive Claude Sonnet/Opus/Haiku across every major IDE assistant.
+
+**Workflow:**
+
+1. Generate or copy your API key from [console.anthropic.com](https://console.anthropic.com/settings/keys).
+2. Wire into each surface you use:
+
+| Surface | How to wire BYOK |
+|---|---|
+| **Claude Code** | Native — uses subscription OR `ANTHROPIC_API_KEY` env. Set `--api-key` or auth via console. |
+| **Cursor** | Settings → Models → API Keys → "Anthropic API key" field. Bypasses Cursor's subscription quota. |
+| **Continue.dev** | `.continue/config.yaml` with `provider: anthropic`, key reference. First-party provider with prompt caching. |
+| **Aider** | `aider --model anthropic/claude-sonnet-4-6-20250929` with `ANTHROPIC_API_KEY` env. Aliases: `sonnet`, `haiku`, `opus`. |
+| **GitHub Copilot** | VS Code Chat "Custom Endpoint" provider (Insiders). Config in `chatLanguageModels.json` with `vendor: customendpoint`, `apiType: "messages"`, `url: https://api.anthropic.com/v1/messages`. |
+| **Cody Enterprise** | BYO key in admin settings, or route via Cody Gateway / Bedrock / Vertex. (Free/Pro plans don't apply — deprecated 2025-07-23.) |
+| **Claude API direct** | Native — same key. |
+
+3. All seven surfaces bill to the same Anthropic account. Prompt caching works wherever the surface supports it (Continue, Code, API direct).
+
+**Evidence:**
+
+- [Anthropic Console](https://console.anthropic.com)
+- [Cursor + Claude integration guide](https://www.spacecake.ai/blog/cursor-claude-integration-guide)
+- [Continue.dev Anthropic provider](https://docs.continue.dev/customize/model-providers/top-level/anthropic)
+- [Aider Anthropic docs](https://aider.chat/docs/llms/anthropic.html)
+- [VS Code AI language models / Custom Endpoint](https://code.visualstudio.com/docs/copilot/customization/language-models)
+- [Cody supported models](https://sourcegraph.com/docs/cody)
+
+**Caveats:**
+
+- **Windsurf does NOT publicly document BYOK.** Routes through Windsurf's gateway with credit pricing instead. If you need direct-billed BYOK, Windsurf is the gap.
+- **Cody Free / Cody Pro retired 2025-07-23.** Only Cody Enterprise ($59/user/mo) supports BYOK now. Indie devs migrated to Cursor / Claude Code / Amp.
+- **Prompt caching support varies.** Continue.dev caches system messages + conversation history automatically. Claude Code and direct API support caching with manual breakpoints or auto-caching. Cursor/Aider/Copilot caching support is less documented.
+- **Rate limits stack against the key, not the surface.** Heavy usage across 7 surfaces hits the same `requests/min` and `tokens/min` quotas. Plan accordingly.
+- **Routing alternatives.** For enterprises that want cloud-provider billing, all major surfaces support Bedrock / Vertex / Foundry / AWS Claude Platform routing — same models, different billing path.

package/synergies/11-claude-code-orchestrates-aider.md

@@ -0,0 +1,52 @@
+---
+name: claude-code-orchestrates-aider
+title: Claude Code orchestrates Aider for cost-shifted edits
+products: [claude-code, aider]
+trigger: User wants Claude's reasoning quality but cheaper actual edits (e.g. for repetitive refactors)
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# Claude Code orchestrates Aider for cost-shifted edits
+
+**Why it works:** [Aider](https://aider.chat) doesn't have a native MCP client, but [`disler/aider-mcp-server`](https://github.com/disler/aider-mcp-server) inverts the relationship: it wraps Aider AS an MCP server that Claude Code (or any MCP host) can call. Claude Code becomes the planner; Aider becomes the executor running cheaper models (Gemini 2.5 Flash, DeepSeek, GPT-5-mini, etc.) for the bulk of the edits.
+
+**Workflow:**
+
+1. Install Aider locally: `pip install aider-chat`
+2. Install the MCP wrapper: `git clone https://github.com/disler/aider-mcp-server`
+3. Register in Claude Code's `.mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "aider": {
+         "command": "python",
+         "args": ["/path/to/aider-mcp-server/server.py"],
+         "env": {
+           "AIDER_MODEL": "gemini/gemini-2.5-flash",
+           "GEMINI_API_KEY": "..."
+         }
+       }
+     }
+   }
+   ```
+4. In Claude Code: draft the architectural plan, decide what files need editing, then call the Aider MCP tool with: "go apply X transformation to these N files." Aider does the actual diff work with the cheaper model + its commit-per-edit discipline.
+
+**Why pay Claude for code Aider can do:** Claude excels at planning, judgment, and ambiguous decisions. Aider excels at mechanical diff application with git-commit hygiene. Cost-shifting heavy edit work to a small model saves an order of magnitude on token spend for repetitive refactors.
+
+**Evidence:**
+
+- [disler/aider-mcp-server](https://github.com/disler/aider-mcp-server) — third-party wrapper
+- [Aider Anthropic docs](https://aider.chat/docs/llms/anthropic.html) — confirms Aider supports any LiteLLM-compatible model
+- [Aider HISTORY.md](https://raw.githubusercontent.com/Aider-AI/aider/main/HISTORY.md) — main-branch entry confirms Claude 4.5/4.6 + Gemini 2.5 + DeepSeek + GPT-5.1-5.4 support
+
+**Variants:**
+
+- **Aider thinking-tokens for hard refactors:** `aider --model anthropic/claude-sonnet-4-5 --thinking-tokens 32k` runs Aider WITH Claude as the model — useful when extended thinking matters for the edit decision. Use sparingly (expensive).
+- **Conventions handoff:** Have Claude write `CONVENTIONS.md`, then `aider --read CONVENTIONS.md --message-file plan.md` to execute against a real repo with atomic commits per change.
+
+**Caveats:**
+
+- **The MCP wrapper is third-party.** Not maintained by Anthropic or Aider's primary maintainer. If reliability matters, pin to a known-good commit.
+- **Aider rewrites files in place.** Make sure git is clean before invoking; rely on Aider's per-edit commit discipline for rollback.
+- **Model selection matters.** Cheaper models (Flash, DeepSeek) work for mechanical edits but struggle with novel patterns. If Claude rejects Aider's output, fall back to running Aider with Sonnet directly.

package/synergies/12-mcp-config-format-gotcha.md

@@ -0,0 +1,60 @@
+---
+name: mcp-config-format-gotcha
+title: Copilot's MCP config wrapper key is `servers` not `mcpServers`
+products: [claude-code, cursor, continue-dev, copilot, windsurf, cody-enterprise]
+trigger: User is copy-pasting an MCP server config between Claude Code/Cursor/Continue and GitHub Copilot
+status: confirmed
+last_validated: 2026-05-21
+---
+
+# Copilot's MCP config wrapper key is `servers` not `mcpServers`
+
+**Why this matters:** Six of seven major MCP-host surfaces use `"mcpServers"` as the top-level wrapper key. **GitHub Copilot uses `"servers"`.** Same value shape — just a different parent key. Copy-pasting between configs without renaming silently fails (Copilot ignores `mcpServers` keys; sees an empty config).
+
+**Comparison:**
+
+```jsonc
+// Claude Code .mcp.json (also: Cursor, Continue, Windsurf, Cody)
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+    }
+  }
+}
+
+// GitHub Copilot .vscode/mcp.json (note the different key)
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
+    }
+  }
+}
+```
+
+**Workflow when bridging:**
+
+1. **From Claude Code → Copilot:** strip the outer `mcpServers` key, wrap the contents in `servers` instead.
+2. **From Copilot → Claude Code:** reverse — strip `servers`, wrap in `mcpServers`.
+3. **For a script that does this:**
+   ```bash
+   # Claude Code → Copilot
+   jq '{servers: .mcpServers}' .mcp.json > .vscode/mcp.json
+   ```
+
+**Evidence:**
+
+- [GitHub Copilot MCP docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) — uses `"servers"` consistently in all examples
+- [GitHub Copilot CLI MCP](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) — same key
+- [Cursor MCP docs](https://forum.cursor.com/t/what-are-the-capabilities-of-mcp-json/63130) — uses `mcpServers`
+- [Continue MCP docs](https://docs.continue.dev/customize/deep-dives/mcp) — uses `mcpServers`, explicitly notes compatibility with Claude Desktop's config
+
+**Caveats / extras:**
+
+- **Value shape is identical** across both. `{ command, args, env }` for stdio. `{ url, headers, type: "http" }` for HTTP. No translation needed within each entry.
+- **HTTP vs stdio.** Both support both transports. Copilot HTTP entries can use `"type": "http"` explicitly; some Cursor builds require it too.
+- **Why the divergence?** Likely historical — Copilot adopted MCP later and chose a config shape closer to VS Code's existing `settings.json` patterns rather than mirroring Claude Desktop's `claude_desktop_config.json` convention.
+- **Future:** an Anthropic-shipped MCP `inspector` works against both shapes by reading raw JSON. If a portable config standard ever lands, expect Copilot to align (the `mcpServers` key is the de-facto standard for everyone else).

package/synergies/INDEX.md

@@ -0,0 +1,47 @@
+# Synergies
+
+Cross-product workflows that emerge from combining multiple Anthropic surfaces. Each entry describes a composition pattern, the trigger that makes it the right answer, and the changelog evidence that enables it.
+
+The Synergy section is what makes this a product rather than a mirror. Any single changelog tells you what one product does; a synergy tells you what becomes *possible* when you compose two or three together.
+
+## Seed entries (2026-05-21)
+
+| # | Synergy | Products | Trigger |
+|---|---------|----------|---------|
+| 01 | [Skill portability](01-skill-portability.md) | Code + API + Cowork | Built a skill in Code, want to use it in a production agent |
+| 02 | [MCP server portability](02-mcp-server-portability.md) | Code + API + Cowork + Claude.ai | Built an MCP server for Code, want to reuse it everywhere |
+| 03 | [Claude Design ↔ Code bundle handoff](03-design-to-code-bundle.md) | Design + Code | Visual mockup needs to become a working app |
+| 04 | [Computer Use cross-surface](04-computer-use-cross-surface.md) | Code + API + Claude.ai (Pro/Max) + Cowork | Browser/desktop automation, prototype → production |
+| 05 | [Local Ollama as cost-shifting partner](05-ollama-cost-shifting.md) | Code + ollama-intern-mcp | Bulk analysis without burning Claude tokens |
+| 06 | [Agent SDK graduation path](06-agent-sdk-graduation.md) | Code + Agent SDK | Prototype in CLI, deploy as standalone SDK app |
+| 07 | [/code-review in GitHub Actions](07-code-review-in-ci.md) | Code + claude-code-action | Automated PR review reusing local skills/hooks |
+| 08 | [Universal SKILL.md format](08-universal-skill-md-format.md) | Code + Cursor + Codex | One skill author, three agents read it |
+| 09 | [MCP across seven surfaces](09-mcp-across-seven-surfaces.md) | Code + Cursor + Continue + Copilot + Windsurf + Cody + API | One MCP server binary, every agent surface |
+| 10 | [Anthropic BYOK across surfaces](10-anthropic-byok-across-surfaces.md) | Code + Cursor + Continue + Aider + Copilot + Cody + API | One API key, unified billing across editors |
+| 11 | [Claude Code orchestrates Aider](11-claude-code-orchestrates-aider.md) | Code + Aider | Cost-shift heavy edits to cheap model while Claude plans |
+| 12 | [MCP config format gotcha](12-mcp-config-format-gotcha.md) | Code + Cursor + Continue + Copilot + Windsurf + Cody | Bridging configs between Copilot (`servers`) and everyone else (`mcpServers`) |
+
+## Future entries (TBD)
+
+- Prompt caching across surfaces (auto-caching since 2026-02-19; `cache_miss_reason` beta 2026-05-13)
+- Memory tool across surfaces (API memory beta 2025-09-29; Claude.ai Memory free tier 2026-03-02; Code auto-memory)
+- Compaction patterns (server-side API 2026-02-05; client-side Code compaction)
+- Self-hosted Managed Agents sandboxes + local LLM intern (2026-05-19 + ollama-intern)
+- MCP tunnels for private-network MCP servers (Research Preview 2026-05-19)
+- `/goal` + Workflow tool composition (2.1.139 + 2.1.147)
+- `ant` CLI ↔ Claude API ↔ Claude Code triangulation
+- Plugin marketplace ↔ Cowork team rollout
+- Vertical marketplaces (legal, life-sciences, healthcare, financial-services) ↔ Code project setup
+
+## Schema mapping
+
+Each synergy maps to the planned DB shape:
+
+```sql
+synergies          (id, name, title, trigger, status, last_validated)
+synergy_products   (synergy_id, product_name)         -- many-to-many
+synergy_steps      (synergy_id, ordinal, text)
+synergy_evidence   (synergy_id, source_url, quote, source_kind)
+```
+
+Markdown files are the source of truth; parser populates DB tables. See [../schema.sql](../schema.sql) for current schema (which will be extended to include synergies in Tier 2).