From afc53ead132e7ffd4f212fe3e2497d32f6dec6d3 Mon Sep 17 00:00:00 2001
From: Rohit Yadav <thesandman.sh@gmail.com>
Date: Wed, 1 Jul 2026 02:17:51 +0530
Subject: [PATCH] feat: add agent-ux-skill for Solana Agent-UX audits

---
 agent-ux-skill/LICENSE               |  21 +
 agent-ux-skill/README.md             | 173 ++++++++
 agent-ux-skill/install.sh            | 110 +++++
 agent-ux-skill/skill/SKILL.md        |  68 ++++
 agent-ux-skill/skill/gasless-flow.md | 343 ++++++++++++++++
 agent-ux-skill/skill/scaffold-ui.md  | 588 +++++++++++++++++++++++++++
 agent-ux-skill/skill/ux-audit.md     | 138 +++++++
 7 files changed, 1441 insertions(+)
 create mode 100644 agent-ux-skill/LICENSE
 create mode 100644 agent-ux-skill/README.md
 create mode 100644 agent-ux-skill/install.sh
 create mode 100644 agent-ux-skill/skill/SKILL.md
 create mode 100644 agent-ux-skill/skill/gasless-flow.md
 create mode 100644 agent-ux-skill/skill/scaffold-ui.md
 create mode 100644 agent-ux-skill/skill/ux-audit.md

