dexe-mcp 0.16.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 0.19.0 — 2026-07-06
+
+### DAO creation: governance coherence guards + frontend parity
+
+`dexe_dao_create` could ship broken/reverting DAOs — it invented no defaults, ran
+no coherence checks, and carried assumptions that diverged from the frontend
+(`investing-dashboard`, the 3-year production source of truth that deploys to BSC
+mainnet daily). Reconciled the whole path to the frontend.
+
+- **SIMPLE mode.** `dexe_dao_create` now takes high-level fields (`symbol`,
+  `totalSupply`, optional `treasuryPercent`/`quorumPercent`/`voteModel`/
+  `durationSeconds`) and synthesizes a coherent, frontend-equivalent deploy
+  config — LINEAR power, treasury as an **implicit remainder**, a reachable
+  quorum. It returns a `mode:"preview"` (resolved config + safety proof) and only
+  broadcasts on a second call with `confirm:true`. ADVANCED mode (full `params`)
+  still works. `params` is now optional.
+- **Governance coherence guards** (`src/lib/preflight.ts`, enforced in
+  `buildDeployGovPool` for both `dexe_dao_create` and `dexe_dao_build_deploy`),
+  mirroring the frontend's blocking validation:
+  - `checkQuorumReachable` — `quorum% × supply ≤ votable tokens` (treasury/
+    undistributed tokens can't vote). LINEAR exact; POLYNOMIAL via a port of the
+    frontend `calcMeritocraticVotingPower`. **Hard block.**
+  - `checkMinVotesVsDistribution` — `minVotesForVoting/Creating ≤ largest
+    recipient`. **Hard block.**
+  - `checkSettingsBounds` — `0<quorum≤1e27`, `duration>0`, etc. (`GovSettings.sol`).
+  - `checkNoTreasuryRecipient` — the predicted govPool must never be in
+    `tokenParams.users[]`.
+- **Corrected the cap rule (verified live on mainnet via eth_call).** The gov
+  token is `ERC20Capped`: `cap = 0` reverts (`ERC20Capped: cap is 0`) — there is
+  **no uncapped mode** — and `cap < mintedTotal` reverts. `cap == mintedTotal` is
+  a valid fixed supply (old bug #28 "cap==minted reverts" is outdated). New rule:
+  `cap ≥ mintedTotal > 0`. `checkDeployCap` + the deploy builder now enforce it;
+  SIMPLE mode sets `cap = totalSupply`.
+- **Reversed the treasury-remainder rule (old bug #32 was wrong — verified live).**
+  A treasury remainder (`sum(amounts) < mintedTotal`) deploys fine on mainnet — the
+  contract mints the remainder to the DAO. `checkTreasuryRemainder` now only rejects
+  OVER-distribution (`sum > minted`), on all chains. The prior "mainnet needs
+  `mintedTotal == sum(amounts)`" belief forced the treasury address into the voter list.
+- **Mainnet is NOT broken.** Dropped the false "mainnet deployGovPool reverts /
+  `require(false)`" gating text. Mainnet (56) is a supported target; it just
+  requires `confirm:true` (spends real BNB). Testnet-first is a recommendation.
+- Default vote model = **LINEAR**; default quorum **51%** with a ≥50% advisory
+  floor. No new tools.
+
+## 0.18.0 — 2026-07-06
+
+### WalletConnect QR + hot-key "NOT SAFE" warnings
+
+WalletConnect is now the clearly-primary signer, and pairing takes zero copy-paste.
+
+- **`dexe_wc_connect` renders a scannable QR**, not a raw URI. It returns both a
+  terminal ASCII QR (scannable in a bare terminal, no browser, no external
+  service) **and** an `image/png` MCP content block (crisp QR in GUI clients).
+  The raw `uri` + an `api.qrserver.com` fallback URL are still included. New
+  helper `src/lib/qr.ts` (lazy-imports `qrcode`, so read-only installs pay
+  nothing and a missing install degrades gracefully).
+- **Auto-print QR when a write needs a wallet.** `dexe_tx_send` in WalletConnect
+  mode with no session now *starts pairing and prints the QR* instead of
+  erroring "call dexe_wc_connect". The composite flows (`dexe_dao_create`,
+  `dexe_proposal_create`, `dexe_proposal_vote_and_execute`, OTC) attach a live
+  `pairing` QR to their read-only response. (Composites still emit payloads to
+  feed to `dexe_tx_send` — no WC broadcast routing inside composites.)
+- **Hot keys are flagged "⚠️ NOT SAFE" everywhere.** Every `dexe_tx_send`
+  hot-key broadcast carries a `safety` field; `dexe_get_config` reports
+  `recommendedSigner: "walletconnect"` + a `safety` note; `dexe_doctor` adds a
+  `signer.hotKey` advisory; the startup log warns about the plaintext key.
+- **`dexe_wc_connect` no longer refuses when `DEXE_PRIVATE_KEY` is set** — it
+  pairs and tells you the hot key still takes signing precedence until removed
+  (non-breaking: key-wins precedence is unchanged).
+- New: `WalletConnectManager.ensurePairing()` (reuses an in-flight URI / live
+  session). No new tools — tool count unchanged.
+
+## 0.17.0 — 2026-07-06
+
+### Zero-config public defaults + guided setup
+
+A fresh install is now useful immediately — **reads and WalletConnect signing
+work with no `.env` at all.** The plugin ships public defaults, all overridable
+by a user `.env` (env value always wins).
+
+- **Baked defaults** (`src/config.ts` `DEFAULTS`): DeXe backend (`api.dexe.io`),
+  a shared WalletConnect project id, and the three DeXe subgraph URLs (The Graph
+  decentralized network, modern `gateway.thegraph.com` host, key embedded in the
+  path — no standalone `DEXE_GRAPH_API_KEY` needed, which also removes the old
+  Bearer-vs-URL key mismatch). RPC public fallback + the chain-56 registry were
+  already baked.
+- **IPFS reads default to public gateways** (ipfs.io, dweb.link, cloudflare) when
+  no dedicated gateway is set. New `DEXE_IPFS_DISABLE_PUBLIC_FALLBACK=1` opt-out.
+- **Behavior change:** with no hot key, `signerMode` is now `walletconnect`
+  (WalletConnect available) instead of `readonly`. Signing is still gated on an
+  actual `dexe_wc_connect`; `address` stays `null` until you connect.
+- **Runtime hints instead of bare errors.** A failing public-RPC call now carries
+  a "set a private RPC" nudge (only for the public fallback, never your own RPC;
+  contract reverts pass through untouched). A failing all-public IPFS fetch nudges
+  toward a dedicated gateway. The Pinata-JWT block on create flows now uses a
+  shared, actionable message pointing at `/dexe-setup`.
+- **`dexe_doctor`** validates the *default* subgraph + backend endpoints (no
+  longer skipped when unset) and adds an `env.sharedDefaults` advisory — the
+  shared Graph key + WC id are billable-shared, so heavy users should bring their
+  own. `dexe_context.env` gains `usingSharedDefaults`, `ipfsReads`,
+  `walletConnectAvailable`, and `usingPublicRpcFallback`.
+- **`/dexe-setup` rewritten** as a tiered "skip → what breaks" journey, plus a
+  once-only SessionStart onboarding nudge shipped with the plugin.
+- Docs: `docs/ENVIRONMENT.md` gains a baked-defaults table + key-rotation note;
+  `.env.example` reframed around optional overrides with current var names.
+
+No new tools (159). No breaking config changes — every default is overridable.
+
 ## 0.16.0 — 2026-07-04
 
 ### Backend-powered treasury + holder/stats/NFT reads (156 → 159 tools)

package/README.md

@@ -46,7 +46,7 @@ Then just ask:
 
 > *"Show the treasury of `0x…` on BSC."*
 
-Reads work with **zero setup** — the server falls back to public BSC RPC out of the box, and the governance skills (create DAO, create proposal, vote & execute, OTC) install with the plugin.
+Reads work with **zero setup** — on-chain data, subgraphs, the DeXe backend, and IPFS all run on public defaults out of the box, and WalletConnect signing is available immediately (connect a wallet with `dexe_wc_connect`). The governance skills (create DAO, create proposal, vote & execute, OTC) install with the plugin.
 
 **Want to create DAOs or proposals, or broadcast transactions?** Type **`/dexe-setup`** and Claude walks you through adding your keys (a Pinata token for IPFS, a wallet for signing) — one guided step, nothing to hand-edit.
 

package/dexe-plugin/skills/dexe-create-dao/SKILL.md

@@ -1,99 +1,123 @@
 ---
 name: dexe-create-dao
 description: |
-  Deploy a new DeXe DAO with the one-call `dexe_dao_create` composite. Covers the
-  exact param recipe, the decimal conventions, and the four deploy gotchas that
-  silently revert (cap>minted, LINEAR initData, non-zero userKeeper asset, mainnet
-  treasury remainder). Use when the user says "create/deploy a DAO".
+  Deploy a new DeXe DAO with the one-call `dexe_dao_create` composite. Use SIMPLE
+  mode (symbol + totalSupply) and let the tool synthesize a coherent, governance-
+  safe config — it previews the resolved config + a safety proof and only
+  broadcasts on confirm. Covers the two quorum rules (reachable ≤ votable, floor
+  ≥50%), the implicit-treasury pattern, and the deploy gotchas. Use when the user
+  says "create/deploy a DAO".
 ---
 
 # dexe-create-dao
 
-Deploy a DeXe governance DAO in **one tool call** — `dexe_dao_create` handles
+Deploy a DeXe governance DAO in **one tool call**. `dexe_dao_create` handles
 avatar → DAO IPFS metadata → `PoolFactory.deployGovPool` (predicted-address
 wiring, 1→5 settings auto-expand, executorDescription upload) → broadcast.
 
-## Golden rule: testnet first
+**Do NOT hand-fabricate token splits or quorum numbers.** That is exactly how you
+ship a broken DAO. Use SIMPLE mode and let the tool synthesize + verify a coherent
+config, or read the two rules below and satisfy them.
 
-**Validate on BSC testnet (chain 97).** Mainnet `deployGovPool` is broken
-upstream (`require(false)`). Never spend mainnet BNB on a deploy without the
-user explicitly asking. Pass `chainId: 97`.
+## The two rules that make a DAO usable (the tool enforces both)
 
-## Recipe
+A DeXe DAO holds two kinds of tokens: **votable** (distributed to real wallets)
+and **treasury** (held by the DAO/govPool — these **cannot vote**).
 
-0. **Orient:** call `dexe_context` first — it shows the signer, active chain,
-   env readiness, and DAOs you already deployed (so you don't re-create one).
-1. **Confirm chain + signer:** `dexe_get_config` (or the `dexe_context` output).
-   Ensure the active/target chain is 97 and `DEXE_PINATA_JWT` is set (required
-   for metadata upload).
-2. **(Optional) avatar:** `dexe_dao_generate_avatar` or `dexe_ipfs_upload_avatar`
-   → take the returned `cid` as `avatarCID`. Must be a **real JPEG**, not SVG
-   bytes named `.jpeg` (the frontend gateway rejects the mismatch).
-3. **Create:** call `dexe_dao_create` once. `deployer` defaults to the signer.
+1. **Quorum must be REACHABLE:** `quorum% × totalSupply ≤ votable tokens`.
+   Equivalently `quorum% ≤ (100 − treasury%)`. If quorum is higher than the
+   votable share, **no proposal can ever pass** — the tool hard-blocks this
+   (mirrors the frontend's blocking check).
+2. **Quorum floor ≥ 50%** (51% recommended). Below 50%, a small group can pass
+   proposals and even drain the treasury. Advisory, surfaced in the preview.
+
+Together these mean **treasury% ≤ 50%** (so a ≥50% quorum can still be reached).
+The default (treasury 49% / quorum 51%) sits right at the boundary.
+
+## Golden rule: validate on testnet first
+
+Deploy to **BSC testnet (chain 97)** first (`chainId: 97`) — free faucet BNB.
+**Mainnet (chain 56) works** (the frontend ships there daily) and is supported,
+but it spends real BNB, so `dexe_dao_create` requires `confirm: true` for any
+mainnet broadcast. Never confirm a mainnet deploy without the user explicitly
+asking.
+
+## Recipe — SIMPLE mode (recommended)
+
+0. **Orient:** `dexe_context` — shows signer, active chain, env readiness, and
+   DAOs you already deployed.
+1. **Env:** ensure the target chain is 97 and `DEXE_PINATA_JWT` is set (metadata).
+2. **(Optional) avatar:** `dexe_dao_generate_avatar` / `dexe_ipfs_upload_avatar`
+   → pass the `cid` as `avatarCID` (a real JPEG, not SVG named `.jpeg`).
+3. **Preview:** call `dexe_dao_create` with just the essentials:
 
 ```jsonc
 dexe_dao_create({
   chainId: 97,
   daoName: "Aurora Collective",
-  daoDescription: "A community treasury DAO.",   // markdown → slate, uploaded for you
-  websiteUrl: "https://aurora.example",
-  socialLinks: [["twitter", "https://x.com/aurora"]],
-  avatarCID: "bafy…",                             // optional
-  params: {
-    settingsParams: {
-      proposalSettings: [{                        // pass ONE → auto-expands to 5
-        earlyCompletion: true,
-        delegatedVotingAllowed: false,            // INVERTED: false = delegation ALLOWED
-        validatorsVote: false,
-        duration: "86400",                        // seconds (1 day)
-        durationValidators: "86400",
-        executionDelay: "0",
-        quorum: "500000000000000000000000000",    // 25-dec wei = 50%
-        quorumValidators: "500000000000000000000000000",
-        minVotesForVoting: "1000000000000000000", // 18-dec wei = 1 token
-        minVotesForCreating: "1000000000000000000",
-        rewardsInfo: { rewardToken: "0x0000000000000000000000000000000000000000",
-                       creationReward: "0", executionReward: "0", voteRewardsCoefficient: "0" },
-        executorDescription: ""                   // auto-uploaded to IPFS
-      }]
-    },
-    userKeeperParams: { tokenAddress: "0x0000000000000000000000000000000000000000",
-                        nftAddress: "0x0000000000000000000000000000000000000000",
-                        individualPower: "0", nftsTotalSupply: "0" },
-    tokenParams: {                                // non-empty name => create a gov token
-      name: "Aurora", symbol: "AUR",
-      users: ["0xYourAddr"],
-      cap: "0",                                   // 0 = uncapped (or > mintedTotal)
-      mintedTotal: "1000000000000000000000",      // 1000 tokens (18-dec)
-      amounts: ["1000000000000000000000"]         // MUST sum to mintedTotal on mainnet
-    },
-    votePowerParams: { voteType: "LINEAR_VOTES" }  // initData auto-encoded — do NOT pass it
-  }
+  symbol: "AUR",
+  totalSupply: "1000000",     // whole tokens
+  // optional (these are the defaults):
+  treasuryPercent: 49,        // implicit remainder held by the DAO (can't vote)
+  quorumPercent: 51,          // must be ≥50 AND ≤ (100 − treasuryPercent)
+  voteModel: "LINEAR",        // 1 token = 1 vote (default); or "POLYNOMIAL"
+  durationSeconds: 86400,     // 1 day
+  daoDescription: "A community treasury DAO.",
+  avatarCID: "bafy…"          // optional
 })
 ```
 
+This returns `mode: "preview"` with the **resolved config** (who holds what) and a
+**safety proof** (votable %, quorum %, reachable?, floor OK?). Show it to the user.
+
+4. **Confirm:** re-call with the **same arguments plus `confirm: true`** to broadcast.
+   The deployer holds the entire distributed portion; the treasury is an **implicit
+   remainder** (the govPool address is never a token recipient).
+
+## Recipe — ADVANCED mode (full control)
+
+Pass a full `params` struct (same shape as `dexe_dao_build_deploy`) instead of the
+SIMPLE fields. The coherence guards still run. Key rules for hand-built params:
+
+- **Treasury is an implicit remainder.** `tokenParams.users`/`amounts` list only
+  external wallets; `sum(amounts)` is **less than** `mintedTotal` (the contract
+  mints the remainder to the DAO). **Never** put the predicted govPool in `users[]`.
+- Pass **one** `proposalSettings` entry → auto-expands to 5.
+- `votePowerParams.voteType: "LINEAR_VOTES"` — `initData` is auto-encoded; don't pass it.
+
 ## Deploy gotchas (the tool pre-flights these — heed the errors)
 
-1. **cap > mintedTotal** — or `cap = 0` (uncapped). `cap == mintedTotal` reverts
-   ERC20Gov init silently (bug #28).
-2. **LINEAR initData** — the tool auto-encodes `__LinearPower_init()`
-   (`0x892aea1f`). Never pass `initData` for LINEAR/POLYNOMIAL; only CUSTOM_VOTES
-   takes a manual `initData`.
-3. **Non-zero governance asset** — if not creating a token (`tokenParams.name`
-   empty), set `userKeeperParams.tokenAddress` or `.nftAddress`.
-4. **Treasury remainder (mainnet)** — `mintedTotal` must equal `sum(amounts)`;
-   a remainder reverts on chain 56 (bug #32). Distribute the whole mint.
+1. **Unreachable quorum** — `quorum% × supply > votable`. Lower quorum, distribute
+   more to voters, or shrink the treasury. (hard block)
+2. **min-votes above every holder** — `minVotesForVoting/Creating` must be ≤ the
+   largest single recipient. (hard block)
+3. **cap** — must be `> 0` AND `≥ mintedTotal`. There is **no uncapped mode**
+   (`cap = 0` reverts `ERC20Capped: cap is 0`); `cap == mintedTotal` is a valid
+   fixed supply; `cap < mintedTotal` reverts. SIMPLE mode sets `cap = totalSupply`. (hard block)
+4. **LINEAR initData** — auto-encoded (`__LinearPower_init()` = `0x892aea1f`). Never
+   pass `initData` for LINEAR/POLYNOMIAL; only CUSTOM_VOTES takes a manual one.
+5. **Non-zero governance asset** — if not creating a token, set
+   `userKeeperParams.tokenAddress` or `.nftAddress`.
+6. **Over-distribution** — `sum(amounts)` must be ≤ `mintedTotal`. (An implicit
+   treasury remainder is correct and expected — do NOT force them equal.)
 
 ## Decimal conventions (must match the frontend)
 
-- `quorum`, `quorumValidators`, `voteRewardsCoefficient`: **25-dec** wei (50% = `5e26`).
+- `quorum`, `quorumValidators`, `voteRewardsCoefficient`: **25-dec** wei (50% = `5e26`, 100% = `1e27`).
 - `minVotes*`, `cap`, `mintedTotal`, `amounts`, `individualPower`, rewards: **18-dec** wei.
 - `duration*`, `executionDelay`: plain **seconds** as string.
-- `delegatedVotingAllowed` is **inverted**: `true` DISABLES delegation.
+- `delegatedVotingAllowed` is **inverted**: `true` DISABLES delegation, `false` ALLOWS it.
+
+## Pre-submit self-check (before `confirm: true`)
+
+- [ ] `quorumPercent ≤ 100 − treasuryPercent` (reachable) and `≥ 50` (floor)?
+- [ ] treasury is an implicit remainder — govPool NOT in `users[]`?
+- [ ] `sum(amounts) ≤ mintedTotal`, and `cap ≥ mintedTotal > 0` (never cap=0)?
+- [ ] validating on testnet (97) first, or the user explicitly asked for mainnet?
 
 ## After deploy
 
-The result includes `predictedGovPool` — that is the DAO's GovPool address once
-the tx confirms. Use it for `dexe_proposal_create` / `dexe_proposal_vote_and_execute`.
+The result includes `predictedGovPool` — the DAO's GovPool address once the tx
+confirms. Use it for `dexe_proposal_create` / `dexe_proposal_vote_and_execute`.
 
 Related: [[dexe-create-proposal]], [[dexe-vote-execute]].

package/dexe-plugin/skills/dexe-setup/SKILL.md

@@ -1,108 +1,152 @@
 ---
 name: dexe-setup
 description: |
-  Onboard a user to dexe-mcp. Runs `dexe_doctor`, parses the report, asks the
-  user only for what is missing, edits `.env` (NEVER `.claude.json`), and
-  tells them to restart Claude Code. Triggered by `/dexe-setup`, or
-  proactively when the user reports an env-related MCP tool failure
-  ("DEXE_PINATA_JWT not set", "RPC unreachable", "subgraph 401", etc.).
+  Guided setup journey for dexe-mcp. Explains that reads work with ZERO config,
+  then walks the user through only the keys that unlock more — signing, DAO/
+  proposal creation (Pinata JWT), and optional reliability upgrades — telling
+  them for each one exactly what breaks if they skip it. Drives from
+  `dexe_doctor`, edits `.env` (NEVER `.claude.json`), and tells them to restart.
+  Triggered by `/dexe-setup`, or proactively when a tool reports a missing key
+  ("DEXE_PINATA_JWT is required…", "public RPC unstable", "shared public defaults").
 ---
 
 # dexe-setup
 
 ## What this does
 
-Iterative env-setup loop for `dexe-mcp`. Replaces the brittle workflow where
-Claude guesses which file to edit and which keys are needed. Drives entirely
-from the `dexe_doctor` tool — no guessing.
+A guided onboarding journey for `dexe-mcp`. The plugin ships with sane public
+defaults, so **reads work the moment it's installed** — no keys required. This
+skill's job is to explain that reality and then help the user unlock the parts
+that *do* need a key, one tier at a time, always saying what they lose by
+skipping. It drives from the `dexe_doctor` tool — no guessing which file or key.
+
+## The two-tier reality (say this first)
+
+Open by orienting the user:
+
+> **Reads already work** — DAO info, treasury, holders, proposals, subgraph
+> queries, IPFS reads all run on shared public defaults with zero setup.
+> You only need to configure something to **write** or to **create DAOs/
+> proposals**. Want me to walk you through it, or are reads all you need?
+
+If reads are all they need: confirm they're done, mention `dexe_doctor` is there
+if anything misbehaves, and stop.
 
 ## When to invoke
 
 - The user types `/dexe-setup`.
-- The user reports any of:
-  - "dexe-mcp not working", "tools failing", "RPC error", "missing env"
-  - A specific MCP tool error mentioning a `DEXE_*` env var
-  - "How do I configure dexe-mcp?"
-- You see a tool result containing `"Missing required env: DEXE_*"` or
-  `"DEXE_* is not set"` — invoke proactively.
+- The user says "set up dexe", "enable writes", "I want to create a DAO/
+  proposal", "how do I configure dexe-mcp?".
+- You see a tool result containing any of: `"DEXE_PINATA_JWT is required"`,
+  `"Missing required env"`, `"public RPC unstable"`, `"public IPFS gateways
+  are failing"`, `env.sharedDefaults` — invoke proactively.
 
 ## Hard rules (do not violate)
 
 1. **Never write `DEXE_*` values to `.claude.json`.** The MCP host's env block
    SHADOWS `.env` silently. Edits go in `.env` at the dexe-mcp repo root.
-2. **Never write `DEXE_PRIVATE_KEY` without explicit user opt-in.** Default
-   to readonly mode. If the user says "I want to broadcast", first suggest
-   WalletConnect (`DEXE_WALLETCONNECT_PROJECT_ID`); only fall back to
-   `DEXE_PRIVATE_KEY` if the user insists, and warn them that the key
-   lives in plaintext on disk.
+2. **Never write `DEXE_PRIVATE_KEY` without explicit user opt-in.** Signing is
+   available by default via WalletConnect (below) — reach for a hot key only if
+   the user insists, and warn it lives in plaintext on disk.
 3. **Always tell the user to restart Claude Code after editing `.env`.**
-   `process.loadEnvFile()` runs once at startup; mid-session edits do
-   nothing until restart.
-4. **Cap the loop at 3 iterations.** If `dexe_doctor` still shows failures
-   after three doctor → fix → restart cycles, stop and present the full
-   report to the user — the remaining issues need manual investigation.
+   `process.loadEnvFile()` runs once at startup; mid-session edits do nothing
+   until restart.
+4. **Cap the doctor loop at 3 iterations.** After three doctor → fix → restart
+   cycles still failing, stop and present the full report for manual triage.
+
+## The setup tiers (walk in order; for each, state what breaks if skipped)
+
+### Tier 0 — Reads (nothing to do)
+On-chain reads, subgraph reads, backend reads, IPFS reads all work on shared
+public defaults. **Skip cost: none.** The only downside is the shared Graph API
+key + public RPC/IPFS gateways are rate-limited and billable-shared — fine for
+light use, upgrade under Tier 3 for heavy use.
+
+### Tier 1 — Signing (to vote / execute / broadcast)
+WalletConnect is **available by default** (shared project id). To sign: run
+`dexe_wc_connect`, scan the QR with a wallet, approve each tx on your phone. No
+key touches disk.
+- **Skip cost:** you can build calldata and read, but can't broadcast.
+- Optional: set your own `DEXE_WALLETCONNECT_PROJECT_ID` (free at
+  cloud.reown.com) to stop sharing the default id.
+- Only if the user *insists* on unattended/CI signing → hot key ladder below.
+
+### Tier 2 — Creating DAOs / proposals (the one hard blocker)
+Creating a DAO or proposal pins metadata to IPFS, which needs a **Pinata JWT**
+(`DEXE_PINATA_JWT`). This is the only thing reads/signing can't default around.
+- **Skip cost:** `dexe_dao_create`, `dexe_proposal_create`, and metadata uploads
+  refuse up front (no on-chain tx is attempted).
+- How to get one (say this to non-technical users): sign up free at
+  https://app.pinata.cloud → API Keys → New Key → enable `pinJSONToIPFS` and
+  `pinFileToIPFS` → copy the JWT.
+- Validate it before saving: `GET https://api.pinata.cloud/data/testAuthentication`
+  with header `Authorization: Bearer <jwt>` should return `{"message":
+  "Congratulations! ..."}`. (The `npx dexe-mcp init` wizard does this check for you.)
+
+### Tier 3 — Reliability upgrades (optional, offer when errors appear)
+- **Private RPC** — if a read fails with *"public RPC unstable"*: set
+  `DEXE_RPC_URL_MAINNET` (chain 56) / `DEXE_RPC_URL_TESTNET` (chain 97) to an
+  Alchemy / QuickNode / Ankr URL. **Skip cost:** occasional rate-limit flakiness.
+- **Dedicated IPFS gateway** — if a read fails with *"public IPFS gateways are
+  failing"*: set `DEXE_IPFS_GATEWAY` (a free Pinata dedicated gateway comes with
+  your JWT — `https://<subdomain>.mypinata.cloud`). **Skip cost:** slower/flaky
+  metadata reads.
+- **Own Graph key** — if `dexe_doctor` shows `env.sharedDefaults`: set your own
+  `DEXE_SUBGRAPH_*_URL` (with your Graph key embedded, or `DEXE_GRAPH_API_KEY`).
+  **Skip cost:** you share a rate-limited, billable key.
 
 ## Algorithm
 
 1. Call `dexe_doctor` (no input).
-2. Read the `summary` and `checks` arrays from the structured response.
-   - If `summary.status === "pass"`, congratulate the user — no work to do.
-   - If only `warnings`, surface them but don't block.
-3. For every `fail`:
-   - If it is an env presence/validation issue: collect the env key.
-   - If it is a network reachability issue (RPC unreachable, Pinata 401):
-     use the `remediation` field verbatim; ask the user for a replacement
-     value.
-4. Batch the questions by category (RPC, IPFS, subgraph, signer) using
-   `AskUserQuestion`. One question per category, not one per key.
-5. Locate the `.env` file. The startup banner in the doctor response shows
-   `environment.envFile`; if absent, look at the repo root (where
-   `package.json` lives — usually `D:\dev\dexe-mcp\.env`).
-6. Edit `.env` with the Edit tool. For each provided value:
-   - If the key already exists, replace its line.
-   - Otherwise, append `KEY=value` at the bottom (preserve trailing newline).
+2. Read `summary` and `checks` from the structured response.
+   - `summary.status === "pass"` (only warnings) → reads are healthy. Ask which
+     tier (if any) the user wants; don't block on warnings.
+   - Treat `warn` checks (`chain.publicRpcFallback`, `env.sharedDefaults`) as
+     *offers*, not problems.
+3. For each `fail` or the user's chosen tier, collect the env key(s). Use the
+   check's `remediation` verbatim for network failures.
+4. Batch questions by tier/category with `AskUserQuestion` — one question per
+   tier, not one per key. Only ask for what the chosen tier needs.
+5. Locate `.env` at the repo root (where `package.json` lives — usually
+   `D:\dev\dexe-mcp\.env`). The doctor/banner shows the env-file path.
+6. Edit `.env` with the Edit tool: replace the key's line if present, else
+   append `KEY=value` (preserve the trailing newline).
 7. Tell the user, verbatim:
    > Edits saved to `.env`. **Restart Claude Code** so the new values load
-   > (`Ctrl+R` rebuilds the session, or quit and relaunch). Then I will
-   > re-run `dexe_doctor` to confirm.
-8. After restart, call `dexe_doctor` again. If still failing, go to step 3.
-   Iterate at most 3 times.
-9. If after 3 iterations there are still failures, present the full
-   `checks` array and tell the user the remaining issues need manual
-   investigation (likely: bad credentials, account suspended, paid plan
-   required, or a corporate proxy blocking the relevant host).
+   > (quit and relaunch). Then I'll re-run `dexe_doctor` to confirm.
+8. After restart, re-run `dexe_doctor`. If still failing, go to step 3. Iterate
+   at most 3 times.
+9. After 3 iterations still failing, present the full `checks` array — remaining
+   issues need manual triage (bad credentials, suspended account, paid-plan
+   required, corporate proxy).
 
 ## Signer mode escalation
 
-If a user wants broadcast capability, walk this ladder (top = safest):
-
-1. **WalletConnect (`DEXE_WALLETCONNECT_PROJECT_ID`).** Key stays on phone.
-   Every tx is approved manually.
-2. **Safe multisig (`DEXE_SAFE_TX_SERVICE_URL`).** Proposes tx to a Safe;
-   owners co-sign separately.
-3. **Hot key (`DEXE_PRIVATE_KEY`).** Plaintext on disk. Convenient for CI
-   bots, dangerous for humans. Show this warning before writing:
-   > Setting `DEXE_PRIVATE_KEY` stores your key in plaintext at `.env`.
-   > Anyone who reads the file can drain that wallet. Are you sure you
-   > don't want WalletConnect (above) or a Safe multisig instead?
-4. Refuse to proceed past step 3 without an explicit "yes" confirming
-   the user understands the trade-off.
+If the user wants signing beyond phone-approval WalletConnect, walk this ladder
+(top = safest):
+
+1. **WalletConnect (default).** `dexe_wc_connect` → approve on phone. No key on
+   disk. This is already available; prefer it.
+2. **Safe multisig (`DEXE_SAFE_TX_SERVICE_URL`).** Proposes tx to a Safe; owners
+   co-sign separately.
+3. **Hot key (`DEXE_PRIVATE_KEY`).** Plaintext on disk. Convenient for CI bots,
+   dangerous for humans. Show this before writing:
+   > Setting `DEXE_PRIVATE_KEY` stores your key in plaintext at `.env`. Anyone
+   > who reads the file can drain that wallet. Are you sure you don't want
+   > WalletConnect (already available) or a Safe multisig instead?
+4. Refuse to proceed to a hot key without an explicit "yes" confirming the
+   trade-off.
 
 ## .env precedence trap
 
-If `dexe_doctor` returns a check named `env.<KEY>` with the message
-"shadowed by host env block", the user has the same key defined in BOTH
-`.env` AND `.claude.json`. The host wins. Tell them to either:
-  - remove the key from `.claude.json` `env` block (use `.env`), OR
-  - update it in `.claude.json` instead of `.env`.
-
-Whichever they pick, restart Claude Code after.
+If `dexe_doctor` returns a check named `env.<KEY>` with "shadowed by host env
+block", the same key is defined in BOTH `.env` and `.claude.json`. The host
+wins. Tell them to keep it in one place (prefer `.env`) and restart.
 
 ## Useful tools (reference)
 
 - `dexe_doctor` — diagnostic (read-only, safe to call repeatedly).
-- `dexe_get_config` — current chain/signer state (lower detail than doctor).
-- `npx dexe-mcp doctor` — CLI form of the same diagnostic. Useful when the
-  MCP server itself failed to start.
-- `npx dexe-mcp init` — fresh-start wizard. Overwrites `.env`. Use for new
-  installations, not for fixing an existing setup.
+- `dexe_context` — signer/mode + env readiness + `usingSharedDefaults` list.
+- `npx dexe-mcp doctor` — CLI form; useful when the MCP server failed to start.
+- `npx dexe-mcp init` — fresh-start wizard (prompts + live-validates Pinata JWT).
+  Overwrites `.env`; use for new installs, not for fixing an existing setup.

package/dist/cli/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AA+BA,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA2MzC;AA0CD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB3E;AA2HD,wBAAgB,YAAY,IAAI,MAAM,CAWrC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AA+BA,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CA8MzC;AA0CD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB3E;AA2HD,wBAAgB,YAAY,IAAI,MAAM,CAWrC"}

package/dist/cli/init.js

@@ -28,8 +28,10 @@ export async function run() {
     try {
         output.write(line("dexe-mcp init — onboarding wizard"));
         output.write(line("─".repeat(64)));
-        output.write(line("Builds a minimal .env. Answers are stored in plaintext;"));
-        output.write(line("use WalletConnect or readonly mode if that worries you."));
+        output.write(line("Reads already work with ZERO config (RPC, subgraphs, backend,"));
+        output.write(line("IPFS reads, WalletConnect). This only overrides a default or"));
+        output.write(line("enables writes. Answers are stored in plaintext; use WalletConnect"));
+        output.write(line("or readonly mode if that worries you."));
         output.write("\n");
         const repoRoot = findRepoRoot();
         // ---- Top-level intent -----------------------------------------------
@@ -85,8 +87,9 @@ export async function run() {
             ? (await ask(rl, "IPFS gateway URL", "https://gateway.pinata.cloud")).trim()
             : "";
         // ---- Subgraph (optional) -------------------------------------------
-        output.write(line("Subgraph reads need a Graph API key (free at thegraph.com)."));
-        const graphKey = (await ask(rl, "Graph API key (blank to skip subgraph reads)", "")).trim();
+        output.write(line("Subgraph reads work by default via a shared DeXe Graph key."));
+        output.write(line("Set your own only for heavy use (blank keeps the default)."));
+        const graphKey = (await ask(rl, "Graph API key (blank = use shared default)", "")).trim();
         // ---- Signer mode ---------------------------------------------------
         output.write(line(""));
         output.write(line("Signer mode:"));