@sodax/skills 2.0.0-rc.10 → 2.0.0-rc.11

package/.claude-plugin/plugin.json

@@ -12,7 +12,30 @@
     "./skills/sodax-sdk/recovery",
     "./skills/sodax-sdk/backend-api",
     "./skills/sodax-wallet-sdk-core",
+    "./skills/sodax-wallet-sdk-core/evm",
+    "./skills/sodax-wallet-sdk-core/solana",
+    "./skills/sodax-wallet-sdk-core/sui",
+    "./skills/sodax-wallet-sdk-core/bitcoin",
+    "./skills/sodax-wallet-sdk-core/stellar",
+    "./skills/sodax-wallet-sdk-core/icon",
+    "./skills/sodax-wallet-sdk-core/injective",
+    "./skills/sodax-wallet-sdk-core/near",
+    "./skills/sodax-wallet-sdk-core/stacks",
     "./skills/sodax-wallet-sdk-react",
-    "./skills/sodax-dapp-kit"
+    "./skills/sodax-wallet-sdk-react/connect",
+    "./skills/sodax-wallet-sdk-react/wallet-modal",
+    "./skills/sodax-wallet-sdk-react/bridge-to-sdk",
+    "./skills/sodax-wallet-sdk-react/switch-chain",
+    "./skills/sodax-wallet-sdk-react/sign-message",
+    "./skills/sodax-wallet-sdk-react/walletconnect",
+    "./skills/sodax-dapp-kit",
+    "./skills/sodax-dapp-kit/swap",
+    "./skills/sodax-dapp-kit/money-market",
+    "./skills/sodax-dapp-kit/staking",
+    "./skills/sodax-dapp-kit/bridge",
+    "./skills/sodax-dapp-kit/dex",
+    "./skills/sodax-dapp-kit/migration",
+    "./skills/sodax-dapp-kit/bitcoin",
+    "./skills/sodax-dapp-kit/auxiliary-services"
   ]
 }

package/AGENTS.md

@@ -4,16 +4,16 @@
 
 ## 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.
+This package ships **four mode-gated broad skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package — plus **nested granular skills** under every broad skill: `sodax-sdk` (one per Core SDK feature service), `sodax-dapp-kit` (one per dapp-kit feature domain), `sodax-wallet-sdk-core` (one per chain family), and `sodax-wallet-sdk-react` (one per connectivity concern). 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` | — |
+| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | `sodax-wallet-sdk-core/evm`, `sodax-wallet-sdk-core/solana`, `sodax-wallet-sdk-core/sui`, `sodax-wallet-sdk-core/bitcoin`, `sodax-wallet-sdk-core/stellar`, `sodax-wallet-sdk-core/icon`, `sodax-wallet-sdk-core/injective`, `sodax-wallet-sdk-core/near`, `sodax-wallet-sdk-core/stacks` |
+| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | `sodax-wallet-sdk-react/connect`, `sodax-wallet-sdk-react/wallet-modal`, `sodax-wallet-sdk-react/bridge-to-sdk`, `sodax-wallet-sdk-react/switch-chain`, `sodax-wallet-sdk-react/sign-message`, `sodax-wallet-sdk-react/walletconnect` |
+| `@sodax/dapp-kit` | `sodax-dapp-kit` | `sodax-dapp-kit/swap`, `sodax-dapp-kit/money-market`, `sodax-dapp-kit/staking`, `sodax-dapp-kit/bridge`, `sodax-dapp-kit/dex`, `sodax-dapp-kit/migration`, `sodax-dapp-kit/bitcoin`, `sodax-dapp-kit/auxiliary-services` |
 
-**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.
+**When to prefer a granular skill:** if the consumer has already picked a sub-domain (e.g. *"swap with Sodax"*, *"supply on money market"*, *"useSwap hook"*, *"instantiate EvmWalletProvider"*, *"add a connect button"*), load the matching granular skill — it's ~3 KB vs the broad skill's ~13 KB and points at exactly the knowledge files needed. For a React dapp that has settled on one feature, load `sodax-dapp-kit/<feature>`; for raw SDK / backend work, load `sodax-sdk/<feature>`; for a known chain in a backend/Node wallet flow, load `sodax-wallet-sdk-core/<chain>`; for a known React wallet concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect), load `sodax-wallet-sdk-react/<concern>`. Load the broad skill when the sub-domain is undecided, the task spans several, 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.
 
@@ -24,6 +24,9 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
 | 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 |
+| **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, migration, bitcoin, auxiliary-services) | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit/<feature>` (granular, covers both modes via internal links). Skip the broad `sodax-dapp-kit` skill. If the wallet concern is also settled (just a connect button, modal, bridge, etc.), narrow to `sodax-wallet-sdk-react/<concern>` too |
+| **Scaffolding ONE chain's wallet provider** (backend/Node/non-React: evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks) | `sodax-wallet-sdk-core/<chain>` (granular, covers both modes) → `sodax-sdk/<feature>` for the operation it signs. Skip the broad `sodax-wallet-sdk-core` skill |
+| **Scaffolding ONE React wallet concern** (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect) | `sodax-wallet-sdk-react/<concern>` (granular, covers both modes). Skip the broad `sodax-wallet-sdk-react` 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) |
@@ -57,9 +60,16 @@ packages/skills/
     ├── 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/}
