chore: update rules with learnings from PR #884 and #885

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 0xYankee-Raccoons

.claude/rules/decisions.md

@@ -234,3 +234,21 @@ Track all redirects added to `vercel.json` here for visibility:
 **Alternatives considered:**
 1. `/submit` at repo root - too generic, no namespace for future transaction endpoints.
 2. Keep at `/swap/submit` - contradicts the API path and the endpoint's product-neutral scope. A non-swap developer wouldn't look under `/swap/` for transaction submission.
+
+### [2026-04-16] Reframe swap overview as Meta-Aggregator vs Router
+**Status:** implemented
+**Scope:** navigation | folder-structure | redirect
+**Files affected:** `swap/index.mdx`, `swap/order-and-execute.mdx`, `swap/build/index.mdx`, `swap/fees.mdx` (deleted), `swap/routing/index.mdx` (deleted), `swap/build/common-instructions.mdx` (renamed from other-instructions), `swap/migration/` (split into 3 pages), `docs.json`
+**Linear issue:** PR #884
+
+**Context:** The swap overview lacked a clear framing for the two integration paths. Developers had to piece together the relationship between `/order`, `/build`, `/execute`, and `/submit` across multiple pages. Fees and routing were standalone pages that fragmented the narrative.
+**Decision:**
+- Reframe overview around two paths: **Meta-Aggregator** (`/order` + `/execute`) and **Router** (`/build` + `/submit`)
+- Absorb `swap/fees.mdx` into `order-and-execute.mdx` and `build/index.mdx` (fees are path-specific)
+- Absorb `swap/routing/index.mdx` into `swap/index.mdx` (routing context belongs in overview)
+- Rename "Metis Router" to just "Router" in most contexts (Metis mentioned only when explaining internals)
+- Rename `other-instructions.mdx` to `common-instructions.mdx` with redirect
+- Split monolithic `migration.mdx` into 3 profile-targeted pages: `metis-to-build`, `metis-to-meta-aggregator`, `ultra-to-order`
+- Reorganise sidebar: Swap (overview), Meta-Aggregator (order-and-execute + API refs), Router (build + submit + API refs), Advanced, Routing Integration, Guides, Migration
+**Rationale:** Two clear paths reduce decision fatigue. Absorbing fees and routing eliminates page-hopping for core concepts. Profile-targeted migration pages let developers find their specific upgrade path without reading irrelevant content.
+**Migration notes:** Redirects added for `swap/fees` → `swap/order-and-execute`, `swap/routing` → `swap`, `swap/build/other-instructions` → `swap/build/common-instructions`.

.claude/rules/product-learning.md

@@ -52,6 +52,7 @@ Keep entries concise — one line if possible, a short paragraph if needed.
 ## Architecture
 
 - [2026-03-17] Three endpoints: `/order` (default, all routers compete), `/build` (raw instructions, Metis-only routing), `/execute` (managed landing for `/order` only).
+- [2026-04-16] Two integration paths: **Meta-Aggregator** (`/order` + `/execute`) where Jupiter handles transaction assembly and landing, and **Router** (`/build` + `/submit` or own RPC) where the integrator builds the transaction. The swap overview page uses this framing.
 - [2026-03-17] `/order` without optional params gets all routers (Metis, JupiterZ, Hashflow, Dflow, OKX, Mantis). Adding certain params (fee, slippage overrides) may restrict to Metis-only routing.
 - [2026-03-17] `/build` has no Jupiter swap fees. Only integrator platform fees via `platformFeeBps`.
 - [2026-03-17] `/build` returns `computeBudgetInstructions` with CU price only, NOT CU limit. Integrators must simulate to determine CU limit (confirmed from `ultra-api` source: `setComputeUnitPrice` only).
@@ -85,6 +86,7 @@ Keep entries concise — one line if possible, a short paragraph if needed.
 - [2026-03-17] Code examples provide both @solana/kit and @solana/web3.js variants in `<CodeGroup>` tabs. Kit is listed first as the recommended modern SDK.
 - [2026-03-17] Prerequisites (imports, types, helpers) go in a collapsible `<Accordion>` above the main code example to keep the page scannable.
 - [2026-04-09] `/build` code examples now default to `/submit` as the submission path instead of `sendRawTransaction`. Comments note "or use your own RPC / transaction pipeline" for integrators not using `/submit`.
