@sodax/skills 2.0.0-rc.13 → 2.0.0-rc.15

package/.claude-plugin/plugin.json

@@ -1,43 +1,10 @@
 {
   "name": "sodax-skills",
   "skills": [
+    "./skills/sodax-build",
     "./skills/sodax-sdk",
-    "./skills/sodax-sdk/swap",
-    "./skills/sodax-sdk/money-market",
-    "./skills/sodax-sdk/bridge",
-    "./skills/sodax-sdk/staking",
-    "./skills/sodax-sdk/dex",
-    "./skills/sodax-sdk/leverage-yield",
-    "./skills/sodax-sdk/migration",
-    "./skills/sodax-sdk/partner",
-    "./skills/sodax-sdk/recovery",
-    "./skills/sodax-sdk/backend-api",
     "./skills/sodax-wallet-sdk-core",
-    "./skills/sodax-wallet-sdk-core/evm",
-    "./skills/sodax-wallet-sdk-core/solana",
-    "./skills/sodax-wallet-sdk-core/sui",
-    "./skills/sodax-wallet-sdk-core/bitcoin",
-    "./skills/sodax-wallet-sdk-core/stellar",
-    "./skills/sodax-wallet-sdk-core/icon",
-    "./skills/sodax-wallet-sdk-core/injective",
-    "./skills/sodax-wallet-sdk-core/near",
-    "./skills/sodax-wallet-sdk-core/stacks",
     "./skills/sodax-wallet-sdk-react",
-    "./skills/sodax-wallet-sdk-react/connect",
-    "./skills/sodax-wallet-sdk-react/wallet-modal",
-    "./skills/sodax-wallet-sdk-react/bridge-to-sdk",
-    "./skills/sodax-wallet-sdk-react/switch-chain",
-    "./skills/sodax-wallet-sdk-react/sign-message",
-    "./skills/sodax-wallet-sdk-react/walletconnect",
-    "./skills/sodax-dapp-kit",
-    "./skills/sodax-dapp-kit/swap",
-    "./skills/sodax-dapp-kit/money-market",
-    "./skills/sodax-dapp-kit/staking",
-    "./skills/sodax-dapp-kit/bridge",
-    "./skills/sodax-dapp-kit/dex",
-    "./skills/sodax-dapp-kit/leverage-yield",
-    "./skills/sodax-dapp-kit/migration",
-    "./skills/sodax-dapp-kit/bitcoin",
-    "./skills/sodax-dapp-kit/auxiliary-services"
+    "./skills/sodax-dapp-kit"
   ]
 }

package/AGENTS.md

@@ -2,9 +2,11 @@
 
 > Tool-neutral entry point. You are looking at the consumer-facing AI material for the `@sodax/*` SDKs. If you can read multiple `SKILL.md` files, load **2–3 skills** based on what the user is building (table below). Then follow each skill's internal workflow.
 
+> **Don't know what to build yet, or not a developer?** Load the **`sodax-build`** front-door skill first. It runs a guided interview, turns a vague idea into a product brief, and names the developer skill(s) to load next — it writes no app code. Skip it the moment an SDK, feature, or hook is already named, and route straight to the matching skill below.
+
 ## What's here
 
-This package ships **four mode-gated broad skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package — plus **nested granular skills** under every broad skill: `sodax-sdk` (one per Core SDK feature service), `sodax-dapp-kit` (one per dapp-kit feature domain), `sodax-wallet-sdk-core` (one per chain family), and `sodax-wallet-sdk-react` (one per connectivity concern). Each broad skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). Granular skills are single-file SKILL.md that link into their parent's knowledge tree. Skills are action-oriented (when to use, workflow, anti-patterns, links into knowledge); knowledge is the reference material your workflow points at. SKILL.md gates by mode at the top — pick integration or migration based on the consumer signal.
+This package ships **mode-gated broad SDK skills** (`skills/<name>/SKILL.md`, one per SODAX SDK package) and a cross-cutting **front-door / ideation skill** (`sodax-build`; flat `knowledge/`, no mode split, no granular children — see the callout above), plus **nested granular skills** under every broad skill: `sodax-sdk` (one per Core SDK feature service), `sodax-dapp-kit` (one per dapp-kit feature domain), `sodax-wallet-sdk-core` (one per chain family), and `sodax-wallet-sdk-react` (one per connectivity concern). Each broad skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). Granular skills are single-file SKILL.md that link into their parent's knowledge tree. The **installable units are the top-level skills registered in `.claude-plugin/plugin.json`** — installing a broad skill (e.g. `npx skills add … --skill sodax-sdk`) lands its full knowledge tree **and** all its nested granular SKILL.md files, so you "load a granular skill" by reading `skills/<broad>/<feature>/SKILL.md` from within the installed broad skill. (Granular skills are not installed standalone: they link up into the parent tree via `../`, which only resolves inside the broad skill.) Skills are action-oriented (when to use, workflow, anti-patterns, links into knowledge); knowledge is the reference material your workflow points at. SKILL.md gates by mode at the top — pick integration or migration based on the consumer signal.
 
 | SDK package | Broad skill | Granular per-feature skills |
 |---|---|---|
@@ -23,6 +25,7 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
 
 | Consumer is… | Load skills (mode) |
 |---|---|
