July updates

.agents/README.md

@@ -37,7 +37,22 @@ Specs live in the vault, not this repo. The maintainer keeps a document-driven d
 - **OpenAPI**: `GET /api/swagger` (JSON).
 - **Bot auth**: `POST /api/v1/botAuth` with body `{ "botKeyId", "secret", "paymentAddress" }` → `{ "token", "botId" }`. Use token as Bearer for `walletIds`, `pendingTransactions`, `freeUtxos`, `addTransaction`, `signTransaction`, etc. Reference client: `scripts/bot-ref/` (see README there).
 
+## MCP (AI agents)
+
+- **Endpoint**: `POST /api/mcp` — a stateless Model Context Protocol server built on
+  `@modelcontextprotocol/server` v2. Docs: `src/pages/api/mcp/README.md`.
+- **Surface**: read-only plus governance ballot drafts. It cannot sign, spend or
+  broadcast, and that boundary is enforced by a test (`src/__tests__/mcpTools.test.ts`) —
+  adding a write tool must be a deliberate decision, not a registry addition.
+- **Tools wrap the existing v1 handlers in-process** via `src/lib/mcp/invokeV1.ts`, so
+  authorization and validation stay defined once. Handler imports in
+  `src/lib/mcp/tools.ts` must stay **lazy** or the Mesh/whisky WASM lands in the route's
+  cold path.
+- **Auth**: an OAuth 2.1 access token, or an existing v1 bearer token. The authorization
+  server lives under `src/pages/api/oauth/` — see `src/pages/api/oauth/README.md`.
+
 ## Docs to keep in sync
 
 - Landing “Developers & Bots” section: `src/components/pages/homepage/index.tsx` (id `#developers-and-bots`).
 - API/bot docs: `src/utils/swagger.ts`, `scripts/bot-ref/README.md`.
+- MCP/OAuth: `src/pages/api/mcp/README.md`, `src/pages/api/oauth/README.md`.

.cursor/skills/multisig/SKILL.md

@@ -26,9 +26,15 @@ description: Build and integrate with the Mesh Multisig (Cardano multisig wallet
 ## Bot integration (machine-friendly)
 
 - **OpenAPI spec (JSON)**: `GET /api/swagger` — use for codegen or automation.
+- **Registration (new bots)**: `POST /api/v1/botRegister`  
+  Body: `{ "name": string, "requestedScopes": string[], "paymentAddress"?: string }`  
+  New bots should initially register **without** `paymentAddress` — a fresh bot has no wallet yet. Register with just name + scopes, have the owner claim you, pick up your credentials, generate a wallet, then bind the address at first `botAuth`. Only pass `paymentAddress` at registration if the bot already controls a wallet.
 - **Auth (bots)**: `POST /api/v1/botAuth`  
-  Body: `{ "botKeyId": string, "secret": string, "paymentAddress": string, "stakeAddress"?: string }`  
-  Response: `{ "token": string, "botId": string }`. Use `Authorization: Bearer <token>` for v1 endpoints.
+  Body: `{ "botKeyId": string, "secret": string, "paymentAddress"?: string, "stakeAddress"?: string }`  
+  Response: `{ "token": string, "botId": string }`. Use `Authorization: Bearer <token>` for v1 endpoints. The first successful `botAuth` binds `paymentAddress` to the bot (required then; creates its `BotUser` if registration was address-less). Afterwards `paymentAddress` is optional — the JWT always carries the server-side bound address, and a mismatching supplied address is rejected (409). The token lives ~1 hour: cache it and re-auth on 401; the `secret` is picked up once via `botPickupSecret` but stays valid for repeated auths — store it safely.
+- **Ballot drafting lifecycle (bots)**: `POST /api/v1/botBallotsUpsert` (drafts; proposalIds validated against the chain; response has `created` + `ballot.id`), `GET /api/v1/botBallots?walletId=` (reconcile your drafts), `DELETE /api/v1/botBallots` with `{walletId, ballotId}` (clean up stale drafts). All need `ballot:write` scope + any wallet grant (observer is enough). `GET /api/v1/botMe` returns `botWallets` (grants + roles) for self-discovery; `POST /api/v1/botRotateSecret` with the current secret mints a replacement if it leaks.
+- **Rate-limit etiquette (bots)**: requests are limited per IP and per bot (default 40/min). Don't fan out in parallel — space calls ~200–500 ms apart. Responses carry `X-RateLimit-Remaining`/`X-RateLimit-Reset`; a 429 carries `Retry-After` (seconds) — wait that long (the reference client's `fetchWithBackoff` in `scripts/bot-ref/bot-client.ts` does this). Rejected requests never extend the window.
+- **Governance reads (bots)**: `GET /api/v1/governanceActiveProposals?details=true` — use `details=true` to get `expiration` (voting-deadline epoch) and `deposit`; the response's `currentEpoch` gives time-to-deadline. "Active" = no terminal epoch on-chain; explorers may show a higher "active" count because they still display ratified-but-not-enacted actions — pass `includeRatified=true` to include those (status `ratified`, outcome already decided).
 - **Bot keys**: Created in-app (User → Create bot). One bot key can have one `paymentAddress`; same address cannot be used by another bot.
 - **Scopes**: Bot keys have scope (e.g. `multisig:read`); `botAccess.ts` enforces wallet access for bots.
 - **V1 endpoints used by bots**: `walletIds` (query `address` = bot’s `paymentAddress`), `pendingTransactions`, `freeUtxos`, `addTransaction`, `signTransaction`, etc. Same as wallet-authenticated calls but identity is the bot’s registered address.

