@sodax/skills 2.0.0-rc.4 → 2.0.0-rc.6

package/.claude-plugin/plugin.json

@@ -1,13 +1,9 @@
 {
   "name": "sodax-skills",
   "skills": [
-    "./skills/sodax-sdk-migration",
-    "./skills/sodax-sdk-integration",
-    "./skills/sodax-wallet-sdk-core-migration",
-    "./skills/sodax-wallet-sdk-core-integration",
-    "./skills/sodax-wallet-sdk-react-migration",
-    "./skills/sodax-wallet-sdk-react-integration",
-    "./skills/sodax-dapp-kit-migration",
-    "./skills/sodax-dapp-kit-integration"
+    "./skills/sodax-sdk",
+    "./skills/sodax-wallet-sdk-core",
+    "./skills/sodax-wallet-sdk-react",
+    "./skills/sodax-dapp-kit"
   ]
 }

package/AGENTS.md

@@ -4,29 +4,29 @@
 
 ## What's here
 
-This package ships **eight skills** (`skills/<name>/SKILL.md`) and a **knowledge** tree (`knowledge/<pkg>/<mode>/`) split per SODAX package. Skills are action-oriented: when to use, workflow, anti-patterns, links into knowledge. Knowledge is the reference material your workflow points at.
+This package ships **four mode-gated skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package. Each skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). 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 | Skill (write new code) | Skill (port v1 → v2) |
-|---|---|---|
-| `@sodax/sdk` | `sodax-sdk-integration` | `sodax-sdk-migration` |
-| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core-integration` | `sodax-wallet-sdk-core-migration` |
-| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react-integration` | `sodax-wallet-sdk-react-migration` |
-| `@sodax/dapp-kit` | `sodax-dapp-kit-integration` | `sodax-dapp-kit-migration` |
+| SDK package | Skill |
+|---|---|
+| `@sodax/sdk` | `sodax-sdk` |
+| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` |
+| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` |
+| `@sodax/dapp-kit` | `sodax-dapp-kit` |
 
 > **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:
+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 |
+| Consumer is… | Load skills (mode) |
 |---|---|
-| **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 the matching `*-integration` skills for any new code) |
-| **Porting an EXISTING v1 backend** | `sodax-sdk-migration` → `sodax-wallet-sdk-core-migration` (often no-op — additive only) |
+| **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:
 
@@ -48,26 +48,23 @@ Each `SKILL.md` is short on purpose. Follow it like a procedure:
 
 ```
 packages/skills/
-├── AGENTS.md                                   # You are here
-├── .claude-plugin/plugin.json                  # Skill registry (8 entries)
-├── skills/
-│   ├── sodax-sdk-{integration,migration}/SKILL.md
-│   ├── sodax-wallet-sdk-core-{integration,migration}/SKILL.md
-│   ├── sodax-wallet-sdk-react-{integration,migration}/SKILL.md
-│   └── sodax-dapp-kit-{integration,migration}/SKILL.md
-└── knowledge/
-    ├── sdk/{migration,integration}/            # ai-rules, quickstart, architecture, features/, recipes/, reference/, chain-specifics
-    ├── wallet-sdk-core/{migration,integration}/
-    ├── wallet-sdk-react/{migration,integration}/   # includes 4 working .tsx example apps
-    └── dapp-kit/{migration,integration}/
+├── AGENTS.md                              # You are here
+├── .claude-plugin/plugin.json             # Skill registry (4 entries)
+└── skills/                                # Each skill is mode-gated: SKILL.md + two knowledge subtrees
+    ├── sodax-sdk/                         {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}
+    ├── 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>/ai-rules.md` is the consolidated DO / DO NOT list. Skipping it is the top cause of stale v1 patterns.
+- **`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>/reference/` are for lookup, not narrative — chain keys, error codes, public API surface, hook signatures.
-- **Recipes** under `<mode>/recipes/` are self-contained — a recipe contains before/after code, steps, and verification. Don't jump between recipes for one task.
+- **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

package/README.md

