feat: add context7 plugin

.claude-plugin/marketplace.json

@@ -96,6 +96,12 @@
       "source": "./plugins/book-distill",
       "category": "knowledge",
       "tags": ["book", "distill", "pdf", "epub", "skill", "knowledge", "reference", "documentation"]
+    },
+    {
+      "name": "context7",
+      "source": "./plugins/context7",
+      "category": "utilities",
+      "tags": ["context7", "documentation", "library-docs", "api-reference", "tooling", "skill"]
     }
   ]
 }

.lycheeignore

@@ -0,0 +1,7 @@
+# Lychee link-check exclusions. One regex per line (matches anywhere in URL).
+
+# Vendored upstream baselines (plugins/*/skills/*/vendor/) are byte-exact
+# snapshots kept solely for drift diffing. Their relative links may point at
+# upstream sibling files that are deliberately not vendored — do not check
+# links that resolve into a vendor directory.
+/plugins/[^/]+/skills/[^/]+/vendor/

README.md

@@ -35,6 +35,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 | [`mcp-tool-audit`](plugins/mcp-tool-audit) | Skill | Audits MCP server tool definitions against MCP-spec and Anthropic tool-design criteria, returning a per-tool PASS/WARN/FAIL scorecard. Language-agnostic (Python, TypeScript, .NET). |
 | [`prototype`](plugins/prototype) | Skills | Builds throwaway code to answer a design question before committing to architecture. Ships two skills: `/prototype:logic` (an interactive terminal app over a portable state model) and `/prototype:ui` (radically different visual variants on one route). |
 | [`book-distill`](plugins/book-distill) | Skill | Distills a technical book (PDF or EPUB) into concept-organized, author-attributed skill reference files through a structured multi-session read-write pipeline, updating the target skill's routing table. |
+| [`context7`](plugins/context7) | Skill | Looks up current library documentation, API references, and code examples via Context7 — a two-step resolve-then-query workflow over the `ctx7` CLI or the consumer's Context7 MCP server, plus an upstream drift-check `update` action. |
 
 Install one: `/plugin install <plugin-name>@melodic-software`.
 

plugins/context7/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "context7",
+  "version": "0.1.0",
+  "description": "Looks up current library documentation, API references, and code examples via Context7 (ctx7 CLI or the Context7 MCP server), with a two-step resolve-then-query workflow and an upstream drift-check action.",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "license": "MIT",
+  "keywords": ["context7", "documentation", "library-docs", "api-reference", "tooling"]
+}

plugins/context7/README.md