+    ├── sodax-wallet-sdk-core/             {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
+    │                                       <chain>/SKILL.md ×9 — evm, solana, sui, bitcoin, stellar, icon,
+    │                                       injective, near, stacks}
+    ├── sodax-wallet-sdk-react/            {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/
+    │                                       (incl. 4 .tsx example apps under integration/knowledge/examples/),
+    │                                       <concern>/SKILL.md ×6 — connect, wallet-modal, bridge-to-sdk,
+    │                                       switch-chain, sign-message, walletconnect}
+    └── sodax-dapp-kit/                    {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
+                                            <feature>/SKILL.md ×8 — swap, money-market, staking, bridge, dex,
+                                            migration, bitcoin, auxiliary-services}
 ```
 
 Each `<mode>/knowledge/` subtree contains `ai-rules.md`, `quickstart.md`, `architecture.md`, `features/`, `recipes/`, `reference/`, and `chain-specifics.md` / `breaking-changes/` where applicable.

package/README.md

@@ -22,6 +22,7 @@ Four mode-gated skills land in your repo (under `.claude/skills/` or wherever th
 | 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. |
+| **Granular skills** under `skills/sodax-<pkg>/<sub-domain>/SKILL.md` | Every broad skill ships focused single-domain children: `sodax-sdk` / `sodax-dapp-kit` per feature (swap, money-market, bridge, staking, dex, …); `sodax-wallet-sdk-core` per chain (evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks); `sodax-wallet-sdk-react` per connectivity concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect). Load one when the task is already scoped to a single sub-domain — it points at exactly the knowledge files for it instead of the whole broad skill. |
 | **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. |
 

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.0.0-rc.10",
+  "version": "2.0.0-rc.11",
   "license": "MIT",
   "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
   "keywords": [

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

@@ -0,0 +1,61 @@
+---
+name: sodax-dapp-kit-auxiliary-services
+description: 'Granular skill for the @sodax/dapp-kit v2 auxiliary surfaces — partner fee claiming (useFeeClaimSwap, useApproveToken, useSetSwapPreference, useGetAutoSwapPreferences, useIsTokenApproved), recovery (useHubAssetBalances, useWithdrawHubAsset), read-only backend queries (useBackendIntentByTxHash, useBackendUserIntents, useBackendOrderbook, useBackendMoneyMarketPosition, useBackendSubmitSwapTx), and shared utilities (useSodaxContext, useHubProvider, useXBalances, useDeriveUserWalletAddress, useEstimateGas, useStellarTrustlineCheck, useRequestTrustline). Use when a React dapp task is partner fees, recovering stuck hub assets, backend data reads (intent tracking / orderbook / MM data, no wallet), or cross-cutting utilities (token balances, gas estimation, Stellar trustlines). Covers BOTH integration and migration. Links into the parent sodax-dapp-kit knowledge tree.'
+---
+
+# Auxiliary services (dapp-kit granular skill)
+
+Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: **partner** (queryKey `partner`), **recovery** (`recovery`), **backend queries** (`backend`, read-only — no wallet), and **shared utilities** (`shared`). React-only — backend/Node uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which surface?**
+   - **Partner fees:** `useIsTokenApproved` → `useApproveToken` → `useSetSwapPreference` → `useFeeClaimSwap` (returns `IntentAutoSwapResult`, NOT `SwapResponse`); `useGetAutoSwapPreferences`, `useFetchAssetsBalances` for reads.
+   - **Recovery:** `useHubAssetBalances` (list stuck hub assets) → `useWithdrawHubAsset` (withdraw one back to a spoke). Follows a *known* failed cross-chain op — investigate the failure first.
+   - **Backend reads (no wallet):** intent tracking (`useBackendIntentByTxHash` polls 1s, `useBackendIntentByHash`, `useBackendUserIntents`), orderbook (`useBackendOrderbook` — `pagination` nests under `params`), MM data (`useBackendMoneyMarketPosition` etc.), swap submission (`useBackendSubmitSwapTx` mutation + `useBackendSubmitSwapTxStatus`).
+   - **Shared utilities:** `useSodaxContext`, `useHubProvider`, `useXBalances` (needs `xService` from wallet-sdk-react), `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`, `useEstimateGas`, `useStellarTrustlineCheck` / `useRequestTrustline`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/auxiliary-services.md`](../integration/knowledge/features/auxiliary-services.md) — full hook surface for all four surfaces, `useXBalances` shape, trustline pattern, default polling intervals.
+4. Worked examples:
+   - Backend reads → [`../integration/knowledge/recipes/backend-queries.md`](../integration/knowledge/recipes/backend-queries.md).
+   - `useXBalances` → [`../integration/knowledge/recipes/wallet-connectivity.md`](../integration/knowledge/recipes/wallet-connectivity.md).
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Auxiliary-specific anti-patterns (dapp-kit)
+
+- **Treating `useFeeClaimSwap` `data` as a `SwapResponse`.** It's `IntentAutoSwapResult`.
+- **Passing top-level `pagination` to `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers`.** It nests under `params`; without it those queries are disabled.
+- **Calling `useXBalances` without `xService`.** Supply `xService` from `@sodax/wallet-sdk-react`'s `useXService`; the request-side key is `xChainId` (the cross-chain abstraction), distinct from the token-side `chainKey`.
+- **Treating `useRequestTrustline` as a canonical mutation hook.** It takes a single positional `token` arg and returns `{ requestTrustline, isLoading, ... }`; the callback takes `{ token, amount, srcChainKey, walletProvider }` (NOT `account`/`asset`).
+- **Running recovery on successful flows.** Recovery is a workaround for *failed* ops — `useHubAssetBalances` first, then withdraw the specific entry; investigate the original failure.
+- **Leaving `useBackendIntentByTxHash` polling (1s) running after the intent resolves.**
+
+## Migration workflow (port v1 auxiliary hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/auxiliary-services.md`](../migration-v1-to-v2/knowledge/features/auxiliary-services.md) — small per-hook changes across partner / recovery / backend / shared.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. `useBackendOrderbook` / paginated MM reads nest `pagination` under `params`.
+3. `useXBalances` is supplied an `xService`.
+4. Mutation flows (partner / recovery / submit) use `mutateAsyncSafe` and branch on `result.ok`.
+5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — `useBackendSubmitSwapTx` + intent tracking are the backend half of the step-by-step swap flow; partner fee-claim reuses the swap intent layer.
+- [`../money-market/SKILL.md`](../money-market/SKILL.md) — backend MM reads complement the on-chain MM action hooks.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+Partner/recovery mutations take a `walletProvider`; `useXBalances` needs an `xService`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** for `useWalletProvider` and `useXService`. (Backend read hooks need no wallet.)

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