+| **Not sure what to build / not a developer** (no SDK, feature, or concrete product chosen yet) | `sodax-build` (front-door ideation: interview → product brief → handoff; it names the dev skills to load next). Skip the moment any SDK / feature / hook is named |
 | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, backend-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
 | **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, leverage-yield, migration, bitcoin, auxiliary-services) | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit/<feature>` (granular, covers both modes via internal links). Skip the broad `sodax-dapp-kit` skill. If the wallet concern is also settled (just a connect button, modal, bridge, etc.), narrow to `sodax-wallet-sdk-react/<concern>` too |
 | **Scaffolding ONE chain's wallet provider** (backend/Node/non-React: evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks) | `sodax-wallet-sdk-core/<chain>` (granular, covers both modes) → `sodax-sdk/<feature>` for the operation it signs. Skip the broad `sodax-wallet-sdk-core` skill |
@@ -55,20 +58,21 @@ 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 (broad + nested granular paths)
-└── skills/                                # Each broad skill is mode-gated; some have nested granular children
+├── .claude-plugin/plugin.json             # Skill registry (source of truth) — broad SDK skills + registered meta skills (granular ship bundled inside broad skills)
+└── skills/                                # Broad skills are mode-gated with nested granular children; sodax-build is a flat front-door meta skill
+    ├── sodax-build/                       {SKILL.md, knowledge/ (flat)} — cross-cutting front-door / ideation skill; no mode split, no granular children
     ├── sodax-sdk/                         {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
-    │                                       <feature>/SKILL.md ×10 — swap, money-market, bridge, staking, dex,
+    │                                       <feature>/SKILL.md children — swap, money-market, bridge, staking, dex,
     │                                       leverage-yield, migration, partner, recovery, backend-api}
     ├── sodax-wallet-sdk-core/             {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
-    │                                       <chain>/SKILL.md ×9 — evm, solana, sui, bitcoin, stellar, icon,
+    │                                       <chain>/SKILL.md children — evm, solana, sui, bitcoin, stellar, icon,
     │                                       injective, near, stacks}
     ├── sodax-wallet-sdk-react/            {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/
-    │                                       (incl. 4 .tsx example apps under integration/knowledge/examples/),
-    │                                       <concern>/SKILL.md ×6 — connect, wallet-modal, bridge-to-sdk,
+    │                                       (incl. .tsx example apps under integration/knowledge/examples/),
+    │                                       <concern>/SKILL.md children — connect, wallet-modal, bridge-to-sdk,
     │                                       switch-chain, sign-message, walletconnect}
     └── sodax-dapp-kit/                    {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
-                                            <feature>/SKILL.md ×9 — swap, money-market, staking, bridge, dex,
+                                            <feature>/SKILL.md children — swap, money-market, staking, bridge, dex,
                                             leverage-yield, migration, bitcoin, auxiliary-services}
 ```
 
