Expand plugin: agent, slash commands, multi-peer, CLAUDE context, CI

- LICENSE file (Apache-2.0)
- Drop brittle tool count from README; reference the peer's live tool set instead
- Author set to "Convex Foundation and contributors"
- Two MCP bindings: convex-testnet (public HF) and convex-local (localhost), each with its own URL/token env var
- CLAUDE.md at plugin root injects Convex terminology (juice, copper, peer, lattice, CPoS, protonet) and British spelling
- convex subagent preloaded with platform context and tool-selection guidance
- /convex:faucet and /convex:explore slash commands for common flows
- Troubleshooting section in README covering unreachable peers, MCP_TIMEOUT, 401/403, elevated ops
- GitHub Actions workflow validating plugin.json, .mcp.json, and agent/command frontmatter
- CHANGELOG with initial entries

Author: mikera

.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "convex",
-  "description": "Convex peer integration for Claude Code. Exposes ~34 MCP tools covering queries, transactions, cryptography, account management, signing service and live state watches, plus guided prompts for common workflows.",
+  "description": "Convex peer integration for Claude Code. Binds the peer's MCP endpoint so Claude can query the lattice, run transactions, manage accounts and keys, resolve CNS names, and watch on-chain state, plus use guided prompts for common workflows.",
   "version": "0.1.0",
   "author": {
-    "name": "Convex Foundation",
+    "name": "Convex Foundation and contributors",
     "url": "https://convex.world"
   },
   "homepage": "https://convex.world",
   "repository": "https://github.com/Convex-Dev/convex-plugin",
   "license": "Apache-2.0",
-  "keywords": ["convex", "blockchain", "lattice", "mcp", "cvm"]
+  "keywords": ["convex", "lattice", "mcp", "cvm", "decentralised"]
 }

.github/workflows/validate.yml

@@ -0,0 +1,81 @@
+name: Validate plugin
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Validate JSON files parse
+        run: |
+          set -euo pipefail
+          for f in .claude-plugin/plugin.json .mcp.json; do
+            echo "Checking $f"
+            python3 -c "import json, sys; json.load(open('$f'))"
+          done
+
+      - name: Validate plugin.json required fields
+        run: |
+          python3 <<'PY'
+          import json, sys
+          with open('.claude-plugin/plugin.json') as f:
+              m = json.load(f)
+          missing = [k for k in ('name', 'description', 'version') if k not in m]
+          if missing:
+              print(f"Missing required fields: {missing}", file=sys.stderr)
+              sys.exit(1)
+          print("plugin.json OK:", m['name'], m['version'])
+          PY
+
+      - name: Validate .mcp.json structure
+        run: |
+          python3 <<'PY'
+          import json, sys
+          with open('.mcp.json') as f:
+              m = json.load(f)
+          servers = m.get('mcpServers')
+          if not isinstance(servers, dict) or not servers:
+              print("mcpServers must be a non-empty object", file=sys.stderr)
+              sys.exit(1)
+          for name, cfg in servers.items():
+              if cfg.get('type') not in ('http', 'streamable-http', 'sse', 'stdio'):
+                  print(f"{name}: unknown or missing type", file=sys.stderr)
+                  sys.exit(1)
+              if cfg['type'] in ('http', 'streamable-http', 'sse') and 'url' not in cfg:
+                  print(f"{name}: missing url", file=sys.stderr)
+                  sys.exit(1)
+          print("mcp.json OK:", ", ".join(servers))
+          PY
+
+      - name: Validate agent and command frontmatter
+        run: |
+          python3 <<'PY'
+          import os, sys, re
+          errs = []
+          for root in ('agents', 'commands'):
+              if not os.path.isdir(root):
+                  continue
+              for fn in os.listdir(root):
+                  if not fn.endswith('.md'):
+                      continue
+                  path = os.path.join(root, fn)
+                  with open(path) as f:
+                      text = f.read()
+                  m = re.match(r'^---\n(.*?)\n---\n', text, re.DOTALL)
+                  if not m:
+                      errs.append(f"{path}: missing frontmatter block")
+                      continue
+                  fm = m.group(1)
+                  if 'name:' not in fm or 'description:' not in fm:
+                      errs.append(f"{path}: frontmatter must include name and description")
+          if errs:
+              print("\n".join(errs), file=sys.stderr)
+              sys.exit(1)
+          print("frontmatter OK")
+          PY

.mcp.json