@@ -0,0 +1,53 @@
+---
+name: sodax-dapp-kit-bitcoin
+description: 'Granular skill for the @sodax/dapp-kit v2 Bitcoin/Radfi feature only — React Query hooks for Bitcoin trading via the Radfi protocol: useRadfiAuth, useRadfiSession, useTradingWallet, useFundTradingWallet, useRadfiWithdraw, useExpiredUtxos, useRenewUtxos, useBitcoinBalance, useTradingWalletBalance. This is a dapp-kit-UNIQUE surface (no @sodax/sdk equivalent — the flows are React-shaped). Use when a React dapp task is Bitcoin/Radfi (e.g. "Radfi session hook", "fund trading wallet hook", "Radfi withdraw in React", "manage Bitcoin UTXOs hook", "BIP322 auth with dapp-kit"). Covers BOTH integration (new v2 hooks) and migration (port v1 Radfi hooks — mostly signature tightening, flow unchanged). Links into the parent sodax-dapp-kit knowledge tree.'
+---
+
+# Bitcoin / Radfi (dapp-kit granular skill)
+
+Granular skill for the Bitcoin trading hooks of `@sodax/dapp-kit` v2 — authenticate (BIP322), fund a trading wallet, withdraw, manage UTXOs via the Radfi protocol. queryKey/mutationKey first segment: `bitcoin`. **Dapp-kit-unique** — no `@sodax/sdk` equivalent.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which stage?** Session/auth (`useRadfiAuth`, `useRadfiSession`, `useTradingWallet`), balances (`useBitcoinBalance`, `useTradingWalletBalance`), operations (`useFundTradingWallet`, `useRadfiWithdraw`), UTXO maintenance (`useExpiredUtxos`, `useRenewUtxos`).
+3. **Session lifecycle handled?** `useRadfiSession(walletProvider)` manages login/refresh/auto-refresh + localStorage persistence; gate trading buttons on `isAuthed`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/bitcoin.md`](../integration/knowledge/features/bitcoin.md) — full hook surface, session flow, mutation TVars, return shapes, polling notes.
+4. [`../integration/knowledge/recipes/bitcoin.md`](../integration/knowledge/recipes/bitcoin.md) — full worked examples (session, fund, withdraw, UTXO management).
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Bitcoin/Radfi-specific anti-patterns (dapp-kit)
+
+- **Calling trading operations before auth.** Gate on `useRadfiSession(...).isAuthed`; the trading wallet is created during first authentication, not as a separate step.
+- **Expecting `useTradingWallet` to fetch.** It's synchronous — reads the persisted session from localStorage (keyed by wallet address). Use it when you don't yet have a `walletProvider`.
+- **Hand-rolling PSBT signing for withdrawals.** `useRadfiWithdraw` orchestrates the unsigned-PSBT → local-sign → co-sign → broadcast flow; consumers don't touch PSBTs directly.
+- **Treating `useRadfiAuth` `data` as a full `RadfiSession`.** It's `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (no `publicKey` in the return; it's persisted internally).
+- **Leaving `useExpiredUtxos` polling (60s) on hidden UI.** Set `queryOptions.refetchInterval: false` when not visible.
+
+## Migration workflow (port v1 Radfi hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md).
+3. [`../migration-v1-to-v2/knowledge/features/bitcoin.md`](../migration-v1-to-v2/knowledge/features/bitcoin.md) — Radfi flow is mostly unchanged; provider/session lifecycle hook signatures tightened.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Trading buttons gate on `isAuthed`.
+3. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
+4. No hand-rolled PSBT signing; `useRadfiWithdraw` owns the flow.
+
+## Related granular skills (same family)
+
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useXBalances` and other shared utilities used alongside Bitcoin UI.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+These hooks take an `IBitcoinWalletProvider`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire a Bitcoin wallet and obtain the provider via `useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET })`.

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

@@ -0,0 +1,55 @@
+---
+name: sodax-dapp-kit-bridge
+description: 'Granular skill for the @sodax/dapp-kit v2 bridge feature only — React Query hooks for cross-chain token transfer via the hub-and-spoke vault: useBridge, useBridgeApprove, useBridgeAllowance, useGetBridgeableAmount, useGetBridgeableTokens. Use when a React dapp task is specifically bridging (e.g. "useBridge with dapp-kit", "bridge tokens cross-chain in React", "check bridgeable amount hook", "list bridgeable destinations"). useBridge resolves to TxHashPair = { srcChainTxHash, dstChainTxHash }. Covers BOTH integration (new v2 hooks) and migration (port v1 bridge hooks — field renames srcChainId→srcChainKey, recipient→dstAddress, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
+---
+
+# Bridge (dapp-kit granular skill)
+
+Granular skill for the bridge hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `bridge`. React-only — backend uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Need a bridgeable precheck?** `useGetBridgeableAmount` (vault deposit/withdrawal cap, returns a `BridgeLimit`) and `useGetBridgeableTokens` (enumerate compatible destinations).
+3. **Allowance gating?** `useBridgeAllowance` + `useBridgeApprove` before `useBridge`.
+4. **Source/destination chains + recipient format** — confirm both are supported spokes and the `recipient` matches the destination chain encoding.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — full hook surface, `CreateBridgeIntentParams` shape, `useBridgeAllowance` nesting, `BridgeLimit` return.
+4. [`../integration/knowledge/recipes/bridge.md`](../integration/knowledge/recipes/bridge.md) — full worked example.
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Bridge-specific anti-patterns (dapp-kit)
+
+- **Destructuring `useBridge` `data` as an array or single hash.** It resolves to `TxHashPair = { srcChainTxHash, dstChainTxHash }` — destructure by name.
+- **Treating `useGetBridgeableAmount` `data` as a bare bigint.** It's a `BridgeLimit = { amount, decimals, type }` — read `data.amount` / `data.decimals`.
+- **Passing addresses + chain ids to `useGetBridgeableAmount`.** It takes two `XToken` objects (each carries its own `chainKey`); v1's 4-arg shape is gone.
+- **Passing the bridge params directly under `params` on `useBridgeAllowance`.** They nest under `params.payload` alongside `walletProvider`.
+- **Submitting an incompatible token pair.** Tokens bridge only if they share the same hub vault — gate with `useGetBridgeableTokens` (incompatible pairs reject with `VALIDATION_FAILED`).
+
+## Migration workflow (port v1 bridge hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — `useBridge` param renames (`srcChainId` → `srcChainKey`, `recipient` → `dstAddress`); `useGetBridgeableAmount` shape change (bigint → `BridgeLimit`).
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. `useBridge` consumers destructure `{ srcChainTxHash, dstChainTxHash }` (no array/string).
+3. `useGetBridgeableAmount` consumers read `data.amount` (not a scalar).
+4. No `useSpokeProvider`, no `srcChainId`/`recipient` v1 field names (migration only).
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — intent-based cross-chain swaps (solver-routed; different from a direct vault bridge).
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — recovery (`useWithdrawHubAsset`) for assets stranded on the hub after a failed bridge.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.

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

@@ -0,0 +1,56 @@
+---
+name: sodax-dapp-kit-dex
+description: 'Granular skill for the @sodax/dapp-kit v2 DEX feature only — React Query hooks for concentrated-liquidity LP plus asset deposit/withdraw: useDexDeposit, useDexWithdraw, useSupplyLiquidity, useDecreaseLiquidity, useClaimRewards, useDexApprove/useDexAllowance, the useCreate*Params builders, and reads (usePools, usePoolData, usePositionInfo, useLiquidityAmounts). Use when a React dapp task is concentrated-liquidity LP (e.g. "create LP position with dapp-kit", "useSupplyLiquidity hook", "increase/decrease liquidity in React", "claim LP fees hook", "deposit hub assets for LP"). Two-step flow: deposit assets → supply liquidity. Covers BOTH integration (new v2 hooks) and migration (port v1 dex hooks — field renames + srcChainKey, mint/increase routing). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
+---
+
+# DEX (dapp-kit granular skill)
+
+Granular skill for the concentrated-liquidity DEX hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `dex`. Two-step flow: `useDexDeposit` (spoke asset → hub ERC-4626 pool shares) then `useSupplyLiquidity` (shares → position). React-only — backend uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which operation?** Asset deposit/withdraw (`useDexDeposit`/`useDexWithdraw`), supply liquidity (`useSupplyLiquidity` — mint-new OR increase-existing), decrease (`useDecreaseLiquidity`), claim fees (`useClaimRewards`).
+3. **Does opening a position require a deposit first?** Yes — positions hold hub pool shares; deposit from a spoke before supplying liquidity. UI flows usually combine the two steps.
+4. **Using the param builders?** `useCreate*Params` compute derived params (tick range, ERC-4626 conversions) client-side; spread their result into `mutate({ params: { ...result, srcChainKey, srcAddress }, walletProvider })`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/dex.md`](../integration/knowledge/features/dex.md) — full hook surface, SDK param types, the FLAT-props param builders, position-lifecycle notes.
+4. [`../integration/knowledge/recipes/dex.md`](../integration/knowledge/recipes/dex.md) — full worked examples.
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### DEX-specific anti-patterns (dapp-kit)
+
+- **Skipping `useDexDeposit` before `useSupplyLiquidity`.** Positions reference hub pool shares; without a deposit there's nothing to provide.
+- **Wrapping param builders in `{ params }`.** `useCreate*Params` take a FLAT props object (not `{ params }`-wrapped) and return memoized derived params; you add `srcChainKey` + `srcAddress` at the mutation call site.
+- **Treating ticks as prices.** `tickLower`/`tickUpper` are logarithmic indices — convert with Q96 math / SDK helpers.
+- **Calling a separate hook for increase-existing.** `useSupplyLiquidity` fans out to mint-new vs increase based on `params.tokenId` + `isValidPosition`; `useCreateSupplyLiquidityParams` handles the routing.
+- **`usePositionInfo` `tokenId` is `string | null`, not bigint.**
+- **Expecting `usePools` to auto-refresh.** It's `staleTime: Infinity` (static config).
+
+## Migration workflow (port v1 dex hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/dex.md`](../migration-v1-to-v2/knowledge/features/dex.md) — two-step flow unchanged; field renames + `srcChainKey` requirement; `useSupplyLiquidity` mint/increase routing.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Deposit precedes supply in combined flows.
+3. Param-builder output is spread with `srcChainKey`/`srcAddress` added at the call site.
+4. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
+5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
+
+## Related granular skills (same family)
+
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — recovery (`useWithdrawHubAsset`) for stuck hub LP assets; `useXBalances` / gas utilities.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.

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