@@ -13,7 +13,7 @@ Using the [`skills` CLI](https://github.com/vercel-labs/skills) from Vercel Labs
 npx skills@latest add icon-project/sodax-sdks/packages/skills
 ```
 
-Eight skills land in your repo (under `.claude/skills/` or wherever the CLI installs them), one knowledge tree per SODAX SDK package, and a router `AGENTS.md`. Re-running the command picks up the latest content.
+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).
 
@@ -21,9 +21,9 @@ Eight skills land in your repo (under `.claude/skills/` or wherever the CLI inst
 
 | Bundle | Contains |
 |---|---|
-| **8 skills** under `skills/sodax-<pkg>-<mode>/SKILL.md` | One skill per (package, mode). `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. `<mode>` ∈ `migration` (port v1 → v2), `integration` (write new v2 code). |
-| **Knowledge** under `knowledge/<pkg>/<mode>/` | Long-form supporting docs — features, recipes, reference tables, breaking-change writeups, code examples. Skills link into these. |
-| **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right set of skills. |
+| **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.
 
@@ -31,12 +31,12 @@ Skills are short and action-oriented (workflow + anti-patterns + links). Knowled
 
 After install, your agent picks based on what you're building. Quick guide:
 
-| You're building | Load these skills |
+| You're building | Load these skills (mode) |
 |---|---|
-| Backend / Node app (no React) using `@sodax/sdk` | `sodax-sdk-integration` (always) + `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** | Add the corresponding `*-migration` skill alongside each `*-integration` you'd use. |
+| 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.
 
@@ -46,4 +46,4 @@ LLM training data drifts: snippets from chat often use stale method names, resha
 
 ## 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 `knowledge/` tree is structurally CI-guarded (frontmatter, link resolution); prose claims benefit from real-world 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

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.0.0-rc.4",
+  "version": "2.0.0-rc.6",
   "license": "MIT",
   "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
   "keywords": [
@@ -29,7 +29,6 @@
   "files": [
     ".claude-plugin",
     "skills",
-    "knowledge",
     "AGENTS.md",
     "README.md"
   ],

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/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/README.md

@@ -1,6 +1,6 @@
 # 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 [`../migration/README.md`](../migration/README.md) instead.
+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
 
@@ -33,17 +33,17 @@ This tree documents v2 of the dapp-kit React hooks for **new consumers** buildin
 
 If your project also has v1 dapp-kit call sites, port them first using:
 
-- [`../migration/README.md`](../migration/README.md) — overview, reading order, and v1↔v2 glossary.
-- [`../migration/checklist.md`](../migration/checklist.md) — top-down cross-cutting checklist.
-- [`../migration/breaking-changes/`](../migration/breaking-changes/) — the four cross-cutting changes (hook-signatures, result-handling, queryKey-conventions, sdk-leakage).
-- [`../migration/features/`](../migration/features/) — per-feature playbooks in lockstep with `integration/features/` here.
+- [`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 knowledge tree at [`@sodax/sdk` knowledge tree](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills/knowledge/sdk/) (sibling under `@sodax/skills`). Useful for:
+`@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 [`../migration/breaking-changes/sdk-leakage.md`](../migration/breaking-changes/sdk-leakage.md).
+- 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/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/ai-rules.md

@@ -47,7 +47,7 @@ DO / DO NOT / workflow / stop conditions for AI agents writing v2 dapp-kit code.
 |---|---|
 | 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` skill (sibling under `@sodax/skills`) for non-React patterns. |
+| 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

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/architecture.md

@@ -273,4 +273,4 @@ Every mutation hook returns `SafeUseMutationResult` and is registered in `_mutat
 - [`recipes/invalidations.md`](recipes/invalidations.md) — composing your own `onSuccess`.
 - [`reference/querykey-conventions.md`](reference/querykey-conventions.md) — full key tables.
 - [`features/`](features/) — per-feature reference (hook tables, types, gotchas).
-- [`@sodax/sdk`: `integration/architecture.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/architecture.md) — the underlying SDK architecture (`Result<T>`, `SodaxError<C>`, `WalletProviderSlot<K, Raw>`).
+- `sodax-sdk`: `integration/knowledge/architecture.md` — the underlying SDK architecture (`Result<T>`, `SodaxError<C>`, `WalletProviderSlot<K, Raw>`).

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/README.md

