dexe-mcp 0.11.1 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,145 @@
 # Changelog
 
+## 0.15.0 — 2026-07-04
+
+### One-command install — Claude Code plugin + zero-config reads
+
+Onboarding overhaul: an average user should install dexe-mcp from inside Claude
+with no terminal, no JSON editing, and no env vars until they actually want to
+write. No new MCP tools (still 156); this is packaging, CLI, and docs.
+
+- **Claude Code plugin + marketplace.** New `.claude-plugin/marketplace.json`
+  (repo root) and `dexe-plugin/` (`.claude-plugin/plugin.json` + `mcp.json` +
+  the shipped skills). Users install in-session:
+
+  ```
+  /plugin marketplace add edward-arinin-web-dev/dexe-mcp
+  /plugin install dexe@dexe-mcp
+  ```
+
+  The plugin registers the MCP server (launched via `npx -y dexe-mcp@0.15.0`,
+  version pinned) and auto-discovers the governance skills — namespaced
+  `dexe:<skill>`. Both manifests pass `claude plugin validate`.
+- **Zero-config reads (server-side public-RPC fallback).** When no RPC is
+  configured, `loadConfig()` seeds public BSC endpoints (chains 56 + 97, default
+  **56**) so `dao_info` / `read_treasury` / etc. work out of the box — the plugin
+  ships **no env**, so there is no `.claude.json`-shadow trap. Public dataseed
+  nodes rate-limit and lack archive history: a startup banner + a
+  `chain.publicRpcFallback` doctor advisory nudge users to set their own RPC.
+  Opt out with `DEXE_DISABLE_PUBLIC_RPC=1`. `DexeConfig` gains
+  `usingPublicRpcFallback`. (A private key set without an RPC now signs against
+  the public fallback rather than erroring; guards still apply — set your own RPC
+  for reliable broadcasting.)
+- **Project `.env` reaches the server (writes path).** `src/index.ts` now loads
+  the **project (cwd) `.env` first**, then the package-relative `.env`. This is
+  what makes `/dexe-setup` (which edits the project `.env`) reach a server
+  launched via `npx` from the plugin, whose package dir sits in the npx cache.
+- **`npx dexe-mcp skills` — skills-only, no env interview.** New non-interactive
+  subcommand (`--global` for `~/.claude/skills`), reusing `installSkills()`. And
+  `init` now opens with a top-level choice — *just skills* / *full setup* /
+  *both* (or `init --skills-only`) — so it never dives into the env wizard
+  unasked. Fixes the reported "I only wanted the skills" onboarding surprise.
+- **Skills relocated** to `dexe-plugin/skills/` (single source of truth for both
+  the plugin and the CLI copy). `package.json` `files` updated accordingly.
+- **Docs.** README leads with a no-terminal **Install in Claude Code** block;
+  new [`docs/INSTALL.md`](docs/INSTALL.md) (non-technical, plugin-first);
+  `SETUP.md` / `SKILLS.md` / `ENVIRONMENT.md` updated for the plugin path, the
+  `skills` subcommand, the public-RPC fallback, and the project-`.env` load.
+
+## 0.14.0 — 2026-07-04
+
+### Persistent state + `dexe_context`
+
+Phase 3 of the reliability/token plan: stop starting every session from zero.
+
+- **`dexe_context` (new tool; core profile; +1 → 156 tools).** One read that
+  orients an agent: signer + mode, active/configured chains, env readiness, and
+  the persisted operational state — DAOs deployed and proposals broadcast in
+  prior sessions — plus deposited voting power in the most recent DAO. Server
+  `instructions` now say to call it first.
+- **Persistent state store** (`src/lib/stateStore.ts`). Versioned JSON at
+  `DEXE_STATE_PATH` (default `~/.dexe-mcp/state.json`), atomic write (temp +
+  rename), tolerant load (missing/corrupt/newer → empty, never throws).
+  `dexe_dao_create` auto-records the deployed DAO and `dexe_proposal_create`
+  auto-records a broadcast proposal — both best-effort (a state-write error
+  never breaks a broadcast).
+- **`DEXE_STATE_PATH` env** added to `ENV_SPEC`, `loadConfig()`, `.env.example`,
+  and `docs/ENVIRONMENT.md`. `dexe_doctor` gains a writable-path check for it.
+- **Tests** — `tests/lib/stateStore.test.ts` (atomic write, dedupe, corrupt/
+  version-mismatch tolerance, wallet labels); `gate.test.ts` updated to 156 and
+  asserts `dexe_context` in the default profile.
+- Skills updated to start with `dexe_context`.
+
+## 0.13.0 — 2026-07-04
+
+### Toolset profiles — slim default (BREAKING)
+
+Phase 2 of the reliability/token plan: cut the per-session `tools/list` cost by
+gating which tools register.
+
+- **`DEXE_TOOLSETS` gating** (`src/tools/gate.ts`). Named profiles — `core`,
+  `proposals`, `read`, `vote`, `governor`, `dev`, `full` — select which of the
+  155 tools load. `TOOLSETS` maps each profile to an exact tool-name set; the
+  union of the six named sets equals the full surface (asserted in tests), so
+  every tool is reachable under some profile. Applied as a one-line proxy wrap
+  in `registerAll()` — the 30+ register files are unchanged. A typo/unknown set
+  name falls back to `full` (never silently strips).
+- **BREAKING: default is now `core,proposals`** (~71 tools), not all 155.
+  Measured `tools/list`: full **205 KB** → default **111 KB (−46%)**; the
+  max-slim `DEXE_TOOLSETS=core` is **48 KB (−77%)**, viable because
+  `dexe_dao_create` / `dexe_proposal_create` cover the common flows server-side.
+  See [MIGRATION.md](docs/MIGRATION.md#012x--0130--slim-default-toolset-breaking).
+- **`DEXE_TOOLSETS` env** added to `ENV_SPEC`, `loadConfig()`, `.env.example`,
+  and `docs/ENVIRONMENT.md`. `dexe_doctor` now reports the active profile,
+  loaded-tool count, and the `full` restore hint. Startup stderr banner states
+  the active profile.
+- **Expanded server `instructions`** (~700 chars): prefer the composite flow
+  tools, approve UserKeeper not GovPool, testnet-first deploys, the toolsets
+  hint, and the shipped-skills hint.
+- **Tests** — `tests/tools/gate.test.ts`: per-profile resolution, union==155,
+  every set-name is a real tool, default subset assertions, and a real
+  in-memory `tools/list` size measurement.
+- Note: the plan's "slim `dexe_compile` schema" item was moot — the current
+  `dexe_compile` input schema is already a single field (the 11 KB/49-field
+  figure was stale). The token win is the gating above.
+
+## 0.12.0 — 2026-07-03
+
+### Flow-first facade + preflight guards + shipped skills
+
+Phase 1 of the flow-reliability plan: "create a DAO" / "create proposal X" is now
+**one tool call** with server-side validation, and the recurring failure modes are
+encoded as guards + installable skills instead of re-derived each session.
+
+- **`dexe_dao_create` (new composite tool)** — one-call DAO deploy: uploads DAO
+  profile metadata to IPFS, builds `PoolFactory.deployGovPool` (reusing the exact
+  predicted-address wiring / settings auto-expand / executorDescription upload
+  from `dexe_dao_build_deploy`, now extracted to a shared `buildDeployGovPool`),
+  pre-flights the four silent-revert modes, then signs+broadcasts (or returns the
+  payload). Validate on BSC testnet (chain 97). Tool count 154 → **155**.
+- **`dexe_proposal_create` extended to catalog types** — `proposalType` now
+  accepts `token_transfer`, `withdraw_treasury`, `change_voting_settings`,
+  `add_expert`, `remove_expert`, `token_distribution`, `token_sale`, and
+  `custom_abi` (inputs passed in `params`); the tool builds correct calldata +
+  IPFS metadata server-side via a shared builder registry
+  (`src/lib/proposalBuilders.ts`, byte-parity-tested). Any other catalog type
+  returns an actionable error naming its dedicated `dexe_proposal_build_*` tool.
+- **Preflight guard library** (`src/lib/preflight.ts`) — named checks with
+  remediation for the 10 documented failure modes: canonical proposal-metadata
+  zod shape, approve-UserKeeper-not-GovPool, deposited-power vs votingPower,
+  locked-tokens-between-proposals, deploy cap>minted / LINEAR initData /
+  non-zero userKeeper asset / mainnet treasury remainder, single-sourced
+  ProposalState ordering, avatar-is-JPEG, off-chain type/quorum, blacklist
+  recipient. Wired into `dexe_proposal_create` and `dexe_dao_create`.
+- **Shipped skills** (`skills/` → published in the npm package) —
+  `dexe-create-dao`, `dexe-create-proposal`, `dexe-vote-execute`, `dexe-otc`,
+  `dexe-setup`: exact tool-sequence recipes with the relevant failure modes and
+  the chain-97-first rule. `npx dexe-mcp init` now offers to install them into
+  `./.claude/skills` (project) or `~/.claude/skills` (global), idempotently. New
+  [`docs/SKILLS.md`](docs/SKILLS.md).
+- **Tests** — `tests/lib/preflight.test.ts` (per-guard) and
+  `tests/lib/proposalBuilders.test.ts` (calldata byte-parity + registry coverage).
+
 ## 0.11.1 — 2026-07-03
 
 ### OTC date clarity (UTC)

package/README.md

@@ -9,7 +9,7 @@
   <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=E07AFF"></a>
   <a href="https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/npm/l/dexe-mcp.svg?style=flat-square&labelColor=0b0f1e&color=FFC878"></a>
   <a href="https://modelcontextprotocol.io"><img alt="MCP-compatible" src="https://img.shields.io/badge/MCP-compatible-9BB4FF?style=flat-square&labelColor=0b0f1e"></a>
-  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp"><img alt="tools" src="https://img.shields.io/badge/tools-154-7CF2D1?style=flat-square&labelColor=0b0f1e"></a>
+  <a href="https://github.com/edward-arinin-web-dev/dexe-mcp"><img alt="tools" src="https://img.shields.io/badge/tools-156-7CF2D1?style=flat-square&labelColor=0b0f1e"></a>
   <a href="https://github.com/edward-arinin-web-dev/dexe-mcp"><img alt="proposal types" src="https://img.shields.io/badge/proposal--types-33-E07AFF?style=flat-square&labelColor=0b0f1e"></a>
 </p>
 
@@ -22,7 +22,8 @@
 </p>
 
 <p align="center">
-  <a href="#quickstart"><b>Quickstart</b></a> &nbsp;·&nbsp;
+  <a href="#install-in-claude-code-no-terminal"><b>Install</b></a> &nbsp;·&nbsp;
+  <a href="#quickstart">Quickstart</a> &nbsp;·&nbsp;
   <a href="#what-you-can-build">What you can build</a> &nbsp;·&nbsp;
   <a href="#built-for-whats-next">Built for what's next</a> &nbsp;·&nbsp;
   <a href="#tool-catalog">Tool catalog</a> &nbsp;·&nbsp;
@@ -32,6 +33,27 @@
 
 ---
 
+## Install in Claude Code (no terminal)
+
+Two lines, typed inside Claude Code. No npm, no JSON to edit, no keys:
+
+```
+/plugin marketplace add edward-arinin-web-dev/dexe-mcp
+/plugin install dexe@dexe-mcp
+```
+
+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.
+
+**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.
+
+> Using **Cursor, ChatGPT, or another MCP client**, or prefer the terminal? → [**docs/INSTALL.md**](./docs/INSTALL.md)
+
+---
+
 ## The shift
 
 For a decade, DAOs lived behind dashboards. Every action was a click. Every read was a tab. Every coordination loop needed a human at the keyboard.
@@ -40,7 +62,7 @@ That era is ending.
 
 LLMs can now reason about voting power, weigh proposals against a mandate, draft calldata, simulate execution, and ask your wallet to sign — **continuously, across every DAO you care about, all at once.** What was a UI is becoming a conversation. What was a treasurer's spreadsheet is becoming an always-on agent.
 
-**`dexe-mcp` is the substrate that makes it real for the DeXe stack — and now for external OpenZeppelin Governor DAOs as well.** One MCP server. 154 typed tools across 19 groups. Every flow the DeXe frontend exposes — plus a generic `dexe_gov_*` surface targeting Uniswap, Compound, and Optimism.
+**`dexe-mcp` is the substrate that makes it real for the DeXe stack — and now for external OpenZeppelin Governor DAOs as well.** One MCP server. 156 typed tools across 19 groups. Every flow the DeXe frontend exposes — plus a generic `dexe_gov_*` surface targeting Uniswap, Compound, and Optimism.
 
 |     | What you get |
 |-----|------|
@@ -87,6 +109,8 @@ The next generation of DAOs will be **operated by language, not by clicks.**
 
 ## Quickstart
 
+> **In Claude Code?** Skip this — use the [two-line plugin install](#install-in-claude-code-no-terminal) above. The steps below are for **other MCP clients** (Cursor, ChatGPT, custom agents) and terminal/manual setups. Reads need no env at all; env is only for IPFS uploads and broadcasting.
+
 **Fastest path — wizard + diagnostic:**
 
 ```bash
@@ -194,7 +218,8 @@ All optional. Tools that need a missing variable fail with a clear, actionable m
 
 Full docs in [`docs/`](https://github.com/edward-arinin-web-dev/dexe-mcp/tree/main/docs):
 
-- [**`docs/TOOLS.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md) — complete catalog of all 154 tools, grouped, with one-line descriptions and required envs.
+- [**`docs/TOOLS.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md) — complete catalog of all 156 tools, grouped, with one-line descriptions and required envs.
+- [**`docs/SKILLS.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/SKILLS.md) — shipped Claude Code skills (create-dao / create-proposal / vote-execute / otc / setup) and how `npx dexe-mcp init` installs them.
 - [**`docs/GOVERNOR.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/GOVERNOR.md) — external OpenZeppelin / Bravo Governor surface (Uniswap, Compound, Optimism). Family branching, fixture map, paste-able JSON examples, Tally parity harness.
 - [**`docs/WALLETCONNECT.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/WALLETCONNECT.md) — `walletconnect` signer mode: phone-approved broadcast with no hot key. Phase A (config) + Phase B (live relay, `dexe_wc_connect` / `dexe_wc_disconnect`, per-tx phone approval) shipped in v0.7.0, validated end-to-end with a live MetaMask-mobile round-trip on BSC testnet.
 - [**`docs/USAGE.md`**](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/USAGE.md) — 10 worked examples (deploy DAO, create/vote/execute proposals, delegate, validator chamber, decode calldata, off-chain proposals, multicall batching). Copy-pasteable JSON.
@@ -207,7 +232,11 @@ Full docs in [`docs/`](https://github.com/edward-arinin-web-dev/dexe-mcp/tree/ma
 
 ## Tool catalog
 
-**154 tools, 19 groups.** Run `dexe_proposal_catalog` at runtime for the live proposal-type map. Full per-tool reference → [`docs/TOOLS.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md).
+**156 tools, 19 groups.** Run `dexe_proposal_catalog` at runtime for the live proposal-type map. Full per-tool reference → [`docs/TOOLS.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md).
+
+> **Toolset profiles (v0.13.0):** a default session loads a slim **~72 tools** (`DEXE_TOOLSETS=core,proposals`), not all 156 — cutting `tools/list` ~46%. Add profiles (`read`, `vote`, `governor`, `dev`) or set `DEXE_TOOLSETS=full` to restore everything; `DEXE_TOOLSETS=core` is the deepest cut (~76%). `dexe_doctor` shows the active profile. See [TOOLS.md § Toolset profiles](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/TOOLS.md#toolset-profiles).
+>
+> **Persistent context (v0.14.0):** `dexe_context` (call first) returns your signer, active chain, env readiness, and the DAOs/proposals recorded in prior sessions (state at `~/.dexe-mcp/state.json`, override `DEXE_STATE_PATH`).
 
 | Group | # | What it gives you |
 |-------|---|------|
@@ -215,13 +244,13 @@ Full docs in [`docs/`](https://github.com/edward-arinin-web-dev/dexe-mcp/tree/ma
 | **Contract introspection** | 10 | Ask the protocol about itself — list contracts, fetch ABIs, look up selectors, read NatSpec, view source, decode arbitrary calldata or full proposal payloads. The agent's reverse-engineer toolkit. |
 | **DAO reads** | 20 | Everything you'd see on a DAO dashboard, returned as JSON — `dao_info`, predicted helper addresses, proposal state/list/voters, voting power, treasury, settings, validators, staking, distributions, privacy policy, plus `dexe_proposal_risk_assess` (treasury-safety risk readout). |
 | **IPFS** | 9 | Pinata uploads for files / avatars / DAO + proposal metadata, smart metadata updates, deterministic identicon generation, gateway-fallback fetch, CID computation without uploading. |
-| **DAO deploy** | 1 | `dexe_dao_build_deploy` — encodes the full nested `PoolFactory.deployGovPool` struct with predicted helper addresses pre-wired. From idea to a live DAO in one signed tx. |
+| **DAO deploy** | 2 | `dexe_dao_create` — one-call composite: DAO profile → IPFS → deploy with the four revert-guards pre-flighted, signs when configured. `dexe_dao_build_deploy` — the lower-level encoder for the full nested `PoolFactory.deployGovPool` struct with predicted helper addresses pre-wired. |
 | **Proposal catalog + primitives** | 5 | `dexe_proposal_catalog` enumerates **all 33** proposal types with metadata + gating. Primitives `_build_external`, `_build_internal`, `_build_custom_abi`, `_build_offchain` cover anything not in a named wrapper. |
 | **External proposal wrappers** | 20 | Named builders for every common action: token transfer / distribution / sale (single + multi-tier), treasury withdraw, validators, experts, staking tier, math model, blacklist, reward multiplier, apply to DAO, modify profile, change voting settings, new proposal type, whitelist, and more. |
 | **Internal validator wrappers** | 4 | Validator-chamber proposals: `_change_validator_balances`, `_change_validator_settings`, `_monthly_withdraw`, `_offchain_internal_proposal`. |
 | **Off-chain backend** | 8 | Full DeXe-backend integration — nonce + SIWE login, off-chain proposal creation (single-option / multi-option / for-against / settings), off-chain vote + cancel. |
 | **Vote / stake / delegate / execute / claim** | 26 | Every direct EOA write on `GovPool` and `Validators` — deposit, vote, delegate, undelegate, execute, claim rewards, micropool rewards, staking flows, token-sale buy/claim/vesting, distribution claim, NFT multiplier lock/unlock, privacy policy signing, multicall. |
-| **Composite flows + diagnostics** | 6 | High-level flows for power users, plus server self-check: `_proposal_create`, `_proposal_vote_and_execute`, `_tx_send`, `_tx_status`, `_get_config`, `_doctor`. Signing tools opt-in via `DEXE_PRIVATE_KEY`. |
+| **Composite flows + diagnostics** | 7 | High-level flows + orientation: `_context` (call first — signer/chain/known-DAOs from prior sessions), `_proposal_create`, `_proposal_vote_and_execute`, `_tx_send`, `_tx_status`, `_get_config`, `_doctor`. Signing tools opt-in via `DEXE_PRIVATE_KEY`. |
 | **Subgraph reads** | 7 | The Graph queries: DAO list, members, experts, validator list, user activity, delegation map, OTC sale tiers. Decentralized-network endpoints + RPC fallback. |
 | **Merkle utility** | 2 | `dexe_merkle_build`, `dexe_merkle_proof` — OZ `StandardMerkleTree`-compatible. For whitelisted sales and airdrops. |
 | **OTC composites** | 4 | Full project-owner + buyer flows over `TokenSaleProposal`: open multi-tier sale, check buyer status, buy native or with merkle proof, claim vested payouts. See [`docs/OTC.md`](https://github.com/edward-arinin-web-dev/dexe-mcp/blob/main/docs/OTC.md). |

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

@@ -0,0 +1,99 @@
+---
+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".
+---
+
+# dexe-create-dao
+
+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
+
+**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`.
+
+## Recipe
+
+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.
+
+```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
+  }
+})
+```
+
+## 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.
+
+## Decimal conventions (must match the frontend)
+
+- `quorum`, `quorumValidators`, `voteRewardsCoefficient`: **25-dec** wei (50% = `5e26`).
+- `minVotes*`, `cap`, `mintedTotal`, `amounts`, `individualPower`, rewards: **18-dec** wei.
+- `duration*`, `executionDelay`: plain **seconds** as string.
+- `delegatedVotingAllowed` is **inverted**: `true` DISABLES delegation.
+
+## 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`.
+
+Related: [[dexe-create-proposal]], [[dexe-vote-execute]].

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

@@ -0,0 +1,84 @@
+---
+name: dexe-create-proposal
+description: |
+  Create any DeXe governance proposal with the one-call `dexe_proposal_create`
+  composite — it runs approve→deposit→createProposalAndVote and uploads correct
+  IPFS metadata for you. Covers every wired proposalType + params recipe and the
+  metadata/ABI/blacklist failure modes. Use when the user says "create a proposal",
+  "transfer treasury", "add an expert", "change voting settings", "start a token sale".
+---
+
+# dexe-create-proposal
+
+`dexe_proposal_create` builds a governance proposal in **one call**: it checks
+token balance, approves the **UserKeeper** (not GovPool), deposits, uploads IPFS
+metadata with the correct `{proposalName, proposalDescription, category, isMeta,
+changes}` shape, and calls `createProposalAndVote`. With `DEXE_PRIVATE_KEY` it
+signs+broadcasts; otherwise it returns ordered `TxPayload`s.
+
+Call **`dexe_context`** first — it returns the signer, active chain, and the
+DAOs/proposals from prior sessions (so you already have the `govPool` to target).
+
+**Do not hand-sequence** approve/deposit/create, and do not hand-build the IPFS
+metadata — the composite does both correctly. **Do not guess ABIs/selectors**;
+the wired builders encode canonical calldata. Only reach for `dexe_get_methods`
+when composing a truly custom call.
+
+## Pick a proposalType
+
+Pass `proposalType` + the type's inputs in `params`:
+
+| proposalType | params |
+|---|---|
+| `token_transfer` | `{ token, recipient, amount, isNative? }` |
+| `withdraw_treasury` | `{ receiver, token?, amount?, nftAddress?, nftIds? }` (emits external `token.transfer`) |
+| `change_voting_settings` | `{ govSettings, settings:[…], settingsIds? }` (empty ids ⇒ addSettings) |
+| `add_expert` | `{ expertNftContract, scope:"local"\|"global", nominatedUser, uri? }` |
+| `remove_expert` | `{ expertNftContract, scope, nominatedUser }` |
+| `token_distribution` | `{ distributionProposal, proposalId, token, amount, isNative? }` |
+| `token_sale` | `{ tokenSaleProposal, tiers:[…], latestTierId? }` |
+| `custom_abi` | `{ target, signature, method, args?, value? }` |
+| `modify_dao_profile` | top-level `newDaoName/newDaoDescription/newAvatarCID/newWebsiteUrl/newSocialLinks` |
+| `custom` | top-level `actionsOnFor:[{executor,value,data}]` (+ optional `category`) |
+
+Any other catalog type → the tool errors and names the dedicated
+`dexe_proposal_build_*` tool. Discover all 33 types with `dexe_proposal_catalog`.
+
+## Example: transfer treasury tokens
+
+```jsonc
+dexe_proposal_create({
+  govPool: "0x…",
+  chainId: 97,
+  proposalType: "token_transfer",
+  title: "Pay contributor grant",
+  description: "Q3 grant to @alice.",
+  params: { token: "0xGovToken", recipient: "0xAlice", amount: "1000000000000000000" }
+})
+```
+
+## Failure modes this guards against
+
+1. **Sequence** — the composite runs approve→deposit→create; never do it by hand.
+2. **Metadata shape** — auto-built + preflight-validated (`{proposalName,
+   proposalDescription, category, isMeta:false, changes:{proposedChanges,
+   currentChanges}}`). Wrong shape breaks the frontend indexer/diff.
+3. **ABI/selector guessing** — wired builders use canonical signatures; tuple
+   field order is easy to get wrong by hand.
+4. **votingPower vs tokenBalance** — deposited power is
+   `tokenBalance(user,0).balance − ownedBalance`, not `votingPower()` (which is 0
+   without a deposit). The composite computes it.
+6. **Approve target** — the composite approves the **UserKeeper** (which does
+   `transferFrom`), never GovPool.
+8. **withdraw_treasury** emits an external `token.transfer`, never
+   `GovPool.withdraw` ("Gov: invalid internal data").
+10. **Blacklisted recipient** — token transfers to a blacklisted address are
+    refused up front (they'd stick the proposal in `SucceededFor` forever).
+
+## No signer? Preview first
+
+Pass `dryRun: true` to get the ordered `TxPayload`s without broadcasting (also
+the default behavior when no signer is configured). Then broadcast via
+`dexe_tx_send` or a connected wallet.
+
+Next step after it passes: [[dexe-vote-execute]].

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

@@ -0,0 +1,73 @@
+---
+name: dexe-otc
+description: |
+  Run a DeXe OTC token sale end-to-end — open a multi-tier TokenSaleProposal,
+  vote+execute it, then buyers check status / buy / claim. Covers the five
+  dexe_otc_* composites plus the PRECISION-1e25 rate, native-BNB sentinel, and
+  claim-timing gotchas. Use when the user mentions "OTC", "token sale", "sell DAO
+  tokens", "buy from a tier", "claim vested tokens".
+---
+
+# dexe-otc
+
+An OTC DAO sells its own token via on-chain `TokenSaleProposal` tiers. Each step
+is one MCP call; calldata auto-broadcasts when `DEXE_PRIVATE_KEY` is set.
+Validate on **BSC testnet (chain 97)** first. Full recipe + runnable proof:
+`docs/OTC.md` and `scripts/lifecycle-otc.mjs`.
+
+## The five composites
+
+| Tool | Role |
+|---|---|
+| `dexe_otc_dao_open_sale` | multi-tier `createTiers` envelope + IPFS metadata + deposit + `createProposalAndVote`. `buildOnly:true` returns just the envelope. |
+| `dexe_otc_list_sales_for_dao` | list a DAO's tiers (prices, `totalSold`, `isOff`, UTC times). |
+| `dexe_otc_buyer_status` | render-ready buyer view: prices, claimable, vesting, auto-merkle proof. |
+| `dexe_otc_buyer_buy` | preflight balance/allowance + approve + `buy()`; native path uses the sentinel + `value`. |
+| `dexe_otc_buyer_claim_all` | claims tiers with `canClaim && !isClaimed`, withdraws vested; `noop` when nothing pending. |
+
+## Owner flow
+
+1. `dexe_dao_predict_addresses` → get `govPool` / `govToken` / `govTokenSale`.
+2. Deploy with treasury pre-seeded (mint to the predicted `govPool` via
+   `tokenParams.users[]`) — see [[dexe-create-dao]].
+3. `dexe_otc_dao_open_sale` with tiers (schema below).
+4. Poll `dexe_proposal_state` until `SucceededFor` (index 4; it briefly sits in
+   `Locked`=6), then `dexe_vote_build_execute` → broadcast.
+
+## Buyer flow
+
+`dexe_otc_buyer_status` → `dexe_otc_buyer_buy` → (after the sale window closes)
+`dexe_otc_buyer_claim_all`.
+
+## Critical gotchas
+
+- **Exchange rate is PRECISION 1e25**, not 1e18. 1:1 = `"10000000000000000000000000"`.
+- **Native BNB = `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`** (ETHEREUM_ADDRESS),
+  never `0x0…0` — a zero-address purchase token makes the tier unbuyable. Buy
+  tools accept `0x0` as an alias but emit the sentinel.
+- **`canClaim` needs `block.timestamp ≥ saleEndTime + claimLockDuration`** — buyers
+  wait for the window to close even when `claimLockDuration:0`.
+- **`maxAllocationPerUser == 0` means unlimited**, not zero — set a real cap.
+- **Treasury must hold the sale token before the sale opens** — pre-seed at deploy.
+- **`vestingPercentage` is a human percent 0–100** (auto-scaled by 1e25).
+- **Merkle tiers** need the whitelist JSON on IPFS; `open_sale` auto-uploads when
+  `uri` is empty (needs `DEXE_PINATA_JWT`). Roots via `dexe_merkle_build`.
+
+## Tier schema (abridged)
+
+```jsonc
+{
+  "name": "Public Tier 1", "description": "",
+  "totalTokenProvided": "<wei>",
+  "saleStartTime": "<unix sec>", "saleEndTime": "<unix sec>", "claimLockDuration": "0",
+  "saleTokenAddress": "0x…",
+  "purchaseTokenAddresses": ["0xEeee…EEeE"],   // native, or ERC20 addresses
+  "exchangeRates": ["10000000000000000000000000"],
+  "minAllocationPerUser": "0", "maxAllocationPerUser": "<wei, non-zero>",
+  "vestingSettings": { "vestingPercentage": "0", "vestingDuration": "0", "cliffPeriod": "0", "unlockStep": "0" },
+  "participation": []   // AND-list; empty = open tier
+}
+```
+
+Do not modify OTC tool behavior lightly — the v0.11.x OTC surface is validated
+E2E on mainnet. See `docs/OTC.md` for the exhaustive reference.

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

@@ -0,0 +1,108 @@
+---
+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.).
+---
+
+# 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.
+
+## 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.
+
+## 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.
+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.
+
+## 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).
+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).
+
+## 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.
+
+## .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.
+
+## 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.