@@ -0,0 +1,60 @@
+---
+name: sodax-dapp-kit-migration
+description: 'Granular skill for the @sodax/dapp-kit v2 token-migration feature only — React Query hooks for migrating legacy ICON-ecosystem tokens to SODAX assets: useMigrateIcxToSoda, useRevertMigrateSodaToIcx, useMigratebnUSD (bidirectional), useMigrateBaln (with lockup), useMigrationApprove/useMigrationAllowance (action-discriminated). Use when a React dapp task is migrating legacy tokens (e.g. "useMigrateIcxToSoda", "migrate bnUSD hook in React", "migrate BALN with lock period hook", "revert SODA to ICX hook"). IMPORTANT — this is the token-protocol migration FEATURE, NOT v1 → v2 SDK code porting (that is the sodax-dapp-kit skill in migration mode). Same word, different concept. Covers BOTH integration (new v2 hooks) and the v1 → v2 port of these migration hooks. Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
+---
+
+# Token migration (dapp-kit granular skill)
+
+Granular skill for the token-migration hooks of `@sodax/dapp-kit` v2 — ICX/wICX ↔ SODA, legacy bnUSD ↔ new bnUSD, BALN → SODA. queryKey/mutationKey first segment: `migrate`. React-only — backend uses `@sodax/sdk` directly.
+
+> **Important disambiguation.** This skill is about the token-migration **hooks** (migrating legacy ICON tokens to SODAX assets). It is **NOT** about porting v1 dapp-kit code to v2 — that lives under the broad `sodax-dapp-kit` skill (migration mode) and the [`../migration-v1-to-v2/knowledge/`](../migration-v1-to-v2/knowledge/) subtree. Same word, different concept.
+
+## Step 0 — Confirm this IS a token-protocol migration
+
+If the user means *"move/send/transfer a token from chain A to B"* → that's a **bridge** (vault-pair, [`../bridge/SKILL.md`](../bridge/SKILL.md)) or a **swap** (solver-routed, [`../swap/SKILL.md`](../swap/SKILL.md)). If they mean *"migrate my v1 dapp-kit code to v2"* → that's the SDK port; load the broad `sodax-dapp-kit` skill in migration mode. Only continue here for legacy ICON-ecosystem token migration.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port (of these hooks)?**
+2. **Which token?** ICX/wICX → SODA (`useMigrateIcxToSoda`), SODA → wICX revert (`useRevertMigrateSodaToIcx`), legacy bnUSD ↔ new bnUSD (`useMigratebnUSD`, bidirectional), BALN → SODA (`useMigrateBaln`).
+3. **For BALN: lockup period?** `lockupPeriod` is the `LockupPeriod` enum (values in SECONDS, not months); multiplier ranges 0.5x → 1.5x. `stake: boolean` is REQUIRED.
+4. **Allowance gating?** ICON-side migrations need none; Sonic-side (revert) and EVM bnUSD do — use `useMigrationAllowance` + `useMigrationApprove` with `action: 'migrate' | 'revert'`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/migration.md`](../integration/knowledge/features/migration.md) — full hook surface, per-action param types, the `LockupPeriod` enum, action-discriminated approve/allowance.
+4. [`../integration/knowledge/recipes/migration.md`](../integration/knowledge/recipes/migration.md) — full worked examples.
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Token-migration-specific anti-patterns (dapp-kit)
+
+- **Passing a literal number for BALN `lockupPeriod`.** Use the `LockupPeriod` enum members; values are seconds, not months. `BalnMigrateParams` also requires `stake: boolean`.
+- **Looking for a second bnUSD hook for the reverse direction.** `useMigratebnUSD` is bidirectional — swap `srcbnUSD`/`dstbnUSD` + chains for the other direction.
+- **Skipping approval on revert / EVM bnUSD.** `useRevertMigrateSodaToIcx` needs SODA approval on Sonic; gate with `useMigrationAllowance` + `useMigrationApprove({ action: 'revert' })`.
+- **Conflating this feature with the SDK v1 → v2 port.** Different concerns; reading one playbook for the other produces broken code.
+
+## Migration workflow (port v1 migration hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/migration.md`](../migration-v1-to-v2/knowledge/features/migration.md) — **biggest change**: v1's single `useMigrate(spokeProvider)`-style hook split into the per-action hooks above. The legacy `useMigrate` is in [`../migration-v1-to-v2/knowledge/reference/deleted-hooks.md`](../migration-v1-to-v2/knowledge/reference/deleted-hooks.md).
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. BALN flows pass a `LockupPeriod` enum member and `stake: boolean`.
+3. Revert / EVM-bnUSD flows gate on `useMigrationAllowance` + `useMigrationApprove`.
+4. No legacy `useMigrate`, no `useSpokeProvider` (migration only).
+
+## Related granular skills (same family)
+
+- [`../staking/SKILL.md`](../staking/SKILL.md) — BALN migration can auto-stake into xSODA (`stake: true`); generic SODA staking lives there.
+- [`../bridge/SKILL.md`](../bridge/SKILL.md), [`../swap/SKILL.md`](../swap/SKILL.md) — for "move a token across chains" (not a token-protocol migration).
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets (incl. ICON for ICX/BALN) and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.

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

