@sodax/skills 2.0.0-rc.10

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/error-shape-crosswalk.md

@@ -0,0 +1,144 @@
+# Error shape crosswalk — v1 → v2
+
+The shape and type of errors flowing through dapp-kit hooks changed in v2. The change is mostly SDK-level (one canonical `SodaxError<C>` replaces 7+ per-feature classes) but it surfaces in dapp-kit at the consumer level — wherever you catch or branch on errors from hooks.
+
+## Where v2 errors appear
+
+| Surface | v1 | v2 |
+|---|---|---|
+| `mutation.error` | Only on actual exceptions | Includes SDK `!ok` errors (now thrown inside `mutationFn`) |
+| `mutation.data` | `Result<T>` (`{ ok, value, error }`) | Unwrapped success type `T`; SDK `!ok` flows to `mutation.error` |
+| `mutateAsync` rejection | Only on exceptions | Includes SDK `!ok` rejections |
+| `mutateAsyncSafe` `result.error` | (didn't exist) | Includes SDK `!ok` errors (re-packed from the throw) |
+| `onError` callback | Fired only for exceptions | Fires for SDK `!ok` too |
+
+The semantic shift is: v1 treated SDK `!ok` as "successful but with an error inside"; v2 treats it as a thrown error. See [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) for the full picture.
+
+## Error class crosswalk (SDK-level — leaks through)
+
+In v1, each SDK feature had its own error class:
+
+```ts
+// @ai-snippets-skip — describes deleted v1 type surface, not runnable
+// v1
+class MoneyMarketError<C extends MoneyMarketErrorCode> extends Error { /* ... */ }
+class IntentError<C extends IntentErrorCode> extends Error { /* ... */ }
+class StakingError<C extends StakingErrorCode> extends Error { /* ... */ }
+class BridgeError<C extends BridgeErrorCode> extends Error { /* ... */ }
+class MigrationError<C extends MigrationErrorCode> extends Error { /* ... */ }
+class AssetServiceError<C extends AssetServiceErrorCode> extends Error { /* ... */ }
+class ConcentratedLiquidityError<C extends ConcentratedLiquidityErrorCode> extends Error { /* ... */ }
+// ...
+```
+
+In v2, all are consolidated:
+
+```ts
+// @ai-snippets-skip — type-shape reference; the real class is exported from @sodax/sdk
+// v2
+class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
+  readonly code: C;                  // closed reason union (no feature prefix)
+  readonly feature: SodaxFeature;    // 'swap' | 'moneyMarket' | 'bridge' | …
+  readonly cause?: unknown;
+  readonly context?: SodaxErrorContext;
+}
+```
+
+Discriminate via `(error.feature, error.code)` instead of class name.
+
+## Error code crosswalk (key examples)
+
+The SDK reduced the per-feature code unions to a unified 13-code reason vocabulary, with feature-specific context on `error.context.action` / `error.context.method`. Examples:
+
+| v1 (per-feature) | v2 |
+|---|---|
+| `MoneyMarketError<'CREATE_SUPPLY_INTENT_FAILED'>` | `SodaxError<'INTENT_CREATION_FAILED'>` with `feature: 'moneyMarket'`, `context.action: 'supply'` |
+| `MoneyMarketError<'SUPPLY_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'moneyMarket'`, `context.action: 'supply'` |
+| `IntentError<'CREATE_INTENT_FAILED'>` | `SodaxError<'INTENT_CREATION_FAILED'>` with `feature: 'swap'`, `context.action: 'createIntent'` |
+| `IntentError<'POST_EXECUTION_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'swap'`, `context.phase: 'postExecution'` |
+| `StakingError<'STAKE_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'staking'`, `context.action: 'stake'` |
+| `BridgeError<'BRIDGE_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'bridge'`, `context.action: 'bridge'` |
+| `MigrationError<'MIGRATE_BNUSD_FORWARD_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'migration'`, `context.action: 'migratebnUSD'`, `context.direction: 'forward'` |
+| `*Error<'ALLOWANCE_CHECK_FAILED'>` | `SodaxError<'ALLOWANCE_CHECK_FAILED'>` (unchanged code; new feature/context fields) |
+| `*Error<'APPROVE_FAILED'>` | Same |
+| `*Error<'GAS_ESTIMATION_FAILED'>` | Same |
+| `*Error<'RELAY_TIMEOUT'>` | `SodaxError<'RELAY_TIMEOUT'>` with `relayCode: 'RELAY_TIMEOUT'` on context |
+
+Full crosswalk (per feature): `sodax-sdk`: `migration-v1-to-v2/knowledge/reference/error-code-crosswalk.md`.
+
+## How to migrate error-handling code
+
+### Pattern 1: `instanceof` checks → `isSodaxError`
+
+```diff
+- catch (e) {
+-   if (e instanceof MoneyMarketError) {
+-     handleMmError(e.code);
+-   }
+- }
++ catch (e) {
++   if (isSodaxError(e) && e.feature === 'moneyMarket') {
++     handleMmError(e.code);
++   }
++ }
+```
+
+`isSodaxError` is exported from `@sodax/dapp-kit` (re-exported from `@sodax/sdk`).
+
+### Pattern 2: switch on code
+
+```diff
+  catch (e) {
+-   if (e instanceof IntentError) {
+-     switch (e.code) {
+-       case 'CREATE_INTENT_FAILED': /* ... */ break;
+-       case 'POST_EXECUTION_FAILED': /* ... */ break;
+-       case 'RELAY_TIMEOUT': /* ... */ break;
+-     }
+-   }
++   if (isSodaxError(e) && e.feature === 'swap') {
++     switch (e.code) {
++       case 'INTENT_CREATION_FAILED': /* was CREATE_INTENT_FAILED */ break;
++       case 'EXECUTION_FAILED':       /* was POST_EXECUTION_FAILED — check e.context.phase */ break;
++       case 'RELAY_TIMEOUT':           /* unchanged code */ break;
++     }
++   }
+  }
+```
+
+### Pattern 3: error-text helper
+
+If your v1 code has a helper that maps `error.code` to a UI message, write a small adapter:
+
+```ts
+// adapters/v1ErrorShape.ts
+import { isSodaxError } from '@sodax/dapp-kit';
+
+const V1_CODE_MAP: Record<string, string> = {
+  'INTENT_CREATION_FAILED': 'CREATE_INTENT_FAILED',
+  'EXECUTION_FAILED': 'POST_EXECUTION_FAILED',
+  // ... etc.
+};
+
+export function adaptToV1Code(error: unknown): string | undefined {
+  if (!isSodaxError(error)) return undefined;
+  return V1_CODE_MAP[error.code] ?? error.code;
+}
+```
+
+Plan to delete the adapter once you've ported all error UI.
+
+## Pitfalls
+
+1. **`onError` callbacks fire MORE in v2.** They previously didn't fire for SDK `!ok` (success-path-with-error pattern). Now they do. Audit toasts / logs to make sure they're appropriate.
+2. **`mutation.error` reads MORE in v2.** Same reason — SDK errors flow through it now.
+3. **`isSodaxError(e)` is the cross-bundle-safe check.** Bare `instanceof SodaxError` may break in monorepos with multiple package copies (mixed ESM/CJS, etc.). Use the type guard.
+4. **The `feature` field is your discriminator.** A `SodaxError` from a swap mutation has `feature: 'swap'`. A bridge mutation has `feature: 'bridge'`. The `code` is the reason; `feature` is the source.
+
+## Cross-references
+
+- [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) — semantic shift in `Result<T>` handling.
+- [`../breaking-changes/sdk-leakage.md`](../breaking-changes/sdk-leakage.md) — broader SDK-side migrations.
+- `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md` — full SDK error-class consolidation.
+- `sodax-sdk`: `migration-v1-to-v2/knowledge/reference/error-code-crosswalk.md` — per-feature error code crosswalks.
+- [`architecture.md`](../../../integration/knowledge/architecture.md) § "SDK Result handling" — design rationale.

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md

@@ -0,0 +1,68 @@
+# Renamed hooks — v1 → v2
+
+Hooks whose **name** changed between versions. Most v1 → v2 changes were signature-level (single-object params, `mutateAsyncSafe`, etc.) — actual hook renames are rare. The list below is the small set.
+
+## Hooks renamed
+
+| v1 | v2 | Notes |
+|---|---|---|
+| (none significant) | | Most hook names are stable across v1 → v2 |
+
+### Why this list is short
+
+The v2 canonicalization pass focused on hook **shapes** (single-object params, return-shape consolidation, mutateAsyncSafe), not naming. For most consumer code, the hook name you `import { ... }`'d in v1 is still the right hook in v2 — the breaking change is in the call shape, not the import.
+
+## Hooks whose generic / type shape changed
+
+These keep their name but their TypeScript signature is different. Usually requires per-call-site fixes.
+
+| Hook | v1 → v2 change |
+|---|---|
+| `useSwap` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params } → { params, walletProvider }`. |
+| `useSwapAllowance` | Query params: `(params, spokeProvider) → { params: { payload, srcChainKey, walletProvider } }`. SDK request nested under `params.payload`. Data unwrapped to `boolean`. |
+| `useSwapApprove` | Return: `{ approve, isLoading } → SafeUseMutationResult` (with `mutateAsync` / `isPending`). Vars accept `CreateIntentParams \| CreateLimitOrderParams`. TData is `TxReturnType<K, false>` (chain-keyed receipt union). |
+| `useStatus` | Now `useStatus({ params: { intentTxHash } })` — single-object shape AND key renamed from `intentHash` → `intentTxHash`. Data is `Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined` (Result-wrapped). Polls 3s. |
+| `useQuote` | Now `useQuote({ params: { payload } })` — SDK request nested under `params.payload` (NOT directly under `params`). Data is `Result<SolverIntentQuoteResponse, SolverErrorResponse> \| undefined`. Polls 3s. |
+| `useCancelSwap` / `useCancelLimitOrder` | TVars are FLAT (no `params` wrapper): `{ srcChainKey, intent, walletProvider }`. |
+| `useCreateLimitOrder` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params, walletProvider }`. mutationKey is `['swap', 'limitOrder', 'create']`. |
+| All MM mutations (`useSupply`/etc.) | Same as `useSwap`. Plus `srcChainKey` / `srcAddress` required in params (SDK-leakage). All four actions accept optional `dstChainKey`/`dstAddress` for cross-chain delivery (not just borrow/repay). |
+| `useMMAllowance` | Query params: `{ params: { payload: MoneyMarketParams<K> } }`. For `'borrow'` / `'withdraw'` actions: `enabled: false` — `data` stays `undefined`. |
+| `useUserReservesData` | Param key rename: `address → userAddress`; chain key is `spokeChainKey`. |
+| `useUserFormattedSummary` | Same. |
+| `useATokensBalances` | Params: `{ aTokens, spokeProvider, userAddress } → { params: { aTokens, spokeChainKey, userAddress } }`. `spokeProvider` dropped; chain key is **`spokeChainKey`** (NOT `srcChainKey`); user field is **`userAddress`** (NOT `address`). Data: `Map<Address, bigint> \| undefined` (already unwrapped). |
+| `useAToken` | Unaffected by the position-hook renames — takes only `{ aToken }`. Data: `Erc20Token & { chainKey }` (`hubAsset` / `vault` NOT included). |
+| All staking mutations | Same as MM. Plus dedicated approve hooks per token (`useStakeApprove` ↔ `useUnstakeApprove` ↔ `useInstantUnstakeApprove`). |
+| `useStakeRatio` | Return: `Result<bigint> → [xSodaAmount, previewDepositAmount]` (unwrapped tuple — NOT Result-wrapped in v2). |
+| `useStakingInfo` / `useUnstakingInfo` / `useUnstakingInfoWithPenalty` / `useStakingConfig` / `useInstantUnstakeRatio` / `useConvertedAssets` | All unwrapped in v2 (hooks throw on SDK `!ok`). Branch on `isError`/`error`, not `data?.ok`. |
+| `useUnstakingInfo` | Return shape: array → object `{ userUnstakeSodaRequests, totalUnstaking }`. `UserUnstakeInfo` items expose `id` (the requestId) and `request` (original `UnstakeSodaRequest`). |
+| All three staking allowance hooks | Query params: `{ params: { payload: Omit<<Action>Params<K>, 'action'> } }`. Data unwrapped to `boolean`. |
+| `useBridge` | Params: `srcChainId/dstChainId/recipient → srcChainKey/dstChainKey/recipient`. Plus field renames inside `CreateBridgeIntentParams`: `srcAsset → srcToken`, `dstAsset → dstToken`. Return: tuple → `TxHashPair` object (`{ srcChainTxHash, dstChainTxHash }`). |
+| `useBridgeAllowance` | Query params: nested `{ params: { payload, walletProvider } }`. Data unwrapped to `boolean` (queryFn returns `false` on SDK `!ok` — does NOT throw). |
+| `useGetBridgeableAmount` | Params: 4 fields → `{ from: XToken, to: XToken }`. Return: `bigint → BridgeLimit` object (`{ amount, decimals, type: 'DEPOSIT_LIMIT' \| 'WITHDRAWAL_LIMIT' }`). |
+| `useGetBridgeableTokens` | Params: positional → `{ params: { from, to, token } }`. |
+| All DEX mutations | Same as MM. `useSupplyLiquidity` now handles both mint-new and increase-existing — fan-out gated by `params.tokenId` + `params.isValidPosition`. |
+| `useDexAllowance` | Now `{ params: { payload: CreateAssetDepositParams<K> } }`. No `walletProvider` (read-only). |
+| `PoolKey` shape | Real fields are `currency0`, `currency1`, `fee`, `hooks?`, `poolManager`, `parameters` — NOT `poolAddress`/`token0Symbol`/etc. |
+| `useCreate*Params` builders | All take FLAT props object — NOT `{ params }`-wrapped (`useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams`). |
+| `useFeeClaimSwap` (partner) | Same as MM mutation pattern. TData is `IntentAutoSwapResult` (NOT `SwapResponse`). |
+| `useXBalances` | Params: positional → `{ params: { xService, xChainId, xTokens, address } }`. All four required. `xService` injected from `@sodax/wallet-sdk-react`. |
+| `useEstimateGas` | Mutation; vars: `EstimateGasParams<C>` (flat, not `{ params, walletProvider }`-wrapped). |
+| `useDeriveUserWalletAddress`, `useGetUserHubWalletAddress` | Single-object query shape. |
+| `useStellarTrustlineCheck` | Single-object shape with `{ token, amount, chainId, walletProvider }` under `params`. |
+| `useRequestTrustline` | Custom utility hook (NOT a canonical mutation). Takes `(token: string \| undefined)` positionally, returns `{ requestTrustline, isLoading, isRequested, error, data }`. The `requestTrustline` callback takes `{ token, amount, srcChainKey, walletProvider }`. |
+| `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers` | Pagination MUST be nested under `params`: `{ params: { pagination: { offset, limit } } }`. |
+| `useBackendUserIntents` | Data is `UserIntentsResponse = { items: IntentResponse[], total, offset, limit }` — NOT a bare array. Access `data?.items`. |
+| `useBackendSubmitSwapTx` | Mutation. `apiConfig` moved from hook init to `mutate(vars)`. |
+| All migration hooks | **NEW**: 6 per-action hooks replacing v1's single `useMigrate`. See [`deleted-hooks.md`](deleted-hooks.md). |
+| `useMigrationAllowance` | Query params nest under `params` with inner field literally named `params` (NOT `payload`): `{ params: { params: <migration-params>, action: 'migrate' \| 'revert' } }`. |
+| `BalnMigrateParams` (used by `useMigrateBaln`) | NEW required field `stake: boolean`. `lockupPeriod` is the `LockupPeriod` enum (5 members; values in seconds, not months). |
+| `useTradingWalletBalance` | Return is `RadfiWalletBalance = { btcSatoshi, pendingSatoshi, externalPendingSatoshi, totalUtxos }` — NOT `{ confirmed, pending }`. |
+| `useExpiredUtxos` | Return is `RadfiUtxo[]` (with `_id`, `txid`, `vout`, `txidVout`, `satoshi`, `amount`, `address`, `isSpent`, `status`, `source`, optional `runes`). Both this and `useTradingWalletBalance` take `{ params: { walletProvider, tradingAddress } }`. |
+| `useRadfiAuth` | TData is `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields — `publicKey` is persisted to localStorage but NOT returned). |
+| All Bitcoin/Radfi mutations | Standard pattern — drop hook-init args; pass through `mutate(vars)`. |
+
+## Cross-references
+
+- [`deleted-hooks.md`](deleted-hooks.md) — hooks that no longer exist at all.
+- [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) — shape changes in detail.
+- [`../features/`](../features/) — per-feature porting playbooks.

package/skills/sodax-sdk/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: sodax-sdk
+description: 'INTEGRATION (write NEW v2 code) — @sodax/sdk v2 is the SODAX cross-chain DeFi SDK (hub-and-spoke architecture, Sonic hub + 19 spoke chains across EVM and non-EVM). Covers intent-based swaps, lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN token migration, partner fees, and stuck-asset recovery. Use whenever a non-React or backend codebase calls `@sodax/sdk` directly (Node scripts, indexers, bots, server APIs, custom non-React browser flows). Triggers on "use @sodax/sdk", "swap with Sodax", "Sodax bridge", "Sodax money market", "Sodax staking", "cross-chain DeFi", "Sonic hub", any `Sodax` / `ChainKeys` / `Result<T>` / `SodaxError` symbol. For React dapps, prefer `sodax-dapp-kit` instead. MIGRATION (port v1 → v2) — the v2 reshape replaced `*SpokeProvider` classes with chain-key-driven routing, throws with `Result<T>`, module-specific error unions with `SodaxError<C>`, ad-hoc wallet/raw branching with `WalletProviderSlot<K, Raw>`, and static lookup tables with `ConfigService`. Triggers on "migrate Sodax v1", "upgrade @sodax/sdk", "v1 → v2", "useSpokeProvider broken", "Sodax error types changed", v1 fingerprints (`_MAINNET_CHAIN_ID`, `*SpokeProvider`, `xChainId`, `SpokeChainId`, `MoneyMarketError`/`IntentError`/`StakingError`/`BridgeError`/`MigrationError`/`AssetServiceError`/`ConcentratedLiquidityError`/`RelayError`). 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/sdk` v2 — either writing new code or porting from v1.
+
+**Pick your mode:**
+
+- Writing NEW v2 code (greenfield, no v1 fingerprints, no React)? → § **Integration mode** below.
+- Porting EXISTING v1 code to v2 (grep finds `useSpokeProvider`, `*_MAINNET_CHAIN_ID`, `xChainId`, `SpokeChainId`, module-specific error classes)? → § **Migration mode** below.
+- Both? → do migration first, then integration. Stale v1 patterns leak into new code if you skip it.
+
+For React dapps using hooks → use `sodax-dapp-kit` instead (this skill is still relevant for any unwrapped SDK call).
+
+## Prefer a granular skill if the feature is known
+
+If the user has already picked a single feature, load the matching granular skill instead of this broad one — it loads ~3 KB of focused workflow vs this file's ~13 KB and links directly into the right knowledge files. The granular skills sit in the same family (`sdk`) and cover both integration and migration via internal cross-links.
+
+| Feature | Granular skill | Trigger phrases |
+|---|---|---|
+| Intent-based swap (market + limit orders) | [`./swap/SKILL.md`](./swap/SKILL.md) | "swap with Sodax", "limit order", "cancel intent" |
+| Cross-chain lending / borrowing | [`./money-market/SKILL.md`](./money-market/SKILL.md) | "supply", "borrow", "withdraw collateral", "repay" |
+| Direct token bridge via vault | [`./bridge/SKILL.md`](./bridge/SKILL.md) | "bridge tokens", "cross-chain transfer" |
+| SODA ↔ xSoda staking | [`./staking/SKILL.md`](./staking/SKILL.md) | "stake SODA", "instant unstake", "claim staking rewards" |
+| Concentrated-liquidity LP | [`./dex/SKILL.md`](./dex/SKILL.md) | "LP position", "concentrated liquidity", "deposit hub assets" |
+| ICX / bnUSD / BALN token migration to SODAX | [`./migration/SKILL.md`](./migration/SKILL.md) | "migrate ICX", "legacy bnUSD", "BALN lockup" (NOT v1→v2 SDK porting) |
+| Partner fees | [`./partner/SKILL.md`](./partner/SKILL.md) | "claim partner fee", "partner auto-swap preference", "approve partner fee token" |
+| Stuck-asset recovery | [`./recovery/SKILL.md`](./recovery/SKILL.md) | "recover stuck assets on Sonic", "RecoveryService", "withdrawHubAsset" |
+| Backend HTTP client (intents, orderbook, MM reads) | [`./backend-api/SKILL.md`](./backend-api/SKILL.md) | "submit swap tx to backend", "getIntentByHash", "Sodax backend API", "custom IConfigApi" |
+
+Load this broad skill (keep reading below) when:
+
+- The feature is not yet decided.
+- The task spans **multiple** features (e.g. swap + money-market in one flow).
+- The consumer is doing a **full v1 → v2 port** of an existing codebase.
+
+## Out of scope
+
+This skill documents the **SDK call sites** — what to import, how to construct `Sodax`, which method to call, and how to handle the `Result<T>`. It does **not** prescribe application-layer concerns.
+
+### Where to go for the things this skill does NOT cover
+
+- **Wallet provider implementations** (`IEvmWalletProvider`, `ISolanaWalletProvider`, etc.) → **load the `sodax-wallet-sdk-core` skill** (integration mode). It ships ready-made provider classes for all 9 chain families, both private-key (Node / scripts) and browser-extension modes. This skill only treats wallet providers as a contract (`declare const evmWallet: IEvmWalletProvider`).
+- **React hooks wrapping the SDK** → **load the `sodax-dapp-kit` skill** instead of this one.
+- **Browser wallet connectivity** (connect / disconnect / chain switching for React apps) → **load the `sodax-wallet-sdk-react` skill**.
+
+### App-layer concerns the SDK is intentionally silent on
+
+- **Multi-user state** (Telegram bot per-user wallets, dApp session storage, custodial vs non-custodial design). Hold one wallet-provider instance per user/chain at the app layer and pass it into each call — the SDK is stateless.
+- **UI**, framework wiring, route handlers, webhooks. Pick your own framework (telegraf/grammy for bots, Next.js / Vite for web, etc.) — the SDK has no opinion.
+- **Token discovery beyond `sodax.config`**. The SDK exposes `sodax.config.findSupportedTokenBySymbol(chainKey, symbol)` for per-chain lookups and `sodax.bridge.getBridgeableTokens(from, to, srcAddress)` / `sodax.bridge.isBridgeable({ from, to })` for vault-pair checks. There is no exhaustive "all bridgeable pairs across all chains" table — derive it at runtime if needed.
+
+If the consumer needs a runnable end-to-end app (Node bot, CLI, full dApp), the right combination is: this skill (for SDK call sites) + `sodax-wallet-sdk-core` (for wallet providers) + the consumer's chosen framework code. The SDK does not ship an app skeleton.
+
+---
+
+## Integration mode (writing new v2 code)
+
+Pick this mode when the consumer is **writing new v2 code** that calls `@sodax/sdk` directly (no React wrapper). Common signals:
+
+- Node.js server, script, indexer, bot, or CI test that uses `Sodax`.
+- Custom browser flow without `@sodax/dapp-kit`.
+- Any cross-chain DeFi action: swap, bridge, money market (supply/borrow/withdraw/repay), staking, DEX (concentrated liquidity), migration (ICX/bnUSD/BALN), partner fees, recovery.
+
+### Workflow
+
+Follow in order. Skipping `ai-rules.md` is the most common cause of agents reverting to v1 patterns.
+
+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, initialize, first-run troubleshooting.
+3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `backend-api.md`.
+4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
+5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`integration/knowledge/reference/`](./integration/knowledge/reference/).
+6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`integration/knowledge/chain-specifics.md`](./integration/knowledge/chain-specifics.md).
+
+### v2 in one minute
+
+1. **Chain key drives everything.** Pass `srcChainKey: ChainKeys.ETHEREUM_MAINNET` on the request payload — the SDK routes internally and TypeScript narrows `walletProvider` to the chain-specific interface via `GetWalletProviderType<K>`. There are **no** `*SpokeProvider` classes to construct.
+2. **Every async public method returns `Result<T>`.** Branch on `result.ok`. No throws across service boundaries. Sub-Result forwarding is the default: `if (!sub.ok) return sub`.
+3. **Errors are `SodaxError<C>`.** A single class with a closed 13-code reason vocabulary plus a `feature` field. The pair `(feature, code)` is your discriminator. Use `isSodaxError(e)` (not bare `instanceof`).
+4. **Signed vs raw is a discriminated union.** `WalletProviderSlot<K, Raw>` enforces at compile time: `{ raw: false, walletProvider }` for signing, `{ raw: true }` for unsigned-tx building. Mixing them is a TypeScript error.
+5. **Config is dynamic; overrides only land on `sodax.config`.** Always read via `sodax.config.*` (e.g. `sodax.config.spokeChainConfig[chainKey]`). Direct imports of `spokeChainConfig` / `sodaxConfig` from `@sodax/types` / `@sodax/sdk` are packaged-default snapshots and silently miss both `await sodax.config.initialize()` updates and `new Sodax(config)` overrides.
+
+### Top traps, conventions, verification
+
+The DO / DO NOT / verification checklist lives in [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — read it before writing any call site. The biggest source of generated v1-style code is skipping it.
+
+---
+
+## Migration mode (v1 → v2 porting)
+
+Pick this mode when the consumer has **existing v1 SDK code** that needs to compile against v2. Common signals (grep for these):
+
+```bash
+grep -rE '_MAINNET_CHAIN_ID\b|\bSpokeProvider\b|\bxChainId\b|\bSpokeChainId\b|hubAssets|moneyMarketSupportedTokens' src/
+grep -rE 'instanceof (MoneyMarketError|IntentError|StakingError|BridgeError|MigrationError|AssetServiceError|ConcentratedLiquidityError|RelayError)' src/
+```
+
+If the consumer has v1 fingerprints AND also wants new features: **do migration first**.
+
+### 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. **Read first** — prevents the most common porting mistakes.
+2. Read [`migration-v1-to-v2/knowledge/README.md`](./migration-v1-to-v2/knowledge/README.md) — overview, reading order, cross-cutting checklist, v1↔v2 glossary.
+3. **Cross-cutting first.** In order:
+   - [`breaking-changes/type-system.md`](./migration-v1-to-v2/knowledge/breaking-changes/type-system.md) — renames at `@sodax/types`, `ChainKeys`, `WalletProviderSlot`, `RpcConfig`, `IConfigApi` Result.
+   - [`breaking-changes/architecture.md`](./migration-v1-to-v2/knowledge/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`, relay reshape.
+   - [`breaking-changes/result-and-errors.md`](./migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md) — throws → `Result<T>`; module errors → `SodaxError<C>`; v1↔v2 code crosswalk.
+4. **Per-feature playbooks** under [`features/`](./migration-v1-to-v2/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `backend-api.md` — read only the ones the consumer uses.
+5. **Codemods + adapters** for mechanical replacement → [`recipes.md`](./migration-v1-to-v2/knowledge/recipes.md).
+6. **Cross-check** symbols in [`reference/`](./migration-v1-to-v2/knowledge/reference/) — `deleted-exports.md`, `error-code-crosswalk.md`, `return-shapes.md`, `sodax-config.md`.
+
+### Mechanical type renames (do these first)
+
+Apply in this order — type-level changes don't affect behavior; runtime patterns require thinking.
+
+| v1 | v2 | Codemod |
+|---|---|---|
+| `*_MAINNET_CHAIN_ID` | `ChainKeys.*_MAINNET` | regex `(\w+)_MAINNET_CHAIN_ID` → `ChainKeys.$1_MAINNET` |
+| `XToken.xChainId` (and tokens-likes) | `XToken.chainKey` | field rename |
+| `SpokeChainId` / `ChainId` | `SpokeChainKey` | type rename |
+| `Token` | `XToken` | type rename |
+| `AddressType` (BTC) | `BtcAddressType` | only at `@sodax/types` import sites |
+
+Then on every signed-call payload: drop `spokeProvider`, add `walletProvider`, add `raw: false` discriminator, rename `intentParams` → `params`. Plus add `srcChainKey` + `srcAddress` to every action params object (MM, staking, deposit, …).
+
+### Top traps, DO NOT, verification
+
+The full DO / DO NOT list, mode-specific pitfalls, and verification protocol live in [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — read it before touching any call site. Highest-leverage rule: every `await sodax.<feature>.<method>(...)` call site must have `if (!result.ok)` branching.
+
+---
+
+# Related skills
+
+- `sodax-wallet-sdk-core` — set up a wallet provider for signing flows (integration mode) or upgrade an existing wallet-sdk-core surface (migration mode).
+- `sodax-dapp-kit` — React hooks wrapping this SDK.
+- `sodax-wallet-sdk-react` — React wallet connectivity layer.

package/skills/sodax-sdk/backend-api/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sodax-sdk-backend-api
+description: 'Granular skill for the @sodax/sdk v2 BackendApiService — HTTP client to the SODAX backend for intent lookup, swap-tx submission, solver orderbook, money-market position/reserve reads, and (internally) config fetching. Use when the task touches a backend read or write (e.g. "submit swap tx to Sodax backend", "Sodax getIntentByHash", "fetch money market position from Sodax backend", "Sodax orderbook", "Sodax BackendApiService", "implement custom IConfigApi sandbox"). Covers BOTH integration and the load-bearing v1 → v2 Result-wrapping migration. Skill links into the parent sodax-sdk knowledge tree.'
+---
+
+# Backend API (Core SDK granular skill)
+
+Granular skill for `BackendApiService` — `sodax.backendApi`. HTTP client used by every feature for reads + swap-tx submission. **Feature tag for errors** varies by call site (e.g. `'swap'` for `submitSwapTx`, `'moneyMarket'` for MM reads); errors always carry `error.context.api: 'backend'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?** Note: v2's load-bearing change is `Result`-wrapping every method (v1 threw on failure).
+2. **Which category?**
+   - **Swap-related reads / writes:** `submitSwapTx`, `getSubmitSwapTxStatus`, `getOrderbook`, `getIntentByHash`, `getIntentByTxHash`, `getUserIntents`.
+   - **Money-market position reads:** `getMoneyMarketPosition`, `getAllMoneyMarketAssets`, `getMoneyMarketAsset`, `getMoneyMarketAssetBorrowers`, `getMoneyMarketAssetSuppliers`, `getAllMoneyMarketBorrowers`.
+   - **Config-API methods (implements `IConfigApi`):** `getAllConfig`, `getChains`, `getSwapTokens`, `getSwapTokensByChainId`, `getMoneyMarketTokens`, `getMoneyMarketReserveAssets`, `getMoneyMarketTokensByChainId`, `getRelayChainIdMap`.
+3. **Custom `IConfigApi` for sandbox / fixtures?** Every method must return `Promise<Result<T>>` in v2.
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md) — `BackendApiService` API + `submitSwapTx` call shape + custom-backend pattern.
+3. For the `submitSwapTx` + `createIntent` flow → also load [`../swap/SKILL.md`](../swap/SKILL.md) or read [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) § "Backend submit-tx flow".
+4. Errors carry `error.context.api === 'backend'` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Backend-API-specific anti-patterns
+
+- **Passing the `RelayExtraData` object** to `submitSwapTx.relayData`. The field is now `string` — pass `relayData.payload`.
+- **Using v1 `srcChainId` (numeric)** on `SubmitSwapTxRequest`. Renamed to `srcChainKey: SpokeChainKey`.
+- **Implementing `IConfigApi` with throw-on-error semantics.** v2 interface requires `Promise<Result<T>>` — every method.
+- **Reading money-market position from `MoneyMarketService`.** Those reads live here on `BackendApiService`.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/backend-api.md`](../migration-v1-to-v2/knowledge/features/backend-api.md) — the load-bearing change: every method now returns `Promise<Result<T>>`. Includes the `submitSwapTx` request-shape changes (`srcChainId` → `srcChainKey`, `relayData` object → string) and the `IConfigApi` sandbox-impl change.
+3. Cross-cutting `IConfigApi` Result-wrapping note → [`../migration-v1-to-v2/knowledge/breaking-changes/type-system.md`](../migration-v1-to-v2/knowledge/breaking-changes/type-system.md) § 6.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.backendApi.<method>(...)` has `if (!result.ok)`.
+3. `SubmitSwapTxRequest` uses `srcChainKey` (not `srcChainId`) and `relayData: relayData.payload` (string).
+4. Any custom `IConfigApi` implementation returns `Promise<Result<T>>` from every method.
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — `submitSwapTx` is the backend half of the step-by-step swap flow.
+- [`../money-market/SKILL.md`](../money-market/SKILL.md) — `BackendApiService` is the canonical source of MM position reads.
+- [`../partner/SKILL.md`](../partner/SKILL.md), [`../recovery/SKILL.md`](../recovery/SKILL.md) — diagnostics for failures via intent / tx lookups.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/bridge/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sodax-sdk-bridge
+description: 'Granular skill for the @sodax/sdk v2 bridge feature only — cross-chain token transfer via vault. Use when the task is specifically bridging (e.g. "bridge tokens cross-chain with Sodax", "Sodax bridge", "transfer USDC from Arbitrum to Stellar via Sodax", "check bridgeable amount"). The bridge() method returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for every cross-chain mutation. Covers BOTH integration (new v2 code) and migration (port v1 BridgeService). Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
+---
+
+# Bridge (Core SDK granular skill)
+
+Granular skill for `BridgeService` — `sodax.bridge`. Feature tag: `'bridge'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Signed flow (frontend) or unsigned-tx (backend)?**
+3. **Need a bridgeable-amount precheck?** Vault deposit limits may cap the transfer; `getBridgeableAmount` (or equivalent) read tells you the cap before submitting.
+4. **Source / destination chains** — confirm both are supported spoke chains, and the destination address format matches the chain (vd Stellar address starts with `G`, Solana base58, Bitcoin specific encodings).
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — API surface, `TxHashPair` return shape, bridgeable-amount reads.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Destination-chain quirks (Stellar trustline, BTC PSBT, Solana PDA) → [`../integration/knowledge/chain-specifics.md`](../integration/knowledge/chain-specifics.md).
+5. Errors (`feature: 'bridge'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Bridge-specific anti-patterns
+
+- **Destructuring the return as an array or single hash.** v2 ALWAYS returns `{ srcChainTxHash, dstChainTxHash }` for cross-chain mutations — destructure by name.
+- **Skipping the bridgeable-amount check.** Submitting an amount over the vault cap returns `EXECUTION_FAILED`; cheaper to check first.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — v1 `bridge()` returned a string; v2 returns `TxHashPair`. Update all destructuring sites.
+3. v1 `BridgeError` → v2 `SodaxError<C>` with `feature: 'bridge'`.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.bridge.<method>(...)` has `if (!result.ok)`.
+3. No string-typed return destructuring at `bridge()` call sites.
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — for intent-based cross-chain swaps (different from a direct bridge: swap goes via a solver).
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — `RecoveryService` for stuck assets on the hub.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/dex/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sodax-sdk-dex
+description: 'Granular skill for the @sodax/sdk v2 DEX feature only — Uniswap-V3-style concentrated liquidity positions on the hub, plus AssetService for hub-asset deposit/withdraw. Use when the task is LP positions (e.g. "Sodax concentrated liquidity", "create LP position on Sodax", "increase liquidity", "decrease liquidity", "claim LP fees", "deposit hub assets for LP"). Covers BOTH integration and migration. Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
+---
+
+# DEX (Core SDK granular skill)
+
+Granular skill for `DexService` — facade owning `clService: ClService` (concentrated liquidity) and `assetService: AssetService` (hub-asset deposit/withdraw). Access via `sodax.dex.clService` and `sodax.dex.assetService`. Feature tag for errors: `'dex'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which operation?**
+   - LP: `createPosition`, `increaseLiquidity`, `decreaseLiquidity`, `claimFees`, `closePosition`.
+   - Assets: `deposit` (spoke → hub-asset wrapper), `withdraw` (hub → spoke).
+3. **Does the position require an asset deposit first?** LP positions hold hub assets; the user must deposit from a spoke chain before opening a position.
+4. **Signed or unsigned-tx flow?**
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/dex.md`](../integration/knowledge/features/dex.md) — `ClService` + `AssetService` APIs, position lifecycle, tick math notes.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Errors (`feature: 'dex'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### DEX-specific anti-patterns
+
+- **Reaching for `sodax.cl` / `sodax.assets`.** Wrong paths — both services are reached via `sodax.dex` (i.e. `sodax.dex.clService.*` and `sodax.dex.assetService.*`). The `Sodax` facade exposes only `dex`.
+- **Skipping `assetService.deposit` before opening a position.** LP positions reference hub-asset addresses; without deposit there's nothing to provide.
+- **Confusing pool addresses on Sonic with spoke token addresses.** CL pools live on Sonic; the user-facing tokens live on spokes.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/dex.md`](../migration-v1-to-v2/knowledge/features/dex.md) — v1 `ConcentratedLiquidityError` / `AssetServiceError` → v2 `SodaxError<C>` with the appropriate `feature` tag.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.dex.clService.<method>(...)` and `await sodax.dex.assetService.<method>(...)` has `if (!result.ok)`.
+3. No `instanceof ConcentratedLiquidityError` / `AssetServiceError`.
+
+## Related granular skills (same family)
+
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — `RecoveryService` for stuck hub-wallet LP assets.
+- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `BackendApiService` for position reads if surfaced there.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/integration/knowledge/README.md

@@ -0,0 +1,43 @@
+# Integration — `@sodax/sdk` v2
+
+This tree documents v2 of the SDK for **new consumers** building against it. If you're porting v1 code, start at [`README.md`](../../migration-v1-to-v2/knowledge/README.md) instead.
+
+## Files in this tree
+
+| File | What's in it |
+|---|---|
+| [`quickstart.md`](quickstart.md) | Install, initialize a `Sodax` instance, and the top init/setup errors and how to fix them. Covers reads (no wallet), raw-tx flows (no wallet), and signed flows (consumer-supplied wallet provider). |
+| [`architecture.md`](architecture.md) | Every v2 design concept the SDK rests on, in a single TOC-navigable file: hub-and-spoke model, `SpokeService` router, `Sodax` facade + `ConfigService`, `ChainKeys`, `WalletProviderSlot<K, Raw>`, `Result<T>`, `SodaxError<C>` + 13-code vocabulary, relay layer (`mapRelayFailure`, `relayTxAndWaitPacket`). |
+| [`features/swap.md`](features/swap.md) | `SwapService`: intent-based swaps via the solver — `createIntent`, `swap`, `postExecution`, limit orders, `cancelIntent`. |
+| [`features/money-market.md`](features/money-market.md) | `MoneyMarketService`: cross-chain lending/borrowing — supply, borrow, withdraw, repay, reserves, allowance. |
+| [`features/staking.md`](features/staking.md) | `StakingService`: SODA → xSoda — stake, unstake, instant unstake, claim, cancel; ratio + info reads. |
+| [`features/bridge.md`](features/bridge.md) | `BridgeService`: cross-chain token transfer via vault — `bridge`, `createBridgeIntent`, `getBridgeableAmount`, `getBridgeableTokens`. |
+| [`features/dex.md`](features/dex.md) | `ClService` (concentrated liquidity) + `AssetService`: position lifecycle (mint/increase/decrease), claim rewards, asset deposit/withdraw. |
+| [`features/migration.md`](features/migration.md) | `MigrationService` (the SDK module): ICX, bnUSD, BALN sub-services + lock management. |
+| [`features/partner.md`](features/partner.md) | `PartnerService` — partner-fee handling. |
+| [`features/recovery.md`](features/recovery.md) | `RecoveryService` — withdraw stuck hub-wallet assets. |
+| [`features/backend-api.md`](features/backend-api.md) | `BackendApiService` — HTTP client for backend reads + swap-tx submission. |
+| [`recipes/`](recipes/) | Copy-pasteable patterns: SDK initialization, `Result` + error discrimination, raw-tx flow, signed-tx flow, chain-key narrowing + cast-at-boundary, testing (mocks/stubs), gas estimation, backend-server init. |
+| [`reference/`](reference/) | Lookup tables: 20-chain `ChainKeys` table with family + relay id, `I*WalletProvider` interfaces, 13 `SodaxErrorCode` meanings + per-feature narrow unions, public API surface (incl. `@sodax/types` re-export rule), glossary. |
+| [`chain-specifics.md`](chain-specifics.md) | Non-EVM quirks — Stellar trustline check/request, Bitcoin PSBT + Radfi auth/session, Solana PDA derivation, ICON Hana wallet + chain-key string, NEAR connector discovery. |
+
+## Reading order for a new integrator
+
+1. `quickstart.md` — get the SDK installed and a `Sodax` instance running.
+2. `architecture.md` — understand the type system (`ChainKeys`, `Result`, `WalletProviderSlot`, `SodaxError`) before writing call sites.
+3. `recipes/` — pick the patterns you need (signed vs raw, error handling, narrowing).
+4. `features/<x>.md` — read the file for the feature you're integrating.
+5. `chain-specifics.md` — only if you target a non-EVM chain; skip otherwise.
+6. `reference/` — keep open while writing for table lookups.
+
+## Cross-references to migration
+
+If your project also has v1 call sites, port them first using:
+
+- [`README.md`](../../migration-v1-to-v2/knowledge/README.md) — overview, reading order, and cross-cutting checklist.
+- [`breaking-changes/type-system.md`](../../migration-v1-to-v2/knowledge/breaking-changes/type-system.md) — type renames and shape changes you'll hit on import.
+- [`breaking-changes/architecture.md`](../../migration-v1-to-v2/knowledge/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService` replacing static lookups, relay flow reshape.
+- [`breaking-changes/result-and-errors.md`](../../migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md) — throws → `Result<T>` and module errors → `SodaxError<C>`, with the v1↔v2 code crosswalk.
+- [`features/`](../../migration-v1-to-v2/knowledge/features/) — per-feature playbooks in lockstep with the integration features here.
+
+The naming rule: **every feature 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.