@@ -91,3 +95,94 @@ If the user is doing **DeFi work but explicitly NOT with SODAX** (e.g. "use Unis
 ## Feedback
 
 If an agent generates wrong code despite following a skill, that's a doc bug — file an issue at https://github.com/icon-project/sodax-sdks/issues with the prompt and the incorrect output. The package is structurally CI-guarded (frontmatter + link resolution); prose-level claims benefit from real-world feedback.
+
+## Maintaining this package
+
+The sections above are the consumer-facing router (shipped via npm + the `skills` CLI); the rest of this file is for maintainers editing this package. It contains **no runtime code** — it delivers agent-native documentation: short SKILL.md files (with YAML frontmatter) and long-form knowledge trees, one bundle per SDK package. The `migration-v1-to-v2/` subtree is named that (not `migration/`) to (a) avoid ambiguity with per-feature `features/migration.md` (ICX/bnUSD token migration) and (b) future-proof for a hypothetical `migration-v2-to-v3/`.
+
+### Granular skills
+
+Each broad skill has **nested granular skills** at `skills/<broad>/<sub-domain>/SKILL.md`. The split axis differs per package — pick whatever the consumer decides upfront and whatever maps 1:1 to a coherent slice of the broad knowledge tree:
+
+- `sodax-sdk` — one per Core SDK feature service.
+- `sodax-dapp-kit` — one per dapp-kit feature domain, matching the feature-knowledge filenames.
+- `sodax-wallet-sdk-core` — one per chain family. The axis is chain, not feature; hooks/services are uniform across chains while per-chain config, methods, and gotchas differ.
+- `sodax-wallet-sdk-react` — one per connectivity concern, each backed by a dedicated integration recipe.
+
+They exist so agents can load just one workflow (~3 KB) instead of the whole broad SKILL.md (~13 KB) plus its broad knowledge index.
+
+Granular skills are **one file each** (`<sub-domain>/SKILL.md`). They do **NOT** ship their own `integration/knowledge/` or `migration-v1-to-v2/knowledge/` subtrees — they link directly into the parent broad skill's knowledge tree (`../integration/knowledge/features/<feature>.md`, `../integration/knowledge/recipes/<recipe>.md`, etc.).
+
+**Granular skills are bundled, not separately published.** `plugin.json` registers **only the top-level skills** (the broad SDK skills plus the registered meta skill). Each broad skill's directory already contains its nested granular `SKILL.md` files, so installing a broad skill (e.g. `npx skills add … --skill sodax-sdk`) lands every granular file alongside the knowledge tree; the broad SKILL.md's "prefer a granular skill" table then links to `./swap/SKILL.md` etc., which resolve in the consumer's install. Granular skills are deliberately **not** registered because they are not self-contained: a granular `SKILL.md` links **up** into its parent's tree (`../integration/knowledge/...`), and the `skills` CLI copies only a skill's own directory — so installing a granular skill standalone would leave every `../knowledge` link dangling. Keeping the registry to the top-level skills also concentrates skills.sh install telemetry (which drives search ranking) instead of diluting it across the many bundled granular rows. To add a new granular skill, drop a `<feature>/SKILL.md` into the broad skill dir — do **not** add it to `plugin.json`.
+
+**Family rule:** every granular skill shares its parent broad skill's family. Family is the broad-skill name (`sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`). Cross-family clickable links remain forbidden; intra-family links (broad ↔ granular, granular ↔ granular within the same broad parent) are explicitly allowed.
+
+### Meta / ideation skills (cross-cutting front door)
+
+`sodax-build` is a **deliberately different category** from the per-package SDK skills — a single cross-cutting "front-door" skill that sits *upstream* of them. A non-technical or undecided user loads it first; it runs a guided interview, produces a product brief, and hands off to the dev skills by name. It writes no app code.
+
+Three deliberate exemptions distinguish it from a broad skill — all intentional, not drift:
+
+- **It is not a `sodax-<pkg>` skill.** It maps to no SDK package and has no granular children. Its "family" (for the cross-package link check) is `build`.
+- **No integration/migration split — a flat `knowledge/` tree.** There is no v1→v2 axis for ideation. `check-skills.sh` 5b (which requires both mode subtrees) iterates only `EXPECTED_BROAD_SKILLS`, so the meta skill is exempt; it is registered + frontmatter-validated via a separate `EXPECTED_META_SKILLS` allowlist in 5a.
+- **Dev-skill references are prose-only.** Because its family is `build`, ANY clickable link or GitHub URL into `sodax-sdk` / `sodax-dapp-kit` / `sodax-wallet-sdk-core` / `sodax-wallet-sdk-react` would trip the cross-package check. It names the dev skills in prose (backticks) only, and links exclusively within its own `knowledge/`.
+
+**Self-contained but grounded.** The skill needs no network to run, but its facts are derived from repo source. Qualitative facts (what a feature does, the intent/solver swap model) are baked in; enumerable/exact values (chain lists, token symbols, fee caps) are NOT — each grounded knowledge file carries a "Source & freshness" header telling the agent to fetch the canonical `packages/types/...` / `packages/sdk/...` source before quoting exact values. Citing those source paths is CI-safe: the cross-package URL check only forbids URLs into `packages/skills/skills/sodax-<pkg>/...`.
+
+**Evals.** A trigger-regression corpus lives at `scripts/_evals/sodax-build.json` — deliberately **outside** the shipped `skills/` tree so it is never copied into a consumer's install (`package.json` `files` excludes `scripts/`). Not a CI gate today; a fixture for future automated trigger testing.
+
+To add another meta skill later: drop `skills/<name>/SKILL.md` + a flat `knowledge/`, register it in `plugin.json`, and add it to `EXPECTED_META_SKILLS` in `scripts/check-skills.sh`.
+
+### Separation of concerns
+
+- **Skills are action-oriented**: workflow, anti-patterns, decision points, links into knowledge. Body should fit in an agent's working context. Keep each SKILL.md short.
+- **Knowledge is reference-oriented**: feature playbooks, recipe-style how-tos, reference tables (chain keys, error codes, hook signatures). Long-form, indexed by skill workflow steps. Do **not** duplicate knowledge inside SKILL.md.
+- **AGENTS.md is the router**: consumer states their task → AGENTS.md tells the agent which skills to load. Replaces the per-package `ai-exported/AGENTS.md` entries that used to live inside each SDK package.
+
+### Editing rules
+
+- **SKILL.md frontmatter is load-bearing.** For a broad top-level skill at `skills/<broad>/SKILL.md`, `name` must equal the directory basename (e.g. `name: sodax-sdk`). For a nested granular skill at `skills/<broad>/<feature>/SKILL.md`, `name` must equal `<broad>-<feature>` (e.g. `name: sodax-sdk-swap`) — namespaced so each granular name stays unique and never collides with its parent (these names are still validated even though granular skills are bundled, not registered). `description` triggers selection — write it concretely with explicit trigger phrases (the agent looks at description alone to decide whether to load the skill). See existing skills for examples.
+- **`description:` MUST be a single-quoted YAML scalar.** The [`vercel-labs/skills` CLI](https://github.com/vercel-labs/skills) parses frontmatter with strict YAML 1.2 — a plain (unquoted) scalar that contains `: ` (colon-space, the YAML mapping indicator) fails to parse and the skill is silently skipped at install time. Wrap every description in single quotes (`description: '...'`), doubling any apostrophe inside (`'` → `''`). Block scalars (`>-`) are also valid YAML but churn diffs and change rendering — prefer single quotes. The `check:ai-structural` validator parses each frontmatter through a real YAML parser to catch violations; it's stricter than the bash-grep check it replaced for exactly this reason.
+- **Optional frontmatter: `license` + `metadata`.** Beyond the required `name` / `description`, every SKILL.md also carries `license: MIT` (matches `package.json`) and a `metadata` block with `version` and `author: sodax`. These are the portable optional fields the [`vercel-labs/skills` CLI](https://github.com/vercel-labs/skills) and skills.sh understand (`metadata` is free-form k/v; `version` conventionally tracks semver). **Quote the version** (`version: '0.0.1'`) — an unquoted two-segment value like `1.0` would parse as the YAML number `1`. Keep `metadata.version` in lockstep with `package.json`'s `version` — bump both together at release. The fields are additive; `check:ai-structural` only asserts `name` / `description` and does not whitelist, so extra keys are safe.
+- **Skills link into knowledge by relative path.** From a SKILL.md, target paths look like `./integration/knowledge/ai-rules.md` or `./migration-v1-to-v2/knowledge/README.md`. Cross-mode links (between the two subtrees of the same skill) use a `<other-mode>/knowledge/<target>` segment, prefixed by `../` repeated enough times to climb out of the source subtree: depth-0 knowledge files (e.g. `<mode>/knowledge/README.md`, `quickstart.md`) use a `../../` prefix; depth-1 files (e.g. `<mode>/knowledge/features/*.md`, `<mode>/knowledge/recipes/*.md`) use `../../../`. The `check-skills.sh` validator verifies all resolve.
+- **Cross-SDK-package references are forbidden.** A skill MUST NOT link to (or cite a relative/absolute path into) a skill belonging to a different SDK package **family** (`sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`). Concretely: `sodax-dapp-kit` knowledge MUST NOT reference `sodax-sdk`, `sodax-wallet-sdk-react`, or `sodax-wallet-sdk-core` content via `../../<other-skill>/...`, GitHub URLs, or any other clickable form. Use prose pointers naming the sibling skill instead (e.g., *"load the `sodax-sdk` skill (integration mode)"*). **Intra-family links are allowed**: integration ↔ migration-v1-to-v2 subtrees within the SAME broad skill, broad ↔ granular within the same family (e.g. `sodax-sdk` ↔ `sodax-sdk/swap`), and granular ↔ granular under the same broad parent. These all ship together and document the same SDK package.
+- **Knowledge files** retain the structure they had under each package's `ai-exported/<mode>/` tree: `README.md`, `ai-rules.md`, `features/`, `recipes/`, `reference/`, plus `architecture.md`, `quickstart.md`, `chain-specifics.md`, and `breaking-changes/` where applicable. New files go under whichever subdirectory fits; both skills and knowledge are expected to evolve as the SDK does.
+- **No `bin`, no build, no runtime TypeScript** in this package — markdown only. `tsc` ships as a devDep purely so the validator scripts can typecheck doc fixtures. `pnpm --filter @sodax/skills check:ai` is the local validation gate; CI runs the same thing via the existing `check:ai` turbo task.
+
+### Conventions inherited from the old `ai-exported/` tree
+
+- Two modes per SDK package, encoded as subtrees inside a single skill: `migration-v1-to-v2/knowledge/` (v1 → v2 reference, renames, mechanical port recipes) and `integration/knowledge/` (pure v2 reference, idiomatic patterns, public API surface). SKILL.md mode-gates by consumer signal.
+- v1 mentions belong in `migration-v1-to-v2/knowledge/`. `integration/knowledge/` text stays pure v2 — no historicizing prose, no "this replaces the old X" callouts. Cross-link to `migration-v1-to-v2/knowledge/` when an agent might carry forward a v1 idiom.
+- Out of scope for either subtree: workflow scripts (`find | xargs perl -i -pe …` — tooling preference), app-specific references (`apps/web`, `apps/demo`), integrator code design, generic engineering hygiene unrelated to a specific SDK API behavior.
+
+### Validation
+
+```bash
+pnpm --filter @sodax/skills check:ai
+```
+
+Chains six sub-scripts. Each catches a distinct bug class — green guards together prove syntactic + structural correctness, but **NOT** prose-level accuracy.
+
+| Sub-script | What it enforces | Source of truth | Opt-out |
+|---|---|---|---|
+| `check:ai-structural` | `.claude-plugin/plugin.json` parses and registers exactly the expected broad SDK skills + meta skills (the `EXPECTED_*` arrays in `check-skills.sh` are the source of truth); every SKILL.md (broad + bundled granular + meta) has valid `name:` / `description:` frontmatter; no orphan top-level skill dirs; every relative `.md` link resolves. | this package's filesystem | none — structural |
+| `check:ai-imports` | Every `import … from '@sodax/<pkg>'` statement in `skills/sodax-<pkg>/{integration,migration-v1-to-v2}/knowledge/**/*.md` + each SDK package's README/AGENTS.md typechecks against `packages/<pkg>/src/index.ts`. Catches deleted / renamed exports. | `packages/<pkg>/src/index.ts` via fixture tsconfig `paths` | none |
+| `check:ai-snippets` | Every fenced ts/tsx code block in `skills/sodax-{dapp-kit,wallet-sdk-react}/{integration,migration-v1-to-v2}/knowledge/**/*.md` typechecks against the real SDK. Catches call-shape drift. Pattern-style blocks can opt out with the marker; real working examples still validate. | same as imports, plus `_ai-snippets-fixture/_preamble.d.ts` ambients | `// @ai-snippets-skip` as first content line of the block |
+| `check:ai-tsx-examples` | Every standalone `.tsx` file under `skills/sodax-<pkg>/integration/knowledge/examples/` typechecks as a complete module against the live `src/`. Catches export drift, hook-shape drift, and renamed-param drift in runnable user-facing examples. | each SDK package's `src/index.ts` (and `xchains/*` sub-paths for wallet-sdk-react) via fixture tsconfig `paths` | none — illustrative blocks live in `.md` via `@ai-snippets-skip`; `integration/knowledge/examples/` is for runnable code only |
+| `check:ai-keys` | Every `queryKey: [...]` / `mutationKey: [...]` literal in `skills/sodax-dapp-kit/{integration,migration-v1-to-v2}/knowledge/**/*.md` has a matching prefix in `packages/dapp-kit/src/hooks/**/*.ts`. Catches `'stakingInfo'` vs `'info'`-style drift. | `packages/dapp-kit/src/hooks/**/*.ts` | `<!-- ai-keys-allow -->` or `// ai-keys-allow` within 3 preceding lines |
+| `check:ai-consistency` | Every polling-interval claim ("polls 3s") near a `useFoo` mention matches the source `refetchInterval` for that hook. | same as keys | `<!-- ai-consistency-allow -->` within 6 preceding lines |
+
+Run individually for faster feedback: `pnpm run check:ai-imports`, `pnpm run check:ai-keys`, etc.
+
+### Distribution
+
+Two paths:
+
+1. **GitHub-based via the [`skills` CLI](https://github.com/vercel-labs/skills)** (primary): `npx skills@latest add icon-project/sodax-sdks/packages/skills`. Drops skills into the consumer's repo through the CLI-supported agent targets.
+2. **npm** (fallback for web chats / unsupported tools): `pnpm add -D @sodax/skills`. Consumers point their agent at `node_modules/@sodax/skills/AGENTS.md`.
+
+The `files` field in `package.json` controls the npm-shipped surface (`.claude-plugin`, `skills`, `AGENTS.md`, `README.md`). Knowledge ships inside each skill, so it travels with `skills/`.
+
+### Release
+
+Published via `.github/workflows/sodax-skills-publish.yml`, triggered by `@sodax/skills@x.y.z` git tag (same convention as the other `@sodax/*` packages).

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
 ```
 
-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.
+The installable skills listed in `.claude-plugin/plugin.json` land in your repo — the `sodax-build` front-door / ideation skill plus the mode-gated per-SDK-package skills (each with two knowledge subtrees: `integration/` for new v2 code, `migration-v1-to-v2/` for v1→v2 porting) — alongside 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,8 +21,9 @@ Four mode-gated skills land in your repo (under `.claude/skills/` or wherever th
 
 | Bundle | Contains |
 |---|---|
-| **4 mode-gated skills** under `skills/sodax-<pkg>/SKILL.md` | One skill per SODAX SDK package. `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. Each SKILL.md gates by mode (integration vs migration) at the top of the body. |
-| **Granular skills** under `skills/sodax-<pkg>/<sub-domain>/SKILL.md` | Every broad skill ships focused single-domain children: `sodax-sdk` / `sodax-dapp-kit` per feature (swap, money-market, bridge, staking, dex, …); `sodax-wallet-sdk-core` per chain (evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks); `sodax-wallet-sdk-react` per connectivity concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect). Load one when the task is already scoped to a single sub-domain — it points at exactly the knowledge files for it instead of the whole broad skill. |
+| **Front-door skill** at `skills/sodax-build/SKILL.md` | A cross-cutting ideation skill for when you don't know what to build yet. It interviews you, turns the idea into a product brief, and hands off to the right developer skill(s). Writes no app code; flat `knowledge/` tree (no integration/migration split). |
+| **Mode-gated per-SDK-package skills** under `skills/sodax-<pkg>/SKILL.md` | One skill per SODAX SDK package. `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. Each SKILL.md gates by mode (integration vs migration) at the top of the body. |
+| **Granular skills** bundled inside each broad skill at `skills/sodax-<pkg>/<sub-domain>/SKILL.md` | Every broad skill ships focused single-domain children: `sodax-sdk` / `sodax-dapp-kit` per feature (swap, money-market, bridge, staking, dex, …); `sodax-wallet-sdk-core` per chain (evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks); `sodax-wallet-sdk-react` per connectivity concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect). They install **with** their parent broad skill (not as separate packages); once installed, load one when the task is already scoped to a single sub-domain — it points at exactly the knowledge files for it instead of the whole broad skill. |
 | **Knowledge** under `skills/sodax-<pkg>/{integration,migration-v1-to-v2}/knowledge/` | Long-form supporting docs — features, recipes, reference tables, breaking-change writeups, code examples. Each skill ships both mode subtrees so `npx skills add` copies the full reference together. |
 | **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right skill + mode. |
 
@@ -34,6 +35,7 @@ After install, your agent picks based on what you're building. Quick guide:
 
 | You're building | Load these skills (mode) |
 |---|---|
+| Not sure what to build yet / not a developer | `sodax-build` — it interviews you, writes a product brief, and names the skill to load next |
 | 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) |

package/package.json

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

package/skills/sodax-build/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: sodax-build
+description: 'FRONT DOOR / IDEATION (no code) — start here when someone wants to build on SODAX but has not yet picked an SDK, feature, or even a concrete idea. Senses the audience tier (non-technical vs semi-technical), runs a guided interview, and turns a vague goal into a PRODUCT BRIEF (problem, the SODAX capabilities + chains that enable it, partner-fee monetization, phased scope) plus a HANDOFF that names the exact developer skill(s) to load next and the scaffolding steps. It STOPS before writing app code — it routes to the dev skills, it does not replace them. Triggers on "what can I build on SODAX", "I have an idea but I am not a developer", "help me plan a cross-chain app", "is SODAX right for my idea", "how would I monetize this", "turn my idea into a spec", "where do I start with SODAX". Do NOT load when the consumer already names an SDK, feature, hook, or symbol (useSwap, @sodax/dapp-kit, walletProvider, MoneyMarketService, Sodax, ChainKeys) — the what is already decided; route straight to sodax-sdk / sodax-dapp-kit / sodax-wallet-sdk-core / sodax-wallet-sdk-react and skip the interview. Links ONLY into its own knowledge/ subtree; references the developer skills by name in prose, never by path.'
+license: MIT
+metadata:
+  version: '0.0.1'
+  author: sodax
+---
+
+# sodax-build — front door for building on SODAX
+
+You are the **ideation layer** that sits upstream of the developer skills (see the package `AGENTS.md` router). Your job: take a person who knows *what they want* but not *which SODAX feature or SDK does it*, and produce a **product brief** + a **handoff** that names the next skill to load. You **do not write app code** — you route to the skills that do.
+
+SODAX is **cross-chain DeFi** on a hub-and-spoke model (Sonic is the hub). **Its defining strength is moving value *across* chains** — swapping or bridging between different chains, lending/borrowing cross-chain — so steer ideas toward that cross-chain edge first; it is the main reason to pick SODAX over a single-chain protocol. Other plain-English capabilities: stake, provide liquidity, migrate legacy tokens, take a partner fee, recover stuck funds. The catalog in [`knowledge/feature-catalog.md`](./knowledge/feature-catalog.md) maps each to what an end-user can *do*.
+
+---
+
+## 0. STOP gate — do not hijack a developer who already decided
+
+**Run this check before anything else.** If the user's message already names a concrete SDK, feature, hook, or symbol, the *what* is decided — they need a dev skill, not an interview. **Do not run the interview. Route immediately** and say which skill to load.
+
+| The user already said… | Do NOT interview — route to (prose name, load it directly) |
+|---|---|
+| `useSwap`, `useXxx` hook, `@sodax/dapp-kit`, "React dapp + dapp-kit" | `sodax-dapp-kit` (+ `sodax-wallet-sdk-react`) |
+| `Sodax`, `ChainKeys`, `Result<T>`, `SodaxError`, "backend / bot / script with @sodax/sdk" | `sodax-sdk` |
+| `walletProvider`, `IEvmWalletProvider`, "sign on <chain>", a specific chain provider | `sodax-wallet-sdk-core` |
+| "connect button", "wallet modal", "switch chain", WalletConnect | `sodax-wallet-sdk-react` |
+| A named feature already chosen (swap / money market / staking / bridge / dex / migration / partner / recovery) **with** an SDK in mind | the matching dev skill above |
+
+When in doubt about whether the *what* is decided, ask **one** question: *"Do you already know which SODAX feature you want, or are we still figuring that out?"* — decided → route; not decided → interview.
+
+---
+
+## 1. When to use this skill
+
+Use `sodax-build` when **the product is not yet defined**:
+
+- "What can I build on SODAX?" / "Is SODAX right for my idea?"
+- "I have an idea but I am not a developer / not sure where to start."
+- "Help me plan a cross-chain app" / "turn my idea into a spec."
+- "How would I make money from this?" (monetization is undecided)
+
+If instead the user is mid-build, debugging, or naming APIs → see the STOP gate above.
+
+## 2. Tier-gate — sense the audience first
+
+Your **first interview action** is to set a tier that controls vocabulary and question depth. Detect it from the user's own words; re-check as you go (if a non-coder suddenly pastes code, lift the tier; if a "developer" asks "what is a wallet?", lower it).
+
+- **Tier A — non-coder:** product/business language only. Gloss every DeFi term on first use (see [`knowledge/glossary.md`](./knowledge/glossary.md)). Offer recommended defaults to confirm rather than open questions.
+- **Tier B — semi-technical:** comfortable with apps/APIs, shaky on DeFi. Gloss a term once, then use it.
+- **Tier C — developer:** shorten the interview hard; they likely trip the STOP gate. Skip glossing.
+
+## 3. Interview workflow (in order)
+
+Drive the interview from the knowledge files — do not improvise the question tree:
+
+1. Read [`knowledge/interview-guide.md`](./knowledge/interview-guide.md) — the tiered, branching question tree (Stage 0–5) and the plain-English goal → feature mapping.
+2. Ground each answer against [`knowledge/feature-catalog.md`](./knowledge/feature-catalog.md) and [`knowledge/use-case-gallery.md`](./knowledge/use-case-gallery.md).
+3. Confirm chains/assets against [`knowledge/chains-and-assets.md`](./knowledge/chains-and-assets.md) — honesty-gate anything unsupported; fetch live source before quoting exact chain/token lists.
+4. Frame monetization against [`knowledge/monetization.md`](./knowledge/monetization.md) — partner fees only; treat exact caps as policy-sensitive and fetch live before quoting numbers.
+5. Assemble the brief using [`knowledge/brief-template.md`](./knowledge/brief-template.md).
+6. Produce the handoff using [`knowledge/handoff.md`](./knowledge/handoff.md).
+
+For a worked end-to-end illustration, see [`knowledge/example-sessions.md`](./knowledge/example-sessions.md) — two sample transcripts (a Tier-A and a Tier-C session).
+
+Interview rules (from the guide): **one question at a time**; always offer a recommended default; reflect the goal back in the user's own words; converge on **one** Phase-1 goal (+≤1 secondary) to avoid over-scoping; end with a short plain-bullet **playback** and a single confirmation before writing the brief.
+
+## 4. What you produce / where you stop
+
+- **Deliverable:** a product brief following the 9-section template, plus a handoff block.
+- **Where it lands:** if the session has a writable workspace, write `./product-briefs/<slug>.md` (slug = kebab-case of the product name). If a file already exists, suffix `-2`, `-3`, … — never overwrite. If there is no writable workspace (read-only / chat-only), output the brief **inline** instead.
+- **Hard stop:** you do **not** scaffold a repo, install packages, or write app code. The handoff names the dev skill(s) that do that. Stop after the brief + handoff.
+
+## 5. Routing table (product shape → dev skill, prose names only)
+
+A product-audience refinement of the package `AGENTS.md` router. Full version with starter apps and ordered steps in [`knowledge/handoff.md`](./knowledge/handoff.md). Names are prose — never link into another skill.
+
+| Product shape | Hand off to (in order, integration mode) |
+|---|---|
+| Web app: wallet + feature UI | `sodax-wallet-sdk-react`, then `sodax-dapp-kit` |
+| React app calling the SDK directly | `sodax-wallet-sdk-react`, then `sodax-sdk` |
+| Backend / bot / script | `sodax-sdk`, then `sodax-wallet-sdk-core` (if it signs) |
+| Non-React browser | `sodax-wallet-sdk-core`, then `sodax-sdk` |
+| Porting an existing v1 app | each dev skill in **migration** mode first |
+
+Taking a partner fee always adds `sodax-sdk` (partner feature); in React, also `sodax-dapp-kit`.
+
+## 6. Related skills
+
+The developer skills — `sodax-sdk`, `sodax-wallet-sdk-core`, `sodax-wallet-sdk-react`, `sodax-dapp-kit` — are referenced by name only. See the package `AGENTS.md` for the full router. This skill never links into them by path.

package/skills/sodax-build/knowledge/README.md

@@ -0,0 +1,35 @@
+# sodax-build knowledge — index
+
+Reference material for the `sodax-build` front-door skill. The SKILL.md workflow points at these files in order; do not read them top-to-bottom.
+
+| File | Use it to… |
+|---|---|
+| [`interview-guide.md`](./interview-guide.md) | Drive the tiered, branching interview (Stage 0–5) + map plain-English goals to SODAX features. |
+| [`example-sessions.md`](./example-sessions.md) | Style reference: two worked interview transcripts (a Tier-A and a Tier-C session) end to end. |
+| [`feature-catalog.md`](./feature-catalog.md) | Explain, in plain English, what each SODAX capability lets an end-user *do*. |
+| [`use-case-gallery.md`](./use-case-gallery.md) | Borrow worked product ideas → the features + chains they use. |
+| [`glossary.md`](./glossary.md) | Gloss DeFi jargon for non-technical users (tiered). |
+| [`chains-and-assets.md`](./chains-and-assets.md) | Talk about supported chains/assets qualitatively; honesty-gate the unsupported. |
+| [`monetization.md`](./monetization.md) | Frame partner-fee monetization honestly. |
+| [`brief-template.md`](./brief-template.md) | Assemble the 9-section product brief. |
+| [`handoff.md`](./handoff.md) | Route the finished brief to the exact developer skill(s) + scaffolding steps. |
+
+## Source & freshness policy (read once; applies to every file here)
+
+This skill is **self-contained** — it needs no network to run the interview. But the facts it cites are **derived from** the SODAX repository, and some of them drift between releases. Apply this rule everywhere:
+
+- **Qualitative facts are baked in and stable** — what a feature *does*, the hub-and-spoke model, the intent/solver swap model, archetype → feature mappings. Use them directly.
+- **Enumerable / exact values are NOT baked in — fetch live before quoting.** This includes the supported chains, token symbols/addresses, fee numbers/caps, and any config value. When a user needs a precise value, open the current source and quote *that*, not memory.
+
+**Where to look** — navigate the current source by package + area, not a hard path (exact filenames move between releases):
+
+- Chains, tokens, and config → the **`@sodax/types`** package source.
+- Fees, and which feature services exist → the **`@sodax/sdk`** package source.
+
+Repo: `https://github.com/icon-project/sodax-sdks` (the `@sodax/*` packages live under `packages/`). Other files here point back to this policy rather than repeating paths.
+
+## Honesty rules
+
+- Never invent a supported chain, token, or exact fee number. If unsure, say so and fetch the source.
+- Never promise yields, returns, or price outcomes. This skill designs **products**, not investments — keep risk/disclosure framing separate from product design.
+- Never write app code here. The deliverable is a brief + a handoff naming the developer skill that writes code.

package/skills/sodax-build/knowledge/brief-template.md

@@ -0,0 +1,41 @@
+# Product brief template
+
+The output skeleton. After the Stage 5 playback and the user's confirmation, fill this in and write it to `./product-briefs/<slug>.md` (or output inline if there is no writable workspace). Keep the language at the user's tier. Do not include app code — the brief ends with a handoff.
+
+## The 9 sections
+
+1. **Problem & users** — who this is for and the problem it solves, in the user's own words.
+2. **What it does (plain English)** — the core user-facing behavior, no jargon.
+3. **SODAX features used — and why each** — a table tying each feature to a requirement. One row per feature; if you cannot tie a feature to a requirement, drop it.
+4. **Chains & assets** — which chains for Phase 1 (recommend small); flag any non-EVM chain that pulls in a chain-specific wallet provider; note that exact token/chain support is confirmed at dev time against live source.
+5. **Monetization** — partner-fee intent (percentage vs fixed, which actions, recipient deferred), framed per [`monetization.md`](./monetization.md). No promised returns.
+6. **Out of scope (v1)** — the explicit parking lot from Stage 5. This is what keeps Phase 1 shippable.
+7. **Phased build plan** — Phase 1 is a single tracer-bullet (smallest end-to-end slice). Each phase has a **"done when"** line. Later phases are bullets, not detail.
+8. **Risks & assumptions** — unsupported-chain checks, exact-value confirmations needed, non-EVM provider work, fee-policy confirmation, and any market/price assumption (never a promise).
+9. **Handoff to dev skills** — from [`handoff.md`](./handoff.md): the ordered dev skill(s) + mode + starter app + scaffolding steps. Skills named in prose only. Then append the machine-readable **handoff block** (YAML) from [`handoff.md`](./handoff.md) so downstream tooling can parse the routing.
+
+## Worked example (abridged) — Cross-chain payments widget
+
+**1. Problem & users.** People want to pay someone who holds funds on a different chain without manually bridging. Audience: end-users of a consumer wallet app; builder is non-technical.
+
+**2. What it does.** Enter a recipient and an amount; the widget moves the funds to the recipient's chain. If the recipient wants a different coin, it converts on the way.
+
+**3. SODAX features used.**
+
+| Requirement | Feature | Why |
+|---|---|---|
+| Move the same coin cross-chain | Bridge | Same asset on the other side |
+| Convert to a different coin | Swap | Intent-based; live quote, min-output floor |
+| Earn from the product | Partner fee | Small disclosed fee on each transfer |
+
+**4. Chains & assets.** Phase 1: two EVM chains (confirm the pair against live source). EVM-only → no extra wallet providers. Token support confirmed at dev time.
+
+**5. Monetization.** Small percentage partner fee on each transfer, disclosed in the UI. Exact cap confirmed against live SDK source before shipping. Fee recipient deferred.
+
+**6. Out of scope (v1).** Non-EVM chains; fiat on-ramp; recurring payments; multiple fee tiers.
+
+**7. Phased build plan.** *Phase 1 (tracer-bullet):* connect a wallet, enter recipient + amount on one EVM chain pair, execute one real cross-chain transfer with the partner fee attached. **Done when:** one end-to-end transfer completes in the safest supported environment (testnet if the feature flow supports it; confirm from the dev skill / source) and the fee lands at the configured address. *Later:* swap-on-the-way; more chains; richer UI.
+
+**8. Risks & assumptions.** Chain pair must be confirmed supported; exact fee cap must be confirmed; cross-chain transfers incur gas + relay costs the user pays (not a SODAX fee); received amount on a swap depends on a live quote, never promised.
+
+**9. Handoff.** Web app + wallet → load `sodax-wallet-sdk-react` (integration), then `sodax-dapp-kit` (integration); partner fee adds the `sodax-sdk` partner feature. Starter app + ordered steps from [`handoff.md`](./handoff.md).

package/skills/sodax-build/knowledge/chains-and-assets.md

@@ -0,0 +1,26 @@
+# Chains & assets
+
+> **Source & freshness.** The supported chains and tokens **change between releases** — never quote a definitive list from memory. Fetch the current set from live source before naming exact chains/tokens/addresses (where to look: the README *Source & freshness policy*). This file gives the **qualitative shape** only, which is safe for ideation.
+
+## The shape (qualitative — safe to use)
+
+SODAX is **hub-and-spoke**: **Sonic is the hub**, and a broad set of spoke chains spans **both EVM and non-EVM ecosystems**. For ideation you only need two facts:
+
+1. **There are many EVM chains** (for example major chains like Ethereum and Base; Sonic itself is the hub). They all share one wallet-provider family, so adding a second or third EVM chain is cheap.
+2. **There are several non-EVM chains** across different ecosystems (for example Solana, Sui, Bitcoin). Each non-EVM chain needs its **own** wallet provider — this is real extra work and changes the handoff.
+
+These names are **illustrative anchors only** — do not bake the actual chain list into the brief; confirm it from live source when it matters.
+
+**Cross-chain is the value.** SODAX's edge is moving value *between* these chains through the hub — that is the main reason to build on it. Lead the design with the cross-chain story.
+
+## How to use this in the interview (Stage 3)
+
+- **Recommend starting small.** For a non-technical user, a good default is **a small number of EVM chains** (e.g. one major chain plus one lower-fee chain). Confirm rather than open-question.
+- **Honesty-gate unsupported chains.** If the user names a chain you cannot confirm in live source, say you need to check and do so — never assert support from memory.
+- **Flag the non-EVM cost.** If the product touches **any non-EVM chain**, note in the brief that it pulls in a chain-specific wallet provider (a matching chain skill in `sodax-wallet-sdk-core`). EVM-only products avoid this.
+- **Some chains carry extra constraints.** A few chains have their own integration model or readiness gates. If a product centers on one of those, flag it as needing extra validation and confirm against live source before committing.
+
+## Assets
+
+- Bridgeability and per-feature token support are **runtime facts**, not a fixed table. "Can I bridge token X from chain A to B" is answered at runtime by the SDK, not by a baked list — note it as a dev-time check in the brief.
+- Never promise a specific token is supported without confirming live source.

package/skills/sodax-build/knowledge/example-sessions.md

@@ -0,0 +1,84 @@
+# Example interview sessions (few-shot)
+
+Two illustrative transcripts showing how the `sodax-build` interview runs end to end — a **Tier-A** non-coder and a **Tier-C** developer. Use them as a **style reference, not a script**: one question at a time, a recommended default offered, the goal reflected back in the user's words, cross-chain led with, a short playback, then a brief + handoff. All exact chains/tokens/fees shown are **illustrative** — confirm live per the README *Source & freshness policy*.
+
+---
+
+## Session 1 — Tier A (non-coder): a cross-chain payments app
+
+**User:** I'm not a developer. I want people to pay a friend who keeps their money on a different blockchain. Can I build that on SODAX?
+
+**sodax-build:** You can — moving money *between* different chains is exactly SODAX's strength. First, so I pitch this right: are you more comfortable thinking about the *product* (no code), or do you also write some code? (Most non-developers pick the first — totally fine.)
+
+**User:** Just the product. No code.
+
+**sodax-build:** Great — I'll keep it plain and suggest defaults you can just confirm. In one or two sentences: what do you want people to be able to *do*?
+
+**User:** Send money to someone, even if that person uses a different chain than they do.
+
+**sodax-build:** So the core action is "send value from my chain to my friend on their chain." One question: should your friend receive the **same coin** you sent, or is a **different coin** on their side fine?
+
+**User:** Same coin for v1.
+
+**sodax-build:** Then the core feature is a **bridge** (same coin, different chain) — and the whole thing is cross-chain, which is where SODAX shines. (If later you want the friend to receive a *different* coin, that's a **swap** — a phase 2.) Do you want to earn from this — now, later, or keep it free?
+
+**User:** A small fee would be nice, eventually.
+
+**sodax-build:** Noted — a small **partner fee** (your cut on each transfer); we'll mark it "later, small, disclosed" and not block v1 on it. For chains, a good start is **two EVM chains** (one major chain plus one lower-fee chain — confirmed against live source). Sound right, or do you have chains in mind?
+
+**User:** That default is fine.
+
+**sodax-build:** Here's the plan in plain bullets — tell me if anything's off:
+> - **Who/what:** let someone send the *same* coin to a friend on another chain.
+> - **SODAX features:** bridge (core), partner fee (later).
+> - **Chains (v1):** two EVM chains, confirmed live. EVM-only → no extra wallet work.
+> - **Phase 1 goal:** one real cross-chain transfer, wallet connected.
+> - **Out of scope (v1):** receiving a different coin, non-EVM chains, the fee.
+
+**User:** Perfect.
+
+**sodax-build:** I'll write that up as a product brief (`./product-briefs/cross-chain-payments.md`) and end with a handoff:
+
+> **Handoff:** web app with a wallet → load the `sodax-wallet-sdk-react` skill (integration), then the `sodax-dapp-kit` skill for the bridge feature. Start from the demo app's provider setup. Phase-1 goal: one working cross-chain transfer in the safest supported environment.
+
+```yaml
+handoff:
+  skills:
+    - sodax-wallet-sdk-react
+    - sodax-dapp-kit
+  mode: integration
+  partner_fee: false        # deferred to a later phase
+  non_evm_chains: []
+  starter_app: apps/demo
+  phase1_goal: "one working cross-chain same-coin transfer across two EVM chains"
+```
+
+— then it **stops**. It does not write the app code.
+
+---
+
+## Session 2 — Tier C (developer): a backend cross-chain swap bot
+
+**User:** I'm a backend dev. I want a service that swaps tokens across chains for users and takes a small cut. Where do I start?
+
+**sodax-build:** You've described the product but not picked an SDK, so a quick framing then I route you. The core is a **cross-chain swap** (different coin out, on another chain — SODAX's sweet spot) plus a **partner fee** for your cut. It's a backend service (no React), so it signs with a private-key provider. One check: are source and destination *different chains* (the cross-chain case), or also same-chain conversions?
+
+**User:** Mostly cross-chain, occasionally same-chain.
+
+**sodax-build:** Both are the swap feature — lead with the cross-chain path; same-chain is just source == destination. Enough to route. Brief + handoff:
+
+> **Handoff:** backend/bot shape → load the `sodax-sdk` skill (integration) for the swap + partner feature, and the `sodax-wallet-sdk-core` skill (integration) for the chain provider that signs. Start from the node example app. Phase-1 goal: one real cross-chain swap from the service with the partner fee attached, in the safest supported environment.
+
+```yaml
+handoff:
+  skills:
+    - sodax-sdk
+    - sodax-wallet-sdk-core
+  mode: integration
+  partner_fee: true
+  non_evm_chains: []        # add any non-EVM chain the bot signs on
+  starter_app: apps/node
+  phase1_goal: "one real cross-chain swap from the backend with a partner fee"
+```
+
+— then it **stops**. (If the dev had named a hook, `Sodax`, or a provider symbol up front, the SKILL.md STOP gate would skip the interview and route immediately.)

package/skills/sodax-build/knowledge/feature-catalog.md

@@ -0,0 +1,51 @@
+# Feature catalog — what each SODAX capability lets an end-user DO
+
+Plain-English descriptions for the interview. These are **qualitative and stable** (the architecture changes slowly) — safe to use directly. Anything exact (chain lists, token symbols, fee numbers) is **not** here on purpose; fetch live source per the README policy.
+
+SODAX is **cross-chain DeFi on a hub-and-spoke model**: Sonic is the hub chain, and every other chain is a "spoke". A user acts from their own chain; SODAX routes the action through the hub. The user does not need to understand the hub — it is plumbing.
+
+The feature surface (which services actually exist) lives in the `@sodax/sdk` source — fetch it (see the README *Source & freshness policy*) if you need to confirm a feature still ships.
+
+## Swap — convert one token into another, across chains (or on one chain)
+
+**Cross-chain is the point — lead with it.** The user gives token A on one chain and receives token B on **another** chain in a single intent. This cross-chain reach is SODAX's core strength and the main reason to choose it over a single-chain DEX, so frame swap products around it. Mechanically the SDK takes a source chain and a destination chain separately, so a **same-chain** swap (A → B on one chain) is also valid — but cross-chain is where SODAX adds the most, so lead swap products with it. Use it for "let people trade / convert / get a different coin", ideally where the coins live on different chains.
+
+**How pricing works (important, and a common misconception):** SODAX swap is **intent-based**. The user expresses an intent ("swap this for at least that much"), and an **off-chain solver network** quotes a live price and fills it. The price is **not** read from an on-chain price oracle, and it is **not** a fixed on-chain AMM pool — it is a real-time solver quote. The user is protected by a **minimum-output floor** (slippage protection): they receive at least the minimum or the intent does not fill. Practical consequence for a brief: the exact amount received must come from a **live quote**, never a promised number.
+
+> Do not confuse "swap" with SODAX's own DEX (below). Swap = intent/solver. DEX = an on-chain liquidity pool. They are separate features.
+
+## Bridge — move the *same* token to another chain
+
+Same asset, different chain (e.g. move USDC from Ethereum to another chain). Use it for "send / move money to another chain" where the coin stays the same. Bridging works for tokens that share a vault on the hub.
+
+## Money market — lend to earn, or borrow against collateral
+
+Cross-chain lending/borrowing. Two end-user actions: **supply** assets to earn, and **borrow** against supplied collateral. Use it for "savings / earn yield / put money to work" (supply) or "borrow against what I hold" (borrow). Yields are market-driven — never promise a rate.
+
+## Staking — lock SODA to earn
+
+The user stakes the **SODA** token and receives a vault share (xSoda). Unstaking has a waiting period; an "instant unstake" path exists but pays a penalty/slippage. Use it for "earn by locking the SODA token" specifically — not generic savings (that is money market).
+
+## DEX — provide liquidity / market-make
+
+Concentrated-liquidity AMM (similar to Uniswap V3) on the hub. The end-user provides liquidity to a pool and manages a position. Use it for "provide liquidity / be a market maker / run an LP position". This is on-chain pool liquidity — distinct from the solver-based swap.
+
+## Token migration — bring legacy ICON-ecosystem tokens over
+
+Migrates **specific legacy ICON-ecosystem tokens** (e.g. ICX, BALN, bnUSD) into the SODAX ecosystem, with some reverse paths. It only handles a fixed, named set — confirm the current set from live source rather than assuming. **Honesty-gate:** SODAX does not mint or launch brand-new tokens; "I want to create a token" is out of scope.
+
+## Partner fee — how an integrator earns
+
+Lets the app/integrator take a fee on transactions routed through it. This is the **monetization mechanism** for most products built on SODAX. Details and honest framing live in [`monetization.md`](./monetization.md).
+
+## Recovery — withdraw stuck hub-wallet assets
+
+If assets end up stranded in a user's hub wallet, recovery withdraws them back to a spoke chain. This is almost always a **secondary** feature (a safety net), not a product's core value.
+
+## Leverage yield — leveraged ERC-4626 vaults (advanced)
+
+Leveraged-yield vaults on the hub that loop supply → borrow → swap to build a leveraged position. **Advanced and risk-heavy** — only surface it when a semi-technical+ user explicitly wants leverage, and keep risk framing separate from product design. Net yield can be negative. Never present it to a Tier A user as "savings".
+
+---
+
+**Mapping back to the interview:** the goal → feature table lives in [`interview-guide.md`](./interview-guide.md); worked product combinations are in [`use-case-gallery.md`](./use-case-gallery.md).