@@ -0,0 +1,57 @@
+---
+name: sodax-dapp-kit-money-market
+description: 'Granular skill for the @sodax/dapp-kit v2 money-market feature only — React Query hooks for cross-chain lending/borrowing: useSupply, useBorrow, useWithdraw, useRepay, useMMAllowance, useMMApprove, plus reserves/position reads (useReservesHumanized, useUserFormattedSummary, useUserReservesData, useAToken, useATokensBalances). Use when a React dapp task is specifically money-market (e.g. "useSupply with dapp-kit", "borrow hook", "render health factor in React", "Sodax lending hooks", "withdraw collateral hook"). Covers BOTH integration (new v2 hooks) and migration (port v1 MM hooks — single-object params, srcChainKey/srcAddress required, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
+---
+
+# Money Market (dapp-kit granular skill)
+
+Granular skill for the lending/borrowing hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `mm`. React-only — backend uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which action?** `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, or read-only (reserves / user position).
+3. **Same-chain or cross-chain delivery?** All four actions accept optional `dstChainKey`/`dstAddress` (omit for same-chain; don't pass `dstChainKey === srcChainKey`).
+4. **Need allowance gating?** `supply`/`repay` need approval (`useMMAllowance` + `useMMApprove`); `borrow`/`withdraw` never need ERC-20 approval (`useMMAllowance` is `enabled: false` for those → `data` stays `undefined`).
+5. **Need position reads?** Reserve data (`useReservesHumanized` etc.) and user position (`useUserFormattedSummary`, `useUserReservesData`) — read hooks key on `spokeChainKey`, not `srcChainKey`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/money-market.md`](../integration/knowledge/features/money-market.md) — full hook surface, mutation TVars (`{ params: MoneyMarketSupplyParams<K>, walletProvider }`), reserve/position read shapes, the `spokeChainKey` vs `srcChainKey` split.
+4. [`../integration/knowledge/recipes/money-market.md`](../integration/knowledge/recipes/money-market.md) — full worked examples.
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Money-market-specific anti-patterns (dapp-kit)
+
+- **Using `srcChainKey`/`srcAddress` on read hooks.** Those are mutation-side names. Position reads (`useATokensBalances`, `useUserFormattedSummary`, `useUserReservesData`) key on `spokeChainKey` + `userAddress`; the hub wallet is derived automatically. Don't grep-replace one for the other.
+- **Treating `useMMAllowance` `undefined` as "not approved" for borrow/withdraw.** The query is `enabled: false` for those actions — `undefined` means "approval not required."
+- **Passing the MM params directly under `params` on `useMMAllowance`.** They nest under `params.payload`.
+- **Treating mutation `data` as `Result<T>`.** `data` is the unwrapped `TxHashPair = { srcChainTxHash, dstChainTxHash }`.
+- **Skipping a health-factor warning.** Render a warning when `useUserFormattedSummary().healthFactor` is near/below 1.0.
+
+## Migration workflow (port v1 MM hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md) — `srcChainKey`/`srcAddress` now required.
+3. [`../migration-v1-to-v2/knowledge/features/money-market.md`](../migration-v1-to-v2/knowledge/features/money-market.md) — add `srcChainKey`/`srcAddress` to every action; allowance auto-skip for borrow/withdraw.
+4. `invalidateMmQueries` and friends are gone — hooks own their invalidations. See [`../migration-v1-to-v2/knowledge/reference/deleted-hooks.md`](../migration-v1-to-v2/knowledge/reference/deleted-hooks.md).
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
+3. Read hooks use `spokeChainKey`/`userAddress` (not `srcChainKey`/`srcAddress`).
+4. No `invalidateMmQueries`, no `useSpokeProvider` (migration only).
+
+## Related granular skills (same family)
+
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — backend MM data reads (`useBackendMoneyMarketPosition`, suppliers/borrowers lists) that don't need a wallet.
+- [`../swap/SKILL.md`](../swap/SKILL.md) — when supplying collateral that requires an upstream swap.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`walletProvider` flows through `mutate(vars)` for the action hooks. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.

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