.dockerignore

@@ -42,6 +42,12 @@ Thumbs.db
 # Documentation
 *.md
 !README.md
+# The feature vault is data, not documentation: /roadmap/graph reads these notes
+# at runtime, so they have to survive the *.md filter above. Keep this as the
+# bare directory — Railpack turns each negation into a literal copy instruction,
+# and a `!vault/**` glob becomes `copy /vault/** /app/**`, which buildkit rejects
+# with "cannot copy to non-directory". `!vault` alone copies the tree recursively.
+!vault
 docs
 
 # Docker

.env.example

@@ -58,3 +58,21 @@ NEXT_PUBLIC_BLOCKFROST_API_KEY_PREPROD="your-blockfrost-preprod-api-key"
 # DISCORD_CLIENT_SECRET="your-discord-client-secret"
 # DISCORD_BOT_TOKEN="your-discord-bot-token"
 # DISCORD_GUILD_ID="your-discord-guild-id"
+
+# Optional: Email notifications via Resend
+# RESEND_API_KEY="re_..."
+# EMAIL_FROM="Mesh Multisig <notifications@your-domain.example>"
+# EMAIL_REPLY_TO="support@your-domain.example"
+# Optional: override notification email links. Required for localhost links when
+# using `next start` locally (NODE_ENV is production). Defaults to
+# http://localhost:3000 in `next dev` and the production site URL otherwise.
+# NOTIFICATION_LINK_BASE_URL="http://localhost:3000"
+# NOTIFICATION_DRAIN_SECRET="your-notification-drain-secret"
+# NOTIFICATIONS_EMAIL_ENABLED="false"
+# Optional: OAuth 2.1 issuer for the MCP endpoint (/api/mcp)
+# Canonical origin of the authorization server. Access tokens carry it as `iss`,
+# and the /.well-known discovery documents are built from it. Falls back to
+# NEXT_PUBLIC_SITE_URL; set this only if the issuer must differ from the site
+# origin. In non-production it falls back to the request host, so a local
+# `next start` on any port works without setting anything.
+# OAUTH_ISSUER_URL="https://multisig.meshjs.dev"

.github/workflows/ci-smoke-preprod.yml

@@ -35,6 +35,9 @@ jobs:
         with:
           node-version: 22
 
+      - name: Use repo npm version
+        run: npm install -g "$(node -p 'require("./package.json").packageManager')" && npm --version
+
       - name: Check secrets configured
         id: check-secrets
         run: |

.github/workflows/deploy-migrations.yml

@@ -20,7 +20,10 @@ jobs:
         with:
           node-version: '22'
           cache: 'npm'
-
+
+      - name: Use repo npm version
+        run: npm install -g "$(node -p 'require("./package.json").packageManager')" && npm --version
+
       - name: Install dependencies
         run: npm ci
 

.github/workflows/notification-outbox-drain.yml