@@ -1,11 +1,18 @@
 {
   "mcpServers": {
-    "convex": {
+    "convex-testnet": {
       "type": "http",
       "url": "${CONVEX_PEER_URL:-https://mikera1337-convex-testnet.hf.space/mcp}",
       "headers": {
         "Authorization": "Bearer ${CONVEX_AUTH_TOKEN:-}"
       }
+    },
+    "convex-local": {
+      "type": "http",
+      "url": "${CONVEX_LOCAL_URL:-http://localhost:8080/mcp}",
+      "headers": {
+        "Authorization": "Bearer ${CONVEX_LOCAL_AUTH_TOKEN:-}"
+      }
     }
   }
 }

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this plugin will be documented here. Versions follow [semver](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+- Two MCP server bindings: `convex-testnet` (public HuggingFace testnet by default) and `convex-local` (localhost:8080 by default), both overridable via environment variables.
+- `convex` subagent preloaded with Convex platform context, terminology, and tool-selection guidance.
+- `/convex:faucet <address> [amount]` slash command for quick testnet funding.
+- `/convex:explore <address-or-cns-name>` slash command for account inspection.
+- Plugin-level `CLAUDE.md` injecting Convex terminology and conventions (juice not gas, copper, peer not miner, lattice not blockchain) so generated code stays consistent.
+- GitHub Actions workflow validating `plugin.json`, `.mcp.json`, and agent/command frontmatter on every push.
+- Troubleshooting section in README covering peer reachability, `MCP_TIMEOUT` tuning, auth errors, and elevated-operation browser confirmations.
+
+## [0.1.0] — 2026-04-13
+
+### Added
+
+- Initial plugin scaffold targeting the Convex peer MCP endpoint (CAD041).

CLAUDE.md

@@ -0,0 +1,57 @@
+# Convex Context for Claude
+
+When using tools from the Convex plugin (anything namespaced `convex-testnet:*` or `convex-local:*`), keep the conventions below.
+
+## Terminology
+
+Use Convex terms, not blockchain analogues, in generated code, comments, and explanations.
+
+| Use this     | Not this                       |
+| ------------ | ------------------------------ |
+| CVM coin     | CVX                            |
+| Juice        | Gas, fees                      |
+| Copper       | Wei, satoshi                   |
+| Peer         | Miner, validator               |
+| Actor        | Smart contract                 |
+| Lattice      | Blockchain, chain              |
+| CPoS         | Proof of Work, Proof of Stake  |
+| Belief       | Block                          |
+| Etch         | _(core embedded database)_     |
+| CAD          | Specification / whitepaper     |
+| CNS          | DNS, ENS                       |
+| Protonet     | Mainnet                        |
+
+`1 CVM = 1,000,000,000 copper`. Balances returned by `getBalance` are in copper; convert for display.
+
+## Language
+
+British English spelling throughout (decentralised, organisation, behaviour, colour).
+
+## Architecture reminders
+
+- Convex is **not** a blockchain. It uses CRDT-like convergent data structures and reaches consensus via Convergent Proof of Stake.
+- All core data is **immutable and content-addressable** (the `ACell` hierarchy in `convex-core`).
+- The CVM is a **lambda-calculus VM** running Convex Lisp. Transactions are pure functions that update state.
+- Finality is **millisecond-scale**; there is no mining.
+
+## Tool selection hints
+
+- **Queries are free.** Prefer `query` or `queryState` over `transact` when reading data.
+- **`transact` transmits the Ed25519 seed.** Only use against HTTPS peers. For production keys, client side signing is best. If not possible, prefer the signing-service tools (`signingTransact`, `signingSign`) which keep keys server-side.
+- **`prepare` + `submit`** is the two-step flow for external signing (hardware wallets, client-side keys).
+- **`transfer`** is a convenience for coin/token transfers — use it instead of hand-rolling `transact` with `(transfer ...)` source.
+- **`watchState`** uses SSE notifications; remember to `unwatchState` when done to free server-side resources.
+- **Elevated signing operations** (`signingImportKey`, `signingExportKey`, `signingDeleteKey`, `signingChangePassphrase`) require a two-step browser confirmation and will return a URL the user must open.
+
+## Two servers are configured
+
+- `convex-testnet` — defaults to the public HuggingFace testnet. Good for exploration and throwaway accounts.
+- `convex-local` — defaults to `http://localhost:8080/mcp`. Use when developing against a locally-run peer.
+
+If both are active, be explicit about which you're targeting. Ask before transacting against the testnet.
+
+## Resources
+
+- [Convex docs](https://docs.convex.world)
+- [CAD041 (MCP)](https://docs.convex.world/docs/cad/041_mcp)
+- [Convex Lisp tutorial](https://docs.convex.world/docs/tutorial)