@@ -20,7 +20,7 @@ Per-feature reference docs. Each file documents the hooks, params types, return
 
 ## Pair-completeness
 
-Every file in this directory has a sibling in [`../../migration/features/`](../../migration/features/) with the same filename — the v1→v2 porting playbook for that feature. When you're deep in one, the other is one path-swap away.
+Every file in this directory has a sibling in [`features/`](../../../migration-v1-to-v2/knowledge/features/) with the same filename — the v1→v2 porting playbook for that feature. When you're deep in one, the other is one path-swap away.
 
 ## Cross-references
 

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/auxiliary-services.md

@@ -2,7 +2,7 @@
 
 Smaller surfaces grouped together: partner fee claiming, recovery, backend queries (read-only data hooks), and shared utilities.
 
-Pair: [`../../migration/features/auxiliary-services.md`](../../migration/features/auxiliary-services.md).
+Pair: [`features/auxiliary-services.md`](../../../migration-v1-to-v2/knowledge/features/auxiliary-services.md).
 
 ## Partner
 
@@ -165,5 +165,5 @@ All overridable via `queryOptions.refetchInterval`.
 
 - [`../recipes/backend-queries.md`](../recipes/backend-queries.md) — worked examples for intent tracking, orderbook, MM data.
 - [`../recipes/wallet-connectivity.md`](../recipes/wallet-connectivity.md) — `useXBalances` worked example.
-- [`../../migration/features/auxiliary-services.md`](../../migration/features/auxiliary-services.md) — v1 → v2 porting.
-- [`@sodax/sdk`: `integration/features/auxiliary-services.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/features/auxiliary-services.md) — underlying SDK auxiliary surfaces (partner, recovery, backendApi).
+- [`features/auxiliary-services.md`](../../../migration-v1-to-v2/knowledge/features/auxiliary-services.md) — v1 → v2 porting.
+- `sodax-sdk`: `integration/knowledge/features/auxiliary-services.md` — underlying SDK auxiliary surfaces (partner, recovery, backendApi).

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/bitcoin.md

@@ -2,7 +2,7 @@
 
 Bitcoin trading via the Radfi protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
 
-Pair: [`../../migration/features/bitcoin.md`](../../migration/features/bitcoin.md).
+Pair: [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bitcoin.md).
 
 ## Hook surface
 
@@ -84,4 +84,4 @@ type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvi
 ## Cross-references
 
 - [`../recipes/bitcoin.md`](../recipes/bitcoin.md) — full worked examples (session, fund, withdraw, UTXO management).
-- [`../../migration/features/bitcoin.md`](../../migration/features/bitcoin.md) — v1 → v2 porting (mostly hook signature shape changes; flow stays the same).
+- [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bitcoin.md) — v1 → v2 porting (mostly hook signature shape changes; flow stays the same).

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/bridge.md

@@ -2,7 +2,7 @@
 
 Cross-chain token transfers via the hub-and-spoke vault architecture.
 
-Pair: [`../../migration/features/bridge.md`](../../migration/features/bridge.md).
+Pair: [`features/bridge.md`](../../../migration-v1-to-v2/knowledge/features/bridge.md).
 
 ## Hook surface
 
@@ -87,5 +87,5 @@ type UseGetBridgeableTokensParams = ReadHookParams<XToken[], {
 ## Cross-references
 
 - [`../recipes/bridge.md`](../recipes/bridge.md) — full worked example.
-- [`../../migration/features/bridge.md`](../../migration/features/bridge.md) — v1 → v2 porting.
-- [`@sodax/sdk`: `integration/features/bridge.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/features/bridge.md) — underlying SDK bridge surface.
+- [`features/bridge.md`](../../../migration-v1-to-v2/knowledge/features/bridge.md) — v1 → v2 porting.
+- `sodax-sdk`: `integration/knowledge/features/bridge.md` — underlying SDK bridge surface.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/dex.md

@@ -2,7 +2,7 @@
 
 Concentrated-liquidity DEX (similar to Uniswap V3). Two-step flow: deposit assets to mint pool tokens, then supply liquidity to a position.
 