@@ -0,0 +1,56 @@
+---
+name: sodax-dapp-kit-staking
+description: 'Granular skill for the @sodax/dapp-kit v2 staking feature only — React Query hooks for SODA ↔ xSODA staking: useStake, useUnstake, useInstantUnstake, useClaim, useCancelUnstake, the three dedicated approve/allowance hook pairs (stake/unstake/instantUnstake), plus reads (useStakingInfo, useUnstakingInfoWithPenalty, useStakingConfig, useStakeRatio). Use when a React dapp task is specifically staking (e.g. "useStake with dapp-kit", "unstake hook with penalty", "claim staking rewards in React", "instant unstake slippage hook", "render staking info"). Covers BOTH integration (new v2 hooks) and migration (port v1 staking hooks — single-object params, useStakeRatio now returns a tuple, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
+---
+
+# Staking (dapp-kit granular skill)
+
+Granular skill for the staking hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `staking`. React-only — backend uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which action?** `useStake`, `useUnstake` (waiting period), `useInstantUnstake` (slippage, no wait), `useClaim`, `useCancelUnstake`.
+3. **Allowance gating?** `stake` approves SODA, `unstake`/`instantUnstake` approve xSODA — each has its OWN approve + allowance hook pair. `claim`/`cancelUnstake` need no approval.
+4. **Need reads?** `useStakingInfo` (position), `useUnstakingInfoWithPenalty` (pending requests + penalty), `useStakingConfig` (protocol params), `useStakeRatio`/`useInstantUnstakeRatio` (previews).
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/staking.md`](../integration/knowledge/features/staking.md) — full hook surface, mutation TVars per action, the three approve/allowance pairs, read shapes.
+4. [`../integration/knowledge/recipes/staking.md`](../integration/knowledge/recipes/staking.md) — full worked examples.
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Staking-specific anti-patterns (dapp-kit)
+
+- **Treating `useStakeRatio` `data` as a single bigint.** It's a 2-tuple `[xSodaAmount, previewDepositAmount]` (already unwrapped) — index `data?.[0]` / `data?.[1]`.
+- **Branching on `data.ok` for staking reads.** All staking read hooks are already unwrapped (the hook throws on SDK `!ok`). Read `data` fields directly; surface SDK failures via `isError`/`error`.
+- **Reading the request id at `req.request.requestId`.** On `useUnstakingInfoWithPenalty`, access `data?.requestsWithPenalty` directly; the id is `req.id`.
+- **One global approve hook.** There are three — `useStakeApprove` (SODA), `useUnstakeApprove` (xSODA), `useInstantUnstakeApprove` (xSODA). Pick the one matching the action.
+- **Treating instant unstake as free.** It bypasses the wait but pays slippage — preview with `useInstantUnstakeRatio`, set `minAmount`.
+
+## Migration workflow (port v1 staking hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/staking.md`](../migration-v1-to-v2/knowledge/features/staking.md) — all five mutations + their dedicated approve hooks; `useStakeRatio` now returns a tuple.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
+3. `useStakeRatio` consumers index the tuple (`data?.[0]`), not a scalar.
+4. Staking reads read `data` directly (no `.ok`/`.value`).
+5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
+
+## Related granular skills (same family)
+
+- [`../migration/SKILL.md`](../migration/SKILL.md) — BALN → SODA migration can auto-stake (`stake: true`); use it for BALN lock flows.
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useXBalances` / gas-estimation utilities used alongside staking UI.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.

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

@@ -0,0 +1,60 @@
+---
+name: sodax-dapp-kit-swap
+description: 'Granular skill for the @sodax/dapp-kit v2 swap feature only — React Query hooks for intent-based cross-chain swaps via the solver: useSwap, useQuote, useSwapAllowance, useSwapApprove, useStatus, useCreateLimitOrder, useCancelSwap, useCancelLimitOrder. Use when a React dapp has decided the task is a swap (e.g. "useSwap with dapp-kit", "Sodax React swap hook", "limit order hook", "poll swap status", "cancel a Sodax intent in React") and you want to skip loading the broad sodax-dapp-kit skill. Covers BOTH integration (write new v2 hooks) and migration (port v1 swap hooks to v2 — single-object params, mutateAsyncSafe, hook-owned invalidations). Picks via Step 1. Links into the parent sodax-dapp-kit knowledge tree. For backend/Node swaps (no React), use the sodax-sdk skill instead.'
+---
+
+# Swap (dapp-kit granular skill)
+
+Granular skill for the swap hooks of `@sodax/dapp-kit` v2. React-only — backend/Node swaps use `@sodax/sdk` directly. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+   - New → § Integration workflow.
+   - Port v1 → § Migration workflow.
+2. **Which hooks?** Quote/preview (`useQuote`), execute (`useSwap`), allowance gate (`useSwapAllowance` + `useSwapApprove`), status polling (`useStatus`), or limit orders (`useCreateLimitOrder` / `useCancelLimitOrder`).
+3. **Market order or limit order?** Limit orders use `useCreateLimitOrder` (no `deadline`; cancel manually via `useCancelLimitOrder`).
+4. **Imperative flow or render-driven?** Sequenced flows → `mutateAsyncSafe` (returns `Result<T>`, never rejects). Fire-and-forget → `mutate`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first; skipping it is the top cause of reverting to v1 hook shapes).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `SafeUseMutationResult`, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) — full hook surface, param shapes (`useQuote`/`useSwapAllowance` nest under `params.payload`; cancel hooks are FLAT), return shapes, polling intervals.
+4. [`../integration/knowledge/recipes/swap.md`](../integration/knowledge/recipes/swap.md) — full worked example.
+5. Call-shape choice (`mutate` / `mutateAsync` / `mutateAsyncSafe`) → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Swap-specific anti-patterns (dapp-kit)
+
+- **Treating `useSwap` `data` as `Result<T>`.** The hook's `mutationFn` unwraps before resolving — `data` is the success value (`SwapResponse = { intent, intentDeliveryInfo, solverExecutionResponse }`). For SDK `!ok` read `mutation.error` or use `mutateAsyncSafe` for the `Result<T>` shape.
+- **Passing the SDK request directly under `params` on `useQuote`.** It nests under `params.payload` (a `SolverIntentQuoteRequest`). `useSwapAllowance` nests `payload` + `srcChainKey` + `walletProvider` under `params`.
+- **Reading `data.status` on `useQuote` / `useStatus` without `data?.ok`.** Both return a `Result<…>` as their `data` — branch on `.ok` first. (`useSwapAllowance` is the opposite — already-unwrapped `boolean`.)
+- **`useStatus` key is `intentTxHash`, not `intentHash`.**
+- **Flattening `getSupportedSwapTokens()` and keying rows on `address`.** The same token address recurs across chains — use a composite `${address}-${blockchain_id}` key.
+- **Reaching for `useSpokeProvider`.** Deleted. Pass `walletProvider` into `mutate(vars)` for `useSwap`/`useSwapApprove`; cancel hooks take it flat.
+
+## Migration workflow (port v1 swap hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas, in order: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md) (single-arg policy), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md) (`mutateAsyncSafe`), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/swap.md`](../migration-v1-to-v2/knowledge/features/swap.md) — v1 `useSwap(spokeProvider)`-style call sites → v2 `mutate({ params, walletProvider })`; approve return-shape change.
+4. The SDK underneath also changed — also load the `sodax-sdk` skill (migration mode) for the raw swap-layer port.
+
+## Verification
+
+1. `pnpm tsc --noEmit` from the consumer repo exits clean.
+2. Sequenced swap flows use `mutateAsyncSafe` and branch on `result.ok` (user-reject is modal, not exceptional).
+3. `useQuote` / `useStatus` call sites branch on `data?.ok` before reading status fields.
+4. No `useSpokeProvider`, no hook-level `spokeProvider`/`params` (migration only).
+5. React Query devtools show hook-owned invalidations firing on success (consumer `onSuccess` runs after).
+
+## Related granular skills (same family)
+
+- [`../money-market/SKILL.md`](../money-market/SKILL.md) — if the swap feeds a supply/borrow action.
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useBackendSubmitSwapTx` / intent-tracking + orderbook reads (step-by-step swap + diagnostics), partner fee-claim swaps.
+
+For tasks spanning multiple features, load the broad [`sodax-dapp-kit` skill](../SKILL.md) instead.
+
+## Wallet connectivity (different SDK package family)
+
+This skill treats `walletProvider` as an input flowing through `mutate(vars)`. Every dapp-kit consumer needs wallet connectivity — **also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` per chain via `useWalletProvider({ xChainId: chainKey })`.