@@ -0,0 +1,49 @@
+name: Notification Outbox Drain
+
+# Drains the notification outbox (pending + due-for-retry deliveries) by calling
+# the authenticated drain endpoint. Requires NOTIFICATION_DRAIN_SECRET to be set
+# both as a GitHub Actions secret and as an env var on the deployment; until
+# both exist, runs are graceful no-ops.
+
+on:
+  schedule:
+    # Every 15 minutes; the shortest retry delay in the worker is 5 minutes.
+    - cron: '*/15 * * * *'
+  # Allow manual triggering for testing
+  workflow_dispatch:
+
+jobs:
+  drain:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Drain notification outbox
+        env:
+          API_BASE_URL: 'https://multisig.meshjs.dev'
+          DRAIN_SECRET: ${{ secrets.NOTIFICATION_DRAIN_SECRET }}
+        run: |
+          if [ -z "$DRAIN_SECRET" ]; then
+            echo "NOTIFICATION_DRAIN_SECRET repo secret is not set; skipping."
+            exit 0
+          fi
+
+          status=$(curl -s -o response.json -w "%{http_code}" -X POST \
+            "$API_BASE_URL/api/notifications/drain?limit=100" \
+            -H "Authorization: Bearer $DRAIN_SECRET")
+
+          echo "HTTP $status"
+          cat response.json || true
+          echo
+
+          case "$status" in
+            200)
+              ;;
+            503)
+              echo "Drain endpoint reports NOTIFICATION_DRAIN_SECRET is not configured on the deployment; skipping."
+              ;;
+            *)
+              echo "Drain request failed."
+              exit 1
+              ;;
+          esac

.github/workflows/pr-checks.yml

@@ -23,6 +23,9 @@ jobs:
           node-version: 22
           cache: 'npm'
 
+      - name: Use repo npm version
+        run: npm install -g "$(node -p 'require("./package.json").packageManager')" && npm --version
+
       - name: Install dependencies
         run: npm ci
 

.github/workflows/pr-multisig-v1-smoke.yml

@@ -27,6 +27,14 @@ on:
         default: ""
         type: string
 
+# Serialize against the Playwright e2e workflow: both broadcast from the same
+# preprod CI wallets, so they must never run at the same time. A constant group
+# (not per-PR) ensures mutual exclusion across PRs too. cancel-in-progress:false
+# means runs queue rather than cancel each other.
+concurrency:
+  group: ci-preprod-wallets
+  cancel-in-progress: false
+
 jobs:
   multisig-v1-smoke:
     if: github.repository == 'MeshJS/multisig'
@@ -53,7 +61,23 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      # Dependabot-triggered runs never receive repo Actions secrets. When no
+      # core secret is present at all, skip the smoke instead of failing so
+      # dependabot PRs are not systematically red. A partial secret set still
+      # fails loudly in the validate step below.
+      - name: Check CI secrets configured
+        id: check-secrets
+        shell: bash
+        run: |
+          if [[ -z "$CI_JWT_SECRET" && -z "$CI_MNEMONIC_1" && -z "$CI_MNEMONIC_2" && -z "$CI_MNEMONIC_3" && -z "$CI_BLOCKFROST_PREPROD_API_KEY" ]]; then
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+            echo "Multisig v1 smoke skipped: CI_* secrets not available to this run (e.g. dependabot-triggered)."
+          else
+            echo "configured=true" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Validate required CI secrets
+        if: steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: |
           missing=()
@@ -91,23 +115,27 @@ jobs:
           fi
 
       - name: Pull base image (with retry)
+        if: steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: |
           for i in 1 2 3; do
-            docker pull node:20-alpine && break
+            docker pull node:22-slim && break
             echo "Pull attempt $i failed, retrying in 30s..."
             sleep 30
           done
 
       - name: Build CI containers
+        if: steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: docker compose -f docker-compose.ci.yml build
 
       - name: Start Postgres + App containers
+        if: steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: docker compose -f docker-compose.ci.yml up -d postgres app
 
       - name: Wait for app healthcheck
+        if: steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: |
           for i in {1..60}; do
@@ -124,11 +152,12 @@ jobs:
           exit 1
 
       - name: Run CI wallet bootstrap + v1 route-chain smoke
+        if: steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: docker compose -f docker-compose.ci.yml --profile ci-test run --rm ci-runner
 
       - name: Dump container logs on failure
-        if: failure()
+        if: failure() && steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: |
           docker compose -f docker-compose.ci.yml logs --no-color \
@@ -145,22 +174,22 @@ jobs:
             > docker-compose-ci.log
 
       - name: Upload logs on failure
-        if: failure()
+        if: failure() && steps.check-secrets.outputs.configured == 'true'
         uses: actions/upload-artifact@v4
         with:
           name: docker-compose-ci-logs
           path: docker-compose-ci.log
 
       - name: Upload route-chain report
-        if: always()
+        if: always() && steps.check-secrets.outputs.configured == 'true'
         uses: actions/upload-artifact@v4
         with:
           name: ci-route-chain-report
           path: ci-artifacts/ci-route-chain-report.md
           if-no-files-found: warn
 
       - name: Tear down CI containers
-        if: always()
+        if: always() && steps.check-secrets.outputs.configured == 'true'
         shell: bash
         run: docker compose -f docker-compose.ci.yml down -v --remove-orphans