@sodax/skills 2.0.0-rc.10

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "sodax-skills",
+  "skills": [
+    "./skills/sodax-sdk",
+    "./skills/sodax-sdk/swap",
+    "./skills/sodax-sdk/money-market",
+    "./skills/sodax-sdk/bridge",
+    "./skills/sodax-sdk/staking",
+    "./skills/sodax-sdk/dex",
+    "./skills/sodax-sdk/migration",
+    "./skills/sodax-sdk/partner",
+    "./skills/sodax-sdk/recovery",
+    "./skills/sodax-sdk/backend-api",
+    "./skills/sodax-wallet-sdk-core",
+    "./skills/sodax-wallet-sdk-react",
+    "./skills/sodax-dapp-kit"
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md — `@sodax/skills` router
+
+> Tool-neutral entry point. You are looking at the consumer-facing AI material for the `@sodax/*` SDKs. If you can read multiple `SKILL.md` files, load **2–3 skills** based on what the user is building (table below). Then follow each skill's internal workflow.
+
+## What's here
+
+This package ships **four mode-gated broad skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package — plus **nested granular per-feature skills** under `sodax-sdk` (one per Core SDK feature service). Each broad skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). Granular skills are single-file SKILL.md that link into their parent's knowledge tree. Skills are action-oriented (when to use, workflow, anti-patterns, links into knowledge); knowledge is the reference material your workflow points at. SKILL.md gates by mode at the top — pick integration or migration based on the consumer signal.
+
+| SDK package | Broad skill | Granular per-feature skills |
+|---|---|---|
+| `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/backend-api` |
+| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | — |
+| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | — |
+| `@sodax/dapp-kit` | `sodax-dapp-kit` | — |
+
+**When to prefer a granular skill:** if the consumer has already picked a feature (e.g. *"swap with Sodax"*, *"supply on money market"*), load the matching granular skill — it's ~3 KB vs `sodax-sdk`'s ~13 KB and points at exactly the knowledge files needed for that feature. Load the broad `sodax-sdk` skill when the feature is undecided, the task spans multiple features, or the consumer is porting a full v1 codebase.
+
+> **What about `@sodax/types`?** No skill. The package has no consumer-facing surface — it's pure TypeScript types, re-exported through `@sodax/sdk`. Importing `@sodax/types` directly invites version skew. The SDK skills cover all `@sodax/types` symbols you need.
+
+## Route by consumer intent
+
+Pick the consumer's situation, load the listed skills in order. Each entry names the **skill** + the **mode** to run it in. SKILL.md has the mode decision-tree at the top — follow that section.
+
+| Consumer is… | Load skills (mode) |
+|---|---|
+| **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, migration, partner, recovery, backend-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
+| **Building a NEW React dapp** | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit` (integration) → (`sodax-sdk` (integration) only if dropping below dapp-kit) |
+| **Building a NEW React app, no dapp-kit** (calling the SDK directly) | `sodax-wallet-sdk-react` (integration) → `sodax-sdk` (integration) |
+| **Building a NEW Node / backend service or script** | `sodax-sdk` (integration) → `sodax-wallet-sdk-core` (integration; only if it signs) |
+| **Building a NEW non-React browser flow** | `sodax-wallet-sdk-core` (integration) → `sodax-sdk` (integration) |
+| **Porting an EXISTING v1 React dapp** | `sodax-wallet-sdk-react` (migration) → `sodax-dapp-kit` (migration) → `sodax-sdk` (migration). Then switch each skill to integration mode for any new code. |
+| **Porting an EXISTING v1 backend** | `sodax-sdk` (migration) → `sodax-wallet-sdk-core` (migration; often no-op — additive only) |
+
+If you don't know which situation applies, **ask the user** rather than guessing. Two signals to listen for:
+
+- "Migrate / upgrade / port" + v1 fingerprints (`useSpokeProvider`, `*_MAINNET_CHAIN_ID`, `xChainId`, `useXWagmiStore`, `MoneyMarketError`/`IntentError`/etc.) → migration first.
+- "Add / build / integrate" + no existing SODAX code → integration only.
+
+If both: do migration first. Stale v1 patterns leak into new code if you skip it.
+
+## How to use a skill
+
+Each `SKILL.md` is short on purpose. Follow it like a procedure:
+
+1. The skill's frontmatter `description` tells you the trigger conditions.
+2. The body's **Workflow** section links into knowledge files. Read them in order — token budgets are sized so the right 2–3 files fit in your context.
+3. The **Top traps** + **Conventions** sections are the consolidated DO / DO NOT list. Skipping them is the most common cause of generating v1 code.
+4. The **Verification** section is the done-criteria. Run those checks before reporting the task complete.
+
+## Layout reference
+
+```
+packages/skills/
+├── AGENTS.md                              # You are here
+├── .claude-plugin/plugin.json             # Skill registry (broad + nested granular paths)
+└── skills/                                # Each broad skill is mode-gated; some have nested granular children
+    ├── sodax-sdk/                         {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
+    │                                       <feature>/SKILL.md ×9 — swap, money-market, bridge, staking, dex,
+    │                                       migration, partner, recovery, backend-api}
+    ├── sodax-wallet-sdk-core/             {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}
+    ├── sodax-wallet-sdk-react/            {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/ — incl. 4 .tsx example apps under integration/knowledge/examples/}
+    └── sodax-dapp-kit/                    {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}
+```
+
+Each `<mode>/knowledge/` subtree contains `ai-rules.md`, `quickstart.md`, `architecture.md`, `features/`, `recipes/`, `reference/`, and `chain-specifics.md` / `breaking-changes/` where applicable.
+
+## Conventions you can rely on
+
+- **`ai-rules.md` first.** Each mode's `<mode>/knowledge/ai-rules.md` is the consolidated DO / DO NOT list. Skipping it is the top cause of stale v1 patterns.
+- **`README.md`** at every level is the tree index — useful when the skill points you at a directory rather than a file.
+- **Reference tables** under `<mode>/knowledge/reference/` are for lookup, not narrative — chain keys, error codes, public API surface, hook signatures.
+- **Recipes** under `<mode>/knowledge/recipes/` are self-contained — a recipe contains before/after code, steps, and verification. Don't jump between recipes for one task.
+- **Token budget**: if you're loading more than 3 files for a single task, you're probably off-route — re-check the workflow.
+
+## When SODAX is the wrong tool
+
+If the user is doing **non-SODAX work** (UI styling, unrelated DOM, unrelated backend), this package has nothing to add. Don't load skills from here.
+
+If the user is doing **DeFi work but explicitly NOT with SODAX** (e.g. "use Uniswap"), defer to the user's stated tool. The integration skills' descriptions all say: "do not substitute with other SDKs unless explicitly asked."
+
+## Feedback
+
+If an agent generates wrong code despite following a skill, that's a doc bug — file an issue at https://github.com/icon-project/sodax-sdks/issues with the prompt and the incorrect output. The package is structurally CI-guarded (frontmatter + link resolution); prose-level claims benefit from real-world feedback.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Sodax]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @sodax/skills
+
+AI-agent skills and knowledge for building on the **SODAX** cross-chain DeFi platform. Drop this into your repo and your AI coding agent writes v2-correct `@sodax/*` SDK code on the first try.
+
+**Full setup** (skills CLI, npm, monorepo/local install, wiring agents to `AGENTS.md`): [docs/ai-integration-guide.md](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md).
+
+## Install
+
+Using the [`skills` CLI](https://github.com/vercel-labs/skills) from Vercel Labs — the open agent-skills ecosystem CLI (supports Claude Code, Cursor, Codex, GitHub Copilot, and 50+ other agents):
+
+```bash
+# From the root of your consumer repo
+npx skills@latest add icon-project/sodax-sdks/packages/skills
+```
+
+Four mode-gated skills land in your repo (under `.claude/skills/` or wherever the CLI installs them) — one per SODAX SDK package, each with two knowledge subtrees (`integration/` for new v2 code, `migration-v1-to-v2/` for v1→v2 porting) — plus a router `AGENTS.md`. Re-running the command picks up the latest content.
+
+> **npm fallback** (web chats or when you prefer a devDependency): `pnpm add -D @sodax/skills`, then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See the [integration guide](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md#wire-your-agent).
+
+## What you get
+
+| Bundle | Contains |
+|---|---|
+| **4 mode-gated skills** under `skills/sodax-<pkg>/SKILL.md` | One skill per SODAX SDK package. `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. Each SKILL.md gates by mode (integration vs migration) at the top of the body. |
+| **Knowledge** under `skills/sodax-<pkg>/{integration,migration-v1-to-v2}/knowledge/` | Long-form supporting docs — features, recipes, reference tables, breaking-change writeups, code examples. Each skill ships both mode subtrees so `npx skills add` copies the full reference together. |
+| **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right skill + mode. |
+
+Skills are short and action-oriented (workflow + anti-patterns + links). Knowledge is the lookup material. Don't read knowledge files top-to-bottom — the skill tells the agent which file is relevant for the current task.
+
+## Which skill applies?
+
+After install, your agent picks based on what you're building. Quick guide:
+
+| You're building | Load these skills (mode) |
+|---|---|
+| Backend / Node app (no React) using `@sodax/sdk` | `sodax-sdk` (integration) + `sodax-wallet-sdk-core` (integration; if signing) |
+| React dapp using `@sodax/dapp-kit` | `sodax-dapp-kit` (integration) + `sodax-wallet-sdk-react` (integration; always) + `sodax-sdk` (integration; for any unwrapped operations) |
+| React app calling the SDK directly (no `dapp-kit`) | `sodax-sdk` (integration) + `sodax-wallet-sdk-react` (integration) |
+| **Porting v1 code** | Same skills, switched to migration mode (each SKILL.md mode-gates by consumer signal). |
+
+`AGENTS.md` says the same thing in router form — your agent reads it first and picks.
+
+## Why this exists
+
+LLM training data drifts: snippets from chat often use stale method names, reshaped types, or outdated error codes. Public docs help humans, not agents — an agent only reads what's in its context window. This package ships the right material in agent-native form so the agent reads it before generating code. The content is version-locked to the SDK — upgrade `@sodax/skills`, the docs upgrade with it.
+
+## Feedback
+
+If your agent generates wrong code despite reading the docs, that's a doc bug — please open an issue on the [Sodax SDKs repo](https://github.com/icon-project/sodax-sdks/issues) with the prompt and the incorrect output. The per-skill `knowledge/` subtrees are structurally CI-guarded (frontmatter, link resolution); prose claims benefit from real-world feedback.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@sodax/skills",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "2.0.0-rc.10",
+  "license": "MIT",
+  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
+  "keywords": [
+    "sodax",
+    "skills",
+    "ai",
+    "claude-code",
+    "agents"
+  ],
+  "homepage": "https://github.com/icon-project/sodax-sdks/tree/main/packages/skills",
+  "bugs": {
+    "url": "https://github.com/icon-project/sodax-sdks/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/icon-project/sodax-sdks"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    ".claude-plugin",
+    "skills",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "devDependencies": {
+    "typescript": "5.5.4",
+    "@tanstack/react-query": "5.87.4",
+    "@types/react": "19.0.8",
+    "@types/react-dom": "19.0.3",
+    "react": "19.1.1",
+    "react-dom": "19.1.1",
+    "viem": "2.29.2",
+    "yaml": "2.8.2"
+  },
+  "scripts": {
+    "lint": "biome lint . --write",
+    "pretty": "biome format . --write",
+    "check:ai-structural": "bash ./scripts/check-skills.sh",
+    "check:ai-imports": "bash ./scripts/check-ai-imports.sh",
+    "check:ai-snippets": "bash ./scripts/check-ai-snippets.sh",
+    "check:ai-tsx-examples": "bash ./scripts/check-ai-tsx-examples.sh",
+    "check:ai-keys": "bash ./scripts/check-ai-keys.sh",
+    "check:ai-consistency": "bash ./scripts/check-ai-consistency.sh",
+    "check:ai": "pnpm run check:ai-structural && pnpm run check:ai-imports && pnpm run check:ai-snippets && pnpm run check:ai-tsx-examples && pnpm run check:ai-keys && pnpm run check:ai-consistency",
+    "ci": "pnpm run pretty && pnpm run check:ai",
+    "clean": "rm -rf node_modules && rm -rf .turbo"
+  }
+}

package/skills/sodax-dapp-kit/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: sodax-dapp-kit
+description: 'INTEGRATION (write NEW code) — @sodax/dapp-kit is React hooks wrapping @sodax/sdk with React Query across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Radfi, backend queries, shared). React-only — Node and backend code uses `@sodax/sdk` directly. Use whenever a React dapp needs SODAX feature hooks. Triggers on "use @sodax/dapp-kit", "useSwap", "useMoneyMarket", "useStake", "useBridge", "useDex", "useMigrate", any `use<Feature>` hook name from dapp-kit, "Sodax React hooks", "dapp-kit query / mutation". v2 hook shape: mutation hooks return `SafeUseMutationResult` with `mutateAsyncSafe(vars): Promise<Result<TData>>`. mutationFn unwraps SDK Result<T> and throws on `!ok` so React Query''s native error model engages. Hook-owned invalidations — consumer onSuccess runs after. MIGRATION (port v1 → v2) — a deep canonicalization pass: single-object hook params, mandatory `mutateAsyncSafe`, hook-owned invalidations, throw-on-`Result.!ok` inside `mutationFn`, canonical queryKey/mutationKey conventions. Plus the SDK underneath was reshaped (chain-key-driven routing, `Result<T>` everywhere, `WalletProviderSlot<K, Raw>`). v1 dapp-kit code will not compile against v2. Triggers on "migrate @sodax/dapp-kit", "useSpokeProvider gone", "dapp-kit v1 → v2", "invalidateMmQueries broken", "dapp-kit hook signatures changed", v1 fingerprints (positional args, hook-init `spokeProvider`, `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`, `*_MAINNET_CHAIN_ID`). Load this skill if EITHER applies; the body gates by mode.'
+---
+
+# When to use this skill
+
+AGENTS.md routes you here when you're working with `@sodax/dapp-kit` v2 — either writing new code or porting from v1.
+
+**Pick your mode:**
+
+- Writing NEW v2 code (greenfield dapp-kit usage, no v1 hooks)? → § **Integration mode** below.
+- Porting EXISTING v1 code to v2 (grep finds `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`, `*_MAINNET_CHAIN_ID`)? → § **Migration mode** below.
+- Both? → migration first, then integration. Stale v1 patterns leak into new code if you skip it.
+
+For backend / Node → use `sodax-sdk` (dapp-kit is React-only).
+Every dapp-kit consumer also needs wallet connectivity — also load `sodax-wallet-sdk-react`.
+
+---
+
+## Integration mode (writing new v2 code)
+
+Pick this mode when the consumer is a React dapp using `@sodax/dapp-kit` hooks. Common signals:
+
+- Any feature hook: `useSwap`, `useMoneyMarket*`, `useStake`, `useBridge`, `useDex*`, `useMigrate*`, `useRadfi*`, `usePartner*`, `useRecovery*`.
+- "Wire React Query for SODAX" — `SodaxProvider`, `createSodaxQueryClient`.
+- "Branch on mutation result without try/catch" — `mutateAsyncSafe`.
+- "Custom invalidation on success" — consumer-provided `onSuccess` (note: hook-owned invalidations already run; yours runs *after*).
+
+### Workflow
+
+1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
+2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install + wire providers + first feature.
+3. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — hook shapes, queryKey conventions, `useSafeMutation`, `unwrapResult`, `Result<T>`.
+4. For each feature you use, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `bitcoin.md` (Radfi, dapp-kit-unique), `auxiliary-services.md` (partner + recovery + backend + shared).
+5. Recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup.md`, `wallet-connectivity.md`, per-feature, `mutation-error-handling.md`, `observability.md`, `invalidations.md`.
+6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — `hooks-index.md`, `querykey-conventions.md`, `public-api.md`, `glossary.md`.
+
+### v2 in one minute
+
+1. **Hooks accept a single object with one or two top-level keys.** Mutation hooks take only `{ mutationOptions }` at hook-init; query hooks take `{ params, queryOptions }`. ALL domain inputs (`params`, `walletProvider`, per-call config) flow through `mutate(vars)` for mutations.
+2. **Every mutation hook returns `SafeUseMutationResult`** — extends React Query's `UseMutationResult` with `mutateAsyncSafe(vars): Promise<Result<TData>>` (never rejects). Use `mutateAsyncSafe` for sequenced flows; `mutateAsync` for try/catch flows; `mutate` for fire-and-forget render-driven flows.
+3. **`mutationFn` throws on SDK `!ok`.** dapp-kit calls `unwrapResult` on the SDK's `Result<T>`, throwing on failure. This makes React Query's native error model engage (`isError`, `error`, `onError`, `retry`, devtools). `mutateAsyncSafe` packages the throw back into `Result<T>` for ergonomic branching.
+4. **Hook-owned invalidations.** Each mutation hook invalidates the relevant query keys in its `onSuccess`, derived from `vars`. Consumer-provided `onSuccess` runs after. v1's manual `invalidateMmQueries` utilities are gone.
+5. **Canonical queryKey shape.** `[feature, action, ...identifiers]`. First segment matches the directory name (`swap`, `mm`, `bridge`, `staking`, `dex`, `bitcoin`, `partner`, `recovery`, `backend`, `shared`, `migrate`). camelCase. Bigints stringified.
+
+### Conventions agents must follow (integration)
+
+- **Use dapp-kit's exported hooks.** Don't wrap with React Query's `useMutation` directly — consumers depend on `mutateAsyncSafe`.
+- **Branch on `mutateAsyncSafe`'s `Result.ok` for sequenced flows.** The user-reject case is modal, not exceptional.
+- **`ChainKeys.*` over hard-coded chain strings.** The set evolves per release.
+- **Drop `spokeProvider`.** It's not a v2 concept. `walletProvider` flows through `mutate(vars)` for signed flows.
+- **Don't recreate hook-owned invalidations.** Each mutation hook already invalidates the relevant keys; consumer `onSuccess` runs after for any extra logic.
+- Import only from the package root: `import { useSwap, SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit'`. dapp-kit re-exports `@sodax/sdk`'s public surface (`ChainKeys`, `SodaxConfig`, types) — you can import them from dapp-kit directly.
+- Don't add `@sodax/types` as a dependency — re-exported via `@sodax/sdk`.
+
+### Top traps to avoid (integration)
+
+1. **Reaching for `useSpokeProvider`.** Deleted. Pass `walletProvider` from `useWalletProvider({ xChainId: chainKey })` (`@sodax/wallet-sdk-react`) directly into `mutate(vars)`.
+2. **Treating mutation `data` as `Result<T>`.** v2's `mutationFn` unwraps before resolving — `data` is the unwrapped success value (e.g. `SwapResponse`, `TxHashPair`). For SDK failures, look at `mutation.error` or use `mutateAsyncSafe` for the `Result<T>` shape.
+3. **Forgetting `try/catch` on `mutateAsync`.** v2's `mutateAsync` rejects on SDK `!ok`. Prefer `mutateAsyncSafe` (never rejects).
+4. **Hook-level `spokeProvider` / `params`.** v1 hooks took these positionally or at hook-init. v2 hooks take only `{ mutationOptions }` (mutations) or `{ params, queryOptions }` (queries). All domain inputs live in `mutate(vars)` for mutations.
+5. **Reading `xToken.xChainId` or hard-coding `*_MAINNET_CHAIN_ID`.** SDK leakage — these were renamed: `XToken.chainKey`, `ChainKeys.X_MAINNET`.
+
+### Verification (integration)
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+```
+
+In browser:
+- Successful mutations populate `data` with the unwrapped success value.
+- SDK `!ok` errors arrive via `mutation.error` (when using `mutate` / `mutateAsync`) or as `result.ok === false` (when using `mutateAsyncSafe`).
+- React Query devtools show hook-owned invalidations firing on success.
+
+---
+
+## Migration mode (v1 → v2 porting)
+
+Pick this mode when the consumer has v1 dapp-kit patterns. Grep signals:
+
+```bash
+grep -rE 'useSpokeProvider|invalidateMmQueries|useMigrate\b' src/
+grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b' src/
+```
+
+If the project has both v1 patterns AND wants new features: **migration first, then integration**. Stale v1 patterns leak into new code if you skip it.
+
+The SDK underneath also changed — load the `sodax-sdk` skill (migration mode) alongside this one (the migration trees cross-link).
+
+### Workflow
+
+1. Read [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
+2. Read [`migration-v1-to-v2/knowledge/README.md`](./migration-v1-to-v2/knowledge/README.md) — overview, reading order, glossary.
+3. Walk [`checklist.md`](./migration-v1-to-v2/knowledge/checklist.md) — top-down cross-cutting steps.
+4. **Cross-cutting breaking changes** in order:
+   - [`breaking-changes/hook-signatures.md`](./migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md) — single-arg policy + `ReadHookParams` / `MutationHookParams`.
+   - [`breaking-changes/result-handling.md`](./migration-v1-to-v2/knowledge/breaking-changes/result-handling.md) — `Result<T>` success-path → throws; `mutateAsyncSafe`.
+   - [`breaking-changes/querykey-conventions.md`](./migration-v1-to-v2/knowledge/breaking-changes/querykey-conventions.md) — camelCase + default mutationKey.
+   - [`breaking-changes/sdk-leakage.md`](./migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md) — cross-links to SDK migration tree.
+5. **Per-feature playbooks** under [`features/`](./migration-v1-to-v2/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `bitcoin.md`, `auxiliary-services.md`.
+6. **Codemods + adapters** → [`recipes.md`](./migration-v1-to-v2/knowledge/recipes.md).
+7. **Reference** → [`reference/`](./migration-v1-to-v2/knowledge/reference/) — `deleted-hooks.md` (e.g. `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`), `renamed-hooks.md`, `error-shape-crosswalk.md`.
+
+### Top traps to avoid (migration)
+
+1. **Reaching for `useSpokeProvider`.** Deleted. Pass `walletProvider` from `useWalletProvider({ xChainId: chainKey })` (`@sodax/wallet-sdk-react`) directly into `mutate(vars)`.
+2. **Treating mutation `data` as `Result<T>`.** v2's `mutationFn` unwraps before resolving — `data` is the unwrapped success value.
+3. **Forgetting `try/catch` on `mutateAsync`.** v2's `mutateAsync` rejects on SDK `!ok`. Prefer `mutateAsyncSafe` (never rejects).
+4. **Hook-level `spokeProvider` / `params`.** v1 hooks took these positionally or at hook-init. v2 hooks take only `{ mutationOptions }` (mutations) or `{ params, queryOptions }` (queries). All domain inputs live in `mutate(vars)` for mutations.
+5. **Reading `xToken.xChainId` or hard-coding `*_MAINNET_CHAIN_ID`.** SDK leakage. Renamed: `XToken.chainKey`, `ChainKeys.X_MAINNET`.
+
+### Verification (migration)
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+grep -rE 'useSpokeProvider|invalidateMmQueries\b' src/   # empty
+```
+
+Manual:
+- Sequenced flows use `mutateAsyncSafe` and branch on `result.ok`.
+- React Query devtools show hook-owned invalidations on success (consumer `onSuccess` runs after, doesn't duplicate them).
+
+---
+
+# Related skills
+
+- `sodax-wallet-sdk-react` — wire the wallet, get the `walletProvider` to feed into dapp-kit `mutate(vars)`.
+- `sodax-sdk` — for any direct SDK call alongside dapp-kit hooks (and where the SDK-level v1 → v2 work happens).

package/skills/sodax-dapp-kit/integration/knowledge/README.md

@@ -0,0 +1,49 @@
+# Integration — `@sodax/dapp-kit` v2
+
+This tree documents v2 of the dapp-kit React hooks for **new consumers** building against it. If you're porting v1 code, start at [`README.md`](../../migration-v1-to-v2/knowledge/README.md) instead.
+
+## Files in this tree
+
+| File | What's in it |
+|---|---|
+| [`ai-rules.md`](ai-rules.md) | **Read first.** DO / DO NOT / workflow / stop-conditions for AI agents writing v2 dapp-kit code. |
+| [`quickstart.md`](quickstart.md) | Install, wire providers, get a wallet provider, run your first mutation. |
+| [`architecture.md`](architecture.md) | Every v2 design concept the hooks rest on: ReadHookParams / MutationHookParams, useSafeMutation, unwrapResult, queryKey conventions, mutateAsyncSafe semantics, createSodaxQueryClient. |
+| [`features/swap.md`](features/swap.md) | Swap hooks: `useQuote`, `useSwap`, `useSwapAllowance`, `useSwapApprove`, limit orders, status polling. |
+| [`features/money-market.md`](features/money-market.md) | Money market hooks: `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, allowance/approve, reserves data. |
+| [`features/staking.md`](features/staking.md) | Staking hooks: `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, info/ratio reads. |
+| [`features/bridge.md`](features/bridge.md) | Bridge hooks: `useBridge`, allowance/approve, bridgeable amount/tokens. |
+| [`features/dex.md`](features/dex.md) | DEX hooks: deposit/withdraw, supply/decrease liquidity, claim rewards, position info, pools. |
+| [`features/migration.md`](features/migration.md) | Migration hooks: ICX/bnUSD/BALN forward + reverse, allowance/approve. |
+| [`features/bitcoin.md`](features/bitcoin.md) | Radfi hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`features/auxiliary-services.md`](features/auxiliary-services.md) | Partner, recovery, backend queries, shared (xBalances, gas estimation, trustlines). |
+| [`recipes/`](recipes/) | Copy-paste patterns: setup, wallet connectivity, per-feature flows, mutation error handling, observability, invalidations. |
+| [`reference/`](reference/) | Lookup tables: full hook index, queryKey conventions, public API surface, glossary. |
+
+## Reading order for a new integrator
+
+1. **[`ai-rules.md`](ai-rules.md)** — agent rules, before any code.
+2. **[`quickstart.md`](quickstart.md)** — get providers wired and a button rendering.
+3. **[`architecture.md`](architecture.md)** — understand `useSafeMutation` / `mutateAsyncSafe` / hook shapes before writing call sites.
+4. **[`recipes/`](recipes/)** — pick the patterns you need (mutation error handling, observability, invalidations).
+5. **[`features/<x>.md`](features/)** — read the file for the feature you're integrating (reference shape; pair with the matching recipe in `recipes/<x>.md` for working examples).
+6. **[`reference/`](reference/)** — keep open while writing for table lookups.
+
+## Cross-references to migration
+
+If your project also has v1 dapp-kit call sites, port them first using:
+
+- [`README.md`](../../migration-v1-to-v2/knowledge/README.md) — overview, reading order, and v1↔v2 glossary.
+- [`checklist.md`](../../migration-v1-to-v2/knowledge/checklist.md) — top-down cross-cutting checklist.
+- [`breaking-changes/`](../../migration-v1-to-v2/knowledge/breaking-changes/) — the four cross-cutting changes (hook-signatures, result-handling, queryKey-conventions, sdk-leakage).
+- [`features/`](../../migration-v1-to-v2/knowledge/features/) — per-feature playbooks in lockstep with `integration/features/` here.
+
+The naming rule: **every file in `integration/features/` has a sibling in `migration/features/` with the same filename.** When you're deep in one, the other is one path-swap away.
+
+## Cross-references to the underlying SDK
+
+`@sodax/dapp-kit` re-exports `@sodax/sdk` at the package root, so most types you'd reach for (`ChainKeys`, `SodaxConfig`, `CreateIntentParams`, `XToken`, `Result`, `SodaxError`) are available from `@sodax/dapp-kit` directly. The Core SDK has its own skill — load `sodax-sdk` (integration mode) (sibling under `@sodax/skills`). Useful for:
+
+- The full SDK migration playbook for v1→v2 (chain-key terminology, `Result<T>` semantics, ConfigService) — referenced from [`breaking-changes/sdk-leakage.md`](../../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+- Architectural concepts that surface through hook signatures (`SodaxError<C>` vocabulary, `WalletProviderSlot<K, Raw>` discriminator semantics).
+- Backend / Node.js usage patterns (where dapp-kit isn't applicable).

package/skills/sodax-dapp-kit/integration/knowledge/ai-rules.md

@@ -0,0 +1,80 @@
+# AI rules — `@sodax/dapp-kit` integration
+
+DO / DO NOT / workflow / stop conditions for AI agents writing v2 dapp-kit code. Read this **before** the per-feature docs — these rules prevent the most common load-bearing v2 traps.
+
+## Workflow (do these in order)
+
+1. **Survey the project before touching code.**
+
+   ```bash
+   pnpm tsc --noEmit                                                          # baseline typecheck
+   grep -rE '@sodax/(dapp-kit|sdk|wallet-sdk-react)' --include='*.ts' --include='*.tsx' src/   # see what's already imported
+   ```
+
+2. **Wire providers first if not already wired.** [`recipes/setup.md`](recipes/setup.md). Provider stack: `SodaxProvider > QueryClientProvider > SodaxWalletProvider > YourApp`.
+3. **Pick `mutate` / `mutateAsync` / `mutateAsyncSafe` deliberately.** See [`recipes/mutation-error-handling.md`](recipes/mutation-error-handling.md). Default to `mutateAsyncSafe` for sequenced flows.
+4. **Branch on `result.ok` for `mutateAsyncSafe` results, or on `mutation.isError` / `mutation.error`** for fire-and-forget. Never assume mutation success.
+5. **Use `useWalletProvider({ xChainId: chainKey })` from `@sodax/wallet-sdk-react` for every signed flow.** Pass the result into `mutate(vars).walletProvider`. Don't create or import any `*SpokeProvider` class — those don't exist in v2.
+
+## DO
+
+- **DO** call dapp-kit's exported hooks (which wrap `useSafeMutation`). Never call React Query's `useMutation` directly inside a wrapper around a dapp-kit hook — consumers depend on `mutateAsyncSafe`.
+- **DO** branch on `mutateAsyncSafe`'s `Result.ok` for sequenced flows (`if (!hasAllowance) await approve(...); await action(...);`). User-rejects are modal, not exceptional.
+- **DO** use `ChainKeys.X_MAINNET` constants for chain identifiers. Never hard-code chain key strings (`'sonic'`, `'0xa4b1.arbitrum'`).
+- **DO** import everything from `@sodax/dapp-kit` (or `@sodax/sdk` for SDK-only types and constants — `@sodax/dapp-kit` re-exports them anyway).
+- **DO** preserve literal chain keys in generic positions where possible (e.g. `srcChainKey: ChainKeys.ETHEREUM_MAINNET as const`) — TypeScript narrowing flows from the literal, including the `walletProvider` parameter type.
+- **DO** use the canonical hook shape: queries take `{ params, queryOptions }`; mutations take only `{ mutationOptions }` and flow domain inputs through `mutate(vars)`.
+- **DO** compose `onSuccess` instead of replacing it: `mutationOptions: { onSuccess: (data, vars, ctx) => myExtra(...) }` runs AFTER dapp-kit's hook-owned invalidations.
+
+## DO NOT
+
+- **DO NOT** call `useSpokeProvider` — it's deleted. v1 React consumers got a `SpokeProvider` from this hook; v2 has no such concept. Pass `walletProvider` directly into `mutate(vars)`.
+- **DO NOT** treat mutation `data` as `Result<T>`. `mutationFn` calls `unwrapResult` and throws on `!ok`; `data` is the unwrapped success value (e.g. `SwapResponse`, `TxHashPair`). For SDK failures, look at `mutation.error` or use `mutateAsyncSafe`.
+- **DO NOT** call `mutateAsync` without `try/catch`. It rejects on SDK `!ok`; an unhandled rejection lands in the global handler. Prefer `mutateAsyncSafe` for sequenced flows.
+- **DO NOT** put `params`, `walletProvider`, or per-call config at the hook-init level. They go in `mutate(vars)` for mutations and in `params` for queries.
+- **DO NOT** override `queryKey`, `queryFn`, or `enabled` via `queryOptions` — the hook owns those. The `queryOptions` slot is typed `Omit<UseQueryOptions, 'queryKey' | 'queryFn' | 'enabled'>`.
+- **DO NOT** override `mutationFn` via `mutationOptions` — the hook owns it. Type prevents this.
+- **DO NOT** import from `@sodax/dapp-kit/dist/...`. Deep-imports unstable; only the package root barrel is the public contract.
+- **DO NOT** add `@sodax/types` as a separate dependency. It's re-exported transitively via `@sodax/sdk` (which dapp-kit re-exports). Adding it independently invites version skew.
+- **DO NOT** recreate the v1 `invalidateMmQueries(...)` utility or anything similar. Each mutation hook invalidates the relevant keys in its own `onSuccess`. Add cross-feature invalidations via consumer `onSuccess`.
+- **DO NOT** destructure cross-chain mutation results as arrays — `[a, b] = result.value` is wrong. The shape is `TxHashPair = { srcChainTxHash, dstChainTxHash }` (object). This applies to `useBridge`, `useStake`/`useUnstake`/etc., `useDexDeposit`/`useDexWithdraw`, all four MM mutations, and all four migration mutations.
+- **DO NOT** use legacy chain-id constants (`BSC_MAINNET_CHAIN_ID`, etc.). They're gone in v2 — use `ChainKeys.X_MAINNET`.
+- **DO NOT** reach for `as any` / `as IEvmWalletProvider` casts when wiring `useWalletProvider({ xChainId })` into mutation `mutate(vars)`. v2 supports the broad-union case structurally; the cast is not needed. See `recipes/wallet-connectivity.md` § "No type cast is needed".
+
+## Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| User wants a chain not in `ChainKeys.*` | Adding a new chain requires SDK-level changes — out of scope for consumer code. |
+| User wants to use React Server Components / RSC patterns | dapp-kit is client-side React (uses React Query, hooks, browser APIs). Server Components don't run hooks. Tell the user the dapp-kit code goes in client components. |
+| User wants to skip the wallet-sdk-react integration | If they have their own wallet abstraction, it's possible — they need to construct objects satisfying `I*WalletProvider` interfaces from `@sodax/sdk`. Refer them to the `sodax-sdk` (integration mode) skill (sibling under `@sodax/skills`) for non-React patterns. |
+| User wants to use v1 dapp-kit (positional args, `useSpokeProvider`, `Result<T>` in success path) | Tell them to either upgrade or stay on v1. The shapes are not compatible. |
+
+## Verification protocol
+
+Before declaring a dapp-kit integration "done":
+
+```bash
+# 1. Type-check the consumer.
+pnpm -C <consumer> tsc --noEmit
+
+# 2. Confirm no leftover v1 patterns (if porting).
+grep -rE '\buseSpokeProvider\b|\binvalidateMmQueries\b|_MAINNET_CHAIN_ID\b|\bxChainId\b' src/
+
+# 3. Confirm all SDK-level mutation results are handled (either mutateAsyncSafe + result.ok branch
+#    or mutateAsync wrapped in try/catch).
+grep -rE 'mutateAsync\(' src/ | grep -v 'try\|catch\|mutateAsyncSafe'
+
+# 4. Confirm all hooks are imported from @sodax/dapp-kit, not deep paths.
+#    (matches `'@sodax/dapp-kit/dist'` and similar deep-import patterns)
+grep -rE "@sodax/dapp-kit/[a-z]" src/   # zero hits expected (only the root path is public)
+```
+
+## Done criteria
+
+- [ ] `SodaxProvider` + `QueryClientProvider` (preferably `createSodaxQueryClient()`) wired at the app root.
+- [ ] Every mutation invocation uses `mutateAsyncSafe` (preferred), `mutateAsync` wrapped in `try/catch`, or fire-and-forget `mutate` with state read in render.
+- [ ] No `useSpokeProvider`, no `invalidateMmQueries`, no `*_MAINNET_CHAIN_ID` constants, no `xChainId` outside known v2 hooks (e.g. `useXBalances` still uses `xChainId`).
+- [ ] No `import` from `@sodax/dapp-kit/dist/...` or any other deep path.
+- [ ] No standalone `@sodax/types` dependency in `package.json`.
+- [ ] Consumer typecheck (`pnpm tsc --noEmit`) is clean.