@@ -0,0 +1,70 @@
+# context7
+
+A Claude Code plugin for looking up **current library documentation, API
+references, and code examples** via [Context7](https://context7.com) — so
+answers about libraries, frameworks, SDKs, and cloud services come from live
+docs instead of stale training data.
+
+Invoke it with `/context7:context7` (or let Claude invoke it automatically when
+a question names a library):
+
+```text
+/context7:context7 react "useEffect cleanup"
+/context7:context7 configure
+/context7:context7 update
+```
+
+## What it does
+
+- **`lookup <library> <query>`** (default) — the two-step Context7 workflow:
+  resolve the library name to a `/org/project` ID, then query its docs. Works
+  through the `ctx7` CLI, or through the Context7 MCP server when the consuming
+  project has one configured (same backend, ~1.8× more content per call).
+- **`configure`** — CLI install, `CONTEXT7_API_KEY` auth, and the Windows Git
+  Bash `MSYS_NO_PATHCONV=1` gotcha.
+- **`update`** — checks the installed `ctx7` CLI against the latest npm release
+  (`--fix` upgrades it) and diffs Upstash's upstream reference skills against
+  the plugin's bundled `vendor/` baselines, reporting anything new for manual
+  review. It never auto-rewrites the skill.
+
+## Requirements
+
+- **`ctx7` CLI** (`npm install -g ctx7@latest`) for the CLI path — or a
+  Context7 MCP server configured in the consuming project for the MCP path.
+  Either alone is enough; the skill picks whichever is available.
+- **`CONTEXT7_API_KEY`** (optional) — anonymous usage works at low rates; an
+  API key raises limits. Set it as an environment variable; never commit it.
+
+## Install
+
+```shell
+/plugin marketplace add melodic-software/claude-code-plugins
+/plugin install context7@melodic-software
+```
+
+## Configuration
+
+This plugin has no `userConfig` and ships **no MCP server** — it never opens a
+network surface by itself beyond the lookups you ask for. Two optional
+consumer-side settings:
+
+- `CONTEXT7_API_KEY` environment variable — higher rate limits for both CLI
+  and MCP paths.
+- A `context7` entry in your own MCP configuration if you want the MCP path —
+  the skill documents the exact snippet and degrades cleanly to the CLI when
+  it is absent.
+
+## Data egress note
+
+Lookup queries (your library question text) are sent to the Context7 backend
+(`context7.com` / `mcp.context7.com`). Don't put secrets in queries. The
+`ctx7` CLI also sends anonymous usage telemetry by default — set
+`CTX7_TELEMETRY_DISABLED=1` to opt out. The `update` action additionally
+fetches two public files from `raw.githubusercontent.com` (Upstash's
+reference skills) and reads the npm registry for the latest `ctx7` version —
+read-only, nothing uploaded.
+
+## License
+
+MIT (SPDX-License-Identifier: MIT). See the LICENSE file at the root of the
+melodic-software/claude-code-plugins repository.

plugins/context7/skills/context7/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: context7
+description: "Look up current library documentation, API references, and code examples via Context7 (ctx7 CLI or the Context7 MCP server — same backend) whenever a question names a library, framework, SDK, CLI tool, or cloud service, including API syntax, configuration, setup, and version-migration questions. Actions: lookup <library> <query> (default) | configure (CLI/MCP setup, auth, Windows gotchas) | update (CLI upgrade + upstream drift check)."
+argument-hint: "[lookup <library> <query> | configure | update] (default: lookup — e.g., /context7:context7 react \"useEffect cleanup\")"
+user-invocable: true
+disable-model-invocation: false
+allowed-tools:
+  - "Bash(ctx7 --version*)"
+metadata:
+  upstream-version: upstash/context7@master
+  synced: 2026-05-22
+---
+
+## Pre-computed context
+
+Installed CLI version: !`ctx7 --version 2>/dev/null || echo "not installed (run: npm install -g ctx7@latest)"`
+
+MCP availability: check your own tool list — if `mcp__context7__resolve-library-id` / `mcp__context7__query-docs` are present, the MCP path is configured.
+
+## Purpose
+
+A primary source of up-to-date library documentation. Two equivalent interfaces: CLI (`ctx7`) via npm, and the Context7 HTTP MCP server (`mcp__context7__*`) when the consuming project has it configured. Both read the same backend. Pick by workflow (see [When to use CLI vs MCP](#when-to-use-cli-vs-mcp)).
+
+**Philosophy**: training data is stale by the time you use it. Library APIs, framework defaults, best practices change. Before claiming how a library works, verify against Context7 — even for libraries you "know."
+
+## Actions
+
+| Action | When | Loads |
+|---|---|---|
+| `lookup <library> <query>` (default) | User asks about a library | [context/lookup.md](context/lookup.md) |
+| `update` | Drift check + CLI upgrade + upstream skill changes | [context/update.md](context/update.md) |
+| `configure` | First-time setup, auth, env vars, Windows gotchas | [context/cli.md](context/cli.md) |
+
+If the argument is bare (no action keyword), treat as `lookup`.
+
+## Lookup (happy path)
+
+Two-step: resolve library name → fetch docs with resolved ID.
+
+```bash
+# Step 1: name → Context7 library ID
+ctx7 library "<name>" "<question>"
+# Step 2: ID → docs (Windows Git Bash: prefix with MSYS_NO_PATHCONV=1 — see context/cli.md)
+MSYS_NO_PATHCONV=1 ctx7 docs "<libraryId>" "<question>"
+```
+
+Equivalent via MCP when the consuming project has the Context7 MCP server configured (no Windows gotcha, cleaner output, returns ~1.5-2× more content):
+
+```text
+mcp__context7__resolve-library-id(libraryName: "...", query: "...")
+mcp__context7__query-docs(libraryId: "/org/project", query: "...")
+```
+
+You MUST call `library` / `resolve-library-id` first to get a valid ID, UNLESS the user provides one in `/org/project` format. One concept per query — when a question spans several independent topics, run a separate lookup per topic. Do not run more than 3 lookup commands per topic — if you cannot find what you need, fall back to training knowledge and tell the user Context7 didn't cover it.
+
+**Do not include sensitive information** (API keys, passwords, credentials) in queries — sent to the Context7 backend.
+
+Details: query-writing, result selection, version-specific IDs, common mistakes → [context/lookup.md](context/lookup.md)
+
+## When to use CLI vs MCP
+
+Both read the same backend — results equivalent in substance. Pick by workflow.
+
+| Use the CLI (`ctx7`) when | Use the MCP (`mcp__context7__*`) when |
+|---|---|
+| Piping into `grep`, `jq`, `head`, a file | Conversational lookup where the model picks the tool naturally |
+| Dumping large docs to disk (`> docs.md`) instead of context | Default docs depth matters (MCP returns ~1.8× more content per call) |
+| Scripting, loops, Bash one-liners | Clean markdown output (no ANSI codes) |
+| No MCP server configured, or `mcp.context7.com` blocked | Zero Windows Git Bash ceremony (no `MSYS_NO_PATHCONV=1`) |
+| Structured extraction (`--json`) | Auto-discoverable from the model's tool list |
+
+More: [context/cli.md](context/cli.md), [context/mcp.md](context/mcp.md)
+
+## Update
+
+Two upstream dependencies can drift: the `ctx7` npm package, and Upstash's reference skill content. Aggregate-level stale-tracking via `metadata.upstream-version` + `metadata.synced` in the frontmatter above; the verbatim upstream baselines under `vendor/` refresh together.
+
+When CLI or upstream skill content drifts:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/update.sh"        # check only
+bash "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/update.sh" --fix  # apply CLI upgrade
+```
+
+Script (a) reports installed vs latest `ctx7` version, (b) fetches latest upstream `find-docs/SKILL.md` and `context7-cli/SKILL.md` from `upstash/context7`, (c) diffs against the `vendor/` baselines, (d) if different, reports NEW upstream guidance for manual integration into this skill. The script does NOT auto-overwrite this `SKILL.md` — customizations (Windows gotcha, CLI-vs-MCP guidance, action dispatch) must be preserved.
+
+Full protocol (merge strategy, what to preserve, maintainer-only baseline refresh) → [context/update.md](context/update.md)
+
+## What this skill does NOT do
+
+- **Does not replace multi-source research** — use your research workflow for architecture decisions or anything needing cross-referenced sources. This skill is library-doc retrieval only
+- **Does not refactor code** — retrieves docs. User's question shapes what comes back
+- **Does not cache content locally** — docs fetched fresh each call. `vendor/` baseline is verbatim upstream for skill-content drift detection only, not doc retrieval (do NOT read `vendor/` for normal lookup invocations; only when running the `update` action)
+- **Does not auto-overwrite on update** — `update` is advisory. User approves any merge before changes land
+
+## Gotchas
+
+- **Windows Git Bash**: `ctx7 docs /org/project "..."` gets path-mangled to `C:/Program Files/Git/org/project`. Always prefix with `MSYS_NO_PATHCONV=1`. `ctx7 library` is unaffected. Full detail: [context/cli.md](context/cli.md)
+- **Prefer the `CONTEXT7_API_KEY` env var over `ctx7 login`**: `ctx7 login` triggers browser OAuth and writes a token to `~/.ctx7/` — the env var is simpler and portable across machines. See [context/cli.md](context/cli.md)
+- **No content tuning**: CLI has no `--tokens` / `--limit` flag. Default depth is server-controlled. For more content per call, prefer MCP (returns ~1.8× more by default)
+- **Don't run `ctx7 skills install` into `.claude/skills/`**: this plugin owns the Context7 lookup surface. Installing Upstash's `find-docs` skill alongside creates a parallel surface that fragments lookups and drifts independently

plugins/context7/skills/context7/context/cli.md

@@ -0,0 +1,135 @@
+# CLI reference (`ctx7`)
+
+Install, configure, command reference, flags, env vars, and Windows-specific gotchas.
+
+## Install
+
+```bash
+npm install -g ctx7@latest
+ctx7 --version  # 0.3.13 or later
+```
+
+Fallback (no global install): `npx ctx7@latest <command>` — slower per-invocation, no PATH ceremony.
+
+## Authentication
+
+CLI works anonymously for low-rate usage. For higher limits, set the `CONTEXT7_API_KEY` env var:
+
+```bash
+export CONTEXT7_API_KEY="<your-key>"
+```
+
+Set it wherever your project manages local environment variables (shell profile, a gitignored local settings file, or your secret manager) — never commit the key.
+
+**Prefer the env var over `ctx7 login`** — `login` triggers browser OAuth and writes a token to `~/.ctx7/`. The env-var approach is simpler, cross-machine-portable, and doesn't pollute the user profile. If `login` was run anyway, it's harmless but redundant — delete `~/.ctx7/` to revert.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `ctx7 library <name> <query>` | Resolve library name → Context7 library ID |
+| `ctx7 docs <libraryId> <query>` | Fetch documentation for a resolved library |
+| `ctx7 setup [flags]` | Configure Context7 for an IDE (this plugin does NOT use it — see below) |
+| `ctx7 login` / `logout` / `whoami` | OAuth flow (this plugin does NOT use it — env var is enough) |
+| `ctx7 skills install <repo> [skill]` | Install skills from a GitHub repo (this plugin does NOT use it — see below) |
+| `ctx7 skills search <keywords>` | Search the Context7 skills registry |
+| `ctx7 skills suggest` | Auto-suggest skills based on project dependencies |
+| `ctx7 skills info <repo>` | Show skills available in a repository |
+| `ctx7 skills generate` | Interactive AI skill generator (Pro feature, requires login) |
+| `ctx7 skills list` | List installed skills in the current directory |
+| `ctx7 skills remove <name>` | Uninstall a skill |
+
+Short aliases: `ctx7 skills` ↔ `ctx7 skill`, `install` ↔ `i`, `list` ↔ `ls`, `search` ↔ `s`, `generate` ↔ `gen/g`.
+
+## Flags
+
+### Global
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `--base-url <url>` | `https://context7.com/api` | Point at a custom Context7 backend |
+| `-V, --version` | | Print version |
+| `-h, --help` | | Help for the current command |
+
+### Per-command (`library`, `docs`)
+
+| Flag | Purpose |
+|---|---|
+| `--json` | Structured JSON output (vs. formatted text). Useful for scripts / `jq` extraction |
+
+**No `--tokens`, `--limit`, `--format`, or `-v/--verbose` flag exists.** Default content depth is server-controlled. For more content per call, prefer MCP (`mcp__context7__query-docs`) — returns ~1.8× more content by default.
+
+### Setup / install flags (why this plugin doesn't use them)
+
+`ctx7 setup --claude --project --cli` and `ctx7 skills install /upstash/context7 find-docs --claude --yes` both install Upstash's skills into `.claude/skills/`. **This plugin does not use these** because:
+
+1. They create a parallel `find-docs/` skill that fragments the lookup surface — this plugin owns the lookup workflow
+2. `ctx7 skills install` re-fetched overwrites local customizations with zero warning — it would destroy the Windows gotcha notes, CLI-vs-MCP guidance, and action dispatch
+3. This plugin's `update` action ([update.md](update.md)) fetches upstream skill content for diffing, but integrates changes manually — a human reviews the merge
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `CONTEXT7_API_KEY` | Higher rate limits + priority. Required for `ctx7 skills generate` |
+| `CTX7_TELEMETRY_DISABLED` | Set to `1` to disable the CLI's anonymous usage telemetry |
+
+The CLI sends anonymous usage telemetry **by default** (see the Telemetry section of Context7's CLI docs at context7.com/docs/clients/cli). In privacy-sensitive environments, disable it per invocation (`CTX7_TELEMETRY_DISABLED=1 ctx7 docs ...`) or permanently by exporting the variable in your shell profile.
+
+## Windows Git Bash gotcha (REQUIRED for `docs`)
+
+On Windows with Git Bash / MSYS2, any CLI argument starting with `/` is rewritten to a Windows path. When you run:
+
+```bash
+ctx7 docs /facebook/react "useEffect cleanup"
+```
+
+Git Bash converts `/facebook/react` → `C:/Program Files/Git/facebook/react` before the CLI sees it. The CLI correctly rejects the malformed ID:
+
+```text
+✖ Invalid library ID: "C:/Program Files/Git/facebook/react"
+```
+
+**Always prefix `ctx7 docs` calls with `MSYS_NO_PATHCONV=1`:**
+
+```bash
+MSYS_NO_PATHCONV=1 ctx7 docs /facebook/react "useEffect cleanup"
+```
+
+- Prefix disables MSYS path conversion for that one invocation
+- No-op on macOS/Linux — safe to always include
+- Double-slash workaround (`//facebook/react`) does **not** work — ctx7 rejects it as malformed
+- `ctx7 library` is unaffected (its first argument doesn't start with `/`)
+
+This is a Git Bash quirk, not a `ctx7` bug. Any CLI taking `/org/project`-style IDs hits the same thing on Windows.
+
+## Composability (CLI's main advantage over MCP)
+
+Output goes to stdout in formatted text (with ANSI color codes) or JSON with `--json`. Common pipe patterns:
+
+```bash
+# Filter docs for a specific keyword
+MSYS_NO_PATHCONV=1 ctx7 docs /facebook/react "hooks" | grep -A3 -i useEffect
+
+# Strip ANSI for clean grep output
+MSYS_NO_PATHCONV=1 ctx7 docs /facebook/react "hooks" | sed 's/\x1b\[[0-9;]*m//g' | grep useEffect
+
+# Dump to disk (keeps context clean)
+MSYS_NO_PATHCONV=1 ctx7 docs /vercel/next.js "app router" > /tmp/nextjs-router.md
+
+# Extract library IDs from a search
+ctx7 library react "hooks" --json | jq -r '.[0].id'
+
+# Top 3 by benchmark score
+ctx7 library "Entity Framework Core" "tracking" --json | jq 'sort_by(-.benchmarkScore) | .[0:3] | .[].id'
+```
+
+## When to prefer the CLI (summary)
+
+- Pipe into `grep` / `jq` / `head` / a file
+- Dump large docs to disk instead of context
+- Scripting, loops, Bash one-liners
+- No MCP server configured, or restricted networks where `mcp.context7.com` is blocked
+- Structured extraction with `--json`
+
+When not to: conversational lookups where the model picks the tool — MCP is more discoverable and returns more content. See [mcp.md](mcp.md) for that side.