diff --git a/jest.config.js b/jest.config.js
index 8af58ee4..a955000d 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -9,10 +9,31 @@ const config = {
   moduleNameMapper: {
     "^@/(.*)$": "<rootDir>/src/$1",
   },
-  testMatch: ["**/__tests__/**/*.(test|spec).(ts|tsx)"],
+  testMatch: [
+    "**/__tests__/**/*.(test|spec).(ts|tsx)",
+    "**/__tests__/**/*.(test|spec).(js|jsx)",
+  ],
   testPathIgnorePatterns: ["/node_modules/", "/src/app/search/__tests__/"],
-  collectCoverageFrom: ["src/components/**/*.{ts,tsx}", "!src/components/**/*.d.ts"],
-  coverageThreshold: { global: { branches: 80, functions: 80, lines: 80, statements: 80 } },
+  collectCoverageFrom: [
+    "src/components/**/*.{ts,tsx}",
+    "src/lib/errors/**/*.{ts,tsx}",
+    "src/lib/retry/**/*.{ts,tsx}",
+    "src/lib/offline/**/*.{ts,tsx}",
+    "src/lib/api/**/*.{ts,tsx}",
+    "!src/components/**/*.d.ts",
+    "!src/lib/**/*.d.ts",
+    "!src/lib/**/index.ts",
+  ],
+  coverageThreshold: {
+    global: { branches: 80, functions: 80, lines: 80, statements: 80 },
+    "./src/lib/errors/": { branches: 85, functions: 85, lines: 85, statements: 85 },
+    "./src/lib/retry/": { branches: 85, functions: 85, lines: 85, statements: 85 },
+    "./src/lib/offline/": { branches: 80, functions: 80, lines: 80, statements: 80 },
+  },
+  coveragePathIgnorePatterns: ["/node_modules/", "/__tests__/", "/__mocks__/"],
+  testTimeout: 10000,
+  clearMocks: true,
+  restoreMocks: true,
 };
 
-module.exports = createJestConfig(config);
+module.exports = createJestConfig(config);
\ No newline at end of file
diff --git a/jest.setup.ts b/jest.setup.ts
index d0de870d..c8c17382 100644
--- a/jest.setup.ts
+++ b/jest.setup.ts
@@ -1 +1,362 @@
 import "@testing-library/jest-dom";
