August and September Updates

.agents/README.md

@@ -41,15 +41,32 @@ Specs live in the vault, not this repo. The maintainer keeps a document-driven d
 
 - **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.
+- **Surface**: read-only, governance ballot drafts, and — under the opt-in
+  `transactions:write` scope — unsigned transaction drafts in two steps
+  (`transaction_preview` returns a review-card PNG plus a signed draft token;
+  `transaction_propose` takes only that token and creates the pending transaction with
+  zero signatures). 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.
+  authorization and validation stay defined once — including the dual identity (human
+  signer JWT vs. bot key with a WalletBotAccess grant), which a tool body calling a
+  tRPC router directly would not reproduce. A tool that needs an operation with no REST
+  route gets a new v1 handler first (`tasks.ts` / `taskUpsert.ts` are the model). The
+  transaction review tools are the exception: they live in `src/lib/tx-review/` and
+  reuse the canvas builder's `src/lib/tx-draft/` pipeline server-side, and even they
+  take their UTxOs from `freeUtxos.ts` through `freeUtxosFetcher` in `tools.ts`. Handler
+  imports in `src/lib/mcp/tools.ts` must stay **lazy** or the Mesh/whisky WASM (and the
+  `next/og` renderer) 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`.
+- **Inline card (MCP App)**: the review tools point at `ui://mesh-multisig/review-card`
+  (`src/lib/mcp/apps/review-card.ts`), a self-contained HTML view the Claude app renders
+  inline with a Confirm button. Keep it dependency-free (default CSP: no fetch, no external
+  assets) and keep the `ui/initialize` handshake — the host hides the frame until it completes.
+- **Server instructions** (`MCP_SERVER_INSTRUCTIONS`, `src/lib/mcp/server.ts`) are sent
+  at initialize and land in the model's context for every conversation: keep them short
+  and behavioural (what to do with tool results), never a feature list.
 
 ## Docs to keep in sync
 

.env.example

@@ -40,9 +40,9 @@ NEXT_PUBLIC_BLOCKFROST_API_KEY_PREPROD="your-blockfrost-preprod-api-key"
 # SNAPSHOT_AUTH_TOKEN="your-snapshot-auth-token"
 
 # Canonical public URL of the deployment.
-# Used for SEO: canonical tags, Open Graph / Twitter URLs, robots.txt and the
-# sitemap. Defaults to the production domain when unset; set this on preview or
-# self-hosted environments so links point at the right origin.
+# Used for bot setup guide URLs and SEO: canonical tags, Open Graph / Twitter
+# URLs, robots.txt and the sitemap. Defaults to the production domain when unset;
+# set this on local, preview or self-hosted environments so links point at the right origin.
 # NEXT_PUBLIC_SITE_URL="https://multisig.meshjs.dev"
 
 # Optional: Skip environment validation during builds

.github/workflows/ballot-deadline-reminders.yml

@@ -0,0 +1,50 @@
+name: Ballot Deadline Reminders
+
+# Enqueues 48h/24h ballot-deadline reminder emails (derived from on-chain
+# proposal expiration epochs) and drains the outbox, by calling the
+# authenticated reminder endpoint. Shares NOTIFICATION_DRAIN_SECRET with the
+# outbox drain workflow; until it is set both here and on the deployment, runs
+# are graceful no-ops.
+
+on:
+  schedule:
+    # Hourly; reminder windows are 24h wide so this is ample resolution.
+    - cron: '17 * * * *'
+  # Allow manual triggering for testing
+  workflow_dispatch:
+
+jobs:
+  remind:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Scan ballots and enqueue deadline reminders
+        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/ballot-deadlines" \
+            -H "Authorization: Bearer $DRAIN_SECRET")
+
+          echo "HTTP $status"
+          cat response.json || true
+          echo
+
+          case "$status" in
+            200)
+              ;;
+            503)
+              echo "Endpoint reports NOTIFICATION_DRAIN_SECRET is not configured on the deployment; skipping."
+              ;;
+            *)
+              echo "Ballot deadline reminder request failed."
+              exit 1
+              ;;
+          esac

README.md

@@ -347,7 +347,8 @@ The application provides comprehensive API documentation through Swagger UI:
 - `GET /api/v1/walletIds` - Get user's wallet IDs
 - `POST /api/v1/addTransaction` - Create new transaction
 - `POST /api/v1/authSigner` - Authenticate signer
-- `GET /api/v1/lookupMultisigWallet` - Lookup multisig wallet
+- `GET /api/v1/lookupMultisigWallet` - Lookup multisig wallet registrations by signer key hash
+- `GET /api/v1/resolveScript` - Resolve a native script (policy id or wallet address) to its signer key hashes
 - `POST /api/discord/send-message` - Send Discord notifications
 
 > 💡 **Tip**: The Swagger UI provides interactive API testing. Start the dev server and visit `/api-docs` to explore all available endpoints.