+- [2026-04-16] Code examples for `/build` and `/submit` must include confirmation polling as the final step (`confirmTransaction` with blockhash strategy). Step numbering must be consistent across pages that share the same flow (currently 7 steps: call API, collect instructions, prepare blockhash/ALTs, simulate CU, build final tx, sign and submit, confirm).
 
 ---
 
@@ -251,11 +253,12 @@ Keep entries concise — one line if possible, a short paragraph if needed.
 ## Architecture
 
 - [2026-04-06] `POST api.jup.ag/tx/v1/submit` accepts any signed Solana transaction with a SOL tip (min 1M lamports / 0.001 SOL) to one of 16 Jupiter V6 program authorities.
-- [2026-04-06] `/submit` is for `/build` transactions and non-Jupiter transactions. `/execute` is for `/order` transactions only. Different fee models: tips vs swap fees.
+- [2026-04-06] `/submit` is for `/build` transactions and non-Jupiter transactions. `/execute` is exclusively for `/order` (meta-aggregator flow) transactions. Different fee models: tips vs swap fees.
 - [2026-04-07] `/submit` is now public. API path is `api.jup.ag/tx/v1/submit` (deliberately outside the `/swap/v2/` namespace since it accepts any transaction). Docs page at `/transaction/submit`.
 - [2026-04-06] `/build` supports a `tipAmount` param that auto-includes the tip instruction in the response. For non-Jupiter transactions, integrators add a standard SOL transfer instruction manually.
-- [2026-04-07] Jupiter runs one of the top 3 validators on Solana. `/submit` opens this landing pipeline to integrators. Key selling point for the docs.
+- [2026-04-07] Jupiter operates one of the highest-staked validators on Solana. `/submit` opens this landing pipeline to integrators. Key selling points: validator stake, MEV protection (no intermediaries), sub-second landing, zero credit cost.
 - [2026-04-07] Recommended integration pattern: run `/submit` in parallel with existing RPC submission for zero-risk comparison. Whichever lands first wins.
+- [2026-04-16] `/submit` costs zero API credits on all plans (free, Developer, Launch, Pro) and works with keyless access. The only cost is the SOL tip in the transaction.
 
 ---
 

.claude/rules/style-guide.md

@@ -32,6 +32,8 @@ Technical but approachable. Professional and precise, not cold or overly formal.
 | `/build`          | build endpoint, build API              | Always backtick the path in prose              |
 | `/execute`        | execute endpoint, execute API          | Always backtick the path in prose              |
 | `/submit`          | submit endpoint, submit API            | Always backtick. API at `api.jup.ag/tx/v1/submit`, not under `/swap/v2/` |
+| Meta-Aggregator    | meta aggregator, MetaAggregator        | The `/order` + `/execute` integration path. Capitalised, hyphenated. |
+| Router             | Metis Router (in most contexts)        | The `/build` + `/submit` integration path. Say "Router" in prose, mention Metis only when explaining what the Router uses under the hood. |
 
 ### Product-Specific Terms
 
@@ -196,3 +198,6 @@ Format: `- [YYYY-MM-DD] Decision: rationale`
 - [2026-04-07] `/submit` is a product-neutral endpoint at `api.jup.ag/tx/v1/submit`. Always use the full API URL in code examples (`https://api.jup.ag/tx/v1/submit`), not a `BASE_URL` variable. The docs path is `/transaction/submit`. In prose, reference as `/submit` with backticks.
 - [2026-04-07] RTSE terminology: always use "RTSE" or "Real-Time Slippage Estimator". Never use "dynamic slippage" or "auto slippage" — these were legacy names that are no longer used.
 - [2026-04-07] Docs file path does not need to mirror the API URL path. Mintlify's docs.json decouples sidebar placement from file location. A page can live at `transaction/submit.mdx` but appear in the Swap sidebar. Choose file paths based on product scope, not discovery context.
+- [2026-04-16] Swap API overview uses "Meta-Aggregator" and "Router" as the two integration paths. "Meta-Aggregator" = `/order` + `/execute` (Jupiter handles everything). "Router" = `/build` + `/submit` or own RPC (integrator builds the transaction). Use these terms consistently in swap docs.
+- [2026-04-16] When absorbing a standalone page into another page, delete the original and add a redirect. Done for `swap/fees.mdx` (absorbed into order-and-execute and build) and `swap/routing/index.mdx` (absorbed into overview). Keeps URL space clean.
+- [2026-04-16] British English spelling for docs prose (e.g. "randomise", "optimise", "colour"). Do not Americanise existing British spellings.