diff --git a/agent-ux-skill/LICENSE b/agent-ux-skill/LICENSE
new file mode 100644
index 0000000..fef0ed9
--- /dev/null
+++ b/agent-ux-skill/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-ux-skill contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/agent-ux-skill/README.md b/agent-ux-skill/README.md
new file mode 100644
index 0000000..8ef527a
--- /dev/null
+++ b/agent-ux-skill/README.md
@@ -0,0 +1,173 @@
+# 🧩 agent-ux-skill
+
+> **AI skill for the Solana AI Kit** — Analyze dApp transaction flows, generate UX optimization reports, and scaffold production-ready frontend components.
+
+[![Solana](https://img.shields.io/badge/Solana-2026_Stack-9945FF?style=flat-square&logo=solana)](https://solana.com)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](./LICENSE)
+[![Skill Bounty](https://img.shields.io/badge/Superteam-Skill_Bounty-14F195?style=flat-square)](https://github.com/solanabr/skill-bounty)
+
+---
+
+## The Problem
+
+Web3 dApps lose **40–60% of users** at the transaction signing step due to:
+
+- 🔴 Wallet connection failures with no fallback UI
+- 🔴 Cryptic error messages (`"custom program error: 0x1194"`)
+- 🔴 No loading states during 10-second confirmation waits
+- 🔴 Requiring SOL for gas before users can do anything
+- 🔴 Missing retry logic on `BlockhashNotFound` errors
+
+Founders know their UX is bad, but lack the tooling to systematically identify
+and fix these issues.
+
+## The Solution
+
+**agent-ux-skill** is an AI skill that plugs into the
+[Solana AI Kit](https://github.com/solana-labs/solana-ai-kit) and gives your
+AI coding agent three superpowers:
+
+| Capability              | What it does                                                                 |
+|-------------------------|------------------------------------------------------------------------------|
+| **🔍 UX Audit**         | Analyzes your transaction flow against a 20+ point checklist and outputs a severity-ranked report. |
+| **🧱 Scaffold UI**      | Generates production-ready React/Vue components: wallet guards, transaction toasts, error boundaries, priority fee selectors. |
+| **⛽ Gasless Flow**      | Guides implementation of fee-payer architecture, Octane relays, or session keys so users never need SOL to transact. |
+
+---
+
+## Architecture
+
+This skill follows the **progressive loading** pattern — the AI agent only
+loads the specific instructions it needs, keeping token usage minimal:
+
+```
+skill/
+├── SKILL.md            ← Router (entry point — routes to sub-files)
+├── ux-audit.md         ← UX audit checklist & report template
+├── scaffold-ui.md      ← React/Vue component templates
+└── gasless-flow.md     ← Fee payer / relay / session key guides
+```
+
+The router (`SKILL.md`) evaluates the user's intent and loads **only the
+relevant file** — never all three at once.
+
+---
+
+## Installation
+
+### Option 1: Installer Script
+
+```bash
+# Clone this repo
+git clone https://github.com/your-username/agent-ux-skill.git
+cd agent-ux-skill
+
+# Set the path to your Solana AI Kit installation
+export SOLANA_AI_KIT_DIR="/path/to/solana-ai-kit"
+
+# Run the installer
+chmod +x install.sh
+./install.sh
+```
+
+### Option 2: Manual Copy
+
+```bash
+cp -r skill/ /path/to/solana-ai-kit/skills/agent-ux-skill/
+```
+
+### Option 3: Git Submodule
+
+```bash
+cd /path/to/solana-ai-kit
+git submodule add https://github.com/your-username/agent-ux-skill.git skills/agent-ux-skill
+```
+
+---
+
+## Usage
+
+Once installed, your AI agent will automatically detect the skill. Use natural
+language prompts:
+
+### UX Audit
+
+```
+"Audit the UX of my Solana dApp. My program ID is Fg6P...abc.
+Here's a recent transaction: 5Kx9...xyz"
+```
+
+The agent will analyze your transaction flow and produce a structured report
+with **Critical / Warning / Info** findings, each with a concrete fix.
+
+### Scaffold Components
+
+```
+"Scaffold wallet connection and transaction UI components for my
+Next.js app using React and CSS Modules."
+```
+
+The agent generates 5 production-ready components:
+- `WalletConnectionGuard` — conditional rendering based on wallet state
+- `TransactionToast` — real-time tx status feedback
+- `SendTransactionButton` — one-click send with simulation, retry, priority fees
+- `SolanaErrorBoundary` — catches and decodes Anchor/program errors
+- `PriorityFeeSelector` — user-facing tx speed picker (Slow / Standard / Fast)
+
+### Gasless Transactions
+
+```
+"Add gasless transactions to my dApp so users don't need SOL.
+I want a server-side fee payer approach."
+```
+
+The agent provides a complete server endpoint + client hook with rate limiting,
+security validation, and transaction co-signing.
+
+---
+
+## Tech Stack
+
+| Layer           | Technology                                                |
+|-----------------|-----------------------------------------------------------|
+| Solana SDK      | `@solana/web3.js` v2                                      |
+| Wallet Adapter  | `@solana/wallet-adapter-react` v0.15+                     |
+| React           | React 19 with `"use client"` directives                   |
+| Vue             | Vue 3.5+ Composition API (`<script setup lang="ts">`)     |
+| Transactions    | Versioned Transactions, Compute Budget, Address Lookup Tables |
+
+---
+
+## Submitting to the Skill Bounty
+
+This skill is designed for submission to the
+[Superteam Earn Skill Bounty](https://github.com/solanabr/skill-bounty).
+
+### Steps to Submit
+
+1. **Fork** the [skill-bounty repository](https://github.com/solanabr/skill-bounty).
+2. **Copy** the `skill/` directory into the fork under `skills/agent-ux-skill/`.
+3. **Add** this `README.md` to the root of your submission.
+4. **Open a Pull Request** with:
+   - Title: `[Skill Submission] agent-ux-skill`
+   - Description: Link to this README and a brief summary of the three capabilities.
+5. **Include a demo** — record a short video or GIF showing the agent
+   performing a UX audit or scaffolding components.
+
+---
+
+## Contributing
+
+Contributions are welcome. Key areas:
+
+- **New audit checks** — add to the checklist in `ux-audit.md`
+- **Framework support** — add Svelte/SolidJS component variants to `scaffold-ui.md`
+- **Relay integrations** — add new gasless relay providers to `gasless-flow.md`
+
+Please open an issue before submitting large changes.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.
diff --git a/agent-ux-skill/install.sh b/agent-ux-skill/install.sh
new file mode 100644
index 0000000..4d63f5d
--- /dev/null
+++ b/agent-ux-skill/install.sh
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# ──────────────────────────────────────────────────────────────────
+#  agent-ux-skill installer
+#  Installs the skill into the Solana AI Kit's skills directory.
+# ──────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# ── Config ───────────────────────────────────────────────────────
+SKILL_NAME="agent-ux-skill"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_SOURCE="${SCRIPT_DIR}/skill"
+
+# Default install target — can be overridden via env var
+SOLANA_AI_KIT_DIR="${SOLANA_AI_KIT_DIR:-$(pwd)/solana-ai-kit}"
+SKILLS_DIR="${SOLANA_AI_KIT_DIR}/skills"
+TARGET_DIR="${SKILLS_DIR}/${SKILL_NAME}"
+
+# ── Colors ───────────────────────────────────────────────────────
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+info()  { echo -e "${GREEN}[✓]${NC} $*"; }
+warn()  { echo -e "${YELLOW}[!]${NC} $*"; }
+error() { echo -e "${RED}[✗]${NC} $*"; exit 1; }
+
+# ── Pre-flight checks ───────────────────────────────────────────
+echo ""
+echo "╔═══════════════════════════════════════════╗"
+echo "║   agent-ux-skill — Installer              ║"
+echo "╚═══════════════════════════════════════════╝"
+echo ""
+
+# Verify source skill directory exists
+if [ ! -d "${SKILL_SOURCE}" ]; then
+  error "Skill source directory not found at: ${SKILL_SOURCE}"
+fi
+
+# Verify SKILL.md exists
+if [ ! -f "${SKILL_SOURCE}/SKILL.md" ]; then
+  error "SKILL.md not found in ${SKILL_SOURCE}. Aborting."
+fi
+
+# Check if Solana AI Kit directory exists
+if [ ! -d "${SOLANA_AI_KIT_DIR}" ]; then
+  warn "Solana AI Kit directory not found at: ${SOLANA_AI_KIT_DIR}"
+  echo ""
+  echo "Options:"
+  echo "  1. Set SOLANA_AI_KIT_DIR env var to the correct path and re-run."
+  echo "  2. Clone the Solana AI Kit first:"
+  echo "     git clone https://github.com/solana-labs/solana-ai-kit.git"
+  echo ""
+  read -rp "Create ${SKILLS_DIR} now? [y/N] " confirm
+  if [[ "${confirm}" =~ ^[Yy]$ ]]; then
+    mkdir -p "${SKILLS_DIR}"
+    info "Created ${SKILLS_DIR}"
+  else
+    error "Cannot proceed without a target directory. Aborting."
+  fi
+fi
+
+# Create skills directory if it doesn't exist
+mkdir -p "${SKILLS_DIR}"
+
+# ── Install ──────────────────────────────────────────────────────
+
+# Check for existing installation
+if [ -d "${TARGET_DIR}" ]; then
+  warn "Existing installation found at ${TARGET_DIR}"
+  read -rp "Overwrite? [y/N] " overwrite
+  if [[ "${overwrite}" =~ ^[Yy]$ ]]; then
+    rm -rf "${TARGET_DIR}"
+    info "Removed existing installation"
+  else
+    error "Aborting to preserve existing installation."
+  fi
+fi
+
+# Copy skill files
+cp -r "${SKILL_SOURCE}" "${TARGET_DIR}"
+info "Copied skill files to ${TARGET_DIR}"
+
+# Verify installation
+EXPECTED_FILES=("SKILL.md" "ux-audit.md" "scaffold-ui.md" "gasless-flow.md")
+for file in "${EXPECTED_FILES[@]}"; do
+  if [ ! -f "${TARGET_DIR}/${file}" ]; then
+    error "Verification failed: ${file} missing from ${TARGET_DIR}"
+  fi
+done
+
+info "All skill files verified"
+
+# ── Summary ──────────────────────────────────────────────────────
+echo ""
+echo "╔═══════════════════════════════════════════╗"
+echo "║   Installation Complete                    ║"
+echo "╚═══════════════════════════════════════════╝"
+echo ""
+info "Skill installed at: ${TARGET_DIR}"
+echo ""
+echo "Files installed:"
+for file in "${EXPECTED_FILES[@]}"; do
+  echo "  • ${file}"
+done
+echo ""
+echo "Usage: Point your AI agent at the skills directory or reference"
+echo "the SKILL.md file directly. The skill will auto-route based on"
+echo "your prompt."
+echo ""
diff --git a/agent-ux-skill/skill/SKILL.md b/agent-ux-skill/skill/SKILL.md
new file mode 100644
index 0000000..8e86b4a
--- /dev/null
+++ b/agent-ux-skill/skill/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: agent-ux-skill
+description: >
+  Analyzes Solana dApp transaction flows and generates UX optimization reports.
+  Scaffolds production-ready React/Vue UI components for wallet connection,
+  gasless transactions, error boundaries, and optimal signing states.
+  Use when the user says "audit my dApp UX", "scaffold wallet UI",
+  "gasless transactions", "optimize Solana UX", "generate wallet adapter components",
+  "fee payer setup", or "transaction error handling".
+---
+
+# Agent UX Skill — Router
+
+You are the **Agent UX Skill** for the Solana AI Kit. Your job is to improve
+the end-user experience of Solana dApps by auditing transaction flows,
+scaffolding production-grade frontend components, and guiding gasless
+transaction architecture.
+
+**Do NOT read all sub-files at once.** Only load the file that matches the
+user's current intent. This keeps token usage minimal.
+
+---
+
+## Routing Table
+
+Evaluate the user's request and load **exactly one** of the following files:
+
+### 1 · UX Audit
+
+**Trigger phrases:** "audit my dApp", "analyze transactions", "UX report",
+"find UX issues", "transaction flow analysis", "review my Solana UX",
+"user friction", "drop-off analysis"
+
+→ Read [skill/ux-audit.md](./ux-audit.md) and follow its instructions.
+
+---
+
+### 2 · Scaffold UI Components
+
+**Trigger phrases:** "scaffold wallet UI", "generate React components",
+"Vue wallet adapter", "wallet connection component", "build sign-in flow",
+"create transaction modal", "UI components for Solana"
+
+→ Read [skill/scaffold-ui.md](./scaffold-ui.md) and follow its instructions.
+
+---
+
+### 3 · Gasless Transaction Flow
+
+**Trigger phrases:** "gasless transactions", "fee payer", "sponsor fees",
+"relay transactions", "abstract gas", "onboard web2 users",
+"no SOL for fees", "meta-transactions"
+
+→ Read [skill/gasless-flow.md](./gasless-flow.md) and follow its instructions.
+
+---
+
+## Combination Requests
+
+If the user's request spans multiple areas (e.g., "audit my dApp and then
+scaffold improved components"), load the files **sequentially** — complete the
+first workflow before loading the next.
+
+## Fallback
+
+If the request does not match any trigger above but is broadly related to
+Solana frontend or UX, load [skill/ux-audit.md](./ux-audit.md) as the
+default starting point and adapt from there.
diff --git a/agent-ux-skill/skill/gasless-flow.md b/agent-ux-skill/skill/gasless-flow.md
new file mode 100644
index 0000000..dc189a0
--- /dev/null
+++ b/agent-ux-skill/skill/gasless-flow.md
@@ -0,0 +1,343 @@
+# Gasless Transaction Flow — Fee Payer & Relay Architecture
+
+You are guiding the user through implementing **gasless transactions** for
+their Solana dApp — where end-users do not need SOL to pay transaction fees.
+This is critical for onboarding Web2 users who may not hold any SOL.
+
+---
+
+## Step 1 — Choose an Approach
+
+Present these three approaches and help the user decide:
+
+| Approach              | Complexity | Cost Model         | Best For                          |
+|-----------------------|------------|--------------------|-----------------------------------|
+| **Server-side fee payer** | Low    | You pay all fees   | Small user base, high-value txns  |
+| **Octane relay**          | Medium | Flexible           | Token-based fee payment           |
+| **Session keys**          | High   | Users pre-approve  | Gaming, high-frequency dApps      |
+
+Ask the user: **"Which approach fits your use case?"** Default to the
+**server-side fee payer** for simplicity.
+
+---
+
+## Step 2 — Server-Side Fee Payer Implementation
+
+### 2.1 Architecture Overview
+
+```
+┌──────────┐     1. Build unsigned tx     ┌──────────┐
+│  Client   │ ──────────────────────────► │  Server   │
+│ (Browser) │                              │ (API)     │
+│           │ ◄────────────────────────── │           │
+│           │   2. Return partially        │  Has fee  │
+│           │      signed tx (fee payer)   │  payer KP │
+│           │                              └──────────┘
+│           │  3. User signs (wallet)
+│           │  4. Send fully signed tx
+│           │     to RPC
+└──────────┘
+```
+
+### 2.2 Server Endpoint (Node.js / Express)
+
+```typescript
+// server/api/sponsor-transaction.ts
+import express from "express";
+import {
+  Connection,
+  Keypair,
+  VersionedTransaction,
+  TransactionMessage,
+} from "@solana/web3.js";
+import bs58 from "bs58";
+
+const FEE_PAYER = Keypair.fromSecretKey(
+  bs58.decode(process.env.FEE_PAYER_PRIVATE_KEY!),
+);
+const connection = new Connection(process.env.RPC_URL!, "confirmed");
+
+const router = express.Router();
+
+// Rate limiting: max 10 sponsored txns per wallet per hour
+const rateLimitMap = new Map<string, { count: number; resetAt: number }>();
+
+function checkRateLimit(wallet: string): boolean {
+  const now = Date.now();
+  const entry = rateLimitMap.get(wallet);
+  if (!entry || now > entry.resetAt) {
+    rateLimitMap.set(wallet, { count: 1, resetAt: now + 3_600_000 });
+    return true;
+  }
+  if (entry.count >= 10) return false;
+  entry.count++;
+  return true;
+}
+
+router.post("/sponsor-transaction", async (req, res) => {
+  try {
+    const { serializedTransaction, userWallet } = req.body;
+
+    if (!serializedTransaction || !userWallet) {
+      return res.status(400).json({ error: "Missing required fields" });
+    }
+
+    // Rate limit check
+    if (!checkRateLimit(userWallet)) {
+      return res.status(429).json({ error: "Rate limit exceeded. Try again later." });
+    }
+
+    // Deserialize the transaction
+    const txBuffer = Buffer.from(serializedTransaction, "base64");
+    const transaction = VersionedTransaction.deserialize(txBuffer);
+
+    // Verify the fee payer is set to our server's fee payer
+    // (the client should have built the tx with our fee payer pubkey)
+    // Security: validate instructions are for the expected program
+    // to prevent abuse.
+
+    // Sign with fee payer
+    transaction.sign([FEE_PAYER]);
+
+    // Return partially signed transaction for user to co-sign
+    const signedBytes = transaction.serialize();
+
+    return res.json({
+      signedTransaction: Buffer.from(signedBytes).toString("base64"),
+      feePayerBalance: await connection.getBalance(FEE_PAYER.publicKey),
+    });
+  } catch (err) {
+    console.error("Sponsor transaction error:", err);
+    return res.status(500).json({ error: "Failed to sponsor transaction" });
+  }
+});
+
+export default router;
+```
+
+### 2.3 Client-Side Integration (React)
+
+```tsx
+// hooks/useGaslessTransaction.ts
+"use client";
+
+import { useConnection, useWallet } from "@solana/wallet-adapter-react";
+import {
+  TransactionMessage,
+  VersionedTransaction,
+  PublicKey,
+  type TransactionInstruction,
+} from "@solana/web3.js";
+import { useCallback } from "react";
+import { useTransactionToast } from "../components/TransactionToast";
+
+// The fee payer's public key — must match the server's keypair
+const FEE_PAYER_PUBKEY = new PublicKey(
+  process.env.NEXT_PUBLIC_FEE_PAYER_PUBKEY!,
+);
+
+interface GaslessOptions {
+  instructions: TransactionInstruction[];
+  onSuccess?: (signature: string) => void;
+  onError?: (error: Error) => void;
+}
+
+export function useGaslessTransaction() {
+  const { connection } = useConnection();
+  const { publicKey, signTransaction } = useWallet();
+  const toast = useTransactionToast();
+
+  const sendGasless = useCallback(
+    async ({ instructions, onSuccess, onError }: GaslessOptions) => {
+      if (!publicKey || !signTransaction) {
+        throw new Error("Wallet not connected or does not support signing");
+      }
+
+      toast.start();
+
+      try {
+        // 1. Build unsigned transaction with server's fee payer
+        const { blockhash, lastValidBlockHeight } =
+          await connection.getLatestBlockhash("confirmed");
+
+        const messageV0 = new TransactionMessage({
+          payerKey: FEE_PAYER_PUBKEY, // Fee payer is the server
+          recentBlockhash: blockhash,
+          instructions,
+        }).compileToV0Message();
+
+        const transaction = new VersionedTransaction(messageV0);
+
+        // 2. Send to server for fee payer signature
+        const response = await fetch("/api/sponsor-transaction", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            serializedTransaction: Buffer.from(
+              transaction.serialize(),
+            ).toString("base64"),
+            userWallet: publicKey.toBase58(),
+          }),
+        });
+
+        if (!response.ok) {
+          const err = await response.json();
+          throw new Error(err.error ?? "Server sponsorship failed");
+        }
+
+        const { signedTransaction } = await response.json();
+
+        // 3. Deserialize server-signed tx and co-sign with user wallet
+        const serverSignedTx = VersionedTransaction.deserialize(
+          Buffer.from(signedTransaction, "base64"),
+        );
+
+        toast.sending();
+        const userSignedTx = await signTransaction(serverSignedTx);
+
+        // 4. Send the fully signed transaction
+        const signature = await connection.sendRawTransaction(
+          userSignedTx.serialize(),
+          { skipPreflight: false },
+        );
+
+        toast.confirming(signature);
+
+        await connection.confirmTransaction(
+          { signature, blockhash, lastValidBlockHeight },
+          "confirmed",
+        );
+
+        toast.confirmed();
+        onSuccess?.(signature);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        toast.fail(error);
+        onError?.(error);
+      }
+    },
+    [publicKey, signTransaction, connection, toast],
+  );
+
+  return { sendGasless };
+}
+```
+
+### 2.4 Usage Example
+
+```tsx
+import { useGaslessTransaction } from "@/hooks/useGaslessTransaction";
+import { SystemProgram, PublicKey } from "@solana/web3.js";
+
+function MintButton() {
+  const { sendGasless } = useGaslessTransaction();
+
+  const handleMint = () => {
+    sendGasless({
+      instructions: [
+        // Your program instructions here — user doesn't pay any SOL
+        SystemProgram.transfer({
+          fromPubkey: new PublicKey("..."),
+          toPubkey: new PublicKey("..."),
+          lamports: 0,
+        }),
+      ],
+      onSuccess: (sig) => console.log("Minted!", sig),
+    });
+  };
+
+  return <button onClick={handleMint}>Mint (Free!)</button>;
+}
+```
+
+---
+
+## Step 3 — Octane Relay Setup
+
+If the user chose **Octane**, guide them through:
+
+1. **Deploy Octane** — self-hosted or use a public relay.
+2. **Configure token payment** — users pay fees in USDC/BONK instead of SOL.
+3. **Client integration** — similar to above but POST to Octane endpoint.
+
+Reference: [Octane GitHub](https://github.com/solana-labs/octane)
+
+Provide a trimmed integration snippet:
+
+```typescript
+// Using Octane as a relay
+const octaneEndpoint = "https://your-octane-instance.com/api/v1/transfer";
+
+const response = await fetch(octaneEndpoint, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    transaction: Buffer.from(transaction.serialize()).toString("base64"),
+    // Octane deducts fee from user's token account instead of SOL
+    tokenMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
+  }),
+});
+```
+
+---
+
+## Step 4 — Session Keys (Advanced)
+
+If the user chose **session keys**, guide them through:
+
+1. **Generate ephemeral keypair** in the browser.
+2. **User approves a delegate** — an on-chain instruction that grants the
+   session key permission to sign on behalf of the user for N minutes.
+3. **Auto-sign** transactions with the session key (no wallet popups).
+4. **Expire / revoke** the session key after timeout or user logout.
+
+> ⚠️ **Security warning:** Session keys must be scoped to specific programs
+> and expire. Never grant blanket signing authority.
+
+```typescript
+// Simplified session key flow
+import { Keypair } from "@solana/web3.js";
+
+// 1. Generate ephemeral key (lives only in browser memory)
+const sessionKey = Keypair.generate();
+
+// 2. User signs a "create session" instruction delegating
+//    authority to sessionKey.publicKey for 30 minutes
+const createSessionIx = yourProgram.methods
+  .createSession({
+    delegate: sessionKey.publicKey,
+    expiresAt: Math.floor(Date.now() / 1000) + 1800,
+    allowedPrograms: [YOUR_PROGRAM_ID],
+  })
+  .accounts({ authority: userWallet })
+  .instruction();
+
+// 3. Subsequent transactions are signed by sessionKey — no wallet popup
+const tx = new VersionedTransaction(message);
+tx.sign([sessionKey]); // Instant, no user interaction
+await connection.sendRawTransaction(tx.serialize());
+```
+
+---
+
+## Step 5 — Security Checklist
+
+Before deploying any gasless flow, verify:
+
+- [ ] Fee payer private key is stored in environment variables, never in code.
+- [ ] Rate limiting is enforced per-wallet (prevent draining).
+- [ ] Server validates that instructions target only expected program IDs.
+- [ ] Fee payer balance is monitored with alerts (< 1 SOL triggers warning).
+- [ ] Transaction simulation runs before fee payer signs.
+- [ ] CORS is restricted to your frontend domain.
+- [ ] HTTPS is enforced on the relay/API endpoint.
+
+---
+
+## Step 6 — Offer Follow-Up
+
+After implementing gasless flows, offer:
+
+1. **"Want me to audit the overall UX?"** → Load [ux-audit.md](./ux-audit.md).
+2. **"Want me to scaffold remaining UI components?"** → Load
+   [scaffold-ui.md](./scaffold-ui.md).
diff --git a/agent-ux-skill/skill/scaffold-ui.md b/agent-ux-skill/skill/scaffold-ui.md
new file mode 100644
index 0000000..42df583
--- /dev/null
+++ b/agent-ux-skill/skill/scaffold-ui.md
@@ -0,0 +1,588 @@
+# Scaffold UI — Solana Wallet & Transaction Components
+
+You are scaffolding **production-ready** frontend components for a Solana dApp.
+All templates target the 2026 Solana stack: `@solana/web3.js` v2,
+`@solana/wallet-adapter-react` v0.15+, and React 19 / Vue 3.5+.
+
+---
+
+## Step 1 — Determine Scope
+
+Ask the user which components they need. Default to **all** if unspecified:
+
+| Component                | Description                                      |
+|--------------------------|--------------------------------------------------|
+| `WalletConnectionGuard`  | Wraps pages that require a connected wallet.     |
+| `TransactionToast`       | Real-time tx status (pending → confirmed → done).|
+| `SendTransactionButton`  | One-click send with simulation, retry, and fees. |
+| `ErrorBoundary`          | Catches and decodes Solana/Anchor errors.        |
+| `PriorityFeeSelector`    | UI for users to pick tx speed (low/med/high).    |
+
+Also ask:
+- **Framework:** React (default) or Vue 3.
+- **Styling:** Tailwind, CSS Modules, or Vanilla CSS. Default: CSS Modules.
+- **State management:** React Context (default), Zustand, or Jotai.
+
+---
+
+## Step 2 — Generate Components
+
+### 2.1 WalletConnectionGuard (React)
+
+```tsx
+// components/WalletConnectionGuard.tsx
+"use client";
+
+import { useWallet } from "@solana/wallet-adapter-react";
+import { WalletMultiButton } from "@solana/wallet-adapter-react-ui";
+import type { ReactNode } from "react";
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+export function WalletConnectionGuard({ children, fallback }: Props) {
+  const { connected, connecting } = useWallet();
+
+  if (connecting) {
+    return (
+      <div className="wallet-guard wallet-guard--connecting" role="status">
+        <span className="spinner" aria-label="Connecting wallet…" />
+        <p>Connecting wallet…</p>
+      </div>
+    );
+  }
+
+  if (!connected) {
+    return (
+      fallback ?? (
+        <div className="wallet-guard wallet-guard--disconnected">
+          <h2>Connect Your Wallet</h2>
+          <p>You need a Solana wallet to use this app.</p>
+          <WalletMultiButton />
+        </div>
+      )
+    );
+  }
+
+  return <>{children}</>;
+}
+```
+
+### 2.2 TransactionToast (React)
+
+```tsx
+// components/TransactionToast.tsx
+"use client";
+
+import { useCallback, useState, useRef, useEffect } from "react";
+import type { TransactionSignature } from "@solana/web3.js";
+
+type TxStatus = "idle" | "signing" | "sending" | "confirming" | "confirmed" | "error";
+
+interface TxState {
+  status: TxStatus;
+  signature?: TransactionSignature;
+  error?: string;
+  explorerUrl?: string;
+}
+
+const EXPLORER_BASE = "https://explorer.solana.com/tx/";
+
+export function useTransactionToast(cluster: "mainnet-beta" | "devnet" = "mainnet-beta") {
+  const [state, setState] = useState<TxState>({ status: "idle" });
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>();
+
+  const update = useCallback((patch: Partial<TxState>) => {
+    setState((prev) => ({ ...prev, ...patch }));
+  }, []);
+
+  const start = useCallback(() => update({ status: "signing", error: undefined }), [update]);
+  const sending = useCallback(() => update({ status: "sending" }), [update]);
+
+  const confirming = useCallback(
+    (signature: TransactionSignature) =>
+      update({
+        status: "confirming",
+        signature,
+        explorerUrl: `${EXPLORER_BASE}${signature}?cluster=${cluster}`,
+      }),
+    [update, cluster],
+  );
+
+  const confirmed = useCallback(() => {
+    update({ status: "confirmed" });
+    timeoutRef.current = setTimeout(() => update({ status: "idle" }), 5000);
+  }, [update]);
+
+  const fail = useCallback(
+    (error: unknown) =>
+      update({
+        status: "error",
+        error: error instanceof Error ? error.message : String(error),
+      }),
+    [update],
+  );
+
+  const reset = useCallback(() => setState({ status: "idle" }), []);
+
+  useEffect(() => () => clearTimeout(timeoutRef.current), []);
+
+  return { state, start, sending, confirming, confirmed, fail, reset };
+}
+
+export function TransactionToast({ state }: { state: TxState }) {
+  if (state.status === "idle") return null;
+
+  const statusMap: Record<TxStatus, { label: string; icon: string }> = {
+    idle: { label: "", icon: "" },
+    signing: { label: "Waiting for wallet approval…", icon: "✍️" },
+    sending: { label: "Sending transaction…", icon: "📡" },
+    confirming: { label: "Confirming on-chain…", icon: "⏳" },
+    confirmed: { label: "Transaction confirmed!", icon: "✅" },
+    error: { label: state.error ?? "Transaction failed", icon: "❌" },
+  };
+
+  const { label, icon } = statusMap[state.status];
+
+  return (
+    <div
+      className={`tx-toast tx-toast--${state.status}`}
+      role="alert"
+      aria-live="polite"
+    >
+      <span className="tx-toast__icon">{icon}</span>
+      <span className="tx-toast__label">{label}</span>
+      {state.explorerUrl && (
+        <a
+          href={state.explorerUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="tx-toast__link"
+        >
+          View on Explorer ↗
+        </a>
+      )}
+    </div>
+  );
+}
+```
+
+### 2.3 SendTransactionButton (React)
+
+```tsx
+// components/SendTransactionButton.tsx
+"use client";
+
+import { useConnection, useWallet } from "@solana/wallet-adapter-react";
+import {
+  TransactionMessage,
+  VersionedTransaction,
+  ComputeBudgetProgram,
+  type TransactionInstruction,
+} from "@solana/web3.js";
+import { useCallback, useState } from "react";
+import { useTransactionToast } from "./TransactionToast";
+
+interface Props {
+  instructions: TransactionInstruction[];
+  label?: string;
+  computeUnits?: number;
+  priorityFee?: number; // micro-lamports per CU
+  onSuccess?: (signature: string) => void;
+  onError?: (error: Error) => void;
+  className?: string;
+  disabled?: boolean;
+}
+
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 1500;
+
+export function SendTransactionButton({
+  instructions,
+  label = "Send Transaction",
+  computeUnits = 200_000,
+  priorityFee = 1_000,
+  onSuccess,
+  onError,
+  className,
+  disabled,
+}: Props) {
+  const { connection } = useConnection();
+  const { publicKey, sendTransaction } = useWallet();
+  const toast = useTransactionToast();
+  const [busy, setBusy] = useState(false);
+
+  const handleSend = useCallback(async () => {
+    if (!publicKey) return;
+    setBusy(true);
+    toast.start();
+
+    try {
+      // Prepend compute budget instructions
+      const budgetIxs = [
+        ComputeBudgetProgram.setComputeUnitLimit({ units: computeUnits }),
+        ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityFee }),
+      ];
+
+      const allInstructions = [...budgetIxs, ...instructions];
+
+      let lastError: Error | null = null;
+
+      for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+        try {
+          const { blockhash, lastValidBlockHeight } =
+            await connection.getLatestBlockhash("confirmed");
+
+          const messageV0 = new TransactionMessage({
+            payerKey: publicKey,
+            recentBlockhash: blockhash,
+            instructions: allInstructions,
+          }).compileToV0Message();
+
+          const transaction = new VersionedTransaction(messageV0);
+
+          toast.sending();
+
+          const signature = await sendTransaction(transaction, connection, {
+            skipPreflight: false,
+            maxRetries: 2,
+          });
+
+          toast.confirming(signature);
+
+          await connection.confirmTransaction(
+            { signature, blockhash, lastValidBlockHeight },
+            "confirmed",
+          );
+
+          toast.confirmed();
+          onSuccess?.(signature);
+          setBusy(false);
+          return;
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error(String(err));
+
+          const isRetryable =
+            lastError.message.includes("BlockhashNotFound") ||
+            lastError.message.includes("block height exceeded");
+
+          if (!isRetryable || attempt === MAX_RETRIES - 1) break;
+
+          await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * (attempt + 1)));
+        }
+      }
+
+      throw lastError ?? new Error("Transaction failed after retries");
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      toast.fail(error);
+      onError?.(error);
+    } finally {
+      setBusy(false);
+    }
+  }, [
+    publicKey,
+    connection,
+    sendTransaction,
+    instructions,
+    computeUnits,
+    priorityFee,
+    toast,
+    onSuccess,
+    onError,
+  ]);
+
+  return (
+    <button
+      onClick={handleSend}
+      disabled={disabled || busy || !publicKey}
+      className={`send-tx-btn ${busy ? "send-tx-btn--busy" : ""} ${className ?? ""}`}
+      aria-busy={busy}
+    >
+      {busy ? "Processing…" : label}
+    </button>
+  );
+}
+```
+
+### 2.4 ErrorBoundary (React)
+
+```tsx
+// components/SolanaErrorBoundary.tsx
+"use client";
+
+import { Component, type ReactNode, type ErrorInfo } from "react";
+
+// Common Anchor / Solana error code mappings
+const KNOWN_ERRORS: Record<number, string> = {
+  0x0: "Unknown error",
+  0x1: "Insufficient funds for transaction",
+  0x3: "Account already in use",
+  0x5: "Invalid program argument",
+  0x11: "Borsh deserialization failed — check instruction data",
+  0x12: "Borsh serialization failed",
+  0x64: "Account not initialized",
+  0xbc: "Token account not found",
+  0x1194: "Anchor: Constraint violated",
+  0x1195: "Anchor: Account discriminator mismatch",
+  0x1770: "Anchor: Declared program ID mismatch",
+  0x1771: "Anchor: IDL instruction not found",
+  6000: "Custom program error — check program logs",
+};
+
+interface Props {
+  children: ReactNode;
+  fallback?: (props: { error: Error; reset: () => void }) => ReactNode;
+}
+
+interface State {
+  error: Error | null;
+}
+
+export class SolanaErrorBoundary extends Component<Props, State> {
+  state: State = { error: null };
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error("[SolanaErrorBoundary]", error, info.componentStack);
+  }
+
+  reset = () => this.setState({ error: null });
+
+  decodeError(error: Error): string {
+    const msg = error.message;
+
+    // Try to extract Anchor error code: "custom program error: 0x1194"
+    const hexMatch = msg.match(/custom program error:\s*0x([0-9a-fA-F]+)/i);
+    if (hexMatch) {
+      const code = parseInt(hexMatch[1], 16);
+      return KNOWN_ERRORS[code] ?? `Program error 0x${hexMatch[1]}`;
+    }
+
+    // Try decimal: "Error Code: 6001"
+    const decMatch = msg.match(/Error Code:\s*(\d+)/);
+    if (decMatch) {
+      const code = parseInt(decMatch[1], 10);
+      return KNOWN_ERRORS[code] ?? `Program error #${code}`;
+    }
+
+    // Wallet rejection
+    if (msg.includes("User rejected")) return "You cancelled the transaction.";
+
+    // Timeout
+    if (msg.includes("Transaction was not confirmed in"))
+      return "Transaction timed out. The network may be congested — try again.";
+
+    return msg;
+  }
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+
+    if (this.props.fallback) {
+      return this.props.fallback({ error, reset: this.reset });
+    }
+
+    return (
+      <div className="sol-error-boundary" role="alert">
+        <h3>⚠️ Something went wrong</h3>
+        <p className="sol-error-boundary__msg">{this.decodeError(error)}</p>
+        <details>
+          <summary>Technical details</summary>
+          <pre>{error.message}</pre>
+        </details>
+        <button onClick={this.reset} className="sol-error-boundary__retry">
+          Try Again
+        </button>
+      </div>
+    );
+  }
+}
+```
+
+### 2.5 PriorityFeeSelector (React)
+
+```tsx
+// components/PriorityFeeSelector.tsx
+"use client";
+
+import { useConnection } from "@solana/wallet-adapter-react";
+import { useState, useEffect, useCallback } from "react";
+import type { PublicKey } from "@solana/web3.js";
+
+interface Props {
+  programIds?: PublicKey[];
+  onChange: (microLamports: number) => void;
+  defaultTier?: "low" | "medium" | "high";
+}
+
+interface FeeTiers {
+  low: number;
+  medium: number;
+  high: number;
+}
+
+export function PriorityFeeSelector({
+  programIds,
+  onChange,
+  defaultTier = "medium",
+}: Props) {
+  const { connection } = useConnection();
+  const [tiers, setTiers] = useState<FeeTiers>({ low: 100, medium: 1_000, high: 50_000 });
+  const [selected, setSelected] = useState<keyof FeeTiers>(defaultTier);
+  const [loading, setLoading] = useState(true);
+
+  const fetchFees = useCallback(async () => {
+    setLoading(true);
+    try {
+      const fees = await connection.getRecentPrioritizationFees({
+        lockedWritableAccounts: programIds ?? [],
+      });
+
+      if (fees.length === 0) {
+        setLoading(false);
+        return;
+      }
+
+      const sorted = fees
+        .map((f) => f.prioritizationFee)
+        .filter((f) => f > 0)
+        .sort((a, b) => a - b);
+
+      if (sorted.length > 0) {
+        const p25 = sorted[Math.floor(sorted.length * 0.25)] ?? 100;
+        const p50 = sorted[Math.floor(sorted.length * 0.5)] ?? 1_000;
+        const p75 = sorted[Math.floor(sorted.length * 0.75)] ?? 50_000;
+        setTiers({ low: p25, medium: p50, high: p75 });
+      }
+    } catch (err) {
+      console.warn("Failed to fetch priority fees, using defaults", err);
+    } finally {
+      setLoading(false);
+    }
+  }, [connection, programIds]);
+
+  useEffect(() => {
+    fetchFees();
+  }, [fetchFees]);
+
+  useEffect(() => {
+    onChange(tiers[selected]);
+  }, [selected, tiers, onChange]);
+
+  const tierConfig = [
+    { key: "low" as const, label: "🐢 Slow", desc: "Lower cost, slower landing" },
+    { key: "medium" as const, label: "⚡ Standard", desc: "Balanced speed & cost" },
+    { key: "high" as const, label: "🚀 Fast", desc: "Higher cost, faster landing" },
+  ];
+
+  return (
+    <fieldset className="fee-selector" disabled={loading}>
+      <legend className="fee-selector__legend">Transaction Speed</legend>
+      <div className="fee-selector__options">
+        {tierConfig.map(({ key, label, desc }) => (
+          <label
+            key={key}
+            className={`fee-selector__option ${
+              selected === key ? "fee-selector__option--active" : ""
+            }`}
+          >
+            <input
+              type="radio"
+              name="priorityFee"
+              value={key}
+              checked={selected === key}
+              onChange={() => setSelected(key)}
+              className="sr-only"
+            />
+            <span className="fee-selector__label">{label}</span>
+            <span className="fee-selector__desc">{desc}</span>
+            <span className="fee-selector__price">
+              {loading ? "…" : `${tiers[key].toLocaleString()} µL/CU`}
+            </span>
+          </label>
+        ))}
+      </div>
+    </fieldset>
+  );
+}
+```
+
+---
+
+## Step 3 — Vue 3 Variants
+
+If the user selected **Vue 3**, adapt each component above to Vue 3 Composition API
+(`<script setup lang="ts">`). Key differences:
+
+- Replace `useWallet()` with `useWallet()` from `solana-wallets-vue`.
+- Replace `useConnection()` with `useConnection()` from `solana-wallets-vue`.
+- Use `ref()` / `computed()` instead of `useState` / `useMemo`.
+- Use `<Teleport to="body">` for toast overlay.
+- Use `onErrorCaptured` lifecycle hook instead of Error Boundary class.
+
+Generate equivalent `.vue` SFCs following the same logic and structure as the
+React versions above.
+
+---
+
+## Step 4 — Wiring Instructions
+
+After generating the components, provide the user with:
+
+1. **Dependency installation command:**
+
+```bash
+npm install @solana/web3.js@^2 @solana/wallet-adapter-react @solana/wallet-adapter-react-ui @solana/wallet-adapter-wallets
+```
+
+2. **App-level provider setup** (`_app.tsx` or `layout.tsx`):
+
+```tsx
+import { ConnectionProvider, WalletProvider } from "@solana/wallet-adapter-react";
+import { WalletModalProvider } from "@solana/wallet-adapter-react-ui";
+import {
+  PhantomWalletAdapter,
+  SolflareWalletAdapter,
+  BackpackWalletAdapter,
+} from "@solana/wallet-adapter-wallets";
+import "@solana/wallet-adapter-react-ui/styles.css";
+
+const wallets = [
+  new PhantomWalletAdapter(),
+  new SolflareWalletAdapter(),
+  new BackpackWalletAdapter(),
+];
+
+export default function App({ children }: { children: React.ReactNode }) {
+  return (
+    <ConnectionProvider endpoint={process.env.NEXT_PUBLIC_RPC_URL!}>
+      <WalletProvider wallets={wallets} autoConnect>
+        <WalletModalProvider>
+          <SolanaErrorBoundary>
+            {children}
+          </SolanaErrorBoundary>
+        </WalletModalProvider>
+      </WalletProvider>
+    </ConnectionProvider>
+  );
+}
+```
+
+3. **File placement guidance** — tell the user where to place each file in
+   their existing project structure.
+
+---
+
+## Step 5 — Offer Follow-Up
+
+After scaffolding, offer:
+
+1. **"Want me to audit your existing UX?"** → Load [ux-audit.md](./ux-audit.md).
+2. **"Want to add gasless transactions?"** → Load [gasless-flow.md](./gasless-flow.md).
diff --git a/agent-ux-skill/skill/ux-audit.md b/agent-ux-skill/skill/ux-audit.md
new file mode 100644
index 0000000..15d9148
--- /dev/null
+++ b/agent-ux-skill/skill/ux-audit.md
@@ -0,0 +1,138 @@
+# UX Audit — Transaction Flow Analysis
+
+You are performing a **Solana dApp UX audit**. Your goal is to analyze the
+user's transaction flow (on-chain program calls, wallet interactions, and
+frontend signing logic) and produce a structured optimization report.
+
+---
+
+## Step 1 — Gather Context
+
+Ask the user for the following. Accept whatever subset they provide:
+
+| Input                        | Required | Notes                                             |
+|------------------------------|----------|---------------------------------------------------|
+| Program ID(s)                | Yes      | The on-chain program addresses the dApp calls.    |
+| Frontend framework           | No       | React / Next.js / Vue / Svelte. Default: React.   |
+| Wallet adapter version       | No       | `@solana/wallet-adapter-*` version.               |
+| RPC endpoint                 | No       | Mainnet / Devnet / custom. Default: Mainnet-beta. |
+| Sample transaction signature | No       | A recent tx sig for on-chain inspection.          |
+| Known pain points            | No       | Any UX complaints from real users.                |
+
+If the user provides a **transaction signature**, use `@solana/web3.js` v2
+(`getTransaction` with `maxSupportedTransactionVersion`) to fetch and parse it.
+
+---
+
+## Step 2 — Analyze Transaction Flow
+
+Run through this checklist against the user's codebase and/or on-chain data:
+
+### 2.1 Wallet Connection
+
+- [ ] Is the wallet adapter wrapped at the app root (`WalletProvider`)?
+- [ ] Are multiple wallet adapters registered (Phantom, Solflare, Backpack, etc.)?
+- [ ] Is auto-connect enabled with a persisted adapter name?
+- [ ] Does the UI degrade gracefully when no wallet is installed?
+- [ ] Is `WalletMultiButton` or a custom equivalent used?
+- [ ] Are connection errors surfaced to the user (not swallowed)?
+
+### 2.2 Transaction Construction
+
+- [ ] Are transactions using Versioned Transactions (`VersionedTransaction`)?
+- [ ] Is `ComputeBudgetProgram.setComputeUnitLimit` called with a right-sized value?
+- [ ] Is `ComputeBudgetProgram.setComputeUnitPrice` used for priority fees?
+- [ ] Are priority fee estimates fetched dynamically (`getRecentPrioritizationFees`)?
+- [ ] Is `getLatestBlockhash` called with `confirmed` commitment?
+- [ ] Are lookup tables (ALTs) used when instruction count > 4?
+
+### 2.3 Transaction Signing & Sending
+
+- [ ] Is `sendTransaction` used instead of `signTransaction` + `sendRawTransaction` (unless batching)?
+- [ ] Is `skipPreflight: false` the default (preflight catches errors early)?
+- [ ] Is transaction confirmation awaited with `confirmTransaction` using `blockhash` strategy?
+- [ ] Is there a retry mechanism with exponential backoff on `BlockhashNotFound`?
+- [ ] Are simulation errors decoded and shown to the user in plain language?
+
+### 2.4 Error Handling & Feedback
+
+- [ ] Are Anchor/program-specific error codes decoded to human-readable messages?
+- [ ] Is there a loading state shown during signing, sending, and confirmation?
+- [ ] Is the user notified of success with a Solana Explorer / SolanaFM link?
+- [ ] Are timeout errors (> 60s confirmation) handled with a "retry" affordance?
+- [ ] Is there a React Error Boundary wrapping transaction-related components?
+
+### 2.5 Mobile & Responsive
+
+- [ ] Does the wallet adapter detect mobile wallets (e.g., Phantom mobile deep-links)?
+- [ ] Is the signing modal usable on viewports < 400px?
+- [ ] Are touch targets ≥ 44×44px?
+
+---
+
+## Step 3 — Generate the UX Audit Report
+
+Output a structured markdown report using this exact template:
+
+```markdown
+# 🔍 Solana dApp UX Audit Report
+
+**dApp:** {name or Program ID}
+**Date:** {ISO 8601}
+**Framework:** {React | Vue | …}
+**Network:** {Mainnet | Devnet}
+
+---
+
+## Executive Summary
+
+{2–3 sentence summary of overall UX health. Mention the critical-severity count.}
+
+## Findings
+
+### 🔴 Critical
+
+{Each finding as a bullet: **Issue** — description — **Fix** — concrete code change.}
+
+### 🟡 Warning
+
+{Same format.}
+
+### 🟢 Info / Best Practice
+
+{Same format.}
+
+## Priority Fee Recommendation
+
+Based on recent network conditions:
+- **Low priority:** {x} micro-lamports/CU
+- **Medium priority:** {y} micro-lamports/CU
+- **High priority:** {z} micro-lamports/CU
+
+Recommend dynamically fetching via `getRecentPrioritizationFees` targeting the
+program addresses involved.
+
+## Recommended Architecture
+
+{ASCII or mermaid diagram showing the ideal transaction lifecycle:
+  User Action → Build Tx → Simulate → Sign → Send → Confirm → UI Feedback}
+
+## Next Steps
+
+- [ ] {Actionable item 1}
+- [ ] {Actionable item 2}
+- [ ] {Actionable item 3}
+```
+
+---
+
+## Step 4 — Offer Follow-Up
+
+After delivering the report, offer:
+
+1. **"Want me to scaffold the fixed components?"** → Load
+   [scaffold-ui.md](./scaffold-ui.md).
+2. **"Want me to add gasless transactions?"** → Load
+   [gasless-flow.md](./gasless-flow.md).
+3. **"Want me to fix these issues in your codebase directly?"** → Proceed to
+   edit the user's files using the findings above.