-Pair: [`../../migration/features/dex.md`](../../migration/features/dex.md).
+Pair: [`features/dex.md`](../../../migration-v1-to-v2/knowledge/features/dex.md).
 
 ## Hook surface
 
@@ -148,5 +148,5 @@ if (supplyResult && walletProvider) {
 ## Cross-references
 
 - [`../recipes/dex.md`](../recipes/dex.md) — full worked examples.
-- [`../../migration/features/dex.md`](../../migration/features/dex.md) — v1 → v2 porting.
-- [`@sodax/sdk`: `integration/features/dex.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/features/dex.md) — underlying SDK DEX surface.
+- [`features/dex.md`](../../../migration-v1-to-v2/knowledge/features/dex.md) — v1 → v2 porting.
+- `sodax-sdk`: `integration/knowledge/features/dex.md` — underlying SDK DEX surface.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/migration.md

@@ -2,7 +2,7 @@
 
 Token migration: ICX/wICX → SODA, BALN → SODA, legacy bnUSD ↔ new bnUSD. Six per-action hooks plus shared allowance/approve.
 
-Pair: [`../../migration/features/migration.md`](../../migration/features/migration.md).
+Pair: [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md).
 
 ## Hook surface
 
@@ -114,5 +114,5 @@ await approve({ params: bnUSDParams, walletProvider, action: 'migrate' });
 ## Cross-references
 
 - [`../recipes/migration.md`](../recipes/migration.md) — full worked examples.
-- [`../../migration/features/migration.md`](../../migration/features/migration.md) — v1 → v2 porting (the v1 dapp-kit had a single `useMigrate(spokeProvider)`-style hook; v2 split into 6).
-- [`@sodax/sdk`: `integration/features/icx-bnusd-baln.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/features/icx-bnusd-baln.md) — underlying SDK migration surface.
+- [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md) — v1 → v2 porting (the v1 dapp-kit had a single `useMigrate(spokeProvider)`-style hook; v2 split into 6).
+- `sodax-sdk`: `integration/knowledge/features/icx-bnusd-baln.md` — underlying SDK migration surface.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/money-market.md

@@ -2,7 +2,7 @@
 
 Cross-chain lending and borrowing.
 
-Pair: [`../../migration/features/money-market.md`](../../migration/features/money-market.md).
+Pair: [`features/money-market.md`](../../../migration-v1-to-v2/knowledge/features/money-market.md).
 
 ## Hook surface
 
@@ -140,5 +140,5 @@ if (!isApproved) await approve({ params: supplyParams, walletProvider });
 ## Cross-references
 
 - [`../recipes/money-market.md`](../recipes/money-market.md) — full worked examples.
-- [`../../migration/features/money-market.md`](../../migration/features/money-market.md) — v1 → v2 porting.
-- [`@sodax/sdk`: `integration/features/money-market.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/features/money-market.md) — underlying SDK MM surface.
+- [`features/money-market.md`](../../../migration-v1-to-v2/knowledge/features/money-market.md) — v1 → v2 porting.
+- `sodax-sdk`: `integration/knowledge/features/money-market.md` — underlying SDK MM surface.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/staking.md

@@ -2,7 +2,7 @@
 
 SODA → xSODA staking via ERC-4626 vault. Five user actions plus reads.
 
-Pair: [`../../migration/features/staking.md`](../../migration/features/staking.md).
+Pair: [`features/staking.md`](../../../migration-v1-to-v2/knowledge/features/staking.md).
 
 ## Hook surface
 
@@ -119,5 +119,5 @@ All read hooks here are **already unwrapped** — they call `unwrapResult` inter
 ## Cross-references
 
 - [`../recipes/staking.md`](../recipes/staking.md) — full worked examples.
-- [`../../migration/features/staking.md`](../../migration/features/staking.md) — v1 → v2 porting.
-- [`@sodax/sdk`: `integration/features/staking.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/features/staking.md) — underlying SDK staking surface.
+- [`features/staking.md`](../../../migration-v1-to-v2/knowledge/features/staking.md) — v1 → v2 porting.
+- `sodax-sdk`: `integration/knowledge/features/staking.md` — underlying SDK staking surface.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/features/swap.md

@@ -2,7 +2,7 @@
 
 Cross-chain token swaps via the intent-based solver.
 
-Pair: [`../../migration/features/swap.md`](../../migration/features/swap.md).
+Pair: [`features/swap.md`](../../../migration-v1-to-v2/knowledge/features/swap.md).
 
 ## Hook surface
 
@@ -97,5 +97,5 @@ type UseStatusParams = ReadHookParams<
 
 - [`../recipes/swap.md`](../recipes/swap.md) — full worked example.
 - [`../recipes/mutation-error-handling.md`](../recipes/mutation-error-handling.md) — call-shape patterns.
-- [`../../migration/features/swap.md`](../../migration/features/swap.md) — v1 → v2 porting.
-- [`@sodax/sdk`: `integration/features/swap.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/features/swap.md) — underlying SDK swap surface.
+- [`features/swap.md`](../../../migration-v1-to-v2/knowledge/features/swap.md) — v1 → v2 porting.
+- `sodax-sdk`: `integration/knowledge/features/swap.md` — underlying SDK swap surface.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/quickstart.md

@@ -172,7 +172,7 @@ Some query hooks return `Result<T>` as their `data` (the underlying SDK method r
 | `Type ... is missing the following properties from type 'MoneyMarketSupplyParams': srcChainKey, srcAddress` | SDK-leakage: v2 added required `srcChainKey` + `srcAddress` to action params. | Add both to your `params` payload. See [`features/money-market.md`](features/money-market.md). |
 | `Cannot read properties of undefined (reading 'sodax')` | `useSodaxContext` (or any dapp-kit hook) called outside `<SodaxProvider>`. | Wrap your component tree in `<SodaxProvider>` from this package. |
 
-For broader v1 → v2 migration, see [`../migration/README.md`](../migration/README.md).
+For broader v1 → v2 migration, see [`README.md`](../../migration-v1-to-v2/knowledge/README.md).
 
 ## What to read next
 
@@ -184,5 +184,5 @@ For broader v1 → v2 migration, see [`../migration/README.md`](../migration/REA
 
 ## Cross-references
 
-- [`@sodax/sdk`: `AGENTS.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/AGENTS.md) — the underlying Core SDK's knowledge tree (sibling under `@sodax/skills`). Useful when you hit SDK-level types or behaviors leaking through hook signatures.
+- `sodax-sdk` (integration mode) skill — the underlying Core SDK's knowledge tree (sibling under `@sodax/skills`). Load it when you hit SDK-level types or behaviors leaking through hook signatures.
 

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/recipes/README.md

@@ -40,7 +40,7 @@ Copy-paste patterns for adding SODAX features to a React app. Each recipe is sel
 
 ## Hook conventions (mandatory)
 
-These rules are enforced across every dapp-kit hook by [`packages/dapp-kit/src/hooks/_mutationContract.test.ts`](../../../src/hooks/_mutationContract.test.ts) and apply to everything you write against this package.
+These rules are enforced across every dapp-kit hook by a contract test in the `@sodax/dapp-kit` source (`src/hooks/_mutationContract.test.ts`) and apply to everything you write against this package.
 
 ### Single-object params
 
@@ -129,8 +129,8 @@ const display = formatUnits(amount, 18); // '1.5'
 
 ## Backend / non-React consumers
 
-If you're building a backend (API server, bot, script), you don't need `@sodax/dapp-kit` at all — use `@sodax/sdk` directly. The SDK has its own knowledge tree shipped via `@sodax/skills` — load the `sodax-sdk-integration` skill or read `node_modules/@sodax/skills/knowledge/sdk/AGENTS.md` directly.
+If you're building a backend (API server, bot, script), you don't need `@sodax/dapp-kit` at all — use `@sodax/sdk` directly. The SDK has its own knowledge tree shipped via `@sodax/skills` — load the `sodax-sdk` (integration mode) skill.
 
 ## Migration pointer
 
-If you're porting v1 dapp-kit code to v2, start at [`../../migration/README.md`](../../migration/README.md). It covers: hook signatures (single-arg policy), `Result<T>` handling shift, deleted `useSpokeProvider`, queryKey conventions, and SDK leakage.
+If you're porting v1 dapp-kit code to v2, start at [`README.md`](../../../migration-v1-to-v2/knowledge/README.md). It covers: hook signatures (single-arg policy), `Result<T>` handling shift, deleted `useSpokeProvider`, queryKey conventions, and SDK leakage.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/recipes/invalidations.md

@@ -107,7 +107,7 @@ The order is unchanged: hook invalidations → consumer `onSuccess` → per-call
 
 In v1 dapp-kit, consumers managed invalidations themselves — most apps had a `lib/invalidate*Queries.ts` utility that fired `queryClient.invalidateQueries(...)` after each mutation. Those utilities are no longer needed in v2; delete them.
 
-If you're migrating v1 code, see [`../../migration/breaking-changes/hook-signatures.md`](../../migration/breaking-changes/hook-signatures.md) for the full delta.
+If you're migrating v1 code, see [`breaking-changes/hook-signatures.md`](../../../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md) for the full delta.
 
 ## Cross-references
 

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/reference/README.md

@@ -9,4 +9,4 @@ Lookup tables. Read while writing code; not a tutorial.
 | [`public-api.md`](public-api.md) | What `@sodax/dapp-kit` exports + import rules. |
 | [`glossary.md`](glossary.md) | Type aliases (`ReadHookParams`, `MutationHookParams`, `SafeUseMutationResult`, `MutationHookOptions`, etc.). |
 
-For full SDK reference (chain keys, error codes, `Sodax` class surface, wallet provider interfaces), see [`@sodax/sdk`: `integration/reference/`](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills/knowledge/sdk/integration/reference/) — `@sodax/dapp-kit` re-exports the SDK's public surface, so those types are reachable from `@sodax/dapp-kit` directly.
+For full SDK reference (chain keys, error codes, `Sodax` class surface, wallet provider interfaces), see `sodax-sdk`: `integration/knowledge/reference/` — `@sodax/dapp-kit` re-exports the SDK's public surface, so those types are reachable from `@sodax/dapp-kit` directly.

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/reference/glossary.md

@@ -1,6 +1,6 @@
 # Glossary — `@sodax/dapp-kit` v2
 
-Type aliases, conventions, and domain terms specific to dapp-kit. SDK-side terms (Hub, Spoke, Intent, ChainKey, SodaxError, etc.) are documented in [`@sodax/sdk`: `integration/reference/glossary.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/reference/glossary.md).
+Type aliases, conventions, and domain terms specific to dapp-kit. SDK-side terms (Hub, Spoke, Intent, ChainKey, SodaxError, etc.) are documented in `sodax-sdk`: `integration/knowledge/reference/glossary.md`.
 
 ## Hook shape types
 
@@ -187,4 +187,4 @@ When porting v1 code, these shifts are pervasive:
 - [`../architecture.md`](../architecture.md) — full design rationale for these types and conventions.
 - [`querykey-conventions.md`](querykey-conventions.md) — queryKey/mutationKey rules.
 - [`public-api.md`](public-api.md) — what's exported.
-- [`@sodax/sdk`: `integration/reference/glossary.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/reference/glossary.md) — SDK-side terms (Hub, Spoke, Intent, ChainKey, SodaxError).
+- `sodax-sdk`: `integration/knowledge/reference/glossary.md` — SDK-side terms (Hub, Spoke, Intent, ChainKey, SodaxError).

package/{knowledge/dapp-kit/integration → skills/sodax-dapp-kit/integration/knowledge}/reference/public-api.md

@@ -107,4 +107,4 @@ Don't rely on any other path being present. Consumer-facing AI docs (this knowle
 
 - [`../architecture.md`](../architecture.md) — design rationale for the canonical hook shapes.
 - [`hooks-index.md`](hooks-index.md) — full hook list.
-- [`@sodax/sdk`: `integration/reference/public-api.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/reference/public-api.md) — underlying SDK's public API surface.
+- `sodax-sdk`: `integration/knowledge/reference/public-api.md` — underlying SDK's public API surface.