+
+/**
+ * Global Jest setup.
+ *
+ * Provides reliable mocks for browser APIs used by the error handling,
+ * retry, and offline queue features so tests run deterministically in jsdom.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*                              IndexedDB mock                                */
+/* -------------------------------------------------------------------------- */
+
+type StoreRecord = Record<string, unknown>;
+
+class MockIDBRequest<T = unknown> {
+  result: T | undefined = undefined;
+  error: Error | null = null;
+  readyState: "pending" | "done" = "pending";
+  source: unknown = null;
+  transaction: unknown = null;
+  onsuccess: ((event: unknown) => void) | null = null;
+  onerror: ((event: unknown) => void) | null = null;
+
+  addEventListener(type: string, listener: (event: unknown) => void): void {
+    if (type === "success") this.onsuccess = listener;
+    if (type === "error") this.onerror = listener;
+  }
+
+  removeEventListener(type: string, listener: (event: unknown) => void): void {
+    if (type === "success" && this.onsuccess === listener) this.onsuccess = null;
+    if (type === "error" && this.onerror === listener) this.onerror = null;
+  }
+}
+
+class MockIDBObjectStore {
+  constructor(
+    private readonly data: Map<string, StoreRecord>,
+    private readonly name: string,
+  ) {}
+
+  private schedule<T>(request: MockIDBRequest<T>, fn: () => T): MockIDBRequest<T> {
+    queueMicrotask(() => {
+      try {
+        request.result = fn();
+        request.readyState = "done";
+        request.onsuccess?.({ target: request });
+      } catch (err) {
+        request.error = err as Error;
+        request.readyState = "done";
+        request.onerror?.({ target: request });
+      }
+    });
+    return request;
+  }
+
+  put(value: StoreRecord, key?: string): MockIDBRequest<string> {
+    const request = new MockIDBRequest<string>();
+    const recordKey = key ?? (value.id as string) ?? String(Date.now());
+    return this.schedule(request, () => {
+      this.data.set(recordKey, { ...value });
+      return recordKey;
+    });
+  }
+
+  add(value: StoreRecord, key?: string): MockIDBRequest<string> {
+    return this.put(value, key);
+  }
+
+  get(key: string): MockIDBRequest<StoreRecord | undefined> {
+    const request = new MockIDBRequest<StoreRecord | undefined>();
+    return this.schedule(request, () => this.data.get(key));
+  }
+
+  getAll(): MockIDBRequest<StoreRecord[]> {
+    const request = new MockIDBRequest<StoreRecord[]>();
+    return this.schedule(request, () => Array.from(this.data.values()));
+  }
+
+  delete(key: string): MockIDBRequest<undefined> {
+    const request = new MockIDBRequest<undefined>();
+    return this.schedule(request, () => {
+      this.data.delete(key);
+      return undefined;
+    });
+  }
+
+  clear(): MockIDBRequest<undefined> {
+    const request = new MockIDBRequest<undefined>();
+    return this.schedule(request, () => {
+      this.data.clear();
+      return undefined;
+    });
+  }
+
+  count(): MockIDBRequest<number> {
+    const request = new MockIDBRequest<number>();
+    return this.schedule(request, () => this.data.size);
+  }
+
+  createIndex(): unknown {
+    return {};
+  }
+
+  index(): unknown {
+    return {};
+  }
+
+  get name_(): string {
+    return this.name;
+  }
+}
+
+class MockIDBTransaction {
+  oncomplete: ((event: unknown) => void) | null = null;
+  onerror: ((event: unknown) => void) | null = null;
+  onabort: ((event: unknown) => void) | null = null;
+  error: Error | null = null;
+  mode: string;
+
+  constructor(
+    private readonly db: MockIDBDatabase,
+    storeNames: string | string[],
+    mode: string = "readonly",
+  ) {
+    this.mode = mode;
+    this.storeNames = Array.isArray(storeNames) ? storeNames : [storeNames];
+    queueMicrotask(() => this.oncomplete?.({ target: this }));
+  }
+
+  storeNames: string[];
+
+  objectStore(name: string): MockIDBObjectStore {
+    return this.db.getStore(name);
+  }
+
+  abort(): void {
+    this.onabort?.({ target: this });
+  }
+}
+
+class MockIDBDatabase {
+  readonly name: string;
+  readonly version: number;
+  readonly objectStoreNames: { contains: (name: string) => boolean };
+  onclose: (() => void) | null = null;
+  onerror: ((event: unknown) => void) | null = null;
+  onversionchange: ((event: unknown) => void) | null = null;
+
+  private readonly stores = new Map<string, Map<string, StoreRecord>>();
+
+  constructor(name: string, version: number) {
+    this.name = name;
+    this.version = version;
+    this.objectStoreNames = {
+      contains: (storeName: string) => this.stores.has(storeName),
+    };
+  }
+
+  getStore(name: string): MockIDBObjectStore {
+    let data = this.stores.get(name);
+    if (!data) {
+      data = new Map<string, StoreRecord>();
+      this.stores.set(name, data);
+    }
+    return new MockIDBObjectStore(data, name);
+  }
+
+  createObjectStore(name: string): MockIDBObjectStore {
+    return this.getStore(name);
+  }
+
+  deleteObjectStore(name: string): void {
+    this.stores.delete(name);
+  }
+
+  transaction(
+    storeNames: string | string[],
+    mode: string = "readonly",
+  ): MockIDBTransaction {
+    return new MockIDBTransaction(this, storeNames, mode);
+  }
+
+  close(): void {
+    this.onclose?.();
+  }
+}
+
+class MockIDBOpenDBRequest extends MockIDBRequest<MockIDBDatabase> {
+  onupgradeneeded: ((event: unknown) => void) | null = null;
+  onblocked: ((event: unknown) => void) | null = null;
+}
+
+const openDatabases = new Map<string, MockIDBDatabase>();
+
+const mockIndexedDB = {
+  open(name: string, version: number = 1): MockIDBOpenDBRequest {
+    const request = new MockIDBOpenDBRequest();
+    queueMicrotask(() => {
+      try {
+        const existing = openDatabases.get(name);
+        const db = existing ?? new MockIDBDatabase(name, version);
+        const isNew = !existing;
+        openDatabases.set(name, db);
+        request.result = db;
+        if (isNew) {
+          request.onupgradeneeded?.({ target: request, oldVersion: 0, newVersion: version });
+        }
+        request.readyState = "done";
+        request.onsuccess?.({ target: request });
+      } catch (err) {
+        request.error = err as Error;
+        request.readyState = "done";
+        request.onerror?.({ target: request });
+      }
+    });
+    return request;
+  },
+
+  deleteDatabase(name: string): MockIDBRequest<undefined> {
+    const request = new MockIDBRequest<undefined>();
+    queueMicrotask(() => {
+      openDatabases.delete(name);
+      request.result = undefined;
+      request.readyState = "done";
+      request.onsuccess?.({ target: request });
+    });
+    return request;
+  },
+
+  cmp(a: unknown, b: unknown): number {
+    if (a === b) return 0;
+    return (a as number) < (b as number) ? -1 : 1;
+  },
+};
+
+Object.defineProperty(globalThis, "indexedDB", {
+  value: mockIndexedDB,
+  writable: true,
+  configurable: true,
+});
+
+Object.defineProperty(globalThis, "IDBKeyRange", {
+  value: {
+    only: (value: unknown) => ({ only: value }),
+    lowerBound: (value: unknown) => ({ lowerBound: value }),
+    upperBound: (value: unknown) => ({ upperBound: value }),
+    bound: (lower: unknown, upper: unknown) => ({ lower, upper }),
+  },
+  writable: true,
+  configurable: true,
+});
+
+/* -------------------------------------------------------------------------- */
+/*                          navigator.onLine mock                             */
+/* -------------------------------------------------------------------------- */
+
+let onlineState = true;
+
+Object.defineProperty(globalThis.navigator, "onLine", {
+  get: () => onlineState,
+  configurable: true,
+});
+
+/**
+ * Test helper: set the simulated connectivity state and dispatch the
+ * corresponding online/offline event on window.
+ */
+export function setOnlineState(online: boolean): void {
+  onlineState = online;
+  const event = new Event(online ? "online" : "offline");
+  window.dispatchEvent(event);
+}
+
+Object.defineProperty(globalThis, "__setOnlineState", {
+  value: setOnlineState,
+  writable: true,
+  configurable: true,
+});
+
+/* -------------------------------------------------------------------------- */
+/*                          online/offline events                             */
+/* -------------------------------------------------------------------------- */
+
+// jsdom does not implement online/offline events; ensure listeners work.
+if (typeof window !== "undefined") {
+  window.addEventListener("online", () => {
+    onlineState = true;
+  });
+  window.addEventListener("offline", () => {
+    onlineState = false;
+  });
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                  fetch mock                                */
+/* -------------------------------------------------------------------------- */
+
+type FetchMockHandler = (
+  input: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response> | Response;
+
+const defaultFetchHandler: FetchMockHandler = () =>
+  Promise.resolve(
+    new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    }),
+  );
+
+let fetchHandler: FetchMockHandler = defaultFetchHandler;
+
+const fetchMock = jest.fn((input: RequestInfo | URL, init?: RequestInit) =>
+  Promise.resolve(fetchHandler(input, init)),
+);
+
+Object.defineProperty(globalThis, "fetch", {
+  value: fetchMock,
+  writable: true,
+  configurable: true,
+});
+
+/**
+ * Test helper: override the fetch implementation for the current test.
+ */
+export function mockFetch(handler: FetchMockHandler): void {
+  fetchHandler = handler;
+}
+
+/**
+ * Test helper: reset fetch to the default successful response.
+ */
+export function resetFetchMock(): void {
+  fetchHandler = defaultFetchHandler;
+  fetchMock.mockClear();
+}
+
+Object.defineProperty(globalThis, "__mockFetch", {
+  value: mockFetch,
+  writable: true,
+  configurable: true,
+});
+
+Object.defineProperty(globalThis, "__resetFetchMock", {
+  value: resetFetchMock,
+  writable: true,
+  configurable: true,
+});
+
+/* -------------------------------------------------------------------------- */
+/*                              Global resets                                 */
+/* -------------------------------------------------------------------------- */
+
+beforeEach(() => {
+  onlineState = true;
+  resetFetchMock();
+});
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
\ No newline at end of file
diff --git a/playwright.config.ts b/playwright.config.ts
index b1992acd..466140b7 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -20,6 +20,26 @@ export default defineConfig({
       name: 'chromium',
       use: { ...devices['Desktop Chrome'] },
     },
+    {
+      name: 'error-handling',
+      testMatch: /error-handling\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'retry',
+      testMatch: /retry\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'offline-queue',
+      testMatch: /offline-queue\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'api-docs',
+      testMatch: /api-docs\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
   ],
 
   webServer: {
@@ -34,4 +54,4 @@ export default defineConfig({
       NEXT_PUBLIC_USDC_ADDRESS: process.env.NEXT_PUBLIC_USDC_ADDRESS || '',
     },
   },
-});
+});
\ No newline at end of file
diff --git a/public/openapi.json b/public/openapi.json
new file mode 100644
index 00000000..863f223f
--- /dev/null
+++ b/public/openapi.json
@@ -0,0 +1,707 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Task Manager API",
+    "version": "1.0.0",
+    "description": "Machine-readable OpenAPI 3.1 specification for the Task Manager API.\n\n## Overview\nThis document describes every public HTTP endpoint exposed by the service, including request/response schemas, worked examples, authentication requirements, and error scenarios aligned with the application's `AppError` taxonomy.\n\n## Authentication\nMost endpoints require a bearer token. Obtain a token from `POST /api/auth/login` and send it in the `Authorization` header:\n\n```\nAuthorization: Bearer <token>\n```\n\n## Error model\nAll errors are returned as JSON with the following shape:\n\n```json\n{\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"Human readable message\",\n    \"details\": [ { \"field\": \"email\", \"message\": \"must be a valid email\" } ],\n    \"requestId\": \"b3f1c2a4-...\"\n  }\n}\n```\n\nThe `code` field is drawn from the `AppError` taxonomy:\n\n| Code | HTTP status | Meaning |\n| --- | --- | --- |\n| `VALIDATION_ERROR` | 400 | Request body/query failed validation |\n| `UNAUTHORIZED` | 401 | Missing or invalid credentials/token |\n| `FORBIDDEN` | 403 | Authenticated but not allowed |\n| `NOT_FOUND` | 404 | Resource does not exist |\n| `CONFLICT` | 409 | Resource state conflict (e.g. duplicate email) |\n| `RATE_LIMITED` | 429 | Too many requests |\n| `INTERNAL_ERROR` | 500 | Unexpected server error |\n\n## Keeping this document in sync\nThis file is generated from the route definitions and Zod schemas. To regenerate after changing an endpoint:\n\n```bash\nnpm run docs:openapi   # regenerates public/openapi.json\nnpm run docs:lint      # validates the spec against OpenAPI 3.1\n```\n\nCI runs `docs:lint` and fails the build if the committed spec is stale or invalid. Do not hand-edit generated sections; update the source schemas instead.",
+    "contact": {
+      "name": "API Team",
+      "email": "api@example.com"
+    },
+    "license": {
+      "name": "MIT",
+      "url": "https://opensource.org/licenses/MIT"
+    }
+  },
+  "servers": [
+    {
+      "url": "http://localhost:3000",
+      "description": "Local development"
+    },
+    {
+      "url": "https://api.example.com",
+      "description": "Production"
+    }
+  ],
+  "tags": [
+    { "name": "Auth", "description": "Registration, login, and session management" },
+    { "name": "Users", "description": "User profile operations" },
+    { "name": "Tasks", "description": "Task CRUD operations" },
+    { "name": "Health", "description": "Service health and readiness" }
+  ],
+  "security": [{ "bearerAuth": [] }],
+  "paths": {
+    "/api/health": {
+      "get": {
+        "tags": ["Health"],
+        "summary": "Service health check",
+        "description": "Returns the current health status of the service. Does not require authentication.",
+        "operationId": "getHealth",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Service is healthy",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HealthResponse" },
+                "example": { "status": "ok", "uptime": 12345.67, "version": "1.0.0" }
+              }
+            }
+          },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    },
+    "/api/auth/register": {
+      "post": {
+        "tags": ["Auth"],
+        "summary": "Register a new user",
+        "description": "Creates a new user account and returns an access token.",
+        "operationId": "registerUser",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/RegisterRequest" },
+              "example": {
+                "email": "jane.doe@example.com",
+                "password": "S3cure!Passw0rd",
+                "name": "Jane Doe"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "User created",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/AuthResponse" },
+                "example": {
+                  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+                  "user": {
+                    "id": "usr_01HXYZ",
+                    "email": "jane.doe@example.com",
+                    "name": "Jane Doe",
+                    "createdAt": "2024-01-15T10:30:00.000Z"
+                  }
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/ValidationError" },
+          "409": {
+            "description": "Email already registered",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+                "example": {
+                  "error": {
+                    "code": "CONFLICT",
+                    "message": "A user with this email already exists",
+                    "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+                  }
+                }
+              }
+            }
+          },
+          "429": { "$ref": "#/components/responses/RateLimited" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    },
+    "/api/auth/login": {
+      "post": {
+        "tags": ["Auth"],
+        "summary": "Log in",
+        "description": "Authenticates a user and returns an access token.",
+        "operationId": "loginUser",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/LoginRequest" },
+              "example": {
+                "email": "jane.doe@example.com",
+                "password": "S3cure!Passw0rd"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Authenticated",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/AuthResponse" },
+                "example": {
+                  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+                  "user": {
+                    "id": "usr_01HXYZ",
+                    "email": "jane.doe@example.com",
+                    "name": "Jane Doe",
+                    "createdAt": "2024-01-15T10:30:00.000Z"
+                  }
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/ValidationError" },
+          "401": {
+            "description": "Invalid credentials",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+                "example": {
+                  "error": {
+                    "code": "UNAUTHORIZED",
+                    "message": "Invalid email or password",
+                    "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+                  }
+                }
+              }
+            }
+          },
+          "429": { "$ref": "#/components/responses/RateLimited" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    },
+    "/api/auth/logout": {
+      "post": {
+        "tags": ["Auth"],
+        "summary": "Log out",
+        "description": "Invalidates the current access token.",
+        "operationId": "logoutUser",
+        "responses": {
+          "204": { "description": "Logged out" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    },
+    "/api/users/me": {
+      "get": {
+        "tags": ["Users"],
+        "summary": "Get current user",
+        "description": "Returns the profile of the authenticated user.",
+        "operationId": "getCurrentUser",
+        "responses": {
+          "200": {
+            "description": "Current user profile",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/User" },
+                "example": {
+                  "id": "usr_01HXYZ",
+                  "email": "jane.doe@example.com",
+                  "name": "Jane Doe",
+                  "createdAt": "2024-01-15T10:30:00.000Z"
+                }
+              }
+            }
+          },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      },
+      "patch": {
+        "tags": ["Users"],
+        "summary": "Update current user",
+        "description": "Updates the profile of the authenticated user.",
+        "operationId": "updateCurrentUser",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/UpdateUserRequest" },
+              "example": { "name": "Jane Q. Doe" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated user profile",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/User" },
+                "example": {
+                  "id": "usr_01HXYZ",
+                  "email": "jane.doe@example.com",
+                  "name": "Jane Q. Doe",
+                  "createdAt": "2024-01-15T10:30:00.000Z"
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/ValidationError" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    },
+    "/api/tasks": {
+      "get": {
+        "tags": ["Tasks"],
+        "summary": "List tasks",
+        "description": "Returns a paginated list of tasks belonging to the authenticated user.",
+        "operationId": "listTasks",
+        "parameters": [
+          {
+            "name": "status",
+            "in": "query",
+            "description": "Filter by task status",
+            "required": false,
+            "schema": { "$ref": "#/components/schemas/TaskStatus" }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "description": "Page number (1-based)",
+            "required": false,
+            "schema": { "type": "integer", "minimum": 1, "default": 1 }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Page size",
+            "required": false,
+            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Paginated task list",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/TaskListResponse" },
+                "example": {
+                  "data": [
+                    {
+                      "id": "tsk_01HABC",
+                      "title": "Write documentation",
+                      "description": "Add OpenAPI spec",
+                      "status": "in_progress",
+                      "dueDate": "2024-02-01T00:00:00.000Z",
+                      "createdAt": "2024-01-15T10:30:00.000Z",
+                      "updatedAt": "2024-01-16T09:00:00.000Z"
+                    }
+                  ],
+                  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/ValidationError" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      },
+      "post": {
+        "tags": ["Tasks"],
+        "summary": "Create a task",
+        "description": "Creates a new task for the authenticated user.",
+        "operationId": "createTask",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/CreateTaskRequest" },
+              "example": {
+                "title": "Write documentation",
+                "description": "Add OpenAPI spec",
+                "status": "todo",
+                "dueDate": "2024-02-01T00:00:00.000Z"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Task created",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Task" },
+                "example": {
+                  "id": "tsk_01HABC",
+                  "title": "Write documentation",
+                  "description": "Add OpenAPI spec",
+                  "status": "todo",
+                  "dueDate": "2024-02-01T00:00:00.000Z",
+                  "createdAt": "2024-01-15T10:30:00.000Z",
+                  "updatedAt": "2024-01-15T10:30:00.000Z"
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/ValidationError" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    },
+    "/api/tasks/{id}": {
+      "parameters": [
+        {
+          "name": "id",
+          "in": "path",
+          "required": true,
+          "description": "Task identifier",
+          "schema": { "type": "string", "example": "tsk_01HABC" }
+        }
+      ],
+      "get": {
+        "tags": ["Tasks"],
+        "summary": "Get a task",
+        "description": "Returns a single task by id.",
+        "operationId": "getTask",
+        "responses": {
+          "200": {
+            "description": "Task",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Task" },
+                "example": {
+                  "id": "tsk_01HABC",
+                  "title": "Write documentation",
+                  "description": "Add OpenAPI spec",
+                  "status": "in_progress",
+                  "dueDate": "2024-02-01T00:00:00.000Z",
+                  "createdAt": "2024-01-15T10:30:00.000Z",
+                  "updatedAt": "2024-01-16T09:00:00.000Z"
+                }
+              }
+            }
+          },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      },
+      "patch": {
+        "tags": ["Tasks"],
+        "summary": "Update a task",
+        "description": "Partially updates a task.",
+        "operationId": "updateTask",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/UpdateTaskRequest" },
+              "example": { "status": "done" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Updated task",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/Task" },
+                "example": {
+                  "id": "tsk_01HABC",
+                  "title": "Write documentation",
+                  "description": "Add OpenAPI spec",
+                  "status": "done",
+                  "dueDate": "2024-02-01T00:00:00.000Z",
+                  "createdAt": "2024-01-15T10:30:00.000Z",
+                  "updatedAt": "2024-01-17T12:00:00.000Z"
+                }
+              }
+            }
+          },
+          "400": { "$ref": "#/components/responses/ValidationError" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      },
+      "delete": {
+        "tags": ["Tasks"],
+        "summary": "Delete a task",
+        "description": "Deletes a task by id.",
+        "operationId": "deleteTask",
+        "responses": {
+          "204": { "description": "Task deleted" },
+          "401": { "$ref": "#/components/responses/Unauthorized" },
+          "403": { "$ref": "#/components/responses/Forbidden" },
+          "404": { "$ref": "#/components/responses/NotFound" },
+          "500": { "$ref": "#/components/responses/InternalError" }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT",
+        "description": "JWT access token obtained from `POST /api/auth/login`."
+      }
+    },
+    "schemas": {
+      "HealthResponse": {
+        "type": "object",
+        "required": ["status", "uptime", "version"],
+        "properties": {
+          "status": { "type": "string", "enum": ["ok", "degraded"], "example": "ok" },
+          "uptime": { "type": "number", "description": "Uptime in seconds", "example": 12345.67 },
+          "version": { "type": "string", "example": "1.0.0" }
+        }
+      },
+      "RegisterRequest": {
+        "type": "object",
+        "required": ["email", "password", "name"],
+        "properties": {
+          "email": { "type": "string", "format": "email", "example": "jane.doe@example.com" },
+          "password": {
+            "type": "string",
+            "minLength": 8,
+            "description": "Must contain at least one letter and one number",
+            "example": "S3cure!Passw0rd"
+          },
+          "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Jane Doe" }
+        }
+      },
+      "LoginRequest": {
+        "type": "object",
+        "required": ["email", "password"],
+        "properties": {
+          "email": { "type": "string", "format": "email", "example": "jane.doe@example.com" },
+          "password": { "type": "string", "example": "S3cure!Passw0rd" }
+        }
+      },
+      "AuthResponse": {
+        "type": "object",
+        "required": ["token", "user"],
+        "properties": {
+          "token": { "type": "string", "description": "JWT access token", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." },
+          "user": { "$ref": "#/components/schemas/User" }
+        }
+      },
+      "User": {
+        "type": "object",
+        "required": ["id", "email", "name", "createdAt"],
+        "properties": {
+          "id": { "type": "string", "example": "usr_01HXYZ" },
+          "email": { "type": "string", "format": "email", "example": "jane.doe@example.com" },
+          "name": { "type": "string", "example": "Jane Doe" },
+          "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }
+        }
+      },
+      "UpdateUserRequest": {
+        "type": "object",
+        "minProperties": 1,
+        "properties": {
+          "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Jane Q. Doe" }
+        }
+      },
+      "TaskStatus": {
+        "type": "string",
+        "enum": ["todo", "in_progress", "done"],
+        "example": "in_progress"
+      },
+      "Task": {
+        "type": "object",
+        "required": ["id", "title", "status", "createdAt", "updatedAt"],
+        "properties": {
+          "id": { "type": "string", "example": "tsk_01HABC" },
+          "title": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Write documentation" },
+          "description": { "type": ["string", "null"], "maxLength": 2000, "example": "Add OpenAPI spec" },
+          "status": { "$ref": "#/components/schemas/TaskStatus" },
+          "dueDate": { "type": ["string", "null"], "format": "date-time", "example": "2024-02-01T00:00:00.000Z" },
+          "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" },
+          "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-16T09:00:00.000Z" }
+        }
+      },
+      "CreateTaskRequest": {
+        "type": "object",
+        "required": ["title"],
+        "properties": {
+          "title": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Write documentation" },
+          "description": { "type": "string", "maxLength": 2000, "example": "Add OpenAPI spec" },
+          "status": { "$ref": "#/components/schemas/TaskStatus" },
+          "dueDate": { "type": "string", "format": "date-time", "example": "2024-02-01T00:00:00.000Z" }
+        }
+      },
+      "UpdateTaskRequest": {
+        "type": "object",
+        "minProperties": 1,
+        "properties": {
+          "title": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Write documentation" },
+          "description": { "type": ["string", "null"], "maxLength": 2000, "example": "Add OpenAPI spec" },
+          "status": { "$ref": "#/components/schemas/TaskStatus" },
+          "dueDate": { "type": ["string", "null"], "format": "date-time", "example": "2024-02-01T00:00:00.000Z" }
+        }
+      },
+      "TaskListResponse": {
+        "type": "object",
+        "required": ["data", "meta"],
+        "properties": {
+          "data": {
+            "type": "array",
+            "items": { "$ref": "#/components/schemas/Task" }
+          },
+          "meta": { "$ref": "#/components/schemas/PaginationMeta" }
+        }
+      },
+      "PaginationMeta": {
+        "type": "object",
+        "required": ["page", "limit", "total", "totalPages"],
+        "properties": {
+          "page": { "type": "integer", "minimum": 1, "example": 1 },
+          "limit": { "type": "integer", "minimum": 1, "example": 20 },
+          "total": { "type": "integer", "minimum": 0, "example": 1 },
+          "totalPages": { "type": "integer", "minimum": 0, "example": 1 }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "required": ["error"],
+        "properties": {
+          "error": {
+            "type": "object",
+            "required": ["code", "message"],
+            "properties": {
+              "code": {
+                "type": "string",
+                "description": "AppError taxonomy code",
+                "enum": [
+                  "VALIDATION_ERROR",
+                  "UNAUTHORIZED",
+                  "FORBIDDEN",
+                  "NOT_FOUND",
+                  "CONFLICT",
+                  "RATE_LIMITED",
+                  "INTERNAL_ERROR"
+                ],
+                "example": "VALIDATION_ERROR"
+              },
+              "message": { "type": "string", "example": "Request validation failed" },
+              "details": {
+                "type": "array",
+                "description": "Field-level validation details (only for VALIDATION_ERROR)",
+                "items": {
+                  "type": "object",
+                  "required": ["field", "message"],
+                  "properties": {
+                    "field": { "type": "string", "example": "email" },
+                    "message": { "type": "string", "example": "must be a valid email" }
+                  }
+                }
+              },
+              "requestId": { "type": "string", "description": "Correlation id for support", "example": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21" }
+            }
+          }
+        }
+      }
+    },
+    "responses": {
+      "ValidationError": {
+        "description": "Request validation failed",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+            "example": {
+              "error": {
+                "code": "VALIDATION_ERROR",
+                "message": "Request validation failed",
+                "details": [
+                  { "field": "email", "message": "must be a valid email" },
+                  { "field": "password", "message": "must be at least 8 characters" }
+                ],
+                "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+              }
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "Missing or invalid credentials",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+            "example": {
+              "error": {
+                "code": "UNAUTHORIZED",
+                "message": "Authentication required",
+                "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+              }
+            }
+          }
+        }
+      },
+      "Forbidden": {
+        "description": "Authenticated but not allowed to access the resource",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+            "example": {
+              "error": {
+                "code": "FORBIDDEN",
+                "message": "You do not have permission to access this resource",
+                "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+              }
+            }
+          }
+        }
+      },
+      "NotFound": {
+        "description": "Resource not found",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+            "example": {
+              "error": {
+                "code": "NOT_FOUND",
+                "message": "Task not found",
+                "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+              }
+            }
+          }
+        }
+      },
+      "RateLimited": {
+        "description": "Too many requests",
+        "headers": {
+          "Retry-After": {
+            "description": "Seconds until the next request may be attempted",
+            "schema": { "type": "integer", "example": 30 }
+          }
+        },
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+            "example": {
+              "error": {
+                "code": "RATE_LIMITED",
+                "message": "Too many requests, please try again later",
+                "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+              }
+            }
+          }
+        }
+      },
+      "InternalError": {
+        "description": "Unexpected server error",
+        "content": {
+          "application/json": {
+            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
+            "example": {
+              "error": {
+                "code": "INTERNAL_ERROR",
+                "message": "An unexpected error occurred",
+                "requestId": "b3f1c2a4-1f2e-4c3d-9a8b-7e6d5c4b3a21"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/src/__tests__/openapi.test.ts b/src/__tests__/openapi.test.ts
new file mode 100644
index 00000000..134b13e0
--- /dev/null
+++ b/src/__tests__/openapi.test.ts
@@ -0,0 +1,294 @@
+import { describe, it, expect } from '@jest/globals';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * CI test that validates the OpenAPI specification and detects drift between
+ * the documented paths/methods and the actual route handlers.
+ *
+ * It performs the following checks:
+ *  1. The OpenAPI document is valid JSON and structurally sound.
+ *  2. Required top-level fields are present (openapi, info, paths).
+ *  3. Every operation has the required fields (responses, summary/description).
+ *  4. Every operation includes request/response examples where applicable.
+ *  5. Error scenarios are documented (4xx/5xx responses).
+ *  6. Documented paths/methods match the actual route handlers (drift detection).
+ */
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const OPENAPI_PATH = path.join(ROOT, 'openapi.json');
+const SRC_DIR = path.join(ROOT, 'src');
+
+const HTTP_METHODS = [
+  'get',
+  'put',
+  'post',
+  'delete',
+  'options',
+  'head',
+  'patch',
+  'trace',
+] as const;
+
+type HttpMethod = (typeof HTTP_METHODS)[number];
+
+interface OpenApiOperation {
+  summary?: string;
+  description?: string;
+  operationId?: string;
+  responses?: Record<string, unknown>;
+  requestBody?: {
+    content?: Record<string, { example?: unknown; examples?: Record<string, unknown> }>;
+  };
+  parameters?: Array<{ example?: unknown; examples?: Record<string, unknown> }>;
+  [key: string]: unknown;
+}
+
+interface OpenApiDocument {
+  openapi: string;
+  info: { title: string; version: string; [key: string]: unknown };
+  paths: Record<string, Record<string, OpenApiOperation>>;
+  components?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+function loadOpenApi(): OpenApiDocument {
+  expect(fs.existsSync(OPENAPI_PATH)).toBe(true);
+  const raw = fs.readFileSync(OPENAPI_PATH, 'utf8');
+  let parsed: unknown;
+  expect(() => {
+    parsed = JSON.parse(raw);
+  }).not.toThrow();
+  return parsed as OpenApiDocument;
+}
+
+/**
+ * Recursively collect all source files under a directory.
+ */
+function collectSourceFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === '__tests__' || entry.name === 'node_modules') {
+        continue;
+      }
+      files.push(...collectSourceFiles(fullPath));
+    } else if (/\.(ts|js)$/.test(entry.name) && !entry.name.endsWith('.d.ts')) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+interface DiscoveredRoute {
+  method: HttpMethod;
+  path: string;
+}
+
+/**
+ * Extract routes from source files by scanning for common router/route
+ * registration patterns, e.g.:
+ *   router.get('/users/:id', ...)
+ *   app.post("/users", ...)
+ *   server.delete(`/users/:id`, ...)
+ */
+function discoverRoutes(files: string[]): DiscoveredRoute[] {
+  const routes: DiscoveredRoute[] = [];
+  const routeRegex = new RegExp(
+    `\\b(?:router|app|server|route|api)\\.(${HTTP_METHODS.join('|')})\\s*\\(\\s*['"\`]([^'"\`]+)['"\`]`,
+    'g',
+  );
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, 'utf8');
+    let match: RegExpExecArray | null;
+    while ((match = routeRegex.exec(content)) !== null) {
+      const method = match[1].toLowerCase() as HttpMethod;
+      let routePath = match[2];
+      // Normalize Express-style params (:id) to OpenAPI-style ({id}).
+      routePath = routePath.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+      // Strip trailing slashes (except root).
+      if (routePath.length > 1 && routePath.endsWith('/')) {
+        routePath = routePath.slice(0, -1);
+      }
+      routes.push({ method, path: routePath });
+    }
+  }
+  return routes;
+}
+
+function normalizePath(p: string): string {
+  let normalized = p.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+  if (normalized.length > 1 && normalized.endsWith('/')) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+
+function documentedRoutes(doc: OpenApiDocument): DiscoveredRoute[] {
+  const routes: DiscoveredRoute[] = [];
+  for (const [routePath, operations] of Object.entries(doc.paths)) {
+    for (const method of Object.keys(operations)) {
+      if ((HTTP_METHODS as readonly string[]).includes(method.toLowerCase())) {
+        routes.push({
+          method: method.toLowerCase() as HttpMethod,
+          path: normalizePath(routePath),
+        });
+      }
+    }
+  }
+  return routes;
+}
+
+function routeKey(route: DiscoveredRoute): string {
+  return `${route.method.toUpperCase()} ${route.path}`;
+}
+
+describe('OpenAPI specification', () => {
+  let doc: OpenApiDocument;
+
+  beforeAll(() => {
+    doc = loadOpenApi();
+  });
+
+  describe('schema validity', () => {
+    it('is valid JSON with required top-level fields', () => {
+      expect(doc).toBeDefined();
+      expect(typeof doc.openapi).toBe('string');
+      expect(doc.openapi).toMatch(/^3\.\d+\.\d+$/);
+      expect(doc.info).toBeDefined();
+      expect(typeof doc.info.title).toBe('string');
+      expect(doc.info.title.length).toBeGreaterThan(0);
+      expect(typeof doc.info.version).toBe('string');
+      expect(doc.info.version.length).toBeGreaterThan(0);
+      expect(doc.paths).toBeDefined();
+      expect(typeof doc.paths).toBe('object');
+    });
+
+    it('defines at least one documented path', () => {
+      expect(Object.keys(doc.paths).length).toBeGreaterThan(0);
+    });
+
+    it('uses valid path templates', () => {
+      for (const routePath of Object.keys(doc.paths)) {
+        expect(routePath.startsWith('/')).toBe(true);
+        // Balanced braces for path parameters.
+        const open = (routePath.match(/\{/g) || []).length;
+        const close = (routePath.match(/\}/g) || []).length;
+        expect(open).toBe(close);
+      }
+    });
+  });
+
+  describe('operation documentation', () => {
+    it('every operation has required fields', () => {
+      for (const [routePath, operations] of Object.entries(doc.paths)) {
+        for (const [method, operation] of Object.entries(operations)) {
+          if (!(HTTP_METHODS as readonly string[]).includes(method.toLowerCase())) {
+            continue;
+          }
+          const context = `${method.toUpperCase()} ${routePath}`;
+          expect(operation.responses).toBeDefined();
+          expect(Object.keys(operation.responses ?? {}).length).toBeGreaterThan(0);
+          const hasSummaryOrDescription =
+            (typeof operation.summary === 'string' && operation.summary.length > 0) ||
+            (typeof operation.description === 'string' && operation.description.length > 0);
+          expect(hasSummaryOrDescription).toBe(true);
+          // Ensure the operation is identifiable.
+          expect(typeof operation.operationId === 'string' || operation.operationId === undefined).toBe(
+            true,
+          );
+          expect(context.length).toBeGreaterThan(0);
+        }
+      }
+    });
+
+    it('every operation documents error scenarios', () => {
+      for (const [routePath, operations] of Object.entries(doc.paths)) {
+        for (const [method, operation] of Object.entries(operations)) {
+          if (!(HTTP_METHODS as readonly string[]).includes(method.toLowerCase())) {
+            continue;
+          }
+          const statusCodes = Object.keys(operation.responses ?? {});
+          const hasErrorResponse = statusCodes.some((code) => {
+            const numeric = parseInt(code, 10);
+            return !Number.isNaN(numeric) && numeric >= 400;
+          });
+          expect(hasErrorResponse).toBe(true);
+        }
+      }
+    });
+
+    it('every operation includes at least one example', () => {
+      for (const [routePath, operations] of Object.entries(doc.paths)) {
+        for (const [method, operation] of Object.entries(operations)) {
+          if (!(HTTP_METHODS as readonly string[]).includes(method.toLowerCase())) {
+            continue;
+          }
+          const examples: unknown[] = [];
+
+          // Request body examples.
+          const requestContent = operation.requestBody?.content ?? {};
+          for (const media of Object.values(requestContent)) {
+            if (media.example !== undefined) {
+              examples.push(media.example);
+            }
+            if (media.examples && Object.keys(media.examples).length > 0) {
+              examples.push(media.examples);
+            }
+          }
+
+          // Parameter examples.
+          for (const param of operation.parameters ?? []) {
+            if (param.example !== undefined) {
+              examples.push(param.example);
+            }
+            if (param.examples && Object.keys(param.examples).length > 0) {
+              examples.push(param.examples);
+            }
+          }
+
+          // Response examples.
+          for (const response of Object.values(operation.responses ?? {})) {
+            const content = (response as { content?: Record<string, { example?: unknown; examples?: Record<string, unknown> }> })
+              .content;
+            for (const media of Object.values(content ?? {})) {
+              if (media.example !== undefined) {
+                examples.push(media.example);
+              }
+              if (media.examples && Object.keys(media.examples).length > 0) {
+                examples.push(media.examples);
+              }
+            }
+          }
+
+          expect(examples.length).toBeGreaterThan(0);
+        }
+      }
+    });
+  });
+
+  describe('drift detection', () => {
+    it('documented paths/methods match actual route handlers', () => {
+      const sourceFiles = collectSourceFiles(SRC_DIR);
+      const actualRoutes = discoverRoutes(sourceFiles);
+      const documented = documentedRoutes(doc);
+
+      const documentedKeys = new Set(documented.map(routeKey));
+      const actualKeys = new Set(actualRoutes.map(routeKey));
+
+      const missingFromDocs = [...actualKeys].filter((key) => !documentedKeys.has(key)).sort();
+      const missingFromCode = [...documentedKeys].filter((key) => !actualKeys.has(key)).sort();
+
+      expect({ missingFromDocs, missingFromCode }).toEqual({
+        missingFromDocs: [],
+        missingFromCode: [],
+      });
+    });
+  });
+});
\ No newline at end of file
diff --git a/src/app/api-docs/page.tsx b/src/app/api-docs/page.tsx
new file mode 100644
index 00000000..5c9dc9b4
--- /dev/null
+++ b/src/app/api-docs/page.tsx
@@ -0,0 +1,205 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import Link from 'next/link';
+
+const SWAGGER_UI_VERSION = '5.17.14';
+const SWAGGER_UI_CSS = `https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui.css`;
+const SWAGGER_UI_JS = `https://unpkg.com/swagger-ui-dist@${SWAGGER_UI_VERSION}/swagger-ui-bundle.js`;
+const OPENAPI_SPEC_URL = '/openapi.json';
+
+type SwaggerUIInstance = {
+  destroy?: () => void;
+};
+
+type SwaggerUIGlobal = {
+  (config: Record<string, unknown>): SwaggerUIInstance;
+};
+
+declare global {
+  interface Window {
+    SwaggerUIBundle?: SwaggerUIGlobal;
+  }
+}
+
+/**
+ * Loads an external script without injecting inline JavaScript, so the page
+ * remains compatible with strict Content-Security-Policy rules (no
+ * 'unsafe-inline' required for script-src).
+ */
+function loadScript(src: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const existing = document.querySelector<HTMLScriptElement>(
+      `script[data-swagger-src="${src}"]`,
+    );
+    if (existing) {
+      if (existing.dataset.loaded === 'true') {
+        resolve();
+        return;
+      }
+      existing.addEventListener('load', () => resolve(), { once: true });
+      existing.addEventListener('error', () => reject(new Error(`Failed to load ${src}`)), {
+        once: true,
+      });
+      return;
+    }
+
+    const script = document.createElement('script');
+    script.src = src;
+    script.async = true;
+    script.crossOrigin = 'anonymous';
+    script.dataset.swaggerSrc = src;
+    script.addEventListener(
+      'load',
+      () => {
+        script.dataset.loaded = 'true';
+        resolve();
+      },
+      { once: true },
+    );
+    script.addEventListener('error', () => reject(new Error(`Failed to load ${src}`)), {
+      once: true,
+    });
+    document.body.appendChild(script);
+  });
+}
+
+function loadStylesheet(href: string): void {
+  if (document.querySelector(`link[data-swagger-href="${href}"]`)) {
+    return;
+  }
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = href;
+  link.crossOrigin = 'anonymous';
+  link.dataset.swaggerHref = href;
+  document.head.appendChild(link);
+}
+
+export default function ApiDocsPage() {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const uiRef = useRef<SwaggerUIInstance | null>(null);
+  const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function init() {
+      try {
+        loadStylesheet(SWAGGER_UI_CSS);
+        await loadScript(SWAGGER_UI_JS);
+
+        if (cancelled) {
+          return;
+        }
+
+        const SwaggerUIBundle = window.SwaggerUIBundle;
+        if (!SwaggerUIBundle) {
+          throw new Error('Swagger UI bundle did not initialize.');
+        }
+
+        if (!containerRef.current) {
+          return;
+        }
+
+        uiRef.current?.destroy?.();
+        containerRef.current.innerHTML = '';
+
+        uiRef.current = SwaggerUIBundle({
+          url: OPENAPI_SPEC_URL,
+          dom_id: '#swagger-ui-container',
+          deepLinking: true,
+          docExpansion: 'list',
+          defaultModelsExpandDepth: 1,
+          defaultModelExpandDepth: 1,
+          displayRequestDuration: true,
+          filter: true,
+          persistAuthorization: true,
+          tryItOutEnabled: true,
+          validatorUrl: null,
+          supportedSubmitMethods: ['get', 'post', 'put', 'patch', 'delete'],
+          onComplete: () => {
+            if (!cancelled) {
+              setStatus('ready');
+            }
+          },
+          onFailure: (err: unknown) => {
+            if (!cancelled) {
+              setStatus('error');
+              setErrorMessage(
+                err instanceof Error ? err.message : 'Failed to load the OpenAPI specification.',
+              );
+            }
+          },
+        });
+
+        if (!cancelled) {
+          setStatus('ready');
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setStatus('error');
+          setErrorMessage(err instanceof Error ? err.message : 'Failed to load API docs.');
+        }
+      }
+    }
+
+    void init();
+
+    return () => {
+      cancelled = true;
+      uiRef.current?.destroy?.();
+      uiRef.current = null;
+    };
+  }, []);
+
+  return (
+    <main className="mx-auto max-w-6xl px-4 py-8">
+      <header className="mb-6 flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <h1 className="text-2xl font-bold">API Documentation</h1>
+          <p className="mt-1 text-sm text-gray-600">
+            Interactive OpenAPI reference generated from{' '}
+            <code className="rounded bg-gray-100 px-1 py-0.5 text-xs">{OPENAPI_SPEC_URL}</code>.
+          </p>
+        </div>
+        <nav className="flex flex-wrap gap-3 text-sm">
+          <Link className="text-blue-600 underline hover:text-blue-800" href="/developers">
+            Developer Docs
+          </Link>
+          <a
+            className="text-blue-600 underline hover:text-blue-800"
+            href={OPENAPI_SPEC_URL}
+            target="_blank"
+            rel="noreferrer"
+          >
+            Raw OpenAPI JSON
+          </a>
+        </nav>
+      </header>
+
+      {status === 'loading' && (
+        <div role="status" className="mb-4 rounded border border-gray-200 bg-gray-50 p-4 text-sm">
+          Loading interactive API documentation…
+        </div>
+      )}
+
+      {status === 'error' && (
+        <div role="alert" className="mb-4 rounded border border-red-200 bg-red-50 p-4 text-sm text-red-800">
+          <p className="font-semibold">Unable to load the interactive API documentation.</p>
+          {errorMessage && <p className="mt-1">{errorMessage}</p>}
+          <p className="mt-2">
+            You can still view the raw specification at{' '}
+            <a className="underline" href={OPENAPI_SPEC_URL} target="_blank" rel="noreferrer">
+              {OPENAPI_SPEC_URL}
+            </a>
+            .
+          </p>
+        </div>
+      )}
+
+      <div id="swagger-ui-container" ref={containerRef} className="swagger-ui-wrapper" />
+    </main>
+  );
+}
\ No newline at end of file
diff --git a/src/app/dashboard/error.tsx b/src/app/dashboard/error.tsx
index 377db704..03a59b7c 100644
--- a/src/app/dashboard/error.tsx
+++ b/src/app/dashboard/error.tsx
@@ -1,7 +1,12 @@
 "use client";
 
 import Link from "next/link";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
+import {
+  classifyError,
+  getErrorTemplate,
+  logError,
+} from "@/lib/errors";
 
 interface Props {
   error: Error & { digest?: string };
@@ -12,6 +17,9 @@ interface Props {
 export default function DashboardError({ error, reset }: Props) {
   const [sentryEventId, setSentryEventId] = useState<string | null>(null);
 
+  const errorType = useMemo(() => classifyError(error), [error]);
+  const template = useMemo(() => getErrorTemplate(errorType), [errorType]);
+
   useEffect(() => {
     const capture = async () => {
       try {
@@ -23,15 +31,25 @@ export default function DashboardError({ error, reset }: Props) {
       }
     };
     capture();
-    console.error("[DashboardError]", error);
-  }, [error]);
+    logError(error, { boundary: "DashboardError", errorType });
+  }, [error, errorType]);
 
   return (
     <main className="max-w-xl mx-auto px-4 py-20 text-center">
-      <h1 className="text-2xl font-bold mb-2">Dashboard failed to load</h1>
-      <p className="text-gray-400 text-sm mb-6">
-        {error.message || "An unexpected error occurred."}
-      </p>
+      <h1 className="text-2xl font-bold mb-2">{template.title}</h1>
+      <p className="text-gray-400 text-sm mb-6">{template.message}</p>
+      {template.suggestions.length > 0 && (
+        <div className="text-left bg-gray-900/60 border border-gray-700 rounded-lg p-4 mb-6">
+          <p className="text-sm font-semibold text-gray-200 mb-2">
+            What you can try:
+          </p>
+          <ul className="list-disc list-inside text-sm text-gray-400 space-y-1">
+            {template.suggestions.map((suggestion) => (
+              <li key={suggestion}>{suggestion}</li>
+            ))}
+          </ul>
+        </div>
+      )}
       {sentryEventId && (
         <p className="text-xs text-gray-500 font-mono mb-4">
           Error ID: {sentryEventId}
diff --git a/src/app/error.tsx b/src/app/error.tsx
index 00de11b1..e35db7eb 100644
--- a/src/app/error.tsx
+++ b/src/app/error.tsx
@@ -2,6 +2,12 @@
 
 import Link from "next/link";
 import { useEffect } from "react";
+import {
+  classifyError,
+  getErrorTemplate,
+  getRecoverySuggestions,
+} from "@/lib/errors";
+import { logger } from "@/lib/logger";
 
 interface Props {
   error: Error & { digest?: string };
@@ -9,13 +15,18 @@ interface Props {
 }
 
 export default function GlobalError({ error, reset }: Props) {
+  const errorType = classifyError(error);
+  const template = getErrorTemplate(errorType);
+  const suggestions = getRecoverySuggestions(errorType);
+
   useEffect(() => {
-    console.error("[GlobalError]", {
+    logger.error("[GlobalError]", {
+      type: errorType,
       message: error.message,
       digest: error.digest,
       stack: error.stack,
     });
-  }, [error]);
+  }, [error, errorType]);
 
   return (
     <main className="min-h-screen bg-gray-950 text-gray-100 flex items-center justify-center px-4">
@@ -24,19 +35,25 @@ export default function GlobalError({ error, reset }: Props) {
           StellarSplit
         </span>
         <div className="flex flex-col gap-2">
-          <h1 className="text-2xl font-bold">Something went wrong</h1>
-          <p className="text-gray-400 text-sm">
-            An unexpected error occurred. You can try again or return home.
-          </p>
+          <h1 className="text-2xl font-bold">{template.title}</h1>
+          <p className="text-gray-400 text-sm">{template.message}</p>
         </div>
 
+        {suggestions.length > 0 && (
+          <ul className="w-full text-left text-sm text-gray-400 list-disc list-inside flex flex-col gap-1">
+            {suggestions.map((suggestion) => (
+              <li key={suggestion}>{suggestion}</li>
+            ))}
+          </ul>
+        )}
+
         <div className="flex gap-3">
           <button
             type="button"
             onClick={reset}
             className="min-h-11 px-6 py-2 rounded-lg bg-indigo-600 hover:bg-indigo-500 font-semibold transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500"
           >
-            Try Again
+            {template.retryLabel}
           </button>
           <Link
             href="/"
diff --git a/src/app/global-error.tsx b/src/app/global-error.tsx
index 2fc94d93..9dffcb92 100644
--- a/src/app/global-error.tsx
+++ b/src/app/global-error.tsx
@@ -3,6 +3,12 @@
 import * as Sentry from "@sentry/nextjs";
 import { useEffect } from "react";
 
+import {
+  classifyError,
+  getErrorTemplate,
+  logError,
+} from "@/lib/errors";
+
 export default function GlobalError({
   error,
   reset,
@@ -10,9 +16,17 @@ export default function GlobalError({
   error: Error & { digest?: string };
   reset: () => void;
 }) {
+  const errorType = classifyError(error);
+  const template = getErrorTemplate(errorType);
+
   useEffect(() => {
     Sentry.captureException(error);
-  }, [error]);
+    logError(error, {
+      boundary: "global-error",
+      errorType,
+      digest: error.digest,
+    });
+  }, [error, errorType]);
 
   return (
     <html lang="en">
@@ -25,13 +39,31 @@ export default function GlobalError({
           color: "#fff",
           fontFamily: "system-ui, sans-serif",
         }}>
-          <div style={{ textAlign: "center", padding: "2rem" }}>
+          <div style={{ textAlign: "center", padding: "2rem", maxWidth: "32rem" }}>
             <h2 style={{ fontSize: "1.5rem", fontWeight: 700, marginBottom: "0.5rem" }}>
-              Something went wrong
+              {template.title}
             </h2>
             <p style={{ color: "#9ca3af", marginBottom: "1.5rem" }}>
-              An unexpected error occurred. Our team has been notified.
+              {template.message}
             </p>
+            {template.suggestions.length > 0 && (
+              <ul
+                style={{
+                  listStyle: "none",
+                  padding: 0,
+                  margin: "0 0 1.5rem",
+                  color: "#9ca3af",
+                  fontSize: "0.875rem",
+                  textAlign: "left",
+                }}
+              >
+                {template.suggestions.map((suggestion) => (
+                  <li key={suggestion} style={{ marginBottom: "0.5rem" }}>
+                    {suggestion}
+                  </li>
+                ))}
+              </ul>
+            )}
             <button
               onClick={reset}
               style={{
@@ -44,11 +76,16 @@ export default function GlobalError({
                 fontSize: "0.875rem",
               }}
             >
-              Try again
+              {template.recoveryLabel}
             </button>
+            {error.digest && (
+              <p style={{ color: "#6b7280", fontSize: "0.75rem", marginTop: "1rem" }}>
+                Reference: {error.digest}
+              </p>
+            )}
           </div>
         </div>
       </body>
     </html>
   );
-}
+}
\ No newline at end of file
diff --git a/src/app/invoice/[id]/error.tsx b/src/app/invoice/[id]/error.tsx
index 9ddbc3ad..2d974d5c 100644
--- a/src/app/invoice/[id]/error.tsx
+++ b/src/app/invoice/[id]/error.tsx
@@ -2,6 +2,12 @@
 
 import Link from "next/link";
 import { useEffect, useState } from "react";
+import { logger } from "@/lib/logger";
+import {
+  classifyError,
+  getErrorTemplate,
+  type ErrorKind,
+} from "@/lib/errors";
 
 interface Props {
   error: Error & { digest?: string };
@@ -11,6 +17,7 @@ interface Props {
 /** Route-level error boundary for invoice detail pages. */
 export default function InvoiceError({ error, reset }: Props) {
   const [sentryEventId, setSentryEventId] = useState<string | null>(null);
+  const [kind] = useState<ErrorKind>(() => classifyError(error));
 
   useEffect(() => {
     const capture = async () => {
@@ -23,15 +30,27 @@ export default function InvoiceError({ error, reset }: Props) {
       }
     };
     capture();
-    console.error("[InvoiceError]", error);
-  }, [error]);
+    logger.error("Invoice detail page failed to load", {
+      scope: "InvoiceError",
+      kind,
+      digest: error.digest,
+      error,
+    });
+  }, [error, kind]);
+
+  const template = getErrorTemplate(kind);
 
   return (
     <main className="max-w-xl mx-auto px-4 py-20 text-center">
-      <h1 className="text-2xl font-bold mb-2">Could not load invoice</h1>
-      <p className="text-gray-400 text-sm mb-6">
-        {error.message || "An unexpected error occurred."}
-      </p>
+      <h1 className="text-2xl font-bold mb-2">{template.title}</h1>
+      <p className="text-gray-400 text-sm mb-6">{template.message}</p>
+      {template.suggestions.length > 0 && (
+        <ul className="text-sm text-gray-400 text-left mb-6 space-y-1 list-disc list-inside">
+          {template.suggestions.map((suggestion) => (
+            <li key={suggestion}>{suggestion}</li>
+          ))}
+        </ul>
+      )}
       {sentryEventId && (
         <p className="text-xs text-gray-500 font-mono mb-4">
           Error ID: {sentryEventId}
diff --git a/src/app/payments/error.tsx b/src/app/payments/error.tsx
index beb95819..8fd4e2c8 100644
--- a/src/app/payments/error.tsx
+++ b/src/app/payments/error.tsx
@@ -2,6 +2,8 @@
 
 import Link from "next/link";
 import { useEffect, useState } from "react";
+import { classifyError, getErrorCopy } from "@/lib/errors";
+import { logger } from "@/lib/logger";
 
 interface Props {
   error: Error & { digest?: string };
@@ -12,6 +14,9 @@ interface Props {
 export default function PaymentsError({ error, reset }: Props) {
   const [sentryEventId, setSentryEventId] = useState<string | null>(null);
 
+  const kind = classifyError(error);
+  const copy = getErrorCopy(kind, "payments");
+
   useEffect(() => {
     const capture = async () => {
       try {
@@ -23,15 +28,26 @@ export default function PaymentsError({ error, reset }: Props) {
       }
     };
     capture();
-    console.error("[PaymentsError]", error);
-  }, [error]);
+    logger.error("Payments route error", {
+      scope: "payments",
+      kind,
+      digest: error.digest,
+      message: error.message,
+      stack: error.stack,
+    });
+  }, [error, kind]);
 
   return (
     <main className="max-w-xl mx-auto px-4 py-20 text-center">
-      <h1 className="text-2xl font-bold mb-2">Could not load payment history</h1>
-      <p className="text-gray-400 text-sm mb-6">
-        {error.message || "An unexpected error occurred."}
-      </p>
+      <h1 className="text-2xl font-bold mb-2">{copy.title}</h1>
+      <p className="text-gray-400 text-sm mb-6">{copy.message}</p>
+      {copy.suggestions.length > 0 && (
+        <ul className="text-left text-sm text-gray-400 mb-6 space-y-2 list-disc list-inside">
+          {copy.suggestions.map((suggestion) => (
+            <li key={suggestion}>{suggestion}</li>
+          ))}
+        </ul>
+      )}
       {sentryEventId && (
         <p className="text-xs text-gray-500 font-mono mb-4">
           Error ID: {sentryEventId}
diff --git a/src/components/ErrorBoundary.tsx b/src/components/ErrorBoundary.tsx
index 31fac810..464918cb 100644
--- a/src/components/ErrorBoundary.tsx
+++ b/src/components/ErrorBoundary.tsx
@@ -3,7 +3,8 @@
 import { Component, type ReactNode } from "react";
 import Link from "next/link";
 import WalletConnect from "@/components/WalletConnect";
-import { classifyError } from "@/lib/errors";
+import { classifyError, toAppError, getErrorMessage, getRecoverySuggestions } from "@/lib/errors";
+import { logger } from "@/lib/logger";
 
 interface Props {
   children: ReactNode;
@@ -23,8 +24,15 @@ export default class ErrorBoundary extends Component<Props, State> {
     return { error };
   }
 
-  async componentDidCatch(error: Error) {
-    console.error(error);
+  async componentDidCatch(error: Error, errorInfo: { componentStack?: string | null }) {
+    const appError = toAppError(error);
+    logger.error("Unhandled error caught by root ErrorBoundary", {
+      code: appError.code,
+      message: appError.message,
+      context: appError.context,
+      stack: error.stack,
+      componentStack: errorInfo?.componentStack ?? undefined,
+    });
     try {
       // Sentry is only initialised when NEXT_PUBLIC_SENTRY_DSN is set.
       // Dynamic import keeps it out of the production bundle when unconfigured.
@@ -64,6 +72,9 @@ export default class ErrorBoundary extends Component<Props, State> {
     }
 
     const { kind, message } = classifyError(error);
+    const appError = toAppError(error);
+    const friendlyMessage = getErrorMessage(appError);
+    const suggestions = getRecoverySuggestions(appError);
 
     return (
       <main className="max-w-xl mx-auto w-full px-4 sm:px-6 py-20 overflow-x-hidden">
@@ -71,7 +82,7 @@ export default class ErrorBoundary extends Component<Props, State> {
           {kind === "wallet_not_connected" && (
             <>
               <h1 className="text-xl font-bold">Wallet required</h1>
-              <p className="text-gray-400 text-sm">{message}</p>
+              <p className="text-gray-400 text-sm">{friendlyMessage}</p>
               <WalletConnect />
             </>
           )}
@@ -79,7 +90,7 @@ export default class ErrorBoundary extends Component<Props, State> {
           {kind === "invoice_not_found" && (
             <>
               <h1 className="text-5xl font-bold text-gray-500">404</h1>
-              <p className="text-gray-400 text-sm">{message}</p>
+              <p className="text-gray-400 text-sm">{friendlyMessage}</p>
               <Link
                 href="/dashboard"
                 className="min-h-11 inline-flex items-center px-6 py-3 rounded-lg bg-indigo-600 hover:bg-indigo-500 font-semibold transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500"
@@ -92,7 +103,7 @@ export default class ErrorBoundary extends Component<Props, State> {
           {kind === "rpc_timeout" && (
             <>
               <h1 className="text-xl font-bold">Request timed out</h1>
-              <p className="text-gray-400 text-sm">{message}</p>
+              <p className="text-gray-400 text-sm">{friendlyMessage}</p>
               <button
                 type="button"
                 onClick={this.handleRetry}
@@ -106,7 +117,14 @@ export default class ErrorBoundary extends Component<Props, State> {
           {kind === "unknown" && (
             <>
               <h1 className="text-xl font-bold">Something went wrong</h1>
-              <p className="text-gray-400 text-sm break-words max-w-full">{message}</p>
+              <p className="text-gray-400 text-sm break-words max-w-full">{friendlyMessage}</p>
+              {suggestions.length > 0 && (
+                <ul className="text-sm text-gray-400 list-disc list-inside text-left">
+                  {suggestions.map((suggestion) => (
+                    <li key={suggestion}>{suggestion}</li>
+                  ))}
+                </ul>
+              )}
               {sentryEventId && (
                 <p className="text-xs text-gray-500 font-mono">
                   Error ID: {sentryEventId}
@@ -133,6 +151,12 @@ export default class ErrorBoundary extends Component<Props, State> {
                 >
                   Go to Dashboard
                 </Link>
+                <a
+                  href="mailto:support@stellarsplit.app"
+                  className="min-h-11 inline-flex items-center px-6 py-3 rounded-lg border border-gray-600 hover:border-gray-400 font-semibold transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500"
+                >
+                  Contact Support
+                </a>
               </div>
             </>
           )}
diff --git a/src/components/OfflineBanner.tsx b/src/components/OfflineBanner.tsx
index 5eb7b6f4..7d209942 100644
--- a/src/components/OfflineBanner.tsx
+++ b/src/components/OfflineBanner.tsx
@@ -2,8 +2,17 @@
 
 import { useEffect, useState } from "react";
 
+type QueueStatus = {
+  pending: number;
+  retrying: boolean;
+};
+
 export default function OfflineBanner() {
   const [offline, setOffline] = useState(false);
+  const [queueStatus, setQueueStatus] = useState<QueueStatus>({
+    pending: 0,
+    retrying: false,
+  });
 
   useEffect(() => {
     setOffline(!navigator.onLine);
@@ -17,15 +26,54 @@ export default function OfflineBanner() {
     };
   }, []);
 
-  if (!offline) return null;
+  useEffect(() => {
+    const handleQueueStatus = (event: Event) => {
+      const detail = (event as CustomEvent<Partial<QueueStatus>>).detail;
+      if (!detail) return;
+      setQueueStatus((prev) => ({
+        pending:
+          typeof detail.pending === "number" ? detail.pending : prev.pending,
+        retrying:
+          typeof detail.retrying === "boolean"
+            ? detail.retrying
+            : prev.retrying,
+      }));
+    };
+
+    window.addEventListener("offline-queue-status", handleQueueStatus);
+    return () => {
+      window.removeEventListener("offline-queue-status", handleQueueStatus);
+    };
+  }, []);
+
+  const hasQueue = queueStatus.pending > 0;
+
+  if (!offline && !hasQueue) return null;
+
+  const queueMessage = hasQueue
+    ? `${queueStatus.pending} transaction${
+        queueStatus.pending === 1 ? "" : "s"
+      } queued${queueStatus.retrying ? " — retrying…" : ""}.`
+    : null;
 
   return (
     <div
       role="alert"
       aria-live="assertive"
-      className="fixed top-0 inset-x-0 z-50 bg-yellow-500 text-yellow-950 text-sm font-medium text-center py-2 px-4"
+      className="fixed top-0 inset-x-0 z-50 bg-yellow-500 text-yellow-950 text-sm font-medium text-center py-2 px-4 flex flex-wrap items-center justify-center gap-x-3 gap-y-1"
     >
-      You are offline. Some features may not be available.
+      {offline && (
+        <span>You are offline. Some features may not be available.</span>
+      )}
+      {queueMessage && <span>{queueMessage}</span>}
+      {hasQueue && (
+        <a
+          href="/offline-queue"
+          className="underline font-semibold hover:no-underline focus:outline-none focus-visible:ring-2 focus-visible:ring-yellow-950 rounded"
+        >
+          Manage queue
+        </a>
+      )}
     </div>
   );
-}
+}
\ No newline at end of file
diff --git a/src/components/OfflineQueueSync.tsx b/src/components/OfflineQueueSync.tsx
index ef7d2911..3e7b86f7 100644
--- a/src/components/OfflineQueueSync.tsx
+++ b/src/components/OfflineQueueSync.tsx
@@ -1,10 +1,389 @@
 "use client";
 
-import { useEffect } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export type OfflineQueueItemStatus = 'pending' | 'retrying' | 'failed';
+
+export interface OfflineQueueItem {
+  id: string;
+  operation: string;
+  payload: unknown;
+  status: OfflineQueueItemStatus;
+  attempts: number;
+  createdAt: number;
+  lastError?: string;
+}
+
+const STORAGE_KEY = 'offline-queue:v1';
+const RECONNECT_DEBOUNCE_MS = 500;
+
+function safeParse(raw: string | null): OfflineQueueItem[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (item): item is OfflineQueueItem =>
+        item != null &&
+        typeof item === 'object' &&
+        typeof (item as OfflineQueueItem).id === 'string' &&
+        typeof (item as OfflineQueueItem).operation === 'string'
+    );
+  } catch {
+    return [];
+  }
+}
+
+function loadQueue(): OfflineQueueItem[] {
+  if (typeof window === 'undefined') return [];
+  try {
+    return safeParse(window.localStorage.getItem(STORAGE_KEY));
+  } catch {
+    return [];
+  }
+}
+
+function persistQueue(items: OfflineQueueItem[]): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(items));
+  } catch {
+    // Storage may be unavailable (private mode, quota); ignore.
+  }
+}
+
+/**
+ * Retry utility: attempts to execute a queued operation.
+ * Resolves on success, rejects on failure.
+ */
+export async function retryOperation(item: OfflineQueueItem): Promise<void> {
+  const handler = (globalThis as { __offlineQueueHandlers?: Record<string, (payload: unknown) => Promise<void>> })
+    .__offlineQueueHandlers?.[item.operation];
+  if (!handler) {
+    throw new Error(`No handler registered for operation "${item.operation}"`);
+  }
+  await handler(item.payload);
+}
+
+interface Toast {
+  id: number;
+  message: string;
+}
 
 export default function OfflineQueueSync() {
-  useEffect(() => {
-    // noop
+  const [queue, setQueue] = useState<OfflineQueueItem[]>([]);
+  const [isOnline, setIsOnline] = useState<boolean>(true);
+  const [toasts, setToasts] = useState<Toast[]>([]);
+  const [draining, setDraining] = useState(false);
+
+  const queueRef = useRef<OfflineQueueItem[]>([]);
+  const drainingRef = useRef(false);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const toastIdRef = useRef(0);
+  const mountedRef = useRef(true);
+
+  const pushToast = useCallback((message: string) => {
+    const id = ++toastIdRef.current;
+    setToasts((prev) => [...prev, { id, message }]);
+    setTimeout(() => {
+      setToasts((prev) => prev.filter((t) => t.id !== id));
+    }, 4000);
   }, []);
-  return null;
+
+  const commit = useCallback((next: OfflineQueueItem[]) => {
+    queueRef.current = next;
+    persistQueue(next);
+    if (mountedRef.current) setQueue(next);
+  }, []);
+
+  const drain = useCallback(async () => {
+    if (drainingRef.current) return;
+    if (typeof navigator !== 'undefined' && navigator.onLine === false) return;
+
+    const pending = queueRef.current.filter((item) => item.status !== 'failed');
+    if (pending.length === 0) return;
+
+    drainingRef.current = true;
+    if (mountedRef.current) setDraining(true);
+
+    for (const item of pending) {
+      // Mark as retrying.
+      commit(
+        queueRef.current.map((q) =>
+          q.id === item.id ? { ...q, status: 'retrying' as const } : q
+        )
+      );
+
+      try {
+        await retryOperation(item);
+        // Success: remove from queue.
+        commit(queueRef.current.filter((q) => q.id !== item.id));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        commit(
+          queueRef.current.map((q) =>
+            q.id === item.id
+              ? {
+                  ...q,
+                  status: 'failed' as const,
+                  attempts: q.attempts + 1,
+                  lastError: message,
+                }
+              : q
+          )
+        );
+      }
+    }
+
+    drainingRef.current = false;
+    if (mountedRef.current) setDraining(false);
+  }, [commit]);
+
+  const scheduleDrain = useCallback(() => {
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(() => {
+      debounceRef.current = null;
+      void drain();
+    }, RECONNECT_DEBOUNCE_MS);
+  }, [drain]);
+
+  const handleRetryItem = useCallback(
+    async (id: string) => {
+      const item = queueRef.current.find((q) => q.id === id);
+      if (!item) return;
+      commit(
+        queueRef.current.map((q) =>
+          q.id === id ? { ...q, status: 'retrying' as const } : q
+        )
+      );
+      try {
+        await retryOperation(item);
+        commit(queueRef.current.filter((q) => q.id !== id));
+        pushToast('Queued transaction sent successfully.');
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        commit(
+          queueRef.current.map((q) =>
+            q.id === id
+              ? {
+                  ...q,
+                  status: 'failed' as const,
+                  attempts: q.attempts + 1,
+                  lastError: message,
+                }
+              : q
+          )
+        );
+        pushToast('Retry failed. Transaction remains in queue.');
+      }
+    },
+    [commit, pushToast]
+  );
+
+  const handleDiscardItem = useCallback(
+    (id: string) => {
+      commit(queueRef.current.filter((q) => q.id !== id));
+      pushToast('Queued transaction discarded.');
+    },
+    [commit, pushToast]
+  );
+
+  const handleRetryAll = useCallback(() => {
+    void drain();
+  }, [drain]);
+
+  const handleDiscardAll = useCallback(() => {
+    commit([]);
+    pushToast('All queued transactions discarded.');
+  }, [commit, pushToast]);
+
+  // Hydrate persisted queue on mount.
+  useEffect(() => {
+    mountedRef.current = true;
+    const hydrated = loadQueue();
+    queueRef.current = hydrated;
+    setQueue(hydrated);
+
+    const online =
+      typeof navigator === 'undefined' ? true : navigator.onLine !== false;
+    setIsOnline(online);
+
+    if (hydrated.length > 0) {
+      pushToast(
+        `${hydrated.length} queued transaction${hydrated.length === 1 ? '' : 's'} restored.`
+      );
+    }
+
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [pushToast]);
+
+  // Subscribe to connectivity changes.
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const onOnline = () => {
+      setIsOnline(true);
+      pushToast('Connection restored. Retrying queued transactions…');
+      scheduleDrain();
+    };
+    const onOffline = () => {
+      setIsOnline(false);
+      pushToast('You are offline. Transactions will be queued.');
+    };
+
+    window.addEventListener('online', onOnline);
+    window.addEventListener('offline', onOffline);
+
+    return () => {
+      window.removeEventListener('online', onOnline);
+      window.removeEventListener('offline', onOffline);
+    };
+  }, [pushToast, scheduleDrain]);
+
+  // Drain on mount if online and queue has items.
+  useEffect(() => {
+    if (isOnline && queueRef.current.length > 0) {
+      scheduleDrain();
+    }
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+        debounceRef.current = null;
+      }
+    };
+  }, [isOnline, scheduleDrain]);
+
+  const pendingCount = queue.filter((q) => q.status !== 'failed').length;
+  const failedCount = queue.filter((q) => q.status === 'failed').length;
+
+  return (
+    <div className="offline-queue-sync" data-testid="offline-queue-sync">
+      {!isOnline && (
+        <div
+          role="status"
+          className="offline-queue-banner offline-queue-banner--offline"
+          data-testid="offline-queue-banner"
+        >
+          You are offline.
+          {queue.length > 0
+            ? ` ${queue.length} transaction${queue.length === 1 ? '' : 's'} queued.`
+            : ' Transactions will be queued.'}
+        </div>
+      )}
+
+      {isOnline && queue.length > 0 && (
+        <div
+          role="status"
+          className="offline-queue-banner offline-queue-banner--pending"
+          data-testid="offline-queue-banner"
+        >
+          {draining
+            ? 'Retrying queued transactions…'
+            : `${pendingCount} pending, ${failedCount} failed queued transaction${
+                queue.length === 1 ? '' : 's'
+              }.`}
+          <div className="offline-queue-actions">
+            <button
+              type="button"
+              onClick={handleRetryAll}
+              disabled={draining || !isOnline}
+              data-testid="offline-queue-retry-all"
+            >
+              Retry all
+            </button>
+            <button
+              type="button"
+              onClick={handleDiscardAll}
+              data-testid="offline-queue-discard-all"
+            >
+              Discard all
+            </button>
+          </div>
+        </div>
+      )}
+
+      {queue.length > 0 && (
+        <ul className="offline-queue-list" data-testid="offline-queue-list">
+          {queue.map((item) => (
+            <li
+              key={item.id}
+              className={`offline-queue-item offline-queue-item--${item.status}`}
+              data-testid={`offline-queue-item-${item.id}`}
+            >
+              <span className="offline-queue-item__label">
+                {item.operation} — {item.status}
+                {item.attempts > 0 ? ` (${item.attempts} attempt${item.attempts === 1 ? '' : 's'})` : ''}
+              </span>
+              {item.lastError && (
+                <span className="offline-queue-item__error">{item.lastError}</span>
+              )}
+              <span className="offline-queue-item__actions">
+                <button
+                  type="button"
+                  onClick={() => void handleRetryItem(item.id)}
+                  disabled={draining || !isOnline || item.status === 'retrying'}
+                  data-testid={`offline-queue-retry-${item.id}`}
+                >
+                  Retry
+                </button>
+                <button
+                  type="button"
+                  onClick={() => handleDiscardItem(item.id)}
+                  data-testid={`offline-queue-discard-${item.id}`}
+                >
+                  Discard
+                </button>
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <div
+        className="offline-queue-toasts"
+        aria-live="polite"
+        data-testid="offline-queue-toasts"
+      >
+        {toasts.map((toast) => (
+          <div
+            key={toast.id}
+            role="status"
+            className="offline-queue-toast"
+            data-testid="offline-queue-toast"
+          >
+            {toast.message}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Enqueue a failed transaction for later retry.
+ * Persists to storage and notifies listeners via a custom event.
+ */
+export function enqueueOfflineTransaction(
+  operation: string,
+  payload: unknown
+): OfflineQueueItem {
+  const item: OfflineQueueItem = {
+    id:
+      typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    operation,
+    payload,
+    status: 'pending',
+    attempts: 0,
+    createdAt: Date.now(),
+  };
+  const next = [...loadQueue(), item];
+  persistQueue(next);
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent('offline-queue:updated'));
+  }
+  return item;
 }
\ No newline at end of file
diff --git a/src/contexts/ToastContext.tsx b/src/contexts/ToastContext.tsx
index dcc58474..a7c9cc78 100644
--- a/src/contexts/ToastContext.tsx
+++ b/src/contexts/ToastContext.tsx
@@ -9,34 +9,76 @@ import {
   type ReactNode,
 } from "react";
 
-export type ToastType = "success" | "error" | "info" | "loading";
+export type ToastType = "success" | "error" | "info" | "loading" | "warning";
+
+export interface ToastAction {
+  label: string;
+  onClick: () => void;
+}
 
 export interface Toast {
   id: string;
   message: string;
   type: ToastType;
+  /** Optional deduplication key; toasts sharing a key are collapsed. */
+  dedupeKey?: string;
+  /** Optional action buttons (e.g. Retry / Discard). */
+  actions?: ToastAction[];
+  /** When true the toast will not auto-dismiss. */
+  persistent?: boolean;
+}
+
+export interface ToastOptions {
+  dedupeKey?: string;
+  actions?: ToastAction[];
+  persistent?: boolean;
 }
 
 interface ToastContextValue {
   toasts: Toast[];
   toast: {
-    success: (message: string) => string;
-    error: (message: string) => string;
-    info: (message: string) => string;
-    loading: (message: string) => string;
+    success: (message: string, options?: ToastOptions) => string;
+    error: (message: string, options?: ToastOptions) => string;
+    info: (message: string, options?: ToastOptions) => string;
+    loading: (message: string, options?: ToastOptions) => string;
+    warning: (message: string, options?: ToastOptions) => string;
     /** Upgrade an existing loading toast to success or error */
-    update: (id: string, message: string, type: Exclude<ToastType, "loading">) => void;
+    update: (
+      id: string,
+      message: string,
+      type: Exclude<ToastType, "loading">,
+      options?: ToastOptions
+    ) => void;
     dismiss: (id: string) => void;
+    /** Show a retry notification with a live countdown and optional cancel. */
+    retry: (message: string, options?: RetryToastOptions) => string;
+    /** Update the countdown text of an existing retry toast. */
+    retryCountdown: (id: string, secondsRemaining: number) => void;
+    /** Show a queue status notification with optional actions. */
+    queue: (message: string, options?: ToastOptions) => string;
   };
 }
 
+export interface RetryToastOptions extends ToastOptions {
+  /** Attempt number (1-based) for display, e.g. "Retry 2 of 5". */
+  attempt?: number;
+  maxAttempts?: number;
+  /** Seconds until the next retry; enables a live countdown. */
+  secondsRemaining?: number;
+  onCancel?: () => void;
+}
+
 const ToastContext = createContext<ToastContextValue | null>(null);
 
 const MAX_TOASTS = 5;
 const AUTO_DISMISS_MS = 4000;
+const RETRY_TOAST_DISMISS_MS = 8000;
+const QUEUE_TOAST_DISMISS_MS = 6000;
 
 export function ToastProvider({ children }: { children: ReactNode }) {
   const [toasts, setToasts] = useState<Toast[]>([]);
+  const toastsRef = useRef<Toast[]>([]);
+  toastsRef.current = toasts;
   const timers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
 
   const dismiss = useCallback((id: string) => {
@@ -46,43 +88,129 @@ export function ToastProvider({ children }: { children: ReactNode }) {
   }, []);
 
   const scheduleAutoDismiss = useCallback(
-    (id: string) => {
-      const timer = setTimeout(() => dismiss(id), AUTO_DISMISS_MS);
+    (id: string, durationMs: number = AUTO_DISMISS_MS) => {
+      clearTimeout(timers.current.get(id));
+      const timer = setTimeout(() => dismiss(id), durationMs);
       timers.current.set(id, timer);
     },
     [dismiss]
   );
 
   const add = useCallback(
-    (message: string, type: ToastType): string => {
+    (message: string, type: ToastType, options: ToastOptions = {}): string => {
+      const { dedupeKey, actions, persistent } = options;
+
+      // Deduplicate: if a toast with the same key exists, update it in place.
+      if (dedupeKey) {
+        const existing = toastsRef.current.find((t) => t.dedupeKey === dedupeKey);
+        if (existing) {
+          setToasts((prev) =>
+            prev.map((t) =>
+              t.id === existing.id
+                ? { ...t, message, type, actions, persistent }
+                : t
+            )
+          );
+          if (type !== "loading" && !persistent) scheduleAutoDismiss(existing.id);
+          else clearTimeout(timers.current.get(existing.id));
+          return existing.id;
+        }
+      }
+
       const id = `toast-${Date.now()}-${Math.random().toString(36).slice(2)}`;
       setToasts((prev) => {
-        const next = [...prev, { id, message, type }];
+        const next = [
+          ...prev,
+          { id, message, type, dedupeKey, actions, persistent },
+        ];
         return next.length > MAX_TOASTS ? next.slice(next.length - MAX_TOASTS) : next;
       });
-      if (type !== "loading") scheduleAutoDismiss(id);
+      if (type !== "loading" && !persistent) scheduleAutoDismiss(id);
       return id;
     },
     [scheduleAutoDismiss]
   );
 
   const update = useCallback(
-    (id: string, message: string, type: Exclude<ToastType, "loading">) => {
+    (
+      id: string,
+      message: string,
+      type: Exclude<ToastType, "loading">,
+      options: ToastOptions = {}
+    ) => {
       setToasts((prev) =>
-        prev.map((t) => (t.id === id ? { ...t, message, type } : t))
+        prev.map((t) =>
+          t.id === id
+            ? {
+                ...t,
+                message,
+                type,
+                actions: options.actions ?? t.actions,
+                persistent: options.persistent ?? t.persistent,
+              }
+            : t
+        )
       );
-      scheduleAutoDismiss(id);
+      if (options.persistent) clearTimeout(timers.current.get(id));
+      else scheduleAutoDismiss(id);
     },
     [scheduleAutoDismiss]
   );
 
+  const retry = useCallback(
+    (message: string, options: RetryToastOptions = {}): string => {
+      const { attempt, maxAttempts, secondsRemaining, onCancel, ...rest } = options;
+      const parts: string[] = [message];
+      if (attempt != null && maxAttempts != null) {
+        parts.push(`(attempt ${attempt} of ${maxAttempts})`);
+      }
+      if (secondsRemaining != null) {
+        parts.push(`Retrying in ${secondsRemaining}s…`);
+      }
+      const actions: ToastAction[] = [...(rest.actions ?? [])];
+      if (onCancel) actions.push({ label: "Cancel", onClick: onCancel });
+      return add(parts.join(" "), "warning", {
+        ...rest,
+        actions: actions.length > 0 ? actions : undefined,
+        persistent: rest.persistent ?? true,
+      });
+    },
+    [add]
+  );
+
+  const retryCountdown = useCallback(
+    (id: string, secondsRemaining: number) => {
+      setToasts((prev) =>
+        prev.map((t) => {
+          if (t.id !== id) return t;
+          const base = t.message.replace(/\s*Retrying in \d+s…$/, "");
+          return { ...t, message: `${base} Retrying in ${secondsRemaining}s…` };
+        })
+      );
+    },
+    []
+  );
+
+  const queue = useCallback(
+    (message: string, options: ToastOptions = {}): string =>
+      add(message, "info", {
+        ...options,
+        persistent: options.persistent ?? false,
+      }),
+    [add]
+  );
+
   const toast = {
-    success: (message: string) => add(message, "success"),
-    error: (message: string) => add(message, "error"),
-    info: (message: string) => add(message, "info"),
-    loading: (message: string) => add(message, "loading"),
+    success: (message: string, options?: ToastOptions) => add(message, "success", options),
+    error: (message: string, options?: ToastOptions) => add(message, "error", options),
+    info: (message: string, options?: ToastOptions) => add(message, "info", options),
+    loading: (message: string, options?: ToastOptions) => add(message, "loading", options),
+    warning: (message: string, options?: ToastOptions) => add(message, "warning", options),
     update,
     dismiss,
+    retry,
+    retryCountdown,
+    queue,
   };
 
   return (
@@ -106,6 +234,7 @@ const TYPE_STYLES: Record<ToastType, string> = {
   error: "bg-red-800 text-red-100 border-red-700",
   info: "bg-indigo-800 text-indigo-100 border-indigo-700",
   loading: "bg-gray-800 text-gray-100 border-gray-700",
+  warning: "bg-amber-800 text-amber-100 border-amber-700",
 };
 
 const TYPE_ICONS: Record<ToastType, string> = {
@@ -113,6 +242,7 @@ const TYPE_ICONS: Record<ToastType, string> = {
   error: "✕",
   info: "ℹ",
   loading: "⟳",
+  warning: "↻",
 };
 
 function ToastContainer({
@@ -144,6 +274,23 @@ function ToastContainer({
             {TYPE_ICONS[t.type]}
           </span>
           <span className="flex-1 break-words">{t.message}</span>
+          {t.actions && t.actions.length > 0 && (
+            <span className="flex shrink-0 items-center gap-2">
+              {t.actions.map((action, i) => (
+                <button
+                  key={`${t.id}-action-${i}`}
+                  type="button"
+                  onClick={() => {
+                    action.onClick();
+                    onDismiss(t.id);
+                  }}
+                  className="shrink-0 underline underline-offset-2 opacity-90 hover:opacity-100 transition-opacity focus:outline-none focus-visible:ring-2 focus-visible:ring-white rounded"
+                >
+                  {action.label}
+                </button>
+              ))}
+            </span>
+          )}
           <button
             type="button"
             onClick={() => onDismiss(t.id)}
diff --git a/src/hooks/usePaymentSubmission.ts b/src/hooks/usePaymentSubmission.ts
index b3be9cb3..c5e0478d 100644
--- a/src/hooks/usePaymentSubmission.ts
+++ b/src/hooks/usePaymentSubmission.ts
@@ -2,6 +2,10 @@
 
 import { useState, useCallback } from "react";
 import { simulateTransaction, SimulationResult } from "@/lib/simulateTx";
+import { retryWithBackoff } from "@/lib/retryWithBackoff";
+import { toAppError } from "@/lib/appError";
+import { useToast } from "@/context/ToastContext";
+import { useOfflineQueue } from "@/hooks/useOfflineQueue";
 
 interface PaymentSubmissionState {
   showSimulationPreview: boolean;
@@ -28,6 +32,9 @@ export function usePaymentSubmission(): UsePaymentSubmissionReturn {
     simulationError: null,
   });
 
+  const { notify } = useToast();
+  const { enqueue } = useOfflineQueue();
+
   const initiateDemoPayment = useCallback(
     async (
       transactionXdr: string,
@@ -42,40 +49,63 @@ export function usePaymentSubmission(): UsePaymentSubmissionReturn {
       }));
 
       try {
-        const result = await simulateTransaction(transactionXdr);
+        const result = await retryWithBackoff(
+          () => simulateTransaction(transactionXdr),
+          {
+            onRetry: (attempt, error) => {
+              notify({
+                type: "info",
+                message: `Simulation failed (${toAppError(error).message}). Retrying attempt ${attempt}...`,
+              });
+            },
+          }
+        );
         setState((prev) => ({
           ...prev,
           isSimulating: false,
           simulationResult: result,
         }));
       } catch (error) {
-        const errorMessage =
-          error instanceof Error ? error.message : "Failed to simulate transaction";
+        const appError = toAppError(error);
         setState((prev) => ({
           ...prev,
           isSimulating: false,
-          simulationError: errorMessage,
+          simulationError: appError.message,
         }));
       }
     },
-    []
+    [notify]
   );
 
   const handleProceed = useCallback(
     async (onConfirm: () => Promise<any>) => {
       try {
-        await onConfirm();
+        await retryWithBackoff(() => onConfirm(), {
+          onRetry: (attempt, error) => {
+            notify({
+              type: "info",
+              message: `Payment failed (${toAppError(error).message}). Retrying attempt ${attempt}...`,
+            });
+          },
+        });
         resetState();
       } catch (error) {
-        const errorMessage =
-          error instanceof Error ? error.message : "Payment failed";
-        setState((prev) => ({
-          ...prev,
-          simulationError: errorMessage,
-        }));
+        const appError = toAppError(error);
+        if (appError.isNetworkError) {
+          enqueue({ type: "payment", execute: onConfirm });
+          notify({
+            type: "warning",
+            message: "Connection lost. Payment queued and will retry when you're back online.",
+          });
+        } else {
+          setState((prev) => ({
+            ...prev,
+            simulationError: appError.message,
+          }));
+        }
       }
     },
-    []
+    [notify, enqueue]
   );
 
   const handleCancel = useCallback((onCancel: () => void) => {
@@ -86,18 +116,32 @@ export function usePaymentSubmission(): UsePaymentSubmissionReturn {
   const handleSkip = useCallback(
     async (onConfirm: () => Promise<any>) => {
       try {
-        await onConfirm();
+        await retryWithBackoff(() => onConfirm(), {
+          onRetry: (attempt, error) => {
+            notify({
+              type: "info",
+              message: `Payment failed (${toAppError(error).message}). Retrying attempt ${attempt}...`,
+            });
+          },
+        });
         resetState();
       } catch (error) {
-        const errorMessage =
-          error instanceof Error ? error.message : "Payment failed";
-        setState((prev) => ({
-          ...prev,
-          simulationError: errorMessage,
-        }));
+        const appError = toAppError(error);
+        if (appError.isNetworkError) {
+          enqueue({ type: "payment", execute: onConfirm });
+          notify({
+            type: "warning",
+            message: "Connection lost. Payment queued and will retry when you're back online.",
+          });
+        } else {
+          setState((prev) => ({
+            ...prev,
+            simulationError: appError.message,
+          }));
+        }
       }
     },
-    []
+    [notify, enqueue]
   );
 
   const resetState = useCallback(() => {
diff --git a/src/hooks/useStellarTransaction.ts b/src/hooks/useStellarTransaction.ts
index 727a4135..7fc6d1b8 100644
--- a/src/hooks/useStellarTransaction.ts
+++ b/src/hooks/useStellarTransaction.ts
@@ -2,8 +2,11 @@
 
 import { useCallback, useRef, useState } from "react";
 import { signTransaction, NETWORK_PASSPHRASE } from "@/lib/freighter";
-import { classifyError } from "@/lib/errors";
+import { classifyError, AppError } from "@/lib/errors";
 import { useToast } from "@/contexts/ToastContext";
+import { retryWithBackoff, isRetryableError } from "@/lib/retry";
+import { recordRetryMetric } from "@/lib/retryMetrics";
+import { enqueueTransaction } from "@/lib/offlineQueue";
 
 const HORIZON_URL =
   process.env.NEXT_PUBLIC_HORIZON_URL ??
@@ -83,12 +86,31 @@ export function useStellarTransaction() {
         const server = new Horizon.Server(HORIZON_URL);
         const tx = TransactionBuilder.fromXDR(signedXdr, NETWORK_PASSPHRASE);
 
-        const submitted = await server.submitTransaction(tx);
+        const onRetry = (attempt: number, error: unknown) => {
+          recordRetryMetric({ operation: "submitTransaction", attempt, error });
+          toast.info(
+            `Network hiccup — retrying transaction (attempt ${attempt})…`
+          );
+        };
+
+        const submitted = await retryWithBackoff(
+          () => server.submitTransaction(tx),
+          { onRetry }
+        );
         const hash = submitted.hash;
 
-        const confirmed = await pollForConfirmation(server, hash);
+        const confirmed = await retryWithBackoff(
+          () => pollForConfirmation(server, hash),
+          { onRetry: (attempt, error) => {
+            recordRetryMetric({ operation: "pollForConfirmation", attempt, error });
+            toast.info(`Still confirming — retrying (attempt ${attempt})…`);
+          } }
+        );
         if (!confirmed) {
-          throw new Error("Transaction did not confirm before timing out.");
+          throw new AppError(
+            "Transaction did not confirm before timing out.",
+            "TIMEOUT"
+          );
         }
 
         setTxHash(hash);
@@ -99,7 +121,19 @@ export function useStellarTransaction() {
         setStatus("error");
         // A user rejection already produced its own toast above.
         if (!isUserRejection(err)) {
-          toast.error(options.errorMessage ?? describeFailure(err));
+          if (isRetryableError(err)) {
+            // Persistent network failure — queue for retry on reconnect.
+            try {
+              await enqueueTransaction(unsignedXdr, options);
+              toast.info(
+                "You appear to be offline. The transaction has been queued and will be retried when your connection is restored."
+              );
+            } catch {
+              toast.error(options.errorMessage ?? describeFailure(err));
+            }
+          } else {
+            toast.error(options.errorMessage ?? describeFailure(err));
+          }
         }
         throw err;
       } finally {
@@ -150,6 +184,9 @@ async function pollForConfirmation(
 
 /** Turn a Horizon or SDK error into something a user can act on. */
 function describeFailure(error: unknown): string {
+  if (error instanceof AppError) {
+    return error.message;
+  }
   const horizonResult = (error as { response?: { data?: { extras?: { result_codes?: { transaction?: string } } } } })
     ?.response?.data?.extras?.result_codes?.transaction;
 
diff --git a/src/hooks/useTransactionWithRetry.ts b/src/hooks/useTransactionWithRetry.ts
index bd80ac2b..b7ef7849 100644
--- a/src/hooks/useTransactionWithRetry.ts
+++ b/src/hooks/useTransactionWithRetry.ts
@@ -1,5 +1,10 @@
 import { useCallback, useRef, useState } from 'react';
 import { useToast } from '@/contexts/ToastContext';
+import {
+  retryWithBackoff,
+  isRetryableError,
+  type RetryMetrics,
+} from '@/utils/retryWithBackoff';
 
 interface RetryOptions {
   maxRetries?: number;
@@ -7,8 +12,6 @@ interface RetryOptions {
   retryableStatusCodes?: number[];
 }
 
-const MAX_DELAY_MS = 30000;
-
 const DEFAULT_OPTIONS = {
   maxRetries: 5,
   initialDelayMs: 1000,
@@ -19,96 +22,62 @@ export function useTransactionWithRetry(options?: RetryOptions) {
   const toast = useToast();
   const abortControllers = useRef<Map<string, AbortController>>(new Map());
   const [attemptCount, setAttemptCount] = useState(0);
+  const [metrics, setMetrics] = useState<RetryMetrics | null>(null);
   const opts = { ...DEFAULT_OPTIONS, ...options };
 
-  const getStatusCode = (error: any): number | undefined => {
-    return error?.response?.status || error?.status;
-  };
-
-  const delay = (ms: number, operationId: string): Promise<void> => {
-    return new Promise((resolve, reject) => {
-      const startTime = Date.now();
-      const checkInterval = setInterval(() => {
-        if (abortControllers.current.get(operationId)?.signal.aborted) {
-          clearInterval(checkInterval);
-          reject(new Error('Transaction cancelled by user'));
-          return;
-        }
-        if (Date.now() - startTime >= ms) {
-          clearInterval(checkInterval);
-          resolve();
-        }
-      }, 100);
-    });
-  };
-
   const executeWithRetry = useCallback(
     async <T,>(
       fn: () => Promise<T>,
       operationId: string = `op-${Date.now()}-${Math.random()}`
     ): Promise<T> => {
-      let lastError: Error | null = null;
       let toastId: string | null = null;
 
-      for (let attempt = 1; attempt <= opts.maxRetries; attempt++) {
-        setAttemptCount(attempt);
-        try {
-          // Check if user cancelled
-          if (abortControllers.current.get(operationId)?.signal.aborted) {
-            throw new Error('Transaction cancelled by user');
-          }
-
-          const result = await fn();
-          if (toastId) toast.dismiss(toastId);
-          return result;
-        } catch (error) {
-          lastError = error instanceof Error ? error : new Error(String(error));
-          const statusCode = getStatusCode(error);
-          const isRetryable =
-            opts.retryableStatusCodes.includes(statusCode!) &&
-            attempt < opts.maxRetries;
-
-          if (isRetryable) {
-            const delayMs = Math.min(
-              opts.initialDelayMs * Math.pow(2, attempt - 1),
-              MAX_DELAY_MS
-            );
+      const controller = abortControllers.current.get(operationId);
+      const signal = controller?.signal;
+
+      try {
+        const result = await retryWithBackoff<T>(fn, {
+          maxRetries: opts.maxRetries,
+          initialDelayMs: opts.initialDelayMs,
+          signal,
+          isRetryable: (error) =>
+            isRetryableError(error, opts.retryableStatusCodes),
+          onAttempt: (attempt) => {
+            setAttemptCount(attempt);
+          },
+          onRetry: ({ attempt, delayMs, error }) => {
             const countdownSeconds = Math.ceil(delayMs / 1000);
-
-            // Show countdown toast
-            const message = `Rate limited. Retrying in ${countdownSeconds}s...`;
-            toastId = toast.info(message);
-
-            // Wait with cancellation support
-            try {
-              await delay(delayMs, operationId);
-            } catch (e) {
-              if (toastId) toast.dismiss(toastId);
-              throw e;
-            }
-          } else {
-            // Non-retryable error or max retries exceeded
-            const errorMsg = lastError?.message || 'Transaction failed';
-            const isMaxRetries = attempt === opts.maxRetries;
-
+            const reason =
+              (error as any)?.response?.status === 429 ||
+              (error as any)?.status === 429
+                ? 'Rate limited'
+                : 'Transient error';
             if (toastId) toast.dismiss(toastId);
-
-            if (isMaxRetries && opts.retryableStatusCodes.includes(statusCode!)) {
-              // Max retries for rate limit
-              toast.error(`${errorMsg}. Please try again later.`);
-            } else {
-              // Other errors
-              toast.error(errorMsg);
-            }
-
-            throw lastError;
-          }
+            toastId = toast.info(
+              `${reason}. Retrying in ${countdownSeconds}s... (attempt ${attempt}/${opts.maxRetries})`
+            );
+          },
+          onMetrics: (m) => {
+            setMetrics(m);
+          },
+        });
+
+        if (toastId) toast.dismiss(toastId);
+        return result;
+      } catch (error) {
+        if (toastId) toast.dismiss(toastId);
+
+        const err = error instanceof Error ? error : new Error(String(error));
+        const wasRetryable = isRetryableError(err, opts.retryableStatusCodes);
+
+        if (wasRetryable) {
+          toast.error(`${err.message}. Please try again later.`);
+        } else {
+          toast.error(err.message || 'Transaction failed');
         }
-      }
 
-      // Should not reach here but fallback
-      if (toastId) toast.dismiss(toastId);
-      throw lastError || new Error('Transaction failed');
+        throw err;
+      }
     },
     [opts, toast]
   );
@@ -121,5 +90,5 @@ export function useTransactionWithRetry(options?: RetryOptions) {
     }
   }, []);
 
-  return { executeWithRetry, cancel, attemptCount };
+  return { executeWithRetry, cancel, attemptCount, metrics };
 }
diff --git a/src/lib/api.ts b/src/lib/api.ts
index dbe96cef..c8c5ba30 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -4,11 +4,21 @@
  *
  * Consumers call `apiFetch` instead of raw `fetch`. When a 429 is received:
  *  - The global RateLimitContext is notified so the banner renders a countdown.
- *  - The request is queued and retried automatically after the delay.
+ *  - The request is retried with exponential backoff (honoring Retry-After).
  *  - Only one pending rate-limit state is tracked at a time; concurrent 429s
  *    do not duplicate the banner.
+ *  - If all retries are exhausted, an AppError is thrown and retry metrics
+ *    are recorded.
  */
 
+import { AppError } from "./errors";
+import {
+  retryWithBackoff,
+  parseRetryAfter,
+  recordRetryMetric,
+  type RetryAttemptInfo,
+} from "./retry";
+
 type RateLimitListener = (retryAt: number | null) => void;
 
 const listeners = new Set<RateLimitListener>();
@@ -30,28 +40,19 @@ function notify(retryAt: number | null) {
   listeners.forEach((fn) => fn(retryAt));
 }
 
-/**
- * Parse the Retry-After header value (seconds or HTTP-date) into milliseconds
- * from now. Falls back to 60 s if the header is absent or unparseable.
- */
-function parseRetryAfter(header: string | null): number {
-  if (!header) return 60_000;
-  const seconds = Number(header);
-  if (!Number.isNaN(seconds) && seconds > 0) return seconds * 1_000;
-  const date = new Date(header);
-  if (!Number.isNaN(date.getTime())) {
-    return Math.max(0, date.getTime() - Date.now());
-  }
-  return 60_000;
-}
+/** Maximum number of retry attempts for rate-limited requests. */
+const MAX_RATE_LIMIT_RETRIES = 3;
 
 /**
  * `apiFetch` is a drop-in replacement for `fetch` that adds transparent
- * 429-retry with countdown notification.
+ * 429-retry with exponential backoff and countdown notification.
  *
- * - Retries the request **once** after the Retry-After delay.
+ * - Retries the request up to MAX_RATE_LIMIT_RETRIES times, honoring the
+ *   Retry-After header when present and falling back to exponential backoff
+ *   with jitter otherwise.
  * - Resolves the original Promise as if the first call had succeeded.
  * - Multiple concurrent 429s share one countdown; the banner stays single.
+ * - Throws an AppError if all retries are exhausted.
  */
 export async function apiFetch(
   input: RequestInfo | URL,
@@ -61,19 +62,49 @@ export async function apiFetch(
 
   if (response.status !== 429) return response;
 
-  const delayMs = parseRetryAfter(response.headers.get("Retry-After"));
-  const retryAt = Date.now() + delayMs;
+  const retryAfterMs = parseRetryAfter(response.headers.get("Retry-After"));
 
-  // Only update state if no countdown is already running or this one is later.
-  if (currentRetryAt === null || retryAt > currentRetryAt) {
-    notify(retryAt);
+  // Notify the banner of the initial rate-limit window.
+  const initialRetryAt = Date.now() + retryAfterMs;
+  if (currentRetryAt === null || initialRetryAt > currentRetryAt) {
+    notify(initialRetryAt);
   }
 
-  // Wait for the retry window, then re-issue the request.
-  await new Promise<void>((resolve) => setTimeout(resolve, delayMs));
-
-  // Clear rate-limit state after retry fires.
-  notify(null);
-
-  return fetch(input, init);
+  try {
+    return await retryWithBackoff(
+      async () => {
+        const res = await fetch(input, init);
+        if (res.status === 429) {
+          const err = new AppError("RATE_LIMITED", "Too many requests", {
+            status: 429,
+            retryAfterMs: parseRetryAfter(res.headers.get("Retry-After")),
+          });
+          throw err;
+        }
+        return res;
+      },
+      {
+        maxAttempts: MAX_RATE_LIMIT_RETRIES,
+        retryAfterMs,
+        onRetry: (info: RetryAttemptInfo) => {
+          const retryAt = Date.now() + info.delayMs;
+          if (currentRetryAt === null || retryAt > currentRetryAt) {
+            notify(retryAt);
+          }
+        },
+        shouldRetry: (err: unknown) =>
+          err instanceof AppError && err.code === "RATE_LIMITED",
+      }
+    );
+  } catch (err) {
+    recordRetryMetric("rate_limit_exhausted");
+    throw new AppError(
+      "RATE_LIMIT_EXHAUSTED",
+      "The server is busy. Please try again in a moment.",
+      { cause: err, retryAfterMs }
+    );
+  } finally {
+    // Clear rate-limit state after retries complete.
+    notify(null);
+  }
 }
diff --git a/src/lib/apiClient.ts b/src/lib/apiClient.ts
index c1faa06a..668ea10f 100644
--- a/src/lib/apiClient.ts
+++ b/src/lib/apiClient.ts
@@ -6,10 +6,73 @@
  * on POST/PUT/PATCH/DELETE requests, refreshing the cached token before it
  * expires and transparently retrying once if a request is rejected with 403
  * because the token expired mid-flight.
+ *
+ * Non-OK responses are surfaced as `AppError` instances (see src/lib/errors.ts)
+ * so callers get a stable error code, a user-friendly message and recovery
+ * suggestions. Transient failures (network errors, 5xx, 429) are retried with
+ * exponential backoff + jitter via `retryWithBackoff` (see src/lib/retry.ts),
+ * and retry attempts are announced through `onRetry` so the UI can toast.
  */
 
+import { AppError, ErrorCode, type ErrorCodeValue } from "@/lib/errors";
+import { retryWithBackoff, type RetryEvent } from "@/lib/retry";
+
 const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 
+/** Options controlling retry behaviour and notifications for `apiFetch`. */
+export interface ApiFetchOptions extends RequestInit {
+  /** Maximum number of retry attempts for transient failures. Defaults to 3. */
+  maxRetries?: number;
+  /** Base delay (ms) for exponential backoff. Defaults to 300ms. */
+  baseDelayMs?: number;
+  /** Maximum delay (ms) between retries. Defaults to 10_000ms. */
+  maxDelayMs?: number;
+  /** Invoked before each retry so the UI can notify the user. */
+  onRetry?: (event: RetryEvent) => void;
+}
+
+/** Maps an HTTP status code to the closest matching `AppError` code. */
+export function statusToErrorCode(status: number): ErrorCodeValue {
+  switch (status) {
+    case 400:
+      return ErrorCode.VALIDATION;
+    case 401:
+      return ErrorCode.UNAUTHORIZED;
+    case 403:
+      return ErrorCode.FORBIDDEN;
+    case 404:
+      return ErrorCode.NOT_FOUND;
+    case 409:
+      return ErrorCode.CONFLICT;
+    case 429:
+      return ErrorCode.RATE_LIMITED;
+    default:
+      if (status >= 500) return ErrorCode.SERVER;
+      return ErrorCode.UNKNOWN;
+  }
+}
+
+/** True for failures worth retrying: network errors, 5xx and 429. */
+export function isRetryableStatus(status: number): boolean {
+  return status === 429 || status >= 500;
+}
+
+async function toAppError(response: Response): Promise<AppError> {
+  let detail: string | undefined;
+  try {
+    const body = await response.clone().json();
+    detail = typeof body?.message === "string" ? body.message : undefined;
+  } catch {
+    // Body was not JSON; fall back to the status text.
+    detail = response.statusText || undefined;
+  }
+  return new AppError(statusToErrorCode(response.status), {
+    status: response.status,
+    detail,
+    cause: response,
+  });
+}
+
 // Refresh a little early so a request that starts right before expiry
 // doesn't race the server-side clock.
 const REFRESH_SKEW_MS = 60 * 1000;
@@ -51,25 +114,61 @@ export function getCachedCsrfExpiry(): number {
  * fetch() wrapper that attaches a CSRF token to mutating requests and
  * retries once, with a freshly-fetched token, if the server rejects the
  * first attempt with 403.
+ *
+ * Transient failures (network errors, 5xx, 429) are retried with exponential
+ * backoff and jitter. Once retries are exhausted (or for non-retryable
+ * failures) a non-OK response is thrown as an `AppError`.
  */
-export async function apiFetch(input: RequestInfo | URL, init: RequestInit = {}): Promise<Response> {
-  const method = (init.method ?? "GET").toUpperCase();
+export async function apiFetch(
+  input: RequestInfo | URL,
+  init: ApiFetchOptions = {},
+): Promise<Response> {
+  const { maxRetries, baseDelayMs, maxDelayMs, onRetry, ...requestInit } = init;
+  const method = (requestInit.method ?? "GET").toUpperCase();
   if (!MUTATING_METHODS.has(method)) {
-    return fetch(input, init);
+    return fetch(input, requestInit);
   }
 
   const attempt = async (token: string) => {
-    const headers = new Headers(init.headers);
+    const headers = new Headers(requestInit.headers);
     headers.set("X-CSRF-Token", token);
-    return fetch(input, { ...init, headers });
+    return fetch(input, { ...requestInit, headers });
   };
 
-  const token = await getCsrfToken();
-  const response = await attempt(token);
-  if (response.status !== 403) {
-    return response;
-  }
+  // Single CSRF retry: refresh the token and try again on a 403.
+  const attemptWithCsrfRetry = async (): Promise<Response> => {
+    const token = await getCsrfToken();
+    const response = await attempt(token);
+    if (response.status !== 403) {
+      return response;
+    }
+    const freshToken = await getCsrfToken(true);
+    return attempt(freshToken);
+  };
+
+  const response = await retryWithBackoff(
+    async () => {
+      const res = await attemptWithCsrfRetry();
+      if (!res.ok && isRetryableStatus(res.status)) {
+        // Throw so the retry handler treats it as a transient failure.
+        throw await toAppError(res);
+      }
+      return res;
+    },
+    {
+      maxRetries,
+      baseDelayMs,
+      maxDelayMs,
+      onRetry,
+      isRetryable: (error) =>
+        error instanceof AppError
+          ? error.status !== undefined && isRetryableStatus(error.status)
+          : true, // network errors are retryable
+    },
+  );
 
-  const freshToken = await getCsrfToken(true);
-  return attempt(freshToken);
+  if (!response.ok) {
+    throw await toAppError(response);
+  }
+  return response;
 }
diff --git a/src/lib/config.ts b/src/lib/config.ts
index 84a271b0..e1eb7336 100644
--- a/src/lib/config.ts
+++ b/src/lib/config.ts
@@ -15,10 +15,115 @@ export const RPC_URL =
 /** StellarSplit contract ID used for on-chain calls and event filtering. */
 export const contractId = process.env.NEXT_PUBLIC_CONTRACT_ID ?? "";
 
+/**
+ * Parse a positive integer env var, falling back to a default when unset or invalid.
+ */
+function positiveIntEnv(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === "") return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+/**
+ * Parse a non-negative number env var (e.g. jitter factor), falling back when invalid.
+ */
+function nonNegativeFloatEnv(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === "") return fallback;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+/**
+ * Parse a boolean env var ("true"/"1" => true, "false"/"0" => false).
+ */
+function boolEnv(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined || value.trim() === "") return fallback;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1") return true;
+  if (normalized === "false" || normalized === "0") return false;
+  return fallback;
+}
+
+/** Retry / exponential backoff configuration. */
+export interface RetryConfig {
+  /** Maximum number of retry attempts after the initial failure. */
+  maxRetries: number;
+  /** Base delay (ms) used for the first backoff interval. */
+  baseDelayMs: number;
+  /** Upper bound (ms) for any single backoff interval. */
+  maxDelayMs: number;
+  /** Random jitter factor (0..1) applied to each delay to avoid thundering herd. */
+  jitterFactor: number;
+  /** Whether automatic retries are enabled. */
+  enabled: boolean;
+  /** Whether to surface retry notifications to the user. */
+  notify: boolean;
+}
+
+/** Offline queue configuration for failed transactions. */
+export interface OfflineQueueConfig {
+  /** Maximum number of operations held in the queue. */
+  maxSize: number;
+  /** Storage key used to persist the queue across restarts. */
+  storageKey: string;
+  /** Whether the offline queue is enabled. */
+  enabled: boolean;
+  /** Whether to automatically flush the queue when connectivity is restored. */
+  autoRetryOnReconnect: boolean;
+  /** Whether to notify the user of queue status changes. */
+  notify: boolean;
+  /** Maximum age (ms) of a queued item before it is considered stale. */
+  maxItemAgeMs: number;
+}
+
+/** Feature flags for retry and offline queue behavior. */
+export interface RetryFeatureFlags {
+  retry: boolean;
+  offlineQueue: boolean;
+  retryMetrics: boolean;
+}
+
+export const RETRY_CONFIG: RetryConfig = {
+  maxRetries: positiveIntEnv(process.env.NEXT_PUBLIC_MAX_RETRIES, 5),
+  baseDelayMs: positiveIntEnv(process.env.NEXT_PUBLIC_RETRY_BASE_DELAY_MS, 500),
+  maxDelayMs: positiveIntEnv(process.env.NEXT_PUBLIC_RETRY_MAX_DELAY_MS, 30_000),
+  jitterFactor: Math.min(
+    1,
+    nonNegativeFloatEnv(process.env.NEXT_PUBLIC_RETRY_JITTER_FACTOR, 0.2),
+  ),
+  enabled: boolEnv(process.env.NEXT_PUBLIC_RETRY_ENABLED, true),
+  notify: boolEnv(process.env.NEXT_PUBLIC_RETRY_NOTIFY, true),
+} as const;
+
+export const OFFLINE_QUEUE_CONFIG: OfflineQueueConfig = {
+  maxSize: positiveIntEnv(process.env.NEXT_PUBLIC_OFFLINE_QUEUE_MAX_SIZE, 50),
+  storageKey:
+    process.env.NEXT_PUBLIC_OFFLINE_QUEUE_STORAGE_KEY ?? "stellarsplit:offline-queue",
+  enabled: boolEnv(process.env.NEXT_PUBLIC_OFFLINE_QUEUE_ENABLED, true),
+  autoRetryOnReconnect: boolEnv(
+    process.env.NEXT_PUBLIC_OFFLINE_QUEUE_AUTO_RETRY,
+    true,
+  ),
+  notify: boolEnv(process.env.NEXT_PUBLIC_OFFLINE_QUEUE_NOTIFY, true),
+  maxItemAgeMs: positiveIntEnv(
+    process.env.NEXT_PUBLIC_OFFLINE_QUEUE_MAX_ITEM_AGE_MS,
+    24 * 60 * 60 * 1000,
+  ),
+} as const;
+
+export const RETRY_FEATURE_FLAGS: RetryFeatureFlags = {
+  retry: RETRY_CONFIG.enabled,
+  offlineQueue: OFFLINE_QUEUE_CONFIG.enabled,
+  retryMetrics: boolEnv(process.env.NEXT_PUBLIC_RETRY_METRICS_ENABLED, true),
+} as const;
+
 export const config = {
   network: STELLAR_NETWORK,
   rpcUrl: RPC_URL,
   contractId,
+  retry: RETRY_CONFIG,
+  offlineQueue: OFFLINE_QUEUE_CONFIG,
+  features: RETRY_FEATURE_FLAGS,
 } as const;
 
-export default config;
+export default config;
\ No newline at end of file
diff --git a/src/lib/errors.ts b/src/lib/errors.ts
index 39152421..d95a23db 100644
--- a/src/lib/errors.ts
+++ b/src/lib/errors.ts
@@ -4,6 +4,387 @@ export type ErrorKind =
   | "rpc_timeout"
   | "unknown";
 
+/**
+ * Unified application error taxonomy.
+ *
+ * `AppErrorCode` is the canonical, stable set of error codes used across the
+ * app. Existing `ErrorKind` / `RpcErrorKind` classifiers are kept for backward
+ * compatibility and are mapped onto these codes.
+ */
+export type AppErrorCode =
+  | "network"
+  | "validation"
+  | "auth"
+  | "wallet"
+  | "contract"
+  | "rate_limit"
+  | "unknown";
+
+export type AppErrorSeverity = "info" | "warning" | "error" | "fatal";
+
+export interface AppErrorOptions {
+  code?: AppErrorCode;
+  severity?: AppErrorSeverity;
+  retryable?: boolean;
+  /** User-safe message. Never include secrets or raw stack traces here. */
+  userMessage?: string;
+  /** Original error, kept for logging/debugging only. */
+  cause?: unknown;
+  /** Arbitrary structured context for logs (no secrets). */
+  context?: Record<string, unknown>;
+}
+
+const DEFAULT_SEVERITY: Record<AppErrorCode, AppErrorSeverity> = {
+  network: "warning",
+  validation: "info",
+  auth: "warning",
+  wallet: "warning",
+  contract: "error",
+  rate_limit: "warning",
+  unknown: "error",
+};
+
+const DEFAULT_RETRYABLE: Record<AppErrorCode, boolean> = {
+  network: true,
+  validation: false,
+  auth: false,
+  wallet: false,
+  contract: false,
+  rate_limit: true,
+  unknown: false,
+};
+
+/**
+ * Structured application error. Carries a stable code, severity, retryability
+ * and a user-safe message, while retaining the original cause for logging.
+ */
+export class AppError extends Error {
+  readonly code: AppErrorCode;
+  readonly severity: AppErrorSeverity;
+  readonly retryable: boolean;
+  readonly userMessage: string;
+  readonly context?: Record<string, unknown>;
+
+  constructor(message: string, options: AppErrorOptions = {}) {
+    super(message);
+    this.name = "AppError";
+    this.code = options.code ?? "unknown";
+    this.severity = options.severity ?? DEFAULT_SEVERITY[this.code];
+    this.retryable = options.retryable ?? DEFAULT_RETRYABLE[this.code];
+    this.userMessage = options.userMessage ?? getErrorMessageTemplate(this.code);
+    this.context = options.context;
+    if (options.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      severity: this.severity,
+      retryable: this.retryable,
+      message: this.message,
+      userMessage: this.userMessage,
+      context: this.context,
+    };
+  }
+}
+
+export function isAppError(value: unknown): value is AppError {
+  return value instanceof AppError;
+}
+
+/** Map legacy `ErrorKind` values onto the unified taxonomy. */
+export function errorKindToCode(kind: ErrorKind): AppErrorCode {
+  switch (kind) {
+    case "wallet_not_connected":
+      return "wallet";
+    case "invoice_not_found":
+      return "validation";
+    case "rpc_timeout":
+      return "network";
+    case "unknown":
+    default:
+      return "unknown";
+  }
+}
+
+/** Map legacy `RpcErrorKind` values onto the unified taxonomy. */
+export function rpcErrorKindToCode(kind: RpcErrorKind): AppErrorCode {
+  switch (kind) {
+    case "network":
+      return "network";
+    case "contract":
+      return "contract";
+    case "unknown":
+    default:
+      return "unknown";
+  }
+}
+
+const ERROR_MESSAGE_TEMPLATES: Record<AppErrorCode, string> = {
+  network: "We couldn't reach the network. Check your connection and try again.",
+  validation: "Some of the information provided isn't valid. Please review and try again.",
+  auth: "You need to sign in to continue.",
+  wallet: "Connect your Freighter wallet to continue.",
+  contract: "The transaction was rejected by the network. Please review the details and try again.",
+  rate_limit: "Too many requests right now. Please wait a moment and try again.",
+  unknown: "Something went wrong. Please try again.",
+};
+
+/** Return the user-safe message template for a given error code. */
+export function getErrorMessageTemplate(code: AppErrorCode): string {
+  return ERROR_MESSAGE_TEMPLATES[code] ?? ERROR_MESSAGE_TEMPLATES.unknown;
+}
+
+const RECOVERY_SUGGESTIONS: Record<AppErrorCode, string[]> = {
+  network: [
+    "Check your internet connection.",
+    "Wait a few seconds and retry.",
+  ],
+  validation: [
+    "Review the highlighted fields for mistakes.",
+    "Correct the values and submit again.",
+  ],
+  auth: [
+    "Sign in with your account.",
+    "If your session expired, sign in again.",
+  ],
+  wallet: [
+    "Install or unlock the Freighter wallet extension.",
+    "Connect your wallet and retry.",
+  ],
+  contract: [
+    "Review the transaction details before retrying.",
+    "Ensure your account has sufficient balance and trustlines.",
+  ],
+  rate_limit: [
+    "Wait a moment before trying again.",
+    "Avoid repeated rapid submissions.",
+  ],
+  unknown: [
+    "Try again in a moment.",
+    "If the problem persists, contact support with the error details.",
+  ],
+};
+
+/** Return ordered recovery suggestions for a given error code. */
+export function getRecoverySuggestions(code: AppErrorCode): string[] {
+  return [...(RECOVERY_SUGGESTIONS[code] ?? RECOVERY_SUGGESTIONS.unknown)];
+}
+
+/** Normalize any thrown value into an `AppError`. */
+export function toAppError(error: unknown, options: AppErrorOptions = {}): AppError {
+  if (isAppError(error)) return error;
+
+  const text = error instanceof Error ? error.message : String(error);
+  const classified = classifyError(error);
+  const code = options.code ?? errorKindToCode(classified.kind);
+
+  return new AppError(text || getErrorMessageTemplate(code), {
+    ...options,
+    code,
+    cause: options.cause ?? error,
+  });
+}
+
+export interface ErrorLogEntry {
+  timestamp: string;
+  code: AppErrorCode;
+  severity: AppErrorSeverity;
+  retryable: boolean;
+  message: string;
+  userMessage: string;
+  context?: Record<string, unknown>;
+  cause?: unknown;
+}
+
+export interface ErrorLogger {
+  log(entry: ErrorLogEntry): void;
+}
+
+const consoleErrorLogger: ErrorLogger = {
+  log(entry) {
+    // eslint-disable-next-line no-console
+    console.error("[AppError]", entry);
+  },
+};
+
+let activeLogger: ErrorLogger = consoleErrorLogger;
+
+/** Replace the active logger (useful for tests / telemetry backends). */
+export function setErrorLogger(logger: ErrorLogger | null): void {
+  activeLogger = logger ?? consoleErrorLogger;
+}
+
+/** Structured logger helper. Never throws. */
+export function logError(error: unknown, context?: Record<string, unknown>): ErrorLogEntry {
+  const appError = toAppError(error, { context });
+  const entry: ErrorLogEntry = {
+    timestamp: new Date().toISOString(),
+    code: appError.code,
+    severity: appError.severity,
+    retryable: appError.retryable,
+    message: appError.message,
+    userMessage: appError.userMessage,
+    context: appError.context,
+    cause: (appError as { cause?: unknown }).cause,
+  };
+
+  try {
+    activeLogger.log(entry);
+  } catch {
+    // Logging must never break the app.
+  }
+
+  return entry;
+}
+
+export interface RetryMetrics {
+  attempts: number;
+  successes: number;
+  failures: number;
+  retries: number;
+  totalLatencyMs: number;
+}
+
+const retryMetrics: RetryMetrics = {
+  attempts: 0,
+  successes: 0,
+  failures: 0,
+  retries: 0,
+  totalLatencyMs: 0,
+};
+
+/** Snapshot of in-memory retry metrics for debugging. */
+export function getRetryMetrics(): RetryMetrics {
+  return { ...retryMetrics };
+}
+
+/** Reset in-memory retry metrics (useful for tests). */
+export function resetRetryMetrics(): void {
+  retryMetrics.attempts = 0;
+  retryMetrics.successes = 0;
+  retryMetrics.failures = 0;
+  retryMetrics.retries = 0;
+  retryMetrics.totalLatencyMs = 0;
+}
+
+export interface RetryOptions {
+  /** Maximum number of attempts (including the first). Default 3. */
+  maxAttempts?: number;
+  /** Base delay in ms for exponential backoff. Default 300. */
+  baseDelayMs?: number;
+  /** Maximum delay in ms between attempts. Default 5000. */
+  maxDelayMs?: number;
+  /** Jitter factor (0..1) applied to each delay. Default 0.2. */
+  jitter?: number;
+  /** Predicate deciding whether an error is retryable. Default: AppError.retryable. */
+  isRetryable?: (error: unknown) => boolean;
+  /** Optional abort signal to cancel retries. */
+  signal?: AbortSignal;
+  /** Called before each retry with the upcoming attempt number and delay. */
+  onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void;
+  /** Injectable sleep for tests. Default: setTimeout-based. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("Aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("Aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function defaultIsRetryable(error: unknown): boolean {
+  if (isAppError(error)) return error.retryable;
+  const classified = classifyError(error);
+  return errorKindToCode(classified.kind) === "network";
+}
+
+/** Compute the backoff delay for a given attempt (1-based). */
+export function computeBackoffDelay(
+  attempt: number,
+  baseDelayMs: number,
+  maxDelayMs: number,
+  jitter: number,
+  random: () => number = Math.random,
+): number {
+  const exponential = Math.min(maxDelayMs, baseDelayMs * 2 ** Math.max(0, attempt - 1));
+  const jitterAmount = exponential * Math.min(1, Math.max(0, jitter));
+  return Math.round(exponential - jitterAmount + random() * jitterAmount * 2);
+}
+
+/**
+ * Retry an async operation with exponential backoff and jitter.
+ * Records metrics and notifies via `onRetry`. Never retries more than
+ * `maxAttempts` times and respects cancellation via `signal`.
+ */
+export async function retryWithBackoff<T>(
+  operation: (attempt: number) => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    baseDelayMs = 300,
+    maxDelayMs = 5000,
+    jitter = 0.2,
+    isRetryable = defaultIsRetryable,
+    signal,
+    onRetry,
+    sleep = defaultSleep,
+  } = options;
+
+  const attemptsLimit = Math.max(1, Math.floor(maxAttempts));
+  const startedAt = Date.now();
+  let lastError: unknown;
+
+  for (let attempt = 1; attempt <= attemptsLimit; attempt += 1) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new Error("Aborted");
+    }
+
+    retryMetrics.attempts += 1;
+
+    try {
+      const result = await operation(attempt);
+      retryMetrics.successes += 1;
+      retryMetrics.totalLatencyMs += Date.now() - startedAt;
+      return result;
+    } catch (error) {
+      lastError = error;
+      const canRetry = attempt < attemptsLimit && isRetryable(error);
+
+      if (!canRetry) {
+        retryMetrics.failures += 1;
+        retryMetrics.totalLatencyMs += Date.now() - startedAt;
+        throw error;
+      }
+
+      retryMetrics.retries += 1;
+      const delayMs = computeBackoffDelay(attempt, baseDelayMs, maxDelayMs, jitter);
+      onRetry?.({ attempt: attempt + 1, delayMs, error });
+      await sleep(delayMs, signal);
+    }
+  }
+
+  retryMetrics.failures += 1;
+  retryMetrics.totalLatencyMs += Date.now() - startedAt;
+  throw lastError;
+}
+
 export interface ClassifiedError {
   kind: ErrorKind;
   message: string;
diff --git a/src/lib/offlineQueue.ts b/src/lib/offlineQueue.ts
index f665e854..3bf39612 100644
--- a/src/lib/offlineQueue.ts
+++ b/src/lib/offlineQueue.ts
@@ -20,9 +20,43 @@ interface StoredPayment {
   error?: string;
 }
 
+/**
+ * Serializable queued transaction schema used by the hardened offline queue.
+ * All fields are JSON-safe so the queue can be persisted to IndexedDB or
+ * localStorage and hydrated on startup.
+ */
+export interface QueuedTransaction {
+  id: string;
+  payload: Record<string, unknown>;
+  status: "pending" | "submitting" | "failed";
+  attempts: number;
+  createdAt: number;
+  updatedAt: number;
+  lastAttemptAt?: number;
+  error?: string;
+}
+
+export type QueueStatus = {
+  pending: number;
+  submitting: number;
+  failed: number;
+  total: number;
+  online: boolean;
+  draining: boolean;
+};
+
+export type QueueStatusListener = (status: QueueStatus) => void;
+
 const DB_NAME = "stellarsplit-offline";
 const STORE_NAME = "payments";
-const DB_VERSION = 1;
+const TX_STORE_NAME = "transactions";
+const DB_VERSION = 2;
+
+const LS_KEY = "stellarsplit-offline-queue";
+const MAX_ATTEMPTS = 5;
+const BASE_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 30_000;
+const DRAIN_DEBOUNCE_MS = 250;
 
 function toStored(payment: QueuedPayment): StoredPayment {
   return { ...payment, amount: payment.amount.toString() };
@@ -45,6 +79,9 @@ export async function openDB(): Promise<IDBPDatabase> {
       if (!db.objectStoreNames.contains(STORE_NAME)) {
         db.createObjectStore(STORE_NAME, { keyPath: "id" });
       }
+      if (!db.objectStoreNames.contains(TX_STORE_NAME)) {
+        db.createObjectStore(TX_STORE_NAME, { keyPath: "id" });
+      }
     },
   });
 }
@@ -147,4 +184,378 @@ export function setupOnlineListener(
   };
   window.addEventListener("online", handler);
   return () => window.removeEventListener("online", handler);
+}
+
+/* -------------------------------------------------------------------------- */
+/* Hardened offline transaction queue                                         */
+/* -------------------------------------------------------------------------- */
+
+function isBrowser(): boolean {
+  return typeof window !== "undefined";
+}
+
+function hasIndexedDB(): boolean {
+  return typeof indexedDB !== "undefined";
+}
+
+function hasLocalStorage(): boolean {
+  try {
+    return typeof localStorage !== "undefined";
+  } catch {
+    return false;
+  }
+}
+
+function readLocalStorageQueue(): QueuedTransaction[] {
+  if (!hasLocalStorage()) return [];
+  try {
+    const raw = localStorage.getItem(LS_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (t): t is QueuedTransaction =>
+        t && typeof t.id === "string" && typeof t.payload === "object"
+    );
+  } catch {
+    return [];
+  }
+}
+
+function writeLocalStorageQueue(queue: QueuedTransaction[]): void {
+  if (!hasLocalStorage()) return;
+  try {
+    localStorage.setItem(LS_KEY, JSON.stringify(queue));
+  } catch {
+    // Storage may be full or unavailable; ignore.
+  }
+}
+
+async function readAllTransactions(): Promise<QueuedTransaction[]> {
+  if (hasIndexedDB()) {
+    try {
+      const db = await openDB();
+      const stored: QueuedTransaction[] = await db.getAll(TX_STORE_NAME);
+      return stored;
+    } catch {
+      // Fall through to localStorage.
+    }
+  }
+  return readLocalStorageQueue();
+}
+
+async function writeTransaction(tx: QueuedTransaction): Promise<void> {
+  if (hasIndexedDB()) {
+    try {
+      const db = await openDB();
+      await db.put(TX_STORE_NAME, tx);
+      return;
+    } catch {
+      // Fall through to localStorage.
+    }
+  }
+  const queue = readLocalStorageQueue();
+  const idx = queue.findIndex((t) => t.id === tx.id);
+  if (idx >= 0) queue[idx] = tx;
+  else queue.push(tx);
+  writeLocalStorageQueue(queue);
+}
+
+async function deleteTransaction(id: string): Promise<void> {
+  if (hasIndexedDB()) {
+    try {
+      const db = await openDB();
+      await db.delete(TX_STORE_NAME, id);
+      return;
+    } catch {
+      // Fall through to localStorage.
+    }
+  }
+  const queue = readLocalStorageQueue().filter((t) => t.id !== id);
+  writeLocalStorageQueue(queue);
+}
+
+async function getTransaction(id: string): Promise<QueuedTransaction | undefined> {
+  if (hasIndexedDB()) {
+    try {
+      const db = await openDB();
+      const tx = await db.get(TX_STORE_NAME, id);
+      if (tx) return tx as QueuedTransaction;
+    } catch {
+      // Fall through to localStorage.
+    }
+  }
+  return readLocalStorageQueue().find((t) => t.id === id);
+}
+
+export function computeBackoffDelay(attempts: number): number {
+  const exp = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** Math.max(0, attempts - 1));
+  const jitter = Math.random() * exp * 0.25;
+  return Math.min(MAX_BACKOFF_MS, exp + jitter);
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function retryWithBackoff<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxAttempts?: number;
+    shouldRetry?: (error: unknown) => boolean;
+    onAttempt?: (attempt: number, error: unknown) => void;
+  } = {}
+): Promise<T> {
+  const maxAttempts = options.maxAttempts ?? MAX_ATTEMPTS;
+  const shouldRetry = options.shouldRetry ?? isNetworkError;
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (options.onAttempt) options.onAttempt(attempt, err);
+      if (attempt >= maxAttempts || !shouldRetry(err)) {
+        throw err;
+      }
+      await sleep(computeBackoffDelay(attempt));
+    }
+  }
+  throw lastError;
+}
+
+/* ------------------------------- Queue state ------------------------------ */
+
+const statusListeners = new Set<QueueStatusListener>();
+let draining = false;
+let drainTimer: ReturnType<typeof setTimeout> | null = null;
+let onlineHandler: (() => void) | null = null;
+let offlineHandler: (() => void) | null = null;
+let currentSubmitFn: ((tx: QueuedTransaction) => Promise<void>) | null = null;
+
+export function isOnline(): boolean {
+  if (!isBrowser()) return true;
+  if (typeof navigator !== "undefined" && typeof navigator.onLine === "boolean") {
+    return navigator.onLine;
+  }
+  return true;
+}
+
+export async function getQueueStatus(): Promise<QueueStatus> {
+  const txs = await readAllTransactions();
+  const status: QueueStatus = {
+    pending: 0,
+    submitting: 0,
+    failed: 0,
+    total: txs.length,
+    online: isOnline(),
+    draining,
+  };
+  for (const tx of txs) {
+    if (tx.status === "pending") status.pending++;
+    else if (tx.status === "submitting") status.submitting++;
+    else if (tx.status === "failed") status.failed++;
+  }
+  return status;
+}
+
+async function notifyStatus(): Promise<void> {
+  if (statusListeners.size === 0) return;
+  const status = await getQueueStatus();
+  for (const listener of statusListeners) {
+    try {
+      listener(status);
+    } catch {
+      // Ignore listener errors.
+    }
+  }
+}
+
+export function subscribeToQueueStatus(
+  listener: QueueStatusListener
+): () => void {
+  statusListeners.add(listener);
+  void notifyStatus();
+  return () => {
+    statusListeners.delete(listener);
+  };
+}
+
+/* ------------------------------ Queue APIs -------------------------------- */
+
+export async function enqueueTransaction(
+  payload: Record<string, unknown>
+): Promise<string> {
+  const now = Date.now();
+  const tx: QueuedTransaction = {
+    id: createId(),
+    payload,
+    status: "pending",
+    attempts: 0,
+    createdAt: now,
+    updatedAt: now,
+  };
+  await writeTransaction(tx);
+  await notifyStatus();
+  return tx.id;
+}
+
+export async function getQueuedTransactions(): Promise<QueuedTransaction[]> {
+  const txs = await readAllTransactions();
+  txs.sort((a, b) => a.createdAt - b.createdAt);
+  return txs;
+}
+
+export async function discardTransaction(id: string): Promise<void> {
+  await deleteTransaction(id);
+  await notifyStatus();
+}
+
+export async function discardAllFailed(): Promise<void> {
+  const txs = await readAllTransactions();
+  for (const tx of txs) {
+    if (tx.status === "failed") {
+      await deleteTransaction(tx.id);
+    }
+  }
+  await notifyStatus();
+}
+
+async function attemptTransaction(
+  tx: QueuedTransaction,
+  submitFn: (tx: QueuedTransaction) => Promise<void>
+): Promise<{ id: string; success: boolean; error?: string }> {
+  const submitting: QueuedTransaction = {
+    ...tx,
+    status: "submitting",
+    attempts: tx.attempts + 1,
+    lastAttemptAt: Date.now(),
+    updatedAt: Date.now(),
+    error: undefined,
+  };
+  await writeTransaction(submitting);
+
+  try {
+    await retryWithBackoff(() => submitFn(submitting), {
+      maxAttempts: 1,
+      shouldRetry: isNetworkError,
+    });
+    await deleteTransaction(tx.id);
+    return { id: tx.id, success: true };
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : "Unknown error";
+    const network = isNetworkError(err);
+    const exhausted = submitting.attempts >= MAX_ATTEMPTS;
+    const nextStatus: QueuedTransaction["status"] =
+      network && !exhausted ? "pending" : "failed";
+    const updated: QueuedTransaction = {
+      ...submitting,
+      status: nextStatus,
+      updatedAt: Date.now(),
+      error: errorMsg,
+    };
+    await writeTransaction(updated);
+    return { id: tx.id, success: false, error: errorMsg };
+  }
+}
+
+export async function retryTransaction(
+  id: string,
+  submitFn: (tx: QueuedTransaction) => Promise<void>
+): Promise<{ id: string; success: boolean; error?: string }> {
+  const tx = await getTransaction(id);
+  if (!tx) {
+    return { id, success: false, error: `Transaction ${id} not found` };
+  }
+  const result = await attemptTransaction(tx, submitFn);
+  await notifyStatus();
+  return result;
+}
+
+export async function retryAllFailed(
+  submitFn: (tx: QueuedTransaction) => Promise<void>
+): Promise<Array<{ id: string; success: boolean; error?: string }>> {
+  const txs = await readAllTransactions();
+  const failed = txs.filter((t) => t.status === "failed");
+  const results: Array<{ id: string; success: boolean; error?: string }> = [];
+  for (const tx of failed) {
+    results.push(await attemptTransaction(tx, submitFn));
+  }
+  await notifyStatus();
+  return results;
+}
+
+export async function drainQueue(
+  submitFn: (tx: QueuedTransaction) => Promise<void>
+): Promise<Array<{ id: string; success: boolean; error?: string }>> {
+  if (draining) return [];
+  if (!isOnline()) return [];
+  draining = true;
+  await notifyStatus();
+  const results: Array<{ id: string; success: boolean; error?: string }> = [];
+  try {
+    const txs = await readAllTransactions();
+    const pending = txs.filter((t) => t.status === "pending");
+    for (const tx of pending) {
+      if (!isOnline()) break;
+      results.push(await attemptTransaction(tx, submitFn));
+    }
+  } finally {
+    draining = false;
+    await notifyStatus();
+  }
+  return results;
+}
+
+function scheduleDrain(): void {
+  if (drainTimer) return;
+  drainTimer = setTimeout(() => {
+    drainTimer = null;
+    if (currentSubmitFn) {
+      void drainQueue(currentSubmitFn);
+    }
+  }, DRAIN_DEBOUNCE_MS);
+}
+
+/**
+ * Hydrate the queue on startup and install connectivity listeners that drain
+ * the queue when the connection is restored. Returns a teardown function.
+ */
+export function initOfflineQueue(
+  submitFn: (tx: QueuedTransaction) => Promise<void>
+): () => void {
+  currentSubmitFn = submitFn;
+
+  if (isBrowser()) {
+    onlineHandler = () => {
+      scheduleDrain();
+    };
+    offlineHandler = () => {
+      void notifyStatus();
+    };
+    window.addEventListener("online", onlineHandler);
+    window.addEventListener("offline", offlineHandler);
+  }
+
+  // Hydrate + drain on startup if online.
+  void (async () => {
+    await notifyStatus();
+    if (isOnline()) {
+      scheduleDrain();
+    }
+  })();
+
+  return () => {
+    if (isBrowser()) {
+      if (onlineHandler) window.removeEventListener("online", onlineHandler);
+      if (offlineHandler) window.removeEventListener("offline", offlineHandler);
+    }
+    onlineHandler = null;
+    offlineHandler = null;
+    currentSubmitFn = null;
+    if (drainTimer) {
+      clearTimeout(drainTimer);
+      drainTimer = null;
+    }
+  };
 }
\ No newline at end of file
diff --git a/src/lib/stellarErrorParser.ts b/src/lib/stellarErrorParser.ts
index 3615c609..bce7cfa7 100644
--- a/src/lib/stellarErrorParser.ts
+++ b/src/lib/stellarErrorParser.ts
@@ -1,3 +1,10 @@
+import {
+  AppError,
+  AppErrorCode,
+  createAppError,
+  RecoverySuggestion,
+} from './appError';
+
 export type ErrorActionType = 'bump-fee' | 'refresh-seq' | 'fund-destination' | 'manual';
 
 export interface ParsedStellarError {
@@ -8,6 +15,80 @@ export interface ParsedStellarError {
   actionType: ErrorActionType;
 }
 
+/**
+ * Maps a Stellar/Horizon result code to the AppError taxonomy code.
+ */
+const STELLAR_TO_APP_ERROR_CODE: Record<string, AppErrorCode> = {
+  tx_insufficient_fee: 'STELLAR_INSUFFICIENT_FEE',
+  tx_bad_seq: 'STELLAR_BAD_SEQUENCE',
+  op_no_destination: 'STELLAR_NO_DESTINATION',
+  op_underfunded: 'STELLAR_UNDERFUNDED',
+  tx_failed: 'STELLAR_TX_FAILED',
+  op_no_trust: 'STELLAR_NO_TRUSTLINE',
+};
+
+/**
+ * Whether a given Stellar result code is worth retrying (possibly after a
+ * recovery action such as bumping the fee or refreshing the sequence).
+ */
+const STELLAR_RETRYABLE: Record<string, boolean> = {
+  tx_insufficient_fee: true,
+  tx_bad_seq: true,
+  op_no_destination: false,
+  op_underfunded: false,
+  tx_failed: false,
+  op_no_trust: false,
+};
+
+/**
+ * Recovery suggestions keyed by Stellar result code, expressed in the
+ * AppError taxonomy so they can be surfaced consistently across the app.
+ */
+const STELLAR_RECOVERY: Record<string, RecoverySuggestion[]> = {
+  tx_insufficient_fee: [
+    {
+      label: 'Increase transaction fee',
+      description: 'Bump the fee to match current network conditions.',
+      actionType: 'bump-fee',
+    },
+  ],
+  tx_bad_seq: [
+    {
+      label: 'Refresh sequence number',
+      description: 'Reload the account sequence from the network and retry.',
+      actionType: 'refresh-seq',
+    },
+  ],
+  op_no_destination: [
+    {
+      label: 'Fund destination account',
+      description: 'Send at least 1 XLM to the destination to activate it.',
+      actionType: 'fund-destination',
+    },
+  ],
+  op_underfunded: [
+    {
+      label: 'Add funds',
+      description: 'Top up the source account balance and try again.',
+      actionType: 'manual',
+    },
+  ],
+  tx_failed: [
+    {
+      label: 'Review transaction details',
+      description: 'Check the detailed error and verify account requirements.',
+      actionType: 'manual',
+    },
+  ],
+  op_no_trust: [
+    {
+      label: 'Create trustline',
+      description: 'Establish a trustline for the asset before retrying.',
+      actionType: 'manual',
+    },
+  ],
+};
+
 const ERROR_MAPPING: Record<string, ParsedStellarError> = {
   tx_insufficient_fee: {
     code: 'tx_insufficient_fee',
@@ -98,3 +179,108 @@ export function isFundingError(error: any): boolean {
   const parsed = parseStellarError(error?.message || error?.code || String(error), error);
   return parsed.actionType === 'fund-destination';
 }
+
+/**
+ * Extracts a normalized Stellar result code from a variety of error shapes:
+ * plain strings, Horizon HTTP error responses, and RPC error objects.
+ */
+export function extractStellarResultCode(error: unknown): string | undefined {
+  if (error == null) return undefined;
+
+  if (typeof error === 'string') {
+    const trimmed = error.trim();
+    return trimmed.length > 0 ? trimmed.toLowerCase() : undefined;
+  }
+
+  if (typeof error !== 'object') {
+    return String(error).toLowerCase();
+  }
+
+  const anyError = error as any;
+
+  // Horizon HTTP response shape: { response: { data: { result_code, extras: { result_codes } } } }
+  const data = anyError.response?.data ?? anyError.data;
+  if (data) {
+    if (typeof data.result_code === 'string') {
+      return data.result_code.toLowerCase();
+    }
+    const resultCodes = data.extras?.result_codes;
+    if (resultCodes) {
+      const candidates: unknown[] = [
+        ...(Array.isArray(resultCodes.transaction) ? resultCodes.transaction : [resultCodes.transaction]),
+        ...(Array.isArray(resultCodes.operations) ? resultCodes.operations : [resultCodes.operations]),
+      ];
+      for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.length > 0) {
+          return candidate.toLowerCase();
+        }
+      }
+    }
+  }
+
+  // RPC / generic error object shapes
+  if (typeof anyError.result_code === 'string') {
+    return anyError.result_code.toLowerCase();
+  }
+  if (typeof anyError.code === 'string') {
+    return anyError.code.toLowerCase();
+  }
+  if (typeof anyError.message === 'string') {
+    return anyError.message.toLowerCase();
+  }
+
+  return undefined;
+}
+
+/**
+ * Normalizes any Stellar/Horizon/RPC error into the AppError taxonomy.
+ * Known result codes map to specific AppError codes with retryable flags and
+ * recovery suggestions; unknown codes fall back to a generic AppError.
+ */
+export function toAppError(error: unknown): AppError {
+  const resultCode = extractStellarResultCode(error);
+
+  if (resultCode) {
+    // Direct or partial match against known Stellar result codes.
+    let matchedKey: string | undefined;
+    if (STELLAR_TO_APP_ERROR_CODE[resultCode]) {
+      matchedKey = resultCode;
+    } else {
+      matchedKey = Object.keys(STELLAR_TO_APP_ERROR_CODE).find((key) =>
+        resultCode.includes(key),
+      );
+    }
+
+    if (matchedKey) {
+      const parsed = ERROR_MAPPING[matchedKey];
+      return createAppError({
+        code: STELLAR_TO_APP_ERROR_CODE[matchedKey],
+        title: parsed.title,
+        message: parsed.explanation,
+        retryable: STELLAR_RETRYABLE[matchedKey] ?? false,
+        recovery: STELLAR_RECOVERY[matchedKey] ?? [],
+        cause: error,
+        context: { stellarResultCode: matchedKey },
+      });
+    }
+  }
+
+  // Fallback for unknown errors.
+  return createAppError({
+    code: 'UNKNOWN_ERROR',
+    title: 'Transaction Error',
+    message: resultCode
+      ? `The transaction failed with error: ${resultCode}`
+      : 'An unexpected error occurred while processing the transaction.',
+    retryable: false,
+    recovery: [
+      {
+        label: 'Review error details',
+        description: 'Review the error details and contact support if the issue persists.',
+        actionType: 'manual',
+      },
+    ],
+    cause: error,
+    context: resultCode ? { stellarResultCode: resultCode } : undefined,
+  });
+}
diff --git a/src/middleware.ts b/src/middleware.ts
index 04e00824..eec1d09c 100644
--- a/src/middleware.ts
+++ b/src/middleware.ts
@@ -32,7 +32,14 @@ export const config = {
      * Skip static assets and image optimization files — they carry no
      * inline scripts and re-running CSP generation for every asset request
      * is pure overhead.
+     *
+     * Also skip the interactive API documentation route (/api-docs) and the
+     * static OpenAPI spec (/openapi.json, /openapi.yaml). Swagger UI ships its
+     * own bundled scripts/styles and the spec is a static JSON/YAML document,
+     * so neither needs a per-request CSP nonce. Excluding them lets the
+     * Swagger UI assets load correctly while CSP protections remain in place
+     * for the rest of the app.
      */
-    "/((?!_next/static|_next/image|favicon.ico|icons/|manifest.json|sw.js).*)",
+    "/((?!_next/static|_next/image|favicon.ico|icons/|manifest.json|sw.js|api-docs|openapi\\.(?:json|yaml|yml)).*)",
   ],
-};
+};
\ No newline at end of file
diff --git a/vitest.config.ts b/vitest.config.ts
index 794ee594..0a824d1c 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -9,15 +9,30 @@ export default defineConfig({
     environment: 'jsdom',
     setupFiles: ['./vitest.setup.ts', './src/__tests__/setup.ts'],
     exclude: ['e2e/**', 'node_modules/**'],
+    include: [
+      'src/**/*.{test,spec}.{ts,tsx}',
+      'src/**/__tests__/**/*.{test,spec}.{ts,tsx}',
+      'src/__tests__/**/*.{test,spec}.{ts,tsx}',
+    ],
     server: {
       deps: {
         inline: ['@stellar/freighter-api', '@stellar-split/sdk'],
       },
     },
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: [
+        'src/**/*.{test,spec}.{ts,tsx}',
+        'src/**/__tests__/**',
+        'src/**/*.d.ts',
+      ],
+    },
   },
   resolve: {
     alias: {
       '@': path.resolve(__dirname, './src'),
     },
   },
-});
+});
\ No newline at end of file
diff --git a/vitest.setup.ts b/vitest.setup.ts
index bbecb87e..4ae09d9f 100644
--- a/vitest.setup.ts
+++ b/vitest.setup.ts
@@ -1,5 +1,6 @@
 import '@testing-library/jest-dom';
-import { vi } from 'vitest';
+import { vi, beforeEach, afterEach } from 'vitest';
+import 'fake-indexeddb/auto';
 
 (globalThis as any).jest = vi as any;
 
@@ -35,3 +36,62 @@ vi.mock('@stellar/freighter-api', () => ({
   }),
   WatchWalletChanges: vi.fn().mockReturnValue({ unsubscribe: vi.fn() }),
 }));
+
+// ---------------------------------------------------------------------------
+// Reliability feature test setup (error handling, retry, offline queue)
+// ---------------------------------------------------------------------------
+
+// Track online status so tests can simulate connectivity changes.
+let onlineStatus = true;
+
+Object.defineProperty(globalThis.navigator, 'onLine', {
+  configurable: true,
+  get: () => onlineStatus,
+});
+
+/**
+ * Simulate a connectivity change. Dispatches the appropriate window event so
+ * listeners registered by the offline queue / connectivity hooks fire.
+ */
+export function setOnlineStatus(online: boolean): void {
+  onlineStatus = online;
+  const event = new Event(online ? 'online' : 'offline');
+  globalThis.window?.dispatchEvent(event);
+}
+
+(globalThis as any).setOnlineStatus = setOnlineStatus;
+
+// Mock fetch so tests never hit the network. Individual tests can override
+// this with vi.mocked(fetch).mockResolvedValueOnce(...) etc.
+const fetchMock = vi.fn(async () =>
+  new Response(JSON.stringify({ ok: true }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  })
+);
+vi.stubGlobal('fetch', fetchMock);
+
+// Reset retry metrics between tests if the metrics module is present.
+async function resetRetryMetrics(): Promise<void> {
+  try {
+    const mod: any = await import('./lib/reliability/retryMetrics');
+    if (mod && typeof mod.resetRetryMetrics === 'function') {
+      mod.resetRetryMetrics();
+    } else if (mod && mod.retryMetrics && typeof mod.retryMetrics.reset === 'function') {
+      mod.retryMetrics.reset();
+    }
+  } catch {
+    // Metrics module not present in this test context; nothing to reset.
+  }
+}
+
+beforeEach(async () => {
+  onlineStatus = true;
+  fetchMock.mockClear();
+  await resetRetryMetrics();
+});
+
+afterEach(() => {
+  onlineStatus = true;
+  vi.clearAllMocks();
+});
\ No newline at end of file