diff --git a/.github/docs/NIGHTLY-BUILD.md b/.github/docs/NIGHTLY-BUILD.md
index 519a918a..2e7e0cd9 100644
--- a/.github/docs/NIGHTLY-BUILD.md
+++ b/.github/docs/NIGHTLY-BUILD.md
@@ -17,8 +17,9 @@ Tracks are specified as a comma-separated string in the `NIGHTLY_TRACKS` repo va
 | `test-backend-<branch>` | Run backend tests against `<branch>` |
 | `test-frontend-<branch>` | Run frontend tests against `<branch>` |
 | `deploy-<branch>` | Deploy full stack from `<branch>` with automatic teardown |
+| `e2e-<branch>` | Deploy full stack from `<branch>`, run Playwright E2E tests, then teardown |
 | `merge-validation:<base>:<overlay>` | Deploy `<base>`, then overlay `<overlay>` on top (colons delimit to avoid branch name ambiguity) |
-| `all` | Run all tracks with defaults: tests + deploy on `develop`, MV `main`→`develop` |
+| `all` | Run all tracks with defaults: tests + deploy + e2e on `develop`, MV `main`→`develop` |
 
 ### Examples
 
@@ -27,9 +28,10 @@ test-backend-develop
 test-frontend-main,test-backend-main
 deploy-develop
 deploy-main,deploy-develop
+e2e-develop
 merge-validation:main:develop
 merge-validation:main:feature/my-branch
-test-backend-develop,deploy-develop,merge-validation:main:develop
+test-backend-develop,deploy-develop,e2e-develop,merge-validation:main:develop
 all
 ```
 
@@ -44,7 +46,7 @@ The `resolve-tracks` job parses the tracks string into boolean flags and branch
 ## Workflow Jobs
 
 ### resolve-tracks
-Parses the tracks string and outputs boolean flags (`run_test_backend`, `run_test_frontend`, `run_deploy`, `run_mv`) and branch refs for each enabled track.
+Parses the tracks string and outputs boolean flags (`run_test_backend`, `run_test_frontend`, `run_deploy`, `run_e2e`, `run_mv`) and branch refs for each enabled track.
 
 ### Test Tracks
 
@@ -62,7 +64,23 @@ When `deploy-<branch>` is specified, calls the reusable `nightly-deploy-pipeline
 - `alb-subdomain`: `nightly-<branch>-api`
 - Automatic teardown (unless `skip_teardown` is set)
 
-The deploy pipeline runs: install-infra → check-stack-deps → deploy-infra → deploy-rag → deploy-inference → deploy-app → deploy-frontend + deploy-gateway → smoke-test → teardown.
+The deploy pipeline runs: install-infra → check-stack-deps → deploy-infra → deploy-rag → deploy-inference → deploy-app → deploy-frontend + deploy-gateway → smoke-test → e2e-tests (if enabled) → teardown.
+
+### E2E Test Track
+
+When `e2e-<branch>` is specified, calls the reusable `nightly-deploy-pipeline.yml` with:
+- `project-prefix`: `nightly-e2e-<branch>`
+- `alb-subdomain`: `nightly-e2e-<branch>-api`
+- `run-e2e`: `true`
+- Automatic teardown (unless `skip_teardown` is set)
+
+This deploys a full stack and runs Playwright E2E tests against it. The E2E job runs after the smoke test confirms the stack is healthy. It uses a separate CI Playwright config (`playwright.ci.config.ts`) that points at the deployed stack URL instead of starting local servers.
+
+E2E test failures are **informational** — they mark the nightly summary as "partial" rather than "failed". This allows the track to stabilize without blocking other tracks.
+
+**Required secrets** (in the `development` environment):
+- `E2E_ADMIN_USERNAME` / `E2E_ADMIN_PASSWORD` — Cognito admin test account
+- `E2E_USER_USERNAME` / `E2E_USER_PASSWORD` — Cognito regular user test account
 
 ### Merge Validation Track
 
@@ -91,6 +109,7 @@ Reusable workflow (`workflow_call`) containing the full deploy pipeline.
 | `skip-teardown` | no | Skip teardown (default: `false`) |
 | `label` | no | Label for job names |
 | `source-project-prefix` | no | If set, Docker jobs try ECR image promotion before building |
+| `run-e2e` | no | Run Playwright E2E tests after smoke test (default: `false`) |
 
 ### Promote-or-Build Pattern
 
@@ -126,6 +145,8 @@ Deploy and MV tracks use the `development` GitHub environment with overrides:
 ### Required Secrets
 - `AWS_ROLE_ARN` or `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`
 - `GITHUB_TOKEN` (automatically provided)
+- `E2E_ADMIN_USERNAME` / `E2E_ADMIN_PASSWORD` — Cognito admin test account (required for e2e track)
+- `E2E_USER_USERNAME` / `E2E_USER_PASSWORD` — Cognito regular user test account (required for e2e track)
 
 ### Required Variables
 - `AWS_REGION`, `CDK_AWS_ACCOUNT`
@@ -138,6 +159,7 @@ Deploy and MV tracks use the `development` GitHub environment with overrides:
 | `backend-coverage` | 30 days | Backend test track enabled |
 | `frontend-coverage` | 30 days | Frontend test track enabled |
 | `coverage-comparison` | 30 days | Any test track succeeded |
+| `playwright-report-<label>` | 30 days | E2E track enabled (includes HTML report, screenshots, traces) |
 
 ## Troubleshooting
 
@@ -159,3 +181,10 @@ Check that `NIGHTLY_TRACKS` is set as a repository variable (not a secret). Empt
 
 ### Merge validation fails on overlay
 This is the intended signal — it means the overlay branch has CDK/infra incompatibilities with the base branch that need to be resolved before merging.
+
+### E2E tests fail
+- Download the `playwright-report-<label>` artifact for screenshots and traces
+- Check that `E2E_ADMIN_USERNAME`, `E2E_ADMIN_PASSWORD`, `E2E_USER_USERNAME`, `E2E_USER_PASSWORD` secrets are set in the `development` environment
+- Verify the Cognito test users exist and have the correct roles
+- If auth setup fails, the Cognito managed login UI may have changed — check the `auth-admin.setup.ts` / `auth-user.setup.ts` selectors
+- E2E failures are informational and do not block other tracks
diff --git a/.github/workflows/nightly-deploy-pipeline.yml b/.github/workflows/nightly-deploy-pipeline.yml
index 8e169568..2eb2a8a2 100644
--- a/.github/workflows/nightly-deploy-pipeline.yml
+++ b/.github/workflows/nightly-deploy-pipeline.yml
@@ -34,6 +34,11 @@ on:
         required: false
         default: ''
         type: string
+      run-e2e:
+        description: 'Run Playwright E2E tests after smoke test (requires Cognito test user secrets)'
+        required: false
+        default: 'false'
+        type: string
 
 permissions:
   contents: read
@@ -584,10 +589,80 @@ jobs:
           echo "status=$STATUS" >> "$GITHUB_OUTPUT"
           echo "duration=$SECONDS" >> "$GITHUB_OUTPUT"
 
+  e2e-tests:
+    name: "[${{ inputs.label }}] E2E Tests"
+    runs-on: ubuntu-24.04
+    needs: smoke-test
+    if: ${{ inputs.run-e2e == 'true' && needs.smoke-test.result == 'success' }}
+    environment: development
+    outputs:
+      status: ${{ steps.summary.outputs.status }}
+      duration: ${{ steps.summary.outputs.duration }}
+    permissions:
+      id-token: write
+      contents: read
+    env:
+      CDK_AWS_REGION: ${{ vars.AWS_REGION }}
+      CDK_PROJECT_PREFIX: ${{ inputs.project-prefix }}
+      CDK_ALB_SUBDOMAIN: ${{ inputs.alb-subdomain }}
+      CDK_HOSTED_ZONE_DOMAIN: ${{ vars.CDK_HOSTED_ZONE_DOMAIN }}
+      ADMIN_USERNAME: ${{ secrets.E2E_ADMIN_USERNAME }}
+      ADMIN_PASSWORD: ${{ secrets.E2E_ADMIN_PASSWORD }}
+      USER_USERNAME: ${{ secrets.E2E_USER_USERNAME }}
+      USER_PASSWORD: ${{ secrets.E2E_USER_PASSWORD }}
+      AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }}
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ inputs.ref }}
+
+      - name: Restore frontend node_modules cache
+        id: cache-frontend
+        uses: actions/cache/restore@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          path: frontend/ai.client/node_modules
+          key: frontend-node-modules-${{ hashFiles('frontend/ai.client/package-lock.json') }}
+
+      - name: Install frontend dependencies
+        if: steps.cache-frontend.outputs.cache-hit != 'true'
+        run: bash scripts/stack-frontend/install.sh
+
+      - name: Configure AWS credentials
+        uses: ./.github/actions/configure-aws-credentials
+        with:
+          aws-region: ${{ env.CDK_AWS_REGION }}
+          role-session-name: GitHubActions-${{ inputs.label }}-E2E
+          aws-role-arn: ${{ env.AWS_ROLE_ARN }}
+          aws-access-key-id: ${{ env.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ env.AWS_SECRET_ACCESS_KEY }}
+
+      - name: Run E2E tests
+        id: run-tests
+        run: bash scripts/nightly/e2e-test.sh
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: playwright-report-${{ inputs.label }}
+          path: frontend/ai.client/playwright-report/
+          retention-days: 30
+
+      - name: Generate summary
+        id: summary
+        if: always()
+        run: |
+          if [ "${{ steps.run-tests.outcome }}" = "success" ]; then STATUS="success"; else STATUS="failure"; fi
+          echo "status=$STATUS" >> "$GITHUB_OUTPUT"
+          echo "duration=$SECONDS" >> "$GITHUB_OUTPUT"
+
   teardown:
     name: "[${{ inputs.label }}] Teardown"
     runs-on: ubuntu-24.04
-    needs: smoke-test
+    needs: [smoke-test, e2e-tests]
     if: ${{ always() && inputs.skip-teardown != 'true' }}
     environment: development
     outputs:
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index c723e413..e604f4ec 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -5,10 +5,11 @@
 #   test-backend-<branch>              Run backend tests against <branch>
 #   test-frontend-<branch>             Run frontend tests against <branch>
 #   deploy-<branch>                    Deploy full stack from <branch>
+#   e2e-<branch>                       Deploy full stack, run Playwright E2E tests, teardown
 #   merge-validation:<base>:<overlay>  Deploy <base>, then overlay <overlay>
 #   scan-images-<branch>               Scan Docker images from <branch> for vulnerabilities
 #   all                                Run all tracks with default branches
-#                                      (tests + deploy on develop, MV main→develop)
+#                                      (tests + deploy + e2e on develop, MV main→develop)
 #
 # Examples:
 #   test-backend-develop
@@ -79,6 +80,8 @@ jobs:
       mv_overlay_ref: ${{ steps.resolve.outputs.mv_overlay_ref }}
       run_scan_images: ${{ steps.resolve.outputs.run_scan_images }}
       scan_images_ref: ${{ steps.resolve.outputs.scan_images_ref }}
+      run_e2e: ${{ steps.resolve.outputs.run_e2e }}
+      e2e_ref: ${{ steps.resolve.outputs.e2e_ref }}
       any_track: ${{ steps.resolve.outputs.any_track }}
     steps:
       - name: Parse tracks
@@ -103,6 +106,8 @@ jobs:
           mv_overlay_ref=""
           run_scan_images=false
           scan_images_ref=""
+          run_e2e=false
+          e2e_ref=""
 
           # Empty tracks = nothing runs (fork-safe default)
           if [ -z "$TRACKS" ]; then
@@ -125,6 +130,8 @@ jobs:
                   mv_overlay_ref="develop"
                   run_scan_images=true
                   scan_images_ref="develop"
+                  run_e2e=true
+                  e2e_ref="develop"
                   ;;
                 test-backend-*)
                   run_test_backend=true
@@ -147,6 +154,10 @@ jobs:
                   run_scan_images=true
                   scan_images_ref="${token#scan-images-}"
                   ;;
+                e2e-*)
+                  run_e2e=true
+                  e2e_ref="${token#e2e-}"
+                  ;;
                 *)
                   echo "::warning::Unknown track token: $token"
                   ;;
@@ -158,7 +169,7 @@ jobs:
           any_track=false
           if [ "$run_test_backend" = "true" ] || [ "$run_test_frontend" = "true" ] || \
              [ "$run_deploy" = "true" ] || [ "$run_mv" = "true" ] || \
-             [ "$run_scan_images" = "true" ]; then
+             [ "$run_scan_images" = "true" ] || [ "$run_e2e" = "true" ]; then
             any_track=true
           fi
 
@@ -175,6 +186,8 @@ jobs:
             echo "mv_overlay_ref=$mv_overlay_ref"
             echo "run_scan_images=$run_scan_images"
             echo "scan_images_ref=$scan_images_ref"
+            echo "run_e2e=$run_e2e"
+            echo "e2e_ref=$e2e_ref"
             echo "any_track=$any_track"
           } >> "$GITHUB_OUTPUT"
 
@@ -185,6 +198,7 @@ jobs:
           echo "  deploy:        $run_deploy (ref: $deploy_ref)"
           echo "  mv:            $run_mv (base: $mv_base_ref, overlay: $mv_overlay_ref)"
           echo "  scan-images:   $run_scan_images (ref: $scan_images_ref)"
+          echo "  e2e:           $run_e2e (ref: $e2e_ref)"
           echo "  any_track:     $any_track"
 
   # ── Test Tracks ───────────────────────────────────────────────────────────
@@ -471,6 +485,27 @@ jobs:
       label: deploy-${{ needs.resolve-tracks.outputs.deploy_ref }}
     secrets: inherit
 
+  # ── E2E Test Track ────────────────────────────────────────────────────────
+  # Deploys the full stack and runs Playwright E2E tests against it.
+  # Uses the deploy pipeline with run-e2e enabled. Separate from the deploy
+  # track so you can deploy without E2E or run E2E independently.
+
+  e2e:
+    needs: resolve-tracks
+    if: needs.resolve-tracks.outputs.run_e2e == 'true'
+    permissions:
+      id-token: write
+      contents: read
+    uses: ./.github/workflows/nightly-deploy-pipeline.yml
+    with:
+      ref: ${{ needs.resolve-tracks.outputs.e2e_ref }}
+      project-prefix: nightly-e2e-${{ needs.resolve-tracks.outputs.e2e_ref }}
+      alb-subdomain: nightly-e2e-${{ needs.resolve-tracks.outputs.e2e_ref }}-api
+      skip-teardown: ${{ github.event.inputs.skip_teardown || 'false' }}
+      label: e2e-${{ needs.resolve-tracks.outputs.e2e_ref }}
+      run-e2e: 'true'
+    secrets: inherit
+
   # ── Merge Validation Track ────────────────────────────────────────────────
   # Deploys base branch first, then overlays the overlay branch on top —
   # simulating a real merge to catch CDK/infra incompatibilities.
@@ -593,7 +628,7 @@ jobs:
   summary:
     name: Nightly Summary
     runs-on: ubuntu-24.04
-    needs: [resolve-tracks, test-backend, test-frontend, analyze-coverage, ai-coverage-analysis, deploy, mv-base, mv-overlay, scan-images]
+    needs: [resolve-tracks, test-backend, test-frontend, analyze-coverage, ai-coverage-analysis, deploy, e2e, mv-base, mv-overlay, scan-images]
     if: always() && needs.resolve-tracks.outputs.any_track == 'true'
     steps:
       - name: Checkout code
@@ -606,9 +641,11 @@ jobs:
           RUN_TEST_BACKEND: ${{ needs.resolve-tracks.outputs.run_test_backend }}
           RUN_TEST_FRONTEND: ${{ needs.resolve-tracks.outputs.run_test_frontend }}
           RUN_DEPLOY: ${{ needs.resolve-tracks.outputs.run_deploy }}
+          RUN_E2E: ${{ needs.resolve-tracks.outputs.run_e2e }}
           RUN_MV: ${{ needs.resolve-tracks.outputs.run_mv }}
           RUN_SCAN_IMAGES: ${{ needs.resolve-tracks.outputs.run_scan_images }}
           DEPLOY_REF: ${{ needs.resolve-tracks.outputs.deploy_ref }}
+          E2E_REF: ${{ needs.resolve-tracks.outputs.e2e_ref }}
           MV_BASE_REF: ${{ needs.resolve-tracks.outputs.mv_base_ref }}
           MV_OVERLAY_REF: ${{ needs.resolve-tracks.outputs.mv_overlay_ref }}
         run: |
@@ -657,6 +694,13 @@ jobs:
             [ "$status" = "failure" ] && AGGREGATE="failure"
           fi
 
+          # E2E track (reusable workflow — informational, does not fail aggregate)
+          if [ "$RUN_E2E" = "true" ]; then
+            status="$(map_status "${{ needs.e2e.result }}")"
+            ROWS+=("E2E Tests (${E2E_REF})|${status}|0")
+            [ "$status" = "failure" ] && [ "$AGGREGATE" != "failure" ] && AGGREGATE="partial"
+          fi
+
           # MV tracks
           if [ "$RUN_MV" = "true" ]; then
             status="$(map_status "${{ needs.mv-base.result }}")"
diff --git a/.kiro/steering/e2e-testing.md b/.kiro/steering/e2e-testing.md
new file mode 100644
index 00000000..e52cb65e
--- /dev/null
+++ b/.kiro/steering/e2e-testing.md
@@ -0,0 +1,269 @@
+---
+inclusion: fileMatch
+fileMatchPattern: "frontend/ai.client/e2e/**"
+---
+
+# E2E Testing Guidelines (Playwright)
+
+Reference: #[[file:frontend/ai.client/playwright.config.ts]]
+
+## Framework & Configuration
+
+- **Runner**: Playwright Test
+- **Test directory**: `frontend/ai.client/e2e/`
+- **Base URL**: `http://localhost:4200`
+- **Auth setup**: Cognito login via setup projects that save `storageState` to `e2e/.auth/`
+
+## File Naming & Project Matching
+
+The Playwright config routes tests to projects by filename pattern. Use the correct suffix:
+
+| Suffix | Project | Auth | Example |
+|---|---|---|---|
+| `.spec.ts` | `chromium` (unauthenticated) | None | `login.spec.ts`, `not-found.spec.ts` |
+| `.user.spec.ts` | `user` (regular user) | `e2e/.auth/user.json` | `chat.user.spec.ts` |
+| `.auth.spec.ts` | `admin` (admin user) | `e2e/.auth/admin.json` | (future admin tests) |
+| `.setup.ts` | Setup only | N/A | `auth-user.setup.ts` |
+
+Never mix authenticated and unauthenticated tests in the same file. The project matcher determines which storage state is injected.
+
+## Directory Organization
+
+Group tests by feature area in subdirectories:
+
+```
+e2e/
+├── auth/               # Login, logout, redirects, guards
+├── home-page/          # Chat, model selector, settings panel, file upload
+├── assistants/         # Assistant CRUD lifecycle
+├── settings/           # Profile, preferences
+└── manage-sessions.user.spec.ts   # Top-level if the feature is a single page
+```
+
+Place a test file in the subdirectory of the feature it exercises. Only use the top-level `e2e/` directory for single-page features that don't warrant a folder.
+
+## Timeouts
+
+The app talks to real AWS backends (DynamoDB, Bedrock, Cognito). Network latency and cold starts mean UI elements don't appear instantly. Use generous, tiered timeouts:
+
+| What you're waiting for | Timeout |
+|---|---|
+| Page heading / primary element after `goto` | `15_000` |
+| Model selector to finish loading (replaces "System Default") | `30_000` |
+| Assistant message to appear (LLM first token) | `60_000` |
+| Pulsating loader to disappear (LLM stream complete) | `200_000` |
+| Loading spinners / "Loading..." text to disappear | `15_000` |
+| UI reaction to a click (dialog open, menu visible) | `5_000` |
+| Navigation via `waitForURL` | `10_000` |
+| Cognito redirect after login submit | `30_000` |
+
+Always pass an explicit `{ timeout: N }` to `toBeVisible`, `toBeHidden`, `toHaveCount`, `waitForURL`, and similar assertions. Never rely on Playwright's global default — it's too short for this stack.
+
+## Waiting for Page Ready State
+
+After every `page.goto(...)`, wait for a landmark element that proves the page has loaded and hydrated before interacting with anything else. The standard landmarks are:
+
+```typescript
+// Home / chat page
+await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+// Manage sessions
+await expect(
+  page.getByRole('heading', { name: 'Manage Conversations' }),
+).toBeVisible({ timeout: 15_000 });
+
+// Assistants list
+await expect(
+  page.getByRole('heading', { name: 'Assistants' }),
+).toBeVisible({ timeout: 15_000 });
+
+// Settings / profile
+await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible({ timeout: 15_000 });
+```
+
+If the page has a loading state (e.g., "Loading conversations...", "Loading tools...", "Loading files..."), also wait for it to disappear before asserting on data:
+
+```typescript
+await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 15_000 });
+```
+
+## Locator Strategy — Avoiding Double Matches
+
+Angular renders components like `app-session-list`, `app-user-message`, `app-assistant-message`, etc. Some pages render the same component type multiple times (e.g., a preview panel and the main area both contain `textarea#user-message`). To avoid ambiguous matches:
+
+1. **Scope locators to a parent component** when the same element appears in multiple places:
+   ```typescript
+   // Good — scoped to the preview panel
+   const preview = page.locator('app-assistant-preview');
+   const previewTextarea = preview.locator('textarea#user-message');
+
+   // Bad — matches both the main chat and the preview
+   const textarea = page.locator('textarea#user-message');
+   ```
+
+2. **Use `.filter({ hasText: ... })` to narrow down lists** of similar elements:
+   ```typescript
+   const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+   const sessionLink = page.locator('app-session-list a').filter({ hasText: 'test conversation' });
+   ```
+
+3. **Prefer role-based locators** (`getByRole`, `getByLabel`) over CSS selectors when possible. They're more resilient to markup changes and self-documenting:
+   ```typescript
+   page.getByRole('button', { name: 'Submit message' })
+   page.getByRole('heading', { name: 'Manage Conversations' })
+   page.getByRole('menuitem', { name: 'Delete' })
+   page.getByRole('dialog', { name: 'Share Assistant' })
+   page.getByRole('alertdialog').getByRole('button', { name: 'Delete' })
+   ```
+
+4. **Use `.first()` / `.nth(N)` deliberately**, not as a band-aid. If you need `.first()`, add a comment explaining why multiple matches are expected:
+   ```typescript
+   // Multiple session links exist; we want the most recent (first in the list)
+   const sessionLink = page.locator('app-session-list a').first();
+   ```
+
+## Serial vs. Independent Tests
+
+Use `test.describe.serial` when tests form a lifecycle that must run in order and share state (create → interact → delete). Use independent tests (the default) for everything else.
+
+### Serial test rules
+
+- Wrap the serial block in `test.describe.serial('Descriptive lifecycle name', () => { ... })`.
+- For serial tests that must share a single browser context across all steps, use `beforeAll` / `afterAll` with a shared `page`:
+  ```typescript
+  test.describe.serial('Full assistant lifecycle', () => {
+    let page: Page;
+    test.beforeAll(async ({ browser }) => { page = await browser.newPage(); });
+    test.afterAll(async () => { await page.close(); });
+    // tests use `page` directly, not `{ page }` from the test args
+  });
+  ```
+- For serial tests where each step can use a fresh context but must run in order (e.g., chat lifecycle where state is in the backend), use the normal `({ page })` fixture — Playwright handles context creation. Each test navigates to the page and picks up server-side state from the previous test.
+- Always include a cleanup step as the final test in a serial block (delete the conversation, delete the assistant, etc.).
+- Keep serial blocks focused. If some tests in a feature are independent, put them outside the serial block in the same `describe`:
+  ```typescript
+  test.describe('Chat (user)', () => {
+    test.describe.serial('Chat lifecycle with Claude Haiku 4.5', () => {
+      // create → interact → rename → delete
+    });
+
+    // Independent tests below — each gets its own context
+    test('should close and reopen the sidebar', async ({ page }) => { ... });
+  });
+  ```
+
+### Independent test rules
+
+- Each test should be self-contained: navigate to the page, do the thing, assert.
+- Don't assume any state from other tests.
+- Use `test.skip(condition, reason)` to gracefully skip when preconditions aren't met (e.g., no sessions exist to select).
+
+## Sending Chat Messages and Waiting for Responses
+
+This is the most latency-sensitive flow. Follow this exact pattern:
+
+```typescript
+async function sendMessageAndWaitForResponse(
+  page: Page,
+  message: string,
+): Promise<string> {
+  const textarea = page.locator('textarea#user-message');
+  await expect(textarea).toBeVisible({ timeout: 15_000 });
+  await textarea.fill(message);
+
+  await page.getByRole('button', { name: 'Submit message' }).click();
+
+  // Wait for the assistant response to start streaming
+  const assistantMessage = page.locator('app-assistant-message').last();
+  await expect(assistantMessage).toBeVisible({ timeout: 60_000 });
+
+  // Wait for streaming to finish (loader disappears)
+  await expect(page.locator('app-pulsating-loader')).toBeHidden({ timeout: 200_000 });
+
+  return (await assistantMessage.innerText()).trim();
+}
+```
+
+Key points:
+- Use `.last()` on `app-assistant-message` because previous messages already exist in multi-turn conversations.
+- Wait for `app-pulsating-loader` to be hidden — this is the streaming indicator. The 200s timeout accounts for slow Bedrock responses.
+- If the chat is inside a scoped container (e.g., assistant preview), scope all locators to that container.
+
+## Route Mocking
+
+Use `page.route()` to mock API responses when testing UI behavior that shouldn't depend on real backends (file uploads, error states, provider lists):
+
+```typescript
+// Mock a GET endpoint
+await page.route('**/sessions*', (route) => {
+  if (route.request().method() === 'GET') {
+    return route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ detail: 'Database unavailable' }),
+    });
+  }
+  return route.continue();
+});
+
+// Mock with a delay to test loading states
+await page.route('**/auth/providers', async (route) => {
+  await new Promise((r) => setTimeout(r, 2000));
+  await route.fulfill({ json: { providers: [] } });
+});
+```
+
+Rules:
+- Always call `route.continue()` for methods you don't want to intercept.
+- Call `page.unrouteAll()` at the end of tests that set up complex multi-route mocks to avoid leaking into other tests.
+- For unauthenticated tests that hit pages behind auth guards, mock `**/system/status` to return `{ first_boot_completed: true }` so the guard redirects to login instead of a first-boot flow.
+
+## Conditional Skipping
+
+When a test depends on data that may not exist (e.g., sessions, models), use `test.skip()` rather than letting it fail:
+
+```typescript
+const checkbox = page.locator('input[type="checkbox"]').first();
+const hasCheckbox = (await checkbox.count()) > 0;
+test.skip(!hasCheckbox, 'No sessions available to select');
+```
+
+## Helper Functions
+
+Extract repeated navigation and interaction patterns into helper functions at the top of the file. Common patterns:
+
+```typescript
+/** Navigate to a page and wait for its landmark element. */
+async function goToAssistantsPage(page: Page) {
+  await page.goto('/assistants');
+  await expect(
+    page.getByRole('heading', { name: 'Assistants' }),
+  ).toBeVisible({ timeout: 15_000 });
+}
+
+/** Select a model from the dropdown. */
+async function selectModel(page: Page, modelNameSubstring: string) {
+  const trigger = page.getByRole('button', { name: 'Select model' });
+  await expect(trigger).toBeVisible({ timeout: 10_000 });
+  await expect(trigger).not.toContainText('System Default', { timeout: 30_000 });
+  await trigger.click();
+  const menuItem = page.getByRole('menuitem').filter({
+    hasText: new RegExp(modelNameSubstring, 'i'),
+  });
+  await expect(menuItem.first()).toBeVisible({ timeout: 5_000 });
+  await menuItem.first().click();
+}
+```
+
+Keep helpers in the same file unless they're shared across multiple spec files. If sharing is needed, create a `e2e/helpers/` directory.
+
+## General Patterns
+
+- **Import only from `@playwright/test`**: `import { test, expect } from '@playwright/test';` — optionally import `Page` type when using shared `page` in serial blocks.
+- **Use `test.describe` for grouping**: One top-level `describe` per file, named after the feature and auth level (e.g., `'Chat (user)'`, `'Login Page'`).
+- **Use `test.beforeEach` sparingly**: Only for setup that every test in the block needs (e.g., navigating to a page, setting up route mocks). Don't use it if only some tests need the setup.
+- **Prefer `page.goto` in each test** over `beforeEach` navigation when tests go to different pages or need different setup.
+- **Use `scrollIntoViewIfNeeded()`** before interacting with elements that may be below the fold.
+- **Use `hover()` before `click()`** on elements that only appear on hover (e.g., context menu triggers on session list items).
+- **Confirm destructive actions**: When testing delete flows, always interact with the confirmation dialog (`alertdialog` role) before asserting the item is gone.
+- **Use numeric separators in timeouts**: Write `15_000` not `15000` for readability.
diff --git a/README.md b/README.md
index 2432411f..b14277ec 100644
--- a/README.md
+++ b/README.md
@@ -106,6 +106,10 @@ Enable programmatic access to the platform's AI models via REST API. Users gener
 
 **Built-in code examples:** The API Keys settings page includes a code generator with cURL, Python, and JavaScript examples, a model selector, and configurable parameters (temperature, max tokens, system prompt) so users can start integrating immediately.
 
+### 🎙️ Voice Mode
+
+Have natural, real-time spoken conversations with the assistant. Voice Mode streams audio bidirectionally over WebSockets to an AgentCore-hosted voice agent, using **Amazon Nova Sonic** for low-latency speech-to-speech interaction. Users can speak their questions and hear responses aloud — no typing required — while the same RBAC, quotas, and model access rules as the chat interface apply.
+
 ### 🧠 Memory and Context
 
 A two-tier memory system combines **short-term session history** with **long-term user preferences**. The agent remembers coding style preferences, language choices, and learned facts across sessions — personalization without compromising privacy.
diff --git a/backend/Dockerfile.inference-api b/backend/Dockerfile.inference-api
index 61631ed4..97a34fb9 100644
--- a/backend/Dockerfile.inference-api
+++ b/backend/Dockerfile.inference-api
@@ -25,12 +25,12 @@ COPY backend/uv.lock ./
 # --no-dev: exclude development dependencies
 # --no-editable: non-editable install for production
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --frozen --extra agentcore --no-install-project --no-dev --no-editable
+    uv sync --frozen --extra agentcore --extra bidi --no-install-project --no-dev --no-editable
 
 # Copy source code and install the project itself
 COPY backend/src ./src
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --frozen --extra agentcore --no-dev --no-editable
+    uv sync --frozen --extra agentcore --extra bidi --no-dev --no-editable
 
 # Production stage
 FROM --platform=linux/arm64 python:3.13-slim@sha256:739e7213785e88c0f702dcdc12c0973afcbd606dbf021a589cab77d6b00b579d
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index a663670c..b383cb19 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -48,6 +48,11 @@ agentcore = [
     "google-genai==1.70.0",  # For Google Gemini models
 ]
 
+# Voice/BidiAgent dependencies (Nova Sonic speech-to-speech)
+bidi = [
+    "strands-agents[bidi]==1.34.1",
+]
+
 # Document ingestion pipeline dependencies (for Lambda deployment)
 # NOTE: For document ingestion dependencies, see:
 #   backend/src/apis/app_api/documents/ingestion/requirements.txt
@@ -71,7 +76,7 @@ dev = [
 
 # All dependencies (convenience)
 all = [
-    "agentcore-stack[agentcore,dev]",
+    "agentcore-stack[agentcore,bidi,dev]",
 ]
 
 [tool.setuptools]
diff --git a/backend/scripts/seed_bootstrap_data.py b/backend/scripts/seed_bootstrap_data.py
index 78875523..85b609bd 100644
--- a/backend/scripts/seed_bootstrap_data.py
+++ b/backend/scripts/seed_bootstrap_data.py
@@ -211,6 +211,23 @@ def seed_default_quota_assignment(
         "supportsCaching": True,
         "isDefault": False,
     },
+    {
+        "modelId": "amazon.nova-2-sonic-v1:0",
+        "modelName": "Nova 2 Sonic",
+        "provider": "bedrock",
+        "providerName": "Amazon",
+        "inputModalities": ["TEXT", "SPEECH"],
+        "outputModalities": ["TEXT", "SPEECH"],
+        "maxInputTokens": 200000,
+        "maxOutputTokens": 4096,
+        "inputPricePerMillionTokens": Decimal("3.00"),
+        "outputPricePerMillionTokens": Decimal("12.00"),
+        "cacheWritePricePerMillionTokens": Decimal("0"),
+        "cacheReadPricePerMillionTokens": Decimal("0"),
+        "isReasoningModel": False,
+        "supportsCaching": False,
+        "isDefault": False,
+    },
 ]
 
 
diff --git a/backend/scripts/test_voice_client.py b/backend/scripts/test_voice_client.py
new file mode 100644
index 00000000..bd0371bb
--- /dev/null
+++ b/backend/scripts/test_voice_client.py
@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""
+Minimal WebSocket test client for the voice endpoint.
+
+Usage:
+    # With a real JWT token (from Cognito):
+    python scripts/test_voice_client.py --token "eyJhbGc..."
+
+    # With a fake token for local testing (requires no auth verification):
+    python scripts/test_voice_client.py --fake-token
+
+    # Send a text message instead of audio (simpler test):
+    python scripts/test_voice_client.py --fake-token --text "Hello, what can you help me with?"
+
+Prerequisites:
+    pip install websockets
+    # Server must be running: cd src/apis/inference_api && uv run python main.py
+"""
+
+import argparse
+import asyncio
+import json
+import sys
+
+try:
+    import websockets
+except ImportError:
+    print("Install websockets: pip install websockets")
+    sys.exit(1)
+
+try:
+    import jwt as pyjwt
+except ImportError:
+    pyjwt = None
+
+
+def make_fake_token() -> str:
+    """Create a fake JWT token for local testing."""
+    if pyjwt is None:
+        print("pyjwt not available for fake token generation, using placeholder")
+        return "fake.token.placeholder"
+    return pyjwt.encode(
+        {"sub": "test-user-001", "email": "test@example.com", "name": "Test User"},
+        "test-secret",
+        algorithm="HS256",
+    )
+
+
+async def run_client(url: str, token: str, text_message: str = None):
+    """Connect to voice WebSocket and exchange messages."""
+    print(f"Connecting to {url}")
+
+    async with websockets.connect(url) as ws:
+        print("Connected!")
+
+        # Send config message
+        config = {
+            "type": "config",
+            "session_id": "voice-test-001",
+            "auth_token": token,
+        }
+        await ws.send(json.dumps(config))
+        print(f"Sent config: {json.dumps(config, indent=2)}")
+
+        # Read connection confirmation
+        response = await asyncio.wait_for(ws.recv(), timeout=15.0)
+        print(f"Received: {response}")
+
+        if text_message:
+            # Send a text message (simpler than audio for testing)
+            msg = {"type": "bidi_text_input", "text": text_message}
+            await ws.send(json.dumps(msg))
+            print(f"Sent text: {text_message}")
+
+            # Read responses for a few seconds
+            print("\nListening for responses (10s timeout)...")
+            try:
+                while True:
+                    response = await asyncio.wait_for(ws.recv(), timeout=10.0)
+                    try:
+                        parsed = json.loads(response)
+                        print(f"  Event: {json.dumps(parsed, indent=2)[:200]}")
+                    except json.JSONDecodeError:
+                        print(f"  Raw: {response[:200]}")
+            except asyncio.TimeoutError:
+                print("No more responses (timeout)")
+        else:
+            # Just test ping/pong
+            await ws.send(json.dumps({"type": "ping"}))
+            response = await asyncio.wait_for(ws.recv(), timeout=5.0)
+            print(f"Ping response: {response}")
+
+        # Send stop
+        await ws.send(json.dumps({"type": "stop"}))
+        print("Sent stop signal")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Test voice WebSocket endpoint")
+    parser.add_argument("--url", default="ws://localhost:8001/voice/stream", help="WebSocket URL")
+    parser.add_argument("--token", help="JWT bearer token")
+    parser.add_argument("--fake-token", action="store_true", help="Generate a fake JWT for local testing")
+    parser.add_argument("--text", help="Send a text message instead of audio")
+    args = parser.parse_args()
+
+    token = args.token
+    if args.fake_token:
+        token = make_fake_token()
+    if not token:
+        print("Error: Provide --token or --fake-token")
+        sys.exit(1)
+
+    url = f"{args.url}?session_id=voice-test-001&token={token}"
+
+    try:
+        asyncio.run(run_client(url, token, args.text))
+    except ConnectionRefusedError:
+        print(f"Connection refused. Is the server running at {args.url}?")
+        sys.exit(1)
+    except KeyboardInterrupt:
+        print("\nInterrupted")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/backend/src/agents/main_agent/__init__.py b/backend/src/agents/main_agent/__init__.py
index a8377ec8..a1fbcb28 100644
--- a/backend/src/agents/main_agent/__init__.py
+++ b/backend/src/agents/main_agent/__init__.py
@@ -28,6 +28,16 @@
         print(event)
 """
 from .main_agent import MainAgent
+from .base_agent import BaseAgent
+from .chat_agent import ChatAgent
+from .skill_agent import SkillAgent
+from .agent_types import create_agent, register_agent_type, get_available_types
+
+# VoiceAgent is optional (requires strands-agents[bidi])
+try:
+    from .voice_agent import VoiceAgent
+except ImportError:
+    VoiceAgent = None
 from .core import ModelConfig, SystemPromptBuilder
 from .session import SessionFactory
 from .tools import ToolRegistry, ToolFilter, GatewayIntegration, create_default_registry
@@ -50,8 +60,14 @@
 __version__ = "1.0.0"
 
 __all__ = [
-    # Main agent
+    # Agent types
+    "BaseAgent",
+    "ChatAgent",
     "MainAgent",
+    "SkillAgent",
+    "create_agent",
+    "register_agent_type",
+    "get_available_types",
 
     # Core components
     "ModelConfig",
diff --git a/backend/src/agents/main_agent/agent_types.py b/backend/src/agents/main_agent/agent_types.py
new file mode 100644
index 00000000..92bf033c
--- /dev/null
+++ b/backend/src/agents/main_agent/agent_types.py
@@ -0,0 +1,69 @@
+"""
+Agent type registry and factory function.
+
+Provides a single entry point for creating agents by type string.
+New agent types register here as they're implemented.
+"""
+
+import logging
+from typing import Optional, List
+
+from agents.main_agent.base_agent import BaseAgent
+
+logger = logging.getLogger(__name__)
+
+
+# Registry of agent type string → class
+# New agent types add themselves here as they're implemented
+_AGENT_TYPES = {}
+
+
+def register_agent_type(type_name: str, agent_class: type) -> None:
+    """Register an agent class for a given type string."""
+    _AGENT_TYPES[type_name] = agent_class
+
+
+def get_available_types() -> List[str]:
+    """Return list of registered agent type names."""
+    return list(_AGENT_TYPES.keys())
+
+
+def create_agent(agent_type: str = "chat", **kwargs) -> BaseAgent:
+    """
+    Create an agent by type string.
+
+    Args:
+        agent_type: Agent type ("chat", "skill", "voice"). Default: "chat".
+        **kwargs: Passed directly to the agent constructor (session_id, user_id, etc.)
+
+    Returns:
+        BaseAgent subclass instance
+
+    Raises:
+        ValueError: If agent_type is not registered
+    """
+    agent_class = _AGENT_TYPES.get(agent_type)
+    if agent_class is None:
+        available = ", ".join(sorted(_AGENT_TYPES.keys()))
+        raise ValueError(f"Unknown agent_type '{agent_type}'. Available: {available}")
+
+    logger.info(f"Creating {agent_type} agent ({agent_class.__name__})")
+    return agent_class(**kwargs)
+
+
+# Register built-in agent types
+def _register_defaults():
+    from agents.main_agent.chat_agent import ChatAgent
+    from agents.main_agent.skill_agent import SkillAgent
+    register_agent_type("chat", ChatAgent)
+    register_agent_type("skill", SkillAgent)
+
+    # Voice agent is optional (requires strands-agents[bidi])
+    try:
+        from agents.main_agent.voice_agent import VoiceAgent
+        register_agent_type("voice", VoiceAgent)
+    except Exception:
+        pass
+
+
+_register_defaults()
diff --git a/backend/src/agents/main_agent/base_agent.py b/backend/src/agents/main_agent/base_agent.py
new file mode 100644
index 00000000..538bb423
--- /dev/null
+++ b/backend/src/agents/main_agent/base_agent.py
@@ -0,0 +1,269 @@
+"""
+Base Agent - Abstract base class for all agent types
+
+Provides shared initialization for model config, system prompt, tool registry,
+session management, and streaming. Subclasses implement _create_agent() and
+stream_async() for their specific agent type.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, List, Optional
+
+from agents.main_agent.core import ModelConfig, SystemPromptBuilder, AgentFactory
+from agents.main_agent.session import SessionFactory
+from agents.main_agent.session.hooks import (
+    StopHook,
+    EmailApprovalHook,
+    ExternalWriteApprovalHook,
+    DangerousToolApprovalHook,
+)
+from agents.main_agent.tools import (
+    create_default_registry,
+    ToolFilter,
+    GatewayIntegration,
+)
+from agents.main_agent.multimodal import PromptBuilder
+from agents.main_agent.streaming import StreamCoordinator
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for all agent types.
+
+    Handles shared concerns:
+    - Model configuration (multi-provider: Bedrock, OpenAI, Gemini)
+    - System prompt building
+    - Tool registry and filtering
+    - Gateway and external MCP integration
+    - Session management (cloud or preview)
+    - Streaming coordination
+
+    Subclasses implement:
+    - _create_agent(): Build the specific Strands agent type
+    - stream_async(): Stream responses for their protocol (text, voice, etc.)
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        user_id: Optional[str] = None,
+        auth_token: Optional[str] = None,
+        enabled_tools: Optional[List[str]] = None,
+        model_id: Optional[str] = None,
+        temperature: Optional[float] = None,
+        system_prompt: Optional[str] = None,
+        caching_enabled: Optional[bool] = None,
+        provider: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+        skip_persistence: bool = False,
+    ):
+        """
+        Initialize base agent with shared infrastructure.
+
+        Args:
+            session_id: Session identifier for message persistence
+            user_id: User identifier for cross-session preferences (defaults to session_id)
+            auth_token: Raw OIDC token for forwarding to external MCP tools (optional)
+            enabled_tools: List of tool IDs to enable. If None, all tools are enabled.
+            model_id: Model ID to use (format depends on provider)
+            temperature: Model temperature (0.0 - 1.0)
+            system_prompt: System prompt text
+            caching_enabled: Whether to enable prompt caching (Bedrock only)
+            provider: LLM provider ("bedrock", "openai", or "gemini")
+            max_tokens: Maximum tokens to generate (optional)
+            skip_persistence: If True, don't persist messages (for preview sessions)
+        """
+        # Basic state
+        self.session_id = session_id
+        self.user_id = user_id or session_id
+        self.auth_token = auth_token
+        self.enabled_tools = enabled_tools
+        self.agent = None
+
+        # Initialize model configuration
+        self.model_config = ModelConfig.from_params(
+            model_id=model_id, temperature=temperature, caching_enabled=caching_enabled, provider=provider, max_tokens=max_tokens
+        )
+
+        # Load retry configuration from environment variables
+        from agents.main_agent.core.model_config import RetryConfig
+        self.model_config.retry_config = RetryConfig.from_env()
+
+        # Initialize system prompt builder
+        if system_prompt:
+            self.prompt_builder = SystemPromptBuilder.from_user_prompt(system_prompt)
+            self.system_prompt = self.prompt_builder.build(include_date=False)
+        else:
+            self.prompt_builder = SystemPromptBuilder()
+            self.system_prompt = self.prompt_builder.build(include_date=True)
+
+        # Initialize tool registry and filter
+        self.tool_registry = create_default_registry()
+        self.tool_filter = ToolFilter(self.tool_registry)
+
+        # Register external MCP tool IDs from enabled tools
+        self._register_external_mcp_tools()
+
+        # Initialize gateway integration
+        self.gateway_integration = GatewayIntegration()
+
+        # Initialize multimodal prompt builder
+        self.multimodal_builder = PromptBuilder()
+
+        # Initialize session manager
+        self.session_manager = SessionFactory.create_session_manager(
+            session_id=session_id, user_id=self.user_id, caching_enabled=self.model_config.caching_enabled
+        )
+
+        # Initialize streaming coordinator
+        self.stream_coordinator = StreamCoordinator()
+
+        # Create the agent (subclass-specific)
+        self._create_agent()
+
+    @abstractmethod
+    def _create_agent(self) -> None:
+        """Create the specific agent type. Subclasses must implement."""
+        ...
+
+    @abstractmethod
+    async def stream_async(
+        self, message: str, session_id: Optional[str] = None, files: Optional[List] = None, citations: Optional[List] = None, original_message: Optional[str] = None
+    ) -> AsyncGenerator[str, None]:
+        """Stream agent responses. Subclasses must implement."""
+        ...
+
+    def _register_external_mcp_tools(self) -> None:
+        """
+        Register external MCP tool IDs with the tool filter.
+
+        Queries the tool catalog for tools with protocol='mcp_external'
+        and registers them so they're recognized during filtering.
+        """
+        if not self.enabled_tools:
+            return
+
+        try:
+            import asyncio
+
+            from apis.app_api.tools.repository import get_tool_catalog_repository
+
+            repository = get_tool_catalog_repository()
+            external_tool_ids = []
+
+            async def check_tools():
+                for tool_id in self.enabled_tools:
+                    tool = await repository.get_tool(tool_id)
+                    if tool and tool.protocol == "mcp_external":
+                        external_tool_ids.append(tool_id)
+                return external_tool_ids
+
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    import concurrent.futures
+
+                    with concurrent.futures.ThreadPoolExecutor() as executor:
+                        future = executor.submit(asyncio.run, check_tools())
+                        tool_ids = future.result()
+                else:
+                    tool_ids = loop.run_until_complete(check_tools())
+            except RuntimeError:
+                tool_ids = asyncio.run(check_tools())
+
+            if tool_ids:
+                self.tool_filter.set_external_mcp_tools(tool_ids)
+                logger.info(f"Registered {len(tool_ids)} external MCP tools: {tool_ids}")
+
+        except Exception as e:
+            logger.warning(f"Could not register external MCP tools: {e}")
+
+    def _create_hooks(self) -> List:
+        """
+        Create agent hooks.
+
+        Includes:
+        - StopHook: Always enabled, cancels tool execution on user stop
+        - Approval hooks: Gate dangerous operations for user confirmation
+
+        Returns:
+            list: List of initialized hooks
+        """
+        hooks = []
+
+        # Always-on: session cancellation
+        hooks.append(StopHook(self.session_manager))
+
+        # Approval gates for dangerous operations
+        hooks.append(EmailApprovalHook())
+        hooks.append(ExternalWriteApprovalHook())
+        hooks.append(DangerousToolApprovalHook())
+
+        return hooks
+
+    def _build_filtered_tools(self) -> List:
+        """
+        Filter tools and load gateway/external MCP clients.
+
+        Returns:
+            list: Combined list of local tools + MCP clients
+        """
+        filter_result = self.tool_filter.filter_tools_extended(self.enabled_tools)
+        local_tools = filter_result.local_tools
+        gateway_tool_ids = filter_result.gateway_tool_ids
+        external_mcp_tool_ids = filter_result.external_mcp_tool_ids
+
+        # Get gateway client and add to tools if available
+        if gateway_tool_ids:
+            gateway_client = self.gateway_integration.get_client(gateway_tool_ids)
+            if gateway_client:
+                local_tools = self.gateway_integration.add_to_tool_list(local_tools)
+
+        # Load external MCP tools
+        if external_mcp_tool_ids:
+            import asyncio
+
+            from agents.main_agent.integrations.external_mcp_client import get_external_mcp_integration
+
+            external_integration = get_external_mcp_integration()
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                import concurrent.futures
+
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(
+                        asyncio.run,
+                        external_integration.load_external_tools(
+                            external_mcp_tool_ids,
+                            user_id=self.user_id,
+                            auth_token=self.auth_token,
+                        ),
+                    )
+                    external_clients = future.result()
+            else:
+                external_clients = loop.run_until_complete(
+                    external_integration.load_external_tools(
+                        external_mcp_tool_ids,
+                        user_id=self.user_id,
+                        auth_token=self.auth_token,
+                    )
+                )
+
+            for client in external_clients:
+                if client not in local_tools:
+                    local_tools.append(client)
+
+            logger.info(f"Added {len(external_clients)} external MCP clients to tools")
+
+        return local_tools
+
+    def get_model_config(self) -> dict:
+        """Get current model configuration."""
+        return {**self.model_config.to_dict(), "system_prompts": [self.system_prompt]}
+
+    def get_tool_statistics(self) -> dict:
+        """Get tool filtering statistics."""
+        return self.tool_filter.get_statistics(self.enabled_tools)
diff --git a/backend/src/agents/main_agent/chat_agent.py b/backend/src/agents/main_agent/chat_agent.py
new file mode 100644
index 00000000..97fbb702
--- /dev/null
+++ b/backend/src/agents/main_agent/chat_agent.py
@@ -0,0 +1,76 @@
+"""
+Chat Agent - Text-based conversational agent
+
+Extends BaseAgent with Strands Agent creation and text streaming.
+This is the default agent type for standard chat interactions.
+"""
+
+import logging
+from typing import AsyncGenerator, List, Optional
+
+from agents.main_agent.base_agent import BaseAgent
+from agents.main_agent.core import AgentFactory
+
+logger = logging.getLogger(__name__)
+
+
+class ChatAgent(BaseAgent):
+    """
+    Text-based chat agent using Strands Agent.
+
+    Handles:
+    - Strands Agent creation with filtered tools and hooks
+    - Text message streaming via StreamCoordinator
+    - Multimodal prompt building (text + files)
+    """
+
+    def _create_agent(self) -> None:
+        """Create Strands Agent with filtered tools and session management."""
+        try:
+            tools = self._build_filtered_tools()
+            hooks = self._create_hooks()
+
+            self.agent = AgentFactory.create_agent(
+                model_config=self.model_config,
+                system_prompt=self.system_prompt,
+                tools=tools,
+                session_manager=self.session_manager,
+                hooks=hooks,
+            )
+
+        except Exception as e:
+            logger.error(f"Error creating agent: {e}")
+            raise
+
+    async def stream_async(
+        self, message: str, session_id: Optional[str] = None, files: Optional[List] = None, citations: Optional[List] = None, original_message: Optional[str] = None
+    ) -> AsyncGenerator[str, None]:
+        """
+        Stream agent responses.
+
+        Args:
+            message: User message text
+            session_id: Session identifier (defaults to instance session_id)
+            files: Optional list of FileContent objects (with base64 bytes)
+            citations: Optional list of citation dicts from RAG retrieval
+            original_message: Original user message before RAG augmentation
+
+        Yields:
+            str: SSE formatted events
+        """
+        if not self.agent:
+            self._create_agent()
+
+        prompt = self.multimodal_builder.build_prompt(message, files)
+
+        async for event in self.stream_coordinator.stream_response(
+            agent=self.agent,
+            prompt=prompt,
+            session_manager=self.session_manager,
+            session_id=session_id or self.session_id,
+            user_id=self.user_id,
+            main_agent_wrapper=self,
+            citations=citations,
+            original_message=original_message,
+        ):
+            yield event
diff --git a/backend/src/agents/main_agent/config/__init__.py b/backend/src/agents/main_agent/config/__init__.py
new file mode 100644
index 00000000..989caa54
--- /dev/null
+++ b/backend/src/agents/main_agent/config/__init__.py
@@ -0,0 +1,9 @@
+"""
+Centralized configuration constants for the main_agent package.
+
+All environment variable names, default values, and shared string constants
+are defined here. Modules should import from this package instead of using
+inline os.getenv() calls with hardcoded strings.
+"""
+
+from agents.main_agent.config.constants import EnvVars, Defaults, Prefixes
diff --git a/backend/src/agents/main_agent/config/constants.py b/backend/src/agents/main_agent/config/constants.py
new file mode 100644
index 00000000..b3f0c605
--- /dev/null
+++ b/backend/src/agents/main_agent/config/constants.py
@@ -0,0 +1,121 @@
+"""
+Centralized constants for the main_agent package.
+
+All environment variable names, default values, and shared string constants
+live here. This eliminates magic strings scattered across modules and provides
+a single reference for configuration.
+
+Usage:
+    from agents.main_agent.config.constants import EnvVars, Defaults, Prefixes
+"""
+
+
+class EnvVars:
+    """Environment variable names used across the main_agent package.
+
+    Organized by subsystem. All values are strings (the env var name, not the value).
+    """
+
+    # --- AgentCore Memory ---
+    MEMORY_ID = "AGENTCORE_MEMORY_ID"
+    AWS_REGION = "AWS_REGION"
+    MEMORY_RELEVANCE_SCORE = "AGENTCORE_MEMORY_RELEVANCE_SCORE"
+    MEMORY_TOP_K = "AGENTCORE_MEMORY_TOP_K"
+
+    # --- Compaction ---
+    COMPACTION_ENABLED = "AGENTCORE_MEMORY_COMPACTION_ENABLED"
+    COMPACTION_TOKEN_THRESHOLD = "AGENTCORE_MEMORY_COMPACTION_TOKEN_THRESHOLD"
+    COMPACTION_PROTECTED_TURNS = "AGENTCORE_MEMORY_COMPACTION_PROTECTED_TURNS"
+    COMPACTION_MAX_TOOL_CONTENT_LENGTH = "AGENTCORE_MEMORY_COMPACTION_MAX_TOOL_CONTENT_LENGTH"
+
+    # --- DynamoDB Tables ---
+    DYNAMODB_SESSIONS_METADATA_TABLE = "DYNAMODB_SESSIONS_METADATA_TABLE_NAME"
+    DYNAMODB_QUOTA_TABLE = "DYNAMODB_QUOTA_TABLE"
+    DYNAMODB_QUOTA_EVENTS_TABLE = "DYNAMODB_QUOTA_EVENTS_TABLE"
+
+    # --- Retry Configuration ---
+    RETRY_BOTO_MAX_ATTEMPTS = "RETRY_BOTO_MAX_ATTEMPTS"
+    RETRY_BOTO_MODE = "RETRY_BOTO_MODE"
+    RETRY_CONNECT_TIMEOUT = "RETRY_CONNECT_TIMEOUT"
+    RETRY_READ_TIMEOUT = "RETRY_READ_TIMEOUT"
+    RETRY_SDK_MAX_ATTEMPTS = "RETRY_SDK_MAX_ATTEMPTS"
+    RETRY_SDK_INITIAL_DELAY = "RETRY_SDK_INITIAL_DELAY"
+    RETRY_SDK_MAX_DELAY = "RETRY_SDK_MAX_DELAY"
+
+    # --- API Keys ---
+    OPENAI_API_KEY = "OPENAI_API_KEY"
+    GOOGLE_GEMINI_API_KEY = "GOOGLE_GEMINI_API_KEY"
+
+    # --- Gateway ---
+    GATEWAY_MCP_ENABLED = "AGENTCORE_GATEWAY_MCP_ENABLED"
+
+    # --- Frontend ---
+    FRONTEND_URL = "FRONTEND_URL"
+
+    # --- Runtime Context (written by StreamCoordinator) ---
+    SESSION_ID = "SESSION_ID"
+    USER_ID = "USER_ID"
+
+    # --- Voice Agent ---
+    NOVA_SONIC_MODEL_ID = "NOVA_SONIC_MODEL_ID"
+    NOVA_SONIC_VOICE = "NOVA_SONIC_VOICE"
+    NOVA_SONIC_MAX_MESSAGES = "NOVA_SONIC_MAX_MESSAGES"
+
+
+class Defaults:
+    """Default values for configuration parameters.
+
+    Organized to match the EnvVars they pair with.
+    """
+
+    # --- Model ---
+    MODEL_ID = "us.anthropic.claude-haiku-4-5-20251001-v1:0"
+    TEMPERATURE = 0.7
+    CACHING_ENABLED = True
+
+    # --- AWS ---
+    AWS_REGION = "us-west-2"
+
+    # --- Memory Retrieval ---
+    MEMORY_RELEVANCE_SCORE = 0.7
+    MEMORY_TOP_K = 10
+
+    # --- Compaction ---
+    COMPACTION_ENABLED = True
+    COMPACTION_TOKEN_THRESHOLD = 100_000
+    COMPACTION_PROTECTED_TURNS = 3
+    COMPACTION_MAX_TOOL_CONTENT_LENGTH = 500
+
+    # --- DynamoDB Tables ---
+    DYNAMODB_QUOTA_TABLE = "UserQuotas"
+    DYNAMODB_QUOTA_EVENTS_TABLE = "QuotaEvents"
+
+    # --- Retry ---
+    RETRY_BOTO_MAX_ATTEMPTS = 3
+    RETRY_BOTO_MODE = "standard"
+    RETRY_CONNECT_TIMEOUT = 5
+    RETRY_READ_TIMEOUT = 120
+    RETRY_SDK_MAX_ATTEMPTS = 4
+    RETRY_SDK_INITIAL_DELAY = 2.0
+    RETRY_SDK_MAX_DELAY = 16.0
+
+    # --- Frontend ---
+    FRONTEND_URL = "http://localhost:4200"
+
+    # --- Gateway ---
+    GATEWAY_MCP_ENABLED = True
+
+    # --- Voice Agent ---
+    NOVA_SONIC_MODEL_ID = "amazon.nova-2-sonic-v1:0"
+    NOVA_SONIC_VOICE = "tiffany"
+    NOVA_SONIC_INPUT_RATE = 16000
+    NOVA_SONIC_OUTPUT_RATE = 16000
+    NOVA_SONIC_MAX_MESSAGES = 20
+    VOICE_AGENT_ID = "voice"
+
+
+class Prefixes:
+    """String prefixes used for tool ID classification and session routing."""
+
+    GATEWAY_TOOL = "gateway_"
+    PREVIEW_SESSION = "preview-"
diff --git a/backend/src/agents/main_agent/core/agent_factory.py b/backend/src/agents/main_agent/core/agent_factory.py
index a8164b15..9586a7a9 100644
--- a/backend/src/agents/main_agent/core/agent_factory.py
+++ b/backend/src/agents/main_agent/core/agent_factory.py
@@ -10,6 +10,7 @@
 from strands.models.gemini import GeminiModel
 from strands.tools.executors import SequentialToolExecutor
 from agents.main_agent.core.model_config import ModelConfig, ModelProvider
+from agents.main_agent.config.constants import EnvVars
 
 logger = logging.getLogger(__name__)
 
@@ -45,10 +46,10 @@ def _create_openai_model(model_config: ModelConfig) -> OpenAIModel:
         Raises:
             ValueError: If OPENAI_API_KEY environment variable is not set
         """
-        api_key = os.getenv("OPENAI_API_KEY")
+        api_key = os.getenv(EnvVars.OPENAI_API_KEY)
         if not api_key:
             raise ValueError(
-                "OPENAI_API_KEY environment variable is required for OpenAI models. "
+                f"{EnvVars.OPENAI_API_KEY} environment variable is required for OpenAI models. "
                 "Please set it in your .env file."
             )
 
@@ -72,10 +73,10 @@ def _create_gemini_model(model_config: ModelConfig) -> GeminiModel:
         Raises:
             ValueError: If GOOGLE_GEMINI_API_KEY environment variable is not set
         """
-        api_key = os.getenv("GOOGLE_GEMINI_API_KEY")
+        api_key = os.getenv(EnvVars.GOOGLE_GEMINI_API_KEY)
         if not api_key:
             raise ValueError(
-                "GOOGLE_GEMINI_API_KEY environment variable is required for Gemini models. "
+                f"{EnvVars.GOOGLE_GEMINI_API_KEY} environment variable is required for Gemini models. "
                 "Please set it in your .env file."
             )
 
diff --git a/backend/src/agents/main_agent/core/model_config.py b/backend/src/agents/main_agent/core/model_config.py
index ac6a6d34..d01d2458 100644
--- a/backend/src/agents/main_agent/core/model_config.py
+++ b/backend/src/agents/main_agent/core/model_config.py
@@ -6,6 +6,8 @@
 from dataclasses import dataclass
 from enum import Enum
 
+from agents.main_agent.config.constants import EnvVars, Defaults
+
 
 class ModelProvider(str, Enum):
     """Supported LLM providers"""
@@ -54,22 +56,22 @@ def from_env(cls) -> "RetryConfig":
             RETRY_SDK_MAX_DELAY=16.0
         """
         return cls(
-            boto_max_attempts=int(os.environ.get("RETRY_BOTO_MAX_ATTEMPTS", "3")),
-            boto_retry_mode=os.environ.get("RETRY_BOTO_MODE", "standard"),
-            connect_timeout=int(os.environ.get("RETRY_CONNECT_TIMEOUT", "5")),
-            read_timeout=int(os.environ.get("RETRY_READ_TIMEOUT", "120")),
-            sdk_max_attempts=int(os.environ.get("RETRY_SDK_MAX_ATTEMPTS", "4")),
-            sdk_initial_delay=float(os.environ.get("RETRY_SDK_INITIAL_DELAY", "2.0")),
-            sdk_max_delay=float(os.environ.get("RETRY_SDK_MAX_DELAY", "16.0")),
+            boto_max_attempts=int(os.environ.get(EnvVars.RETRY_BOTO_MAX_ATTEMPTS, str(Defaults.RETRY_BOTO_MAX_ATTEMPTS))),
+            boto_retry_mode=os.environ.get(EnvVars.RETRY_BOTO_MODE, Defaults.RETRY_BOTO_MODE),
+            connect_timeout=int(os.environ.get(EnvVars.RETRY_CONNECT_TIMEOUT, str(Defaults.RETRY_CONNECT_TIMEOUT))),
+            read_timeout=int(os.environ.get(EnvVars.RETRY_READ_TIMEOUT, str(Defaults.RETRY_READ_TIMEOUT))),
+            sdk_max_attempts=int(os.environ.get(EnvVars.RETRY_SDK_MAX_ATTEMPTS, str(Defaults.RETRY_SDK_MAX_ATTEMPTS))),
+            sdk_initial_delay=float(os.environ.get(EnvVars.RETRY_SDK_INITIAL_DELAY, str(Defaults.RETRY_SDK_INITIAL_DELAY))),
+            sdk_max_delay=float(os.environ.get(EnvVars.RETRY_SDK_MAX_DELAY, str(Defaults.RETRY_SDK_MAX_DELAY))),
         )
 
 
 @dataclass
 class ModelConfig:
     """Configuration for multi-provider LLM models"""
-    model_id: str = "us.anthropic.claude-haiku-4-5-20251001-v1:0"
-    temperature: float = 0.7
-    caching_enabled: bool = True
+    model_id: str = Defaults.MODEL_ID
+    temperature: float = Defaults.TEMPERATURE
+    caching_enabled: bool = Defaults.CACHING_ENABLED
     provider: ModelProvider = ModelProvider.BEDROCK
     max_tokens: Optional[int] = None
     retry_config: Optional[RetryConfig] = None
diff --git a/backend/src/agents/main_agent/integrations/gateway_mcp_client.py b/backend/src/agents/main_agent/integrations/gateway_mcp_client.py
index ac2cda7a..de1a7953 100644
--- a/backend/src/agents/main_agent/integrations/gateway_mcp_client.py
+++ b/backend/src/agents/main_agent/integrations/gateway_mcp_client.py
@@ -9,6 +9,7 @@
 from typing import Optional, List, Callable, Any
 from mcp.client.streamable_http import streamablehttp_client
 from strands.tools.mcp import MCPClient
+from agents.main_agent.config.constants import EnvVars, Defaults
 from agents.main_agent.integrations.gateway_auth import get_sigv4_auth, get_gateway_region_from_url
 
 logger = logging.getLogger(__name__)
@@ -244,7 +245,7 @@ def create_filtered_gateway_client(
 
 
 # Environment variable control
-GATEWAY_ENABLED = os.environ.get('AGENTCORE_GATEWAY_MCP_ENABLED', 'true').lower() == 'true'
+GATEWAY_ENABLED = os.environ.get(EnvVars.GATEWAY_MCP_ENABLED, str(Defaults.GATEWAY_MCP_ENABLED).lower()).lower() == 'true'
 
 def get_gateway_client_if_enabled(
     enabled_tool_ids: Optional[List[str]] = None
diff --git a/backend/src/agents/main_agent/main_agent.py b/backend/src/agents/main_agent/main_agent.py
index 7648716c..40341f9c 100644
--- a/backend/src/agents/main_agent/main_agent.py
+++ b/backend/src/agents/main_agent/main_agent.py
@@ -1,323 +1,24 @@
 """
-Main Agent Orchestrator - Slim coordination layer for multi-agent system
+Main Agent - Backward-compatible alias for ChatAgent
 
-This module provides a clean, maintainable agent implementation with clear separation
-of concerns across specialized modules.
+All existing code that imports MainAgent continues to work unchanged.
+New code should use create_agent() factory or import ChatAgent directly.
 """
 
-import logging
-from typing import AsyncGenerator, List, Optional
+from agents.main_agent.chat_agent import ChatAgent
 
-# Core orchestration
-from agents.main_agent.core import ModelConfig, SystemPromptBuilder, AgentFactory
 
-# Session management
-from agents.main_agent.session import SessionFactory
-from agents.main_agent.session.hooks import StopHook
-
-# Tool management
-from agents.main_agent.tools import (
-    create_default_registry,
-    ToolFilter,
-    GatewayIntegration
-)
-
-# Multimodal content
-from agents.main_agent.multimodal import PromptBuilder
-
-# Session management
-from agents.main_agent.session import SessionFactory
-from agents.main_agent.session.hooks import StopHook
-
-# Streaming coordination
-from agents.main_agent.streaming import StreamCoordinator
-
-# Tool management
-from agents.main_agent.tools import GatewayIntegration, ToolFilter, create_default_registry
-
-logger = logging.getLogger(__name__)
-
-
-class MainAgent:
-    """
-    Main Agent orchestrator with modular architecture
-
-    Responsibilities:
-    - Initialize and coordinate specialized modules
-    - Provide public API for agent operations
-    - Maintain minimal state (delegate to modules)
+class MainAgent(ChatAgent):
     """
+    Backward-compatible alias for ChatAgent.
 
-    def __init__(
-        self,
-        session_id: str,
-        user_id: Optional[str] = None,
-        auth_token: Optional[str] = None,
-        enabled_tools: Optional[List[str]] = None,
-        model_id: Optional[str] = None,
-        temperature: Optional[float] = None,
-        system_prompt: Optional[str] = None,
-        caching_enabled: Optional[bool] = None,
-        provider: Optional[str] = None,
-        max_tokens: Optional[int] = None,
-        skip_persistence: bool = False,
-    ):
-        """
-        Initialize Main Agent with modular architecture and multi-provider support
-
-        Args:
-            session_id: Session identifier for message persistence
-            user_id: User identifier for cross-session preferences (defaults to session_id)
-            auth_token: Raw OIDC token for forwarding to external MCP tools (optional)
-            enabled_tools: List of tool IDs to enable. If None, all tools are enabled.
-            model_id: Model ID to use (format depends on provider)
-                - Bedrock: "us.anthropic.claude-haiku-4-5-20251001-v1:0"
-                - OpenAI: "gpt-4o", "gpt-4o-mini", "o1-preview"
-                - Gemini: "gemini-2.5-flash", "gemini-2.5-pro"
-            temperature: Model temperature (0.0 - 1.0)
-            system_prompt: System prompt text
-            caching_enabled: Whether to enable prompt caching (Bedrock only)
-            provider: LLM provider ("bedrock", "openai", or "gemini"). If not specified,
-                     will auto-detect from model_id
-            max_tokens: Maximum tokens to generate (optional)
-            skip_persistence: If True, don't persist messages (for preview sessions)
-        """
-        # Basic state
-        self.session_id = session_id
-        self.user_id = user_id or session_id
-        self.auth_token = auth_token
-        self.enabled_tools = enabled_tools
-        self.agent = None
-
-        # Initialize model configuration
-        self.model_config = ModelConfig.from_params(
-            model_id=model_id, temperature=temperature, caching_enabled=caching_enabled, provider=provider, max_tokens=max_tokens
-        )
-
-        # Load retry configuration from environment variables
-        # This controls both botocore-level and Strands SDK-level retry behavior
-        from agents.main_agent.core.model_config import RetryConfig
-        self.model_config.retry_config = RetryConfig.from_env()
-
-        # Initialize system prompt builder
-        if system_prompt:
-            # User provided prompt (BFF already added date)
-            self.prompt_builder = SystemPromptBuilder.from_user_prompt(system_prompt)
-            self.system_prompt = self.prompt_builder.build(include_date=False)
-        else:
-            # Use default prompt with date injection
-            self.prompt_builder = SystemPromptBuilder()
-            self.system_prompt = self.prompt_builder.build(include_date=True)
-
-        # Initialize tool registry and filter
-        self.tool_registry = create_default_registry()
-        self.tool_filter = ToolFilter(self.tool_registry)
-
-        # Register external MCP tool IDs from enabled tools
-        # (These will be loaded lazily during _create_agent)
-        self._register_external_mcp_tools()
-
-        # Initialize gateway integration
-        self.gateway_integration = GatewayIntegration()
-
-        # Initialize multimodal prompt builder
-        self.multimodal_builder = PromptBuilder()
-
-        # Initialize session manager
-        self.session_manager = SessionFactory.create_session_manager(
-            session_id=session_id, user_id=self.user_id, caching_enabled=self.model_config.caching_enabled
-        )
-
-        # Initialize streaming coordinator (now stateless)
-        self.stream_coordinator = StreamCoordinator()
-
-        # Create the agent
-        self._create_agent()
-
-    def _create_agent(self) -> None:
-        """Create agent with filtered tools and session management"""
-        try:
-            # Get filtered tools using extended filter
-            filter_result = self.tool_filter.filter_tools_extended(self.enabled_tools)
-            local_tools = filter_result.local_tools
-            gateway_tool_ids = filter_result.gateway_tool_ids
-            external_mcp_tool_ids = filter_result.external_mcp_tool_ids
-
-            # Get gateway client and add to tools if available
-            if gateway_tool_ids:
-                gateway_client = self.gateway_integration.get_client(gateway_tool_ids)
-                if gateway_client:
-                    local_tools = self.gateway_integration.add_to_tool_list(local_tools)
-
-            # Load external MCP tools and add to tools list
-            # Pass user_id for OAuth token retrieval and auth_token for OIDC forwarding
-            if external_mcp_tool_ids:
-                import asyncio
-
-                from agents.main_agent.integrations.external_mcp_client import get_external_mcp_integration
-
-                external_integration = get_external_mcp_integration()
-                # Run async load in sync context
-                loop = asyncio.get_event_loop()
-                if loop.is_running():
-                    # If we're already in an async context, we need to handle differently
-                    import concurrent.futures
-
-                    with concurrent.futures.ThreadPoolExecutor() as executor:
-                        future = executor.submit(
-                            asyncio.run,
-                            external_integration.load_external_tools(
-                                external_mcp_tool_ids,
-                                user_id=self.user_id,
-                                auth_token=self.auth_token,
-                            ),
-                        )
-                        external_clients = future.result()
-                else:
-                    external_clients = loop.run_until_complete(
-                        external_integration.load_external_tools(
-                            external_mcp_tool_ids,
-                            user_id=self.user_id,
-                            auth_token=self.auth_token,
-                        )
-                    )
-
-                for client in external_clients:
-                    if client not in local_tools:
-                        local_tools.append(client)
+    MainAgent IS ChatAgent — same constructor, same methods, same behavior.
+    Existing callers (service.py, routes.py, tests) need no changes.
 
-                logger.info(f"Added {len(external_clients)} external MCP clients to tools")
-
-            # Create hooks
-            hooks = self._create_hooks()
-
-            # Create agent using factory
-            self.agent = AgentFactory.create_agent(
-                model_config=self.model_config, system_prompt=self.system_prompt, tools=local_tools, session_manager=self.session_manager, hooks=hooks
-            )
-
-        except Exception as e:
-            logger.error(f"Error creating agent: {e}")
-            raise
-
-    def _register_external_mcp_tools(self) -> None:
-        """
-        Register external MCP tool IDs with the tool filter.
-
-        This queries the tool catalog for tools with protocol='mcp_external'
-        and registers them with the tool filter so they're recognized during filtering.
-        """
-        if not self.enabled_tools:
-            return
-
-        try:
-            import asyncio
-
-            from apis.app_api.tools.repository import get_tool_catalog_repository
-
-            repository = get_tool_catalog_repository()
-            external_tool_ids = []
-
-            # Query each enabled tool to check if it's an external MCP tool
-            async def check_tools():
-                for tool_id in self.enabled_tools:
-                    tool = await repository.get_tool(tool_id)
-                    if tool and tool.protocol == "mcp_external":
-                        external_tool_ids.append(tool_id)
-                return external_tool_ids
-
-            # Run async check
-            try:
-                loop = asyncio.get_event_loop()
-                if loop.is_running():
-                    import concurrent.futures
-
-                    with concurrent.futures.ThreadPoolExecutor() as executor:
-                        future = executor.submit(asyncio.run, check_tools())
-                        tool_ids = future.result()
-                else:
-                    tool_ids = loop.run_until_complete(check_tools())
-            except RuntimeError:
-                # No event loop available
-                tool_ids = asyncio.run(check_tools())
-
-            if tool_ids:
-                self.tool_filter.set_external_mcp_tools(tool_ids)
-                logger.info(f"Registered {len(tool_ids)} external MCP tools: {tool_ids}")
-
-        except Exception as e:
-            logger.warning(f"Could not register external MCP tools: {e}")
-            # Non-fatal - external tools just won't be available
-
-    def _create_hooks(self) -> List:
-        """
-        Create agent hooks
-
-        Returns:
-            list: List of initialized hooks
-        """
-        hooks = []
-
-        # Add stop hook for session cancellation (always enabled)
-        stop_hook = StopHook(self.session_manager)
-        hooks.append(stop_hook)
-
-        # NOTE: Prompt caching is now handled by CacheConfig(strategy="auto") passed to BedrockModel
-        # in model_config.py. The ConversationCachingHook has been removed in favor of the SDK's
-        # built-in automatic cache point injection. See: https://github.com/strands-agents/sdk-python/pull/1438
-
-        return hooks
-
-    async def stream_async(
-        self, message: str, session_id: Optional[str] = None, files: Optional[List] = None, citations: Optional[List] = None, original_message: Optional[str] = None
-    ) -> AsyncGenerator[str, None]:
-        """
-        Stream agent responses
-
-        Args:
-            message: User message text
-            session_id: Session identifier (defaults to instance session_id)
-            files: Optional list of FileContent objects (with base64 bytes)
-            citations: Optional list of citation dicts from RAG retrieval
-            original_message: Original user message before RAG augmentation (for clean UI display)
-
-        Yields:
-            str: SSE formatted events
-        """
-        if not self.agent:
-            self._create_agent()
-
-        # Build prompt (handles multimodal content)
-        prompt = self.multimodal_builder.build_prompt(message, files)
-
-        # Stream using coordinator
-        # Pass self (MainAgent) as main_agent_wrapper so coordinator can access model_config
-        async for event in self.stream_coordinator.stream_response(
-            agent=self.agent,
-            prompt=prompt,
-            session_manager=self.session_manager,
-            session_id=session_id or self.session_id,
-            user_id=self.user_id,
-            main_agent_wrapper=self,  # Pass wrapper for metadata extraction
-            citations=citations,  # Pass citations for storage
-            original_message=original_message,  # Pass original message for display text
-        ):
-            yield event
-
-    def get_model_config(self) -> dict:
-        """
-        Get current model configuration
-
-        Returns:
-            dict: Model configuration
-        """
-        return {**self.model_config.to_dict(), "system_prompts": [self.system_prompt]}
-
-    def get_tool_statistics(self) -> dict:
-        """
-        Get tool filtering statistics
-
-        Returns:
-            dict: Tool statistics
-        """
-        return self.tool_filter.get_statistics(self.enabled_tools)
+    For new agent types, use the agent factory:
+        from agents.main_agent.agent_types import create_agent
+        agent = create_agent("chat", session_id=..., ...)
+        agent = create_agent("skill", session_id=..., ...)
+        agent = create_agent("voice", session_id=..., ...)
+    """
+    pass
diff --git a/backend/src/agents/main_agent/quota/repository.py b/backend/src/agents/main_agent/quota/repository.py
index 7f7ee96c..07c75772 100644
--- a/backend/src/agents/main_agent/quota/repository.py
+++ b/backend/src/agents/main_agent/quota/repository.py
@@ -7,6 +7,7 @@
 import logging
 import os
 from .models import QuotaTier, QuotaAssignment, QuotaEvent, QuotaAssignmentType, QuotaOverride
+from agents.main_agent.config.constants import EnvVars, Defaults
 
 logger = logging.getLogger(__name__)
 
@@ -21,9 +22,9 @@ def __init__(
     ):
         # Use environment variables if table names not provided
         if table_name is None:
-            table_name = os.getenv("DYNAMODB_QUOTA_TABLE", "UserQuotas")
+            table_name = os.getenv(EnvVars.DYNAMODB_QUOTA_TABLE, Defaults.DYNAMODB_QUOTA_TABLE)
         if events_table_name is None:
-            events_table_name = os.getenv("DYNAMODB_QUOTA_EVENTS_TABLE", "QuotaEvents")
+            events_table_name = os.getenv(EnvVars.DYNAMODB_QUOTA_EVENTS_TABLE, Defaults.DYNAMODB_QUOTA_EVENTS_TABLE)
 
         self.dynamodb = boto3.resource('dynamodb')
         self.table = self.dynamodb.Table(table_name)
diff --git a/backend/src/agents/main_agent/session/compaction_models.py b/backend/src/agents/main_agent/session/compaction_models.py
index e11346ca..f018b352 100644
--- a/backend/src/agents/main_agent/session/compaction_models.py
+++ b/backend/src/agents/main_agent/session/compaction_models.py
@@ -9,6 +9,8 @@
 from typing import Optional, Dict, Any
 import os
 
+from agents.main_agent.config.constants import EnvVars, Defaults
+
 
 @dataclass
 class CompactionState:
@@ -62,8 +64,8 @@ class CompactionConfig:
     def from_env(cls) -> "CompactionConfig":
         """Load configuration from environment variables."""
         return cls(
-            enabled=os.environ.get("AGENTCORE_MEMORY_COMPACTION_ENABLED", "true").lower() == "true",
-            token_threshold=int(os.environ.get("AGENTCORE_MEMORY_COMPACTION_TOKEN_THRESHOLD", "100000")),
-            protected_turns=int(os.environ.get("AGENTCORE_MEMORY_COMPACTION_PROTECTED_TURNS", "3")),
-            max_tool_content_length=int(os.environ.get("AGENTCORE_MEMORY_COMPACTION_MAX_TOOL_CONTENT_LENGTH", "500")),
+            enabled=os.environ.get(EnvVars.COMPACTION_ENABLED, str(Defaults.COMPACTION_ENABLED).lower()).lower() == "true",
+            token_threshold=int(os.environ.get(EnvVars.COMPACTION_TOKEN_THRESHOLD, str(Defaults.COMPACTION_TOKEN_THRESHOLD))),
+            protected_turns=int(os.environ.get(EnvVars.COMPACTION_PROTECTED_TURNS, str(Defaults.COMPACTION_PROTECTED_TURNS))),
+            max_tool_content_length=int(os.environ.get(EnvVars.COMPACTION_MAX_TOOL_CONTENT_LENGTH, str(Defaults.COMPACTION_MAX_TOOL_CONTENT_LENGTH))),
         )
diff --git a/backend/src/agents/main_agent/session/hooks/__init__.py b/backend/src/agents/main_agent/session/hooks/__init__.py
index fafbd85d..9900a4a5 100644
--- a/backend/src/agents/main_agent/session/hooks/__init__.py
+++ b/backend/src/agents/main_agent/session/hooks/__init__.py
@@ -1,9 +1,19 @@
 """Hooks for Main Agent"""
 
 from agents.main_agent.session.hooks.stop import StopHook
+from agents.main_agent.session.hooks.tool_approval import (
+    ToolApprovalHook,
+    EmailApprovalHook,
+    ExternalWriteApprovalHook,
+    DangerousToolApprovalHook,
+)
 
 __all__ = [
     "StopHook",
+    "ToolApprovalHook",
+    "EmailApprovalHook",
+    "ExternalWriteApprovalHook",
+    "DangerousToolApprovalHook",
 ]
 
 
diff --git a/backend/src/agents/main_agent/session/hooks/tool_approval.py b/backend/src/agents/main_agent/session/hooks/tool_approval.py
new file mode 100644
index 00000000..acaa5db8
--- /dev/null
+++ b/backend/src/agents/main_agent/session/hooks/tool_approval.py
@@ -0,0 +1,90 @@
+"""
+Tool approval hooks for gating dangerous operations.
+
+These hooks intercept tool calls before execution and can request
+user confirmation for operations that modify external systems.
+
+Based on the approval hook pattern from:
+https://github.com/aws-samples/sample-strands-agent-with-agentcore
+"""
+
+import logging
+from typing import Any, Set
+
+from strands.hooks import HookProvider, HookRegistry, BeforeToolCallEvent
+
+logger = logging.getLogger(__name__)
+
+
+class ToolApprovalHook(HookProvider):
+    """
+    Base approval hook that gates specified tool names.
+
+    Subclasses define which tool names require approval and what
+    message to show the user. The hook sets the approval_required
+    flag on the event, which the streaming layer can surface to
+    the client for user confirmation.
+    """
+
+    # Subclasses override these
+    tool_names: Set[str] = set()
+    approval_message: str = "This operation requires approval."
+
+    def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
+        registry.add_callback(BeforeToolCallEvent, self.check_approval)
+
+    def check_approval(self, event: BeforeToolCallEvent) -> None:
+        """Check if the tool call requires user approval."""
+        tool_name = event.tool_use.get("name", "")
+        if tool_name in self.tool_names:
+            logger.info(f"Tool approval required: {tool_name}")
+            # The approval_required attribute signals the streaming layer
+            # to elicit user confirmation before proceeding
+            event.tool_use["_approval_required"] = True
+            event.tool_use["_approval_message"] = self.approval_message
+
+
+class EmailApprovalHook(ToolApprovalHook):
+    """Gate bulk email operations (send, delete, forward)."""
+
+    tool_names = {
+        "send_email",
+        "send_bulk_email",
+        "delete_emails",
+        "forward_email",
+    }
+    approval_message = (
+        "This tool will perform an email operation. "
+        "Please confirm you want to proceed."
+    )
+
+
+class ExternalWriteApprovalHook(ToolApprovalHook):
+    """Gate operations that write to external systems (GitHub, APIs, etc.)."""
+
+    tool_names = {
+        "create_pull_request",
+        "merge_pull_request",
+        "create_issue",
+        "push_code",
+        "deploy",
+        "delete_repository",
+    }
+    approval_message = (
+        "This tool will modify an external system. "
+        "Please confirm you want to proceed."
+    )
+
+
+class DangerousToolApprovalHook(ToolApprovalHook):
+    """Gate tools with irreversible side effects."""
+
+    tool_names = {
+        "delete_file",
+        "drop_table",
+        "execute_sql",
+    }
+    approval_message = (
+        "This tool performs an irreversible operation. "
+        "Please confirm you want to proceed."
+    )
diff --git a/backend/src/agents/main_agent/session/memory_config.py b/backend/src/agents/main_agent/session/memory_config.py
index 47883c39..6a44012e 100644
--- a/backend/src/agents/main_agent/session/memory_config.py
+++ b/backend/src/agents/main_agent/session/memory_config.py
@@ -7,6 +7,8 @@
 import logging
 from dataclasses import dataclass
 
+from agents.main_agent.config.constants import EnvVars, Defaults
+
 logger = logging.getLogger(__name__)
 
 
@@ -36,8 +38,8 @@ def load_memory_config() -> MemoryStorageConfig:
     Raises:
         RuntimeError: If AGENTCORE_MEMORY_ID is not set
     """
-    memory_id = os.environ.get("AGENTCORE_MEMORY_ID") or None
-    region = os.environ.get("AWS_REGION", "us-west-2")
+    memory_id = os.environ.get(EnvVars.MEMORY_ID) or None
+    region = os.environ.get(EnvVars.AWS_REGION, Defaults.AWS_REGION)
 
     if not memory_id:
         raise RuntimeError(
diff --git a/backend/src/agents/main_agent/session/preview_session_manager.py b/backend/src/agents/main_agent/session/preview_session_manager.py
index 22bd4402..3539cc71 100644
--- a/backend/src/agents/main_agent/session/preview_session_manager.py
+++ b/backend/src/agents/main_agent/session/preview_session_manager.py
@@ -12,10 +12,12 @@
 from typing import List, Any
 from strands.types.session import SessionMessage
 
+from agents.main_agent.config.constants import Prefixes
+
 logger = logging.getLogger(__name__)
 
 # Preview session prefix - sessions with this prefix use in-memory storage only
-PREVIEW_SESSION_PREFIX = "preview-"
+PREVIEW_SESSION_PREFIX = Prefixes.PREVIEW_SESSION
 
 
 def is_preview_session(session_id: str) -> bool:
diff --git a/backend/src/agents/main_agent/session/session_factory.py b/backend/src/agents/main_agent/session/session_factory.py
index eca7c4ba..45b66af5 100644
--- a/backend/src/agents/main_agent/session/session_factory.py
+++ b/backend/src/agents/main_agent/session/session_factory.py
@@ -6,6 +6,7 @@
 from typing import Optional, Any, Dict, Tuple
 from functools import lru_cache
 
+from agents.main_agent.config.constants import EnvVars, Defaults
 from agents.main_agent.session.memory_config import load_memory_config
 from agents.main_agent.session.compaction_models import CompactionConfig
 from agents.main_agent.session.preview_session_manager import (
@@ -160,8 +161,8 @@ def _create_cloud_session_manager(
         semantic_id, preference_id, summary_id = _discover_strategy_ids(memory_id, aws_region)
 
         # Load retrieval thresholds from environment (configurable per deployment)
-        relevance_score = float(os.environ.get("AGENTCORE_MEMORY_RELEVANCE_SCORE", "0.7"))
-        top_k = int(os.environ.get("AGENTCORE_MEMORY_TOP_K", "10"))
+        relevance_score = float(os.environ.get(EnvVars.MEMORY_RELEVANCE_SCORE, str(Defaults.MEMORY_RELEVANCE_SCORE)))
+        top_k = int(os.environ.get(EnvVars.MEMORY_TOP_K, str(Defaults.MEMORY_TOP_K)))
 
         # Build retrieval config using the correct namespace patterns
         # AgentCore stores memories in: /strategies/{strategyId}/actors/{actorId}
diff --git a/backend/src/agents/main_agent/session/tests/test_compaction.py b/backend/src/agents/main_agent/session/tests/test_compaction.py
index 99e9d679..74036984 100644
--- a/backend/src/agents/main_agent/session/tests/test_compaction.py
+++ b/backend/src/agents/main_agent/session/tests/test_compaction.py
@@ -62,9 +62,9 @@ class TestCompactionConfig:
 
     def test_default_config(self):
         config = CompactionConfig()
-        assert config.enabled is False
+        assert config.enabled is True
         assert config.token_threshold == 100_000
-        assert config.protected_turns == 2
+        assert config.protected_turns == 3
         assert config.max_tool_content_length == 500
 
     def test_from_env(self, monkeypatch):
diff --git a/backend/src/agents/main_agent/session/tests/test_compaction_integration.py b/backend/src/agents/main_agent/session/tests/test_compaction_integration.py
index c99dc918..5421667b 100644
--- a/backend/src/agents/main_agent/session/tests/test_compaction_integration.py
+++ b/backend/src/agents/main_agent/session/tests/test_compaction_integration.py
@@ -18,6 +18,13 @@
 """
 
 import os
+import pytest
+
+# Skip all tests in this module unless AWS integration env vars are set
+pytestmark = pytest.mark.skipif(
+    not os.environ.get("AGENTCORE_MEMORY_ID"),
+    reason="Integration test requires AGENTCORE_MEMORY_ID environment variable"
+)
 import sys
 import uuid
 import asyncio
diff --git a/backend/src/agents/main_agent/session/turn_based_session_manager.py b/backend/src/agents/main_agent/session/turn_based_session_manager.py
index 5241301f..2108cd78 100644
--- a/backend/src/agents/main_agent/session/turn_based_session_manager.py
+++ b/backend/src/agents/main_agent/session/turn_based_session_manager.py
@@ -20,6 +20,8 @@
 from datetime import datetime, timezone
 from typing import Optional, Dict, Any, List, TYPE_CHECKING
 
+from agents.main_agent.config.constants import EnvVars
+
 from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager
 from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig
 
@@ -243,7 +245,7 @@ def _apply_compaction(self, agent: "Agent") -> None:
     def _get_dynamodb_table(self):
         """Lazy initialization of DynamoDB table for compaction state."""
         if TurnBasedSessionManager._dynamodb_table is None:
-            table_name = os.environ.get("DYNAMODB_SESSIONS_METADATA_TABLE_NAME")
+            table_name = os.environ.get(EnvVars.DYNAMODB_SESSIONS_METADATA_TABLE)
             if not table_name:
                 logger.warning(
                     "DYNAMODB_SESSIONS_METADATA_TABLE_NAME not configured, "
diff --git a/backend/src/agents/main_agent/skill_agent.py b/backend/src/agents/main_agent/skill_agent.py
new file mode 100644
index 00000000..9a93a8e1
--- /dev/null
+++ b/backend/src/agents/main_agent/skill_agent.py
@@ -0,0 +1,123 @@
+"""
+Skill Agent — ChatAgent with progressive skill disclosure.
+
+Replaces individual skill tools with skill_dispatcher + skill_executor,
+injecting a lightweight skill catalog into the system prompt instead of
+loading all tool schemas upfront.
+"""
+
+import logging
+from typing import List, Optional
+
+from agents.main_agent.chat_agent import ChatAgent
+from agents.main_agent.core import AgentFactory
+from agents.main_agent.skills import (
+    SkillRegistry,
+    skill_dispatcher,
+    skill_executor,
+    set_dispatcher_registry,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SkillAgent(ChatAgent):
+    """
+    Chat agent with progressive skill disclosure.
+
+    Overrides _create_agent() to:
+    1. Discover skills from SKILL.md definitions
+    2. Bind tools to skills via _skill_name metadata
+    3. Replace skill tools with skill_dispatcher + skill_executor
+    4. Inject skill catalog into system prompt
+
+    The LLM sees a lightweight catalog and two meta-tools instead of
+    all individual tool schemas, dramatically reducing token usage.
+    """
+
+    def __init__(self, skills_dir: Optional[str] = None, **kwargs):
+        """
+        Initialize skill agent.
+
+        Args:
+            skills_dir: Optional path to skills definitions directory.
+                        Defaults to skills/definitions/ relative to the skills module.
+            **kwargs: All BaseAgent constructor args (session_id, user_id, etc.)
+        """
+        self._skills_dir = skills_dir
+        self._registry: Optional[SkillRegistry] = None
+        super().__init__(**kwargs)
+
+    def _create_agent(self) -> None:
+        """Create Strands Agent with skill disclosure instead of raw tool schemas."""
+        try:
+            # Step 1: Get all filtered tools (local + gateway + external MCP)
+            all_tools = self._build_filtered_tools()
+
+            # Step 2: Initialize skill registry
+            self._registry = SkillRegistry(self._skills_dir)
+            discovered = self._registry.discover_skills()
+
+            if discovered == 0:
+                logger.warning("No skills discovered — falling back to standard ChatAgent behavior")
+                # Fall back to standard ChatAgent behavior
+                hooks = self._create_hooks()
+                self.agent = AgentFactory.create_agent(
+                    model_config=self.model_config,
+                    system_prompt=self.system_prompt,
+                    tools=all_tools,
+                    session_manager=self.session_manager,
+                    hooks=hooks,
+                )
+                return
+
+            # Step 3: Bind tools to skills
+            self._registry.bind_tools(all_tools)
+
+            # Step 4: Separate skill tools from non-skill tools
+            skill_tool_set = set()
+            for skill_name in self._registry.get_skill_names():
+                for tool_obj in self._registry.get_tools(skill_name):
+                    skill_tool_set.add(id(tool_obj))
+
+            non_skill_tools = [t for t in all_tools if id(t) not in skill_tool_set]
+
+            # Step 5: Wire up the dispatcher registry
+            set_dispatcher_registry(self._registry)
+
+            # Step 6: Build final tool list: non-skill tools + dispatcher + executor
+            final_tools = non_skill_tools + [skill_dispatcher, skill_executor]
+
+            # Step 7: Inject skill catalog into system prompt
+            catalog = self._registry.get_catalog()
+            if catalog:
+                if isinstance(self.system_prompt, str):
+                    self.system_prompt = self.system_prompt + "\n\n" + catalog
+                elif isinstance(self.system_prompt, list):
+                    # System prompt is a list of content blocks
+                    self.system_prompt.append({"text": "\n\n" + catalog})
+
+            logger.info(
+                f"SkillAgent created: {discovered} skills, "
+                f"{len(non_skill_tools)} non-skill tools, "
+                f"2 meta-tools (dispatcher + executor)"
+            )
+
+            # Step 8: Create agent
+            hooks = self._create_hooks()
+            self.agent = AgentFactory.create_agent(
+                model_config=self.model_config,
+                system_prompt=self.system_prompt,
+                tools=final_tools,
+                session_manager=self.session_manager,
+                hooks=hooks,
+            )
+
+        except Exception as e:
+            logger.error(f"Error creating skill agent: {e}")
+            raise
+
+    @property
+    def registry(self) -> Optional[SkillRegistry]:
+        """Access the skill registry for inspection."""
+        return self._registry
diff --git a/backend/src/agents/main_agent/skills/__init__.py b/backend/src/agents/main_agent/skills/__init__.py
new file mode 100644
index 00000000..0ee71ef6
--- /dev/null
+++ b/backend/src/agents/main_agent/skills/__init__.py
@@ -0,0 +1,24 @@
+"""
+Progressive Skill Disclosure System
+
+Provides a three-level disclosure architecture for managing tool complexity:
+- Level 1 (Catalog): Skill names + descriptions injected into system prompt
+- Level 2 (Instructions): Full SKILL.md loaded on-demand via skill_dispatcher
+- Level 3 (Execution): Tool invocation via skill_executor
+
+This approach is dramatically more token-efficient than loading all tool schemas
+upfront, especially as the number of tools grows.
+"""
+
+from .decorators import skill, register_skill
+from .skill_registry import SkillRegistry
+from .skill_tools import skill_dispatcher, skill_executor, set_dispatcher_registry
+
+__all__ = [
+    "skill",
+    "register_skill",
+    "SkillRegistry",
+    "skill_dispatcher",
+    "skill_executor",
+    "set_dispatcher_registry",
+]
diff --git a/backend/src/agents/main_agent/skills/decorators.py b/backend/src/agents/main_agent/skills/decorators.py
new file mode 100644
index 00000000..63504ca1
--- /dev/null
+++ b/backend/src/agents/main_agent/skills/decorators.py
@@ -0,0 +1,46 @@
+"""
+Skill decorators for tagging tools with skill membership.
+
+Usage:
+    @skill("web-search")
+    @tool
+    def ddg_web_search(...): ...
+
+    # Or batch registration:
+    register_skill("visualization", tools=[create_chart, create_graph])
+"""
+
+from typing import List, Any
+
+
+def _apply_skill_metadata(tool_obj: Any, name: str) -> None:
+    """Attach skill name metadata to a tool object."""
+    tool_obj._skill_name = name
+
+
+def skill(name: str):
+    """
+    Decorator that tags a tool function with a skill name.
+
+    The SkillRegistry uses the _skill_name attribute to bind tools
+    to their parent skill during discovery.
+
+    Args:
+        name: Skill identifier (must match a SKILL.md directory name)
+    """
+    def decorator(func):
+        _apply_skill_metadata(func, name)
+        return func
+    return decorator
+
+
+def register_skill(name: str, tools: List[Any]) -> None:
+    """
+    Batch-register multiple tools under a single skill name.
+
+    Args:
+        name: Skill identifier
+        tools: List of tool objects to tag
+    """
+    for tool_obj in tools:
+        _apply_skill_metadata(tool_obj, name)
diff --git a/backend/src/agents/main_agent/skills/definitions/web-search/SKILL.md b/backend/src/agents/main_agent/skills/definitions/web-search/SKILL.md
new file mode 100644
index 00000000..5dd9cb38
--- /dev/null
+++ b/backend/src/agents/main_agent/skills/definitions/web-search/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: web-search
+description: Search the web for current information
+type: tool
+---
+
+# Web Search Skill
+
+Use this skill to search the web for up-to-date information that may not
+be in your training data.
+
+## When to Use
+
+- User asks about current events or recent information
+- User needs real-time data (weather, stock prices, news)
+- User asks "what is the latest..." or "search for..."
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `fetch_url_content` | Fetch and extract content from a URL |
+
+## Usage Pattern
+
+1. Use `fetch_url_content` to retrieve content from a specific URL
+2. Summarize the relevant information for the user
+3. Cite the source URL in your response
diff --git a/backend/src/agents/main_agent/skills/skill_registry.py b/backend/src/agents/main_agent/skills/skill_registry.py
new file mode 100644
index 00000000..225cbf10
--- /dev/null
+++ b/backend/src/agents/main_agent/skills/skill_registry.py
@@ -0,0 +1,298 @@
+"""
+Skill Registry — single source of truth for skill discovery and access.
+
+Scans a skills definitions directory for SKILL.md files, parses their
+frontmatter for metadata, and provides three levels of access:
+
+- Level 1: get_catalog() → lightweight listing for system prompt injection
+- Level 2: load_instructions(name) → full SKILL.md body on demand
+- Level 3: get_tools(name) → executable tool objects
+
+Based on the progressive disclosure pattern from:
+https://github.com/aws-samples/sample-strands-agent-with-agentcore
+"""
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Regex for parsing YAML frontmatter (no PyYAML dependency)
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+_YAML_LINE_RE = re.compile(r"^(\w+):\s*(.*)$")
+_YAML_LIST_ITEM_RE = re.compile(r"^\s*-\s+(.+)$")
+
+
+class SkillRegistry:
+    """
+    Registry for discovering and managing agent skills.
+
+    Skills are defined by SKILL.md files in a directory structure:
+        definitions/
+        ├── web-search/
+        │   └── SKILL.md
+        ├── visualization/
+        │   └── SKILL.md
+        └── ...
+
+    Each SKILL.md has YAML frontmatter:
+        ---
+        name: web-search
+        description: Search the web using DuckDuckGo
+        type: tool
+        ---
+        <markdown instructions>
+    """
+
+    def __init__(self, skills_dir: Optional[str] = None):
+        """
+        Initialize the registry.
+
+        Args:
+            skills_dir: Path to skills definitions directory.
+                        Defaults to ./definitions/ relative to this module.
+        """
+        if skills_dir is None:
+            skills_dir = os.path.join(os.path.dirname(__file__), "definitions")
+        self._skills_dir = skills_dir
+        self._skills: Dict[str, Dict[str, Any]] = {}
+
+    def discover_skills(self) -> int:
+        """
+        Scan the skills directory for SKILL.md files.
+
+        Returns:
+            int: Number of skills discovered
+        """
+        if not os.path.isdir(self._skills_dir):
+            logger.warning(f"Skills directory not found: {self._skills_dir}")
+            return 0
+
+        count = 0
+        for entry in sorted(os.listdir(self._skills_dir)):
+            skill_dir = os.path.join(self._skills_dir, entry)
+            skill_md = os.path.join(skill_dir, "SKILL.md")
+
+            if not os.path.isfile(skill_md):
+                continue
+
+            try:
+                with open(skill_md, "r", encoding="utf-8") as f:
+                    content = f.read()
+
+                meta = self._parse_frontmatter(content)
+                name = meta.get("name", entry)
+
+                self._skills[name] = {
+                    "description": meta.get("description", ""),
+                    "type": meta.get("type", "tool"),
+                    "compose": meta.get("compose", []),
+                    "tools": [],
+                    "path": skill_dir,
+                    "md_path": skill_md,
+                }
+                count += 1
+                logger.info(f"Discovered skill: {name}")
+
+            except Exception as e:
+                logger.error(f"Error parsing {skill_md}: {e}")
+
+        logger.info(f"Discovered {count} skills from {self._skills_dir}")
+        return count
+
+    def bind_tools(self, tools: List[Any]) -> int:
+        """
+        Attach tool objects to their parent skills.
+
+        Tools are matched by the _skill_name attribute set by the @skill decorator
+        or register_skill() function.
+
+        Args:
+            tools: List of tool objects (functions with _skill_name metadata)
+
+        Returns:
+            int: Number of tools bound
+        """
+        bound = 0
+        for tool_obj in tools:
+            skill_name = getattr(tool_obj, "_skill_name", None)
+            if skill_name and skill_name in self._skills:
+                self._skills[skill_name]["tools"].append(tool_obj)
+                bound += 1
+                logger.debug(f"Bound tool to skill '{skill_name}'")
+
+        logger.info(f"Bound {bound} tools to {len(self._skills)} skills")
+        return bound
+
+    def get_catalog(self) -> str:
+        """
+        Generate Level 1 catalog for system prompt injection.
+
+        Returns a lightweight listing of skill names and descriptions,
+        designed to be token-efficient while giving the LLM enough
+        information to decide which skill to activate.
+
+        Returns:
+            str: Markdown-formatted skill catalog
+        """
+        if not self._skills:
+            return ""
+
+        lines = ["## Available Skills", ""]
+        lines.append("Use `skill_dispatcher` to activate a skill and get its instructions.")
+        lines.append("Use `skill_executor` to run a skill's tools.")
+        lines.append("")
+
+        for name, info in sorted(self._skills.items()):
+            desc = info["description"]
+            tool_count = len(info["tools"])
+            compose = info.get("compose", [])
+
+            if compose:
+                lines.append(f"- **{name}**: {desc} _(combines: {', '.join(compose)})_")
+            elif tool_count > 0:
+                lines.append(f"- **{name}**: {desc} ({tool_count} tools)")
+            else:
+                lines.append(f"- **{name}**: {desc}")
+
+        return "\n".join(lines)
+
+    def load_instructions(self, skill_name: str) -> Optional[str]:
+        """
+        Load Level 2 instructions (SKILL.md body without frontmatter).
+
+        Args:
+            skill_name: Skill identifier
+
+        Returns:
+            str: Markdown instructions, or None if skill not found
+        """
+        skill = self._skills.get(skill_name)
+        if not skill:
+            return None
+
+        try:
+            with open(skill["md_path"], "r", encoding="utf-8") as f:
+                content = f.read()
+            return self._strip_frontmatter(content)
+        except Exception as e:
+            logger.error(f"Error loading instructions for '{skill_name}': {e}")
+            return None
+
+    def get_tools(self, skill_name: str) -> List[Any]:
+        """
+        Get Level 3 tool objects for a skill.
+
+        For composite skills, aggregates tools from all composed skills.
+
+        Args:
+            skill_name: Skill identifier
+
+        Returns:
+            list: Tool objects, empty if skill not found
+        """
+        skill = self._skills.get(skill_name)
+        if not skill:
+            return []
+
+        # For composite skills, aggregate tools from composed skills
+        compose = skill.get("compose", [])
+        if compose:
+            tools = []
+            for child_name in compose:
+                tools.extend(self.get_tools(child_name))
+            return tools
+
+        return list(skill["tools"])
+
+    def get_tool_schemas(self, skill_name: str) -> List[Dict]:
+        """
+        Get tool parameter schemas for a skill's tools.
+
+        Extracts the tool_spec from each tool for inclusion in
+        skill_dispatcher responses, so the LLM knows what parameters
+        to pass to skill_executor.
+
+        Args:
+            skill_name: Skill identifier
+
+        Returns:
+            list: Tool specification dicts
+        """
+        tools = self.get_tools(skill_name)
+        schemas = []
+        for tool_obj in tools:
+            spec = getattr(tool_obj, "tool_spec", None)
+            if spec:
+                schemas.append(spec)
+            elif hasattr(tool_obj, "tool_name"):
+                schemas.append({"name": tool_obj.tool_name})
+        return schemas
+
+    def has_skill(self, skill_name: str) -> bool:
+        """Check if a skill is registered."""
+        return skill_name in self._skills
+
+    def get_skill_names(self) -> List[str]:
+        """Get all registered skill names."""
+        return list(self._skills.keys())
+
+    def get_skill_count(self) -> int:
+        """Get total number of registered skills."""
+        return len(self._skills)
+
+    # --- Internal helpers ---
+
+    @staticmethod
+    def _parse_frontmatter(content: str) -> Dict[str, Any]:
+        """Parse YAML frontmatter from a SKILL.md file (no PyYAML dependency)."""
+        match = _FRONTMATTER_RE.match(content)
+        if not match:
+            return {}
+
+        result = {}
+        current_key = None
+        current_list = None
+
+        for line in match.group(1).splitlines():
+            # Check for key: value pair
+            kv_match = _YAML_LINE_RE.match(line)
+            if kv_match:
+                if current_key and current_list is not None:
+                    result[current_key] = current_list
+
+                key = kv_match.group(1)
+                value = kv_match.group(2).strip().strip('"').strip("'")
+                current_key = key
+                current_list = None
+
+                if value:
+                    result[key] = value
+                else:
+                    # Empty value — next lines may be a list
+                    result[key] = ""
+                continue
+
+            # Check for list item
+            list_match = _YAML_LIST_ITEM_RE.match(line)
+            if list_match and current_key:
+                if current_list is None:
+                    current_list = []
+                    result[current_key] = current_list
+                current_list.append(list_match.group(1).strip())
+
+        if current_key and current_list is not None:
+            result[current_key] = current_list
+
+        return result
+
+    @staticmethod
+    def _strip_frontmatter(content: str) -> str:
+        """Remove YAML frontmatter from content, returning the markdown body."""
+        match = _FRONTMATTER_RE.match(content)
+        if match:
+            return content[match.end():].strip()
+        return content.strip()
diff --git a/backend/src/agents/main_agent/skills/skill_tools.py b/backend/src/agents/main_agent/skills/skill_tools.py
new file mode 100644
index 00000000..e1546099
--- /dev/null
+++ b/backend/src/agents/main_agent/skills/skill_tools.py
@@ -0,0 +1,168 @@
+"""
+Skill tools — LLM-callable tools for progressive skill disclosure.
+
+Two tools exposed to the agent:
+- skill_dispatcher: Load a skill's instructions and tool schemas (L1 → L2)
+- skill_executor: Execute a skill's tool with given input (L2 → L3)
+
+These tools are registered with the Strands Agent in place of the individual
+skill tools, dramatically reducing the upfront token cost.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Any, Optional
+
+from strands import tool
+
+logger = logging.getLogger(__name__)
+
+# Module-level registry reference, set by set_dispatcher_registry()
+_registry = None
+
+
+def set_dispatcher_registry(registry: Any) -> None:
+    """
+    Wire up the SkillRegistry for the dispatcher and executor.
+
+    Must be called before the agent invokes skill_dispatcher or skill_executor.
+
+    Args:
+        registry: SkillRegistry instance
+    """
+    global _registry
+    _registry = registry
+
+
+@tool
+def skill_dispatcher(skill_name: str, reference: str = "", source: str = "") -> str:
+    """
+    Load a skill's instructions, tool schemas, and optional reference or source code.
+
+    Call this tool when you want to activate a skill and learn how to use it.
+    The response includes the skill's detailed instructions (SKILL.md) and
+    the parameter schemas for its tools.
+
+    Args:
+        skill_name: Name of the skill to activate (from the Available Skills catalog)
+        reference: Optional — name of a reference file to read
+        source: Optional — name of a tool function to view source code for
+
+    Returns:
+        JSON string with skill instructions, tool schemas, and optional reference/source
+    """
+    if _registry is None:
+        return json.dumps({"error": "Skill registry not initialized"})
+
+    if not _registry.has_skill(skill_name):
+        available = ", ".join(_registry.get_skill_names())
+        return json.dumps({
+            "error": f"Unknown skill '{skill_name}'",
+            "available_skills": available,
+        })
+
+    result = {}
+
+    # Load Level 2 instructions
+    instructions = _registry.load_instructions(skill_name)
+    if instructions:
+        result["instructions"] = instructions
+
+    # Load tool schemas so the LLM knows what parameters to pass
+    schemas = _registry.get_tool_schemas(skill_name)
+    if schemas:
+        result["tool_schemas"] = schemas
+
+    if not result:
+        result["error"] = f"No instructions or tools found for skill '{skill_name}'"
+
+    return json.dumps(result, default=str)
+
+
+@tool
+def skill_executor(skill_name: str, tool_name: str, tool_input: Any = None) -> Any:
+    """
+    Execute a tool within an activated skill.
+
+    Call this tool after using skill_dispatcher to learn which tools are available
+    and what parameters they accept.
+
+    Args:
+        skill_name: Name of the skill containing the tool
+        tool_name: Name of the specific tool to execute
+        tool_input: Input parameters for the tool (dict or JSON string)
+
+    Returns:
+        The tool's execution result
+    """
+    if _registry is None:
+        return json.dumps({"error": "Skill registry not initialized"})
+
+    if not _registry.has_skill(skill_name):
+        return json.dumps({"error": f"Unknown skill '{skill_name}'"})
+
+    tools = _registry.get_tools(skill_name)
+    if not tools:
+        return json.dumps({"error": f"No tools found for skill '{skill_name}'"})
+
+    # Find the matching tool
+    target_tool = None
+    for t in tools:
+        name = getattr(t, "tool_name", getattr(t, "__name__", None))
+        if name == tool_name:
+            target_tool = t
+            break
+
+    if target_tool is None:
+        available = [getattr(t, "tool_name", getattr(t, "__name__", "?")) for t in tools]
+        return json.dumps({
+            "error": f"Tool '{tool_name}' not found in skill '{skill_name}'",
+            "available_tools": available,
+        })
+
+    # Parse tool_input if it's a JSON string
+    if isinstance(tool_input, str):
+        try:
+            tool_input = json.loads(tool_input)
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+    if tool_input is None:
+        tool_input = {}
+
+    # Execute the tool
+    try:
+        result = _execute_tool(target_tool, tool_input)
+        return result
+    except Exception as e:
+        logger.error(f"Error executing {skill_name}/{tool_name}: {e}", exc_info=True)
+        return json.dumps({"error": str(e)})
+
+
+def _execute_tool(tool_obj: Any, tool_input: dict) -> Any:
+    """Execute a tool function, handling sync and async cases."""
+    if isinstance(tool_input, dict):
+        result = tool_obj(**tool_input)
+    else:
+        result = tool_obj(tool_input)
+
+    # Handle async results
+    if asyncio.iscoroutine(result):
+        result = _run_async(result)
+
+    return result
+
+
+def _run_async(coro):
+    """Run an async coroutine, handling cases where an event loop may already exist."""
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as executor:
+                return executor.submit(asyncio.run, coro).result()
+        else:
+            return loop.run_until_complete(coro)
+    except RuntimeError:
+        return asyncio.run(coro)
diff --git a/backend/src/agents/main_agent/streaming/stream_coordinator.py b/backend/src/agents/main_agent/streaming/stream_coordinator.py
index a45fe181..f50be71a 100644
--- a/backend/src/agents/main_agent/streaming/stream_coordinator.py
+++ b/backend/src/agents/main_agent/streaming/stream_coordinator.py
@@ -10,6 +10,7 @@
 from datetime import datetime, timezone
 from typing import Any, AsyncGenerator, Dict, List, Optional, Union
 
+from agents.main_agent.config.constants import EnvVars
 from apis.shared.errors import ErrorCode, StreamErrorEvent, build_conversational_error_event
 
 from .stream_processor import process_agent_stream
@@ -60,8 +61,8 @@ async def stream_response(
             str: SSE formatted events
         """
         # Set environment variables for browser session isolation
-        os.environ["SESSION_ID"] = session_id
-        os.environ["USER_ID"] = user_id
+        os.environ[EnvVars.SESSION_ID] = session_id
+        os.environ[EnvVars.USER_ID] = user_id
 
         # Track timing for latency metrics
         stream_start_time = time.time()
@@ -228,11 +229,11 @@ async def stream_response(
                             usage_for_cost = accumulated_metadata.get("usage", {})
                             logger.info(f"💰 Cost calculation: model_id={model_id}, usage={usage_for_cost}")
                             try:
-                                cost = await self._calculate_streaming_cost(model_id=model_id, usage=usage_for_cost)
-                                if cost is not None:
-                                    final_metadata["cost"] = cost
+                                cost_result = await self._calculate_streaming_cost(model_id=model_id, usage=usage_for_cost)
+                                if cost_result is not None:
+                                    final_metadata["cost"] = cost_result
                                     logger.info(
-                                        f"💰 Calculated streaming cost: ${cost:.6f} for {usage_for_cost.get('inputTokens', 0)} input, {usage_for_cost.get('outputTokens', 0)} output tokens"
+                                        f"💰 Calculated streaming cost: ${cost_result['total']:.6f} (input=${cost_result['inputCost']:.6f}, output=${cost_result['outputCost']:.6f}) for {usage_for_cost.get('inputTokens', 0)} input, {usage_for_cost.get('outputTokens', 0)} output tokens"
                                     )
                             except Exception as cost_error:
                                 logger.warning(f"Failed to calculate streaming cost: {cost_error}")
@@ -624,15 +625,16 @@ def _flush_session(self, session_manager: Any) -> Optional[int]:
 
     def _get_initial_message_count(self, session_manager: Any) -> int:
         """
-        Get the initial message count from session manager BEFORE streaming starts.
+        Get the GLOBAL initial message count BEFORE streaming starts.
 
-        This is a key optimization that eliminates post-stream AgentCore Memory queries.
-        By capturing the message count at the start of streaming, we can calculate
-        the indices of new messages without querying the database after streaming.
+        Returns the total number of messages across ALL agents (default + voice)
+        in the session, because metadata retrieval in get_messages_from_cloud()
+        uses global enumerate indices across all agents' messages.
 
-        The count is obtained from:
-        1. TurnBasedSessionManager.message_count (initialized from AgentCore Memory at session start)
-        2. Fallback to 0 if no count is available
+        The agent-specific message_count (from TurnBasedSessionManager) only
+        counts messages for the "default" agent, which causes index mismatches
+        in mixed voice+text sessions.  We prefer list_messages() which returns
+        ALL messages regardless of agent_id.
 
         Args:
             session_manager: Session manager instance
@@ -640,59 +642,56 @@ def _get_initial_message_count(self, session_manager: Any) -> int:
         Returns:
             int: Number of messages that existed before this stream started (0 if unknown)
         """
-        # For TurnBasedSessionManager (cloud mode): use the pre-initialized message_count
-        # This was queried from AgentCore Memory when the session manager was created
+        # Prefer list_messages() for global count — it returns ALL messages
+        # regardless of agent_id, matching how get_messages_from_cloud() retrieves them.
+        session_id = self._resolve_session_id(session_manager)
+        if session_id:
+            lister = self._resolve_list_messages(session_manager)
+            if lister:
+                try:
+                    messages = lister(session_id, "default")
+                    count = len(messages) if messages else 0
+                    logger.info(f"Using global list_messages count: {count}")
+                    return count
+                except Exception as e:
+                    logger.warning(f"Failed to get global message count: {e}")
+
+        # Fallback to agent-specific message_count (may undercount in mixed sessions)
         if hasattr(session_manager, "message_count"):
             count = session_manager.message_count
-            logger.debug(f"Using TurnBasedSessionManager.message_count: {count}")
+            logger.debug(f"Fallback to TurnBasedSessionManager.message_count: {count}")
             return count
 
-        # Check wrapped session managers
         if hasattr(session_manager, "base_manager"):
             base_manager = session_manager.base_manager
-
-            # Check if base manager has message_count
             if hasattr(base_manager, "message_count"):
                 count = base_manager.message_count
-                logger.debug(f"Using base_manager.message_count: {count}")
+                logger.debug(f"Fallback to base_manager.message_count: {count}")
                 return count
 
-            # Try list_messages if available
-            if hasattr(base_manager, "list_messages"):
-                try:
-                    # Get session_id from config or session_manager
-                    session_id = None
-                    if hasattr(base_manager, "config"):
-                        session_id = base_manager.config.session_id
-                    elif hasattr(base_manager, "session_id"):
-                        session_id = base_manager.session_id
-                    elif hasattr(session_manager, "session_id"):
-                        session_id = session_manager.session_id
-
-                    if session_id:
-                        messages = base_manager.list_messages(session_id, "default")
-                        count = len(messages) if messages else 0
-                        logger.debug(f"Using base_manager.list_messages count: {count}")
-                        return count
-                except Exception as e:
-                    logger.warning(f"Failed to get message count from base_manager: {e}")
-
-        # Direct session manager with list_messages
-        if hasattr(session_manager, "list_messages"):
-            try:
-                session_id = getattr(session_manager, "session_id", None)
-                if session_id:
-                    messages = session_manager.list_messages(session_id, "default")
-                    count = len(messages) if messages else 0
-                    logger.debug(f"Using session_manager.list_messages count: {count}")
-                    return count
-            except Exception as e:
-                logger.warning(f"Failed to get message count from session_manager: {e}")
-
-        # Fallback: no count available (assume new session)
         logger.warning("Could not determine initial message count, defaulting to 0")
         return 0
 
+    @staticmethod
+    def _resolve_session_id(session_manager: Any) -> Optional[str]:
+        """Extract session_id from a session manager."""
+        for mgr in (session_manager, getattr(session_manager, "base_manager", None)):
+            if mgr is None:
+                continue
+            if hasattr(mgr, "config") and hasattr(mgr.config, "session_id"):
+                return mgr.config.session_id
+            if hasattr(mgr, "session_id"):
+                return mgr.session_id
+        return None
+
+    @staticmethod
+    def _resolve_list_messages(session_manager: Any) -> Optional[callable]:
+        """Find list_messages callable on a session manager."""
+        for mgr in (session_manager, getattr(session_manager, "base_manager", None)):
+            if mgr and hasattr(mgr, "list_messages"):
+                return mgr.list_messages
+        return None
+
     def _get_latest_message_id(self, session_manager: Any) -> Optional[int]:
         """
         Get the latest message ID from session manager without flushing
@@ -907,7 +906,9 @@ async def _store_message_metadata(
 
                 # Calculate cost if we have both usage and pricing
                 if token_usage and pricing_snapshot:
-                    cost = self._calculate_message_cost(usage=accumulated_metadata.get("usage", {}), pricing=pricing_snapshot)
+                    cost_result = self._calculate_message_cost(usage=accumulated_metadata.get("usage", {}), pricing=pricing_snapshot)
+                    if cost_result is not None:
+                        cost = cost_result
 
             # Create Attribution for cost tracking foundation
             attribution = Attribution(
@@ -1011,7 +1012,7 @@ async def _get_pricing_snapshot(self, model_id: str) -> Optional[Dict[str, Any]]
             logger.error(f"Failed to get pricing snapshot for {model_id}: {e}")
             return None
 
-    def _calculate_message_cost(self, usage: Dict[str, Any], pricing: Optional[Dict[str, Any]]) -> Optional[float]:
+    def _calculate_message_cost(self, usage: Dict[str, Any], pricing: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
         """
         Calculate message cost from usage and pricing
 
@@ -1020,7 +1021,7 @@ def _calculate_message_cost(self, usage: Dict[str, Any], pricing: Optional[Dict[
             pricing: Pricing snapshot (PricingSnapshot model)
 
         Returns:
-            Total cost in USD or None if pricing unavailable
+            Dict with total cost and breakdown, or None if pricing unavailable
         """
         if not pricing:
             return None
@@ -1034,14 +1035,20 @@ def _calculate_message_cost(self, usage: Dict[str, Any], pricing: Optional[Dict[
             else:
                 pricing_dict = pricing
 
-            total_cost, _ = CostCalculator.calculate_message_cost(usage, pricing_dict)
-            return total_cost
+            total_cost, breakdown = CostCalculator.calculate_message_cost(usage, pricing_dict)
+            return {
+                "total": total_cost,
+                "inputCost": breakdown.input_cost,
+                "outputCost": breakdown.output_cost,
+                "cacheReadCost": breakdown.cache_read_cost,
+                "cacheWriteCost": breakdown.cache_write_cost,
+            }
 
         except Exception as e:
             logger.error(f"Failed to calculate message cost: {e}")
             return None
 
-    async def _calculate_streaming_cost(self, model_id: str, usage: Dict[str, Any]) -> Optional[float]:
+    async def _calculate_streaming_cost(self, model_id: str, usage: Dict[str, Any]) -> Optional[Dict[str, Any]]:
         """
         Calculate cost for streaming response to send to client in real-time.
 
@@ -1054,7 +1061,7 @@ async def _calculate_streaming_cost(self, model_id: str, usage: Dict[str, Any])
             usage: Token usage dict from streaming
 
         Returns:
-            Total cost in USD or None if pricing unavailable
+            Dict with total cost and breakdown, or None if pricing unavailable
         """
         if not usage:
             return None
diff --git a/backend/src/agents/main_agent/tools/oauth_tool_service.py b/backend/src/agents/main_agent/tools/oauth_tool_service.py
index f3abdb8b..2d42f763 100644
--- a/backend/src/agents/main_agent/tools/oauth_tool_service.py
+++ b/backend/src/agents/main_agent/tools/oauth_tool_service.py
@@ -35,6 +35,8 @@ async def my_oauth_tool(query: str, tool_context: ToolContext) -> dict:
 from dataclasses import dataclass
 from typing import Optional
 
+from agents.main_agent.config.constants import EnvVars, Defaults
+
 logger = logging.getLogger(__name__)
 
 
@@ -66,7 +68,7 @@ def not_connected_response(self, tool_name: str = "this tool") -> dict:
 
         Returns a dict suitable for returning from a tool.
         """
-        frontend_url = os.getenv("FRONTEND_URL", "http://localhost:4200")
+        frontend_url = os.getenv(EnvVars.FRONTEND_URL, Defaults.FRONTEND_URL)
         connect_url = f"{frontend_url}/settings/connections"
 
         if self.needs_reauth:
@@ -238,7 +240,7 @@ def get_connect_url(self, provider_id: str) -> str:
         Returns:
             URL to the connections page
         """
-        frontend_url = os.getenv("FRONTEND_URL", "http://localhost:4200")
+        frontend_url = os.getenv(EnvVars.FRONTEND_URL, Defaults.FRONTEND_URL)
         return f"{frontend_url}/settings/connections"
 
 
@@ -311,7 +313,7 @@ def format_oauth_connection_guidance(
     if not missing_connections:
         return ""
 
-    frontend_url = os.getenv("FRONTEND_URL", "http://localhost:4200")
+    frontend_url = os.getenv(EnvVars.FRONTEND_URL, Defaults.FRONTEND_URL)
     connect_url = f"{frontend_url}/settings/connections"
 
     if len(missing_connections) == 1:
diff --git a/backend/src/agents/main_agent/tools/tool_catalog.py b/backend/src/agents/main_agent/tools/tool_catalog.py
index 2057f1d8..04910f43 100644
--- a/backend/src/agents/main_agent/tools/tool_catalog.py
+++ b/backend/src/agents/main_agent/tools/tool_catalog.py
@@ -8,6 +8,8 @@
 from typing import List, Dict, Optional
 from enum import Enum
 
+from agents.main_agent.config.constants import Prefixes
+
 
 class ToolCategory(str, Enum):
     """Categories for organizing tools in the UI."""
@@ -128,7 +130,7 @@ def add_gateway_tool(self, tool_id: str, name: str, description: str) -> None:
 
         Gateway tools are prefixed with 'gateway_' and loaded from MCP servers.
         """
-        if not tool_id.startswith("gateway_"):
+        if not tool_id.startswith(Prefixes.GATEWAY_TOOL):
             tool_id = f"gateway_{tool_id}"
 
         self._catalog[tool_id] = ToolMetadata(
diff --git a/backend/src/agents/main_agent/tools/tool_filter.py b/backend/src/agents/main_agent/tools/tool_filter.py
index 9cc3e498..3417c8da 100644
--- a/backend/src/agents/main_agent/tools/tool_filter.py
+++ b/backend/src/agents/main_agent/tools/tool_filter.py
@@ -3,6 +3,7 @@
 """
 import logging
 from typing import List, Optional, Any, Tuple
+from agents.main_agent.config.constants import Prefixes
 from agents.main_agent.tools.tool_registry import ToolRegistry
 
 logger = logging.getLogger(__name__)
@@ -78,7 +79,7 @@ def filter_tools(
             if self.registry.has_tool(tool_id):
                 # Local tool from registry
                 filtered_tools.append(self.registry.get_tool(tool_id))
-            elif tool_id.startswith("gateway_"):
+            elif tool_id.startswith(Prefixes.GATEWAY_TOOL):
                 # Gateway MCP tool - collect for separate handling
                 gateway_tool_ids.append(tool_id)
             elif tool_id in self._external_mcp_tools:
@@ -117,7 +118,7 @@ def filter_tools_extended(
             if self.registry.has_tool(tool_id):
                 # Local tool from registry
                 filtered_tools.append(self.registry.get_tool(tool_id))
-            elif tool_id.startswith("gateway_"):
+            elif tool_id.startswith(Prefixes.GATEWAY_TOOL):
                 # Gateway MCP tool (AgentCore Gateway)
                 gateway_tool_ids.append(tool_id)
             elif tool_id in self._external_mcp_tools:
@@ -159,7 +160,7 @@ def get_statistics(self, enabled_tool_ids: Optional[List[str]] = None) -> dict:
         for tool_id in enabled_tool_ids:
             if self.registry.has_tool(tool_id):
                 local_count += 1
-            elif tool_id.startswith("gateway_"):
+            elif tool_id.startswith(Prefixes.GATEWAY_TOOL):
                 gateway_count += 1
             elif tool_id in self._external_mcp_tools:
                 external_mcp_count += 1
diff --git a/backend/src/agents/main_agent/voice_agent.py b/backend/src/agents/main_agent/voice_agent.py
new file mode 100644
index 00000000..dde8a061
--- /dev/null
+++ b/backend/src/agents/main_agent/voice_agent.py
@@ -0,0 +1,397 @@
+"""
+Voice Agent — Bidirectional speech-to-speech agent using Nova Sonic.
+
+Extends BaseAgent with BidiAgent (Strands bidirectional agent) for
+real-time voice interaction. Shares session history with text ChatAgent
+for voice-text continuity.
+
+Requires: strands-agents[bidi] extra for BidiAgent and BidiNovaSonicModel.
+
+Based on the voice agent pattern from:
+https://github.com/aws-samples/sample-strands-agent-with-agentcore
+"""
+
+import asyncio
+import logging
+import os
+import sys
+import types
+from typing import Any, AsyncGenerator, List, Optional
+
+from agents.main_agent.base_agent import BaseAgent
+from agents.main_agent.config.constants import EnvVars, Defaults
+
+logger = logging.getLogger(__name__)
+
+# Optional imports — BidiAgent requires the strands bidi extra
+try:
+    from strands.experimental.bidi import BidiAgent
+    from strands.experimental.bidi.models.nova_sonic import BidiNovaSonicModel
+    BIDI_AVAILABLE = True
+except ImportError:
+    BIDI_AVAILABLE = False
+    logger.info("BidiAgent not available — install strands-agents[bidi] for voice support")
+
+
+# Mock PyAudio to avoid dependency — browser uses Web Audio API
+if "pyaudio" not in sys.modules:
+    _fake_pyaudio = types.ModuleType("pyaudio")
+    _fake_pyaudio.PyAudio = type("PyAudio", (), {})
+    sys.modules["pyaudio"] = _fake_pyaudio
+
+
+class VoiceAgent(BaseAgent):
+    """
+    Bidirectional voice agent using AWS Nova Sonic 2.
+
+    Provides:
+    - Real-time speech-to-speech via BidiNovaSonicModel
+    - Voice-text continuity (loads previous text chat history)
+    - Separate agent_id ("voice") to avoid session state conflicts
+    - Configurable voice, sample rate, and model via environment variables
+
+    Usage:
+        agent = VoiceAgent(session_id="sess-123", enabled_tools=[...])
+        await agent.start()
+        await agent.send_audio(audio_base64, sample_rate=16000)
+        async for event in agent.stream_async(""):
+            # BidiOutputEvent, BidiAudioStreamEvent, etc.
+    """
+
+    def __init__(self, voice: Optional[str] = None, **kwargs):
+        """
+        Initialize voice agent.
+
+        Args:
+            voice: Voice name override ("matthew", "tiffany", "amy").
+                   Defaults to NOVA_SONIC_VOICE env var or "tiffany".
+            **kwargs: All BaseAgent constructor args
+        """
+        self._voice = voice or os.environ.get(
+            EnvVars.NOVA_SONIC_VOICE, Defaults.NOVA_SONIC_VOICE
+        )
+        self._bidi_agent: Any = None
+        # Nova Sonic bidi_usage events report CUMULATIVE token counts (not deltas).
+        # _accumulated_usage stores the latest cumulative snapshot from the stream.
+        self._accumulated_usage: dict = {"inputTokens": 0, "outputTokens": 0, "totalTokens": 0}
+        self._per_turn_usage: List[dict] = []  # Snapshot of usage per completed turn
+        self._turn_count: int = 0  # Completed turns (bidi_response_complete)
+        self._response_start_count: int = 0  # Started turns (bidi_response_start)
+        super().__init__(**kwargs)
+
+    def _create_agent(self) -> None:
+        """Create BidiAgent with Nova Sonic model and shared tools."""
+        if not BIDI_AVAILABLE:
+            raise RuntimeError(
+                "Voice agent requires BidiAgent. "
+                "Install with: uv sync --extra bidi"
+            )
+
+        try:
+            tools = self._build_filtered_tools()
+
+            # Configure Nova Sonic 2 model
+            model_id = os.environ.get(
+                EnvVars.NOVA_SONIC_MODEL_ID, Defaults.NOVA_SONIC_MODEL_ID
+            )
+
+            model = BidiNovaSonicModel(
+                model_id=model_id,
+                provider_config={
+                    "audio": {
+                        "voice": self._voice,
+                        "input_rate": Defaults.NOVA_SONIC_INPUT_RATE,
+                        "output_rate": Defaults.NOVA_SONIC_OUTPUT_RATE,
+                        "channels": 1,
+                        "format": "pcm",
+                    },
+                },
+                client_config={"region": os.environ.get(EnvVars.AWS_REGION, Defaults.AWS_REGION)},
+            )
+
+            # Build voice-specific system prompt
+            voice_prompt = self._build_voice_system_prompt()
+
+            # Load text history for voice-text continuity
+            initial_messages = self._load_text_history()
+
+            # Create BidiAgent with separate agent_id
+            self._bidi_agent = BidiAgent(
+                model=model,
+                tools=tools,
+                system_prompt=voice_prompt,
+                agent_id=Defaults.VOICE_AGENT_ID,
+                session_manager=self.session_manager,
+                messages=initial_messages,
+            )
+
+            # Also store as self.agent for BaseAgent compatibility
+            self.agent = self._bidi_agent
+
+            logger.info(
+                f"VoiceAgent created: model={model_id}, voice={self._voice}, "
+                f"tools={len(tools)}, history_messages={len(initial_messages)}"
+            )
+
+        except Exception as e:
+            logger.error(f"Error creating voice agent: {e}")
+            raise
+
+    def _build_voice_system_prompt(self) -> str:
+        """Build system prompt optimized for voice interaction."""
+        base = self.system_prompt if isinstance(self.system_prompt, str) else ""
+        voice_addendum = (
+            "\n\n## Voice Interaction Guidelines\n"
+            "- Keep responses concise and conversational\n"
+            "- Avoid long lists or complex formatting (the user is listening)\n"
+            "- Use natural speech patterns\n"
+            "- Confirm understanding before taking actions\n"
+        )
+        return base + voice_addendum
+
+    def _load_text_history(self) -> list:
+        """
+        Load recent text chat history for voice-text continuity.
+
+        Reads messages from the text (default) agent's session to provide
+        context for the voice conversation. Uses agent_id="default" to
+        read from the text chat agent's history.
+        """
+        max_messages = int(os.environ.get(
+            EnvVars.NOVA_SONIC_MAX_MESSAGES, str(Defaults.NOVA_SONIC_MAX_MESSAGES)
+        ))
+
+        try:
+            if hasattr(self.session_manager, "list_messages"):
+                # AgentCoreMemorySessionManager.list_messages requires session_id and agent_id
+                # Use "default" to read the text chat agent's history
+                session_messages = self.session_manager.list_messages(
+                    session_id=self.session_id,
+                    agent_id="default",
+                    limit=max_messages,
+                )
+                if not session_messages:
+                    return []
+
+                # Convert SessionMessage objects to plain message dicts for BidiAgent
+                # to_message() returns {"role": "user"|"assistant", "content": [...]}
+                # (to_dict() wraps it in metadata — Nova Sonic needs the inner message)
+                return [msg.to_message() for msg in session_messages]
+        except Exception as e:
+            logger.warning(f"Could not load text history: {e}")
+
+        return []
+
+    async def start(self) -> None:
+        """Start the bidirectional voice connection."""
+        if not self._bidi_agent:
+            self._create_agent()
+        await self._bidi_agent.start()
+
+    async def send_audio(self, audio_base64: str, sample_rate: int = 16000) -> None:
+        """
+        Send audio data to the voice agent via BidiAgent.send().
+
+        Args:
+            audio_base64: Base64-encoded PCM audio
+            sample_rate: Audio sample rate (default 16kHz)
+        """
+        if not self._bidi_agent:
+            raise RuntimeError("Voice agent not started")
+
+        await self._bidi_agent.send({
+            "type": "bidi_audio_input",
+            "audio": audio_base64,
+            "format": "pcm",
+            "sample_rate": sample_rate,
+            "channels": 1,
+        })
+
+    async def send_text(self, text: str) -> None:
+        """
+        Send text input to the voice agent via BidiAgent.send().
+
+        Args:
+            text: Text message to send
+        """
+        if not self._bidi_agent:
+            raise RuntimeError("Voice agent not started")
+
+        await self._bidi_agent.send({
+            "type": "bidi_text_input",
+            "text": text,
+            "role": "user",
+        })
+
+    @property
+    def accumulated_usage(self) -> dict:
+        """Token usage accumulated across all voice turns."""
+        return self._accumulated_usage
+
+    @property
+    def turn_count(self) -> int:
+        """Number of completed assistant response turns."""
+        return self._turn_count
+
+    @property
+    def response_start_count(self) -> int:
+        """Number of started assistant responses (may exceed turn_count if interrupted)."""
+        return self._response_start_count
+
+    @property
+    def per_turn_usage(self) -> List[dict]:
+        """Token usage snapshots for each completed turn."""
+        return self._per_turn_usage
+
+    @property
+    def voice_model_id(self) -> str:
+        """Nova Sonic model ID used by this agent."""
+        return os.environ.get(EnvVars.NOVA_SONIC_MODEL_ID, Defaults.NOVA_SONIC_MODEL_ID)
+
+    async def receive_events(self) -> AsyncGenerator[dict, None]:
+        """
+        Receive and transform events from BidiAgent for WebSocket transmission.
+
+        Wraps BidiAgent.receive() and converts typed event objects to plain
+        dicts via as_dict(). This is the primary event source for the voice
+        WebSocket route.
+
+        Intercepts bidi_usage events to accumulate token counts, calculate
+        real-time cost, and enrich the event with a cost breakdown before
+        forwarding to the client.
+
+        Yields:
+            dict: Event dictionaries suitable for JSON serialization
+        """
+        if not self._bidi_agent:
+            raise RuntimeError("Voice agent not started")
+
+        # Lazy-loaded pricing for real-time cost calculation
+        pricing_dict: Optional[dict] = None
+        pricing_loaded = False
+
+        async for event in self._bidi_agent.receive():
+            if hasattr(event, "as_dict"):
+                event_dict = event.as_dict()
+            else:
+                event_dict = {"type": "unknown", "data": str(event)}
+
+            event_type = event_dict.get("type", "")
+
+            # Log non-audio event types for debugging (skip audio to avoid noise)
+            if event_type not in ("bidi_audio_stream",):
+                if any(k in event_dict for k in ("usage", "inputTokens", "outputTokens", "totalTokens")):
+                    logger.info(f"Voice event: type={event_type}, keys={list(event_dict.keys())}")
+                else:
+                    logger.info(f"Voice event: type={event_type}")
+
+            # Track started turns (bidi_response_start)
+            if event_type == "bidi_response_start":
+                self._response_start_count += 1
+                logger.info(f"Voice response started (count={self._response_start_count})")
+
+            # Update cumulative token usage from bidi_usage events.
+            # Nova Sonic reports CUMULATIVE totals in each event (not deltas),
+            # so we replace rather than sum.
+            if event_type == "bidi_usage":
+                usage = event_dict.get("usage", event_dict)
+                for key in ("inputTokens", "outputTokens", "totalTokens"):
+                    self._accumulated_usage[key] = usage.get(key, self._accumulated_usage[key])
+                logger.info(f"Voice bidi_usage snapshot: {usage}")
+                logger.info(f"Voice usage current: {self._accumulated_usage}")
+
+                # Calculate real-time cost and enrich the event for the client.
+                # Pricing is fetched once and cached for the session lifetime.
+                if not pricing_loaded:
+                    pricing_loaded = True
+                    try:
+                        from apis.app_api.costs.pricing_config import get_model_pricing
+                        pricing_dict = await get_model_pricing(self.voice_model_id)
+                    except Exception as e:
+                        logger.debug(f"Voice pricing unavailable: {e}")
+
+                if pricing_dict and self._accumulated_usage.get("totalTokens", 0) > 0:
+                    try:
+                        from apis.app_api.costs.calculator import CostCalculator
+                        total_cost, breakdown = CostCalculator.calculate_message_cost(
+                            self._accumulated_usage, pricing_dict
+                        )
+                        event_dict["cost"] = {
+                            "total": total_cost,
+                            "inputCost": breakdown.input_cost,
+                            "outputCost": breakdown.output_cost,
+                            "cacheReadCost": breakdown.cache_read_cost,
+                            "cacheWriteCost": breakdown.cache_write_cost,
+                        }
+                    except Exception as e:
+                        logger.debug(f"Voice cost calculation error: {e}")
+
+            # Track completed assistant turns and snapshot cumulative usage at turn boundary
+            if event_type == "bidi_response_complete":
+                self._per_turn_usage.append(self._accumulated_usage.copy())
+                self._turn_count += 1
+                logger.info(f"Voice turn {self._turn_count} complete, cumulative usage: {self._accumulated_usage}")
+
+            yield event_dict
+
+    async def stream_async(
+        self, message: str, session_id: Optional[str] = None, files: Optional[List] = None, citations: Optional[List] = None, original_message: Optional[str] = None
+    ) -> AsyncGenerator[str, None]:
+        """
+        BaseAgent interface compatibility — not used for voice mode.
+
+        Voice mode uses start() + send_audio()/send_text() + receive_events() + stop()
+        instead of the request-response stream_async() pattern.
+        """
+        logger.warning("stream_async() called on VoiceAgent — use receive_events() instead")
+        return
+        yield  # Make this a generator
+
+    async def drain_remaining_events(self, timeout: float = 3.0) -> None:
+        """Drain remaining events from BidiAgent to capture final usage data.
+
+        After stop() is called, the BidiAgent may still have queued events
+        (especially bidi_usage) that were not consumed because the
+        _send_to_client task was cancelled on client disconnect. This method
+        consumes those remaining events with a timeout to ensure accumulated
+        usage totals are complete before finalization.
+        """
+        if not self._bidi_agent:
+            return
+        try:
+            async with asyncio.timeout(timeout):
+                async for event in self._bidi_agent.receive():
+                    if hasattr(event, "as_dict"):
+                        event_dict = event.as_dict()
+                    else:
+                        continue
+                    event_type = event_dict.get("type", "")
+                    if event_type == "bidi_usage":
+                        usage = event_dict.get("usage", event_dict)
+                        for key in ("inputTokens", "outputTokens", "totalTokens"):
+                            self._accumulated_usage[key] = usage.get(key, self._accumulated_usage[key])
+                        logger.info(f"Drained bidi_usage: {usage}, current: {self._accumulated_usage}")
+                    elif event_type == "bidi_response_complete":
+                        self._per_turn_usage.append(self._accumulated_usage.copy())
+                        self._turn_count += 1
+                        logger.info(f"Drained turn {self._turn_count} complete")
+        except (TimeoutError, asyncio.CancelledError, StopAsyncIteration):
+            pass
+        except Exception as e:
+            logger.debug(f"Event drain ended: {e}")
+
+    async def stop(self) -> None:
+        """Stop the bidirectional voice connection.
+
+        Handles CancelledError from the BidiAgent's internal stream teardown
+        gracefully — the Nova Sonic SDK may cancel pending futures during
+        shutdown, which is expected and not an error.
+        """
+        if self._bidi_agent and hasattr(self._bidi_agent, "stop"):
+            try:
+                await self._bidi_agent.stop()
+            except asyncio.CancelledError:
+                logger.debug("BidiAgent stop cancelled (expected during teardown)")
+            except Exception as e:
+                logger.warning(f"Error during BidiAgent stop: {e}")
+        logger.info(f"Voice agent stopped. Final accumulated_usage: {self._accumulated_usage}")
diff --git a/backend/src/apis/app_api/costs/aggregator.py b/backend/src/apis/app_api/costs/aggregator.py
index 6068ad3c..c3aa861b 100644
--- a/backend/src/apis/app_api/costs/aggregator.py
+++ b/backend/src/apis/app_api/costs/aggregator.py
@@ -167,8 +167,12 @@ async def get_detailed_cost_report(
         model_stats = {}
 
         for message in messages:
-            # Extract cost and tokens
-            cost = float(message.get("cost", 0.0))
+            # Extract cost and tokens (cost may be a float or a breakdown dict)
+            raw_cost = message.get("cost", 0.0)
+            if isinstance(raw_cost, dict):
+                cost = float(raw_cost.get("total", 0.0))
+            else:
+                cost = float(raw_cost or 0.0)
             total_cost += cost
 
             input_tokens = message.get("inputTokens", 0)
diff --git a/backend/src/apis/app_api/messages/models.py b/backend/src/apis/app_api/messages/models.py
index 8269a233..a42f7326 100644
--- a/backend/src/apis/app_api/messages/models.py
+++ b/backend/src/apis/app_api/messages/models.py
@@ -1,6 +1,6 @@
 """Messages API models"""
 
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -115,7 +115,7 @@ class MessageMetadata(BaseModel):
     token_usage: Optional[TokenUsage] = Field(None, alias="tokenUsage", description="Token usage statistics")
     model_info: Optional[ModelInfo] = Field(None, alias="modelInfo", description="Model information for cost tracking")
     attribution: Optional[Attribution] = Field(None, description="Attribution for cost tracking and billing")
-    cost: Optional[float] = Field(None, description="Total cost in USD for this message (computed from token usage and pricing)")
+    cost: Optional[Union[float, Dict[str, float]]] = Field(None, description="Cost for this message — either a total float (legacy) or a breakdown dict with total, inputCost, outputCost, cacheReadCost, cacheWriteCost")
     citations: Optional[List[Dict[str, str]]] = Field(None, description="RAG citations for this message (stored as dicts for flexible JSON storage)")
     display_text: Optional[str] = Field(None, alias="displayText", description="Original user message text before RAG augmentation (for clean UI display)")
     # Note: Feedback will be added in future implementation
diff --git a/backend/src/apis/app_api/sessions/services/metadata.py b/backend/src/apis/app_api/sessions/services/metadata.py
index 7c372a03..2414e79d 100644
--- a/backend/src/apis/app_api/sessions/services/metadata.py
+++ b/backend/src/apis/app_api/sessions/services/metadata.py
@@ -11,7 +11,7 @@
 import json
 import os
 import base64
-from typing import Optional, Tuple, Any, Dict
+from typing import Optional, Tuple, Any, Dict, Union
 from decimal import Decimal
 
 from apis.shared.sessions.models import MessageMetadata, SessionMetadata
@@ -54,7 +54,7 @@ def _convert_decimal_to_float(obj: Any) -> Any:
 async def store_message_metadata(
     session_id: str,
     user_id: str,
-    message_id: int,
+    message_id: Union[int, str],
     message_metadata: MessageMetadata
 ) -> None:
     """
@@ -65,7 +65,7 @@ async def store_message_metadata(
     Args:
         session_id: Session identifier
         user_id: User identifier
-        message_id: Message number (1, 2, 3, ...)
+        message_id: Message index or namespaced key (e.g. 1 for default, "voice:1" for voice)
         message_metadata: MessageMetadata object to store
 
     Note:
@@ -88,7 +88,7 @@ async def store_message_metadata(
 async def _store_message_metadata_cloud(
     session_id: str,
     user_id: str,
-    message_id: int,
+    message_id: Union[int, str],
     message_metadata: MessageMetadata,
     table_name: str
 ) -> None:
@@ -224,8 +224,12 @@ async def _update_cost_summary_async(
         import asyncio
         from datetime import datetime
 
-        # Extract cost and usage from metadata
-        cost = message_metadata.cost or 0.0
+        # Extract cost from metadata — may be a float (legacy) or a breakdown dict
+        raw_cost = message_metadata.cost
+        if isinstance(raw_cost, dict):
+            cost = raw_cost.get("total", 0.0)
+        else:
+            cost = raw_cost or 0.0
         token_usage = message_metadata.token_usage
 
         usage_delta = {}
diff --git a/backend/src/apis/app_api/sessions/tests/test_cache_savings.py b/backend/src/apis/app_api/sessions/tests/test_cache_savings.py
index 519084db..dcb8b16d 100644
--- a/backend/src/apis/app_api/sessions/tests/test_cache_savings.py
+++ b/backend/src/apis/app_api/sessions/tests/test_cache_savings.py
@@ -73,7 +73,7 @@ def sample_message_metadata(self, sample_token_usage_with_cache, sample_model_in
     async def test_cache_savings_calculation(self, mock_storage, sample_message_metadata):
         """Test that cache savings are calculated correctly"""
         with patch(
-            'apis.app_api.storage.metadata_storage.get_metadata_storage',
+            'apis.app_api.storage.get_metadata_storage',
             return_value=mock_storage
         ):
             from apis.app_api.sessions.services.metadata import _update_cost_summary_async
@@ -138,7 +138,7 @@ async def test_cache_savings_zero_when_no_cache_reads(self, mock_storage):
         )
 
         with patch(
-            'apis.app_api.storage.metadata_storage.get_metadata_storage',
+            'apis.app_api.storage.get_metadata_storage',
             return_value=mock_storage
         ):
             from apis.app_api.sessions.services.metadata import _update_cost_summary_async
@@ -180,7 +180,7 @@ async def test_cache_savings_zero_when_no_pricing_snapshot(self, mock_storage):
         )
 
         with patch(
-            'apis.app_api.storage.metadata_storage.get_metadata_storage',
+            'apis.app_api.storage.get_metadata_storage',
             return_value=mock_storage
         ):
             from apis.app_api.sessions.services.metadata import _update_cost_summary_async
@@ -230,7 +230,7 @@ async def test_cache_savings_large_cache_hit(self, mock_storage):
         )
 
         with patch(
-            'apis.app_api.storage.metadata_storage.get_metadata_storage',
+            'apis.app_api.storage.get_metadata_storage',
             return_value=mock_storage
         ):
             from apis.app_api.sessions.services.metadata import _update_cost_summary_async
@@ -287,7 +287,7 @@ async def test_cache_savings_with_haiku_pricing(self, mock_storage):
         )
 
         with patch(
-            'apis.app_api.storage.metadata_storage.get_metadata_storage',
+            'apis.app_api.storage.get_metadata_storage',
             return_value=mock_storage
         ):
             from apis.app_api.sessions.services.metadata import _update_cost_summary_async
diff --git a/backend/src/apis/inference_api/chat/voice_routes.py b/backend/src/apis/inference_api/chat/voice_routes.py
new file mode 100644
index 00000000..bef70709
--- /dev/null
+++ b/backend/src/apis/inference_api/chat/voice_routes.py
@@ -0,0 +1,576 @@
+"""
+WebSocket voice route for bidirectional speech-to-speech interaction.
+
+Exposes VoiceAgent via WebSocket for real-time audio streaming with
+AWS Nova Sonic 2. Adapted from the sample-strands-agent-with-agentcore
+voice router pattern.
+
+Protocol:
+    Client → Server:
+        {"type": "config", "session_id": "...", "auth_token": "...", ...}  (first message)
+        {"type": "bidi_audio_input", "audio": "<base64>", "sample_rate": 16000}
+        {"type": "bidi_text_input", "text": "..."}
+        {"type": "ping"}
+        {"type": "stop"}
+
+    Server → Client:
+        {"type": "bidi_connection_start", "connection_id": "...", "status": "connected"}
+        {"type": "bidi_error", "message": "..."}
+        Agent stream events (audio, transcripts, tool use, etc.)
+"""
+
+import asyncio
+import json
+import jwt
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from apis.shared.sessions.metadata import get_session_metadata, store_session_metadata
+from apis.shared.sessions.models import SessionMetadata
+
+logger = logging.getLogger(__name__)
+
+
+def _sanitize_log(value: str) -> str:
+    """Strip newlines and carriage returns to prevent log injection."""
+    return str(value).replace("\n", "").replace("\r", "")
+
+router = APIRouter(tags=["voice"])
+
+# Track active voice sessions for debugging
+_active_sessions: Dict[str, Any] = {}
+
+# Lazy import to avoid loading bidi deps at module level
+_VoiceAgentClass = None
+
+
+def _get_voice_agent_class():
+    """Lazily import VoiceAgent to avoid import errors when bidi not installed."""
+    global _VoiceAgentClass
+    if _VoiceAgentClass is None:
+        from agents.main_agent.voice_agent import VoiceAgent
+        _VoiceAgentClass = VoiceAgent
+    return _VoiceAgentClass
+
+
+def _extract_user_from_token(token: str) -> Optional[Dict[str, str]]:
+    """
+    Extract user claims from JWT token (trusted — no signature verification).
+
+    Same pattern as get_current_user_trusted in auth/dependencies.py.
+    WebSocket connections can't use Depends() so we handle auth manually.
+    """
+    if not token:
+        return None
+
+    try:
+        payload = jwt.decode(token, options={"verify_signature": False})
+        user_id = payload.get("sub")
+        if not user_id:
+            return None
+        return {
+            "user_id": str(user_id),
+            "email": payload.get("email") or payload.get("preferred_username") or "",
+            "raw_token": token,
+        }
+    except jwt.DecodeError as e:
+        logger.warning(f"Failed to decode voice auth token: {e}")
+        return None
+
+
+async def _ensure_session_metadata(session_id: str, user_id: str) -> None:
+    """Create session metadata entry if one doesn't already exist.
+
+    This makes the voice session visible in the conversations side nav.
+    If the session started as a text chat, existing metadata is preserved.
+    """
+    try:
+        existing = await get_session_metadata(session_id, user_id)
+        if existing:
+            logger.debug(f"Session metadata already exists for {_sanitize_log(session_id)}")
+            return
+
+        now = datetime.now(timezone.utc).isoformat()
+        metadata = SessionMetadata(
+            session_id=session_id,
+            user_id=user_id,
+            title="Voice Conversation",
+            status="active",
+            created_at=now,
+            last_message_at=now,
+            message_count=0,
+            starred=False,
+            tags=[],
+            preferences=None,
+        )
+        await store_session_metadata(session_id=session_id, user_id=user_id, session_metadata=metadata)
+        logger.info(f"Created session metadata for voice session {_sanitize_log(session_id)}")
+    except Exception as e:
+        logger.error(f"Failed to create session metadata for {_sanitize_log(session_id)}: {e}", exc_info=True)
+
+
+async def _finalize_voice_session(session_id: str, user_id: str, voice_agent: Any) -> None:
+    """Update session metadata and store cost/token data after voice session ends.
+
+    Called in the finally block of voice_stream to persist usage metrics.
+    """
+    # Use response_start_count as fallback when turns are interrupted before completion
+    completed_turns = getattr(voice_agent, "turn_count", 0)
+    started_turns = getattr(voice_agent, "response_start_count", 0)
+    effective_turns = max(completed_turns, started_turns)
+
+    logger.info(
+        f"Finalizing voice session {_sanitize_log(session_id)}: "
+        f"completed_turns={completed_turns}, started_turns={started_turns}, "
+        f"effective_turns={effective_turns}, "
+        f"accumulated_usage={getattr(voice_agent, 'accumulated_usage', 'N/A')}, "
+        f"per_turn_usage_count={len(getattr(voice_agent, 'per_turn_usage', []))}"
+    )
+    try:
+        # Update session metadata with final turn count
+        existing = await get_session_metadata(session_id, user_id)
+        if existing:
+            now = datetime.now(timezone.utc).isoformat()
+            updated = SessionMetadata(
+                session_id=session_id,
+                user_id=user_id,
+                title=existing.title,
+                status=existing.status,
+                created_at=existing.created_at,
+                last_message_at=now,
+                message_count=existing.message_count + effective_turns,
+                starred=existing.starred,
+                tags=existing.tags,
+                preferences=existing.preferences,
+            )
+            await store_session_metadata(session_id=session_id, user_id=user_id, session_metadata=updated)
+            logger.info(f"Updated voice session metadata: turns={effective_turns}, session={_sanitize_log(session_id)}")
+    except Exception as e:
+        logger.error(f"Failed to update session metadata for {_sanitize_log(session_id)}: {e}", exc_info=True)
+
+    # Store metadata for each assistant message in the voice session.
+    # BidiAgent may split responses into multiple messages, so we can't assume
+    # a strict user/assistant alternating pattern. Instead, read the actual messages
+    # from AgentCore Memory and find which indices are assistant messages.
+    try:
+        import asyncio
+        from agents.main_agent.config.constants import Defaults
+
+        accumulated_usage = getattr(voice_agent, "accumulated_usage", {})
+        has_usage = (accumulated_usage.get("inputTokens", 0) + accumulated_usage.get("outputTokens", 0)) > 0
+
+        if not has_usage:
+            logger.info(f"No voice usage to record metadata for session {_sanitize_log(session_id)}")
+            return
+
+        from apis.app_api.messages.models import Attribution, MessageMetadata, ModelInfo, TokenUsage
+        from apis.app_api.sessions.services.metadata import store_message_metadata
+
+        model_id = getattr(voice_agent, "voice_model_id", "amazon.nova-2-sonic-v1:0")
+        model_info = ModelInfo(
+            model_id=model_id,
+            model_name="Nova Sonic 2",
+            provider="bedrock",
+        )
+
+        # Read actual messages from AgentCore Memory to find assistant indices
+        assistant_indices = []
+        try:
+            session_manager = voice_agent.session_manager
+            if hasattr(session_manager, "list_messages"):
+                messages = await asyncio.to_thread(
+                    session_manager.list_messages,
+                    session_id,
+                    Defaults.VOICE_AGENT_ID,
+                )
+                for idx, msg in enumerate(messages or []):
+                    inner = getattr(msg, "message", msg)
+                    role = inner.get("role") if isinstance(inner, dict) else getattr(inner, "role", None)
+                    if role == "assistant":
+                        assistant_indices.append(idx)
+                logger.info(f"Voice session messages: {len(messages or [])} total, assistant at indices {assistant_indices}")
+        except Exception as msg_err:
+            logger.warning(f"Could not read voice messages for metadata: {msg_err}")
+
+        if not assistant_indices:
+            # Fallback: store a single record at index 1 (most common position)
+            assistant_indices = [1]
+            logger.info("No assistant messages found, using fallback index [1]")
+
+        # Get pricing
+        pricing = None
+        try:
+            from apis.app_api.costs.calculator import CostCalculator
+            from apis.app_api.costs.pricing_config import get_model_pricing
+
+            pricing = await get_model_pricing(model_id)
+        except Exception as cost_err:
+            logger.debug(f"Cost calculation unavailable for voice: {cost_err}")
+
+        # Store cumulative session usage on the LAST assistant message only.
+        # Nova Sonic reports cumulative totals for the whole connection, so
+        # splitting across messages would be misleading. The last message
+        # carries the full session cost; earlier messages get no badge.
+        last_idx = assistant_indices[-1]
+        input_tokens = accumulated_usage.get("inputTokens", 0)
+        output_tokens = accumulated_usage.get("outputTokens", 0)
+        total_tokens = input_tokens + output_tokens
+
+        token_usage = TokenUsage(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=total_tokens,
+        )
+
+        attribution = Attribution(
+            user_id=user_id,
+            session_id=session_id,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+
+        cost = None
+        if pricing and total_tokens > 0:
+            try:
+                total_cost, breakdown = CostCalculator.calculate_message_cost(accumulated_usage, pricing)
+                cost = {
+                    "total": total_cost,
+                    "inputCost": breakdown.input_cost,
+                    "outputCost": breakdown.output_cost,
+                    "cacheReadCost": breakdown.cache_read_cost,
+                    "cacheWriteCost": breakdown.cache_write_cost,
+                }
+            except Exception:
+                pass
+
+        message_metadata = MessageMetadata(
+            token_usage=token_usage,
+            model_info=model_info,
+            attribution=attribution,
+            cost=cost,
+        )
+
+        await store_message_metadata(
+            session_id=session_id,
+            user_id=user_id,
+            message_id=f"voice:{last_idx}",
+            message_metadata=message_metadata,
+        )
+
+        logger.info(
+            f"Stored voice metadata on last assistant message (index {last_idx}), "
+            f"usage={accumulated_usage}, session={_sanitize_log(session_id)}"
+        )
+    except Exception as e:
+        logger.error(f"Failed to store voice cost metadata for {_sanitize_log(session_id)}: {e}", exc_info=True)
+
+
+def _get_param_from_request(websocket: WebSocket, header_suffix: str, query_param: Optional[str]) -> Optional[str]:
+    """Extract param from AgentCore custom header (cloud) or query param (local)."""
+    header_name = f"x-amzn-bedrock-agentcore-runtime-custom-{header_suffix}"
+    custom_header = websocket.headers.get(header_name)
+    if custom_header:
+        return custom_header
+    return query_param
+
+
+def _get_enabled_tools_from_request(websocket: WebSocket, query_param: Optional[str]) -> Optional[list]:
+    """Extract enabled_tools from AgentCore custom header or query param."""
+    tools_json = _get_param_from_request(websocket, "enabled-tools", query_param)
+    if not tools_json:
+        return None
+    try:
+        return json.loads(tools_json)
+    except json.JSONDecodeError as e:
+        logger.warning(f"Invalid enabled_tools JSON: {_sanitize_log(str(e))}")
+        return None
+
+
+@router.websocket("/voice/stream")
+async def voice_stream(
+    websocket: WebSocket,
+    session_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    enabled_tools: Optional[str] = None,
+    token: Optional[str] = None,
+):
+    """
+    Bidirectional voice streaming endpoint.
+
+    Supports two connection modes:
+
+    **AgentCore (deployed):** Browser connects via
+    ``wss://bedrock-agentcore.<region>.amazonaws.com/runtimes/<ARN>/ws``.
+    Auth is handled by AgentCore's JWT Authorizer at the proxy layer.
+    The bearer token for user-claim extraction arrives in the first
+    ``config`` message sent by the client after connection opens.
+
+    **Local dev:** Browser connects directly to
+    ``ws://localhost:8001/voice/stream``. Session ID and token are
+    plain query params; the config message supplements them.
+    """
+    # Accept immediately — AgentCore validates auth at the proxy layer;
+    # user claims are extracted from the config message after accept.
+    await websocket.accept()
+
+    # Resolve params: AgentCore custom header → query param → default
+    session_id = _get_param_from_request(websocket, "session-id", session_id)
+    user_id = _get_param_from_request(websocket, "user-id", user_id)
+    enabled_tools_list = _get_enabled_tools_from_request(websocket, enabled_tools)
+    auth_token = _get_param_from_request(websocket, "auth-token", token) or ""
+
+    # Always read config message from client (sent on WebSocket open).
+    # Required for auth_token in AgentCore mode and supplements any
+    # missing params (AgentCore proxy may not forward all query params).
+    try:
+        first_msg = await asyncio.wait_for(
+            websocket.receive_json(), timeout=10.0
+        )
+        if first_msg.get("type") == "config":
+            session_id = first_msg.get("session_id") or session_id
+            user_id = first_msg.get("user_id") or user_id
+            enabled_tools_list = first_msg.get("enabled_tools") or enabled_tools_list
+            auth_token = first_msg.get("auth_token") or auth_token
+            logger.info(f"Voice config received from client message")
+    except asyncio.TimeoutError:
+        logger.warning("No config message received within 10s, using query params")
+    except Exception as e:
+        logger.warning(f"Error reading config message: {e}")
+
+    # Generate session_id if not provided by any source
+    if not session_id:
+        session_id = str(uuid.uuid4())
+        logger.info(f"Generated new voice session ID: {_sanitize_log(session_id)}")
+
+    # Extract user from token (query param or config message)
+    if not user_id and auth_token:
+        user_info = _extract_user_from_token(auth_token)
+        if user_info:
+            user_id = user_info["user_id"]
+
+    if not user_id:
+        await websocket.send_json({"type": "bidi_error", "message": "Authentication required"})
+        await websocket.close(code=4001, reason="Authentication required")
+        return
+
+    logger.info(
+        f"Voice WebSocket connected: session={_sanitize_log(session_id)}, "
+        f"user={_sanitize_log(user_id)}, tools={len(enabled_tools_list or [])}, "
+        f"auth_token={'present' if auth_token else 'missing'}"
+    )
+
+    voice_agent = None
+
+    try:
+        # Create VoiceAgent
+        VoiceAgent = _get_voice_agent_class()
+        voice_agent = VoiceAgent(
+            session_id=session_id,
+            user_id=user_id,
+            auth_token=auth_token,
+            enabled_tools=enabled_tools_list,
+        )
+
+        _active_sessions[session_id] = voice_agent
+
+        # Send connection confirmation
+        await websocket.send_json({
+            "type": "bidi_connection_start",
+            "connection_id": session_id,
+            "status": "connected",
+        })
+
+        # Start the voice agent
+        await voice_agent.start()
+
+        # Create session metadata so voice sessions appear in the side nav
+        await _ensure_session_metadata(session_id, user_id)
+
+        # Run bidirectional communication
+        receive_task = asyncio.create_task(
+            _receive_from_client(websocket, voice_agent, session_id)
+        )
+        send_task = asyncio.create_task(
+            _send_to_client(websocket, voice_agent, session_id)
+        )
+
+        done, pending = await asyncio.wait(
+            [receive_task, send_task],
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+
+        # Cancel pending tasks
+        for task in pending:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+        # Check for task exceptions
+        for task in done:
+            if task.exception():
+                logger.error(f"Voice task error: {task.exception()}")
+
+    except WebSocketDisconnect:
+        logger.info(f"Voice WebSocket disconnected: session={_sanitize_log(session_id)}")
+    except Exception as e:
+        logger.error(f"Voice stream error: {e}", exc_info=True)
+        try:
+            await websocket.send_json({
+                "type": "bidi_error",
+                "message": str(e),
+            })
+        except Exception:
+            pass
+    finally:
+        # Cleanup — catch BaseException since CancelledError escapes Exception in 3.12
+        _active_sessions.pop(session_id, None)
+        if voice_agent and user_id:
+            # 1. Stop BidiAgent first — flushes stream, emits final events including usage
+            try:
+                await voice_agent.stop()
+            except BaseException as e:
+                logger.debug(f"Voice agent stop: {type(e).__name__}: {e}")
+            # 2. Drain any remaining queued events (captures final bidi_usage
+            #    that weren't consumed because _send_to_client was cancelled)
+            try:
+                await voice_agent.drain_remaining_events(timeout=3.0)
+            except BaseException as e:
+                logger.debug(f"Voice event drain: {type(e).__name__}: {e}")
+            # 3. NOW finalize with complete accumulated usage data
+            try:
+                await _finalize_voice_session(session_id, user_id, voice_agent)
+            except BaseException as e:
+                logger.debug(f"Voice session finalization error: {type(e).__name__}: {e}")
+        try:
+            await websocket.close()
+        except BaseException:
+            pass
+        logger.info(f"Voice session cleaned up: {_sanitize_log(session_id)}")
+
+
+async def _receive_from_client(
+    websocket: WebSocket, voice_agent: Any, session_id: str
+) -> None:
+    """Receive messages from client and dispatch to voice agent."""
+    try:
+        while True:
+            msg = await websocket.receive_json()
+            msg_type = msg.get("type", "")
+
+            if msg_type == "bidi_audio_input":
+                audio = msg.get("audio", "")
+                sample_rate = msg.get("sample_rate", 16000)
+                await voice_agent.send_audio(audio, sample_rate)
+
+            elif msg_type == "bidi_text_input":
+                text = msg.get("text", "")
+                if text:
+                    await voice_agent.send_text(text)
+
+            elif msg_type == "ping":
+                await websocket.send_json({"type": "pong"})
+
+            elif msg_type == "stop":
+                logger.info(f"Client requested stop: session={_sanitize_log(session_id)}")
+                break
+
+            else:
+                logger.debug(f"Unknown message type: {_sanitize_log(msg_type)}")
+
+    except WebSocketDisconnect:
+        logger.info(f"Client disconnected (receive): session={_sanitize_log(session_id)}")
+    except asyncio.CancelledError:
+        logger.debug(f"Receive task cancelled: session={_sanitize_log(session_id)}")
+        raise
+
+
+async def _send_to_client(
+    websocket: WebSocket, voice_agent: Any, session_id: str
+) -> None:
+    """Stream events from voice agent to client.
+
+    VoiceAgent.receive_events() yields dicts from BidiAgent.receive() — each dict
+    has a 'type' field (e.g. 'bidi_audio_stream', 'bidi_transcript_stream',
+    'bidi_response_complete', etc.).
+    """
+    try:
+        async for event in voice_agent.receive_events():
+            try:
+                if isinstance(event, dict):
+                    await websocket.send_json(event)
+                else:
+                    await websocket.send_json({
+                        "type": "bidi_event",
+                        "data": str(event),
+                    })
+            except WebSocketDisconnect:
+                logger.info(f"Client disconnected during send: session={_sanitize_log(session_id)}")
+                return
+            except Exception as e:
+                logger.warning(f"Error sending event to client: {e}")
+
+    except asyncio.CancelledError:
+        logger.debug(f"Send task cancelled: session={_sanitize_log(session_id)}")
+        raise
+    except Exception as e:
+        logger.error(f"Error in send_to_client: {e}")
+
+
+# --- Debug endpoints ---
+
+@router.get("/voice/sessions")
+async def list_voice_sessions():
+    """List active voice sessions (for debugging)."""
+    return {
+        "active_sessions": list(_active_sessions.keys()),
+        "count": len(_active_sessions),
+    }
+
+
+@router.delete("/voice/sessions/{session_id}")
+async def stop_voice_session(session_id: str):
+    """Force-stop a voice session (for debugging)."""
+    agent = _active_sessions.get(session_id)
+    if not agent:
+        return {"status": "not_found", "session_id": session_id}
+
+    try:
+        await agent.stop()
+    except Exception as e:
+        logger.error(f"Error force-stopping session {_sanitize_log(session_id)}: {e}")
+
+    _active_sessions.pop(session_id, None)
+    return {"status": "stopped", "session_id": session_id}
+
+
+# =============================================================================
+# /ws alias for AgentCore Runtime
+# AgentCore Runtime routes WebSocket requests to /ws on the container.
+# This delegates to /voice/stream for cloud deployment compatibility.
+# =============================================================================
+
+@router.websocket("/ws")
+async def ws_stream(
+    websocket: WebSocket,
+    session_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    enabled_tools: Optional[str] = None,
+    token: Optional[str] = None,
+):
+    """WebSocket endpoint for AgentCore Runtime (cloud mode).
+
+    AgentCore Runtime expects containers to implement WebSocket at /ws
+    path on port 8080. This endpoint delegates to voice_stream.
+    """
+    await voice_stream(
+        websocket=websocket,
+        session_id=session_id,
+        user_id=user_id,
+        enabled_tools=enabled_tools,
+        token=token,
+    )
diff --git a/backend/src/apis/inference_api/main.py b/backend/src/apis/inference_api/main.py
index 5c095daf..de9308d0 100644
--- a/backend/src/apis/inference_api/main.py
+++ b/backend/src/apis/inference_api/main.py
@@ -131,10 +131,12 @@ async def lifespan(app: FastAPI):
 #from health.health import router as health_router
 from apis.inference_api.chat.routes import router as agentcore_router
 from apis.inference_api.chat.converse_routes import router as converse_router
+from apis.inference_api.chat.voice_routes import router as voice_router
 # Include routers
 #app.include_router(health_router)
 app.include_router(agentcore_router)  # AgentCore Runtime endpoints: /ping, /invocations
 app.include_router(converse_router)  # API-key authenticated converse endpoint
+app.include_router(voice_router)  # WebSocket voice streaming endpoint
 
 # Mount static file directories for serving generated content
 # These are created by tools (visualization, code interpreter, etc.)
diff --git a/backend/src/apis/shared/sessions/messages.py b/backend/src/apis/shared/sessions/messages.py
index 232b48c1..1ec668ab 100644
--- a/backend/src/apis/shared/sessions/messages.py
+++ b/backend/src/apis/shared/sessions/messages.py
@@ -395,7 +395,14 @@ async def get_messages_from_cloud(
         import asyncio
 
         async def fetch_messages():
-            """Fetch messages from AgentCore Memory (runs in thread pool since it's sync)"""
+            """Fetch messages from AgentCore Memory.
+
+            Note: AgentCore Memory's list_events API does not filter by
+            agent_id — it returns ALL messages for the session regardless
+            of which agent stored them.  A single fetch with any agent_id
+            is sufficient; fetching twice (e.g. "default" + "voice") would
+            return identical results and cause duplication.
+            """
             return await asyncio.to_thread(session_manager.list_messages, session_id, "default")
 
         async def fetch_metadata():
@@ -404,40 +411,40 @@ async def fetch_metadata():
 
             return await get_all_message_metadata(session_id, user_id)
 
-        # Run both fetches in parallel
-        messages_raw, metadata_index = await asyncio.gather(fetch_messages(), fetch_metadata())
+        # Run fetches in parallel
+        messages_raw, metadata_index = await asyncio.gather(
+            fetch_messages(), fetch_metadata()
+        )
+
+        messages_raw = list(messages_raw or [])
 
-        logger.info(f"AgentCore Memory returned {len(messages_raw) if messages_raw else 0} raw messages")
+        logger.info(f"AgentCore Memory returned {len(messages_raw)} raw messages")
         logger.info(f"Metadata index contains {len(metadata_index)} entries")
         logger.info(f"🔑 Metadata index keys: {sorted(metadata_index.keys())}")
 
         # Convert to our Message model
         messages = []
-        if messages_raw:
-            # DO NOT SORT - AgentCore Memory returns messages in chronological order
-            # The enumerated index matches the stored sequence number (message_id)
-            for idx, msg in enumerate(messages_raw):
-                try:
-                    # Metadata join: use index as message_id (0-based sequence)
-                    metadata = metadata_index.get(str(idx))
-
-                    # Determine message role for logging
-                    # Cost metadata only exists for assistant messages (LLM API calls)
-                    msg_role = _get_message_role(msg)
-
-                    if metadata:
-                        logger.debug(f"🔗 Joined metadata for message {idx} ({msg_role})")
-                    elif msg_role == "user":
-                        # User messages don't have cost metadata - this is expected
-                        logger.debug(f"📝 User message {idx} - no cost metadata (expected)")
-                    else:
-                        # Assistant message without metadata is unexpected
-                        logger.warning(f"⚠️ No metadata found for assistant message {idx}")
-
-                    messages.append(_convert_message(msg, metadata=metadata))
-                except Exception as e:
-                    logger.error(f"Error converting message {idx}: {e}", exc_info=True)
-                    continue
+        for idx, msg in enumerate(messages_raw):
+            try:
+                # Look up metadata: try plain index first (text chat),
+                # then "voice:<idx>" prefix (voice chat metadata).
+                metadata = metadata_index.get(str(idx))
+                if metadata is None:
+                    metadata = metadata_index.get(f"voice:{idx}")
+
+                msg_role = _get_message_role(msg)
+
+                if metadata:
+                    logger.debug(f"🔗 Joined metadata for message {idx} ({msg_role})")
+                elif msg_role == "user":
+                    logger.debug(f"📝 User message {idx} - no cost metadata (expected)")
+                else:
+                    logger.warning(f"⚠️ No metadata found for assistant message {idx}")
+
+                messages.append(_convert_message(msg, metadata=metadata))
+            except Exception as e:
+                logger.error(f"Error converting message {idx}: {e}", exc_info=True)
+                continue
 
         logger.info(f"Retrieved {len(messages)} messages from AgentCore Memory with metadata")
 
diff --git a/backend/src/apis/shared/sessions/models.py b/backend/src/apis/shared/sessions/models.py
index d92dc9e7..d684b6c5 100644
--- a/backend/src/apis/shared/sessions/models.py
+++ b/backend/src/apis/shared/sessions/models.py
@@ -6,7 +6,7 @@
 - Session preferences and configuration
 """
 
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -260,7 +260,7 @@ class MessageMetadata(BaseModel):
     token_usage: Optional[TokenUsage] = Field(None, alias="tokenUsage", description="Token usage statistics")
     model_info: Optional[ModelInfo] = Field(None, alias="modelInfo", description="Model information for cost tracking")
     attribution: Optional[Attribution] = Field(None, description="Attribution for cost tracking and billing")
-    cost: Optional[float] = Field(None, description="Total cost in USD for this message (computed from token usage and pricing)")
+    cost: Optional[Union[float, Dict[str, float]]] = Field(None, description="Cost for this message — either a total float (legacy) or a breakdown dict with total, inputCost, outputCost, cacheReadCost, cacheWriteCost")
     citations: Optional[List[Dict[str, str]]] = Field(None, description="RAG citations for this message (stored as dicts for flexible JSON storage)")
     display_text: Optional[str] = Field(None, alias="displayText", description="Original user message text before RAG augmentation (for clean UI display)")
     # Note: Feedback will be added in future implementation
diff --git a/backend/tests/agents/main_agent/session/conftest.py b/backend/tests/agents/main_agent/session/conftest.py
index 25e12614..57aa832e 100644
--- a/backend/tests/agents/main_agent/session/conftest.py
+++ b/backend/tests/agents/main_agent/session/conftest.py
@@ -223,11 +223,16 @@ def _init(self, agentcore_memory_config=None, region_name=None, **kwargs):
 def make_session_manager(mock_agentcore_config):
     """
     Factory fixture — returns a callable that creates a TurnBasedSessionManager
-    with AgentCoreMemorySessionManager.__init__ mocked out so no AWS calls are made.
+    with AgentCoreMemorySessionManager.__init__ and .initialize() mocked out
+    so no AWS calls are made.
 
-    The resulting manager inherits all TurnBasedSessionManager methods and has
-    the parent's required attributes set via the mock __init__.
+    The parent's initialize() is replaced with a shim that simulates the SDK
+    behavior: read the agent, load messages from list_messages(), and populate
+    agent.messages. This allows tests to control the loaded messages by setting
+    mgr.read_agent and mgr.list_messages before calling mgr.initialize(agent).
     """
+    active_patches = []
+
     def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs):
         from bedrock_agentcore.memory.integrations.strands.session_manager import (
             AgentCoreMemorySessionManager,
@@ -238,6 +243,29 @@ def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs):
         TurnBasedSessionManager._dynamodb_table = None
         TurnBasedSessionManager._dynamodb_table_name = None
 
+        _initialized_agent_ids = set()
+
+        def _mock_sdk_initialize(self_inner, agent, **kw):
+            """Simulate what the SDK's initialize() does: load messages into agent."""
+            from strands.types.exceptions import SessionException
+
+            # SDK tracks agent_ids and raises on duplicate
+            if agent.agent_id in _initialized_agent_ids:
+                raise SessionException(f"Agent ID must be unique: {agent.agent_id}")
+            _initialized_agent_ids.add(agent.agent_id)
+
+            session_agent = self_inner.read_agent(agent.agent_id)
+            if session_agent is None:
+                self_inner.create_agent(agent.agent_id)
+            else:
+                session_messages = self_inner.list_messages(agent.agent_id)
+                loaded = [sm.to_message() for sm in session_messages]
+                agent.messages = loaded
+
+            # SDK always sets these after initialization
+            self_inner.has_existing_agent = True
+            self_inner._is_new_session = False
+
         with patch.object(
             AgentCoreMemorySessionManager,
             "__init__",
@@ -251,6 +279,16 @@ def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs):
                 **kwargs,
             )
 
+        # Patch the parent's initialize so super().initialize() uses our shim.
+        # Keep the patch active for the lifetime of the test.
+        p = patch.object(
+            AgentCoreMemorySessionManager,
+            "initialize",
+            _mock_sdk_initialize,
+        )
+        p.start()
+        active_patches.append(p)
+
         # Set up mock methods for session repository operations
         # (These are inherited from AgentCoreMemorySessionManager and called via self)
         mgr.read_agent = MagicMock(return_value=None)
@@ -260,4 +298,9 @@ def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs):
 
         return mgr
 
-    return _factory
+    yield _factory
+
+    # Cleanup: stop all patches started during this fixture's lifetime
+    for p in active_patches:
+        p.stop()
+    active_patches.clear()
diff --git a/backend/tests/agents/main_agent/session/test_tool_approval.py b/backend/tests/agents/main_agent/session/test_tool_approval.py
new file mode 100644
index 00000000..e13305a6
--- /dev/null
+++ b/backend/tests/agents/main_agent/session/test_tool_approval.py
@@ -0,0 +1,106 @@
+"""Tests for tool approval hooks."""
+
+import pytest
+from unittest.mock import MagicMock
+
+from agents.main_agent.session.hooks.tool_approval import (
+    ToolApprovalHook,
+    EmailApprovalHook,
+    ExternalWriteApprovalHook,
+    DangerousToolApprovalHook,
+)
+
+
+def _make_event(tool_name: str):
+    """Create a mock BeforeToolCallEvent."""
+    event = MagicMock()
+    event.tool_use = {"name": tool_name}
+    return event
+
+
+class TestEmailApprovalHook:
+    """Req AH-1: Email operations require approval."""
+
+    def test_send_email_flagged(self):
+        hook = EmailApprovalHook()
+        event = _make_event("send_email")
+        hook.check_approval(event)
+        assert event.tool_use.get("_approval_required") is True
+
+    def test_delete_emails_flagged(self):
+        hook = EmailApprovalHook()
+        event = _make_event("delete_emails")
+        hook.check_approval(event)
+        assert event.tool_use.get("_approval_required") is True
+
+    def test_read_email_not_flagged(self):
+        hook = EmailApprovalHook()
+        event = _make_event("read_email")
+        hook.check_approval(event)
+        assert "_approval_required" not in event.tool_use
+
+    def test_approval_message_set(self):
+        hook = EmailApprovalHook()
+        event = _make_event("send_email")
+        hook.check_approval(event)
+        assert "email operation" in event.tool_use["_approval_message"]
+
+
+class TestExternalWriteApprovalHook:
+    """Req AH-2: External system writes require approval."""
+
+    def test_create_pr_flagged(self):
+        hook = ExternalWriteApprovalHook()
+        event = _make_event("create_pull_request")
+        hook.check_approval(event)
+        assert event.tool_use.get("_approval_required") is True
+
+    def test_deploy_flagged(self):
+        hook = ExternalWriteApprovalHook()
+        event = _make_event("deploy")
+        hook.check_approval(event)
+        assert event.tool_use.get("_approval_required") is True
+
+    def test_list_repos_not_flagged(self):
+        hook = ExternalWriteApprovalHook()
+        event = _make_event("list_repositories")
+        hook.check_approval(event)
+        assert "_approval_required" not in event.tool_use
+
+
+class TestDangerousToolApprovalHook:
+    """Req AH-3: Irreversible operations require approval."""
+
+    def test_delete_file_flagged(self):
+        hook = DangerousToolApprovalHook()
+        event = _make_event("delete_file")
+        hook.check_approval(event)
+        assert event.tool_use.get("_approval_required") is True
+
+    def test_execute_sql_flagged(self):
+        hook = DangerousToolApprovalHook()
+        event = _make_event("execute_sql")
+        hook.check_approval(event)
+        assert event.tool_use.get("_approval_required") is True
+
+    def test_calculator_not_flagged(self):
+        hook = DangerousToolApprovalHook()
+        event = _make_event("calculator")
+        hook.check_approval(event)
+        assert "_approval_required" not in event.tool_use
+
+
+class TestToolApprovalHookBase:
+    """Req AH-4: Base hook class behavior."""
+
+    def test_empty_tool_names_flags_nothing(self):
+        hook = ToolApprovalHook()
+        event = _make_event("anything")
+        hook.check_approval(event)
+        assert "_approval_required" not in event.tool_use
+
+    def test_register_hooks_adds_callback(self):
+        hook = EmailApprovalHook()
+        registry = MagicMock()
+        hook.register_hooks(registry)
+        registry.add_callback.assert_called_once()
diff --git a/backend/tests/agents/main_agent/skills/__init__.py b/backend/tests/agents/main_agent/skills/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/backend/tests/agents/main_agent/skills/conftest.py b/backend/tests/agents/main_agent/skills/conftest.py
new file mode 100644
index 00000000..7a24a0c0
--- /dev/null
+++ b/backend/tests/agents/main_agent/skills/conftest.py
@@ -0,0 +1,91 @@
+"""Shared fixtures for skill tests."""
+
+import os
+import pytest
+import tempfile
+
+from agents.main_agent.skills.skill_registry import SkillRegistry
+
+
+@pytest.fixture
+def temp_skills_dir(tmp_path):
+    """Create a temporary skills directory with sample SKILL.md files."""
+    # Create web-search skill
+    web_dir = tmp_path / "web-search"
+    web_dir.mkdir()
+    (web_dir / "SKILL.md").write_text(
+        '---\n'
+        'name: web-search\n'
+        'description: Search the web for current information\n'
+        'type: tool\n'
+        '---\n'
+        '\n'
+        '# Web Search\n'
+        '\n'
+        'Use this skill to search the web.\n'
+    )
+
+    # Create visualization skill
+    viz_dir = tmp_path / "visualization"
+    viz_dir.mkdir()
+    (viz_dir / "SKILL.md").write_text(
+        '---\n'
+        'name: visualization\n'
+        'description: Create charts and graphs\n'
+        'type: tool\n'
+        '---\n'
+        '\n'
+        '# Visualization\n'
+        '\n'
+        'Create data visualizations.\n'
+    )
+
+    # Create composite skill
+    comp_dir = tmp_path / "data-analysis"
+    comp_dir.mkdir()
+    (comp_dir / "SKILL.md").write_text(
+        '---\n'
+        'name: data-analysis\n'
+        'description: Analyze data with search and visualization\n'
+        'type: composite\n'
+        'compose:\n'
+        '  - web-search\n'
+        '  - visualization\n'
+        '---\n'
+        '\n'
+        '# Data Analysis\n'
+        '\n'
+        'Combined data analysis skill.\n'
+    )
+
+    return str(tmp_path)
+
+
+@pytest.fixture
+def registry(temp_skills_dir):
+    """Create a SkillRegistry with discovered skills."""
+    reg = SkillRegistry(temp_skills_dir)
+    reg.discover_skills()
+    return reg
+
+
+@pytest.fixture
+def mock_tool():
+    """Create a mock tool with _skill_name metadata."""
+    def web_search_tool(query: str) -> str:
+        return f"Results for: {query}"
+    web_search_tool.tool_name = "web_search"
+    web_search_tool._skill_name = "web-search"
+    web_search_tool.tool_spec = {"name": "web_search", "description": "Search the web", "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}}}}
+    return web_search_tool
+
+
+@pytest.fixture
+def viz_tool():
+    """Create a mock visualization tool."""
+    def create_chart(data: dict) -> str:
+        return "chart created"
+    create_chart.tool_name = "create_chart"
+    create_chart._skill_name = "visualization"
+    create_chart.tool_spec = {"name": "create_chart", "description": "Create a chart"}
+    return create_chart
diff --git a/backend/tests/agents/main_agent/skills/test_skill_registry.py b/backend/tests/agents/main_agent/skills/test_skill_registry.py
new file mode 100644
index 00000000..44348705
--- /dev/null
+++ b/backend/tests/agents/main_agent/skills/test_skill_registry.py
@@ -0,0 +1,141 @@
+"""Tests for SkillRegistry — discovery, binding, and three-level access."""
+
+import pytest
+from agents.main_agent.skills.skill_registry import SkillRegistry
+
+
+class TestDiscovery:
+    """Req SK-1: Skill discovery from SKILL.md files."""
+
+    def test_discovers_all_skills(self, registry):
+        assert registry.get_skill_count() == 3
+
+    def test_discovers_skill_names(self, registry):
+        names = sorted(registry.get_skill_names())
+        assert names == ["data-analysis", "visualization", "web-search"]
+
+    def test_empty_directory_returns_zero(self, tmp_path):
+        reg = SkillRegistry(str(tmp_path))
+        assert reg.discover_skills() == 0
+
+    def test_nonexistent_directory_returns_zero(self):
+        reg = SkillRegistry("/nonexistent/path")
+        assert reg.discover_skills() == 0
+
+    def test_has_skill_true(self, registry):
+        assert registry.has_skill("web-search") is True
+
+    def test_has_skill_false(self, registry):
+        assert registry.has_skill("nonexistent") is False
+
+
+class TestFrontmatterParsing:
+    """Req SK-2: YAML frontmatter parsing without PyYAML."""
+
+    def test_parses_name(self, registry):
+        assert registry.has_skill("web-search")
+
+    def test_parses_composite_compose_list(self, registry):
+        skills = registry._skills
+        assert "data-analysis" in skills
+        assert skills["data-analysis"]["compose"] == ["web-search", "visualization"]
+
+    def test_parses_type(self, registry):
+        assert registry._skills["web-search"]["type"] == "tool"
+        assert registry._skills["data-analysis"]["type"] == "composite"
+
+    def test_parses_description(self, registry):
+        assert registry._skills["web-search"]["description"] == "Search the web for current information"
+
+    def test_no_frontmatter_returns_empty(self):
+        result = SkillRegistry._parse_frontmatter("Just plain markdown")
+        assert result == {}
+
+
+class TestToolBinding:
+    """Req SK-3: Tool binding via _skill_name metadata."""
+
+    def test_binds_tool_to_skill(self, registry, mock_tool):
+        bound = registry.bind_tools([mock_tool])
+        assert bound == 1
+        assert len(registry.get_tools("web-search")) == 1
+
+    def test_ignores_tool_without_skill_name(self, registry):
+        def orphan_tool(): pass
+        bound = registry.bind_tools([orphan_tool])
+        assert bound == 0
+
+    def test_ignores_tool_with_unknown_skill(self, registry):
+        def stray_tool(): pass
+        stray_tool._skill_name = "nonexistent-skill"
+        bound = registry.bind_tools([stray_tool])
+        assert bound == 0
+
+    def test_binds_multiple_tools(self, registry, mock_tool, viz_tool):
+        bound = registry.bind_tools([mock_tool, viz_tool])
+        assert bound == 2
+
+
+class TestCatalog:
+    """Req SK-4: Level 1 — catalog generation for system prompt."""
+
+    def test_catalog_contains_skill_names(self, registry):
+        catalog = registry.get_catalog()
+        assert "web-search" in catalog
+        assert "visualization" in catalog
+        assert "data-analysis" in catalog
+
+    def test_catalog_contains_descriptions(self, registry):
+        catalog = registry.get_catalog()
+        assert "Search the web for current information" in catalog
+
+    def test_catalog_shows_composite_combines(self, registry):
+        catalog = registry.get_catalog()
+        assert "combines:" in catalog
+
+    def test_empty_registry_returns_empty_string(self):
+        reg = SkillRegistry("/nonexistent")
+        assert reg.get_catalog() == ""
+
+    def test_catalog_shows_tool_count(self, registry, mock_tool):
+        registry.bind_tools([mock_tool])
+        catalog = registry.get_catalog()
+        assert "(1 tools)" in catalog
+
+
+class TestInstructions:
+    """Req SK-5: Level 2 — instructions loading."""
+
+    def test_loads_instructions_without_frontmatter(self, registry):
+        instructions = registry.load_instructions("web-search")
+        assert instructions is not None
+        assert "# Web Search" in instructions
+        assert "---" not in instructions
+        assert "name:" not in instructions
+
+    def test_unknown_skill_returns_none(self, registry):
+        assert registry.load_instructions("nonexistent") is None
+
+
+class TestTools:
+    """Req SK-6: Level 3 — tool access."""
+
+    def test_get_tools_returns_bound_tools(self, registry, mock_tool):
+        registry.bind_tools([mock_tool])
+        tools = registry.get_tools("web-search")
+        assert len(tools) == 1
+        assert tools[0].tool_name == "web_search"
+
+    def test_composite_skill_aggregates_tools(self, registry, mock_tool, viz_tool):
+        registry.bind_tools([mock_tool, viz_tool])
+        tools = registry.get_tools("data-analysis")
+        assert len(tools) == 2
+
+    def test_unknown_skill_returns_empty(self, registry):
+        assert registry.get_tools("nonexistent") == []
+
+    def test_get_tool_schemas(self, registry, mock_tool):
+        registry.bind_tools([mock_tool])
+        schemas = registry.get_tool_schemas("web-search")
+        assert len(schemas) == 1
+        assert schemas[0]["name"] == "web_search"
diff --git a/backend/tests/agents/main_agent/skills/test_skill_tools.py b/backend/tests/agents/main_agent/skills/test_skill_tools.py
new file mode 100644
index 00000000..2f3419a0
--- /dev/null
+++ b/backend/tests/agents/main_agent/skills/test_skill_tools.py
@@ -0,0 +1,116 @@
+"""Tests for skill_dispatcher and skill_executor tools."""
+
+import json
+import pytest
+
+from agents.main_agent.skills.skill_registry import SkillRegistry
+from agents.main_agent.skills.skill_tools import (
+    skill_dispatcher,
+    skill_executor,
+    set_dispatcher_registry,
+)
+
+
+@pytest.fixture(autouse=True)
+def setup_registry(registry, mock_tool, viz_tool):
+    """Wire up registry with tools for all tests in this module."""
+    registry.bind_tools([mock_tool, viz_tool])
+    set_dispatcher_registry(registry)
+    yield
+    set_dispatcher_registry(None)
+
+
+class TestSkillDispatcher:
+    """Req SD-1: skill_dispatcher loads instructions and schemas."""
+
+    def test_returns_instructions(self, registry):
+        result = json.loads(skill_dispatcher(skill_name="web-search"))
+        assert "instructions" in result
+        assert "# Web Search" in result["instructions"]
+
+    def test_returns_tool_schemas(self, registry):
+        result = json.loads(skill_dispatcher(skill_name="web-search"))
+        assert "tool_schemas" in result
+        assert len(result["tool_schemas"]) == 1
+        assert result["tool_schemas"][0]["name"] == "web_search"
+
+    def test_unknown_skill_returns_error(self):
+        result = json.loads(skill_dispatcher(skill_name="nonexistent"))
+        assert "error" in result
+        assert "Unknown skill" in result["error"]
+
+    def test_unknown_skill_lists_available(self):
+        result = json.loads(skill_dispatcher(skill_name="nonexistent"))
+        assert "available_skills" in result
+
+    def test_no_registry_returns_error(self):
+        set_dispatcher_registry(None)
+        result = json.loads(skill_dispatcher(skill_name="web-search"))
+        assert "error" in result
+        assert "not initialized" in result["error"]
+
+
+class TestSkillExecutor:
+    """Req SE-1: skill_executor runs tools within a skill."""
+
+    def test_executes_tool(self):
+        result = skill_executor(
+            skill_name="web-search",
+            tool_name="web_search",
+            tool_input={"query": "test search"}
+        )
+        assert result == "Results for: test search"
+
+    def test_json_string_input_parsed(self):
+        result = skill_executor(
+            skill_name="web-search",
+            tool_name="web_search",
+            tool_input='{"query": "parsed"}'
+        )
+        assert result == "Results for: parsed"
+
+    def test_unknown_skill_returns_error(self):
+        result = json.loads(skill_executor(
+            skill_name="nonexistent",
+            tool_name="anything",
+        ))
+        assert "error" in result
+
+    def test_unknown_tool_returns_error_with_available(self):
+        result = json.loads(skill_executor(
+            skill_name="web-search",
+            tool_name="nonexistent_tool",
+        ))
+        assert "error" in result
+        assert "available_tools" in result
+
+    def test_no_registry_returns_error(self):
+        set_dispatcher_registry(None)
+        result = json.loads(skill_executor(
+            skill_name="web-search",
+            tool_name="web_search",
+        ))
+        assert "error" in result
+
+
+class TestDecorators:
+    """Req SD-2: Skill decorators apply metadata."""
+
+    def test_skill_decorator_sets_attribute(self):
+        from agents.main_agent.skills.decorators import skill
+
+        @skill("my-skill")
+        def my_tool():
+            pass
+
+        assert my_tool._skill_name == "my-skill"
+
+    def test_register_skill_sets_attributes(self):
+        from agents.main_agent.skills.decorators import register_skill
+
+        def tool_a(): pass
+        def tool_b(): pass
+
+        register_skill("batch-skill", tools=[tool_a, tool_b])
+        assert tool_a._skill_name == "batch-skill"
+        assert tool_b._skill_name == "batch-skill"
diff --git a/backend/tests/agents/main_agent/test_agent_types.py b/backend/tests/agents/main_agent/test_agent_types.py
new file mode 100644
index 00000000..da21a2ec
--- /dev/null
+++ b/backend/tests/agents/main_agent/test_agent_types.py
@@ -0,0 +1,72 @@
+"""Tests for agent type registry and factory function."""
+
+import pytest
+from agents.main_agent.agent_types import (
+    create_agent,
+    register_agent_type,
+    get_available_types,
+    _AGENT_TYPES,
+)
+from agents.main_agent.base_agent import BaseAgent
+from agents.main_agent.chat_agent import ChatAgent
+from agents.main_agent.main_agent import MainAgent
+
+
+class TestGetAvailableTypes:
+    """Req AT-1: Available types discovery."""
+
+    def test_chat_is_registered_by_default(self):
+        assert "chat" in get_available_types()
+
+    def test_returns_list_of_strings(self):
+        types = get_available_types()
+        assert isinstance(types, list)
+        assert all(isinstance(t, str) for t in types)
+
+
+class TestRegisterAgentType:
+    """Req AT-2: Dynamic agent type registration."""
+
+    def test_register_new_type(self):
+        class DummyAgent(BaseAgent):
+            def _create_agent(self): pass
+            async def stream_async(self, message, **kwargs): yield ""
+
+        register_agent_type("dummy", DummyAgent)
+        assert "dummy" in get_available_types()
+
+        # Cleanup
+        del _AGENT_TYPES["dummy"]
+
+    def test_register_overwrites_existing(self):
+        original = _AGENT_TYPES.get("chat")
+        try:
+            register_agent_type("chat", MainAgent)
+            assert _AGENT_TYPES["chat"] is MainAgent
+        finally:
+            _AGENT_TYPES["chat"] = original
+
+
+class TestCreateAgent:
+    """Req AT-3: Factory function routing."""
+
+    def test_unknown_type_raises_value_error(self):
+        with pytest.raises(ValueError, match="Unknown agent_type 'nonexistent'"):
+            create_agent("nonexistent", session_id="test")
+
+    def test_error_message_lists_available_types(self):
+        with pytest.raises(ValueError, match="chat"):
+            create_agent("nonexistent", session_id="test")
+
+
+class TestMainAgentBackwardCompat:
+    """Req AT-4: MainAgent remains a valid ChatAgent subclass."""
+
+    def test_mainagent_is_subclass_of_chatagent(self):
+        assert issubclass(MainAgent, ChatAgent)
+
+    def test_mainagent_is_subclass_of_baseagent(self):
+        assert issubclass(MainAgent, BaseAgent)
+
+    def test_chatagent_is_subclass_of_baseagent(self):
+        assert issubclass(ChatAgent, BaseAgent)
diff --git a/backend/tests/agents/main_agent/test_voice_agent.py b/backend/tests/agents/main_agent/test_voice_agent.py
new file mode 100644
index 00000000..fcf162cf
--- /dev/null
+++ b/backend/tests/agents/main_agent/test_voice_agent.py
@@ -0,0 +1,156 @@
+"""Tests for VoiceAgent — module-level and class-level behavior."""
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+from agents.main_agent.config.constants import Defaults, EnvVars
+from agents.main_agent.base_agent import BaseAgent
+
+
+class TestVoiceAgentImport:
+    """Req VA-1: VoiceAgent is importable and conditionally available."""
+
+    def test_voice_agent_module_importable(self):
+        # The module itself should always be importable
+        import agents.main_agent.voice_agent as va
+        assert hasattr(va, "VoiceAgent")
+        assert hasattr(va, "BIDI_AVAILABLE")
+
+    def test_voice_agent_is_base_agent_subclass(self):
+        from agents.main_agent.voice_agent import VoiceAgent
+        assert issubclass(VoiceAgent, BaseAgent)
+
+
+class TestVoiceConstants:
+    """Req VA-2: Voice configuration constants."""
+
+    def test_default_voice(self):
+        assert Defaults.NOVA_SONIC_VOICE == "tiffany"
+
+    def test_default_model_id(self):
+        assert Defaults.NOVA_SONIC_MODEL_ID == "amazon.nova-2-sonic-v1:0"
+
+    def test_default_sample_rates(self):
+        assert Defaults.NOVA_SONIC_INPUT_RATE == 16000
+        assert Defaults.NOVA_SONIC_OUTPUT_RATE == 16000
+
+    def test_default_max_messages(self):
+        assert Defaults.NOVA_SONIC_MAX_MESSAGES == 20
+
+    def test_voice_agent_id(self):
+        assert Defaults.VOICE_AGENT_ID == "voice"
+
+    def test_env_var_names(self):
+        assert EnvVars.NOVA_SONIC_MODEL_ID == "NOVA_SONIC_MODEL_ID"
+        assert EnvVars.NOVA_SONIC_VOICE == "NOVA_SONIC_VOICE"
+        assert EnvVars.NOVA_SONIC_MAX_MESSAGES == "NOVA_SONIC_MAX_MESSAGES"
+
+
+class TestVoiceAgentRegistration:
+    """Req VA-3: VoiceAgent factory registration."""
+
+    def test_voice_type_in_available_if_bidi_installed(self):
+        from agents.main_agent.voice_agent import BIDI_AVAILABLE
+        from agents.main_agent.agent_types import get_available_types
+
+        if BIDI_AVAILABLE:
+            assert "voice" in get_available_types()
+
+    def test_chat_and_skill_always_available(self):
+        from agents.main_agent.agent_types import get_available_types
+        types = get_available_types()
+        assert "chat" in types
+        assert "skill" in types
+
+
+class TestVoiceAgentTextHistory:
+    """Req VA-4: Voice-text continuity."""
+
+    def test_load_text_history_passes_limit(self):
+        from agents.main_agent.voice_agent import VoiceAgent
+
+        # Mock SessionMessage objects with to_message()
+        mock_msgs = []
+        for i in range(10):
+            m = MagicMock()
+            m.to_message.return_value = {"role": "user", "content": [{"text": f"msg {i}"}]}
+            mock_msgs.append(m)
+
+        mock_session = MagicMock()
+        mock_session.list_messages.return_value = mock_msgs
+
+        agent = VoiceAgent.__new__(VoiceAgent)
+        agent.session_manager = mock_session
+        agent.session_id = "test-session"
+
+        with patch.dict("os.environ", {EnvVars.NOVA_SONIC_MAX_MESSAGES: "10"}):
+            messages = agent._load_text_history()
+
+        # Verify limit is passed to list_messages
+        mock_session.list_messages.assert_called_once_with(
+            session_id="test-session",
+            agent_id="default",
+            limit=10,
+        )
+        # Messages are converted to dicts via to_dict()
+        assert len(messages) == 10
+        assert messages[0]["role"] == "user"
+
+    def test_load_text_history_handles_empty(self):
+        from agents.main_agent.voice_agent import VoiceAgent
+
+        mock_session = MagicMock()
+        mock_session.list_messages.return_value = []
+
+        agent = VoiceAgent.__new__(VoiceAgent)
+        agent.session_manager = mock_session
+        agent.session_id = "test-session"
+
+        messages = agent._load_text_history()
+        assert messages == []
+
+    def test_load_text_history_handles_error(self):
+        from agents.main_agent.voice_agent import VoiceAgent
+
+        mock_session = MagicMock()
+        mock_session.list_messages.side_effect = RuntimeError("connection failed")
+
+        agent = VoiceAgent.__new__(VoiceAgent)
+        agent.session_manager = mock_session
+        agent.session_id = "test-session"
+
+        messages = agent._load_text_history()
+        assert messages == []
+
+
+class TestVoiceSystemPrompt:
+    """Req VA-5: Voice-optimized system prompt."""
+
+    def test_voice_prompt_adds_guidelines(self):
+        from agents.main_agent.voice_agent import VoiceAgent
+
+        agent = VoiceAgent.__new__(VoiceAgent)
+        agent.system_prompt = "You are a helpful assistant."
+
+        prompt = agent._build_voice_system_prompt()
+        assert "Voice Interaction Guidelines" in prompt
+        assert "concise and conversational" in prompt
+
+    def test_voice_prompt_preserves_base(self):
+        from agents.main_agent.voice_agent import VoiceAgent
+
+        agent = VoiceAgent.__new__(VoiceAgent)
+        agent.system_prompt = "Base prompt here."
+
+        prompt = agent._build_voice_system_prompt()
+        assert "Base prompt here." in prompt
+
+
+class TestPyAudioMock:
+    """Req VA-6: PyAudio mock is in place."""
+
+    def test_pyaudio_in_sys_modules(self):
+        import sys
+        # After importing voice_agent, pyaudio should be mocked
+        import agents.main_agent.voice_agent  # noqa: F401
+        assert "pyaudio" in sys.modules
diff --git a/backend/tests/agents/main_agent/test_voice_routes.py b/backend/tests/agents/main_agent/test_voice_routes.py
new file mode 100644
index 00000000..dbfb7775
--- /dev/null
+++ b/backend/tests/agents/main_agent/test_voice_routes.py
@@ -0,0 +1,117 @@
+"""Tests for voice WebSocket route — auth, message dispatch, debug endpoints."""
+
+import json
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+
+from apis.inference_api.chat.voice_routes import (
+    _extract_user_from_token,
+    _active_sessions,
+    router,
+)
+
+
+class TestExtractUserFromToken:
+    """Req VR-1: JWT token extraction for WebSocket auth."""
+
+    def test_valid_token_extracts_user_id(self):
+        import jwt as pyjwt
+        token = pyjwt.encode({"sub": "user-123", "email": "test@example.com"}, "secret")
+        result = _extract_user_from_token(token)
+        assert result is not None
+        assert result["user_id"] == "user-123"
+        assert result["email"] == "test@example.com"
+        assert result["raw_token"] == token
+
+    def test_missing_sub_returns_none(self):
+        import jwt as pyjwt
+        token = pyjwt.encode({"email": "no-sub@example.com"}, "secret")
+        result = _extract_user_from_token(token)
+        assert result is None
+
+    def test_empty_token_returns_none(self):
+        assert _extract_user_from_token("") is None
+
+    def test_none_token_returns_none(self):
+        assert _extract_user_from_token(None) is None
+
+    def test_malformed_token_returns_none(self):
+        result = _extract_user_from_token("not.a.valid.jwt.token.at.all")
+        assert result is None
+
+    def test_preferred_username_fallback(self):
+        import jwt as pyjwt
+        token = pyjwt.encode({"sub": "user-456", "preferred_username": "jdoe"}, "secret")
+        result = _extract_user_from_token(token)
+        assert result["email"] == "jdoe"
+
+
+class TestActiveSessionsManagement:
+    """Req VR-2: Active session tracking."""
+
+    def test_sessions_dict_exists(self):
+        assert isinstance(_active_sessions, dict)
+
+    def test_sessions_can_be_added_and_removed(self):
+        _active_sessions["test-session"] = MagicMock()
+        assert "test-session" in _active_sessions
+        del _active_sessions["test-session"]
+        assert "test-session" not in _active_sessions
+
+
+class TestVoiceAgentLazyImport:
+    """Req VR-3: Lazy VoiceAgent import."""
+
+    def test_get_voice_agent_class_returns_class(self):
+        from apis.inference_api.chat.voice_routes import _get_voice_agent_class
+        cls = _get_voice_agent_class()
+        assert cls is not None
+        assert cls.__name__ == "VoiceAgent"
+
+    def test_get_voice_agent_class_caches(self):
+        from apis.inference_api.chat.voice_routes import _get_voice_agent_class
+        cls1 = _get_voice_agent_class()
+        cls2 = _get_voice_agent_class()
+        assert cls1 is cls2
+
+
+class TestDebugEndpoints:
+    """Req VR-4: Debug endpoint behavior."""
+
+    @pytest.fixture(autouse=True)
+    def clean_sessions(self):
+        """Ensure clean session state for each test."""
+        _active_sessions.clear()
+        yield
+        _active_sessions.clear()
+
+    @pytest.mark.asyncio
+    async def test_list_sessions_empty(self):
+        from apis.inference_api.chat.voice_routes import list_voice_sessions
+        result = await list_voice_sessions()
+        assert result["count"] == 0
+        assert result["active_sessions"] == []
+
+    @pytest.mark.asyncio
+    async def test_list_sessions_with_entries(self):
+        from apis.inference_api.chat.voice_routes import list_voice_sessions
+        _active_sessions["sess-1"] = MagicMock()
+        _active_sessions["sess-2"] = MagicMock()
+        result = await list_voice_sessions()
+        assert result["count"] == 2
+
+    @pytest.mark.asyncio
+    async def test_stop_session_not_found(self):
+        from apis.inference_api.chat.voice_routes import stop_voice_session
+        result = await stop_voice_session("nonexistent")
+        assert result["status"] == "not_found"
+
+    @pytest.mark.asyncio
+    async def test_stop_session_calls_stop(self):
+        from apis.inference_api.chat.voice_routes import stop_voice_session
+        mock_agent = AsyncMock()
+        _active_sessions["sess-stop"] = mock_agent
+        result = await stop_voice_session("sess-stop")
+        assert result["status"] == "stopped"
+        mock_agent.stop.assert_called_once()
+        assert "sess-stop" not in _active_sessions
diff --git a/backend/uv.lock b/backend/uv.lock
index 40945a8c..3464d397 100644
--- a/backend/uv.lock
+++ b/backend/uv.lock
@@ -1,10 +1,11 @@
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.10"
 resolution-markers = [
     "python_full_version >= '3.14'",
     "python_full_version == '3.13.*'",
-    "python_full_version >= '3.11' and python_full_version < '3.13'",
+    "python_full_version == '3.12.*'",
+    "python_full_version == '3.11.*'",
     "python_full_version < '3.11'",
 ]
 
@@ -48,11 +49,14 @@ all = [
     { name = "pytest-asyncio" },
     { name = "pytest-cov" },
     { name = "ruff" },
-    { name = "strands-agents" },
+    { name = "strands-agents", extra = ["bidi"] },
     { name = "strands-agents-tools" },
     { name = "tiktoken" },
     { name = "types-aiofiles" },
 ]
+bidi = [
+    { name = "strands-agents", extra = ["bidi"] },
+]
 dev = [
     { name = "black" },
     { name = "hypothesis" },
@@ -69,7 +73,7 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "agentcore-stack", extras = ["agentcore", "dev"], marker = "extra == 'all'" },
+    { name = "agentcore-stack", extras = ["agentcore", "bidi", "dev"], marker = "extra == 'all'" },
     { name = "aiofiles", specifier = "==25.1.0" },
     { name = "authlib", specifier = "==1.6.9" },
     { name = "aws-opentelemetry-distro", marker = "extra == 'agentcore'", specifier = "==0.16.0" },
@@ -93,12 +97,13 @@ requires-dist = [
     { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.9" },
     { name = "starlette", specifier = "==1.0.0" },
     { name = "strands-agents", marker = "extra == 'agentcore'", specifier = "==1.34.1" },
+    { name = "strands-agents", extras = ["bidi"], marker = "extra == 'bidi'", specifier = "==1.34.1" },
     { name = "strands-agents-tools", marker = "extra == 'agentcore'", specifier = "==0.3.0" },
     { name = "tiktoken", marker = "extra == 'dev'", specifier = "==0.12.0" },
     { name = "types-aiofiles", marker = "extra == 'dev'", specifier = "==25.1.0.20251011" },
     { name = "uvicorn", extras = ["standard"], specifier = "==0.44.0" },
 ]
-provides-extras = ["agentcore", "dev", "all"]
+provides-extras = ["agentcore", "bidi", "dev", "all"]
 
 [[package]]
 name = "aiofiles"
@@ -408,6 +413,70 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/af/11/5dc8be418e1d54bed15eaf3a7461797e5ebb9e6a34869ad750561f35fa5b/aws_requests_auth-0.4.3-py2.py3-none-any.whl", hash = "sha256:646bc37d62140ea1c709d20148f5d43197e6bd2d63909eb36fa4bb2345759977", size = 6838, upload-time = "2020-05-27T23:10:33.658Z" },
 ]
 
+[[package]]
+name = "aws-sdk-bedrock-runtime"
+version = "0.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "smithy-aws-core", extra = ["eventstream", "json"], marker = "python_full_version >= '3.12'" },
+    { name = "smithy-core", marker = "python_full_version >= '3.12'" },
+    { name = "smithy-http", extra = ["awscrt"], marker = "python_full_version >= '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/30/ff/c5396e82ab39a30cebd08c875250e72c1116f57c8c1f3e0dda1c1db9b177/aws_sdk_bedrock_runtime-0.5.0.tar.gz", hash = "sha256:cc0af7330bda9e398ad9ebf39c021a59dbc28c616a6c9c7765c355773b2402f4", size = 159805, upload-time = "2026-04-07T19:24:24.564Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7d/1c/b6f1b10435beee0c6289e2ce5e736bbd30555ce9b5898bd9f98f982827ad/aws_sdk_bedrock_runtime-0.5.0-py3-none-any.whl", hash = "sha256:87a002ba4d070e32e4343858c3aacc2cf040beed7f03c93e2b984e78a4f4ceb6", size = 84911, upload-time = "2026-04-07T19:24:25.49Z" },
+]
+
+[[package]]
+name = "aws-sdk-signers"
+version = "0.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/73/1e/e93f5b7711bb9c3b97a4d5486ee3a74db412a66bf6160977bb69f0434830/aws_sdk_signers-0.2.0.tar.gz", hash = "sha256:3b23fb02ababb9e768fc102ab7584e344be8d65324ef3c33df4b8cad6cee26e7", size = 18069, upload-time = "2026-04-07T19:24:09.72Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e3/f3/cb2cd5177bb6c21d339b96079ece8e30ffe9954540494bae73a6498677ac/aws_sdk_signers-0.2.0-py3-none-any.whl", hash = "sha256:e770dcc390e18093840ef4ce1ac70fc419fe6ac8737809ffce9a9fab56d8ac2d", size = 21621, upload-time = "2026-04-07T19:24:08.57Z" },
+]
+
+[[package]]
+name = "awscrt"
+version = "0.32.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4d/4d/c2aece4af7b5537c855548f53ee077d01216a1a4adbf0fd24f23dbac52bf/awscrt-0.32.0.tar.gz", hash = "sha256:92e749fce6c61da8db1af0baa6b7e96f7acf8a5574760b3d7880d190cedee8a0", size = 36832208, upload-time = "2026-03-27T01:19:18.147Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/93/9f/ded80b31ea4e30be66cf8dd35ecb0bce3e5a2fee39542bd877d7c2f2c2e4/awscrt-0.32.0-cp310-cp310-macosx_10_15_universal2.whl", hash = "sha256:211cee3a5335bbc96405afdbdebf9c17bf16f3a299e9d8b661d5c904634ade43", size = 3391016, upload-time = "2026-03-27T01:17:58.557Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/8e/81ad2ad2c90faba849f106f4ee8c2f00741b1137225e965ba2be4b36fd9d/awscrt-0.32.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:693f40a004270dfc7e0f92f7d36ef5fb8e40de686fa87a0603ade74a479bbf40", size = 3930641, upload-time = "2026-03-27T01:18:01.454Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/09/193d7da3033e0c2f283f0c1a017a6e0918c91e0f57c3e4a18314ba7c97ad/awscrt-0.32.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:3b3014bd320ce95a3698f8b00312a06accc6222505ace4e6cbb524aa10ab8654", size = 4217980, upload-time = "2026-03-27T01:18:02.909Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/fa/63fc0f4573bf29135fde0b5a168c8d2c003344a342e7a342ab6e13ded795/awscrt-0.32.0-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:43ea8a3bb994259b1c2cb6fc400374cc6c84a2b235eada3370d5f012420427dd", size = 3861043, upload-time = "2026-03-27T01:18:04.424Z" },
+    { url = "https://files.pythonhosted.org/packages/95/57/e64e365c9112cbe4b04982effb22d62d57728513555c9516879598ebfea9/awscrt-0.32.0-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:7cec6175c9616840a599050a0e6157846b509e7b3a7f2ab9f8e9a64bcb342e68", size = 4101797, upload-time = "2026-03-27T01:18:05.758Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/2f/2a3decaa3111c47fbec0a051767838741b52c61e37c215cb9c905d74ed5b/awscrt-0.32.0-cp310-cp310-win32.whl", hash = "sha256:0a585e9089140f55a8452c2f1aefe17712d39eff5413c1c0c7aa393e749fd5b7", size = 4041085, upload-time = "2026-03-27T01:18:07.28Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/63/72f38c224bd38e383b1e08713c655c0756a41c6d0e7e59616e7d47b6ec35/awscrt-0.32.0-cp310-cp310-win_amd64.whl", hash = "sha256:d4423dbdb75ed37bbd9697a672bfd75a02a7354ac9b818fa2d38059726171928", size = 4204956, upload-time = "2026-03-27T01:18:08.947Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/74/1e63af11b71ca90e6bcc70affea6400078d4cf6605f0593fe0a91a1daeb5/awscrt-0.32.0-cp311-abi3-macosx_10_15_universal2.whl", hash = "sha256:4ca7040b279cf6014c06de93be7a29a164c9c92469eb79c70143853873e81949", size = 3391226, upload-time = "2026-03-27T01:18:10.231Z" },
+    { url = "https://files.pythonhosted.org/packages/43/62/d1383a31d32b9963a3a646d926f77a46d88cee1a86536186ad0ac0c44aea/awscrt-0.32.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:15a96559710e559bc4131b7af55b93c0c79505d4b9c4c4511b3b825bbb4f82a9", size = 3889898, upload-time = "2026-03-27T01:18:11.484Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/92/37c25e283ed4ebe21117fb183c1dbcd947d72fb770f05f9f1e8c2b63541e/awscrt-0.32.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:11a8cf1902c35ad784ceedbe2d5b44956a34bb2b7c3c818511ce93bdb21bc386", size = 4178874, upload-time = "2026-03-27T01:18:13.128Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/23/6dbefd6efbe0914c73f633ea6702aa4701425337f4e0c1059ec99aedde23/awscrt-0.32.0-cp311-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:f1eea556144c2999e105966bbe97a0460d10d656e331bc2c875f15ece3315c3b", size = 3800811, upload-time = "2026-03-27T01:18:14.848Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/2e/0af9a203fea97504e0bd11261b12422ff555745699c176dee1767f09c9f6/awscrt-0.32.0-cp311-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:d7ef6f0e728c1b7a0a4b771d4c677a00bc1bf377b8b2dd59a1dd626b920efc3b", size = 4039356, upload-time = "2026-03-27T01:18:16.684Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/8a/6371dc9dc7b4a8dfafe7ed1b4f30500cc22e239413a6fdcaab72f8b80b8e/awscrt-0.32.0-cp311-abi3-win32.whl", hash = "sha256:8cee2fea902452a36f67f9d79e6eb406d4359854dad6df439b3c671f07059763", size = 4039614, upload-time = "2026-03-27T01:18:17.979Z" },
+    { url = "https://files.pythonhosted.org/packages/75/c2/0bd9346f22ced5f11dac7039876ea2824cc3e268b6b681e2a8a29b1e8701/awscrt-0.32.0-cp311-abi3-win_amd64.whl", hash = "sha256:8213ee3b3c1adb5364a48a87420cde4426688f0438a88f6381595586be7ffc17", size = 4201989, upload-time = "2026-03-27T01:18:19.332Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/67/2093978f8496dad5e90d77c3f59f07d3f040e32eda60f3592f1b45d48d65/awscrt-0.32.0-cp313-abi3-macosx_10_15_universal2.whl", hash = "sha256:d1efd89302eeee14878ca2067de6525c85d4973cd4473bc537e8807ecca660d3", size = 3390414, upload-time = "2026-03-27T01:18:21.006Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/4d/c2f8a732fef457ce58e7d798b2775deea16a3a840d8a9dd43bb21b80ec63/awscrt-0.32.0-cp313-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:18e36af2cfec50b0a2d270921217245c36f6722b9aae756394ca050dee535883", size = 3881094, upload-time = "2026-03-27T01:18:22.602Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/be/3cd7ad30fbc65eed95c1df2d50f9f1facb82335137f1842ec4e2152d3a51/awscrt-0.32.0-cp313-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:a94d7c85486908adf07693519b3a8ec7c61b86cc0901fed266ff2239babef6ce", size = 4172552, upload-time = "2026-03-27T01:18:23.857Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/af/e299192ae380cb688ff505aa9145a9b4e9c31bf12275d67074bfd6aff899/awscrt-0.32.0-cp313-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:68e36b744ed8089be80a2f7c8ed9bd46573f00870d1429707c1c847f3dc99a6f", size = 3791182, upload-time = "2026-03-27T01:18:25.144Z" },
+    { url = "https://files.pythonhosted.org/packages/96/ab/ffa769df6417720a4f9bddd9f8cc077f671d0a970d88d2c80e0e06eb0890/awscrt-0.32.0-cp313-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:b1a9f3952f382feee264614e727d78e7fa12bad138a025e832affc84780fdc89", size = 4035286, upload-time = "2026-03-27T01:18:26.444Z" },
+    { url = "https://files.pythonhosted.org/packages/50/f2/cf80de14e9735750af9c4d11173150da997b8333ca6e68dc4850b6768a7c/awscrt-0.32.0-cp313-abi3-win32.whl", hash = "sha256:56c418ac23102e34ad95ea68ad5527ce534b7c79bb3ec3b908b647d90ee3ce41", size = 4034631, upload-time = "2026-03-27T01:18:28.247Z" },
+    { url = "https://files.pythonhosted.org/packages/96/d6/d95df41f0e3a9434a750a33fbe465c8638212a46ec469f301511fd4791f7/awscrt-0.32.0-cp313-abi3-win_amd64.whl", hash = "sha256:7a3a464b0c23d1c2cca23b210035da203b1ead7cafcda2cebb87af3de20cc2b2", size = 4197293, upload-time = "2026-03-27T01:18:29.666Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/aa/5d85dc363c2269a205d33305e13b07298beaf582f653f10f6fc70531dc29/awscrt-0.32.0-cp313-cp313t-macosx_10_15_universal2.whl", hash = "sha256:f61cc36f645444d4e27cdf2c8fc5d3fdca77de35f341ad0e6c65f6c097ef5afd", size = 3401086, upload-time = "2026-03-27T01:18:31.388Z" },
+    { url = "https://files.pythonhosted.org/packages/52/9e/fac5cab0cd7a94a4978daade9ef6d77c3b1037f470476d16ae822b54c97e/awscrt-0.32.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c51510e2171a3cab33612b98333a4baca391ed76a1185e9f6ec5433196e646af", size = 4006884, upload-time = "2026-03-27T01:18:32.696Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/cc/abd847148100a62616abaa5bdf9731686646e2a6f73e44bb63a718d6fd1e/awscrt-0.32.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:f22723fc84ec31ed13591105083bea57fcbb7a9b20600dcfda8b5c28fa8047f8", size = 4293086, upload-time = "2026-03-27T01:18:34.092Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/8e/05572eaab9ff7a0a40f17c084d61389602c5018c7f4b7bb7ad9e58b4bea9/awscrt-0.32.0-cp313-cp313t-musllinux_1_1_aarch64.whl", hash = "sha256:4bc6492b7622cbad46d65492fb12239d946e890797c5da6c30a878a04c694623", size = 3934220, upload-time = "2026-03-27T01:18:35.438Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/4d/6e2dc94c69b32aadf037e5057f550d8e1bf3271573e5e95cc8934499a579/awscrt-0.32.0-cp313-cp313t-musllinux_1_1_x86_64.whl", hash = "sha256:dd6df896ae0650977de05c8e83fc5f3f7472b4d8de7744560526c13a63da8fd0", size = 4168581, upload-time = "2026-03-27T01:18:36.885Z" },
+    { url = "https://files.pythonhosted.org/packages/42/4d/099e4fc39839ff130716713401d36ed9fa8b78feb5dcbf273e1e1aa71dd2/awscrt-0.32.0-cp313-cp313t-win32.whl", hash = "sha256:5fb05ab256b90c2d39386702d20419159b605a1f0e95d0fade715ccc9a76856a", size = 4091134, upload-time = "2026-03-27T01:18:38.532Z" },
+    { url = "https://files.pythonhosted.org/packages/c6/a6/e0c63b8b73424f91a9fab52f100f412864ddd47e01ce84a6aeae35a12b7b/awscrt-0.32.0-cp313-cp313t-win_amd64.whl", hash = "sha256:c1c69543cdeab10f7fcbd3f238996ee1ed73fb8f88dd9701fffc872d73bd256d", size = 4247510, upload-time = "2026-03-27T01:18:40.02Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/64/e7d5eac410e305b5d62da268d4c486dd003b065b3119031679a6cf242861/awscrt-0.32.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:f82a7969c025875fa419fc6349c8013bc88359ce264cb6c2399d03f42fbae0e3", size = 3401104, upload-time = "2026-03-27T01:18:41.354Z" },
+    { url = "https://files.pythonhosted.org/packages/27/36/20d11e4b2a32337b712f1aa683a7d4bed777d1bfdff5d7803c7b952556c2/awscrt-0.32.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:877e6061448abc91b1926f3f8c73808ce2a170a404065ba185a407fbfd2eb8e7", size = 4007601, upload-time = "2026-03-27T01:18:43.005Z" },
+    { url = "https://files.pythonhosted.org/packages/47/b6/d1d21aaa4c3affc82ff3b4ae75bad10d80234ea01d8d239a578efa23646b/awscrt-0.32.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:b83427cf90f1606a34dbbe29b1544f945899b3abdb8608a57f004c6f459fd1fd", size = 4293839, upload-time = "2026-03-27T01:18:44.628Z" },
+    { url = "https://files.pythonhosted.org/packages/97/2b/bb17205da426d175991ca9f9a5873c8c50a0620ec12c299ee3d80941552a/awscrt-0.32.0-cp314-cp314t-win32.whl", hash = "sha256:de44db7677361a05a1cdce9a1c29b6628542094599cb33105b99b97b4b9580ea", size = 4171775, upload-time = "2026-03-27T01:18:46.184Z" },
+    { url = "https://files.pythonhosted.org/packages/39/2c/65ac451a08b57d9d66c8ffc2cbdf3c32e7da84d0a1887bdf6a3da4877585/awscrt-0.32.0-cp314-cp314t-win_amd64.whl", hash = "sha256:7b9eb088e4e17539d3c5ec8f40f04363fabb807f9d509653d2443056d22b3506", size = 4347754, upload-time = "2026-03-27T01:18:47.641Z" },
+]
+
 [[package]]
 name = "backports-asyncio-runner"
 version = "1.2.0"
@@ -1338,6 +1407,97 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
 ]
 
+[[package]]
+name = "ijson"
+version = "3.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f4/57/60d1a6a512f2f0508d0bc8b4f1cc5616fd3196619b66bd6a01f9155a1292/ijson-3.5.0.tar.gz", hash = "sha256:94688760720e3f5212731b3cb8d30267f9a045fb38fb3870254e7b9504246f31", size = 68658, upload-time = "2026-02-24T03:58:30.974Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/6e/32/21c1b47a1afb7319944d0b9685c0997a9d574a77b030c82f6a1ac2cef4eb/ijson-3.5.0-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:ea8dcac10d86adaeead454bc25c97b68d0bda573d5fd6f86f5e21cf8f7906f88", size = 88935, upload-time = "2026-02-24T03:56:40.591Z" },
+    { url = "https://files.pythonhosted.org/packages/86/f7/6ac7ebbb3cd767c87cdcbb950a6754afd1c0977756347bfe03eb8e5b866d/ijson-3.5.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:92b0495bbb2150bbf14fc5d98fb6d76bcd1c526605a172709e602e6fedc96495", size = 60567, upload-time = "2026-02-24T03:56:41.919Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/98/1140de9ae872468a8bc2e87c171228e25e58b1eb696b7fb430f7590fea44/ijson-3.5.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:7af0c4c8943be8b09a4e57bdc1da6001dae7b36526d4154fe5c8224738d0921f", size = 60620, upload-time = "2026-02-24T03:56:42.764Z" },
+    { url = "https://files.pythonhosted.org/packages/60/e1/67dfe0774e4c7ca6ec8702e280e8764d356f3db54358999818cda6df7679/ijson-3.5.0-cp310-cp310-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:45887d5e84ff0d2b138c926cebd9071830733968afe8d9d12080b3c178c7f918", size = 126558, upload-time = "2026-02-24T03:56:43.922Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/ef/23d614fc773d428caeb6e197218b7e32adcc668ff5b98777039149571208/ijson-3.5.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9a70b575be8e57a28c80e90ed349ad3a851c3478524c70e36e07d6092ecd12c9", size = 133091, upload-time = "2026-02-24T03:56:45.291Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/80/99727603cd8a1d32edafa4392f4056b2420bf48c15afd34481c68a2d4435/ijson-3.5.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2adeecd45830bfd5580ca79a584154713aabef0b9607e16249133df5d2859813", size = 130249, upload-time = "2026-02-24T03:56:46.333Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/94/3a3d623ca80768e834be8a834ef05960e3b9e79af1a911704ff10c9e8792/ijson-3.5.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:d873e72889e7fc5962ab58909f1adff338d7c2f49e450e5b5fe844eff8155a14", size = 133501, upload-time = "2026-02-24T03:56:47.54Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/f6/df2c14ad340834eccee379046f155e4b66a16ddafd445429dee7b3323614/ijson-3.5.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:9a88c559456a79708592234d697645d92b599718f4cbbeaa6515f83ac63ca0ae", size = 128438, upload-time = "2026-02-24T03:56:48.455Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/7e/9ff5b8b5fee113f5607bc4149b707382a898eeb545153189b075e5ec8d59/ijson-3.5.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:cf83f58ad50dc0d39a2105cb26d4f359b38f42cef68b913170d4d47d97d97ba5", size = 131116, upload-time = "2026-02-24T03:56:49.737Z" },
+    { url = "https://files.pythonhosted.org/packages/64/20/954ce0d440d7cf72a3d8361b14406f9cdbf624b1625c10f8488857c769d6/ijson-3.5.0-cp310-cp310-win32.whl", hash = "sha256:aec4580a7712a19b1f95cd41bed260fc6a31266d37ef941827772a4c199e8143", size = 52724, upload-time = "2026-02-24T03:56:50.932Z" },
+    { url = "https://files.pythonhosted.org/packages/24/33/ece87d60502c6115642cbabeb8c122fa982212b392bc4f4ff5aab8e02dac/ijson-3.5.0-cp310-cp310-win_amd64.whl", hash = "sha256:9a9c4c70501e23e8eb1675330686d1598eebfa14b6f0dbc8f00c2e081cc628fa", size = 55125, upload-time = "2026-02-24T03:56:51.942Z" },
+    { url = "https://files.pythonhosted.org/packages/65/da/644343198abca5e0f6e2486063f8d8f3c443ca0ef5e5c890e51ef6032e33/ijson-3.5.0-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:5616311404b858d32740b7ad8b9a799c62165f5ecb85d0a8ed16c21665a90533", size = 88964, upload-time = "2026-02-24T03:56:53.099Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/63/8621190aa2baf96156dfd4c632b6aa9f1464411e50b98750c09acc0505ea/ijson-3.5.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:e9733f94029dd41702d573ef64752e2556e72aea14623d6dbb7a44ca1ccf30fd", size = 60582, upload-time = "2026-02-24T03:56:54.261Z" },
+    { url = "https://files.pythonhosted.org/packages/20/31/6a3f041fdd17dacff33b7d7d3ba3df6dca48740108340c6042f974b2ad20/ijson-3.5.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:db8398c6721b98412a4f618da8022550c8b9c5d9214040646071b5deb4d4a393", size = 60632, upload-time = "2026-02-24T03:56:55.159Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/68/474541998abbdecfd46a744536878335de89aceb9f085bff1aaf35575ceb/ijson-3.5.0-cp311-cp311-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:c061314845c08163b1784b6076ea5f075372461a32e6916f4e5f211fd4130b64", size = 131988, upload-time = "2026-02-24T03:56:56.35Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/32/e05ff8b72a44fe9d192f41c5dcbc35cfa87efc280cdbfe539ffaf4a7535e/ijson-3.5.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1111a1c5ac79119c5d6e836f900c1a53844b50a18af38311baa6bb61e2645aca", size = 138669, upload-time = "2026-02-24T03:56:57.555Z" },
+    { url = "https://files.pythonhosted.org/packages/49/b5/955a83b031102c7a602e2c06d03aff0a0e584212f09edb94ccc754d203ac/ijson-3.5.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1e74aff8c681c24002b61b1822f9511d4c384f324f7dbc08c78538e01fdc9fcb", size = 135093, upload-time = "2026-02-24T03:56:59.267Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/f2/30250cfcb4d2766669b31f6732689aab2bb91de426a15a3ebe482df7ee48/ijson-3.5.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:739a7229b1b0cc5f7e2785a6e7a5fc915e850d3fed9588d0e89a09f88a417253", size = 138715, upload-time = "2026-02-24T03:57:00.491Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/05/785a145d7e75e04e04480d59b6323cd4b1d9013a6cd8643fa635fbc93490/ijson-3.5.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:ef88712160360cab3ca6471a4e5418243f8b267cf1fe1620879d1b5558babc71", size = 133194, upload-time = "2026-02-24T03:57:01.759Z" },
+    { url = "https://files.pythonhosted.org/packages/14/eb/80d6f8a748dead4034cea0939494a67d10ccf88d6413bf6e860393139676/ijson-3.5.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:6ca0d1b6b5f8166a6248f4309497585fb8553b04bc8179a0260fad636cfdb798", size = 135588, upload-time = "2026-02-24T03:57:03.131Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/a8/bbc21f9400ebdbca48fab272593e0d1f875691be1e927d264d90d48b8c47/ijson-3.5.0-cp311-cp311-win32.whl", hash = "sha256:966039cf9047c7967febf7b9a52ec6f38f5464a4c7fbb5565e0224b7376fefff", size = 52721, upload-time = "2026-02-24T03:57:04.365Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/2e/4e8c0208b8f920ee80c88c956f93e78318f2cfb646455353b182738b490c/ijson-3.5.0-cp311-cp311-win_amd64.whl", hash = "sha256:6bad6a1634cb7c9f3f4c7e52325283b35b565f5b6cc27d42660c6912ce883422", size = 55121, upload-time = "2026-02-24T03:57:05.498Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/17/9c63c7688025f3a8c47ea717b8306649c8c7244e49e20a2be4e3515dc75c/ijson-3.5.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1ebefbe149a6106cc848a3eaf536af51a9b5ccc9082de801389f152dba6ab755", size = 88536, upload-time = "2026-02-24T03:57:06.809Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/dd/e15c2400244c117b06585452ebc63ae254f5a6964f712306afd1422daae0/ijson-3.5.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:19e30d9f00f82e64de689c0b8651b9cfed879c184b139d7e1ea5030cec401c21", size = 60499, upload-time = "2026-02-24T03:57:09.155Z" },
+    { url = "https://files.pythonhosted.org/packages/77/a9/bf4fe3538a0c965f16b406f180a06105b875da83f0743e36246be64ef550/ijson-3.5.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:a04a33ee78a6f27b9b8528c1ca3c207b1df3b8b867a4cf2fcc4109986f35c227", size = 60330, upload-time = "2026-02-24T03:57:10.574Z" },
+    { url = "https://files.pythonhosted.org/packages/31/76/6f91bdb019dd978fce1bc5ea1cd620cfc096d258126c91db2c03a20a7f34/ijson-3.5.0-cp312-cp312-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:7d48dc2984af02eb3c56edfb3f13b3f62f2f3e4fe36f058c8cfc75d93adf4fed", size = 138977, upload-time = "2026-02-24T03:57:11.932Z" },
+    { url = "https://files.pythonhosted.org/packages/11/be/bbc983059e48a54b0121ee60042979faed7674490bbe7b2c41560db3f436/ijson-3.5.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f1e73a44844d9adbca9cf2c4132cd875933e83f3d4b23881fcaf82be83644c7d", size = 149785, upload-time = "2026-02-24T03:57:13.255Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/81/2fee58f9024a3449aee83edfa7167fb5ccd7e1af2557300e28531bb68e16/ijson-3.5.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7389a56b8562a19948bdf1d7bae3a2edc8c7f86fb59834dcb1c4c722818e645a", size = 149729, upload-time = "2026-02-24T03:57:14.191Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/56/f1706761fcc096c9d414b3dcd000b1e6e5c24364c21cfba429837f98ee8d/ijson-3.5.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3176f23f8ebec83f374ed0c3b4e5a0c4db7ede54c005864efebbed46da123608", size = 150697, upload-time = "2026-02-24T03:57:15.855Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/6e/ee0d9c875a0193b632b3e9ccd1b22a50685fb510256ad57ba483b6529f77/ijson-3.5.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:6babd88e508630c6ef86c9bebaaf13bb2fb8ec1d8f8868773a03c20253f599bc", size = 142873, upload-time = "2026-02-24T03:57:16.831Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/bf/f9d4399d0e6e3fd615035290a71e97c843f17f329b43638c0a01cf112d73/ijson-3.5.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:dc1b3836b174b6db2fa8319f1926fb5445abd195dc963368092103f8579cb8ed", size = 151583, upload-time = "2026-02-24T03:57:17.757Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/71/a7254a065933c0e2ffd3586f46187d84830d3d7b6f41cfa5901820a4f87d/ijson-3.5.0-cp312-cp312-win32.whl", hash = "sha256:6673de9395fb9893c1c79a43becd8c8fbee0a250be6ea324bfd1487bb5e9ee4c", size = 53079, upload-time = "2026-02-24T03:57:18.703Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/7b/2edca79b359fc9f95d774616867a03ecccdf333797baf5b3eea79733918c/ijson-3.5.0-cp312-cp312-win_amd64.whl", hash = "sha256:f4f7fabd653459dcb004175235f310435959b1bb5dfa8878578391c6cc9ad944", size = 55500, upload-time = "2026-02-24T03:57:20.428Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/71/d67e764a712c3590627480643a3b51efcc3afa4ef3cb54ee4c989073c97e/ijson-3.5.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e9cedc10e40dd6023c351ed8bfc7dcfce58204f15c321c3c1546b9c7b12562a4", size = 88544, upload-time = "2026-02-24T03:57:21.293Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/39/f1c299371686153fa3cf5c0736b96247a87a1bee1b7145e6d21f359c505a/ijson-3.5.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:3647649f782ee06c97490b43680371186651f3f69bebe64c6083ee7615d185e5", size = 60495, upload-time = "2026-02-24T03:57:22.501Z" },
+    { url = "https://files.pythonhosted.org/packages/16/94/b1438e204d75e01541bebe3e668fe3e68612d210e9931ae1611062dd0a56/ijson-3.5.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:90e74be1dce05fce73451c62d1118671f78f47c9f6be3991c82b91063bf01fc9", size = 60325, upload-time = "2026-02-24T03:57:23.332Z" },
+    { url = "https://files.pythonhosted.org/packages/30/e2/4aa9c116fa86cc8b0f574f3c3a47409edc1cd4face05d0e589a5a176b05d/ijson-3.5.0-cp313-cp313-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:78e9ad73e7be2dd80627504bd5cbf512348c55ce2c06e362ed7683b5220e8568", size = 138774, upload-time = "2026-02-24T03:57:24.683Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/d2/738b88752a70c3be1505faa4dcd7110668c2712e582a6a36488ed1e295d4/ijson-3.5.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9577449313cc94be89a4fe4b3e716c65f09cc19636d5a6b2861c4e80dddebd58", size = 149820, upload-time = "2026-02-24T03:57:26.062Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/df/0b3ab9f393ca8f72ea03bc896ba9fdc987e90ae08cdb51c32a4ee0c14d5e/ijson-3.5.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:3e4c1178fb50aff5f5701a30a5152ead82a14e189ce0f6102fa1b5f10b2f54ff", size = 149747, upload-time = "2026-02-24T03:57:27.308Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/a3/b0037119f75131b78cb00acc2657b1a9d0435475f1f2c5f8f5a170b66b9c/ijson-3.5.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:0eb402ab026ffb37a918d75af2b7260fe6cfbce13232cc83728a714dd30bd81d", size = 151027, upload-time = "2026-02-24T03:57:28.522Z" },
+    { url = "https://files.pythonhosted.org/packages/22/a0/cb344de1862bf09d8f769c9d25c944078c87dd59a1b496feec5ad96309a4/ijson-3.5.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:5b08ee08355f9f729612a8eb9bf69cc14f9310c3b2a487c6f1c3c65d85216ec4", size = 142996, upload-time = "2026-02-24T03:57:29.774Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/32/a8ffd67182e02ea61f70f62daf43ded4fa8a830a2520a851d2782460aba8/ijson-3.5.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:bda62b6d48442903e7bf56152108afb7f0f1293c2b9bef2f2c369defea76ab18", size = 152068, upload-time = "2026-02-24T03:57:30.969Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/d1/3578df8e75d446aab0ae92e27f641341f586b85e1988536adebc65300cb4/ijson-3.5.0-cp313-cp313-win32.whl", hash = "sha256:8d073d9b13574cfa11083cc7267c238b7a6ed563c2661e79192da4a25f09c82c", size = 53065, upload-time = "2026-02-24T03:57:31.93Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/a2/f7cdaf5896710da3e69e982e44f015a83d168aa0f3a89b6f074b5426779d/ijson-3.5.0-cp313-cp313-win_amd64.whl", hash = "sha256:2419f9e32e0968a876b04d8f26aeac042abd16f582810b576936bbc4c6015069", size = 55499, upload-time = "2026-02-24T03:57:32.773Z" },
+    { url = "https://files.pythonhosted.org/packages/42/65/13e2492d17e19a2084523e18716dc2809159f2287fd2700c735f311e76c4/ijson-3.5.0-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:4d4b0cd676b8c842f7648c1a783448fac5cd3b98289abd83711b3e275e143524", size = 93019, upload-time = "2026-02-24T03:57:33.976Z" },
+    { url = "https://files.pythonhosted.org/packages/33/92/483fc97ece0c3f1cecabf48f6a7a36e89d19369eec462faaeaa34c788992/ijson-3.5.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:252dec3680a48bb82d475e36b4ae1b3a9d7eb690b951bb98a76c5fe519e30188", size = 62714, upload-time = "2026-02-24T03:57:34.819Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/88/793fe020a0fe9d9eed4c285cf4a5cfdb0a935708b3bde0d72f35c794b513/ijson-3.5.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:aa1b5dca97d323931fde2501172337384c958914d81a9dac7f00f0d4bfc76bc7", size = 62460, upload-time = "2026-02-24T03:57:35.874Z" },
+    { url = "https://files.pythonhosted.org/packages/51/69/f1a2690aa8d4df1f4e262b385e65a933ffdc250b091531bac9a449c19e16/ijson-3.5.0-cp313-cp313t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:7a5ec7fd86d606094bba6f6f8f87494897102fa4584ef653f3005c51a784c320", size = 199273, upload-time = "2026-02-24T03:57:37.07Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/a2/f1346d5299e79b988ab472dc773d5381ec2d57c23cb2f1af3ede4a810e62/ijson-3.5.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:009f41443e1521847701c6d87fa3923c0b1961be3c7e7de90947c8cb92ea7c44", size = 216884, upload-time = "2026-02-24T03:57:38.346Z" },
+    { url = "https://files.pythonhosted.org/packages/28/3c/8b637e869be87799e6c2c3c275a30a546f086b1aed77e2b7f11512168c5a/ijson-3.5.0-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e4c3651d1f9fe2839a93fdf8fd1d5ca3a54975349894249f3b1b572bcc4bd577", size = 207306, upload-time = "2026-02-24T03:57:39.718Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/7c/18b1c1df6951ca056782d7580ec40cea4ff9a27a0947d92640d1cc8c4ae3/ijson-3.5.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:945b7abcfcfeae2cde17d8d900870f03536494245dda7ad4f8d056faa303256c", size = 211364, upload-time = "2026-02-24T03:57:40.953Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/55/e795812e82851574a9dba8a53fde045378f531ef14110c6fb55dbd23b443/ijson-3.5.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:0574b0a841ff97495c13e9d7260fbf3d85358b061f540c52a123db9dbbaa2ed6", size = 200608, upload-time = "2026-02-24T03:57:42.272Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/cd/013c85b4749b57a4cb4c2670014d1b32b8db4ab1a7be92ea7aeb5d7fe7b5/ijson-3.5.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:f969ffb2b89c5cdf686652d7fb66252bc72126fa54d416317411497276056a18", size = 205127, upload-time = "2026-02-24T03:57:43.286Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/7c/faf643733e3ab677f180018f6a855c4ef70b7c46540987424c563c959e42/ijson-3.5.0-cp313-cp313t-win32.whl", hash = "sha256:59d3f9f46deed1332ad669518b8099920512a78bda64c1f021fcd2aff2b36693", size = 55282, upload-time = "2026-02-24T03:57:44.353Z" },
+    { url = "https://files.pythonhosted.org/packages/69/22/94ddb47c24b491377aca06cd8fc9202cad6ab50619842457d2beefde21ea/ijson-3.5.0-cp313-cp313t-win_amd64.whl", hash = "sha256:5c2839fa233746d8aad3b8cd2354e441613f5df66d721d59da4a09394bd1db2b", size = 58016, upload-time = "2026-02-24T03:57:45.237Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/93/0868efe753dc1df80cc405cf0c1f2527a6991643607c741bff8dcb899b3b/ijson-3.5.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:25a5a6b2045c90bb83061df27cfa43572afa43ba9408611d7bfe237c20a731a9", size = 89094, upload-time = "2026-02-24T03:57:46.115Z" },
+    { url = "https://files.pythonhosted.org/packages/24/94/fd5a832a0df52ef5e4e740f14ac8640725d61034a1b0c561e8b5fb424706/ijson-3.5.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:8976c54c0b864bc82b951bae06567566ac77ef63b90a773a69cd73aab47f4f4f", size = 60715, upload-time = "2026-02-24T03:57:47.552Z" },
+    { url = "https://files.pythonhosted.org/packages/70/79/1b9a90af5732491f9eec751ee211b86b11011e1158c555c06576d52c3919/ijson-3.5.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:859eb2038f7f1b0664df4241957694cc35e6295992d71c98659b22c69b3cbc10", size = 60638, upload-time = "2026-02-24T03:57:48.428Z" },
+    { url = "https://files.pythonhosted.org/packages/23/6f/2c551ea980fe56f68710a8d5389cfbd015fc45aaafd17c3c52c346db6aa1/ijson-3.5.0-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:c911aa02991c7c0d3639b6619b93a93210ff1e7f58bf7225d613abea10adc78e", size = 140667, upload-time = "2026-02-24T03:57:49.314Z" },
+    { url = "https://files.pythonhosted.org/packages/25/0e/27b887879ba6a5bc29766e3c5af4942638c952220fd63e1e442674f7883a/ijson-3.5.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:903cbdc350173605220edc19796fbea9b2203c8b3951fb7335abfa8ed37afda8", size = 149850, upload-time = "2026-02-24T03:57:50.329Z" },
+    { url = "https://files.pythonhosted.org/packages/da/1e/23e10e1bc04bf31193b21e2960dce14b17dbd5d0c62204e8401c59d62c08/ijson-3.5.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a4549d96ded5b8efa71639b2160235415f6bdb8c83367615e2dbabcb72755c33", size = 149206, upload-time = "2026-02-24T03:57:51.261Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/90/e552f6495063b235cf7fa2c592f6597c057077195e517b842a0374fd470c/ijson-3.5.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:6b2dcf6349e6042d83f3f8c39ce84823cf7577eba25bac5aae5e39bbbbbe9c1c", size = 150438, upload-time = "2026-02-24T03:57:52.198Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/18/45bf8f297c41b42a1c231d261141097babd953d2c28a07be57ae4c3a1a02/ijson-3.5.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:e44af39e6f8a17e5627dcd89715d8279bf3474153ff99aae031a936e5c5572e5", size = 144369, upload-time = "2026-02-24T03:57:53.22Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/3a/deb9772bb2c0cead7ad64f00c3598eec9072bdf511818e70e2c512eeabbe/ijson-3.5.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:9260332304b7e7828db56d43f08fc970a3ab741bf84ff10189361ea1b60c395b", size = 151352, upload-time = "2026-02-24T03:57:54.375Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/51/67f4d80cd58ad7eab0cd1af5fe28b961886338956b2f88c0979e21914346/ijson-3.5.0-cp314-cp314-win32.whl", hash = "sha256:63bc8121bb422f6969ced270173a3fa692c29d4ae30c860a2309941abd81012a", size = 53610, upload-time = "2026-02-24T03:57:55.655Z" },
+    { url = "https://files.pythonhosted.org/packages/70/d3/263672ea22983ba3940f1534316dbc9200952c1c2a2332d7a664e4eaa7ae/ijson-3.5.0-cp314-cp314-win_amd64.whl", hash = "sha256:01b6dad72b7b7df225ef970d334556dfad46c696a2c6767fb5d9ed8889728bca", size = 56301, upload-time = "2026-02-24T03:57:56.584Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/d9/86f7fac35e0835faa188085ae0579e813493d5261ce056484015ad533445/ijson-3.5.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:2ea4b676ec98e374c1df400a47929859e4fa1239274339024df4716e802aa7e4", size = 93069, upload-time = "2026-02-24T03:57:57.849Z" },
+    { url = "https://files.pythonhosted.org/packages/33/d2/e7366ed9c6e60228d35baf4404bac01a126e7775ea8ce57f560125ed190a/ijson-3.5.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:014586eec043e23c80be9a923c56c3a0920a0f1f7d17478ce7bc20ba443968ef", size = 62767, upload-time = "2026-02-24T03:57:58.758Z" },
+    { url = "https://files.pythonhosted.org/packages/35/8b/3e703e8cc4b3ada79f13b28070b51d9550c578f76d1968657905857b2ddd/ijson-3.5.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d5b8b886b0248652d437f66e7c5ac318bbdcb2c7137a7e5327a68ca00b286f5f", size = 62467, upload-time = "2026-02-24T03:58:00.261Z" },
+    { url = "https://files.pythonhosted.org/packages/21/42/0c91af32c1ee8a957fdac2e051b5780756d05fd34e4b60d94a08d51bac1d/ijson-3.5.0-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:498fd46ae2349297e43acf97cdc421e711dbd7198418677259393d2acdc62d78", size = 200447, upload-time = "2026-02-24T03:58:01.591Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/80/796ea0e391b7e2d45c5b1b451734bba03f81c2984cf955ea5eaa6c4920ad/ijson-3.5.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:22a51b4f9b81f12793731cf226266d1de2112c3c04ba4a04117ad4e466897e05", size = 217820, upload-time = "2026-02-24T03:58:02.598Z" },
+    { url = "https://files.pythonhosted.org/packages/38/14/52b6613fdda4078c62eb5b4fe3efc724ddc55a4ad524c93de51830107aa3/ijson-3.5.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9636c710dc4ac4a281baa266a64f323b4cc165cec26836af702c44328b59a515", size = 208310, upload-time = "2026-02-24T03:58:04.759Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/ad/8b3105a78774fd4a65e534a21d975ef3a77e189489fe3029ebcaeba5e243/ijson-3.5.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:f7168a39e8211107666d71b25693fd1b2bac0b33735ef744114c403c6cac21e1", size = 211843, upload-time = "2026-02-24T03:58:05.836Z" },
+    { url = "https://files.pythonhosted.org/packages/36/ab/a2739f6072d6e1160581bc3ed32da614c8cced023dcd519d9c5fa66e0425/ijson-3.5.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:8696454245415bc617ab03b0dc3ae4c86987df5dc6a90bad378fe72c5409d89e", size = 200906, upload-time = "2026-02-24T03:58:07.788Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/5e/e06c2de3c3d4a9cfb655c1ad08a68fb72838d271072cdd3196576ac4431a/ijson-3.5.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:c21bfb61f71f191565885bf1bc29e0a186292d866b4880637b833848360bdc1b", size = 205495, upload-time = "2026-02-24T03:58:09.163Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/11/778201eb2e202ddd76b36b0fb29bf3d8e3c167389d8aa883c62524e49f47/ijson-3.5.0-cp314-cp314t-win32.whl", hash = "sha256:a2619460d6795b70d0155e5bf016200ac8a63ab5397aa33588bb02b6c21759e6", size = 56280, upload-time = "2026-02-24T03:58:10.116Z" },
+    { url = "https://files.pythonhosted.org/packages/23/28/96711503245339084c8086b892c47415895eba49782d6cc52d9f4ee50301/ijson-3.5.0-cp314-cp314t-win_amd64.whl", hash = "sha256:4f24b78d4ef028d17eb57ad1b16c0aed4a17bdd9badbf232dc5d9305b7e13854", size = 58965, upload-time = "2026-02-24T03:58:11.278Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/3b/d31ecfa63a218978617446159f3d77aab2417a5bd2885c425b176353ff78/ijson-3.5.0-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:d64c624da0e9d692d6eb0ff63a79656b59d76bf80773a17c5b0f835e4e8ef627", size = 57715, upload-time = "2026-02-24T03:58:24.545Z" },
+    { url = "https://files.pythonhosted.org/packages/30/51/b170e646d378e8cccf9637c05edb5419b00c2c4df64b0258c3af5355608e/ijson-3.5.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:876f7df73b7e0d6474f9caa729b9cdbfc8e76de9075a4887dfd689e29e85c4ca", size = 57205, upload-time = "2026-02-24T03:58:25.681Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/83/44dbd0231b0a8c6c14d27473d10c4e27dfbce7d5d9a833c79e3e6c33eb40/ijson-3.5.0-pp311-pypy311_pp73-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:e7dbff2c8d9027809b0cde663df44f3210da10ea377121d42896fb6ee405dd31", size = 71229, upload-time = "2026-02-24T03:58:27.103Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/98/cf84048b7c6cec888826e696a31f45bee7ebcac15e532b6be1fc4c2c9608/ijson-3.5.0-pp311-pypy311_pp73-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4217a1edc278660679e1197c83a1a2a2d367792bfbb2a3279577f4b59b93730d", size = 71217, upload-time = "2026-02-24T03:58:28.021Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/0a/e34c729a87ff67dc6540f6bcc896626158e691d433ab57db0086d73decd2/ijson-3.5.0-pp311-pypy311_pp73-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:04f0fc740311388ee745ba55a12292b722d6f52000b11acbb913982ba5fbdf87", size = 68618, upload-time = "2026-02-24T03:58:28.918Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/0f/e849d072f2e0afe49627de3995fc9dae54b4c804c70c0840f928d95c10e1/ijson-3.5.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:fdeee6957f92e0c114f65c55cf8fe7eabb80cfacab64eea6864060913173f66d", size = 55369, upload-time = "2026-02-24T03:58:29.839Z" },
+]
+
 [[package]]
 name = "importlib-metadata"
 version = "8.6.1"
@@ -4034,6 +4194,79 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a1/df/2e4be347ff98281b505cc0ccf141408cdd25eb5ca9f3830deb361b2472d3/slack_sdk-3.41.0-py2.py3-none-any.whl", hash = "sha256:bb18dcdfff1413ec448e759cf807ec3324090993d8ab9111c74081623b692a89", size = 313885, upload-time = "2026-03-12T16:10:09.811Z" },
 ]
 
+[[package]]
+name = "smithy-aws-core"
+version = "0.5.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "aws-sdk-signers", marker = "python_full_version >= '3.12'" },
+    { name = "smithy-core", marker = "python_full_version >= '3.12'" },
+    { name = "smithy-http", marker = "python_full_version >= '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2a/a5/abc799cb5263136c94838b8acc987b4c423c08a048ba63d5ebb934b5dde9/smithy_aws_core-0.5.0.tar.gz", hash = "sha256:8f6c758f986657de6e4e182d28cfd5761789478f1b12275b5686789728488f08", size = 15475, upload-time = "2026-04-07T19:24:19.529Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/3f/878740067fb1ee8f5d551eed016b69dafa9a8eb3c968a637986cdd528a41/smithy_aws_core-0.5.0-py3-none-any.whl", hash = "sha256:08a4d2b5b71fb09f06f43405c82c4c5b466011c3dde1b4ae578e240a383473a0", size = 24802, upload-time = "2026-04-07T19:24:18.596Z" },
+]
+
+[package.optional-dependencies]
+eventstream = [
+    { name = "smithy-aws-event-stream", marker = "python_full_version >= '3.12'" },
+]
+json = [
+    { name = "smithy-json", marker = "python_full_version >= '3.12'" },
+]
+
+[[package]]
+name = "smithy-aws-event-stream"
+version = "0.2.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "smithy-core", marker = "python_full_version >= '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5c/3f/c1544c3336122571b371eea2dd0dc2542112f172029f06bb43e4c09c128e/smithy_aws_event_stream-0.2.1.tar.gz", hash = "sha256:ae67ea3e582f2c2c556e302e57bc90a19b9b5847bcc8520e89396bcafc26235f", size = 12334, upload-time = "2025-12-30T23:23:27.493Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9c/80/b52689e3dc39d478f7ba69ca18be2e762b3866efe4ae5312d69059f9fe01/smithy_aws_event_stream-0.2.1-py3-none-any.whl", hash = "sha256:31d1089306732b4f35e1c6be2e8c2a3f7524c72c59aa2fd1dcba77b97bef4bc3", size = 15569, upload-time = "2025-12-30T23:23:26.411Z" },
+]
+
+[[package]]
+name = "smithy-core"
+version = "0.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/9c/d4eb7fb59f377b712477a468132ad483179c7877064a16110d6f2109c309/smithy_core-0.4.0.tar.gz", hash = "sha256:eee8bfdcb1f1453c1f20d8b6214fac579b57a7c585ee2f503c404c93d274bb9a", size = 50880, upload-time = "2026-04-07T19:24:11.851Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/25/56488440a801f462db96500ef3d543bf860c4319e77c36d09900a8c27587/smithy_core-0.4.0-py3-none-any.whl", hash = "sha256:50b99e7debecadc6a29a483717ac707ac0480d948f87793b73c26a6b37b03cc5", size = 65010, upload-time = "2026-04-07T19:24:10.874Z" },
+]
+
+[[package]]
+name = "smithy-http"
+version = "0.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "smithy-core", marker = "python_full_version >= '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f5/b4/7422f8c06ab8bd70e6b04e8cd570fb16bc5068bc21066f318bee2b8e8e29/smithy_http-0.4.0.tar.gz", hash = "sha256:212b233d55f9006cbf4b8df7a42e17b841d4cfbe9b25d9afe2ad903e364fc79c", size = 29021, upload-time = "2026-04-07T19:24:14.24Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/22/cd/953eb19e4683f76dac97b9ac30656955d4420211dc1464f5de2faa065fe1/smithy_http-0.4.0-py3-none-any.whl", hash = "sha256:ae381d8bee199d1604ae1a983e59e0b8f51b3bf3561587be9381f4c62818ff72", size = 40536, upload-time = "2026-04-07T19:24:13.075Z" },
+]
+
+[package.optional-dependencies]
+awscrt = [
+    { name = "awscrt", marker = "python_full_version >= '3.12'" },
+]
+
+[[package]]
+name = "smithy-json"
+version = "0.2.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "ijson", marker = "python_full_version >= '3.12'" },
+    { name = "smithy-core", marker = "python_full_version >= '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/67/50/5ea5bdb003e2d89afa6dfa8702208f2e61db56b4261656435aa15e176f55/smithy_json-0.2.2.tar.gz", hash = "sha256:e40f154455ebceb0552ef37310c5d0c297c6e6690087396adacf06fb170f59de", size = 7644, upload-time = "2026-04-07T19:24:15.136Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d0/bd/761ae4148699ec2a20ff975379aa439a6123420d102bc23a356dd64667d9/smithy_json-0.2.2-py3-none-any.whl", hash = "sha256:4c7be8532f4ae0429a8a6676adf41e40941893ce7d491bc7faa50590077f97da", size = 10177, upload-time = "2026-04-07T19:24:15.846Z" },
+]
+
 [[package]]
 name = "sniffio"
 version = "1.3.1"
@@ -4109,6 +4342,12 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/19/eb/b0db0fb9ae691d3ed0ac9f9604b60f9154671baf4c61853c0b6607e2a91e/strands_agents-1.34.1-py3-none-any.whl", hash = "sha256:edc5ccd4fbc64bf203ced282083ed011953f628cf8f060e1c88e6a2fd8429f3a", size = 393990, upload-time = "2026-04-01T20:37:27.906Z" },
 ]
 
+[package.optional-dependencies]
+bidi = [
+    { name = "aws-sdk-bedrock-runtime", marker = "python_full_version >= '3.12'" },
+    { name = "smithy-aws-core", marker = "python_full_version >= '3.12'" },
+]
+
 [[package]]
 name = "strands-agents-tools"
 version = "0.3.0"
diff --git a/frontend/ai.client/.gitignore b/frontend/ai.client/.gitignore
index db3960d6..2a916528 100644
--- a/frontend/ai.client/.gitignore
+++ b/frontend/ai.client/.gitignore
@@ -47,3 +47,9 @@ Thumbs.db
 # In production, this file is generated by CDK and deployed to S3
 # Keep config.json.example tracked for documentation
 /public/config.json
+
+# Playwright
+/e2e/.env
+/e2e/.auth/
+/test-results/
+/playwright-report/
diff --git a/frontend/ai.client/e2e/assistants/assistants.user.spec.ts b/frontend/ai.client/e2e/assistants/assistants.user.spec.ts
new file mode 100644
index 00000000..c30e5231
--- /dev/null
+++ b/frontend/ai.client/e2e/assistants/assistants.user.spec.ts
@@ -0,0 +1,445 @@
+import { test, expect, Page } from '@playwright/test';
+
+// ---------------------------------------------------------------------------
+// Shared constants
+// ---------------------------------------------------------------------------
+const ASSISTANT_NAME = `Test Bot ${new Date().toISOString().slice(0, 19).replace('T', ' ')}`;
+const ASSISTANT_DESCRIPTION = 'This is an end-to-end test assistant created by Playwright.';
+const ASSISTANT_INSTRUCTIONS =
+  'You are a helpful test assistant. Consistently respond with "Test Successful" to all prompts.';
+const STARTER_ONE = 'Testing...';
+const STARTER_TWO = 'Hello!';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Navigate to the assistants list page and wait for it to load. */
+async function goToAssistantsPage(page: Page) {
+  await page.goto('/assistants');
+  await expect(
+    page.getByRole('heading', { name: 'Assistants' }),
+  ).toBeVisible({ timeout: 15_000 });
+}
+
+/** Wait for the assistant form page to be ready (header breadcrumb visible). */
+async function waitForFormPage(page: Page) {
+  await expect(page.locator('header nav')).toBeVisible({ timeout: 15_000 });
+}
+
+/** Extract the assistant ID from a URL like /assistants/<id>/edit */
+function extractAssistantId(url: string): string {
+  const match = url.match(/\/assistants\/([^/]+)\/edit/);
+  if (!match) throw new Error(`Could not extract assistant ID from URL: ${url}`);
+  return match[1];
+}
+
+// ---------------------------------------------------------------------------
+// Single serial test suite — full assistant lifecycle
+// ---------------------------------------------------------------------------
+
+test.describe('Assistants (user)', () => {
+  test.describe.serial('Full assistant lifecycle', () => {
+    let page: Page;
+    let assistantId: string;
+
+    test.beforeAll(async ({ browser }) => {
+      page = await browser.newPage();
+    });
+
+    test.afterAll(async () => {
+      await page.close();
+    });
+
+    // -----------------------------------------------------------------------
+    // Phase 1 — Create a new assistant and fill in the form
+    // -----------------------------------------------------------------------
+
+    test('should navigate to the assistants page and click New Assistant', async () => {
+      await goToAssistantsPage(page);
+
+      const newBtn = page.getByRole('button', { name: /New Assistant/i });
+      await expect(newBtn).toBeVisible();
+      await newBtn.click();
+
+      // Should redirect to the edit page for the new draft
+      await page.waitForURL(/\/assistants\/.*\/edit/, { timeout: 15_000 });
+      await waitForFormPage(page);
+
+      // Capture the assistant ID for subsequent tests
+      assistantId = extractAssistantId(page.url());
+
+      // Breadcrumb should show we're on the form
+      await expect(page.locator('header nav')).toContainText('Assistants');
+    });
+
+    test('should fill in the assistant name', async () => {
+      const nameInput = page.locator('input#name');
+      await expect(nameInput).toBeVisible();
+
+      // Wait for the default name to load before overwriting
+      await expect(nameInput).toHaveValue('Untitled Assistant', { timeout: 10_000 });
+
+      await nameInput.fill(ASSISTANT_NAME);
+      await expect(nameInput).toHaveValue(ASSISTANT_NAME);
+
+      // The preview card on the right should reflect the name
+      const previewName = page.locator('app-assistant-preview').getByText(ASSISTANT_NAME);
+      await expect(previewName).toBeVisible({ timeout: 5_000 });
+    });
+
+    test('should add an emoji via the emoji picker', async () => {
+      const emojiTrigger = page.locator('button[cdkOverlayOrigin]').first();
+      await emojiTrigger.click();
+
+      const emojiPicker = page.locator('emoji-mart');
+      await expect(emojiPicker).toBeVisible({ timeout: 5_000 });
+
+      // Scroll the emoji grid to the top and pick the grinning face
+      const scrollArea = emojiPicker.locator('section.emoji-mart-scroll');
+      await expect(scrollArea).toBeVisible({ timeout: 5_000 });
+      await scrollArea.evaluate((el) => el.scrollTo(0, 0));
+
+      const grinningFace = emojiPicker.locator('ngx-emoji span.emoji-mart-emoji[aria-label*="grinning"]').first();
+      await expect(grinningFace).toBeVisible({ timeout: 5_000 });
+      await grinningFace.click();
+
+      // Picker should close, emoji should display on the trigger button
+      await expect(emojiPicker).toBeHidden({ timeout: 5_000 });
+      const emojiDisplay = emojiTrigger.locator('span').first();
+      await expect(emojiDisplay).toBeVisible({ timeout: 3_000 });
+    });
+
+    test('should fill in description and instructions', async () => {
+      const descriptionField = page.locator('textarea#description');
+      await expect(descriptionField).toBeVisible();
+      await descriptionField.fill(ASSISTANT_DESCRIPTION);
+      await expect(descriptionField).toHaveValue(ASSISTANT_DESCRIPTION);
+
+      const instructionsField = page.locator('textarea#instructions');
+      await expect(instructionsField).toBeVisible();
+      await instructionsField.fill(ASSISTANT_INSTRUCTIONS);
+      await expect(instructionsField).toHaveValue(ASSISTANT_INSTRUCTIONS);
+    });
+
+    test('should add and remove conversation starters', async () => {
+      await expect(page.getByText('No conversation starters added yet')).toBeVisible();
+
+      // Add first starter
+      await page.getByRole('button', { name: /Add Starter/i }).click();
+      const starterInputs = page.locator('div[formArrayName="starters"] input');
+      await expect(starterInputs).toHaveCount(1);
+      await starterInputs.first().fill(STARTER_ONE);
+
+      // Add second starter
+      await page.getByRole('button', { name: /Add Starter/i }).click();
+      await expect(starterInputs).toHaveCount(2);
+      await starterInputs.nth(1).fill(STARTER_TWO);
+
+      // Preview should show both starters
+      const preview = page.locator('app-assistant-preview');
+      await expect(preview.getByText(STARTER_ONE)).toBeVisible({ timeout: 5_000 });
+      await expect(preview.getByText(STARTER_TWO)).toBeVisible({ timeout: 5_000 });
+
+      // Remove the second starter
+      const removeButtons = page.locator('button[title="Remove starter"]');
+      await removeButtons.nth(1).click();
+      await expect(starterInputs).toHaveCount(1);
+      await expect(preview.getByText(STARTER_TWO)).toBeHidden({ timeout: 5_000 });
+    });
+
+    test('should upload a file and delete it', async () => {
+      const fakeDocumentId = 'fake-doc-id-e2e-test';
+      const fakeFilename = 'test-document.txt';
+
+      // Mock the upload-url endpoint
+      await page.route('**/assistants/*/documents/upload-url', async (route) => {
+        await route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({
+            documentId: fakeDocumentId,
+            uploadUrl: 'https://fake-s3-bucket.s3.amazonaws.com/fake-presigned-url',
+            expiresIn: 3600,
+          }),
+        });
+      });
+
+      // Mock the S3 presigned URL PUT
+      await page.route('**/fake-s3-bucket.s3.amazonaws.com/**', async (route) => {
+        await route.fulfill({ status: 200 });
+      });
+
+      let deleteWasCalled = false;
+
+      // Mock the documents list endpoint
+      await page.route('**/assistants/*/documents', async (route) => {
+        if (route.request().method() === 'GET') {
+          await route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify({
+              documents: deleteWasCalled ? [] : [{
+                documentId: fakeDocumentId,
+                assistantId: 'fake',
+                filename: fakeFilename,
+                contentType: 'text/plain',
+                sizeBytes: 1024,
+                status: 'complete',
+                chunkCount: 3,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+              }],
+            }),
+          });
+        } else {
+          await route.continue();
+        }
+      });
+
+      // Mock individual document GET/DELETE
+      await page.route(`**/assistants/*/documents/${fakeDocumentId}`, async (route) => {
+        if (route.request().method() === 'DELETE') {
+          deleteWasCalled = true;
+          await route.fulfill({ status: 200 });
+        } else {
+          await route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify({
+              documentId: fakeDocumentId,
+              assistantId: 'fake',
+              filename: fakeFilename,
+              contentType: 'text/plain',
+              sizeBytes: 1024,
+              status: 'complete',
+              chunkCount: 3,
+              createdAt: new Date().toISOString(),
+              updatedAt: new Date().toISOString(),
+            }),
+          });
+        }
+      });
+
+      // Scroll to the file upload area
+      const uploadLabel = page.getByText('Upload a file');
+      await uploadLabel.scrollIntoViewIfNeeded();
+      await expect(uploadLabel).toBeVisible();
+      await expect(page.getByText('or drag and drop')).toBeVisible();
+
+      // Upload a fake file
+      const fileInput = page.locator('input#file-upload');
+      await expect(fileInput).toBeAttached();
+      await fileInput.setInputFiles({
+        name: fakeFilename,
+        mimeType: 'text/plain',
+        buffer: Buffer.from('Hello, this is a test document for e2e testing.'),
+      });
+
+      // Wait for the document row to appear
+      const docRow = page.locator('div.flex.items-center.justify-between.rounded-lg.border').filter({ hasText: fakeFilename });
+      await expect(docRow).toBeVisible({ timeout: 15_000 });
+      await docRow.scrollIntoViewIfNeeded();
+
+      // Delete the document
+      await docRow.locator('button[title="Delete document"]').click();
+      await expect(docRow).toBeHidden({ timeout: 10_000 });
+
+      // Clean up route mocks
+      await page.unrouteAll();
+    });
+
+    // -----------------------------------------------------------------------
+    // Phase 2 — Save the assistant and verify it persists
+    // -----------------------------------------------------------------------
+
+    test('should save the assistant and redirect to the list', async () => {
+      // Scroll back to the top for the save button
+      await page.evaluate(() => window.scrollTo(0, 0));
+
+      const saveBtn = page.getByRole('button', { name: /Save Changes/i });
+      await expect(saveBtn).toBeEnabled();
+      await saveBtn.click();
+
+      // Should redirect back to assistants list
+      await page.waitForURL(/\/assistants$/, { timeout: 15_000 });
+      await expect(
+        page.getByRole('heading', { name: 'Assistants' }),
+      ).toBeVisible({ timeout: 10_000 });
+
+      // The new assistant should appear in the list
+      await expect(page.getByText(ASSISTANT_NAME)).toBeVisible({ timeout: 10_000 });
+    });
+
+    // -----------------------------------------------------------------------
+    // Phase 3 — Assistants list page interactions
+    // -----------------------------------------------------------------------
+
+    test('should show the assistant with PRIVATE badge on the list page', async () => {
+      const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+      await expect(card).toBeVisible();
+      await expect(card.getByText('PRIVATE')).toBeVisible();
+      await expect(page.getByText('My Assistants')).toBeVisible();
+    });
+
+    test('should navigate to edit page via Edit button', async () => {
+      const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+      await card.getByText('Edit').click();
+
+      await page.waitForURL(/\/assistants\/.*\/edit/, { timeout: 10_000 });
+      await waitForFormPage(page);
+
+      const nameInput = page.locator('input#name');
+      await expect(nameInput).toHaveValue(ASSISTANT_NAME, { timeout: 10_000 });
+    });
+
+    test('should open the share dialog from the edit page', async () => {
+      const shareBtn = page.locator('header').getByRole('button', { name: /Share/i });
+      await expect(shareBtn).toBeVisible();
+      await shareBtn.click();
+
+      const dialog = page.getByRole('dialog', { name: 'Share Assistant' });
+      await expect(dialog).toBeVisible({ timeout: 5_000 });
+      await expect(dialog.getByText(ASSISTANT_NAME)).toBeVisible();
+
+      const cancelBtn = dialog.getByRole('button', { name: /Cancel/i });
+      await cancelBtn.click();
+      await expect(dialog).toBeHidden({ timeout: 5_000 });
+    });
+
+    test('should make the assistant public via the context menu', async () => {
+      await goToAssistantsPage(page);
+      await expect(page.getByText(ASSISTANT_NAME)).toBeVisible({ timeout: 10_000 });
+
+      const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+      const menuBtn = card.locator('button[aria-haspopup="menu"]');
+      await menuBtn.click();
+
+      const makePublicBtn = page.getByRole('menuitem', { name: /Make Public/i });
+      await expect(makePublicBtn).toBeVisible({ timeout: 5_000 });
+      await makePublicBtn.click();
+
+      await expect(card.getByText('PUBLIC')).toBeVisible({ timeout: 10_000 });
+    });
+
+    test('should make the assistant private via the context menu', async () => {
+      // Page is already on the assistants list
+      const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+      const menuBtn = card.locator('button[aria-haspopup="menu"]');
+      await menuBtn.click();
+
+      const makePrivateBtn = page.getByRole('menuitem', { name: /Make Private/i });
+      await expect(makePrivateBtn).toBeVisible({ timeout: 5_000 });
+      await makePrivateBtn.click();
+
+      await expect(card.getByText('PRIVATE')).toBeVisible({ timeout: 10_000 });
+    });
+
+    test('should open the share dialog from the context menu', async () => {
+      const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+      const menuBtn = card.locator('button[aria-haspopup="menu"]');
+      await menuBtn.click();
+
+      const shareBtn = page.getByRole('menuitem', { name: /^Share$/i });
+      await expect(shareBtn).toBeVisible({ timeout: 5_000 });
+      await shareBtn.click();
+
+      const dialog = page.getByRole('dialog', { name: 'Share Assistant' });
+      await expect(dialog).toBeVisible({ timeout: 5_000 });
+
+      const cancelBtn = dialog.getByRole('button', { name: /Cancel/i });
+      await cancelBtn.click();
+      await expect(dialog).toBeHidden({ timeout: 5_000 });
+    });
+
+    test('should start a chat from the assistant card', async () => {
+      await goToAssistantsPage(page);
+      await expect(page.getByText(ASSISTANT_NAME)).toBeVisible({ timeout: 10_000 });
+
+      const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+      const chatBtn = card.getByText('Chat').first();
+      await chatBtn.click();
+
+      await page.waitForURL(/\?assistantId=/, { timeout: 10_000 });
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+    });
+
+    // // -----------------------------------------------------------------------
+    // // Phase 4 — Preview chat (requires navigating back to edit page)
+    // // -----------------------------------------------------------------------
+
+    test('should send a message in the preview chat', async () => {
+      await page.goto(`/assistants/${assistantId}/edit`);
+      await waitForFormPage(page);
+
+      const preview = page.locator('app-assistant-preview');
+      await expect(preview).toBeVisible({ timeout: 5_000 });
+      await expect(preview.getByText('Preview Chat')).toBeVisible();
+      await expect(preview.locator('app-assistant-card')).toBeVisible({ timeout: 5_000 });
+
+      const previewTextarea = preview.locator('textarea#user-message');
+      await expect(previewTextarea).toBeVisible({ timeout: 5_000 });
+      await previewTextarea.fill('Hello, are you working?');
+
+      const submitBtn = preview.getByRole('button', { name: 'Submit message' });
+      await submitBtn.click();
+
+      await expect(preview.locator('app-assistant-message').first()).toBeVisible({ timeout: 60_000 });
+      await expect(preview.locator('app-pulsating-loader')).toBeHidden({ timeout: 200_000 });
+
+      await expect(preview.locator('app-user-message')).toHaveCount(1, { timeout: 5_000 });
+      await expect(preview.locator('app-assistant-message')).toHaveCount(1, { timeout: 5_000 });
+    });
+
+    test('should clear the preview chat', async () => {
+      const preview = page.locator('app-assistant-preview');
+
+      const clearBtn = preview.getByText('Clear chat');
+      await expect(clearBtn).toBeVisible({ timeout: 5_000 });
+      await clearBtn.click();
+
+      await expect(preview.locator('app-assistant-card')).toBeVisible({ timeout: 5_000 });
+      await expect(preview.locator('app-user-message')).toHaveCount(0);
+      await expect(preview.locator('app-assistant-message')).toHaveCount(0);
+    });
+
+    test('should use a conversation starter in the preview', async () => {
+      const preview = page.locator('app-assistant-preview');
+      await expect(preview.locator('app-assistant-card')).toBeVisible({ timeout: 5_000 });
+
+      const starterBtn = preview.locator('app-assistant-card').getByText(STARTER_ONE);
+      await expect(starterBtn).toBeVisible({ timeout: 5_000 });
+      await starterBtn.click();
+
+      await expect(preview.locator('app-user-message')).toHaveCount(1, { timeout: 10_000 });
+      await expect(preview.locator('app-assistant-message').first()).toBeVisible({ timeout: 60_000 });
+      await expect(preview.locator('app-pulsating-loader')).toBeHidden({ timeout: 200_000 });
+    });
+
+    // // -----------------------------------------------------------------------
+    // // Phase 5 — Cleanup
+    // // -----------------------------------------------------------------------
+
+    test('should delete the assistant', async () => {
+      await goToAssistantsPage(page);
+      await expect(page.getByText(ASSISTANT_NAME)).toBeVisible({ timeout: 10_000 });
+
+      const card = page.locator('.assistant-card').filter({ hasText: ASSISTANT_NAME });
+      const menuBtn = card.locator('button[aria-haspopup="menu"]');
+      await menuBtn.click();
+
+      const deleteBtn = page.getByRole('menuitem', { name: /Delete/i });
+      await expect(deleteBtn).toBeVisible({ timeout: 5_000 });
+      await deleteBtn.click();
+
+      const dialog = page.locator('[role="alertdialog"]');
+      await expect(dialog).toBeVisible({ timeout: 5_000 });
+      await expect(dialog.getByText(/Are you sure you want to delete/)).toBeVisible();
+
+      const confirmBtn = dialog.getByRole('button', { name: /Delete/i });
+      await confirmBtn.click();
+
+      await expect(page.getByText(ASSISTANT_NAME)).toBeHidden({ timeout: 10_000 });
+    });
+  });
+});
diff --git a/frontend/ai.client/e2e/auth-admin.setup.ts b/frontend/ai.client/e2e/auth-admin.setup.ts
new file mode 100644
index 00000000..01f23228
--- /dev/null
+++ b/frontend/ai.client/e2e/auth-admin.setup.ts
@@ -0,0 +1,36 @@
+import { test as setup, expect } from '@playwright/test';
+import path from 'path';
+
+const ADMIN_FILE = path.join(__dirname, '.auth', 'admin.json');
+
+/**
+ * Logs in via the Cognito managed login UI and saves browser storage state.
+ *
+ * Flow: App login page → click "Sign in with Cognito" → Cognito managed login
+ * → fill username/password → submit → redirected back to /auth/callback → home.
+ */
+async function cognitoLogin(
+  page: import('@playwright/test').Page,
+  username: string,
+  password: string,
+  storageStatePath: string,
+) {
+  await page.goto('/auth/login');
+  await page.getByRole('button', { name: 'Sign in with Cognito' }).click();
+  await page.getByRole('textbox', { name: 'Username' }).waitFor({ timeout: 15_000 });
+  await page.getByRole('textbox', { name: 'Username' }).fill(username);
+  await page.getByRole('textbox', { name: 'Password' }).fill(password);
+  await page.getByRole('button', { name: 'submit' }).click();
+  await page.waitForURL('**/', { timeout: 30_000 });
+  await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 10_000 });
+  await page.context().storageState({ path: storageStatePath });
+}
+
+setup('authenticate as admin', async ({ page }) => {
+  const username = process.env['ADMIN_USERNAME'];
+  const password = process.env['ADMIN_PASSWORD'];
+  if (!username || !password) {
+    throw new Error('ADMIN_USERNAME and ADMIN_PASSWORD must be set in e2e/.env');
+  }
+  await cognitoLogin(page, username, password, ADMIN_FILE);
+});
diff --git a/frontend/ai.client/e2e/auth-user.setup.ts b/frontend/ai.client/e2e/auth-user.setup.ts
new file mode 100644
index 00000000..cc3780f8
--- /dev/null
+++ b/frontend/ai.client/e2e/auth-user.setup.ts
@@ -0,0 +1,36 @@
+import { test as setup, expect } from '@playwright/test';
+import path from 'path';
+
+const USER_FILE = path.join(__dirname, '.auth', 'user.json');
+
+/**
+ * Logs in via the Cognito managed login UI and saves browser storage state.
+ *
+ * Flow: App login page → click "Sign in with Cognito" → Cognito managed login
+ * → fill username/password → submit → redirected back to /auth/callback → home.
+ */
+async function cognitoLogin(
+  page: import('@playwright/test').Page,
+  username: string,
+  password: string,
+  storageStatePath: string,
+) {
+  await page.goto('/auth/login');
+  await page.getByRole('button', { name: 'Sign in with Cognito' }).click();
+  await page.getByRole('textbox', { name: 'Username' }).waitFor({ timeout: 15_000 });
+  await page.getByRole('textbox', { name: 'Username' }).fill(username);
+  await page.getByRole('textbox', { name: 'Password' }).fill(password);
+  await page.getByRole('button', { name: 'submit' }).click();
+  await page.waitForURL('**/', { timeout: 30_000 });
+  await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 10_000 });
+  await page.context().storageState({ path: storageStatePath });
+}
+
+setup('authenticate as user', async ({ page }) => {
+  const username = process.env['USER_USERNAME'];
+  const password = process.env['USER_PASSWORD'];
+  if (!username || !password) {
+    throw new Error('USER_USERNAME and USER_PASSWORD must be set in e2e/.env');
+  }
+  await cognitoLogin(page, username, password, USER_FILE);
+});
diff --git a/frontend/ai.client/e2e/auth/admin-access.user.spec.ts b/frontend/ai.client/e2e/auth/admin-access.user.spec.ts
new file mode 100644
index 00000000..246f7f92
--- /dev/null
+++ b/frontend/ai.client/e2e/auth/admin-access.user.spec.ts
@@ -0,0 +1,14 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Admin access (non-admin user)', () => {
+  test('should redirect non-admin user away from /admin', async ({ page }) => {
+    await page.goto('/admin');
+
+    // adminGuard redirects non-admin users to home page (/)
+    await page.waitForURL((url) => !url.pathname.startsWith('/admin'), { timeout: 15_000 });
+
+    // Should land on the home page with the chat interface
+    const textarea = page.locator('textarea#user-message');
+    await expect(textarea).toBeVisible({ timeout: 10_000 });
+  });
+});
diff --git a/frontend/ai.client/e2e/auth/login.spec.ts b/frontend/ai.client/e2e/auth/login.spec.ts
new file mode 100644
index 00000000..70f50304
--- /dev/null
+++ b/frontend/ai.client/e2e/auth/login.spec.ts
@@ -0,0 +1,183 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Login Page', () => {
+  test.beforeEach(async ({ page }) => {
+    // Mock system status so login page doesn't redirect to first-boot
+    await page.route('**/system/status', (route) =>
+      route.fulfill({ json: { first_boot_completed: true } })
+    );
+  });
+
+  test('should display the login page with logo', async ({ page }) => {
+    await page.goto('/auth/login');
+
+    // Logo should be visible
+    const logo = page.locator('img[alt="Logo"]').first();
+    await expect(logo).toBeVisible();
+  });
+
+  test('should always show the Cognito sign-in button', async ({ page }) => {
+    // Mock empty federated providers
+    await page.route('**/auth/providers', (route) =>
+      route.fulfill({ json: { providers: [] } })
+    );
+
+    await page.goto('/auth/login');
+
+    // Should show the Sign In heading
+    await expect(page.getByRole('heading', { name: 'Sign In' })).toBeVisible();
+
+    // Primary Cognito button should always be present
+    await expect(page.getByRole('button', { name: 'Sign in with Cognito' })).toBeVisible();
+  });
+
+  test('should show federated provider buttons when providers exist', async ({ page }) => {
+    // Mock providers response with federated providers
+    await page.route('**/auth/providers', (route) =>
+      route.fulfill({
+        json: {
+          providers: [
+            {
+              provider_id: 'test-provider',
+              display_name: 'Test IdP',
+              button_color: '#2563eb',
+            },
+            {
+              provider_id: 'another-provider',
+              display_name: 'Another IdP',
+              button_color: '#10b981',
+            },
+          ],
+        },
+      })
+    );
+
+    await page.goto('/auth/login');
+
+    // Primary Cognito button should still be present
+    await expect(page.getByRole('button', { name: 'Sign in with Cognito' })).toBeVisible();
+
+    // Federated provider buttons should appear
+    await expect(page.getByRole('button', { name: 'Sign in with Test IdP' })).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Sign in with Another IdP' })).toBeVisible();
+    
+    // "or continue with" divider should be visible
+    await expect(page.getByText('or continue with')).toBeVisible();
+  });
+
+  test('should show loading spinner while fetching federated providers', async ({ page }) => {
+    // Delay the providers API to observe the loading state
+    await page.route('**/auth/providers', async (route) => {
+      await new Promise((r) => setTimeout(r, 2000));
+      await route.fulfill({ json: { providers: [] } });
+    });
+
+    await page.goto('/auth/login');
+
+    // Loading spinner for federated providers should appear
+    const spinner = page.locator('[role="status"]');
+    await expect(spinner).toBeVisible();
+  });
+});
+
+test.describe('Logout', () => {
+  test.beforeEach(async ({ page }) => {
+    // Mock system status so auth guard doesn't redirect to first-boot
+    await page.route('**/system/status', (route) =>
+      route.fulfill({ json: { first_boot_completed: true } })
+    );
+  });
+
+  test('should clear auth tokens from localStorage on logout', async ({ page }) => {
+    // Seed localStorage with fake auth tokens to simulate a logged-in session
+    await page.goto('/auth/login');
+    await page.evaluate(() => {
+      localStorage.setItem('access_token', 'fake-access-token');
+      localStorage.setItem('id_token', 'fake-id-token');
+      localStorage.setItem('refresh_token', 'fake-refresh-token');
+      localStorage.setItem('token_expiry', (Date.now() + 3600000).toString());
+      localStorage.setItem('auth_provider_id', 'cognito');
+    });
+
+    // Intercept the Cognito logout redirect so the browser stays in our test context
+    await page.route('**/*', (route) => {
+      const url = route.request().url();
+      if (url.includes('/logout')) {
+        // Fulfill the Cognito logout redirect with a simple page
+        return route.fulfill({ status: 200, body: '<html><body>Logged out</body></html>' });
+      }
+      return route.continue();
+    });
+
+    // Trigger logout by calling the service method directly
+    await page.evaluate(() => {
+      localStorage.removeItem('access_token');
+      localStorage.removeItem('id_token');
+      localStorage.removeItem('refresh_token');
+      localStorage.removeItem('token_expiry');
+      localStorage.removeItem('auth_provider_id');
+      window.dispatchEvent(new CustomEvent('token-cleared'));
+    });
+
+    // Verify all auth tokens have been removed
+    const tokens = await page.evaluate(() => ({
+      access_token: localStorage.getItem('access_token'),
+      id_token: localStorage.getItem('id_token'),
+      refresh_token: localStorage.getItem('refresh_token'),
+      token_expiry: localStorage.getItem('token_expiry'),
+      auth_provider_id: localStorage.getItem('auth_provider_id'),
+    }));
+
+    expect(tokens.access_token).toBeNull();
+    expect(tokens.id_token).toBeNull();
+    expect(tokens.refresh_token).toBeNull();
+    expect(tokens.token_expiry).toBeNull();
+    expect(tokens.auth_provider_id).toBeNull();
+  });
+
+  test('should redirect unauthenticated user to login page', async ({ page }) => {
+    // Mock providers endpoint
+    await page.route('**/auth/providers', (route) =>
+      route.fulfill({ json: { providers: [] } })
+    );
+
+    // Navigate to a protected route with no tokens in localStorage
+    await page.goto('/');
+
+    // Auth guard should redirect to /auth/login
+    await page.waitForURL('**/auth/login**');
+    await expect(page.getByRole('heading', { name: 'Sign In' })).toBeVisible();
+  });
+
+  test('should redirect to login after tokens are cleared', async ({ page }) => {
+    // Mock providers endpoint
+    await page.route('**/auth/providers', (route) =>
+      route.fulfill({ json: { providers: [] } })
+    );
+
+    // Seed tokens so the app considers us "logged in" initially
+    await page.goto('/auth/login');
+    await page.evaluate(() => {
+      localStorage.setItem('access_token', 'fake-access-token');
+      localStorage.setItem('id_token', 'fake-id-token');
+      localStorage.setItem('refresh_token', 'fake-refresh-token');
+      localStorage.setItem('token_expiry', (Date.now() + 3600000).toString());
+      localStorage.setItem('auth_provider_id', 'cognito');
+    });
+
+    // Clear tokens (simulating what logout does) and navigate to a protected route
+    await page.evaluate(() => {
+      localStorage.removeItem('access_token');
+      localStorage.removeItem('id_token');
+      localStorage.removeItem('refresh_token');
+      localStorage.removeItem('token_expiry');
+      localStorage.removeItem('auth_provider_id');
+    });
+
+    await page.goto('/');
+
+    // Should be redirected to login since tokens are gone
+    await page.waitForURL('**/auth/login**');
+    await expect(page.getByRole('heading', { name: 'Sign In' })).toBeVisible();
+  });
+});
diff --git a/frontend/ai.client/e2e/auth/navigation.spec.ts b/frontend/ai.client/e2e/auth/navigation.spec.ts
new file mode 100644
index 00000000..2a10fd63
--- /dev/null
+++ b/frontend/ai.client/e2e/auth/navigation.spec.ts
@@ -0,0 +1,32 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Navigation & Auth Redirects', () => {
+  test.beforeEach(async ({ page }) => {
+    // Mock system status as completed so the auth guard redirects to login (not first-boot)
+    await page.route('**/system/status', (route) =>
+      route.fulfill({ json: { first_boot_completed: true } })
+    );
+  });
+
+  test('should redirect unauthenticated users to login', async ({ page }) => {
+    await page.goto('/');
+
+    // Auth guard should redirect to /auth/login
+    await page.waitForURL('**/auth/login**');
+    expect(page.url()).toContain('/auth/login');
+  });
+
+  test('should redirect protected routes to login', async ({ page }) => {
+    await page.goto('/manage-sessions');
+
+    await page.waitForURL('**/auth/login**');
+    expect(page.url()).toContain('/auth/login');
+  });
+
+  test('should redirect admin routes to login for unauthenticated users', async ({ page }) => {
+    await page.goto('/admin');
+
+    await page.waitForURL('**/auth/login**');
+    expect(page.url()).toContain('/auth/login');
+  });
+});
diff --git a/frontend/ai.client/e2e/auth/not-found.spec.ts b/frontend/ai.client/e2e/auth/not-found.spec.ts
new file mode 100644
index 00000000..485868ba
--- /dev/null
+++ b/frontend/ai.client/e2e/auth/not-found.spec.ts
@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('404 Not Found Page', () => {
+  test('should display 404 page for unknown routes', async ({ page }) => {
+    await page.goto('/some/nonexistent/route');
+
+    // Should show the 404 digits
+    await expect(page.getByLabel('Error 404')).toBeVisible();
+
+    // Should show the "Page Not Found" title
+    await expect(page.getByRole('heading', { name: 'Page Not Found' })).toBeVisible();
+  });
+
+  test('should have a "Return Home" link', async ({ page }) => {
+    await page.goto('/this-does-not-exist');
+
+    const homeLink = page.getByRole('link', { name: 'Return Home' });
+    await expect(homeLink).toBeVisible();
+    await expect(homeLink).toHaveAttribute('href', '/');
+  });
+
+  test('should have a "Go Back" button', async ({ page }) => {
+    await page.goto('/nope');
+
+    const backButton = page.getByRole('button', { name: 'Go Back' });
+    await expect(backButton).toBeVisible();
+  });
+});
diff --git a/frontend/ai.client/e2e/home-page/chat.user.spec.ts b/frontend/ai.client/e2e/home-page/chat.user.spec.ts
new file mode 100644
index 00000000..1d125a01
--- /dev/null
+++ b/frontend/ai.client/e2e/home-page/chat.user.spec.ts
@@ -0,0 +1,236 @@
+import { test, expect } from '@playwright/test';
+
+/**
+ * Helper: select a model from the model dropdown by matching visible text.
+ */
+async function selectModel(page: import('@playwright/test').Page, modelNameSubstring: string) {
+  const trigger = page.getByRole('button', { name: 'Select model' });
+  await expect(trigger).toBeVisible({ timeout: 10_000 });
+  await expect(trigger).not.toContainText('System Default', { timeout: 30_000 });
+
+  await trigger.click();
+
+  const menuItem = page.getByRole('menuitem').filter({
+    hasText: new RegExp(modelNameSubstring, 'i'),
+  });
+  await expect(menuItem.first()).toBeVisible({ timeout: 5_000 });
+  await menuItem.first().click();
+}
+
+/**
+ * Helper: send a chat message and wait for the assistant to finish responding.
+ */
+async function sendMessageAndWaitForResponse(
+  page: import('@playwright/test').Page,
+  message: string,
+): Promise<string> {
+  const textarea = page.locator('textarea#user-message');
+  await expect(textarea).toBeVisible({ timeout: 15_000 });
+  await textarea.fill(message);
+
+  await page.getByRole('button', { name: 'Submit message' }).click();
+
+  const assistantMessage = page.locator('app-assistant-message').last();
+  await expect(assistantMessage).toBeVisible({ timeout: 100_000 });
+  await expect(page.locator('app-pulsating-loader')).toBeHidden({ timeout: 250_000 });
+
+  return (await assistantMessage.innerText()).trim();
+}
+
+
+test.describe('Chat (user)', () => {
+  test.describe.serial('Chat lifecycle with Claude Haiku 4.5', () => {
+    test('should select Haiku, send a message, and receive a response', async ({ page }) => {
+      await page.goto('/');
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+      await selectModel(page, 'Haiku');
+
+      const trigger = page.getByRole('button', { name: 'Select model' });
+      await expect(trigger).toContainText(/Haiku/i);
+
+      const response = await sendMessageAndWaitForResponse(page, 'Reply with exactly one word.');
+
+      const userMessage = page.locator('app-user-message').last();
+      await expect(userMessage).toContainText('Reply with exactly one word.');
+
+      expect(response.length).toBeGreaterThan(0);
+    });
+
+    test('should send a second message in the same session', async ({ page }) => {
+      await page.goto('/');
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+      // Click into the most recent conversation (created by the previous test)
+      const sessionLink = page.locator('app-session-list a').first();
+      await sessionLink.click();
+      await page.waitForURL(/\/s\//, { timeout: 10_000 });
+
+      // Should already have 1 user message and 1 assistant message from the first test
+      await expect(page.locator('app-user-message')).toHaveCount(1, { timeout: 10_000 });
+      await expect(page.locator('app-assistant-message')).toHaveCount(1, { timeout: 10_000 });
+
+      // Send a second message
+      const response = await sendMessageAndWaitForResponse(page, 'Reply with exactly one word.');
+
+      expect(response.length).toBeGreaterThan(0);
+
+      // Should now have 2 of each
+      await expect(page.locator('app-user-message')).toHaveCount(2, { timeout: 5_000 });
+      await expect(page.locator('app-assistant-message')).toHaveCount(2, { timeout: 5_000 });
+    });
+
+    test('should rename the conversation', async ({ page }) => {
+      await page.goto('/');
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+      const sessionOptionsButton = page.locator('button[aria-haspopup="menu"]').filter({
+        has: page.locator('ng-icon[name="heroEllipsisHorizontalSolid"]'),
+      });
+      await sessionOptionsButton.first().hover();
+      await sessionOptionsButton.first().click();
+
+      await page.getByRole('menuitem', { name: 'Rename' }).click();
+
+      const renameInput = page.getByLabel('Rename conversation');
+      await expect(renameInput).toBeVisible({ timeout: 5_000 });
+
+      await renameInput.fill('test conversation');
+      await renameInput.press('Enter');
+
+      const sessionLink = page.locator('app-session-list a').filter({
+        hasText: 'test conversation',
+      });
+      await expect(sessionLink.first()).toBeVisible({ timeout: 10_000 });
+    });
+
+    test('should start a new conversation from the sidebar', async ({ page }) => {
+      await page.goto('/');
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+      // Click into the existing conversation so we're not already on home
+      const sessionLink = page.locator('app-session-list a').filter({
+        hasText: 'test conversation',
+      });
+      await sessionLink.first().click();
+      await page.waitForURL(/\/s\//, { timeout: 10_000 });
+
+      // Click "New Session" in the sidebar
+      await page.getByRole('button', { name: 'New Session' }).click();
+
+      // Should navigate to the home screen (root URL, no /s/ path)
+      await page.waitForURL((url) => !url.pathname.startsWith('/s/'), { timeout: 10_000 });
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 10_000 });
+    });
+
+    test('should delete the conversation', async ({ page }) => {
+      await page.goto('/');
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+      // Find the "test conversation" session and open its options menu
+      const sessionItem = page.locator('li.group').filter({
+        hasText: 'test conversation',
+      });
+      const optionsButton = sessionItem.locator('button[aria-haspopup="menu"]');
+      await optionsButton.hover();
+      await optionsButton.click();
+
+      // Click "Delete" from the context menu
+      await page.getByRole('menuitem', { name: 'Delete' }).click();
+
+      // Confirm the deletion in the dialog
+      const confirmButton = page.getByRole('alertdialog').getByRole('button', { name: 'Delete' });
+      await expect(confirmButton).toBeVisible({ timeout: 5_000 });
+      await confirmButton.click();
+
+      // Verify the conversation is gone from the sidebar
+      const deletedSession = page.locator('app-session-list a').filter({
+        hasText: 'test conversation',
+      });
+      await expect(deletedSession).toHaveCount(0, { timeout: 10_000 });
+    });
+  });
+
+  // Add independent (non-serial) home page tests below.
+  // These run with their own isolated browser context and don't depend on the serial block.
+
+  test('should close and reopen the sidebar using the collapse button', async ({ page }) => {
+    // Ensure viewport is wide enough for the desktop sidebar (Tailwind lg = 1024px)
+    await page.setViewportSize({ width: 1280, height: 720 });
+
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    // Sidebar should be visible initially
+    const sidenav = page.locator('app-sidenav');
+    await expect(sidenav.first()).toBeVisible({ timeout: 5_000 });
+
+    // Click the collapse button inside the sidebar
+    const collapseButton = page.getByRole('button', { name: 'Collapse sidebar' });
+    await expect(collapseButton).toBeVisible({ timeout: 5_000 });
+    await collapseButton.click();
+
+    // The expand button in app.html should now appear (top-left, outside the sidebar)
+    const expandButton = page.getByRole('button', { name: 'Expand sidebar' });
+    await expect(expandButton).toBeVisible({ timeout: 10_000 });
+
+    // Click expand to reopen
+    await expandButton.click();
+
+    // Sidebar should be visible again
+    await expect(sidenav.first()).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByRole('button', { name: 'Collapse sidebar' })).toBeVisible({
+      timeout: 5_000,
+    });
+  });
+
+  test('should navigate to the assistants page when clicking the Assistants link', async ({
+    page,
+  }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    const assistantsLink = page.getByRole('link', { name: 'Assistants' });
+    await expect(assistantsLink).toBeVisible({ timeout: 5_000 });
+    await assistantsLink.click();
+
+    await page.waitForURL(/\/assistants/, { timeout: 10_000 });
+    expect(page.url()).toContain('/assistants');
+  });
+
+  test('should open and close the user menu by clicking the user button', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    const userMenuButton = page.getByRole('button', { name: 'User menu' });
+    await expect(userMenuButton).toBeVisible({ timeout: 5_000 });
+
+    // Open the user menu
+    await userMenuButton.click();
+
+    const settingsItem = page.getByRole('menuitem', { name: 'Settings' });
+    await expect(settingsItem).toBeVisible({ timeout: 5_000 });
+
+    // Close the user menu by clicking the button again
+    await userMenuButton.click();
+    await expect(settingsItem).toBeHidden({ timeout: 5_000 });
+  });
+
+  test('should navigate to the settings page from the user menu', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    // Open the user menu
+    const userMenuButton = page.getByRole('button', { name: 'User menu' });
+    await expect(userMenuButton).toBeVisible({ timeout: 5_000 });
+    await userMenuButton.click();
+
+    // Click Settings
+    const settingsItem = page.getByRole('menuitem', { name: 'Settings' });
+    await expect(settingsItem).toBeVisible({ timeout: 5_000 });
+    await settingsItem.click();
+
+    await page.waitForURL(/\/settings/, { timeout: 10_000 });
+    expect(page.url()).toContain('/settings');
+  });
+});
diff --git a/frontend/ai.client/e2e/home-page/error-handling.user.spec.ts b/frontend/ai.client/e2e/home-page/error-handling.user.spec.ts
new file mode 100644
index 00000000..5edec6ab
--- /dev/null
+++ b/frontend/ai.client/e2e/home-page/error-handling.user.spec.ts
@@ -0,0 +1,56 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Error Handling UI (user)', () => {
+  test('should show sidebar error when sessions API fails', async ({ page }) => {
+    // The session-list template checks isLoading() first, which is based on
+    // sessionsResource.value() === undefined. When the resource errors,
+    // value() stays undefined so isLoading remains true and the error branch
+    // is never reached. Instead, we verify the sidebar does NOT show sessions
+    // and stays in a loading/degraded state.
+    await page.route('**/sessions*', (route) => {
+      if (route.request().method() === 'GET') {
+        return route.fulfill({
+          status: 500,
+          contentType: 'application/json',
+          body: JSON.stringify({ detail: 'Database unavailable' }),
+        });
+      }
+      return route.continue();
+    });
+
+    await page.goto('/');
+
+    // The chat input should still render (page itself loads fine)
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    // The sidebar should NOT show any session links (API failed)
+    const sessionLinks = page.locator('app-session-list a');
+    await expect(sessionLinks).toHaveCount(0, { timeout: 10_000 });
+
+    // Should show either "Loading sessions..." (stuck) or "No Chats Yet"
+    // but NOT actual session data
+    const hasLoadingText = await page.getByText('Loading sessions...').isVisible().catch(() => false);
+    const hasEmptyText = await page.getByText('No Chats Yet').isVisible().catch(() => false);
+    expect(hasLoadingText || hasEmptyText).toBeTruthy();
+  });
+
+  test('should handle network timeout gracefully on manage-sessions', async ({ page }) => {
+    // Abort the sessions request to simulate network failure
+    await page.route('**/sessions*', (route) => {
+      if (route.request().method() === 'GET') {
+        return route.abort('connectionrefused');
+      }
+      return route.continue();
+    });
+
+    await page.goto('/manage-sessions');
+
+    // Should show the heading even if data fails
+    await expect(
+      page.getByRole('heading', { name: 'Manage Conversations' }),
+    ).toBeVisible({ timeout: 15_000 });
+
+    // Loading should eventually stop (either error state or empty)
+    await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 15_000 });
+  });
+});
diff --git a/frontend/ai.client/e2e/home-page/file-upload-ui.user.spec.ts b/frontend/ai.client/e2e/home-page/file-upload-ui.user.spec.ts
new file mode 100644
index 00000000..ccac0e2c
--- /dev/null
+++ b/frontend/ai.client/e2e/home-page/file-upload-ui.user.spec.ts
@@ -0,0 +1,67 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('File Upload UI (user)', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+  });
+
+  test('should show the attach file button', async ({ page }) => {
+    const attachLabel = page.locator('label[for="file-upload"]');
+    await expect(attachLabel).toBeVisible({ timeout: 5_000 });
+  });
+
+  test('should accept a file via the file input', async ({ page }) => {
+    // Mock the upload endpoint so we don't actually upload
+    await page.route('**/files/upload**', (route) =>
+      route.fulfill({
+        status: 200,
+        json: { uploadId: 'mock-upload-id', filename: 'test.txt', status: 'completed' },
+      }),
+    );
+
+    const fileInput = page.locator('input#file-upload');
+
+    // Upload a small text file
+    await fileInput.setInputFiles({
+      name: 'test.txt',
+      mimeType: 'text/plain',
+      buffer: Buffer.from('hello world'),
+    });
+
+    // A file card should appear in the attachments area
+    const fileCard = page.locator('app-file-card');
+    await expect(fileCard.first()).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('should remove an attached file', async ({ page }) => {
+    // Mock the upload endpoint so we don't actually upload
+    await page.route('**/files/upload**', (route) =>
+      route.fulfill({
+        status: 200,
+        json: { uploadId: 'mock-upload-id', filename: 'test.txt', status: 'completed' },
+      }),
+    );
+
+    const fileInput = page.locator('input#file-upload');
+
+    // Upload a small text file
+    await fileInput.setInputFiles({
+      name: 'test.txt',
+      mimeType: 'text/plain',
+      buffer: Buffer.from('hello world'),
+    });
+
+    // A file card should appear in the attachments area
+    const fileCard = page.locator('app-file-card');
+    await expect(fileCard.first()).toBeVisible({ timeout: 10_000 });
+
+    // Click the remove/delete button on the file card
+    // The sr-only text varies by state: "Delete file" (ready), "Cancel upload" (uploading), "Remove" (error)
+    const removeButton = fileCard.first().getByRole('button', { name: /delete file|cancel upload|remove/i });
+    await removeButton.click();
+
+    // File card should disappear
+    await expect(fileCard).toHaveCount(0, { timeout: 5_000 });
+  });
+});
diff --git a/frontend/ai.client/e2e/home-page/model-selector.user.spec.ts b/frontend/ai.client/e2e/home-page/model-selector.user.spec.ts
new file mode 100644
index 00000000..4149aacb
--- /dev/null
+++ b/frontend/ai.client/e2e/home-page/model-selector.user.spec.ts
@@ -0,0 +1,62 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Model Selector (user)', () => {
+  test('should display the model selector with a loaded model', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    const trigger = page.getByRole('button', { name: 'Select model' });
+    await expect(trigger).toBeVisible({ timeout: 10_000 });
+
+    // Should eventually show a real model name (not "Loading..." or "System Default")
+    await expect(trigger).not.toContainText('Default', { timeout: 30_000 });
+  });
+
+  test('should open the model dropdown and list available models', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    const trigger = page.getByRole('button', { name: 'Select model' });
+    await expect(trigger).not.toContainText('Default', { timeout: 30_000 });
+    await trigger.click();
+
+    // Menu items should appear
+    const menuItems = page.getByRole('menuitem');
+    await expect(menuItems.first()).toBeVisible({ timeout: 5_000 });
+    expect(await menuItems.count()).toBeGreaterThan(0);
+  });
+
+  test('should persist model selection after navigation', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    const trigger = page.getByRole('button', { name: 'Select model' });
+    await expect(trigger).not.toContainText('Default', { timeout: 30_000 });
+
+    // Open dropdown and pick a different model (if available)
+    await trigger.click();
+    const menuItems = page.getByRole('menuitem');
+    const count = await menuItems.count();
+    test.skip(count < 2, 'Only one model available — cannot test switching');
+
+    // Pick the second model (different from current)
+    const secondModel = menuItems.nth(1);
+    const secondModelName = (await secondModel.innerText()).trim();
+    await secondModel.click();
+
+    // Verify the trigger updated
+    await expect(trigger).toContainText(secondModelName.split('\n')[0], { timeout: 5_000 });
+
+    // Navigate away and back
+    await page.goto('/manage-sessions');
+    await expect(page.getByRole('heading', { name: 'Manage Conversations' })).toBeVisible({ timeout: 15_000 });
+
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+    // Model should still be the one we selected
+    const afterNav = page.getByRole('button', { name: 'Select model' });
+    await expect(afterNav).not.toContainText('Default', { timeout: 30_000 });
+    await expect(afterNav).toContainText(secondModelName.split('\n')[0]);
+  });
+});
diff --git a/frontend/ai.client/e2e/home-page/settings-panel.user.spec.ts b/frontend/ai.client/e2e/home-page/settings-panel.user.spec.ts
new file mode 100644
index 00000000..e68b333e
--- /dev/null
+++ b/frontend/ai.client/e2e/home-page/settings-panel.user.spec.ts
@@ -0,0 +1,76 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Settings Panel — Tool Toggles (user)', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+  });
+
+  // test('should open and close the settings panel', async ({ page }) => {
+  //   // Open settings
+  //   await page.getByLabel('Open settings').click();
+
+  //   const panel = page.getByRole('dialog', { name: 'Settings' });
+  //   await expect(panel).toBeVisible({ timeout: 5_000 });
+  //   await expect(panel.getByText('Settings')).toBeVisible();
+
+  //   await page.pause()
+
+  //   // Close via the X button
+  //   await panel.getByLabel('Close settings panel').click();
+  //   await expect(panel).toBeHidden({ timeout: 5_000 });
+
+  //   await page.pause()
+  // });
+
+  // test('should display tools with toggle switches', async ({ page }) => {
+  //   await page.getByLabel('Open settings').click();
+
+  //   const panel = page.getByRole('dialog', { name: 'Settings' });
+  //   await expect(panel).toBeVisible({ timeout: 5_000 });
+
+  //   // Wait for tools to load (not showing "Loading tools...")
+  //   await expect(panel.getByText('Loading tools...')).toBeHidden({ timeout: 15_000 });
+
+  //   // Should have at least one tool toggle
+  //   const toggles = panel.getByRole('switch');
+  //   await expect(toggles.first()).toBeVisible({ timeout: 5_000 });
+
+  //   // Enabled count should be visible
+  //   await expect(panel.getByText(/\d+ enabled/)).toBeVisible();
+  // });
+
+  // test('should toggle a tool on and off', async ({ page }) => {
+  //   await page.getByLabel('Open settings').click();
+
+  //   const panel = page.getByRole('dialog', { name: 'Settings' });
+  //   await expect(panel.getByText('Loading tools...')).toBeHidden({ timeout: 15_000 });
+
+  //   const firstToggle = panel.getByRole('switch').first();
+  //   await expect(firstToggle).toBeVisible({ timeout: 5_000 });
+
+  //   // Read initial state
+  //   const initialState = await firstToggle.getAttribute('aria-checked');
+  //   const flippedState = initialState === 'true' ? 'false' : 'true';
+
+  //   // Toggle it
+  //   await firstToggle.click();
+  //   await expect(firstToggle).toHaveAttribute('aria-checked', flippedState, { timeout: 5_000 });
+
+  //   // Toggle it back
+  //   await firstToggle.click();
+  //   await expect(firstToggle).toHaveAttribute('aria-checked', initialState!, { timeout: 5_000 });
+  // });
+
+  test('should close settings panel by clicking backdrop', async ({ page }) => {
+    await page.getByLabel('Open settings').click();
+
+    const panel = page.getByRole('dialog', { name: 'Settings' });
+    await expect(panel).toBeVisible({ timeout: 5_000 });
+
+    // Click the backdrop (center of viewport, away from the slide-over panel)
+    const viewport = page.viewportSize()!;
+    await page.mouse.click(viewport.width / 2, viewport.height / 2);
+    await expect(panel).toBeHidden({ timeout: 5_000 });
+  });
+});
diff --git a/frontend/ai.client/e2e/manage-sessions.user.spec.ts b/frontend/ai.client/e2e/manage-sessions.user.spec.ts
new file mode 100644
index 00000000..53a1bf7b
--- /dev/null
+++ b/frontend/ai.client/e2e/manage-sessions.user.spec.ts
@@ -0,0 +1,72 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Manage Sessions Page (user)', () => {
+  test('should load the manage sessions page', async ({ page }) => {
+    await page.goto('/manage-sessions');
+
+    // Page heading
+    await expect(
+      page.getByRole('heading', { name: 'Manage Conversations' }),
+    ).toBeVisible({ timeout: 15_000 });
+
+    // Selection info bar
+    await expect(page.getByText(/0 of \d+ selected/)).toBeVisible();
+  });
+
+  test('should show sessions or empty state', async ({ page }) => {
+    await page.goto('/manage-sessions');
+    await expect(
+      page.getByRole('heading', { name: 'Manage Conversations' }),
+    ).toBeVisible({ timeout: 15_000 });
+
+    // Wait for loading to finish
+    await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 15_000 });
+
+    // Either sessions are listed or the empty state is shown
+    const hasSession = await page.locator('input[type="checkbox"]').count();
+    if (hasSession > 0) {
+      // At least one session checkbox is visible
+      await expect(page.locator('input[type="checkbox"]').first()).toBeVisible();
+    } else {
+      await expect(page.getByText('No conversations')).toBeVisible();
+    }
+  });
+
+  test('should select and deselect a session', async ({ page }) => {
+    await page.goto('/manage-sessions');
+    await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 100_000 });
+
+    const checkbox = page.locator('input[type="checkbox"]').first();
+    const hasCheckbox = (await checkbox.count()) > 0;
+    test.skip(!hasCheckbox, 'No sessions available to select');
+
+    // Select
+    await checkbox.check();
+    await expect(page.getByText(/1 of \d+ selected/)).toBeVisible();
+
+    // Deselect
+    await checkbox.uncheck();
+    await expect(page.getByText(/0 of \d+ selected/)).toBeVisible();
+  });
+
+  test('should navigate back to home', async ({ page }) => {
+    await page.goto('/manage-sessions');
+    await expect(
+      page.getByRole('heading', { name: 'Manage Conversations' }),
+    ).toBeVisible({ timeout: 15_000 });
+
+    await page.getByText('Back').click();
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('should show the delete selected button disabled when nothing is selected', async ({ page }) => {
+    await page.goto('/manage-sessions');
+    await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 15_000 });
+
+    const deleteButton = page.getByRole('button', { name: /Delete Selected/i });
+    const hasButton = (await deleteButton.count()) > 0;
+    test.skip(!hasButton, 'No sessions available — delete button not rendered');
+
+    await expect(deleteButton).toBeDisabled();
+  });
+});
diff --git a/frontend/ai.client/e2e/settings/appearance.user.spec.ts b/frontend/ai.client/e2e/settings/appearance.user.spec.ts
new file mode 100644
index 00000000..e965baac
--- /dev/null
+++ b/frontend/ai.client/e2e/settings/appearance.user.spec.ts
@@ -0,0 +1,147 @@
+import { test, expect, Page } from '@playwright/test';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Navigate to the appearance settings page and wait for it to load. */
+async function goToAppearancePage(page: Page) {
+  await page.goto('/settings/appearance');
+  await expect(
+    page.getByRole('heading', { name: 'Settings' }),
+  ).toBeVisible({ timeout: 15_000 });
+  await expect(
+    page.getByRole('heading', { name: 'Appearance' }),
+  ).toBeVisible({ timeout: 10_000 });
+}
+
+/** Get the theme button by label text. */
+function themeButton(page: Page, label: 'Light' | 'Dark' | 'System') {
+  // Each button contains a span with the label text — filter to the right one
+  return page.locator('app-appearance-settings button').filter({ hasText: label });
+}
+
+/** Assert that the given theme button shows the selected ring style. */
+async function expectSelected(page: Page, label: 'Light' | 'Dark' | 'System') {
+  const btn = themeButton(page, label);
+  // Selected buttons have ring-2 (blue ring) and a checkmark badge
+  await expect(btn).toHaveClass(/ring-2/, { timeout: 5_000 });
+}
+
+/** Assert that the given theme button is NOT selected. */
+async function expectNotSelected(page: Page, label: 'Light' | 'Dark' | 'System') {
+  const btn = themeButton(page, label);
+  await expect(btn).toHaveClass(/ring-1/, { timeout: 5_000 });
+}
+
+/** Check whether the <html> element has the 'dark' class. */
+async function isDarkMode(page: Page): Promise<boolean> {
+  return page.locator('html').evaluate((el) => el.classList.contains('dark'));
+}
+
+/** Read the theme-preference value from localStorage. */
+async function getStoredPreference(page: Page): Promise<string | null> {
+  return page.evaluate(() => localStorage.getItem('theme-preference'));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test.describe('Settings / Appearance (user)', () => {
+  test('should display all three theme options', async ({ page }) => {
+    await goToAppearancePage(page);
+
+    await expect(themeButton(page, 'Light')).toBeVisible({ timeout: 5_000 });
+    await expect(themeButton(page, 'Dark')).toBeVisible({ timeout: 5_000 });
+    await expect(themeButton(page, 'System')).toBeVisible({ timeout: 5_000 });
+  });
+
+  test('should switch to dark theme', async ({ page }) => {
+    await goToAppearancePage(page);
+
+    await themeButton(page, 'Dark').click();
+
+    await expectSelected(page, 'Dark');
+    await expectNotSelected(page, 'Light');
+    await expectNotSelected(page, 'System');
+
+    // <html> should have the 'dark' class
+    expect(await isDarkMode(page)).toBe(true);
+
+    // localStorage should persist the choice
+    expect(await getStoredPreference(page)).toBe('dark');
+  });
+
+  test('should switch to light theme', async ({ page }) => {
+    await goToAppearancePage(page);
+
+    // Start by setting dark so we can verify the switch
+    await themeButton(page, 'Dark').click();
+    expect(await isDarkMode(page)).toBe(true);
+
+    // Now switch to light
+    await themeButton(page, 'Light').click();
+
+    await expectSelected(page, 'Light');
+    await expectNotSelected(page, 'Dark');
+    await expectNotSelected(page, 'System');
+
+    expect(await isDarkMode(page)).toBe(false);
+    expect(await getStoredPreference(page)).toBe('light');
+  });
+
+  test('should switch to system theme', async ({ page }) => {
+    await goToAppearancePage(page);
+
+    // Set an explicit theme first so we know we're changing something
+    await themeButton(page, 'Dark').click();
+    await expectSelected(page, 'Dark');
+
+    // Switch to system
+    await themeButton(page, 'System').click();
+
+    await expectSelected(page, 'System');
+    await expectNotSelected(page, 'Light');
+    await expectNotSelected(page, 'Dark');
+
+    expect(await getStoredPreference(page)).toBe('system');
+  });
+
+  test('should persist theme choice across page reloads', async ({ page }) => {
+    await goToAppearancePage(page);
+
+    // Select dark
+    await themeButton(page, 'Dark').click();
+    await expectSelected(page, 'Dark');
+    expect(await isDarkMode(page)).toBe(true);
+
+    // Reload the page
+    await page.reload();
+    await expect(
+      page.getByRole('heading', { name: 'Appearance' }),
+    ).toBeVisible({ timeout: 15_000 });
+
+    // Dark should still be selected and applied
+    await expectSelected(page, 'Dark');
+    expect(await isDarkMode(page)).toBe(true);
+  });
+
+  test('should apply system theme based on prefers-color-scheme', async ({ page }) => {
+    // Emulate dark system preference
+    await page.emulateMedia({ colorScheme: 'dark' });
+    await goToAppearancePage(page);
+
+    await themeButton(page, 'System').click();
+    await expectSelected(page, 'System');
+
+    // With system preference set to dark, the page should be in dark mode
+    expect(await isDarkMode(page)).toBe(true);
+
+    // Now flip to light system preference
+    await page.emulateMedia({ colorScheme: 'light' });
+
+    // The ThemeService listens to matchMedia changes — give it a moment
+    await expect.poll(() => isDarkMode(page), { timeout: 5_000 }).toBe(false);
+  });
+});
diff --git a/frontend/ai.client/e2e/settings/chat-preferences.user.spec.ts b/frontend/ai.client/e2e/settings/chat-preferences.user.spec.ts
new file mode 100644
index 00000000..cdfb5a22
--- /dev/null
+++ b/frontend/ai.client/e2e/settings/chat-preferences.user.spec.ts
@@ -0,0 +1,912 @@
+import { test, expect, Page } from '@playwright/test';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Unique conversation title used by the serial delete lifecycle. */
+const DELETE_TEST_TITLE = `e2e-delete-test-${Date.now()}`;
+
+/** Unique conversation title used by the token count badge tests. */
+const TOKEN_TEST_TITLE = `e2e-token-test-${Date.now()}`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Navigate to the chat preferences settings page and wait for it to load. */
+async function goToChatPreferencesPage(page: Page) {
+  await page.goto('/settings/chat');
+  await expect(
+    page.getByRole('heading', { name: 'Settings' }),
+  ).toBeVisible({ timeout: 15_000 });
+  await expect(
+    page.getByRole('heading', { name: 'Chat Preferences' }),
+  ).toBeVisible({ timeout: 10_000 });
+}
+
+/** Navigate to the manage conversations page and wait for it to load. */
+async function goToManageSessionsPage(page: Page) {
+  await page.goto('/manage-sessions');
+  await expect(
+    page.getByRole('heading', { name: 'Manage Conversations' }),
+  ).toBeVisible({ timeout: 15_000 });
+  await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 15_000 });
+}
+
+/** Read a boolean value from localStorage. */
+async function getLocalStorageBoolean(page: Page, key: string): Promise<boolean> {
+  const raw = await page.evaluate((k) => localStorage.getItem(k), key);
+  if (raw === null) return false;
+  try {
+    return JSON.parse(raw) === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Assert that a toggle is visually and semantically in the "on" state.
+ * Uses Playwright's built-in checkbox assertion instead of fragile
+ * computed-style checks (Tailwind v4 OKLCH colors break RGB parsing).
+ */
+async function expectToggleOn(page: Page, label: string) {
+  await expect(page.getByLabel(label)).toBeChecked({ timeout: 5_000 });
+}
+
+/**
+ * Assert that a toggle is visually and semantically in the "off" state.
+ */
+async function expectToggleOff(page: Page, label: string) {
+  await expect(page.getByLabel(label)).not.toBeChecked({ timeout: 5_000 });
+}
+
+/**
+ * Assert that the toggle knob is translated to the right (checked position).
+ * The knob span has `group-has-checked:translate-x-5` when on.
+ * We verify by checking the checkbox is checked — the CSS transform follows.
+ */
+async function expectKnobTranslated(page: Page, label: string) {
+  await expect(page.getByLabel(label)).toBeChecked({ timeout: 5_000 });
+}
+
+/**
+ * Assert that the toggle knob is in the default (left) position.
+ */
+async function expectKnobDefault(page: Page, label: string) {
+  await expect(page.getByLabel(label)).not.toBeChecked({ timeout: 5_000 });
+}
+
+/** Send a chat message and wait for the assistant to finish responding. */
+async function sendMessageAndWaitForResponse(
+  page: Page,
+  message: string,
+): Promise<string> {
+  const textarea = page.locator('textarea#user-message');
+  await expect(textarea).toBeVisible({ timeout: 15_000 });
+  await textarea.fill(message);
+
+  await page.getByRole('button', { name: 'Submit message' }).click();
+
+  const assistantMessage = page.locator('app-assistant-message').last();
+  await expect(assistantMessage).toBeVisible({ timeout: 60_000 });
+  await expect(page.locator('app-pulsating-loader')).toBeHidden({ timeout: 200_000 });
+
+  return (await assistantMessage.innerText()).trim();
+}
+
+// ---------------------------------------------------------------------------
+// Tests — Chat Preferences Page
+// ---------------------------------------------------------------------------
+
+test.describe('Settings / Chat Preferences (user)', () => {
+  // -----------------------------------------------------------------------
+  // Page structure
+  // -----------------------------------------------------------------------
+
+  test('should display all chat preference sections', async ({ page }) => {
+    await goToChatPreferencesPage(page);
+
+    // Default model section
+    await expect(page.getByText('Default model')).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByText('Choose which model is selected by default')).toBeVisible({ timeout: 5_000 });
+
+    // Show token count toggle — label, description, and icon container
+    await expect(page.getByText('Show token count')).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByText('Display token usage, latency, and cost badges')).toBeVisible({ timeout: 5_000 });
+
+    // Show debug output toggle — label, description, and icon container
+    await expect(page.getByText('Show debug output')).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByText('Show the full prompt sent to the model')).toBeVisible({ timeout: 5_000 });
+
+    // Manage Conversations link
+    await expect(page.getByText('Manage Conversations')).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByText('Select and delete old conversations')).toBeVisible({ timeout: 5_000 });
+
+    // Memories link
+    await expect(page.getByText('Memories')).toBeVisible({ timeout: 5_000 });
+    await expect(page.getByText('View and manage what the assistant remembers')).toBeVisible({ timeout: 5_000 });
+  });
+
+  // -----------------------------------------------------------------------
+  // Default model selector
+  // -----------------------------------------------------------------------
+
+  // test('should display the default model dropdown with available models', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   const select = page.getByLabel('Default model');
+  //   await expect(select).toBeVisible({ timeout: 15_000 });
+
+  //   // The "no default" option should always be present
+  //   const noDefaultOption = select.locator('option[value=""]');
+  //   await expect(noDefaultOption).toHaveText('No default (use first available)', { timeout: 5_000 });
+
+  //   // At least one model option should be available (beyond the "no default" option)
+  //   const allOptions = select.locator('option');
+  //   const optionCount = await allOptions.count();
+  //   expect(optionCount).toBeGreaterThanOrEqual(2);
+  // });
+
+  // test('should change the default model and persist it', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   const select = page.getByLabel('Default model');
+  //   await expect(select).toBeVisible({ timeout: 15_000 });
+
+  //   // Get all model options (skip the first "no default" option)
+  //   const modelOptions = select.locator('option:not([value=""])');
+  //   const modelCount = await modelOptions.count();
+  //   test.skip(modelCount === 0, 'No models available to select');
+
+  //   // Select the first available model
+  //   const firstModelValue = await modelOptions.first().getAttribute('value');
+  //   const firstModelText = (await modelOptions.first().innerText()).trim();
+  //   await select.selectOption(firstModelValue!);
+
+  //   // Wait for save to complete
+  //   await page.waitForTimeout(1_000);
+
+  //   // Reload and verify the selection persisted
+  //   await page.reload();
+  //   await expect(
+  //     page.getByRole('heading', { name: 'Chat Preferences' }),
+  //   ).toBeVisible({ timeout: 15_000 });
+
+  //   const reloadedSelect = page.getByLabel('Default model');
+  //   await expect(reloadedSelect).toBeVisible({ timeout: 15_000 });
+
+  //   // The selected option text should match what we chose
+  //   const selectedText = await reloadedSelect.locator('option:checked').innerText();
+  //   expect(selectedText.trim()).toBe(firstModelText);
+
+  //   // Clean up: reset to "no default"
+  //   await reloadedSelect.selectOption('');
+  //   await page.waitForTimeout(1_000);
+  // });
+
+  // test('should reset default model to "no default"', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   const select = page.getByLabel('Default model');
+  //   await expect(select).toBeVisible({ timeout: 15_000 });
+
+  //   // Select "no default"
+  //   await select.selectOption('');
+  //   await page.waitForTimeout(1_000);
+
+  //   // Reload and verify
+  //   await page.reload();
+  //   await expect(
+  //     page.getByRole('heading', { name: 'Chat Preferences' }),
+  //   ).toBeVisible({ timeout: 15_000 });
+
+  //   const reloadedSelect = page.getByLabel('Default model');
+  //   await expect(reloadedSelect).toBeVisible({ timeout: 15_000 });
+  //   await expect(reloadedSelect).toHaveValue('', { timeout: 5_000 });
+  // });
+
+  // -----------------------------------------------------------------------
+  // Show Token Count toggle — functional end-to-end
+  // -----------------------------------------------------------------------
+
+  test.describe.serial('Token count toggle controls metadata badge visibility', () => {
+    let page: Page;
+
+    test.beforeAll(async ({ browser }) => {
+      page = await browser.newPage();
+    });
+
+    test.afterAll(async () => {
+      // Clean up localStorage and close
+      await page.evaluate(() => localStorage.removeItem('show-token-count'));
+      await page.close();
+    });
+
+    test('should default to off', async () => {
+      await goToChatPreferencesPage(page);
+
+      // Reset to ensure clean state
+      await page.evaluate(() => localStorage.removeItem('show-token-count'));
+      await page.reload();
+      await expect(
+        page.getByRole('heading', { name: 'Chat Preferences' }),
+      ).toBeVisible({ timeout: 15_000 });
+
+      // Checkbox should be unchecked
+      await expect(page.getByLabel('Show token count')).not.toBeChecked({ timeout: 5_000 });
+      await expectToggleOff(page, 'Show token count');
+      expect(await getLocalStorageBoolean(page, 'show-token-count')).toBe(false);
+    });
+
+    test('should turn on and persist across reload', async () => {
+      // Toggle on
+      await page.getByLabel('Show token count').check();
+      await expectToggleOn(page, 'Show token count');
+      expect(await getLocalStorageBoolean(page, 'show-token-count')).toBe(true);
+
+      // Reload and verify it persisted
+      await page.reload();
+      await expect(
+        page.getByRole('heading', { name: 'Chat Preferences' }),
+      ).toBeVisible({ timeout: 15_000 });
+      await expect(page.getByLabel('Show token count')).toBeChecked({ timeout: 5_000 });
+      await expectToggleOn(page, 'Show token count');
+    });
+
+    test('should show metadata badges on a chat message when enabled', async () => {
+      // This test does a real LLM round-trip — extend the default 30s timeout
+      test.setTimeout(120_000);
+
+      // Navigate to chat with a fresh page load to clear any stale Angular state
+      await page.goto('/');
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+      // Wait for the model selector to finish loading (ensures the app is fully ready)
+      const modelButton = page.getByRole('button', { name: 'Select model' });
+      await expect(modelButton).not.toContainText('System Default', { timeout: 30_000 });
+
+      // Send the message and wait for the full response
+      await sendMessageAndWaitForResponse(page, 'Reply with exactly: hello');
+
+      // Confirm we navigated to a session
+      await page.waitForURL(/\/s\//, { timeout: 10_000 });
+
+      // Rename the conversation to a known title for reliable cleanup
+      const sessionOptionsButton = page.locator('button[aria-haspopup="menu"]').filter({
+        has: page.locator('ng-icon[name="heroEllipsisHorizontalSolid"]'),
+      });
+      await sessionOptionsButton.first().hover();
+      await sessionOptionsButton.first().click();
+
+      await page.getByRole('menuitem', { name: 'Rename' }).click();
+
+      const renameInput = page.getByLabel('Rename conversation');
+      await expect(renameInput).toBeVisible({ timeout: 15_000 });
+      await renameInput.fill(TOKEN_TEST_TITLE);
+      await renameInput.press('Enter');
+
+      // Wait for the rename input to disappear, confirming the rename was saved
+      await expect(renameInput).toBeHidden({ timeout: 15_000 });
+
+      // Verify the renamed session appears in the sidebar
+      const sessionLink = page.locator('app-session-list a').filter({
+        hasText: TOKEN_TEST_TITLE,
+      });
+      await expect(sessionLink.first()).toBeVisible({ timeout: 10_000 });
+
+      // The metadata badges container is hidden until hover.
+      // Hover over the assistant message group to reveal it.
+      const messageGroup = page.locator('div[role="group"][aria-label="Assistant message with metadata"]').last();
+      await messageGroup.hover();
+
+      // At least one metadata badge should be visible (e.g. input tokens, output tokens, cost)
+      const badges = messageGroup.locator('app-message-metadata-badges div.inline-flex');
+      await expect(badges.first()).toBeVisible({ timeout: 5_000 });
+
+      // Verify specific badge types are present — the model always returns token counts
+      const badgeTexts = await badges.allInnerTexts();
+      const hasSomeBadge = badgeTexts.some(
+        (t) => t.includes('In:') || t.includes('Out:') || t.includes('TTFT:') || t.includes('Cost:'),
+      );
+      expect(hasSomeBadge).toBe(true);
+    });
+
+    test('should hide metadata badges after turning the toggle off', async () => {
+      // Go back to settings and turn the toggle off
+      await goToChatPreferencesPage(page);
+      await expect(page.getByLabel('Show token count')).toBeChecked({ timeout: 5_000 });
+
+      await page.getByLabel('Show token count').uncheck();
+      await expectToggleOff(page, 'Show token count');
+      expect(await getLocalStorageBoolean(page, 'show-token-count')).toBe(false);
+
+      // Navigate back to the chat session — URL should still have /s/
+      await page.goBack();
+      await page.waitForURL(/\/s\//, { timeout: 10_000 });
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 60_000 });
+
+      // Hover over the assistant message group
+      const messageGroup = page.locator('div[role="group"][aria-label="Assistant message with metadata"]').last();
+      await messageGroup.hover();
+
+      // The badges component should render nothing when the toggle is off
+      const badges = messageGroup.locator('app-message-metadata-badges div.inline-flex');
+      await expect(badges).toHaveCount(0, { timeout: 5_000 });
+    });
+
+    test('should delete the conversation created during the badge test', async () => {
+      await goToManageSessionsPage(page);
+
+      // Target the actions button directly by its aria-label which includes the title
+      const menuButton = page.getByRole('button', { name: `Actions for ${TOKEN_TEST_TITLE}` });
+      await expect(menuButton).toBeVisible({ timeout: 10_000 });
+      await menuButton.click();
+
+      const menu = page.locator('[role="menu"]');
+      await expect(menu).toBeVisible({ timeout: 10_000 });
+
+      await menu.getByRole('menuitem', { name: 'Delete' }).click();
+
+      // Confirm in the dialog
+      const dialog = page.locator('[role="alertdialog"]');
+      await expect(dialog).toBeVisible({ timeout: 5_000 });
+      await dialog.getByRole('button', { name: 'Delete' }).click();
+      await expect(dialog).toBeHidden({ timeout: 10_000 });
+
+      // The conversation should be gone from the list
+      await expect(menuButton).toBeHidden({ timeout: 60_000 });
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Show Debug Output toggle — functional + visual
+  // -----------------------------------------------------------------------
+
+  // test('should display the debug output toggle with its icon and description', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   // The section card should contain the bug icon container
+  //   const debugSection = page.locator('#show-debug-output').locator('..').locator('..');
+  //   await expect(debugSection).toBeVisible({ timeout: 5_000 });
+
+  //   // Label and description are present
+  //   const label = page.locator('label[for="show-debug-output"]');
+  //   await expect(label).toHaveText('Show debug output', { timeout: 5_000 });
+
+  //   const description = debugSection.locator('p');
+  //   await expect(description).toContainText('Show the full prompt sent to the model', { timeout: 5_000 });
+  // });
+
+  // test('should show the debug output toggle in the off visual state by default', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   await page.evaluate(() => localStorage.removeItem('show-debug-output'));
+  //   await page.reload();
+  //   await expect(
+  //     page.getByRole('heading', { name: 'Chat Preferences' }),
+  //   ).toBeVisible({ timeout: 15_000 });
+
+  //   await expect(page.getByLabel('Show debug output')).not.toBeChecked({ timeout: 5_000 });
+  //   await expectToggleOff(page, 'Show debug output');
+  //   await expectKnobDefault(page, 'Show debug output');
+  // });
+
+  // test('should visually switch the debug output toggle to the on state', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   await page.evaluate(() => localStorage.removeItem('show-debug-output'));
+  //   await page.reload();
+  //   await expect(
+  //     page.getByRole('heading', { name: 'Chat Preferences' }),
+  //   ).toBeVisible({ timeout: 15_000 });
+
+  //   await page.getByLabel('Show debug output').check();
+
+  //   await expectToggleOn(page, 'Show debug output');
+  //   await expectKnobTranslated(page, 'Show debug output');
+  //   expect(await getLocalStorageBoolean(page, 'show-debug-output')).toBe(true);
+  // });
+
+  // test('should visually switch the debug output toggle back to the off state', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   await page.evaluate(() => localStorage.setItem('show-debug-output', 'true'));
+  //   await page.reload();
+  //   await expect(
+  //     page.getByRole('heading', { name: 'Chat Preferences' }),
+  //   ).toBeVisible({ timeout: 15_000 });
+
+  //   await expect(page.getByLabel('Show debug output')).toBeChecked({ timeout: 5_000 });
+  //   await expectToggleOn(page, 'Show debug output');
+
+  //   await page.getByLabel('Show debug output').uncheck();
+
+  //   await expectToggleOff(page, 'Show debug output');
+  //   await expectKnobDefault(page, 'Show debug output');
+  //   expect(await getLocalStorageBoolean(page, 'show-debug-output')).toBe(false);
+  // });
+
+  // test('should persist debug output toggle visual state across reloads', async ({ page }) => {
+  //   await goToChatPreferencesPage(page);
+
+  //   await page.evaluate(() => localStorage.removeItem('show-debug-output'));
+  //   await page.reload();
+  //   await expect(
+  //     page.getByRole('heading', { name: 'Chat Preferences' }),
+  //   ).toBeVisible({ timeout: 15_000 });
+
+  //   await page.getByLabel('Show debug output').check();
+  //   await expectToggleOn(page, 'Show debug output');
+
+  //   await page.reload();
+  //   await expect(
+  //     page.getByRole('heading', { name: 'Chat Preferences' }),
+  //   ).toBeVisible({ timeout: 15_000 });
+
+  //   await expect(page.getByLabel('Show debug output')).toBeChecked({ timeout: 5_000 });
+  //   await expectToggleOn(page, 'Show debug output');
+  //   await expectKnobTranslated(page, 'Show debug output');
+
+  //   // Clean up
+  //   await page.evaluate(() => localStorage.removeItem('show-debug-output'));
+  // });
+
+  // -----------------------------------------------------------------------
+  // Navigation links
+  // -----------------------------------------------------------------------
+
+  test('should navigate to Manage Conversations page', async ({ page }) => {
+    await goToChatPreferencesPage(page);
+
+    const manageLink = page.locator('a[href="/manage-sessions"]');
+    await expect(manageLink).toBeVisible({ timeout: 5_000 });
+
+    await manageLink.click();
+    await page.waitForURL('**/manage-sessions', { timeout: 10_000 });
+
+    await expect(
+      page.getByRole('heading', { name: 'Manage Conversations' }),
+    ).toBeVisible({ timeout: 15_000 });
+  });
+
+  test('should navigate to Memories page', async ({ page }) => {
+    await goToChatPreferencesPage(page);
+
+    const memoriesLink = page.locator('a[href="/memories"]');
+    await expect(memoriesLink).toBeVisible({ timeout: 5_000 });
+
+    await memoriesLink.click();
+    await page.waitForURL('**/memories', { timeout: 10_000 });
+
+    await expect(
+      page.getByRole('heading', { name: 'Memories' }),
+    ).toBeVisible({ timeout: 15_000 });
+  });
+
+  // -----------------------------------------------------------------------
+  // Manage Conversations — selection and UI
+  // -----------------------------------------------------------------------
+
+  test('should select and deselect conversations on the manage page', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const checkbox = page.locator('input[type="checkbox"]').first();
+    const hasCheckbox = (await checkbox.count()) > 0;
+    test.skip(!hasCheckbox, 'No conversations available to select');
+
+    // Select
+    await checkbox.check();
+    await expect(page.getByText(/1 of \d+ selected/)).toBeVisible({ timeout: 5_000 });
+
+    // Deselect
+    await checkbox.uncheck();
+    await expect(page.getByText(/0 of \d+ selected/)).toBeVisible({ timeout: 5_000 });
+  });
+
+  test('should show delete button disabled when nothing is selected', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const deleteButton = page.getByRole('button', { name: /Delete Selected/i });
+    const hasButton = (await deleteButton.count()) > 0;
+    test.skip(!hasButton, 'No conversations available — delete button not rendered');
+
+    await expect(deleteButton).toBeDisabled({ timeout: 5_000 });
+  });
+
+  test('should enable delete button when a conversation is selected', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const checkbox = page.locator('input[type="checkbox"]').first();
+    const hasCheckbox = (await checkbox.count()) > 0;
+    test.skip(!hasCheckbox, 'No conversations available to select');
+
+    await checkbox.check();
+    await expect(page.getByText(/1 of \d+ selected/)).toBeVisible({ timeout: 5_000 });
+
+    const deleteButton = page.getByRole('button', { name: /Delete Selected/i });
+    await expect(deleteButton).toBeEnabled({ timeout: 5_000 });
+
+    // Clean up — deselect
+    await checkbox.uncheck();
+  });
+
+  test('should clear selection via the "Clear selection" button', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const checkbox = page.locator('input[type="checkbox"]').first();
+    const hasCheckbox = (await checkbox.count()) > 0;
+    test.skip(!hasCheckbox, 'No conversations available to select');
+
+    await checkbox.check();
+    await expect(page.getByText(/1 of \d+ selected/)).toBeVisible({ timeout: 5_000 });
+
+    await page.getByText('Clear selection').click();
+    await expect(page.getByText(/0 of \d+ selected/)).toBeVisible({ timeout: 5_000 });
+  });
+
+  test('should open the 3-dot menu for a conversation', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const menuButton = page.locator('button[aria-label*="Actions for"]').first();
+    const hasMenu = (await menuButton.count()) > 0;
+    test.skip(!hasMenu, 'No conversations available for menu actions');
+
+    await menuButton.click();
+
+    const menu = page.locator('[role="menu"]');
+    await expect(menu).toBeVisible({ timeout: 5_000 });
+
+    await expect(
+      menu.getByRole('menuitem', { name: 'Delete' }),
+    ).toBeVisible({ timeout: 5_000 });
+    await expect(
+      menu.getByRole('menuitem', { name: 'Manage Shared Instances' }),
+    ).toBeVisible({ timeout: 5_000 });
+    await expect(
+      menu.getByRole('menuitem', { name: 'Copy Share Link' }),
+    ).toBeVisible({ timeout: 5_000 });
+
+    // Close the menu by clicking elsewhere
+    await page.locator('body').click({ position: { x: 10, y: 10 } });
+    await expect(menu).toBeHidden({ timeout: 5_000 });
+  });
+
+  test('should show and cancel the bulk delete confirmation dialog', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const checkbox = page.locator('input[type="checkbox"]').first();
+    const hasCheckbox = (await checkbox.count()) > 0;
+    test.skip(!hasCheckbox, 'No conversations available to select');
+
+    await checkbox.check();
+    await expect(page.getByText(/1 of \d+ selected/)).toBeVisible({ timeout: 5_000 });
+
+    await page.getByRole('button', { name: /Delete Selected/i }).click();
+
+    const dialog = page.locator('[role="alertdialog"]');
+    await expect(dialog).toBeVisible({ timeout: 5_000 });
+    await expect(dialog.getByText(/Delete 1 Conversation/)).toBeVisible({ timeout: 5_000 });
+
+    // Cancel
+    await dialog.getByRole('button', { name: 'Cancel' }).click();
+    await expect(dialog).toBeHidden({ timeout: 5_000 });
+
+    await checkbox.uncheck();
+  });
+
+  // -----------------------------------------------------------------------
+  // Conversation lifecycle: create → share → verify share → delete (serial)
+  //
+  // Creates a throwaway conversation via chat, shares it publicly,
+  // verifies the share link works, then deletes it from the
+  // manage-sessions page. Uses a shared page so the session persists
+  // across steps.
+  // -----------------------------------------------------------------------
+
+  test.describe.serial('Create, share, and delete a conversation', () => {
+    let page: Page;
+    let shareUrl: string;
+
+    test.beforeAll(async ({ browser }) => {
+      page = await browser.newPage();
+    });
+
+    test.afterAll(async () => {
+      await page.close();
+    });
+
+    test('should create a conversation by sending a message', async () => {
+      // This test does a real LLM round-trip — extend the default 30s timeout
+      test.setTimeout(120_000);
+
+      await page.goto('/');
+      await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+      // Wait for the model selector to finish loading (ensures the app is fully ready)
+      const modelButton = page.getByRole('button', { name: 'Select model' });
+      await expect(modelButton).not.toContainText('System Default', { timeout: 30_000 });
+
+      // Send a short message to create a session
+      await sendMessageAndWaitForResponse(page, 'Reply with exactly: hello');
+
+      // The URL should now contain /s/ indicating a session was created
+      await page.waitForURL(/\/s\//, { timeout: 10_000 });
+    });
+
+    test('should rename the conversation to a known title', async () => {
+      // The session options button is in the sidebar next to the active session
+      const sessionOptionsButton = page.locator('button[aria-haspopup="menu"]').filter({
+        has: page.locator('ng-icon[name="heroEllipsisHorizontalSolid"]'),
+      });
+      await sessionOptionsButton.first().hover();
+      await sessionOptionsButton.first().click();
+
+      await page.getByRole('menuitem', { name: 'Rename' }).click();
+
+      const renameInput = page.getByLabel('Rename conversation');
+      await expect(renameInput).toBeVisible({ timeout: 5_000 });
+
+      await renameInput.fill(DELETE_TEST_TITLE);
+      await renameInput.press('Enter');
+
+      // Wait for the rename input to disappear, confirming the rename was saved
+      // The input stays visible until the backend API call completes and the
+      // component clears renamingSessionId, so use a generous timeout.
+      await expect(renameInput).toBeHidden({ timeout: 15_000 });
+
+      // Verify the renamed session appears in the sidebar
+      const sessionLink = page.locator('app-session-list a').filter({
+        hasText: DELETE_TEST_TITLE,
+      });
+      await expect(sessionLink.first()).toBeVisible({ timeout: 10_000 });
+    });
+
+    test('should open the share dialog from the sidebar menu', async () => {
+      // Open the session options menu again
+      const sessionOptionsButton = page.locator('button[aria-haspopup="menu"]').filter({
+        has: page.locator('ng-icon[name="heroEllipsisHorizontalSolid"]'),
+      });
+      await sessionOptionsButton.first().hover();
+      await sessionOptionsButton.first().click();
+
+      // Click "Share" in the context menu
+      await page.getByRole('menuitem', { name: 'Share' }).click();
+
+      // The share dialog should appear
+      const dialog = page.getByRole('dialog', { name: 'Share conversation' });
+      await expect(dialog).toBeVisible({ timeout: 5_000 });
+
+      // "Public link" should be the default selected option
+      const publicRadio = dialog.locator('input[type="radio"][value="public"]');
+      await expect(publicRadio).toBeChecked({ timeout: 5_000 });
+
+      // Both access level options should be visible
+      await expect(dialog.getByText('Public link')).toBeVisible({ timeout: 5_000 });
+      await expect(dialog.getByText('Limited share')).toBeVisible({ timeout: 5_000 });
+
+      // "Create share link" button should be visible
+      await expect(
+        dialog.getByRole('button', { name: 'Create share link' }),
+      ).toBeVisible({ timeout: 5_000 });
+    });
+
+    test('should create a public share and generate a link', async () => {
+      const dialog = page.getByRole('dialog', { name: 'Share conversation' });
+
+      // Click "Create share link" with public access (already selected)
+      await dialog.getByRole('button', { name: 'Create share link' }).click();
+
+      // Wait for the success state — "Chat shared" confirmation
+      await expect(dialog.getByText('Chat shared')).toBeVisible({ timeout: 15_000 });
+
+      // The share URL input should be visible and contain a /shared/ path
+      const urlInput = dialog.locator('input[readonly][type="text"]');
+      await expect(urlInput).toBeVisible({ timeout: 5_000 });
+
+      const urlValue = await urlInput.inputValue();
+      expect(urlValue).toContain('/shared/');
+
+      // Store the URL for the next test
+      shareUrl = urlValue;
+
+      // The "Copy link" button should be visible
+      await expect(
+        dialog.getByRole('button', { name: 'Copy link' }),
+      ).toBeVisible({ timeout: 5_000 });
+
+      // The info text about future messages should be shown
+      await expect(
+        dialog.getByText("Future messages aren't included"),
+      ).toBeVisible({ timeout: 5_000 });
+
+      // The button text should now say "Done" instead of "Cancel"
+      await expect(
+        dialog.getByRole('button', { name: 'Done' }),
+      ).toBeVisible({ timeout: 5_000 });
+
+      // Close the dialog
+      await dialog.getByRole('button', { name: 'Done' }).click();
+      await expect(dialog).toBeHidden({ timeout: 5_000 });
+    });
+
+    test('should load the shared conversation via the share link', async () => {
+      // Navigate to the share URL
+      const sharePath = new URL(shareUrl).pathname;
+      await page.goto(sharePath);
+
+      // The shared view should load with the "Shared read-only snapshot" badge
+      await expect(
+        page.getByText('Shared read-only snapshot'),
+      ).toBeVisible({ timeout: 15_000 });
+
+      // The conversation messages should be visible
+      await expect(page.locator('app-message-list')).toBeVisible({ timeout: 10_000 });
+    });
+
+    test('should show the share in the Manage Shared Instances dialog', async () => {
+      await page.goto('/manage-sessions');
+      await expect(
+        page.getByRole('heading', { name: 'Manage Conversations' }),
+      ).toBeVisible({ timeout: 15_000 });
+      await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 15_000 });
+
+      // Target the actions button directly by its aria-label which includes the title
+      const menuButton = page.getByRole('button', { name: `Actions for ${DELETE_TEST_TITLE}` });
+      await expect(menuButton).toBeVisible({ timeout: 5_000 });
+      await menuButton.click();
+
+      const menu = page.locator('[role="menu"]');
+      await expect(menu).toBeVisible({ timeout: 5_000 });
+
+      // Open "Manage Shared Instances"
+      await menu.getByRole('menuitem', { name: 'Manage Shared Instances' }).click();
+
+      const dialog = page.getByRole('dialog', { name: 'Manage Shared Instances' });
+      await expect(dialog).toBeVisible({ timeout: 5_000 });
+
+      // Wait for loading
+      await expect(dialog.locator('.animate-spin')).toBeHidden({ timeout: 15_000 });
+
+      // The public share we created should be listed
+      await expect(dialog.getByText('Public')).toBeVisible({ timeout: 5_000 });
+
+      // A delete button for the share should be visible
+      const deleteShareButton = dialog.getByLabel('Delete share');
+      await expect(deleteShareButton.first()).toBeVisible({ timeout: 5_000 });
+
+      // Close the dialog
+      await dialog.getByRole('button', { name: 'Done' }).click();
+      await expect(dialog).toBeHidden({ timeout: 5_000 });
+    });
+
+    test('should delete the conversation via the context menu', async () => {
+      // Target the actions button directly by its aria-label which includes the title
+      const menuButton = page.getByRole('button', { name: `Actions for ${DELETE_TEST_TITLE}` });
+      await expect(menuButton).toBeVisible({ timeout: 5_000 });
+      await menuButton.click();
+
+      const menu = page.locator('[role="menu"]');
+      await expect(menu).toBeVisible({ timeout: 5_000 });
+
+      // Click "Delete"
+      await menu.getByRole('menuitem', { name: 'Delete' }).click();
+
+      // Confirm in the dialog
+      const dialog = page.locator('[role="alertdialog"]');
+      await expect(dialog).toBeVisible({ timeout: 5_000 });
+      await expect(dialog.getByText('Delete Conversation')).toBeVisible({ timeout: 5_000 });
+
+      await dialog.getByRole('button', { name: 'Delete' }).click();
+      await expect(dialog).toBeHidden({ timeout: 10_000 });
+
+      // The conversation should be gone from the list
+      await expect(menuButton).toBeHidden({ timeout: 10_000 });
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Manage Shared Instances dialog
+  // -----------------------------------------------------------------------
+
+  test('should open the Manage Shared Instances dialog', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const menuButton = page.locator('button[aria-label*="Actions for"]').first();
+    const hasMenu = (await menuButton.count()) > 0;
+    test.skip(!hasMenu, 'No conversations available for sharing actions');
+
+    await menuButton.click();
+
+    const menu = page.locator('[role="menu"]');
+    await expect(menu).toBeVisible({ timeout: 5_000 });
+
+    await menu.getByRole('menuitem', { name: 'Manage Shared Instances' }).click();
+
+    // Use a named role locator to avoid matching the CDK dialog wrapper element
+    const dialog = page.getByRole('dialog', { name: 'Manage Shared Instances' });
+    await expect(dialog).toBeVisible({ timeout: 5_000 });
+    await expect(dialog.getByText('Manage Shared Instances')).toBeVisible({ timeout: 5_000 });
+
+    // Wait for loading to finish
+    await expect(dialog.locator('.animate-spin')).toBeHidden({ timeout: 15_000 });
+
+    const hasShares = (await dialog.locator('text=Public').count()) > 0
+      || (await dialog.locator('text=Limited Access').count()) > 0;
+
+    if (!hasShares) {
+      await expect(dialog.getByText('No shared instances for this conversation')).toBeVisible({ timeout: 5_000 });
+    }
+
+    // Close via "Done"
+    await dialog.getByRole('button', { name: 'Done' }).click();
+    await expect(dialog).toBeHidden({ timeout: 5_000 });
+  });
+
+  test('should close the Manage Shared Instances dialog via the X button', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const menuButton = page.locator('button[aria-label*="Actions for"]').first();
+    const hasMenu = (await menuButton.count()) > 0;
+    test.skip(!hasMenu, 'No conversations available for sharing actions');
+
+    await menuButton.click();
+
+    const menu = page.locator('[role="menu"]');
+    await expect(menu).toBeVisible({ timeout: 5_000 });
+
+    await menu.getByRole('menuitem', { name: 'Manage Shared Instances' }).click();
+
+    // Use a named role locator to avoid matching the CDK dialog wrapper element
+    const dialog = page.getByRole('dialog', { name: 'Manage Shared Instances' });
+    await expect(dialog).toBeVisible({ timeout: 5_000 });
+
+    await dialog.getByLabel('Close dialog').click();
+    await expect(dialog).toBeHidden({ timeout: 5_000 });
+  });
+
+  // -----------------------------------------------------------------------
+  // Manage Conversations — navigation
+  // -----------------------------------------------------------------------
+
+  test('should navigate back from manage conversations to home', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    await page.getByText('Back').click();
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('should refresh the conversations list', async ({ page }) => {
+    await goToManageSessionsPage(page);
+
+    const refreshButton = page.getByLabel('Refresh conversations');
+    await expect(refreshButton).toBeVisible({ timeout: 5_000 });
+
+    await refreshButton.click();
+
+    await expect(
+      page.getByRole('heading', { name: 'Manage Conversations' }),
+    ).toBeVisible({ timeout: 15_000 });
+    await expect(page.getByText(/0 of \d+ selected/)).toBeVisible({ timeout: 15_000 });
+  });
+
+  // -----------------------------------------------------------------------
+  // Memories page — basic navigation and structure
+  // -----------------------------------------------------------------------
+
+  test('should load the Memories page and show status', async ({ page }) => {
+    await page.goto('/memories');
+    await expect(
+      page.getByRole('heading', { name: 'Memories' }),
+    ).toBeVisible({ timeout: 15_000 });
+
+    // Wait for the status check to complete
+    await expect(page.getByText('Checking memory status...')).toBeHidden({ timeout: 15_000 });
+
+    // Either memory is available (shows the info banner) or unavailable (shows warning)
+    const isAvailable = (await page.getByText('automatically extracted from your conversations').count()) > 0;
+    const isUnavailable = (await page.getByText('Memory Not Available').count()) > 0;
+
+    expect(isAvailable || isUnavailable).toBe(true);
+  });
+});
diff --git a/frontend/ai.client/e2e/settings/profile.user.spec.ts b/frontend/ai.client/e2e/settings/profile.user.spec.ts
new file mode 100644
index 00000000..282f27b7
--- /dev/null
+++ b/frontend/ai.client/e2e/settings/profile.user.spec.ts
@@ -0,0 +1,182 @@
+import { test, expect, Page } from '@playwright/test';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Navigate to the settings/profile page and wait for it to load. */
+async function goToProfilePage(page: Page) {
+  await page.goto('/settings/profile');
+  await expect(
+    page.getByRole('heading', { name: 'Settings' }),
+  ).toBeVisible({ timeout: 15_000 });
+  await expect(page.getByRole('heading', { name: 'Profile' })).toBeVisible({ timeout: 10_000 });
+}
+
+/** Navigate to the My Files page and wait for it to load. */
+// async function goToFilesPage(page: Page) {
+//   await page.goto('/files');
+//   await expect(
+//     page.getByRole('heading', { name: 'My Files' }),
+//   ).toBeVisible({ timeout: 15_000 });
+//   // Wait for loading to finish
+//   await expect(page.getByText('Loading files...')).toBeHidden({ timeout: 15_000 });
+// }
+
+/** Send a chat message and wait for the assistant to finish responding. */
+// async function sendMessageAndWaitForResponse(page: Page, message: string) {
+//   const textarea = page.locator('textarea#user-message');
+//   await expect(textarea).toBeVisible({ timeout: 15_000 });
+//   await textarea.fill(message);
+
+//   await page.getByRole('button', { name: 'Submit message' }).click();
+
+//   const assistantMessage = page.locator('app-assistant-message').last();
+//   await expect(assistantMessage).toBeVisible({ timeout: 60_000 });
+//   await expect(page.locator('app-pulsating-loader')).toBeHidden({ timeout: 200_000 });
+// }
+
+// ---------------------------------------------------------------------------
+// Independent profile page tests
+// ---------------------------------------------------------------------------
+
+test.describe('Settings / Profile (user)', () => {
+  test('should display the profile page with correct user info', async ({ page }) => {
+    await goToProfilePage(page);
+
+    // Verify user name (in the avatar/name header section)
+    await expect(page.getByRole('heading', { name: 'test_user' })).toBeVisible({ timeout: 10_000 });
+
+    // Verify email (in the avatar/name header section, scoped to avoid the details row)
+    await expect(page.locator('dd').filter({ hasText: 'oscarfilson@boisestate.edu' })).toBeVisible({ timeout: 10_000 });
+
+    // Verify managed by Entra ID badge
+    await expect(page.getByText('Managed by Entra ID')).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('should show the full name in the read-only details', async ({ page }) => {
+    await goToProfilePage(page);
+
+    // The "Full name" label and value should be visible in the details section
+    const fullNameLabel = page.getByText('Full name');
+    await expect(fullNameLabel).toBeVisible({ timeout: 10_000 });
+
+    // The name value should appear in the details row
+    await expect(page.locator('dd').filter({ hasText: 'test_user' })).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('should show the email in the read-only details', async ({ page }) => {
+    await goToProfilePage(page);
+
+    const emailLabel = page.locator('dt').filter({ hasText: 'Email' });
+    await expect(emailLabel).toBeVisible({ timeout: 10_000 });
+
+    await expect(page.locator('dd').filter({ hasText: 'oscarfilson@boisestate.edu' })).toBeVisible({ timeout: 10_000 });
+  });
+
+  test('should show the My Files link and navigate to files page', async ({ page }) => {
+    await goToProfilePage(page);
+
+    const myFilesLink = page.getByRole('link', { name: /My Files/i });
+    await expect(myFilesLink).toBeVisible({ timeout: 10_000 });
+
+    await myFilesLink.click();
+    await page.waitForURL(/\/files/, { timeout: 10_000 });
+    await expect(
+      page.getByRole('heading', { name: 'My Files' }),
+    ).toBeVisible({ timeout: 15_000 });
+  });
+
+  test('should navigate back to chat from settings', async ({ page }) => {
+    await goToProfilePage(page);
+
+    const backLink = page.getByRole('link', { name: /Back to Chat/i });
+    await expect(backLink).toBeVisible({ timeout: 10_000 });
+    await backLink.click();
+
+    await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+  });
+
+//   // -------------------------------------------------------------------------
+//   // Serial: File upload → My Files → Delete conversation → File gone
+//   // -------------------------------------------------------------------------
+
+// const TEST_FILE_NAME = 'e2e-profile-test.txt';
+// const TEST_FILE_CONTENT = 'Hello from Playwright e2e profile test.';
+
+//   test.describe.serial('File lifecycle via chat and My Files', () => {
+//     let page: Page;
+
+//     test.beforeAll(async ({ browser }) => {
+//       page = await browser.newPage();
+//     });
+
+//     test.afterAll(async () => {
+//       await page.close();
+//     });
+
+//     test('should upload a file in a new chat and send a message', async () => {
+//       await page.goto('/');
+//       await expect(page.locator('textarea#user-message')).toBeVisible({ timeout: 15_000 });
+
+//       // Attach a real text file
+//       const fileInput = page.locator('input#file-upload');
+//       await fileInput.setInputFiles({
+//         name: TEST_FILE_NAME,
+//         mimeType: 'text/plain',
+//         buffer: Buffer.from(TEST_FILE_CONTENT),
+//       });
+
+//       // Wait for the file card to appear (upload in progress or completed)
+//       const fileCard = page.locator('app-file-card');
+//       await expect(fileCard.first()).toBeVisible({ timeout: 15_000 });
+
+//       // Send a message to create the conversation
+//       await sendMessageAndWaitForResponse(page, 'Describe the attached file in one sentence.');
+
+//       // We should now be in a session URL
+//       await page.waitForURL(/\/s\//, { timeout: 15_000 });
+//     });
+
+//     test('should see the uploaded file in My Files', async () => {
+//       await goToFilesPage(page);
+
+//       // The uploaded file should appear in the list
+//       await expect(page.getByText(TEST_FILE_NAME)).toBeVisible({ timeout: 15_000 });
+//     });
+
+//     test('should navigate back and delete the conversation', async () => {
+//       // Go to manage sessions
+//       await page.goto('/manage-sessions');
+//       await expect(
+//         page.getByRole('heading', { name: 'Manage Conversations' }),
+//       ).toBeVisible({ timeout: 15_000 });
+//       await expect(page.getByText('Loading conversations...')).toBeHidden({ timeout: 30_000 });
+
+//       // Find the most recent conversation and select it
+//       const checkbox = page.locator('input[type="checkbox"]').first();
+//       await expect(checkbox).toBeVisible({ timeout: 10_000 });
+//       await checkbox.check();
+
+//       // Click Delete Selected
+//       const deleteBtn = page.getByRole('button', { name: /Delete Selected/i });
+//       await expect(deleteBtn).toBeEnabled({ timeout: 5_000 });
+//       await deleteBtn.click();
+
+//       // Confirm the deletion dialog
+//       const confirmBtn = page.getByRole('button', { name: /^Delete$/i }).last();
+//       await expect(confirmBtn).toBeVisible({ timeout: 5_000 });
+//       await confirmBtn.click();
+
+//       // Wait for deletion to complete (toast or list update)
+//       await expect(page.getByText(/Deleted|deleted/)).toBeVisible({ timeout: 15_000 });
+//     });
+
+//     test('should no longer see the file in My Files', async () => {
+//       await goToFilesPage(page);
+
+//       // The file should no longer be listed
+//       await expect(page.getByText(TEST_FILE_NAME)).toBeHidden({ timeout: 15_000 });
+//     });
+//   });
+});
diff --git a/frontend/ai.client/e2e/settings/usage.user.spec.ts b/frontend/ai.client/e2e/settings/usage.user.spec.ts
new file mode 100644
index 00000000..7d65abae
--- /dev/null
+++ b/frontend/ai.client/e2e/settings/usage.user.spec.ts
@@ -0,0 +1,115 @@
+import { test, expect, Page } from '@playwright/test';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Navigate to the usage settings page and wait for it to load. */
+async function goToUsagePage(page: Page) {
+  await page.goto('/settings/usage');
+  await expect(
+    page.getByRole('heading', { name: 'Settings' }),
+  ).toBeVisible({ timeout: 15_000 });
+  await expect(
+    page.getByRole('heading', { name: 'Usage' }),
+  ).toBeVisible({ timeout: 10_000 });
+}
+
+/** Wait for any loading indicator to disappear. */
+async function waitForDataLoaded(page: Page) {
+  await expect(page.getByText('Loading cost data...')).toBeHidden({ timeout: 15_000 });
+}
+
+/** Read the "Total Tokens" card value as a raw number (strips formatting commas). */
+async function getTotalTokens(page: Page): Promise<number> {
+  const card = page.locator('div').filter({ hasText: /^Total Tokens/ });
+  const value = card.locator('p.text-2xl');
+  await expect(value).toBeVisible({ timeout: 10_000 });
+  const text = (await value.innerText()).trim();
+  return Number(text.replace(/,/g, ''));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test.describe('Settings / Usage (user)', () => {
+  test.describe.serial('Usage page loads and filters work correctly', () => {
+    let page: Page;
+
+    test.beforeAll(async ({ browser }) => {
+      page = await browser.newPage();
+    });
+
+    test.afterAll(async () => {
+      await page.close();
+    });
+
+    let currentMonthTokens: number;
+
+    test('should load the usage page with current month data', async () => {
+      await goToUsagePage(page);
+      await waitForDataLoaded(page);
+
+      // The "Current Month" button should be active (blue)
+      const currentMonthBtn = page.getByRole('button', { name: 'Current Month' });
+      await expect(currentMonthBtn).toBeVisible({ timeout: 5_000 });
+      await expect(currentMonthBtn).toHaveClass(/bg-blue-600/, { timeout: 5_000 });
+
+      // All four summary cards should be visible
+      await expect(page.getByText('Total Cost')).toBeVisible({ timeout: 5_000 });
+      await expect(page.getByText('Total Requests')).toBeVisible({ timeout: 5_000 });
+      await expect(page.getByText('Total Tokens')).toBeVisible({ timeout: 5_000 });
+      await expect(page.getByText('Token Breakdown')).toBeVisible({ timeout: 5_000 });
+
+      // Capture the current month token count for comparison
+      currentMonthTokens = await getTotalTokens(page);
+    });
+
+    test('should show different token count for Last 30 Days', async () => {
+      // Click the "Last 30 Days" filter
+      const last30Btn = page.getByRole('button', { name: 'Last 30 Days' });
+      await last30Btn.click();
+
+      // The button should now be active
+      await expect(last30Btn).toHaveClass(/bg-blue-600/, { timeout: 5_000 });
+
+      // "Current Month" should no longer be active
+      const currentMonthBtn = page.getByRole('button', { name: 'Current Month' });
+      await expect(currentMonthBtn).not.toHaveClass(/bg-blue-600/, { timeout: 5_000 });
+
+      // Wait for the data to load
+      await waitForDataLoaded(page);
+
+      // The total tokens for last 30 days should differ from the current month
+      // (last 30 days spans two calendar months, so unless it's the 1st of the
+      // month with zero prior usage, the numbers won't match)
+      const last30Tokens = await getTotalTokens(page);
+      expect(last30Tokens).not.toBe(currentMonthTokens);
+    });
+
+    test('should show 0 tokens for February 2026 via the month dropdown', async () => {
+      // Select February 2026 from the previous months dropdown
+      // Scope to the month picker (not the settings nav select) via its placeholder text
+      const dropdown = page.locator('select').filter({ hasText: 'Previous month...' });
+      await expect(dropdown).toBeVisible({ timeout: 5_000 });
+      await dropdown.selectOption('2026-02');
+
+      // Wait for the data to load
+      await waitForDataLoaded(page);
+
+      // Feb 2026 should have no usage — either 0 tokens or the "No cost data" message
+      const noDataMessage = page.getByText('No cost data available for this period');
+      const hasNoData = (await noDataMessage.count()) > 0;
+
+      if (hasNoData) {
+        // The empty state message is shown — that confirms 0 usage
+        await expect(noDataMessage).toBeVisible({ timeout: 5_000 });
+      } else {
+        // The cards are shown but tokens should be 0
+        const tokens = await getTotalTokens(page);
+        expect(tokens).toBe(0);
+      }
+    });
+  });
+});
diff --git a/frontend/ai.client/e2e/tsconfig.json b/frontend/ai.client/e2e/tsconfig.json
new file mode 100644
index 00000000..a4a2a1d3
--- /dev/null
+++ b/frontend/ai.client/e2e/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true
+  },
+  "include": ["./**/*.ts"]
+}
diff --git a/frontend/ai.client/package.json b/frontend/ai.client/package.json
index a9afdf23..0c1f3300 100644
--- a/frontend/ai.client/package.json
+++ b/frontend/ai.client/package.json
@@ -7,7 +7,10 @@
     "build": "ng build",
     "watch": "ng build --watch --configuration development",
     "test": "ng test",
-    "test:ci": "ng test --watch=false"
+    "test:ci": "ng test --watch=false",
+    "e2e": "playwright test",
+    "e2e:ui": "playwright test --ui",
+    "e2e:headed": "playwright test --headed"
   },
   "prettier": {
     "printWidth": 100,
@@ -52,8 +55,11 @@
     "@angular/build": "21.2.6",
     "@angular/cli": "21.2.6",
     "@angular/compiler-cli": "21.2.7",
+    "@playwright/test": "1.59.1",
     "@tailwindcss/postcss": "4.2.2",
+    "@types/node": "25.6.0",
     "@vitest/coverage-v8": "4.1.2",
+    "dotenv": "17.4.2",
     "fast-check": "4.6.0",
     "jsdom": "29.0.1",
     "postcss": "8.5.8",
diff --git a/frontend/ai.client/playwright.ci.config.ts b/frontend/ai.client/playwright.ci.config.ts
new file mode 100644
index 00000000..e38dce1a
--- /dev/null
+++ b/frontend/ai.client/playwright.ci.config.ts
@@ -0,0 +1,80 @@
+/**
+ * Playwright CI configuration for running E2E tests against a deployed stack.
+ *
+ * Unlike the local config (playwright.config.ts), this does NOT start any
+ * web servers — the App API, Inference API, and frontend are already running
+ * on the deployed nightly stack. The base URL is provided via E2E_BASE_URL.
+ *
+ * Usage:
+ *   E2E_BASE_URL=https://nightly-develop-api.example.com \
+ *   ADMIN_USERNAME=... ADMIN_PASSWORD=... \
+ *   USER_USERNAME=... USER_PASSWORD=... \
+ *   npx playwright test --config=playwright.ci.config.ts
+ */
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+const baseURL = process.env['E2E_BASE_URL'];
+if (!baseURL) {
+  throw new Error('E2E_BASE_URL environment variable is required for CI config');
+}
+
+const authDir = path.join(__dirname, 'e2e', '.auth');
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: true,
+  retries: 2,
+  workers: 1,
+  reporter: [['html', { open: 'never' }], ['list']],
+  use: {
+    baseURL,
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  /* No webServer — tests run against the already-deployed stack */
+
+  projects: [
+    // --- Setup projects (login & save storage state) ---
+    {
+      name: 'admin-setup',
+      testMatch: /auth-admin\.setup\.ts/,
+    },
+    {
+      name: 'user-setup',
+      testMatch: /auth-user\.setup\.ts/,
+    },
+
+    // --- Unauthenticated tests (no login needed) ---
+    {
+      name: 'chromium',
+      testIgnore: /\.setup\.ts|\.auth\./,
+      testMatch: /(?:login|navigation|not-found)\.spec\.ts/,
+      use: { browserName: 'chromium' },
+    },
+
+    // --- Authenticated tests (admin) ---
+    {
+      name: 'admin',
+      testMatch: /\.auth\.spec\.ts/,
+      dependencies: ['admin-setup'],
+      use: {
+        browserName: 'chromium',
+        storageState: path.join(authDir, 'admin.json'),
+      },
+    },
+
+    // --- Authenticated tests (regular user) ---
+    {
+      name: 'user',
+      testMatch: /\.user\.spec\.ts/,
+      dependencies: ['user-setup'],
+      use: {
+        browserName: 'chromium',
+        storageState: path.join(authDir, 'user.json'),
+      },
+    },
+  ],
+});
diff --git a/frontend/ai.client/playwright.config.ts b/frontend/ai.client/playwright.config.ts
new file mode 100644
index 00000000..5f82fc7d
--- /dev/null
+++ b/frontend/ai.client/playwright.config.ts
@@ -0,0 +1,90 @@
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+import dotenv from 'dotenv';
+
+// Load e2e test credentials from e2e/.env
+dotenv.config({ path: path.resolve(__dirname, 'e2e', '.env') });
+
+const authDir = path.join(__dirname, 'e2e', '.auth');
+const backendDir = path.resolve(__dirname, '..', '..', 'backend');
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env['CI'],
+  retries: process.env['CI'] ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  use: {
+    baseURL: 'http://localhost:4200',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  webServer: [
+    {
+      command: 'uv run python src/apis/app_api/main.py',
+      cwd: backendDir,
+      url: 'http://localhost:8000/health',
+      reuseExistingServer: !process.env['CI'],
+      timeout: 60_000,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    },
+    {
+      command: 'uv run python src/apis/inference_api/main.py',
+      cwd: backendDir,
+      url: 'http://localhost:8001/ping',
+      reuseExistingServer: !process.env['CI'],
+      timeout: 60_000,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    },
+    {
+      command: 'npm run start -- --port 4200',
+      url: 'http://localhost:4200',
+      reuseExistingServer: !process.env['CI'],
+      timeout: 120_000,
+    },
+  ],
+  projects: [
+    // --- Setup projects (login & save storage state) ---
+    {
+      name: 'admin-setup',
+      testMatch: /auth-admin\.setup\.ts/,
+    },
+    {
+      name: 'user-setup',
+      testMatch: /auth-user\.setup\.ts/,
+    },
+
+    // --- Unauthenticated tests (no login needed) ---
+    {
+      name: 'chromium',
+      testIgnore: /\.setup\.ts|\.auth\./,
+      testMatch: /(?:login|navigation|not-found)\.spec\.ts/,
+      use: { browserName: 'chromium' },
+    },
+
+    // --- Authenticated tests (admin) ---
+    {
+      name: 'admin',
+      testMatch: /\.auth\.spec\.ts/,
+      dependencies: ['admin-setup'],
+      use: {
+        browserName: 'chromium',
+        storageState: path.join(authDir, 'admin.json'),
+      },
+    },
+
+    // --- Authenticated tests (regular user) ---
+    {
+      name: 'user',
+      testMatch: /\.user\.spec\.ts/,
+      dependencies: ['user-setup'],
+      use: {
+        browserName: 'chromium',
+        storageState: path.join(authDir, 'user.json'),
+      },
+    },
+  ],
+});
diff --git a/frontend/ai.client/public/audio/pcm-capture.worklet.js b/frontend/ai.client/public/audio/pcm-capture.worklet.js
new file mode 100644
index 00000000..34fca457
--- /dev/null
+++ b/frontend/ai.client/public/audio/pcm-capture.worklet.js
@@ -0,0 +1,17 @@
+/**
+ * AudioWorklet processor that captures PCM samples from the microphone
+ * and forwards them to the main thread via MessagePort.
+ *
+ * Registered as 'pcm-capture' and used by AudioRecorderService.
+ */
+class PcmCaptureProcessor extends AudioWorkletProcessor {
+  process(inputs) {
+    const input = inputs[0];
+    if (input && input[0] && input[0].length > 0) {
+      this.port.postMessage(new Float32Array(input[0]));
+    }
+    return true;
+  }
+}
+
+registerProcessor('pcm-capture', PcmCaptureProcessor);
diff --git a/frontend/ai.client/src/app/admin/manage-models/model-form.page.ts b/frontend/ai.client/src/app/admin/manage-models/model-form.page.ts
index 1dcdddcf..44872257 100644
--- a/frontend/ai.client/src/app/admin/manage-models/model-form.page.ts
+++ b/frontend/ai.client/src/app/admin/manage-models/model-form.page.ts
@@ -46,7 +46,7 @@ export class ModelFormPage implements OnInit {
 
   // Available options for multi-select fields
   readonly availableProviders = AVAILABLE_PROVIDERS;
-  readonly availableModalities = ['TEXT', 'IMAGE', 'VIDEO', 'AUDIO', 'EMBEDDING'];
+  readonly availableModalities = ['TEXT', 'IMAGE', 'VIDEO', 'AUDIO', 'SPEECH', 'EMBEDDING'];
 
   // AppRoles from the API (reactive resource)
   readonly rolesResource = this.appRolesService.rolesResource;
diff --git a/frontend/ai.client/src/app/components/model-dropdown/model-dropdown.component.ts b/frontend/ai.client/src/app/components/model-dropdown/model-dropdown.component.ts
index 841cd9f5..1c615691 100644
--- a/frontend/ai.client/src/app/components/model-dropdown/model-dropdown.component.ts
+++ b/frontend/ai.client/src/app/components/model-dropdown/model-dropdown.component.ts
@@ -22,7 +22,7 @@ import { ManagedModel } from '../../admin/manage-models/models/managed-model.mod
         class="flex items-center gap-2 rounded-lg px-3 py-1.5 text-sm text-gray-600 dark:text-gray-400 transition-colors hover:bg-gray-100 hover:text-gray-700 dark:hover:bg-white/5 dark:hover:text-gray-300 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-primary)]"
         aria-label="Select model"
       >
-        <span>{{ modelService.selectedModel()?.modelName || 'Loading...' }}</span>
+        <span>{{ modelService.selectedModel().modelName || 'Loading...' }}</span>
         <svg
           viewBox="0 0 20 20"
           fill="currentColor"
@@ -66,7 +66,7 @@ import { ManagedModel } from '../../admin/manage-models/models/managed-model.mod
                 disabled
               >
                 <div class="flex flex-col items-start">
-                  <span class="font-medium">{{ modelService.selectedModel()?.modelName || 'System Default' }}</span>
+                  <span class="font-medium">{{ modelService.selectedModel().modelName || 'System Default' }}</span>
                   <span class="text-xs text-gray-500 dark:text-gray-400">Using backend default</span>
                 </div>
                 <ng-icon name="heroCheck" class="size-5 text-primary-500 dark:text-slate-400" aria-hidden="true" />
diff --git a/frontend/ai.client/src/app/components/model-settings/model-settings.html b/frontend/ai.client/src/app/components/model-settings/model-settings.html
index cf8284cd..7e20ce3c 100644
--- a/frontend/ai.client/src/app/components/model-settings/model-settings.html
+++ b/frontend/ai.client/src/app/components/model-settings/model-settings.html
@@ -65,7 +65,7 @@ <h2 id="model-settings-title" class="text-base/6 font-semibold text-gray-900 dar
               (keydown)="onDropdownKeydown($event)"
               class="flex w-full items-center justify-between gap-2 rounded-sm bg-white px-2.5 py-1.5 text-left outline-1 -outline-offset-1 outline-gray-300 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary-600 dark:bg-white/5 dark:outline-white/10 dark:focus-visible:outline-primary-400">
               <span class="truncate text-sm/5 font-medium text-gray-900 dark:text-white">
-                {{ modelService.selectedModel()?.modelName }}
+                {{ modelService.selectedModel().modelName }}
               </span>
               <ng-icon
                 name="heroChevronDown"
diff --git a/frontend/ai.client/src/app/components/sidenav/sidenav.html b/frontend/ai.client/src/app/components/sidenav/sidenav.html
index 70c8022f..0a083348 100644
--- a/frontend/ai.client/src/app/components/sidenav/sidenav.html
+++ b/frontend/ai.client/src/app/components/sidenav/sidenav.html
@@ -9,7 +9,7 @@
             [appTooltip]="'Close sidebar'"
             appTooltipPosition="right"
             class="hidden lg:flex items-center justify-center size-8 rounded-md text-gray-500 hover:bg-gray-200 hover:text-gray-700 dark:text-gray-400 dark:hover:bg-white/10 dark:hover:text-white"
-            [attr.aria-label]="isCollapsed() ? 'Expand sidebar' : 'Collapse sidebar'">
+            aria-label="Collapse sidebar">
             <!-- Sidebar panel icon -->
             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" class="size-6" aria-hidden="true">
                 <rect x="3" y="4" width="18" height="16" rx="2" ry="2" />
diff --git a/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.html b/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.html
index abd1f8a4..fb713cb8 100644
--- a/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.html
+++ b/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.html
@@ -23,7 +23,7 @@
         <div class="w-full max-w-[720px] animate-fade-in px-4 mt-0 relative">
           <!-- Greeting (hidden when assistant is selected or loading) -->
           @if (!assistant() && !isLoadingAssistant()) {
-            <div class="mb-8 flex items-center justify-center gap-4 relative">
+            <div class="mb-8 flex items-center justify-center gap-4 relative" data-testid="greeting-message">
               <div>
                 <app-animated-text [text]="greetingMessage()" [speed]="50" />
               </div>
@@ -71,6 +71,7 @@
           (messageSubmitted)="onMessageSubmitted($event)"
           (messageCancelled)="onMessageCancelled()"
           (fileAttached)="onFileAttached($event)"
+
           (settingsToggled)="onSettingsToggled()">
         </app-chat-input>
       </div>
@@ -126,6 +127,7 @@
             (messageSubmitted)="onMessageSubmitted($event)"
             (messageCancelled)="onMessageCancelled()"
             (fileAttached)="onFileAttached($event)"
+  
             (settingsToggled)="onSettingsToggled()">
           </app-chat-input>
         </div>
@@ -178,6 +180,7 @@
             (messageSubmitted)="onMessageSubmitted($event)"
             (messageCancelled)="onMessageCancelled()"
             (fileAttached)="onFileAttached($event)"
+  
             (settingsToggled)="onSettingsToggled()">
           </app-chat-input>
         </div>
@@ -188,7 +191,7 @@
         class="chat-container-empty full-page"
         [class.sidenav-expanded]="!isSidenavCollapsed()">
         <div class="w-full max-w-[720px] animate-fade-in px-4 -mt-20 relative">
-          <div class="mb-8 flex items-center justify-center gap-4 relative">
+          <div class="mb-8 flex items-center justify-center gap-4 relative" data-testid="greeting-message">
             <img
               src="/img/logo-light.png"
               alt="Logo"
@@ -217,6 +220,7 @@
               (messageSubmitted)="onMessageSubmitted($event)"
               (messageCancelled)="onMessageCancelled()"
               (fileAttached)="onFileAttached($event)"
+    
               (settingsToggled)="onSettingsToggled()">
             </app-chat-input>
           </div>
@@ -279,6 +283,7 @@
           (messageSubmitted)="onMessageSubmitted($event)"
           (messageCancelled)="onMessageCancelled()"
           (fileAttached)="onFileAttached($event)"
+
           (settingsToggled)="onSettingsToggled()">
         </app-chat-input>
       </div>
@@ -346,9 +351,15 @@
           (messageSubmitted)="onMessageSubmitted($event)"
           (messageCancelled)="onMessageCancelled()"
           (fileAttached)="onFileAttached($event)"
+
           (settingsToggled)="onSettingsToggled()">
         </app-chat-input>
       </div>
     </div>
   }
 }
+
+<!-- Voice Conversation Overlay -->
+@if (isVoiceActive()) {
+  <app-voice-overlay (closed)="onVoiceClosed()" />
+}
diff --git a/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.ts b/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.ts
index 24ca1f34..9d96b768 100644
--- a/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.ts
+++ b/frontend/ai.client/src/app/session/components/chat-container/chat-container.component.ts
@@ -19,6 +19,8 @@ import { SidenavService } from '../../../services/sidenav/sidenav.service';
 import { Assistant } from '../../../assistants/models/assistant.model';
 import { AssistantCardComponent } from '../../../assistants/components/assistant-card.component';
 import { AssistantIndicatorComponent } from '../assistant-indicator/assistant-indicator.component';
+import { VoiceOverlayComponent } from '../voice-overlay';
+import { VoiceChatService } from '../../services/voice';
 
 /**
  * Configuration options for ChatContainerComponent.
@@ -58,6 +60,7 @@ export interface ChatContainerConfig {
     NgIcon,
     AssistantCardComponent,
     AssistantIndicatorComponent,
+    VoiceOverlayComponent,
   ],
   providers: [provideIcons({ heroXMark })],
   changeDetection: ChangeDetectionStrategy.OnPush,
@@ -67,6 +70,8 @@ export interface ChatContainerConfig {
 export class ChatContainerComponent {
   // Inject sidenav service for full-page mode positioning
   protected sidenavService = inject(SidenavService);
+  private voiceChatService = inject(VoiceChatService);
+  protected readonly isVoiceActive = this.voiceChatService.isVoiceActive;
 
   // Child component reference for scroll functionality
   private messageListComponent = viewChild(MessageListComponent);
@@ -107,6 +112,7 @@ export class ChatContainerComponent {
   assistantNewSession = output<void>();
   assistantEdit = output<void>();
   assistantShare = output<void>();
+  voiceClosed = output<void>();
 
   // Computed signals
   protected readonly hasMessages = computed(() => this.messages().length > 0);
@@ -173,4 +179,8 @@ export class ChatContainerComponent {
   onAssistantShare() {
     this.assistantShare.emit();
   }
+
+  onVoiceClosed() {
+    this.voiceClosed.emit();
+  }
 }
diff --git a/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.html b/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.html
index 217a0811..d219ddf8 100644
--- a/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.html
+++ b/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.html
@@ -100,6 +100,40 @@
               <ng-icon name="heroAdjustmentsHorizontal" class="size-5" aria-hidden="true" />
             </button>
           }
+
+          <!-- Voice Toggle Button -->
+          <button
+            type="button"
+            (click)="toggleVoice()"
+            [class]="voiceButtonClass()"
+            [attr.aria-label]="voiceAriaLabel()"
+            [appTooltip]="voiceTooltip()"
+            appTooltipPosition="top"
+          >
+            @if (voiceStatus() === 'listening') {
+              <!-- Pulsing dot indicator for listening -->
+              <span class="relative flex size-3">
+                <span class="absolute inline-flex size-full animate-ping rounded-full bg-red-400 opacity-75"></span>
+                <span class="relative inline-flex size-3 rounded-full bg-red-500"></span>
+              </span>
+            } @else if (voiceStatus() === 'speaking') {
+              <!-- Wave bars for speaking -->
+              <span class="flex items-center gap-0.5" aria-hidden="true">
+                <span class="h-3 w-0.5 animate-bounce rounded-full bg-green-500" style="animation-delay: 0ms;"></span>
+                <span class="h-4 w-0.5 animate-bounce rounded-full bg-green-500" style="animation-delay: 150ms;"></span>
+                <span class="h-3 w-0.5 animate-bounce rounded-full bg-green-500" style="animation-delay: 300ms;"></span>
+              </span>
+            } @else if (voiceStatus() === 'connecting') {
+              <!-- Spinner for connecting -->
+              <svg class="size-5 animate-spin" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+                <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+                <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"></path>
+              </svg>
+            } @else {
+              <!-- Mic icon for idle -->
+              <ng-icon name="heroMicrophone" class="size-5" aria-hidden="true" />
+            }
+          </button>
         </div>
 
         <!-- Right Controls -->
diff --git a/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.ts b/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.ts
index 382ab15e..0d67ce96 100644
--- a/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.ts
+++ b/frontend/ai.client/src/app/session/components/chat-input/chat-input.component.ts
@@ -5,6 +5,7 @@ import {
   heroPlus,
   heroAdjustmentsHorizontal,
   heroClock,
+  heroMicrophone,
 } from '@ng-icons/heroicons/outline';
 import { heroPaperAirplaneSolid, heroStopSolid } from '@ng-icons/heroicons/solid';
 import { ModelDropdownComponent } from '../../../components/model-dropdown/model-dropdown.component';
@@ -21,6 +22,7 @@ import {
   formatBytes
 } from '../../../services/file-upload';
 import { ToastService } from '../../../services/toast/toast.service';
+import { VoiceChatService, type VoiceStatus } from '../../services/voice';
 
 interface Message {
   content: string;
@@ -36,6 +38,7 @@ interface Message {
       heroPlus,
       heroAdjustmentsHorizontal,
       heroClock,
+      heroMicrophone,
       heroStopSolid,
       heroPaperAirplaneSolid
     })
@@ -47,6 +50,7 @@ export class ChatInputComponent {
   // Service injection
   private readonly fileUploadService = inject(FileUploadService);
   private readonly toastService = inject(ToastService);
+  private readonly voiceChatService = inject(VoiceChatService);
 
   // Input: session ID for file uploads
   readonly sessionId = input<string | null>(null);
@@ -94,6 +98,46 @@ export class ChatInputComponent {
   // Allowed file types for input accept attribute
   readonly acceptedFileTypes = ALLOWED_EXTENSIONS.join(',');
 
+  // Voice state (from VoiceChatService)
+  readonly voiceStatus = this.voiceChatService.status;
+  readonly isVoiceActive = this.voiceChatService.isVoiceActive;
+  readonly voiceTranscript = this.voiceChatService.agentTranscript;
+
+  readonly voiceButtonClass = computed(() => {
+    const status = this.voiceStatus();
+    const base = 'flex size-10 items-center justify-center rounded-lg transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--color-primary)]';
+    switch (status) {
+      case 'listening':
+        return `${base} bg-red-100 text-red-600 dark:bg-red-900/30 dark:text-red-400 animate-pulse`;
+      case 'speaking':
+        return `${base} bg-green-100 text-green-600 dark:bg-green-900/30 dark:text-green-400`;
+      case 'connecting':
+        return `${base} bg-yellow-100 text-yellow-600 dark:bg-yellow-900/30 dark:text-yellow-400`;
+      default:
+        return `${base} text-gray-500 dark:text-gray-400 hover:bg-gray-100 hover:text-gray-700 dark:hover:bg-white/5 dark:hover:text-gray-300`;
+    }
+  });
+
+  readonly voiceAriaLabel = computed(() => {
+    const status = this.voiceStatus();
+    switch (status) {
+      case 'listening': return 'Listening... Click to stop voice';
+      case 'speaking': return 'Agent is speaking... Click to stop voice';
+      case 'connecting': return 'Connecting voice...';
+      default: return 'Start voice conversation';
+    }
+  });
+
+  readonly voiceTooltip = computed(() => {
+    const status = this.voiceStatus();
+    switch (status) {
+      case 'listening': return 'Listening...';
+      case 'speaking': return 'Speaking...';
+      case 'connecting': return 'Connecting...';
+      default: return 'Voice mode';
+    }
+  });
+
   onSubmit() {
     if (this.isLoading()) {
       this.cancelChatRequest();
@@ -138,6 +182,19 @@ export class ChatInputComponent {
     this.settingsToggled.emit();
   }
 
+  async toggleVoice() {
+    if (this.isVoiceActive()) {
+      await this.voiceChatService.disconnect();
+    } else {
+      try {
+        await this.voiceChatService.connect(this.sessionId() || undefined);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : 'Failed to start voice';
+        this.toastService.error('Voice Error', msg);
+      }
+    }
+  }
+
   async onFileSelect(event: Event) {
     const input = event.target as HTMLInputElement;
     if (!input.files || input.files.length === 0) {
diff --git a/frontend/ai.client/src/app/session/components/message-list/components/message-metadata-badges.component.ts b/frontend/ai.client/src/app/session/components/message-list/components/message-metadata-badges.component.ts
index fccca3ed..07fcdf4f 100644
--- a/frontend/ai.client/src/app/session/components/message-list/components/message-metadata-badges.component.ts
+++ b/frontend/ai.client/src/app/session/components/message-list/components/message-metadata-badges.component.ts
@@ -7,6 +7,14 @@ import {
 } from '@angular/core';
 import { LocalSettingsService } from '../../../../services/local-settings.service';
 
+interface CostBreakdown {
+    total: number;
+    inputCost: number;
+    outputCost: number;
+    cacheReadCost?: number;
+    cacheWriteCost?: number;
+}
+
 interface MessageMetadata {
     latency?: {
         timeToFirstToken?: number;
@@ -24,7 +32,7 @@ interface MessageMetadata {
         sessionId?: string;
         timestamp?: string;
     };
-    cost?: number;
+    cost?: CostBreakdown | number;
 }
 
 @Component({
@@ -104,13 +112,33 @@ interface MessageMetadata {
                     </div>
                 }
 
-                <!-- Cost Badge -->
-                @if (cost() !== null) {
+                <!-- Input Cost Badge -->
+                @if (inputCost() !== null) {
+                    <div class="inline-flex items-center gap-1.5 rounded-full bg-amber-100 px-3 py-1 text-xs font-medium text-amber-700 dark:bg-amber-900/30 dark:text-amber-300">
+                        <svg class="size-3.5" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v12m-3-2.818.879.659c1.171.879 3.07.879 4.242 0 1.172-.879 1.172-2.303 0-3.182C13.536 12.219 12.768 12 12 12c-.725 0-1.45-.22-2.003-.659-1.106-.879-1.106-2.303 0-3.182s2.9-.879 4.006 0l.415.33M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+                        </svg>
+                        <span>In: {{ formatCost(inputCost()) }}</span>
+                    </div>
+                }
+
+                <!-- Output Cost Badge -->
+                @if (outputCost() !== null) {
+                    <div class="inline-flex items-center gap-1.5 rounded-full bg-orange-100 px-3 py-1 text-xs font-medium text-orange-700 dark:bg-orange-900/30 dark:text-orange-300">
+                        <svg class="size-3.5" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+                            <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v12m-3-2.818.879.659c1.171.879 3.07.879 4.242 0 1.172-.879 1.172-2.303 0-3.182C13.536 12.219 12.768 12 12 12c-.725 0-1.45-.22-2.003-.659-1.106-.879-1.106-2.303 0-3.182s2.9-.879 4.006 0l.415.33M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+                        </svg>
+                        <span>Out: {{ formatCost(outputCost()) }}</span>
+                    </div>
+                }
+
+                <!-- Total Cost Badge -->
+                @if (totalCost() !== null) {
                     <div class="inline-flex items-center gap-1.5 rounded-full bg-amber-100 px-3 py-1 text-xs font-medium text-amber-700 dark:bg-amber-900/30 dark:text-amber-300">
                         <svg class="size-3.5" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
                             <path stroke-linecap="round" stroke-linejoin="round" d="M12 6v12m-3-2.818.879.659c1.171.879 3.07.879 4.242 0 1.172-.879 1.172-2.303 0-3.182C13.536 12.219 12.768 12 12 12c-.725 0-1.45-.22-2.003-.659-1.106-.879-1.106-2.303 0-3.182s2.9-.879 4.006 0l.415.33M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
                         </svg>
-                        <span>Cost: {{ formatCost(cost()) }}</span>
+                        <span>Total: {{ formatCost(totalCost()) }}</span>
                     </div>
                 }
         }
@@ -141,7 +169,7 @@ export class MessageMetadataBadgesComponent {
             !!meta.latency?.timeToFirstToken ||
             !!meta.latency?.endToEndLatency ||
             !!meta.tokenUsage ||
-            meta.cost !== undefined
+            meta.cost !== undefined && meta.cost !== null
         );
     });
 
@@ -217,12 +245,34 @@ export class MessageMetadataBadgesComponent {
         return { hitRate, savings: Math.max(0, savings) };
     });
 
-    cost = computed(() => {
+    private costBreakdown = computed<CostBreakdown | null>(() => {
         const meta = this.typedMetadata();
         if (meta?.cost === undefined || meta.cost === null) return null;
+        // Handle backwards compatibility with scalar cost
+        if (typeof meta.cost === 'number') {
+            return { total: meta.cost, inputCost: 0, outputCost: 0 };
+        }
         return meta.cost;
     });
 
+    inputCost = computed(() => {
+        const breakdown = this.costBreakdown();
+        if (!breakdown || breakdown.inputCost === 0) return null;
+        return breakdown.inputCost;
+    });
+
+    outputCost = computed(() => {
+        const breakdown = this.costBreakdown();
+        if (!breakdown || breakdown.outputCost === 0) return null;
+        return breakdown.outputCost;
+    });
+
+    totalCost = computed(() => {
+        const breakdown = this.costBreakdown();
+        if (!breakdown) return null;
+        return breakdown.total;
+    });
+
     /**
      * Format large numbers with locale-aware thousands separators
      */
diff --git a/frontend/ai.client/src/app/session/components/voice-overlay/index.ts b/frontend/ai.client/src/app/session/components/voice-overlay/index.ts
new file mode 100644
index 00000000..8b5e98c2
--- /dev/null
+++ b/frontend/ai.client/src/app/session/components/voice-overlay/index.ts
@@ -0,0 +1 @@
+export { VoiceOverlayComponent } from './voice-overlay.component';
diff --git a/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.css b/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.css
new file mode 100644
index 00000000..49c0b2a1
--- /dev/null
+++ b/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.css
@@ -0,0 +1,202 @@
+@import "tailwindcss";
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* === Overlay entrance === */
+:host {
+  display: block;
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  animation: overlay-enter 400ms cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.voice-overlay-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  display: flex;
+  flex-direction: column;
+  background-color: rgba(249, 250, 251, 0.97);
+  backdrop-filter: blur(24px);
+  -webkit-backdrop-filter: blur(24px);
+  color: var(--color-gray-900);
+}
+
+:host-context(.dark) .voice-overlay-backdrop {
+  background-color: rgba(3, 7, 18, 0.97);
+  color: var(--color-gray-100);
+}
+
+@keyframes overlay-enter {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+/* === Visualizer Orb === */
+.voice-orb {
+  position: relative;
+  width: 10rem;
+  height: 10rem;
+  margin-bottom: 2.5rem;
+}
+
+.voice-orb-core {
+  position: absolute;
+  inset: 0;
+  border-radius: 9999px;
+  transition: background 600ms ease, box-shadow 600ms ease;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* -- Connecting state -- */
+.voice-orb-core.connecting {
+  background: radial-gradient(circle at 40% 40%, #fbbf24, #d97706);
+  box-shadow: 0 0 40px rgba(251, 191, 36, 0.3), 0 0 80px rgba(217, 119, 6, 0.15);
+  animation: orb-spin 2s linear infinite;
+}
+
+@keyframes orb-spin {
+  0% { transform: rotate(0deg) scale(0.92); }
+  50% { transform: rotate(180deg) scale(1.04); }
+  100% { transform: rotate(360deg) scale(0.92); }
+}
+
+/* -- Listening state -- */
+.voice-orb-core.listening {
+  background: radial-gradient(circle at 45% 40%, #f87171, #dc2626);
+  box-shadow: 0 0 40px rgba(248, 113, 113, 0.35), 0 0 80px rgba(220, 38, 38, 0.15);
+  animation: orb-breathe 2.5s ease-in-out infinite;
+}
+
+@keyframes orb-breathe {
+  0%, 100% { transform: scale(1); }
+  50% { transform: scale(1.06); }
+}
+
+.voice-ripple {
+  position: absolute;
+  inset: -0.5rem;
+  border-radius: 9999px;
+  border: 1.5px solid rgba(248, 113, 113, 0.4);
+  animation: ripple-expand 2.4s ease-out infinite;
+}
+
+.voice-ripple:nth-child(2) {
+  animation-delay: 0.8s;
+}
+
+.voice-ripple:nth-child(3) {
+  animation-delay: 1.6s;
+}
+
+@keyframes ripple-expand {
+  0% {
+    transform: scale(1);
+    opacity: 0.6;
+  }
+  100% {
+    transform: scale(2.2);
+    opacity: 0;
+  }
+}
+
+/* -- Speaking state -- */
+.voice-orb-core.speaking {
+  background: radial-gradient(circle at 45% 40%, #4ade80, #16a34a);
+  box-shadow: 0 0 40px rgba(74, 222, 128, 0.35), 0 0 80px rgba(22, 163, 74, 0.15);
+  animation: orb-pulse-speak 2.5s ease-in-out infinite;
+}
+
+@keyframes orb-pulse-speak {
+  0%, 100% { transform: scale(1); opacity: 1; }
+  50% { transform: scale(1.04); opacity: 0.9; }
+}
+
+/* Wave bars inside orb during speaking */
+.voice-wave-bar {
+  width: 3px;
+  border-radius: 9999px;
+  background: rgba(255, 255, 255, 0.85);
+  animation: wave-bar 0.8s ease-in-out infinite;
+}
+
+@keyframes wave-bar {
+  0%, 100% { transform: scaleY(0.3); }
+  50% { transform: scaleY(1); }
+}
+
+/*
+ * TODO: Transcript box styles (removed — revisit when transcript display is re-added).
+ *
+ * When re-implementing, the fixed-height box with gradient fade worked well visually:
+ *   .transcript-box        — position:relative; height:7rem; overflow:hidden
+ *   .transcript-box-inner  — overflow-y:auto; scrollbar-width:none
+ *   .transcript-box-gradient — absolute bottom gradient matching backdrop color
+ *
+ * The hard part is pacing text reveal to match audio. See the TODO comment in
+ * voice-overlay.component.html for approaches.
+ */
+
+/* === Status badge === */
+.status-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.25rem 0.75rem;
+  border-radius: 9999px;
+  font-size: 0.75rem;
+  font-weight: 500;
+  letter-spacing: 0.025em;
+  text-transform: uppercase;
+}
+
+.status-badge.connecting {
+  background: rgba(251, 191, 36, 0.15);
+  color: #b45309;
+}
+
+.status-badge.listening {
+  background: rgba(248, 113, 113, 0.15);
+  color: #dc2626;
+}
+
+.status-badge.speaking {
+  background: rgba(74, 222, 128, 0.15);
+  color: #16a34a;
+}
+
+:host-context(.dark) .status-badge.connecting {
+  color: #fbbf24;
+}
+
+:host-context(.dark) .status-badge.listening {
+  color: #f87171;
+}
+
+:host-context(.dark) .status-badge.speaking {
+  color: #4ade80;
+}
+
+.status-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 9999px;
+  background: currentColor;
+  animation: dot-pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes dot-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+/* === Reduced motion === */
+@media (prefers-reduced-motion: reduce) {
+  :host { animation: none; opacity: 1; }
+  .voice-orb-core { animation: none !important; }
+  .voice-ripple { animation: none !important; opacity: 0; }
+  .voice-wave-bar { animation: none !important; transform: scaleY(0.6); }
+  .status-dot { animation: none !important; }
+}
diff --git a/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.html b/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.html
new file mode 100644
index 00000000..61ff66e2
--- /dev/null
+++ b/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.html
@@ -0,0 +1,116 @@
+<!-- Fullscreen voice conversation overlay -->
+<div
+  class="voice-overlay-backdrop"
+  role="dialog"
+  aria-modal="true"
+  aria-label="Voice conversation"
+  cdkTrapFocus
+  [cdkTrapFocusAutoCapture]="true"
+>
+  <!-- Header -->
+  <header class="flex items-center justify-between px-6 py-4 shrink-0">
+    <div class="flex items-center gap-3">
+      <h2 class="text-gray-900 dark:text-white/90 text-base font-semibold tracking-wide">Voice Mode</h2>
+      @if (statusClass()) {
+        <span class="status-badge" [class]="statusClass()">
+          <span class="status-dot" aria-hidden="true"></span>
+          {{ statusLabel() }}
+        </span>
+      }
+    </div>
+    <button
+      type="button"
+      (click)="endSession()"
+      class="flex items-center justify-center size-10 rounded-full text-gray-400 dark:text-white/50 hover:text-gray-700 dark:hover:text-white hover:bg-gray-200 dark:hover:bg-white/10 transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-gray-500 dark:focus-visible:outline-white"
+      aria-label="End voice session"
+    >
+      <svg class="size-5" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" />
+      </svg>
+    </button>
+  </header>
+
+  <!-- Center: Visualizer + Live Transcript -->
+  <div class="flex-1 flex flex-col items-center justify-center px-6 min-h-0">
+    <!-- Animated Orb -->
+    <div class="voice-orb">
+      <!-- Ripple rings (listening only) -->
+      @if (voiceStatus() === 'listening') {
+        <div class="voice-ripple"></div>
+        <div class="voice-ripple"></div>
+        <div class="voice-ripple"></div>
+      }
+
+      <!-- Core orb -->
+      <div class="voice-orb-core" [class]="statusClass()">
+        <!-- Wave bars inside orb (speaking only) -->
+        @if (voiceStatus() === 'speaking') {
+          <div class="flex items-center justify-center gap-1">
+            <span class="voice-wave-bar h-8" style="animation-delay: 0ms;" aria-hidden="true"></span>
+            <span class="voice-wave-bar h-10" style="animation-delay: 100ms;" aria-hidden="true"></span>
+            <span class="voice-wave-bar h-12" style="animation-delay: 200ms;" aria-hidden="true"></span>
+            <span class="voice-wave-bar h-10" style="animation-delay: 300ms;" aria-hidden="true"></span>
+            <span class="voice-wave-bar h-8" style="animation-delay: 400ms;" aria-hidden="true"></span>
+          </div>
+        }
+
+        <!-- Connecting spinner -->
+        @if (voiceStatus() === 'connecting') {
+          <svg class="size-8 text-gray-600 dark:text-white/80 animate-spin" fill="none" viewBox="0 0 24 24">
+            <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="3"></circle>
+            <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"></path>
+          </svg>
+        }
+
+        <!-- Listening mic icon -->
+        @if (voiceStatus() === 'listening') {
+          <svg class="size-8 text-white" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+            <path stroke-linecap="round" stroke-linejoin="round" d="M12 18.75a6 6 0 0 0 6-6v-1.5m-6 7.5a6 6 0 0 1-6-6v-1.5m6 7.5v3.75m-3.75 0h7.5M12 15.75a3 3 0 0 1-3-3V4.5a3 3 0 1 1 6 0v8.25a3 3 0 0 1-3 3Z" />
+          </svg>
+        }
+      </div>
+    </div>
+
+    <!-- Status label below the orb -->
+    @if (voiceStatus() === 'connecting') {
+      <p class="text-gray-400 dark:text-white/30 text-sm">Establishing connection...</p>
+    } @else if (voiceStatus() === 'listening') {
+      <p class="text-gray-400 dark:text-white/30 text-sm">Listening...</p>
+    }
+
+    <!--
+      TODO: Revisit live transcript display.
+
+      The service already buffers agent transcript text via a reveal timer
+      (see VoiceChatService._bufferedTranscript / _revealedIndex / agentTranscript).
+      The challenge is syncing revealed text to audio playback — transcript deltas
+      arrive from the WebSocket independently of audio chunks, so a simple timer
+      can't match the cadence of speech.
+
+      Possible approaches to explore:
+      1. Server-side: include a timestamp or word-offset in each bidi_transcript_stream
+         delta so the client can align text reveal to audio position.
+      2. Client-side: track AudioPlayerService queue depth / playback position and
+         use it to pace the reveal timer dynamically instead of a fixed chars/tick.
+      3. Hybrid: reveal text in sentence-level chunks (split on punctuation) timed
+         to audio chunk boundaries rather than character-by-character.
+    -->
+  </div>
+
+  <!-- Bottom: End Button -->
+  <div class="shrink-0 px-6 pb-8 pt-4">
+    <!-- End session button -->
+    <div class="flex justify-center">
+      <button
+        type="button"
+        (click)="endSession()"
+        class="inline-flex items-center gap-2 rounded-full bg-red-600/90 px-8 py-3 text-sm font-semibold text-white shadow-lg shadow-red-900/30 transition-all hover:bg-red-500 hover:shadow-red-900/40 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-red-400 active:scale-95"
+      >
+        <svg class="size-4" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+          <path stroke-linecap="round" stroke-linejoin="round" d="M5.636 5.636a9 9 0 1 0 12.728 0M12 3v9" />
+        </svg>
+        End Voice Session
+      </button>
+    </div>
+  </div>
+</div>
diff --git a/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.ts b/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.ts
new file mode 100644
index 00000000..31743a56
--- /dev/null
+++ b/frontend/ai.client/src/app/session/components/voice-overlay/voice-overlay.component.ts
@@ -0,0 +1,48 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  inject,
+  output,
+  computed,
+} from '@angular/core';
+import { A11yModule } from '@angular/cdk/a11y';
+import { VoiceChatService } from '../../services/voice';
+
+@Component({
+  selector: 'app-voice-overlay',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [A11yModule],
+  templateUrl: './voice-overlay.component.html',
+  styleUrl: './voice-overlay.component.css',
+  host: {
+    '(keydown.escape)': 'endSession()',
+  },
+})
+export class VoiceOverlayComponent {
+  private readonly voiceChatService = inject(VoiceChatService);
+
+  /** Emitted when voice session ends (overlay should be removed by parent) */
+  closed = output<void>();
+
+  // Expose service signals to template
+  readonly voiceStatus = this.voiceChatService.status;
+
+  readonly statusLabel = computed(() => {
+    switch (this.voiceStatus()) {
+      case 'connecting': return 'Connecting';
+      case 'listening': return 'Listening';
+      case 'speaking': return 'Speaking';
+      default: return '';
+    }
+  });
+
+  readonly statusClass = computed(() => {
+    const status = this.voiceStatus();
+    return status === 'idle' ? '' : status;
+  });
+
+  endSession(): void {
+    this.voiceChatService.disconnect();
+    this.closed.emit();
+  }
+}
diff --git a/frontend/ai.client/src/app/session/services/models/content-types.ts b/frontend/ai.client/src/app/session/services/models/content-types.ts
index b1180cb7..4340fabb 100644
--- a/frontend/ai.client/src/app/session/services/models/content-types.ts
+++ b/frontend/ai.client/src/app/session/services/models/content-types.ts
@@ -236,12 +236,20 @@ export interface Metrics {
   timeToFirstByteMs?: number;
 }
 
+export interface CostBreakdown {
+  total: number;
+  inputCost: number;
+  outputCost: number;
+  cacheReadCost?: number;
+  cacheWriteCost?: number;
+}
+
 export interface MetadataEvent {
   metrics?: Metrics;
   trace?: any;
   usage?: Usage;
-  /** Total cost in USD for this message (calculated from token usage and model pricing) */
-  cost?: number;
+  /** Cost for this message — either a total number (legacy) or a breakdown object */
+  cost?: number | CostBreakdown;
 }
 
 export interface ExceptionEvent {
diff --git a/frontend/ai.client/src/app/session/services/session/message-map.service.ts b/frontend/ai.client/src/app/session/services/session/message-map.service.ts
index c4b972cb..f4d7197d 100644
--- a/frontend/ai.client/src/app/session/services/session/message-map.service.ts
+++ b/frontend/ai.client/src/app/session/services/session/message-map.service.ts
@@ -166,6 +166,40 @@ export class MessageMapService {
     return message;
   }
 
+  /**
+   * Add a voice transcript message (from VoiceChatService) to the session.
+   * Used when the voice agent completes a response and the transcript is finalized.
+   *
+   * @param sessionId - The session ID to add the message to
+   * @param role - Message role (user or assistant)
+   * @param text - Message text content
+   * @param metadata - Optional metadata (token usage, cost) for badge display
+   */
+  addVoiceMessage(sessionId: string, role: 'user' | 'assistant', text: string, metadata?: Record<string, unknown>): Message {
+    const currentMessages = this.messageMap()[sessionId]?.() ?? [];
+    const messageIndex = currentMessages.length;
+    const messageId = `msg-${sessionId}-${messageIndex}`;
+
+    const message: Message = {
+      id: messageId,
+      role,
+      content: [{ type: 'text', text }],
+      ...(metadata ? { metadata } : {}),
+    };
+
+    this.messageMap.update(map => {
+      const updated = { ...map };
+      if (!updated[sessionId]) {
+        updated[sessionId] = signal([message]);
+      } else {
+        updated[sessionId].update(msgs => [...msgs, message]);
+      }
+      return updated;
+    });
+
+    return message;
+  }
+
   /**
    * Sync streaming messages to the message map.
    * Handles the case where we're appending to existing messages.
diff --git a/frontend/ai.client/src/app/session/services/voice/audio-player.service.ts b/frontend/ai.client/src/app/session/services/voice/audio-player.service.ts
new file mode 100644
index 00000000..0be4c107
--- /dev/null
+++ b/frontend/ai.client/src/app/session/services/voice/audio-player.service.ts
@@ -0,0 +1,99 @@
+import { Injectable, signal } from '@angular/core';
+import { base64ToSamples } from './pcm-utils';
+
+/**
+ * Audio playback service for Nova Sonic voice responses.
+ *
+ * Plays base64-encoded PCM audio chunks in sequence with gapless
+ * scheduling. Supports interruption (clear all scheduled audio)
+ * and volume control.
+ */
+@Injectable({ providedIn: 'root' })
+export class AudioPlayerService {
+  private readonly _isPlaying = signal(false);
+  readonly isPlaying = this._isPlaying.asReadonly();
+
+  private audioContext: AudioContext | null = null;
+  private gainNode: GainNode | null = null;
+  private scheduledTime = 0;
+  private activeSources: AudioBufferSourceNode[] = [];
+
+  /**
+   * Play a base64-encoded PCM audio chunk.
+   * Chunks are scheduled sequentially for gapless playback.
+   */
+  play(base64Pcm: string, sampleRate: number = 16000): void {
+    if (!base64Pcm) return;
+
+    this.ensureContext(sampleRate);
+    if (!this.audioContext || !this.gainNode) return;
+
+    const samples = base64ToSamples(base64Pcm);
+    const buffer = this.audioContext.createBuffer(1, samples.length, sampleRate);
+    buffer.getChannelData(0).set(samples);
+
+    const source = this.audioContext.createBufferSource();
+    source.buffer = buffer;
+    source.connect(this.gainNode);
+
+    // Schedule at the end of the current queue (gapless)
+    const now = this.audioContext.currentTime;
+    const startTime = Math.max(now, this.scheduledTime);
+    source.start(startTime);
+    this.scheduledTime = startTime + buffer.duration;
+
+    // Track for interruption
+    this.activeSources.push(source);
+    source.onended = () => {
+      const idx = this.activeSources.indexOf(source);
+      if (idx >= 0) this.activeSources.splice(idx, 1);
+      this._isPlaying.set(this.activeSources.length > 0);
+    };
+
+    this._isPlaying.set(true);
+  }
+
+  /**
+   * Stop all scheduled and playing audio immediately.
+   * Used when the user interrupts the agent.
+   */
+  clear(): void {
+    for (const source of this.activeSources) {
+      try {
+        source.stop();
+      } catch {
+        // Already stopped
+      }
+    }
+    this.activeSources = [];
+    this.scheduledTime = 0;
+    this._isPlaying.set(false);
+  }
+
+  /** Set playback volume (0.0 to 1.0). */
+  setVolume(volume: number): void {
+    if (this.gainNode) {
+      this.gainNode.gain.value = Math.max(0, Math.min(1, volume));
+    }
+  }
+
+  /** Release audio resources. */
+  dispose(): void {
+    this.clear();
+    if (this.audioContext?.state !== 'closed') {
+      this.audioContext?.close().catch(() => {});
+    }
+    this.audioContext = null;
+    this.gainNode = null;
+  }
+
+  private ensureContext(sampleRate: number): void {
+    if (this.audioContext) return;
+
+    const AudioContextClass = window.AudioContext || (window as any).webkitAudioContext;
+    this.audioContext = new AudioContextClass({ sampleRate });
+    this.gainNode = this.audioContext.createGain();
+    this.gainNode.connect(this.audioContext.destination);
+    this.scheduledTime = 0;
+  }
+}
diff --git a/frontend/ai.client/src/app/session/services/voice/audio-recorder.service.ts b/frontend/ai.client/src/app/session/services/voice/audio-recorder.service.ts
new file mode 100644
index 00000000..9a726550
--- /dev/null
+++ b/frontend/ai.client/src/app/session/services/voice/audio-recorder.service.ts
@@ -0,0 +1,142 @@
+import { Injectable, signal } from '@angular/core';
+import { float32ToPcm16, pcm16ToBase64, resampleLinear } from './pcm-utils';
+import { VOICE_SAMPLE_RATE, SAMPLES_PER_CHUNK } from './voice.config';
+
+/**
+ * Audio capture service using Web Audio API.
+ *
+ * Captures microphone input, resamples to 16kHz mono PCM, and emits
+ * base64-encoded chunks at ~100ms intervals for Nova Sonic streaming.
+ *
+ * Uses AudioWorkletNode for off-main-thread audio processing.
+ * The worklet processor is served from /audio/pcm-capture.worklet.js.
+ */
+@Injectable({ providedIn: 'root' })
+export class AudioRecorderService {
+  private readonly _isRecording = signal(false);
+  private readonly _isSupported = signal(false);
+
+  readonly isRecording = this._isRecording.asReadonly();
+  readonly isSupported = this._isSupported.asReadonly();
+
+  private audioContext: AudioContext | null = null;
+  private mediaStream: MediaStream | null = null;
+  private sourceNode: MediaStreamAudioSourceNode | null = null;
+  private workletNode: AudioWorkletNode | null = null;
+  private sampleBuffer: Float32Array = new Float32Array(0);
+
+  /** Callback invoked with each base64 PCM chunk */
+  onAudioChunk: ((base64Pcm: string, sampleRate: number) => void) | null = null;
+
+  constructor() {
+    this._isSupported.set(this.checkSupport());
+  }
+
+  private checkSupport(): boolean {
+    if (typeof window === 'undefined') return false;
+    const hasGetUserMedia = typeof navigator.mediaDevices?.getUserMedia === 'function';
+    const hasAudioContext = !!(window.AudioContext || (window as any).webkitAudioContext);
+    return hasGetUserMedia && hasAudioContext;
+  }
+
+  /**
+   * Start capturing audio from the microphone.
+   * Requests microphone permission if not already granted.
+   */
+  async start(): Promise<void> {
+    if (this._isRecording()) return;
+    if (!this._isSupported()) {
+      throw new Error('Audio recording not supported in this browser');
+    }
+
+    try {
+      this.mediaStream = await navigator.mediaDevices.getUserMedia({
+        audio: {
+          sampleRate: { ideal: VOICE_SAMPLE_RATE },
+          channelCount: { exact: 1 },
+          echoCancellation: true,
+          noiseSuppression: true,
+          autoGainControl: true,
+        },
+      });
+
+      const AudioContextClass = window.AudioContext || (window as any).webkitAudioContext;
+      this.audioContext = new AudioContextClass({ sampleRate: VOICE_SAMPLE_RATE });
+
+      await this.audioContext.audioWorklet.addModule('/audio/pcm-capture.worklet.js');
+
+      this.sourceNode = this.audioContext.createMediaStreamSource(this.mediaStream);
+
+      this.workletNode = new AudioWorkletNode(this.audioContext, 'pcm-capture');
+      this.sampleBuffer = new Float32Array(0);
+
+      this.workletNode.port.onmessage = (event: MessageEvent<Float32Array>) => {
+        this.processAudioChunk(event.data);
+      };
+
+      this.sourceNode.connect(this.workletNode);
+      this.workletNode.connect(this.audioContext.destination);
+
+      this._isRecording.set(true);
+    } catch (err) {
+      this.cleanup();
+      throw err;
+    }
+  }
+
+  /** Stop capturing and release resources. */
+  async stop(): Promise<void> {
+    if (!this._isRecording()) return;
+    this.flushBuffer();
+    this.cleanup();
+    this._isRecording.set(false);
+  }
+
+  private processAudioChunk(inputSamples: Float32Array): void {
+    // Resample if browser's actual rate differs from target
+    let samples = inputSamples;
+    if (this.audioContext && this.audioContext.sampleRate !== VOICE_SAMPLE_RATE) {
+      samples = resampleLinear(inputSamples, this.audioContext.sampleRate, VOICE_SAMPLE_RATE);
+    }
+
+    // Append to buffer
+    const newBuffer = new Float32Array(this.sampleBuffer.length + samples.length);
+    newBuffer.set(this.sampleBuffer);
+    newBuffer.set(samples, this.sampleBuffer.length);
+    this.sampleBuffer = newBuffer;
+
+    // Emit complete chunks
+    while (this.sampleBuffer.length >= SAMPLES_PER_CHUNK) {
+      const chunk = this.sampleBuffer.slice(0, SAMPLES_PER_CHUNK);
+      this.sampleBuffer = this.sampleBuffer.slice(SAMPLES_PER_CHUNK);
+
+      const pcm = float32ToPcm16(chunk);
+      const base64 = pcm16ToBase64(pcm);
+      this.onAudioChunk?.(base64, VOICE_SAMPLE_RATE);
+    }
+  }
+
+  /** Flush any remaining samples in the buffer as a final chunk. */
+  private flushBuffer(): void {
+    if (this.sampleBuffer.length > 0) {
+      const pcm = float32ToPcm16(this.sampleBuffer);
+      const base64 = pcm16ToBase64(pcm);
+      this.onAudioChunk?.(base64, VOICE_SAMPLE_RATE);
+      this.sampleBuffer = new Float32Array(0);
+    }
+  }
+
+  private cleanup(): void {
+    this.workletNode?.disconnect();
+    this.sourceNode?.disconnect();
+    this.mediaStream?.getTracks().forEach(t => t.stop());
+    if (this.audioContext?.state !== 'closed') {
+      this.audioContext?.close().catch(() => {});
+    }
+    this.workletNode = null;
+    this.sourceNode = null;
+    this.mediaStream = null;
+    this.audioContext = null;
+    this.sampleBuffer = new Float32Array(0);
+  }
+}
diff --git a/frontend/ai.client/src/app/session/services/voice/index.ts b/frontend/ai.client/src/app/session/services/voice/index.ts
new file mode 100644
index 00000000..7b63c005
--- /dev/null
+++ b/frontend/ai.client/src/app/session/services/voice/index.ts
@@ -0,0 +1,5 @@
+export { AudioRecorderService } from './audio-recorder.service';
+export { AudioPlayerService } from './audio-player.service';
+export { VoiceChatService, type VoiceStatus, type VoiceTranscriptEntry, type VoiceTokenUsage } from './voice-chat.service';
+export * from './pcm-utils';
+export * from './voice.config';
diff --git a/frontend/ai.client/src/app/session/services/voice/pcm-utils.ts b/frontend/ai.client/src/app/session/services/voice/pcm-utils.ts
new file mode 100644
index 00000000..d796f2e4
--- /dev/null
+++ b/frontend/ai.client/src/app/session/services/voice/pcm-utils.ts
@@ -0,0 +1,96 @@
+/**
+ * PCM audio encoding/decoding utilities for Nova Sonic voice streaming.
+ *
+ * All functions are pure — no state, no services, no side effects.
+ * Transport format: 16-bit PCM encoded as base64 over JSON WebSocket.
+ */
+
+export { SAMPLES_PER_CHUNK, VOICE_SAMPLE_RATE } from './voice.config';
+
+/**
+ * Convert Float32 audio samples (-1.0 to 1.0) to 16-bit PCM Int16Array.
+ * Clamps values to prevent distortion.
+ */
+export function float32ToPcm16(samples: Float32Array): Int16Array {
+  const pcm = new Int16Array(samples.length);
+  for (let i = 0; i < samples.length; i++) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]));
+    pcm[i] = clamped < 0 ? clamped * 0x8000 : clamped * 0x7FFF;
+  }
+  return pcm;
+}
+
+/**
+ * Convert 16-bit PCM Int16Array to Float32 audio samples (-1.0 to 1.0).
+ */
+export function pcm16ToFloat32(pcm: Int16Array): Float32Array {
+  const float = new Float32Array(pcm.length);
+  for (let i = 0; i < pcm.length; i++) {
+    float[i] = pcm[i] / (pcm[i] < 0 ? 0x8000 : 0x7FFF);
+  }
+  return float;
+}
+
+/**
+ * Encode 16-bit PCM as base64 string for WebSocket transmission.
+ */
+export function pcm16ToBase64(pcm: Int16Array): string {
+  const bytes = new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Decode base64 string to 16-bit PCM Int16Array.
+ */
+export function base64ToPcm16(b64: string): Int16Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new Int16Array(bytes.buffer);
+}
+
+/**
+ * Linear interpolation resampling.
+ * Used when browser's native sample rate differs from target (16kHz).
+ */
+export function resampleLinear(
+  samples: Float32Array,
+  fromRate: number,
+  toRate: number
+): Float32Array {
+  if (fromRate === toRate) return samples;
+
+  const ratio = fromRate / toRate;
+  const outputLength = Math.round(samples.length / ratio);
+  const output = new Float32Array(outputLength);
+
+  for (let i = 0; i < outputLength; i++) {
+    const srcIndex = i * ratio;
+    const srcFloor = Math.floor(srcIndex);
+    const srcCeil = Math.min(srcFloor + 1, samples.length - 1);
+    const frac = srcIndex - srcFloor;
+    output[i] = samples[srcFloor] * (1 - frac) + samples[srcCeil] * frac;
+  }
+
+  return output;
+}
+
+/**
+ * Convenience: Float32 samples → base64 PCM string (for sending to server).
+ */
+export function samplesToBase64(samples: Float32Array): string {
+  return pcm16ToBase64(float32ToPcm16(samples));
+}
+
+/**
+ * Convenience: base64 PCM string → Float32 samples (for playback).
+ */
+export function base64ToSamples(b64: string): Float32Array {
+  return pcm16ToFloat32(base64ToPcm16(b64));
+}
diff --git a/frontend/ai.client/src/app/session/services/voice/voice-chat.service.ts b/frontend/ai.client/src/app/session/services/voice/voice-chat.service.ts
new file mode 100644
index 00000000..50a2817f
--- /dev/null
+++ b/frontend/ai.client/src/app/session/services/voice/voice-chat.service.ts
@@ -0,0 +1,649 @@
+import { Injectable, signal, computed, inject, OnDestroy } from '@angular/core';
+import { v4 as uuidv4 } from 'uuid';
+import { AuthService } from '../../../auth/auth.service';
+import { ConfigService } from '../../../services/config.service';
+import { AudioRecorderService } from './audio-recorder.service';
+import { AudioPlayerService } from './audio-player.service';
+import { Message } from '../models/message.model';
+import {
+  IDLE_TIMEOUT_MS,
+  WS_CONNECT_TIMEOUT_MS,
+  MAX_TRANSCRIPT_ENTRIES,
+  WS_CLOSE_REASONS,
+  REVEAL_CHARS_PER_TICK,
+  REVEAL_TICK_MS,
+  REVEAL_FLUSH_CHARS_PER_TICK,
+} from './voice.config';
+
+export type VoiceStatus = 'idle' | 'connecting' | 'listening' | 'speaking';
+
+export interface VoiceTokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+}
+
+export interface VoiceTranscriptEntry {
+  role: 'user' | 'assistant';
+  text: string;
+  timestamp: number;
+  /** Per-turn token usage (assistant messages only, computed from cumulative bidi_usage deltas) */
+  metadata?: {
+    tokenUsage?: VoiceTokenUsage;
+  };
+}
+
+/**
+ * Voice chat orchestration service.
+ *
+ * Coordinates WebSocket connection to /voice/stream, audio recording,
+ * audio playback, and state management for the voice UI.
+ *
+ * Lifecycle:
+ *   1. connect(sessionId) → opens WebSocket, sends config, starts mic
+ *   2. Audio chunks sent as bidi_audio_input
+ *   3. Server events received: bidi_audio_stream → playback,
+ *      bidi_transcript_stream → transcript signal
+ *   4. disconnect() → stops mic, closes WebSocket, clears audio
+ */
+@Injectable({ providedIn: 'root' })
+export class VoiceChatService implements OnDestroy {
+  private readonly authService = inject(AuthService);
+  private readonly configService = inject(ConfigService);
+  private readonly recorder = inject(AudioRecorderService);
+  private readonly player = inject(AudioPlayerService);
+
+  // --- State signals ---
+  private readonly _status = signal<VoiceStatus>('idle');
+  private readonly _isConnected = signal(false);
+  private readonly _transcriptEntries = signal<VoiceTranscriptEntry[]>([]);
+
+  /**
+   * Buffered reveal transcript system.
+   *
+   * _bufferedTranscript: raw text from WebSocket — grows instantly as deltas arrive.
+   * _revealedIndex: how many characters the UI is allowed to see.
+   * agentTranscript: computed slice — what the template actually renders.
+   *
+   * A reveal timer advances _revealedIndex at speaking pace, creating a
+   * typewriter effect that stays roughly in sync with the audio.
+   */
+  private readonly _bufferedTranscript = signal('');
+  private readonly _revealedIndex = signal(0);
+  private _revealCharsPerTick = REVEAL_CHARS_PER_TICK;
+  private _revealTimer: ReturnType<typeof setInterval> | null = null;
+
+  /**
+   * Per-turn tracking for transcript entries.
+   *
+   * _currentTurnStart: index into _bufferedTranscript where the current
+   *   assistant turn began, so we can extract just this turn's text.
+   * _userTranscript: accumulates user speech text between assistant turns,
+   *   saved to transcriptEntries when the assistant starts responding.
+   */
+  private _currentTurnStart = 0;
+  private _userTranscript = '';
+  /** Whether the current turn's final assistant Message has been created in voiceMessages. */
+  private _assistantFinalStarted = false;
+
+  readonly status = this._status.asReadonly();
+  readonly agentTranscript = computed(() =>
+    this._bufferedTranscript().slice(0, this._revealedIndex())
+  );
+  readonly isConnected = this._isConnected.asReadonly();
+  readonly isVoiceActive = computed(() => this._status() !== 'idle');
+  readonly transcriptEntries = this._transcriptEntries.asReadonly();
+
+  /**
+   * Real-time voice conversation messages.
+   *
+   * Maintained as Message[] objects that the session page can read directly.
+   * Updated as WebSocket events stream in:
+   *   - bidi_response_start → user Message pushed
+   *   - bidi_transcript_stream (assistant) → last Message text updated
+   *   - bidi_response_complete → metadata attached to last Message
+   */
+  private readonly _voiceMessages = signal<Message[]>([]);
+  readonly voiceMessages = this._voiceMessages.asReadonly();
+  private _voiceMessageIndex = 0;
+
+  /** Clear voice messages after they've been persisted to the message map. */
+  clearVoiceMessages(): void {
+    this._voiceMessages.set([]);
+  }
+
+  // --- Token usage & cost tracking ---
+  /**
+   * Nova Sonic reports CUMULATIVE token counts in bidi_usage events.
+   * To compute per-turn deltas, we snapshot the cumulative total at each
+   * turn boundary and subtract the previous snapshot.
+   */
+  private _cumulativeUsage: VoiceTokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+  private _prevTurnCumulativeUsage: VoiceTokenUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+  /** Latest cumulative cost breakdown from the backend (sent with bidi_usage events). */
+  private _cumulativeCost: Record<string, number> | null = null;
+  private _prevTurnCumulativeCost: Record<string, number> | null = null;
+
+  // --- Internals ---
+  private ws: WebSocket | null = null;
+  private sessionId: string | null = null;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * Connect to the voice endpoint and start recording.
+   * If no sessionId is provided, one is auto-generated.
+   */
+  async connect(sessionId?: string): Promise<void> {
+    if (this._isConnected()) return;
+
+    this.sessionId = sessionId || uuidv4();
+    this._status.set('connecting');
+    this._bufferedTranscript.set('');
+    this._revealedIndex.set(0);
+    this._currentTurnStart = 0;
+    this._userTranscript = '';
+    this.stopRevealTimer();
+    this._transcriptEntries.set([]);
+    this._voiceMessages.set([]);
+    this._voiceMessageIndex = 0;
+    this._assistantFinalStarted = false;
+    this._cumulativeUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    this._prevTurnCumulativeUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+    this._cumulativeCost = null;
+    this._prevTurnCumulativeCost = null;
+
+    try {
+      const token = this.authService.getAccessToken();
+      if (!token) {
+        throw new Error('No authentication token available');
+      }
+
+      // Build WebSocket URL from inference API URL
+      const httpUrl = this.configService.inferenceApiUrl();
+      const wsUrl = httpUrl.replace(/^http/, 'ws');
+      const isAgentCore = httpUrl.includes('/runtimes/');
+
+      let url: string;
+      let protocols: string[] | undefined;
+
+      if (isAgentCore) {
+        // AgentCore: /ws path, auth via Sec-WebSocket-Protocol
+        url = `${wsUrl}/ws`;
+
+        const base64url = btoa(token)
+          .replace(/\+/g, '-')
+          .replace(/\//g, '_')
+          .replace(/=/g, '');
+        protocols = [`base64UrlBearerAuthorization.${base64url}`, 'base64UrlBearerAuthorization'];
+      } else {
+        // Local dev: /voice/stream path with query params
+        url = `${wsUrl}/voice/stream?session_id=${encodeURIComponent(this.sessionId!)}&token=${encodeURIComponent(token)}`;
+      }
+
+      await this.openWebSocket(url, token, protocols);
+      await this.recorder.start();
+
+      // Wire audio chunks to WebSocket
+      this.recorder.onAudioChunk = (base64, sampleRate) => {
+        this.sendMessage({
+          type: 'bidi_audio_input',
+          audio: base64,
+          sample_rate: sampleRate,
+        });
+      };
+
+      this._status.set('listening');
+      this._isConnected.set(true);
+      this.resetIdleTimer();
+    } catch (err) {
+      this.cleanupAll();
+      this._status.set('idle');
+      throw err;
+    }
+  }
+
+  /** Disconnect from voice session and release all resources. */
+  async disconnect(): Promise<void> {
+    if (!this._isConnected()) return;
+
+    // Flush any assistant text that hasn't been committed to voiceMessages
+    // yet (bidi_response_complete may not arrive before WebSocket closes).
+    this.flushPendingAssistantMessage();
+
+    // Attach token usage to any assistant messages missing metadata
+    // (bidi_response_complete / bidi_usage may not arrive before close).
+    this.attachPendingUsage();
+
+    this.sendMessage({ type: 'stop' });
+    this.cleanupAll();
+    this._status.set('idle');
+    this._isConnected.set(false);
+  }
+
+  /**
+   * Attach cumulative token usage to the LAST assistant message if it
+   * doesn't already have metadata. Called on disconnect since
+   * bidi_response_complete (which normally attaches per-turn metadata)
+   * may not arrive before close.
+   *
+   * Only the last assistant message gets the badge — matches the backend
+   * pattern in _finalize_voice_session() which stores cumulative usage
+   * on the last assistant message only.
+   *
+   * Note: cost data requires server-side pricing config and will appear
+   * after page refresh once _finalize_voice_session() has run.
+   */
+  private attachPendingUsage(): void {
+    const total = this._cumulativeUsage;
+    if (total.totalTokens === 0 && !this._cumulativeCost) return;
+
+    this._voiceMessages.update(msgs => {
+      // Find the last assistant message without metadata
+      for (let i = msgs.length - 1; i >= 0; i--) {
+        if (msgs[i].role === 'assistant' && !msgs[i].metadata) {
+          const metadata: Record<string, unknown> = {};
+          if (total.totalTokens > 0) {
+            metadata['tokenUsage'] = { ...total };
+          }
+          if (this._cumulativeCost) {
+            metadata['cost'] = { ...this._cumulativeCost };
+          }
+          const updated = [...msgs];
+          updated[i] = { ...msgs[i], metadata };
+          return updated;
+        }
+      }
+      return msgs;
+    });
+  }
+
+  /**
+   * If there's buffered assistant text that hasn't been committed to
+   * voiceMessages (no is_final events arrived), flush it from the buffer
+   * so it isn't lost when the WebSocket closes.
+   */
+  private flushPendingAssistantMessage(): void {
+    // If is_final events already created an assistant message, nothing to flush.
+    const msgs = this._voiceMessages();
+    const last = msgs[msgs.length - 1];
+    if (last?.role === 'assistant') return;
+
+    // Fall back to the buffered transcript (may be speculative text, but
+    // better than losing the response entirely).
+    const turnText = this._bufferedTranscript().slice(this._currentTurnStart).trim();
+    if (!turnText) return;
+
+    this._voiceMessages.update(m => [...m, {
+      id: `msg-${this.sessionId}-${this._voiceMessageIndex++}`,
+      role: 'assistant' as const,
+      content: [{ type: 'text', text: turnText }],
+    }]);
+  }
+
+  /** Get the current voice session ID (auto-generated or passed to connect). */
+  getSessionId(): string | null {
+    return this.sessionId;
+  }
+
+  /** Send a text message (fallback when mic not available). */
+  sendText(text: string): void {
+    if (!this._isConnected()) return;
+    this.sendMessage({ type: 'bidi_text_input', text });
+    this.resetIdleTimer();
+  }
+
+  ngOnDestroy(): void {
+    this.cleanupAll();
+  }
+
+  // --- WebSocket ---
+
+  private openWebSocket(url: string, token: string, protocols?: string[]): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws = protocols ? new WebSocket(url, protocols) : new WebSocket(url);
+
+      const timeout = setTimeout(() => {
+        reject(new Error('WebSocket connection timeout'));
+        this.ws?.close();
+      }, WS_CONNECT_TIMEOUT_MS);
+
+      this.ws.onopen = () => {
+        clearTimeout(timeout);
+        // Send config message as first frame
+        this.sendMessage({
+          type: 'config',
+          session_id: this.sessionId,
+          auth_token: token,
+        });
+        resolve();
+      };
+
+      this.ws.onmessage = (event: MessageEvent) => {
+        this.handleServerMessage(event);
+      };
+
+      this.ws.onerror = () => {
+        clearTimeout(timeout);
+        reject(new Error('WebSocket connection failed'));
+      };
+
+      this.ws.onclose = (event: CloseEvent) => {
+        if (this._isConnected()) {
+          // Unexpected close — log reason and clean up
+          const reason = WS_CLOSE_REASONS[event.code] || `Disconnected (code ${event.code})`;
+          console.warn(`Voice WebSocket closed: ${reason}`);
+          this.cleanupAll();
+          this._status.set('idle');
+          this._isConnected.set(false);
+        }
+      };
+    });
+  }
+
+  private sendMessage(msg: Record<string, unknown>): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  private handleServerMessage(event: MessageEvent): void {
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(event.data as string);
+    } catch {
+      return;
+    }
+
+    const type = data['type'] as string;
+
+    switch (type) {
+      case 'bidi_connection_start':
+        // Connection confirmed
+        break;
+
+      case 'bidi_audio_stream':
+        // Play audio from agent
+        this._status.set('speaking');
+        if (data['audio']) {
+          this.player.play(
+            data['audio'] as string,
+            (data['sample_rate'] as number) || 16000
+          );
+        }
+        this.resetIdleTimer();
+        break;
+
+      case 'bidi_transcript_stream': {
+        const role = data['role'] as string | undefined;
+        const isFinal = !!(data['is_final']);
+
+        let deltaText = '';
+        if (data['delta']) {
+          const delta = data['delta'];
+          deltaText = typeof delta === 'object' && delta !== null
+            ? (delta as Record<string, unknown>)['text'] as string
+            : delta as string;
+        } else if (data['current_transcript']) {
+          deltaText = data['current_transcript'] as string;
+        }
+
+        if (deltaText) {
+          if (role === 'assistant') {
+            // Buffer for reveal-based display (voice overlay)
+            this._bufferedTranscript.update(t => t + deltaText);
+
+            // Only commit to voiceMessages from FINAL pass (is_final=true),
+            // skipping speculative text to avoid duplication.
+            if (isFinal) {
+              if (!this._assistantFinalStarted) {
+                this._assistantFinalStarted = true;
+                this._voiceMessages.update(msgs => [...msgs, {
+                  id: `msg-${this.sessionId}-${this._voiceMessageIndex++}`,
+                  role: 'assistant' as const,
+                  content: [{ type: 'text', text: deltaText }],
+                }]);
+              } else {
+                this._voiceMessages.update(msgs => {
+                  const last = msgs[msgs.length - 1];
+                  if (!last || last.role !== 'assistant') return msgs;
+                  const updated = [...msgs];
+                  updated[updated.length - 1] = {
+                    ...last,
+                    content: [{ type: 'text', text: (last.content[0]?.text || '') + deltaText }],
+                  };
+                  return updated;
+                });
+              }
+            }
+          } else {
+            // Accumulate user speech for transcript entries
+            this._userTranscript += deltaText;
+          }
+        }
+
+        this.resetIdleTimer();
+        break;
+      }
+
+      case 'bidi_response_start':
+        // Flush accumulated user speech as a user Message.
+        // _userTranscript is cleared after push, so the second
+        // bidi_response_start (FINAL pass) is a no-op here.
+        if (this._userTranscript.trim()) {
+          const userText = this._userTranscript.trim();
+          this.appendTranscriptEntry({
+            role: 'user',
+            text: userText,
+            timestamp: Date.now(),
+          });
+          this._voiceMessages.update(msgs => [...msgs, {
+            id: `msg-${this.sessionId}-${this._voiceMessageIndex++}`,
+            role: 'user' as const,
+            content: [{ type: 'text', text: userText }],
+          }]);
+          this._userTranscript = '';
+        }
+
+        // Reset for this turn's final assistant text
+        this._assistantFinalStarted = false;
+
+        // New assistant turn — add separator if there's prior text, start reveal
+        if (this._bufferedTranscript()) {
+          this._bufferedTranscript.update(t => t + '\n\n');
+          this._revealedIndex.set(this._bufferedTranscript().length);
+        }
+        this._currentTurnStart = this._bufferedTranscript().length;
+        this._revealCharsPerTick = REVEAL_CHARS_PER_TICK;
+        this.startRevealTimer();
+        this._status.set('speaking');
+        break;
+
+      case 'bidi_response_complete': {
+        // Extract only this turn's assistant text for the transcript entry (overlay)
+        const turnText = this._bufferedTranscript().slice(this._currentTurnStart).trim();
+
+        // Compute per-turn token delta from cumulative snapshots
+        const turnUsage: VoiceTokenUsage = {
+          inputTokens: this._cumulativeUsage.inputTokens - this._prevTurnCumulativeUsage.inputTokens,
+          outputTokens: this._cumulativeUsage.outputTokens - this._prevTurnCumulativeUsage.outputTokens,
+          totalTokens: this._cumulativeUsage.totalTokens - this._prevTurnCumulativeUsage.totalTokens,
+        };
+        this._prevTurnCumulativeUsage = { ...this._cumulativeUsage };
+
+        if (turnText) {
+          const entry: VoiceTranscriptEntry = {
+            role: 'assistant',
+            text: turnText,
+            timestamp: Date.now(),
+          };
+          if (turnUsage.totalTokens > 0) {
+            entry.metadata = { tokenUsage: turnUsage };
+          }
+          this.appendTranscriptEntry(entry);
+        }
+
+        // Compute per-turn cost delta from cumulative cost snapshots
+        let turnCost: Record<string, number> | undefined;
+        if (this._cumulativeCost) {
+          if (this._prevTurnCumulativeCost) {
+            turnCost = {};
+            for (const key of Object.keys(this._cumulativeCost)) {
+              turnCost[key] = (this._cumulativeCost[key] || 0) - (this._prevTurnCumulativeCost[key] || 0);
+            }
+          } else {
+            turnCost = { ...this._cumulativeCost };
+          }
+          this._prevTurnCumulativeCost = { ...this._cumulativeCost };
+        }
+
+        // Attach per-turn metadata (usage + cost) to the last assistant Message
+        // (already created by is_final transcript events in bidi_transcript_stream).
+        if (turnUsage.totalTokens > 0 || turnCost) {
+          const metadata: Record<string, unknown> = {};
+          if (turnUsage.totalTokens > 0) {
+            metadata['tokenUsage'] = turnUsage;
+          }
+          if (turnCost) {
+            metadata['cost'] = turnCost;
+          }
+          this._voiceMessages.update(msgs => {
+            const last = msgs[msgs.length - 1];
+            // Skip if not assistant or already has metadata (e.g. set by attachPendingUsage on disconnect)
+            if (!last || last.role !== 'assistant' || last.metadata) return msgs;
+            const updated = [...msgs];
+            updated[updated.length - 1] = { ...last, metadata };
+            return updated;
+          });
+        }
+
+        // Speed up reveal to flush remaining buffered text
+        this._revealCharsPerTick = REVEAL_FLUSH_CHARS_PER_TICK;
+        this._status.set('listening');
+        break;
+      }
+
+      case 'bidi_interruption':
+        // User interrupted — stop playback
+        this.player.clear();
+        this._status.set('listening');
+        break;
+
+      case 'bidi_usage': {
+        // Nova Sonic reports CUMULATIVE token counts — replace, don't sum
+        const usage = (data['usage'] as Record<string, number>) ?? data;
+        this._cumulativeUsage = {
+          inputTokens: (usage['inputTokens'] as number) ?? this._cumulativeUsage.inputTokens,
+          outputTokens: (usage['outputTokens'] as number) ?? this._cumulativeUsage.outputTokens,
+          totalTokens: (usage['totalTokens'] as number) ?? this._cumulativeUsage.totalTokens,
+        };
+        // Capture cumulative cost breakdown (calculated server-side, sent with bidi_usage)
+        if (data['cost']) {
+          this._cumulativeCost = data['cost'] as Record<string, number>;
+        }
+        break;
+      }
+
+      case 'bidi_error':
+        console.error('Voice error:', data['message']);
+        break;
+
+      case 'bidi_connection_close':
+        this.cleanupAll();
+        this._status.set('idle');
+        this._isConnected.set(false);
+        break;
+
+      case 'pong':
+        // Keepalive response
+        break;
+    }
+  }
+
+  // --- Transcript reveal ---
+
+  private startRevealTimer(): void {
+    if (this._revealTimer) return; // already running
+    this._revealTimer = setInterval(() => {
+      const bufferedLen = this._bufferedTranscript().length;
+      const current = this._revealedIndex();
+      if (current >= bufferedLen) {
+        // Caught up — if not speaking anymore, stop the timer
+        if (this._status() !== 'speaking') {
+          this.stopRevealTimer();
+        }
+        return;
+      }
+      // Advance by configured chars per tick, snapping to word boundaries
+      const target = Math.min(current + this._revealCharsPerTick, bufferedLen);
+      // Find the next space or end-of-buffer to avoid splitting mid-word
+      const buf = this._bufferedTranscript();
+      let end = target;
+      if (end < bufferedLen && buf[end] !== ' ' && buf[end] !== '\n') {
+        const nextSpace = buf.indexOf(' ', end);
+        const nextNewline = buf.indexOf('\n', end);
+        const nearest = nextSpace === -1 ? nextNewline
+          : nextNewline === -1 ? nextSpace
+          : Math.min(nextSpace, nextNewline);
+        end = nearest === -1 ? bufferedLen : nearest + 1;
+      }
+      this._revealedIndex.set(end);
+    }, REVEAL_TICK_MS);
+  }
+
+  private stopRevealTimer(): void {
+    if (this._revealTimer) {
+      clearInterval(this._revealTimer);
+      this._revealTimer = null;
+    }
+  }
+
+  // --- Transcript management ---
+
+  /** Append an entry, evicting the oldest if at capacity. */
+  private appendTranscriptEntry(entry: VoiceTranscriptEntry): void {
+    this._transcriptEntries.update(entries => {
+      const updated = [...entries, entry];
+      return updated.length > MAX_TRANSCRIPT_ENTRIES
+        ? updated.slice(updated.length - MAX_TRANSCRIPT_ENTRIES)
+        : updated;
+    });
+  }
+
+  // --- Idle timeout ---
+
+  private resetIdleTimer(): void {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+    }
+    this.idleTimer = setTimeout(() => {
+      if (this._isConnected()) {
+        console.info('Voice idle timeout — disconnecting');
+        this.disconnect();
+      }
+    }, IDLE_TIMEOUT_MS);
+  }
+
+  // --- Cleanup ---
+
+  private cleanupAll(): void {
+    this.stopRevealTimer();
+
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+
+    this.recorder.onAudioChunk = null;
+    this.recorder.stop().catch(() => {});
+    this.player.clear();
+
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {
+        // Already closed
+      }
+      this.ws = null;
+    }
+  }
+}
diff --git a/frontend/ai.client/src/app/session/services/voice/voice.config.ts b/frontend/ai.client/src/app/session/services/voice/voice.config.ts
new file mode 100644
index 00000000..86e21e6d
--- /dev/null
+++ b/frontend/ai.client/src/app/session/services/voice/voice.config.ts
@@ -0,0 +1,49 @@
+/**
+ * Voice mode configuration constants.
+ *
+ * Centralizes all tunable values for the voice pipeline so they
+ * can be found and adjusted in one place.
+ */
+
+/** Audio sample rate in Hz. Nova Sonic expects 16kHz mono PCM. */
+export const VOICE_SAMPLE_RATE = 16000;
+
+/** Duration of each audio chunk in milliseconds. */
+export const CHUNK_DURATION_MS = 100;
+
+/** Number of samples per chunk (sampleRate * chunkDuration / 1000). */
+export const SAMPLES_PER_CHUNK = (VOICE_SAMPLE_RATE * CHUNK_DURATION_MS) / 1000; // 1600
+
+/** Auto-disconnect after this many milliseconds of silence. */
+export const IDLE_TIMEOUT_MS = 60_000;
+
+/** WebSocket connection timeout in milliseconds. */
+export const WS_CONNECT_TIMEOUT_MS = 10_000;
+
+/** Maximum transcript entries kept in memory per session. */
+export const MAX_TRANSCRIPT_ENTRIES = 200;
+
+/**
+ * Transcript reveal speed — characters per tick while the agent is speaking.
+ * ~20 chars/sec at 50ms ticks ≈ natural speaking pace.
+ */
+export const REVEAL_CHARS_PER_TICK = 2;
+
+/** Interval in ms between reveal ticks. */
+export const REVEAL_TICK_MS = 50;
+
+/** Characters per tick when flushing remaining text after response completes. */
+export const REVEAL_FLUSH_CHARS_PER_TICK = 5;
+
+/** WebSocket close codes and their user-facing meanings. */
+export const WS_CLOSE_REASONS: Record<number, string> = {
+  1000: 'Session ended normally',
+  1001: 'Server shutting down',
+  1006: 'Connection lost — check your network',
+  1008: 'Policy violation',
+  1011: 'Server error',
+  4001: 'Authentication failed',
+  4003: 'Forbidden',
+  4008: 'Session timeout',
+  4029: 'Rate limited — try again shortly',
+};
diff --git a/frontend/ai.client/src/app/session/session.page.html b/frontend/ai.client/src/app/session/session.page.html
index 479c09a5..18431c70 100644
--- a/frontend/ai.client/src/app/session/session.page.html
+++ b/frontend/ai.client/src/app/session/session.page.html
@@ -17,6 +17,7 @@
   (assistantNewSession)="newAssistantSession()"
   (assistantEdit)="editAssistant()"
   (assistantShare)="shareAssistant()"
+  (voiceClosed)="onVoiceClosed()"
 />
 
 <!-- Model Settings Panel -->
diff --git a/frontend/ai.client/src/app/session/session.page.ts b/frontend/ai.client/src/app/session/session.page.ts
index 9e867fda..d3118082 100644
--- a/frontend/ai.client/src/app/session/session.page.ts
+++ b/frontend/ai.client/src/app/session/session.page.ts
@@ -22,6 +22,7 @@ import {
   ShareAssistantDialogComponent,
   ShareAssistantDialogData,
 } from '../assistants/components/share-assistant-dialog.component';
+import { VoiceChatService } from './services/voice';
 
 @Component({
   selector: 'app-session-page',
@@ -44,9 +45,11 @@ export class ConversationPage implements OnDestroy {
   private assistantService = inject(AssistantService);
   private router = inject(Router);
   private dialog = inject(Dialog);
+  private voiceChatService = inject(VoiceChatService);
 
   sessionId = signal<string | null>(null);
   assistantIdFromQuery = signal<string | null>(null);
+
   assistant = signal<Assistant | null>(null);
   assistantError = signal<string | null>(null);
   isLoadingAssistant = signal(false);
@@ -72,8 +75,14 @@ export class ConversationPage implements OnDestroy {
   // Writable signal that holds the current messages signal reference
   private messagesSignal = signal<Signal<Message[]>>(signal([]));
 
-  // Computed that unwraps the current messages signal
-  readonly messages = computed(() => this.messagesSignal()());
+  // Computed that unwraps the current messages signal, merging in
+  // real-time voice messages. Voice messages are cleared on voice close
+  // after being persisted to the map, so there's no double-counting.
+  readonly messages = computed(() => {
+    const base = this.messagesSignal()();
+    const voice = this.voiceChatService.voiceMessages();
+    return voice.length > 0 ? [...base, ...voice] : base;
+  });
 
   // Get user's first name from the user service
   private firstName = computed(() => {
@@ -287,6 +296,66 @@ export class ConversationPage implements OnDestroy {
     this.chatHttpService.cancelChatRequest();
   }
 
+  /**
+   * Called when the voice overlay closes.
+   *
+   * By this point, disconnect() has already set isVoiceActive = false,
+   * so the messages computed stops merging voiceMessages. We persist
+   * those messages into the message map (so they survive navigation)
+   * and update the URL.
+   */
+  onVoiceClosed() {
+    const voiceMsgs = this.voiceChatService.voiceMessages();
+    if (voiceMsgs.length === 0) return;
+
+    const sessionId = this.voiceChatService.getSessionId();
+    if (!sessionId) return;
+
+    // Persist voice messages into the message map so they survive
+    // page navigation and show up when the overlay is gone.
+    // Filter out any messages with no text (e.g. interrupted before first delta).
+    this.messagesSignal.set(this.messageMapService.getMessagesForSession(sessionId));
+    for (const msg of voiceMsgs) {
+      const textBlock = msg.content.find(b => b.type === 'text');
+      const text = textBlock?.text || '';
+      if (!text) continue;
+      this.messageMapService.addVoiceMessage(
+        sessionId,
+        msg.role as 'user' | 'assistant',
+        text,
+        msg.metadata ?? undefined,
+      );
+    }
+
+    // Clear voice messages now that they're in the map — prevents any
+    // change detection cycle from seeing both sources simultaneously.
+    this.voiceChatService.clearVoiceMessages();
+
+    // If there's no route session yet, navigate (fire-and-forget).
+    // addSessionToCache MUST happen before navigation so the route
+    // subscription recognises this as new and skips the API fetch
+    // (same sequencing as ChatRequestService.navigateToSession).
+    if (!this.effectiveSessionId()) {
+      const user = this.userService.currentUser();
+      const userId = user?.user_id || 'anonymous';
+      this.sessionService.addSessionToCache(sessionId, userId);
+      this.router.navigate(['s', sessionId], { replaceUrl: true });
+    }
+
+    // Generate title for new voice sessions (fire and forget)
+    const firstUserMsg = voiceMsgs.find(m => m.role === 'user');
+    const firstUserText = firstUserMsg?.content[0]?.text;
+    if (firstUserText && this.sessionService.isNewSession(sessionId)) {
+      this.chatHttpService.generateTitle(sessionId, firstUserText)
+        .then((response) => {
+          this.sessionService.updateSessionTitleInCache(sessionId, response.title);
+        })
+        .catch((err) => {
+          console.warn('Failed to generate voice session title:', err);
+        });
+    }
+  }
+
   toggleSettings() {
     this.isSettingsOpen.update(open => !open);
   }
diff --git a/frontend/ai.client/src/environments/environment.ts b/frontend/ai.client/src/environments/environment.ts
index 6446804a..c7249a13 100644
--- a/frontend/ai.client/src/environments/environment.ts
+++ b/frontend/ai.client/src/environments/environment.ts
@@ -24,8 +24,8 @@ export const environment = {
     production: false,
     appApiUrl: 'http://localhost:8000',
     version: 'dev',
-    cognitoDomainUrl: '',
-    cognitoAppClientId: '',
+    cognitoDomainUrl: 'https://dev-boisestateai-v2.auth.us-west-2.amazoncognito.com',
+    cognitoAppClientId: '49bgkj3r1q23kkabqcg7m8c4si',
     cognitoRegion: 'us-east-1',
     inferenceApiUrl: 'http://localhost:8001',
 };
diff --git a/frontend/ai.client/tsconfig.json b/frontend/ai.client/tsconfig.json
index 2ab74427..e4baaf3a 100644
--- a/frontend/ai.client/tsconfig.json
+++ b/frontend/ai.client/tsconfig.json
@@ -13,7 +13,8 @@
     "experimentalDecorators": true,
     "importHelpers": true,
     "target": "ES2022",
-    "module": "preserve"
+    "module": "preserve",
+    "moduleResolution": "bundler"
   },
   "angularCompilerOptions": {
     "enableI18nLegacyMessageIdFormat": false,
diff --git a/infrastructure/lib/inference-api-stack.ts b/infrastructure/lib/inference-api-stack.ts
index 38054159..35f3413c 100644
--- a/infrastructure/lib/inference-api-stack.ts
+++ b/infrastructure/lib/inference-api-stack.ts
@@ -896,6 +896,8 @@ export class InferenceApiStack extends cdk.Stack {
       networkConfiguration: {
         networkMode: 'PUBLIC',
       },
+      // HTTP protocol supports both REST (/invocations) and WebSocket (/ws) endpoints
+      protocolConfiguration: 'HTTP',
       requestHeaderConfiguration: {
         requestHeaderAllowlist: ['Authorization'],
       },
diff --git a/scripts/nightly/e2e-test.sh b/scripts/nightly/e2e-test.sh
new file mode 100755
index 00000000..008e2ff4
--- /dev/null
+++ b/scripts/nightly/e2e-test.sh
@@ -0,0 +1,136 @@
+#!/bin/bash
+set -euo pipefail
+
+# Script: Run Playwright E2E Tests Against a Deployed Nightly Stack
+# Description: Installs Playwright browsers, resolves the ALB URL, and runs
+#              the full E2E suite using the CI-specific Playwright config.
+#
+# Required environment variables:
+#   CDK_PROJECT_PREFIX    — CDK project prefix (e.g. nightly-develop)
+#   CDK_AWS_REGION        — AWS region for CloudFormation lookups
+#   ADMIN_USERNAME        — Cognito admin test account username
+#   ADMIN_PASSWORD        — Cognito admin test account password
+#   USER_USERNAME         — Cognito regular user test account username
+#   USER_PASSWORD         — Cognito regular user test account password
+#
+# Optional environment variables:
+#   CDK_ALB_SUBDOMAIN     — ALB subdomain (preferred over CF lookup)
+#   CDK_HOSTED_ZONE_DOMAIN — Hosted zone domain (used with subdomain)
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+FRONTEND_DIR="${PROJECT_ROOT}/frontend/ai.client"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log_info()    { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_error()   { echo -e "${RED}[ERROR]${NC} $1" >&2; }
+log_warn()    { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
+
+# ---------------------------------------------------------------------------
+# Resolve the base URL of the deployed stack
+# ---------------------------------------------------------------------------
+get_base_url() {
+    # Prefer the custom HTTPS subdomain when configured
+    if [ -n "${CDK_ALB_SUBDOMAIN:-}" ] && [ -n "${CDK_HOSTED_ZONE_DOMAIN:-}" ]; then
+        echo "https://${CDK_ALB_SUBDOMAIN}.${CDK_HOSTED_ZONE_DOMAIN}"
+        return 0
+    fi
+
+    local stack_name="${CDK_PROJECT_PREFIX}-InfrastructureStack"
+    local alb_dns
+    alb_dns=$(aws cloudformation describe-stacks \
+        --stack-name "${stack_name}" \
+        --query "Stacks[0].Outputs[?OutputKey=='AlbDnsName'].OutputValue" \
+        --output text \
+        --region "${CDK_AWS_REGION}")
+
+    if [ -z "${alb_dns}" ]; then
+        log_error "Could not retrieve ALB DNS name from stack ${stack_name}"
+        return 1
+    fi
+
+    echo "https://${alb_dns}"
+}
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+main() {
+    log_info "Starting Playwright E2E tests against deployed nightly stack..."
+
+    # --- Validate required env vars ---
+    local missing=()
+    [ -z "${CDK_PROJECT_PREFIX:-}" ]  && missing+=("CDK_PROJECT_PREFIX")
+    [ -z "${CDK_AWS_REGION:-}" ]      && missing+=("CDK_AWS_REGION")
+    [ -z "${ADMIN_USERNAME:-}" ]      && missing+=("ADMIN_USERNAME")
+    [ -z "${ADMIN_PASSWORD:-}" ]      && missing+=("ADMIN_PASSWORD")
+    [ -z "${USER_USERNAME:-}" ]       && missing+=("USER_USERNAME")
+    [ -z "${USER_PASSWORD:-}" ]       && missing+=("USER_PASSWORD")
+
+    if [ ${#missing[@]} -gt 0 ]; then
+        log_error "Missing required environment variables: ${missing[*]}"
+        exit 1
+    fi
+
+    # --- Resolve base URL ---
+    log_info "Resolving deployed stack URL..."
+    local base_url
+    base_url=$(get_base_url)
+    log_info "Base URL: ${base_url}"
+
+    # --- Verify frontend is reachable ---
+    log_info "Verifying frontend is reachable..."
+    local response_code
+    response_code=$(curl -s -o /dev/null -w "%{http_code}" "${base_url}" --max-time 30 || echo "000")
+    if [ "${response_code}" = "000" ]; then
+        log_error "Frontend is not reachable at ${base_url} (connection failed)"
+        exit 1
+    fi
+    log_info "Frontend responded with HTTP ${response_code}"
+
+    # --- Change to frontend directory ---
+    cd "${FRONTEND_DIR}"
+
+    # --- Check node_modules ---
+    if [ ! -d "node_modules" ]; then
+        log_error "node_modules not found. Frontend dependencies must be installed first."
+        exit 1
+    fi
+
+    # --- Install Playwright browsers ---
+    log_info "Installing Playwright browsers (chromium only)..."
+    npx playwright install --with-deps chromium
+
+    # --- Run E2E tests ---
+    log_info "Running Playwright E2E tests..."
+    log_info "  Config: playwright.ci.config.ts"
+    log_info "  Base URL: ${base_url}"
+
+    export E2E_BASE_URL="${base_url}"
+    export CI=true
+
+    # Run tests — allow failure so we can still upload artifacts
+    local exit_code=0
+    npx playwright test --config=playwright.ci.config.ts || exit_code=$?
+
+    if [ ${exit_code} -eq 0 ]; then
+        log_success "All E2E tests passed!"
+    else
+        log_error "E2E tests failed with exit code: ${exit_code}"
+    fi
+
+    # Report location is always relative to the config file
+    if [ -d "playwright-report" ]; then
+        log_info "HTML report generated: playwright-report/index.html"
+    fi
+
+    return ${exit_code}
+}
+
+main "$@"