feat: decouple manual image sharing from automation gating

The "Share a saved image" panel was wired to the automated exchange
engine, so an operator could only share an image right after an inbound
image request, limited to assets the auto-exchanger would itself pick.

Add a manual path that offers any enabled, unused library image at any
point (no request detection, tier, seller, or boundary gating) and sends
it with no reciprocal "your turn" text. Safety flags now surface as a
non-blocking warning instead of disabling the panel. The automated
auto-send path keeps all its guardrails; the shared image-delivery step
is extracted into a helper used by both paths.

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

DOKPLOY_DEPLOY.md

@@ -1,57 +1,35 @@
-# Deploying RedditBot to Dokploy
+# Dokploy deployment
 
-This guide explains how to deploy the RedditBot to Dokploy without needing to manually transfer your local browser session.
+RedditBot now uses extension dumps as its only account-authentication path. The container does not expose VNC, start Google Chrome, submit Reddit credentials, or sniff Matrix tokens.
 
-## Automated Login Feature
+## Environment
 
-The bot has been updated to support automated login using environment variables. This means when you deploy to a fresh server (like Dokploy), the bot will detect it's not logged in and automatically authenticate using the credentials you provide.
+Configure only the application secrets required by the Compose file:
 
-## Deployment Steps
+- `OPENROUTER_API_KEY`
+- `WEB_DASHBOARD_TOKEN`
 
-1.  **Create a New Application in Dokploy**:
-    *   Select "Docker Compose" as the deployment method (recommended) or "Dockerfile".
+Optional agent credentials:
 
-2.  **Environment Variables**:
-    *   Go to the "Environment" tab of your application.
-    *   Add the following variables:
-        *   `OPENROUTER_API_KEY`: Your OpenRouter API key.
-        *   `REDDIT_USERNAME`: Your Reddit username.
-        *   `REDDIT_PASSWORD`: Your Reddit password.
-        *   `BROWSER_HEADLESS`: `false` (required for interactive noVNC login).
-        *   `VNC_PASSWORD`: A strong password for the interactive VNC session.
-        *   `NOVNC_PUBLIC_URL`: `http://<dokploy-host>:16080`.
+- `REDDIT_BOT_AGENT_READ_TOKEN` permits authenticated GET/SSE access but cannot mutate state.
+- `REDDIT_BOT_AGENT_CONTROL_TOKEN` additionally permits versioned control and sync-job operations.
 
-3.  **Volumes (Persistence)**:
-    *   The `docker-compose.yml` is already configured to mount a `./data` volume.
-    *   Dokploy usually handles volumes automatically for Docker Compose projects, or you may need to define a persistent volume path if you want data to survive container recreations (which you do, to avoid logging in every time).
-    *   Make sure the `/app/data` directory is persisted.
+Use separate long random values. Neither agent token can invoke legacy send,
+session-import, account-activation, or configuration mutations. The dashboard
+token remains the administrator credential.
 
-4.  **Deploy**:
-    *   Push your code to your Git repository connected to Dokploy.
-    *   Click "Deploy".
+Do not configure Reddit usernames, passwords, display servers, CDP endpoints, or remote-browser ports.
 
-## noVNC networking
+## Account activation
 
-The Compose configuration publishes noVNC directly on host port `16080`.
-Do not route it through a Dokploy/Traefik domain: the upstream proxy strips
-the WebSocket Upgrade request that noVNC requires, producing `rfb.js:688` with
-WebSocket code `1011` and “Failed to connect to downstream server”.
+1. Deploy the service and open the dashboard.
+2. Install the extension from `extensions/reddit-session-exporter` in your local Chrome profile.
+3. Sign in to Reddit locally, open Reddit Chat, and wait for the extension badge to show `OK`.
+4. Export `redditbot-session.json` and upload it under **Settings > Access**.
+5. Delete the local JSON file after the dashboard verifies it.
 
-Set `NOVNC_PUBLIC_URL` to `http://<dokploy-host>:16080`, then open that URL in
-a separate tab from the dashboard. If the dashboard itself is HTTPS, browsers
-will not embed this HTTP endpoint in its iframe; the separate-tab link is the
-intended route. Restrict inbound TCP `16080` at the Dokploy host firewall to
-your own IP or VPN subnet.
+The dump contains both Reddit cookies and a Matrix bearer token. Until both identities verify, the bot, response checks, chat, media sync, and dashboard start control remain paused. If either credential expires, import a new dump.
 
-## How it works
+## Persistence
 
-1.  On the first run, the bot will see the `data/browser-session` folder is empty/invalid.
-2.  It will read `REDDIT_USERNAME` and `REDDIT_PASSWORD`.
-3.  It will launch a headless browser, navigate to Reddit, and log in.
-4.  The session cookies and storage will be saved to `data/browser-session`.
-5.  On subsequent restarts, it will use the saved session (as long as the `/app/data` volume is persisted).
-
-## Troubleshooting
-
-*   **Login Failed**: Check the application logs. If Reddit presents a captcha or 2FA, the automated login will fail. You may need to temporarily run locally to solve the captcha, then copy the session (though this feature avoids that for standard accounts).
-*   **Verification**: The logs will show "Credentials found in config/env. Attempting automated login..." followed by "Login successful!".
+The `reddit_bot_data` volume retains the database, the imported Playwright cookie profile, and the verified Matrix credential across deployments. Back up this volume as sensitive account data.

Dockerfile

@@ -1,58 +1,17 @@
-# Use the official Playwright image which includes all browser dependencies
 FROM mcr.microsoft.com/playwright:v1.57.0-jammy
 
-# Install Xvfb (virtual display), x11vnc (VNC server) and noVNC (web-based VNC client)
-# so a human can log in to Reddit through the dashboard.
-ENV DEBIAN_FRONTEND=noninteractive \
-    TZ=Etc/UTC
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    tzdata \
-    xvfb \
-    x11vnc \
-    x11-utils \
-    novnc \
-    websockify \
-    fluxbox \
-    procps \
-    ca-certificates \
-    curl \
-  && curl -fsSLo /tmp/google-chrome-stable_current_amd64.deb \
-    https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb \
-  && apt-get install -y --no-install-recommends \
-    /tmp/google-chrome-stable_current_amd64.deb \
-  && rm -f /tmp/google-chrome-stable_current_amd64.deb \
-  && rm -rf /var/lib/apt/lists/*
-
 WORKDIR /app
 
-# Copy package files
-COPY package*.json ./
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential \
+    && rm -rf /var/lib/apt/lists/*
 
-# Install dependencies (including devDependencies for building)
+COPY package*.json ./
 RUN npm ci
 
-# Copy source code
 COPY . .
-
-# Build the TypeScript project
 RUN npm run build
-
-# Create data directory
 RUN mkdir -p data
 
-# Copy entrypoint
-COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
-RUN chmod +x /usr/local/bin/entrypoint.sh
-
-# Web dashboard
 EXPOSE 3000
-# noVNC (browser-accessible VNC for human login)
-EXPOSE 6080
-
-ENV DISPLAY=:99 \
-    VNC_DISPLAY_NUM=99 \
-    VNC_PORT=5900 \
-    NOVNC_PORT=6080 \
-    SCREEN_GEOMETRY=1280x800x24
-
-CMD ["/usr/local/bin/entrypoint.sh"]
+CMD ["node", "dist/index.js"]

agents.md

@@ -1,5 +1,19 @@
 # Agent Guidelines & Code Standards
 
+## Required orientation and documentation maintenance
+
+Before changing code, read [`docs/README.md`](docs/README.md) and the documents it routes to for the area you are touching. Treat the source code, tests, generated API reference, and migrations as authoritative when a document disagrees with implementation.
+
+Documentation is part of the change, not a follow-up task:
+
+- Update the relevant file in `docs/` whenever behavior, architecture, configuration, data ownership, API contracts, operations, safety boundaries, or development workflow changes.
+- Update `docs/README.md` when adding, renaming, or removing a document.
+- Run `npm run docs:api` after changing `src/web/api-catalog.ts`; verify with `npm run docs:api:check`.
+- Prefer durable explanations and links to owning source files over copied implementation details, line counts, credentials, production IDs, or other facts likely to drift.
+- During final review, explicitly check whether the documentation still describes the code that will be committed.
+
+Do not start, restart, deploy, or otherwise enable live outreach unless the user explicitly authorizes that operational action. A code or documentation request does not imply permission to run the bot. Never expose `.env`, imported account dumps, cookies, Matrix tokens, dashboard tokens, private media, or database contents.
+
 ## Refactoring Goal
 Refactor code to improve maintainability, testability, and clarity. Break down large components into smaller, single-purpose classes/modules.
 
@@ -19,20 +33,11 @@ Refactor code to improve maintainability, testability, and clarity. Break down l
 - **Zod Validation**: Use `zod` (already in deps) to validate external data (config files, API responses).
 - **Async/Await**: properly handle promises. Use `p-queue` or `p-retry` for rate-limited operations.
 
-### 4. Test-Driven Development (TDD) — REQUIRED
-All new functionality and bug fixes MUST follow the red-green-refactor cycle. This is non-negotiable.
-
-- **Red**: Write a failing test FIRST that describes the desired behavior. Run it and confirm it fails for the expected reason.
-- **Green**: Write the minimum production code needed to make the test pass. No extra features, no speculative abstractions.
-- **Refactor**: With tests green, clean up implementation and tests. Re-run the suite after each change.
-
-**Rules**:
-- Never commit production code without an accompanying test that fails without it.
+### 4. Testing
+- TDD is not required. Agents may implement changes before writing or updating tests.
+- Add or update tests when they provide useful coverage for new functionality or bug fixes.
 - Tests live in `tests/` (mirroring `src/` structure) and run via `vitest` (`npm test`).
-- Use dependency injection so collaborators (DB, HTTP, browser, clock) can be faked — do not mock what you don't own; wrap third-party APIs in a thin interface and fake the interface.
 - Prefer behavior-focused tests (inputs → outputs / observable side effects) over tests that pin internal structure.
-- Bug fixes start with a regression test that reproduces the bug.
-- If a change is genuinely untestable (e.g. a one-line config tweak), state that explicitly in the PR/commit rather than skipping silently.
 
 ### 5. Project Specifics
 - **Tech Stack**: Node.js, TypeScript, Playwright, Express, SQLite, Vitest.
@@ -44,11 +49,13 @@ All new functionality and bug fixes MUST follow the red-green-refactor cycle. Th
 - **Logging**: Use `winston` for structured logging. Do not use `console.log` in production code.
 
 ## Workflow for Agents
-1. **Analyze**: Before writing code, read the file and understand the context.
-2. **Plan**: Identify what needs to change. Check if the change violates SRP. Identify the test(s) that will drive the change.
-3. **Write failing test (Red)**: Add a vitest spec that captures the new behavior or reproduces the bug. Run `npm test` and confirm it fails for the right reason.
-4. **Implement (Green)**: Write the smallest change that makes the test pass. Create new small files when SRP calls for it.
-5. **Refactor**: Tidy the implementation and the test with the suite green. Re-run tests after each refactor step.
-6. **Verify**: Ensure the full suite passes (`npm test`) and types check (`npm run build` or `tsc --noEmit`).
+1. **Orient**: Read `docs/README.md`, the relevant topic documents, and the owning code/tests.
+2. **Analyze**: Before writing code, read the file and understand the context.
+3. **Plan**: Identify what needs to change and check if the change violates SRP.
+4. **Implement**: Make the scoped change. Create new small files when SRP calls for it.
+5. **Test**: Add or update useful tests as appropriate for the change.
+6. **Document**: Update the routed documentation for any changed contract or workflow.
+7. **Refactor**: Tidy the implementation and tests while preserving behavior.
+8. **Verify**: Run the relevant tests, documentation checks, and type checks (`npm run build` or `tsc --noEmit`) in proportion to the change.
 
-You must use the dokploy credentials in .env for access to dokploy
+When Dokploy access is explicitly requested, use the credentials in the ignored `.env` file. Do not print, copy, commit, or blindly source that file.

apps/dashboard/src/api/client.ts

@@ -7,6 +7,7 @@ import {
   type ControlResponse,
   type Timers,
 } from './contracts.js';
+import { createDashboardRequest } from './request.js';
 
 export class ApiError extends Error {
   constructor(
@@ -39,9 +40,7 @@ export interface DashboardApi {
 }
 
 export function createDashboardApi(fetchImplementation?: typeof fetch): DashboardApi {
-  function request(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
-    return (fetchImplementation ?? globalThis.fetch)(input, init);
-  }
+  const request = createDashboardRequest(fetchImplementation);
 
   return {
     async getStats() {

apps/dashboard/src/api/queries.ts

@@ -8,11 +8,15 @@ export const dashboardQueryKeys = {
 };
 
 export function useStatsQuery() {
-  return useQuery({ queryKey: dashboardQueryKeys.stats, queryFn: dashboardApi.getStats });
+  return useQuery({
+    queryKey: dashboardQueryKeys.stats,
+    queryFn: dashboardApi.getStats,
+    refetchInterval: 15_000,
+  });
 }
 
 export function useTimersQuery() {
-  return useQuery({ queryKey: dashboardQueryKeys.timers, queryFn: dashboardApi.getTimers });
+  return useQuery({ queryKey: dashboardQueryKeys.timers, queryFn: dashboardApi.getTimers, refetchInterval: 15_000 });
 }
 
 export function useSetRunningMutation() {

apps/dashboard/src/api/request.ts

@@ -0,0 +1,19 @@
+export type DashboardRequest = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+function redirectToLogin(): void {
+  globalThis.location.assign('/auth/login');
+}
+
+export function createDashboardRequest(
+  fetchImplementation: typeof fetch | undefined = undefined,
+  onUnauthorized: () => void = redirectToLogin,
+): DashboardRequest {
+  return async (input, init) => {
+    const fetchRequest = fetchImplementation ?? globalThis.fetch;
+    const response = await fetchRequest(input, { credentials: 'same-origin', ...init });
+    if (response.status === 401) onUnauthorized();
+    return response;
+  };
+}
+
+export const dashboardRequest = createDashboardRequest();

apps/dashboard/src/app/app-shell.tsx

@@ -1,12 +1,14 @@
 import { useState } from 'react';
 import { NavLink, Outlet } from 'react-router-dom';
 import { navigationItems } from './navigation.js';
+import { ShellStatusPanel } from './shell-status-panel.js';
+import { NotificationBell, NotificationProvider, NotificationViewport } from './notifications.js';
 
 export function AppShell() {
   const [isNavigationOpen, setIsNavigationOpen] = useState(false);
 
   return (
-    <div className="app-shell">
+    <NotificationProvider><div className="app-shell">
       <a className="skip-link" href="#main-content">Skip to content</a>
       <aside className={isNavigationOpen ? 'sidebar is-open' : 'sidebar'}>
         <div className="brand">
@@ -15,6 +17,7 @@ export function AppShell() {
             <strong>Reddit Bot</strong>
             <span>Operator console</span>
           </div>
+          <NotificationBell />
         </div>
         <nav aria-label="Primary navigation" id="primary-navigation">
           {navigationItems.map((item) => (
@@ -31,6 +34,7 @@ export function AppShell() {
             </NavLink>
           ))}
         </nav>
+        <ShellStatusPanel />
       </aside>
       {isNavigationOpen ? (
         <button
@@ -43,6 +47,8 @@ export function AppShell() {
       <div className="workspace">
         <header className="mobile-header">
           <span>Reddit Bot</span>
+          <div className="mobile-header-actions">
+            <NotificationBell />
             <button
               aria-controls="primary-navigation"
               aria-expanded={isNavigationOpen}
@@ -53,11 +59,13 @@ export function AppShell() {
             >
               <span aria-hidden="true">{isNavigationOpen ? '×' : '☰'}</span>
             </button>
+          </div>
         </header>
         <main id="main-content" tabIndex={-1}>
           <Outlet />
         </main>
       </div>
-    </div>
+      <NotificationViewport />
+    </div></NotificationProvider>
   );
 }

apps/dashboard/src/app/navigation.ts

@@ -6,8 +6,11 @@ export interface NavigationItem {
 
 export const navigationItems: readonly NavigationItem[] = [
   { label: 'Overview', path: '/', description: 'System health and current activity' },
+  { label: 'Needs attention', path: '/attention', description: 'Handoffs, failures, and account risks' },
+  { label: 'Outreach funnel', path: '/outreach', description: 'Active posts moving toward delivery' },
   { label: 'Conversations', path: '/conversations', description: 'Inbox and message history' },
   { label: 'Media', path: '/media', description: 'Private media and sync controls' },
+  { label: 'Exchange library', path: '/media-library', description: 'Images the bot may send when asked' },
   { label: 'Performance', path: '/performance', description: 'Response and strategy trends' },
   { label: 'Operations', path: '/operations', description: 'Jobs, events, and diagnostics' },
   { label: 'Settings', path: '/settings', description: 'Runtime and access configuration' },

apps/dashboard/src/app/notifications.css

@@ -0,0 +1,57 @@
+.notification-bell {
+  position: relative;
+  display: grid;
+  flex: 0 0 auto;
+  place-items: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  padding: 0;
+  color: #dfe9e3;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: .7rem;
+}
+.notification-bell:hover { color: var(--accent); border-color: #3d5a4c; }
+.notification-bell:focus-visible, .notification-close:focus-visible, .notification-clear:focus-visible, .notification-entry:focus-visible, .notification-toast a:focus-visible, .notification-toast button:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.notification-bell svg, .notification-empty svg { width: 1.2rem; fill: none; stroke: currentColor; stroke-linecap: round; stroke-linejoin: round; stroke-width: 1.8; }
+.notification-badge { position: absolute; top: -.35rem; right: -.35rem; display: grid; place-items: center; min-width: 1.15rem; height: 1.15rem; padding: 0 .25rem; color: #07130c; background: var(--accent); border: 2px solid #0c1511; border-radius: 999px; font-size: .62rem; font-weight: 900; line-height: 1; }
+.brand { justify-content: space-between; }
+.brand > div { margin-right: auto; }
+.notification-backdrop { position: fixed; inset: 0; z-index: 69; width: 100%; padding: 0; background: rgba(0, 0, 0, .52); border: 0; }
+.notification-centre { position: fixed; inset: 0 0 0 auto; z-index: 70; display: grid; grid-template-rows: auto minmax(0, 1fr) auto; width: min(27rem, 100%); visibility: hidden; background: #0c1511; border-left: 1px solid var(--border); box-shadow: -1.5rem 0 4rem rgba(0, 0, 0, .38); transform: translateX(100%); transition: transform 220ms ease, visibility 220ms; }
+.notification-centre.is-open { visibility: visible; transform: translateX(0); }
+.notification-centre > header { display: flex; align-items: center; justify-content: space-between; min-height: 5.5rem; padding: 1.2rem 1.25rem; border-bottom: 1px solid var(--border); }
+.notification-centre h2 { font-size: 1.35rem; letter-spacing: -.025em; }
+.notification-centre .eyebrow { margin-bottom: .25rem; }
+.notification-close { display: grid; place-items: center; width: 2.35rem; height: 2.35rem; padding: 0; color: var(--muted); background: transparent; border: 1px solid var(--border); border-radius: .6rem; font-size: 1.5rem; line-height: 1; }
+.notification-list { min-height: 0; padding: 0; margin: 0; overflow-y: auto; list-style: none; }
+.notification-list li { border-bottom: 1px solid var(--border); }
+.notification-entry { display: grid; grid-template-columns: .65rem minmax(0, 1fr); gap: .8rem; padding: 1rem 1.25rem; color: inherit; text-decoration: none; }
+a.notification-entry:hover { background: var(--surface); }
+.notification-signal { width: .55rem; height: .55rem; margin-top: .3rem; background: #77a6d8; border-radius: 50%; box-shadow: 0 0 0 .3rem rgba(119, 166, 216, .1); }
+.notification-signal.success { background: var(--accent); box-shadow: 0 0 0 .3rem rgba(117, 214, 157, .1); }
+.notification-signal.warning { background: var(--warning); box-shadow: 0 0 0 .3rem rgba(243, 199, 107, .1); }
+.notification-signal.error { background: var(--danger); box-shadow: 0 0 0 .3rem rgba(255, 138, 132, .1); }
+.notification-copy { display: grid; gap: .28rem; min-width: 0; }
+.notification-copy strong { color: #edf5f0; font-size: .9rem; line-height: 1.3; }
+.notification-copy > span { overflow: hidden; color: var(--muted); font-size: .82rem; line-height: 1.45; text-overflow: ellipsis; }
+.notification-copy time { color: #71857b; font-size: .7rem; }
+.notification-centre > footer { display: flex; justify-content: flex-end; padding: .8rem 1.25rem; border-top: 1px solid var(--border); }
+.notification-clear { padding: .4rem 0; color: var(--muted); background: transparent; border: 0; font-size: .78rem; font-weight: 700; }
+.notification-clear:hover { color: #edf5f0; }
+.notification-empty { display: grid; place-items: center; align-content: center; padding: 2rem; text-align: center; }
+.notification-empty > span { display: grid; place-items: center; width: 3.25rem; height: 3.25rem; margin-bottom: .9rem; color: var(--accent); background: var(--accent-dark); border: 1px solid #28593d; border-radius: 1rem; }
+.notification-empty strong { margin-bottom: .35rem; font-size: 1rem; }
+.notification-empty p { max-width: 18rem; margin: 0; color: var(--muted); font-size: .82rem; line-height: 1.5; }
+.toast-stack { position: fixed; right: 1rem; bottom: 1rem; z-index: 75; display: grid; gap: .65rem; width: min(24rem, calc(100% - 2rem)); pointer-events: none; }
+.notification-toast { position: relative; overflow: hidden; background: #15221c; border: 1px solid #355044; border-radius: .85rem; box-shadow: 0 1rem 3rem rgba(0, 0, 0, .4); pointer-events: auto; animation: notification-arrive 220ms ease-out both; }
+.notification-toast.warning { background: #282112; border-color: #5b4922; }
+.notification-toast.error { background: #2d1715; border-color: #69332e; }
+.notification-toast > a, .notification-toast > div { display: grid; grid-template-columns: .65rem minmax(0, 1fr); gap: .75rem; padding: .9rem 2.75rem .9rem 1rem; color: inherit; text-decoration: none; }
+.notification-toast > a:hover { background: rgba(255, 255, 255, .035); }
+.notification-toast .notification-copy time { display: none; }
+.notification-toast > button { position: absolute; top: .5rem; right: .5rem; width: 1.8rem; height: 1.8rem; padding: 0; color: var(--muted); background: transparent; border: 0; border-radius: .35rem; font-size: 1.2rem; }
+@keyframes notification-arrive { from { opacity: 0; transform: translateY(.75rem) scale(.98); } }
+@media (prefers-reduced-motion: reduce) { .notification-centre, .notification-toast { transition: none; animation: none; } }
+@media (max-width: 47.999rem) { .brand .notification-bell { display: none; } .toast-stack { bottom: .75rem; } }
+@media (min-width: 48rem) { .mobile-header .notification-bell { display: none; } }

apps/dashboard/src/app/notifications.tsx

@@ -0,0 +1,346 @@
+import type { DashboardEvent } from '../../../../packages/api-contracts/src/index.js';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type PropsWithChildren,
+} from 'react';
+import { Link } from 'react-router-dom';
+import { z } from 'zod';
+import { useDashboardRealtime } from './realtime-provider.js';
+import './notifications.css';
+
+export type NotificationTone = 'info' | 'success' | 'warning' | 'error';
+
+export interface NotificationItem {
+  id: string;
+  title: string;
+  message: string;
+  occurredAt: string;
+  tone: NotificationTone;
+  href?: string;
+  isRead: boolean;
+}
+
+export type NotificationDraft = Omit<NotificationItem, 'isRead'>;
+
+interface NotificationContextValue {
+  isOpen: boolean;
+  notifications: readonly NotificationItem[];
+  toasts: readonly NotificationItem[];
+  unreadCount: number;
+  clearAll(): void;
+  dismissToast(id: string): void;
+  setOpen(isOpen: boolean): void;
+}
+
+interface RealtimeSubscription {
+  subscribe(listener: (event: DashboardEvent) => void): () => void;
+}
+
+const STORAGE_KEY = 'reddit-bot.notifications.v1';
+const MAX_NOTIFICATIONS = 50;
+const NotificationContext = createContext<NotificationContextValue | null>(null);
+const StoredNotificationsSchema = z.array(z.strictObject({
+  id: z.string(),
+  title: z.string(),
+  message: z.string(),
+  occurredAt: z.string(),
+  tone: z.enum(['info', 'success', 'warning', 'error']),
+  href: z.string().optional(),
+  isRead: z.boolean(),
+}));
+
+function notificationStorage(): Storage | undefined {
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+function titleCase(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1).replaceAll('-', ' ');
+}
+
+export function notificationForEvent(event: DashboardEvent): NotificationDraft | null {
+  switch (event.type) {
+    case 'reply.received':
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: `New reply from u/${event.payload.sender}`,
+        message: event.payload.preview?.trim() || 'A new message arrived in this conversation.',
+        tone: 'success',
+        href: `/conversations/${encodeURIComponent(event.payload.conversationId)}`,
+      };
+    case 'message.sent':
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: `Message sent to u/${event.payload.recipient}`,
+        message: 'The message was delivered successfully.',
+        tone: 'success',
+        href: event.payload.conversationId
+          ? `/conversations/${encodeURIComponent(event.payload.conversationId)}`
+          : '/conversations',
+      };
+    case 'message.failed':
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: `Message to u/${event.payload.recipient} failed`,
+        message: event.payload.reason,
+        tone: 'error',
+        href: event.payload.conversationId
+          ? `/conversations/${encodeURIComponent(event.payload.conversationId)}`
+          : '/operations',
+      };
+    case 'bot.status.changed':
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: `Bot ${event.payload.status}`,
+        message: event.payload.reason ?? `The bot is now ${event.payload.status}.`,
+        tone: event.payload.status === 'running' ? 'success' : event.payload.status === 'stopped' ? 'warning' : 'info',
+        href: '/operations',
+      };
+    case 'sync.completed':
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: `${titleCase(event.payload.kind)} sync complete`,
+        message: `${event.payload.processed.toLocaleString()} items processed.`,
+        tone: 'success',
+        href: '/operations',
+      };
+    case 'sync.failed':
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: `${titleCase(event.payload.kind)} sync failed`,
+        message: event.payload.reason,
+        tone: 'error',
+        href: '/operations',
+      };
+    case 'rate-limit.changed':
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: event.payload.limited ? 'Rate limit reached' : 'Rate limit cleared',
+        message: event.payload.reason ?? (event.payload.limited
+          ? 'Sending will resume when the limit resets.'
+          : 'The bot can send messages again.'),
+        tone: event.payload.limited ? 'warning' : 'success',
+        href: '/operations',
+      };
+    case 'reddit.session.changed':
+      if (!['authenticated', 'expired', 'logged-out', 'error'].includes(event.payload.status)) return null;
+      return {
+        id: event.id,
+        occurredAt: event.occurredAt,
+        title: event.payload.status === 'authenticated' ? 'Reddit account connected' : 'Reddit account needs attention',
+        message: event.payload.reason ?? (event.payload.username
+          ? `Signed in as u/${event.payload.username}.`
+          : `Session status changed to ${event.payload.status}.`),
+        tone: event.payload.status === 'authenticated' ? 'success' : 'error',
+        href: '/settings',
+      };
+    case 'conversation.updated':
+    case 'sync.started':
+    case 'sync.progress':
+    case 'log.created':
+      return null;
+  }
+}
+
+function loadNotifications(): NotificationItem[] {
+  const storage = notificationStorage();
+  if (!storage) return [];
+  try {
+    const value: unknown = JSON.parse(storage.getItem(STORAGE_KEY) ?? '[]');
+    const parsed = StoredNotificationsSchema.safeParse(value);
+    return parsed.success ? parsed.data.slice(0, MAX_NOTIFICATIONS) : [];
+  } catch {
+    return [];
+  }
+}
+
+export interface NotificationProviderProps extends PropsWithChildren {
+  realtime?: RealtimeSubscription;
+}
+
+export function NotificationProvider({ children, realtime: realtimeOverride }: NotificationProviderProps) {
+  const dashboardRealtime = useDashboardRealtime();
+  const realtime = realtimeOverride ?? dashboardRealtime;
+  const [isOpen, setIsOpenState] = useState(false);
+  const [notifications, setNotifications] = useState<NotificationItem[]>(loadNotifications);
+  const [toasts, setToasts] = useState<NotificationItem[]>([]);
+
+  const dismissToast = useCallback((id: string) => {
+    setToasts((current) => current.filter((toast) => toast.id !== id));
+  }, []);
+
+  const setOpen = useCallback((nextOpen: boolean) => {
+    setIsOpenState(nextOpen);
+    if (nextOpen) setNotifications((current) => current.map((item) => ({ ...item, isRead: true })));
+  }, []);
+
+  useEffect(() => {
+    try {
+      notificationStorage()?.setItem(STORAGE_KEY, JSON.stringify(notifications));
+    } catch {
+      // Storage can be unavailable in private or restricted browser contexts.
+    }
+  }, [notifications]);
+
+  useEffect(() => {
+    if (isOpen && notifications.some((item) => !item.isRead)) {
+      setNotifications((current) => current.map((item) => ({ ...item, isRead: true })));
+    }
+  }, [isOpen, notifications]);
+
+  useEffect(() => realtime.subscribe((event) => {
+    const draft = notificationForEvent(event);
+    if (!draft) return;
+    const item = { ...draft, isRead: false };
+    setNotifications((current) => current.some((entry) => entry.id === item.id)
+      ? current
+      : [item, ...current].slice(0, MAX_NOTIFICATIONS));
+    setToasts((current) => current.some((entry) => entry.id === item.id)
+      ? current
+      : [...current, item].slice(-3));
+  }), [realtime]);
+
+  useEffect(() => {
+    if (toasts.length === 0) return undefined;
+    const timers = toasts.map((toast) => globalThis.setTimeout(
+      () => dismissToast(toast.id),
+      toast.tone === 'error' ? 8_000 : 5_000,
+    ));
+    return () => timers.forEach((timer) => globalThis.clearTimeout(timer));
+  }, [dismissToast, toasts]);
+
+  useEffect(() => {
+    function closeOnEscape(event: KeyboardEvent): void {
+      if (event.key === 'Escape') setOpen(false);
+    }
+    globalThis.addEventListener('keydown', closeOnEscape);
+    return () => globalThis.removeEventListener('keydown', closeOnEscape);
+  }, [setOpen]);
+
+  const value = useMemo<NotificationContextValue>(() => ({
+    isOpen,
+    notifications,
+    toasts,
+    unreadCount: notifications.filter((item) => !item.isRead).length,
+    clearAll: () => setNotifications([]),
+    dismissToast,
+    setOpen,
+  }), [dismissToast, isOpen, notifications, setOpen, toasts]);
+
+  return <NotificationContext.Provider value={value}>{children}</NotificationContext.Provider>;
+}
+
+function useNotifications(): NotificationContextValue {
+  const context = useContext(NotificationContext);
+  if (!context) throw new Error('Notifications must be used within NotificationProvider');
+  return context;
+}
+
+function BellIcon() {
+  return (
+    <svg aria-hidden="true" viewBox="0 0 24 24">
+      <path d="M18 8a6 6 0 0 0-12 0c0 7-3 7-3 9h18c0-2-3-2-3-9M10 21h4" />
+    </svg>
+  );
+}
+
+export function NotificationBell({ className = '' }: { className?: string }) {
+  const { isOpen, setOpen, unreadCount } = useNotifications();
+  return (
+    <button
+      aria-controls="notification-centre"
+      aria-expanded={isOpen}
+      aria-label={unreadCount > 0 ? `Notifications, ${unreadCount} unread` : 'Notifications'}
+      className={`notification-bell ${className}`.trim()}
+      onClick={() => setOpen(!isOpen)}
+      type="button"
+    >
+      <BellIcon />
+      {unreadCount > 0 ? <span className="notification-badge">{unreadCount > 99 ? '99+' : unreadCount}</span> : null}
+    </button>
+  );
+}
+
+function formattedTime(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return '';
+  return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(date);
+}
+
+function NotificationContent({ item }: { item: NotificationItem }) {
+  return (
+    <>
+      <span className={`notification-signal ${item.tone}`} aria-hidden="true" />
+      <span className="notification-copy">
+        <strong>{item.title}</strong>
+        <span>{item.message}</span>
+        <time dateTime={item.occurredAt}>{formattedTime(item.occurredAt)}</time>
+      </span>
+    </>
+  );
+}
+
+export function NotificationViewport() {
+  const { clearAll, dismissToast, isOpen, notifications, setOpen, toasts } = useNotifications();
+  return (
+    <>
+      {isOpen ? <button aria-label="Close notifications" className="notification-backdrop" onClick={() => setOpen(false)} type="button" /> : null}
+      <aside aria-label="Notifications" className={isOpen ? 'notification-centre is-open' : 'notification-centre'} id="notification-centre">
+        <header>
+          <div>
+            <span className="eyebrow">Activity inbox</span>
+            <h2>Notifications</h2>
+          </div>
+          <button aria-label="Close notification centre" className="notification-close" onClick={() => setOpen(false)} type="button">×</button>
+        </header>
+        {notifications.length > 0 ? (
+          <>
+            <ol className="notification-list">
+              {notifications.map((item) => (
+                <li key={item.id}>
+                  {item.href ? (
+                    <Link className="notification-entry" onClick={() => setOpen(false)} to={item.href}>
+                      <NotificationContent item={item} />
+                    </Link>
+                  ) : <div className="notification-entry"><NotificationContent item={item} /></div>}
+                </li>
+              ))}
+            </ol>
+            <footer><button className="notification-clear" onClick={clearAll} type="button">Clear all</button></footer>
+          </>
+        ) : (
+          <div className="notification-empty">
+            <span aria-hidden="true"><BellIcon /></span>
+            <strong>All quiet</strong>
+            <p>Replies, delivery updates, syncs, and account alerts will appear here.</p>
+          </div>
+        )}
+      </aside>
+      <div aria-atomic="false" aria-live="polite" className="toast-stack">
+        {toasts.map((toast) => (
+          <div className={`notification-toast ${toast.tone}`} key={toast.id} role={toast.tone === 'error' ? 'alert' : 'status'}>
+            {toast.href ? (
+              <Link onClick={() => dismissToast(toast.id)} to={toast.href}><NotificationContent item={toast} /></Link>
+            ) : <div><NotificationContent item={toast} /></div>}
+            <button aria-label={`Dismiss ${toast.title}`} onClick={() => dismissToast(toast.id)} type="button">×</button>
+          </div>
+        ))}
+      </div>
+    </>
+  );
+}

apps/dashboard/src/app/providers.tsx

@@ -1,5 +1,6 @@
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import type { PropsWithChildren } from 'react';
+import { DashboardRealtimeProvider } from './realtime-provider.js';
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -13,5 +14,5 @@ const queryClient = new QueryClient({
 });
 
 export function AppProviders({ children }: PropsWithChildren) {
-  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+  return <QueryClientProvider client={queryClient}><DashboardRealtimeProvider>{children}</DashboardRealtimeProvider></QueryClientProvider>;
 }

apps/dashboard/src/app/realtime-provider.tsx

@@ -0,0 +1,45 @@
+import { useQueryClient } from '@tanstack/react-query';
+import { createContext, useContext, useEffect, useMemo, useRef, useState, type PropsWithChildren } from 'react';
+import type { DashboardEvent } from '../../../../packages/api-contracts/src/index.js';
+import {
+  createBrowserEventSource, createDashboardRealtimeClient, queryKeysForDashboardEvent,
+  type RealtimeConnectionSnapshot,
+} from '../features/operations/realtime-client.js';
+import { browserPollingScheduler, browserVisibilitySource, createVisibilityAwarePollingFallback } from '../features/operations/realtime-fallback.js';
+import { repairRealtimeSnapshots } from './realtime-repair.js';
+
+type EventListener = (event: DashboardEvent) => void;
+interface RealtimeContextValue { connection: RealtimeConnectionSnapshot; subscribe(listener: EventListener): () => void; }
+const RealtimeContext = createContext<RealtimeContextValue | null>(null);
+
+export function DashboardRealtimeProvider({ children }: PropsWithChildren) {
+  const queryClient = useQueryClient();
+  const listeners = useRef(new Set<EventListener>());
+  const [connection, setConnection] = useState<RealtimeConnectionSnapshot>({ status: 'idle', isStale: true });
+  useEffect(() => {
+    const repair = () => { void repairRealtimeSnapshots(queryClient); };
+    const fallback = createVisibilityAwarePollingFallback({ intervalMs: 15_000, poll: repair, scheduler: browserPollingScheduler, visibility: browserVisibilitySource });
+    fallback.start();
+    if (typeof EventSource === 'undefined') { fallback.setStale(true); return () => fallback.stop(); }
+    const client = createDashboardRealtimeClient({
+      sourceFactory: createBrowserEventSource,
+      onConnected: repair,
+      onEvent(event) {
+        for (const queryKey of queryKeysForDashboardEvent(event)) void queryClient.invalidateQueries({ queryKey });
+        for (const listener of listeners.current) listener(event);
+      },
+      onStateChange(snapshot) { setConnection(snapshot); fallback.setStale(snapshot.isStale); },
+    });
+    client.start();
+    return () => { client.stop(); fallback.stop(); };
+  }, [queryClient]);
+  const value = useMemo<RealtimeContextValue>(() => ({
+    connection,
+    subscribe(listener) { listeners.current.add(listener); return () => listeners.current.delete(listener); },
+  }), [connection]);
+  return <RealtimeContext.Provider value={value}>{children}</RealtimeContext.Provider>;
+}
+
+export function useDashboardRealtime(): RealtimeContextValue {
+  return useContext(RealtimeContext) ?? { connection: { status: 'idle', isStale: true }, subscribe: () => () => undefined };
+}

apps/dashboard/src/app/realtime-repair.ts

@@ -0,0 +1,26 @@
+import type { QueryKey } from '@tanstack/react-query';
+import { dashboardQueryKeys } from '../api/queries.js';
+import { operationsQueryKeys } from '../features/operations/operations-queries.js';
+import { settingsQueryKeys } from '../features/settings/settings-queries.js';
+
+export const realtimeSnapshotKeys: readonly QueryKey[] = [
+  dashboardQueryKeys.stats,
+  dashboardQueryKeys.timers,
+  settingsQueryKeys.loginStatus,
+  operationsQueryKeys.syncStatus,
+  ['conversations'],
+  ['media'],
+  ['performance'],
+];
+
+export interface RealtimeQueryRepairTarget {
+  invalidateQueries(filters: { queryKey: QueryKey; refetchType: 'none' }): Promise<unknown>;
+  refetchQueries(filters: { queryKey: QueryKey; type: 'active' }): Promise<unknown>;
+}
+
+export async function repairRealtimeSnapshots(target: RealtimeQueryRepairTarget): Promise<void> {
+  await Promise.all(realtimeSnapshotKeys.map(async (queryKey) => {
+    await target.invalidateQueries({ queryKey, refetchType: 'none' });
+    await target.refetchQueries({ queryKey, type: 'active' });
+  }));
+}

apps/dashboard/src/app/route-error-page.tsx

@@ -0,0 +1,7 @@
+import { isRouteErrorResponse, useRouteError } from 'react-router-dom';
+
+export function RouteErrorPage() {
+  const error = useRouteError();
+  const message = isRouteErrorResponse(error) ? `${error.status} ${error.statusText}` : error instanceof Error ? error.message : 'Unexpected route failure';
+  return <main className="page-state error-state" role="alert"><strong>This page could not be loaded</strong><span>{message}</span><a className="button secondary" href="/">Return to overview</a></main>;
+}

apps/dashboard/src/app/router.tsx

@@ -2,21 +2,29 @@ import { createBrowserRouter, type RouteObject } from 'react-router-dom';
 import { AppShell } from './app-shell.js';
 import { OverviewPage } from '../features/overview/overview-page.js';
 import { ConversationRoute } from '../features/conversations/conversation-route.js';
-import { MediaPage } from '../features/media/media-page.js';
+import { MediaRoute } from '../features/media/media-route.js';
 import { OperationsPage } from '../features/operations/operations-page.js';
 import { PerformancePage } from '../features/performance/performance-page.js';
 import { SettingsRoute } from '../features/settings/settings-route.js';
+import { RouteErrorPage } from './route-error-page.js';
+import { AttentionPage } from '../features/attention/attention-page.js';
+import { OutreachPage } from '../features/outreach/outreach-page.js';
+import { MediaLibraryPage } from '../features/media-library/media-library-page.js';
 
 export function createDashboardRoutes(): RouteObject[] {
   return [
     {
       path: '/',
       element: <AppShell />,
+      errorElement: <RouteErrorPage />,
       children: [
         { index: true, element: <OverviewPage /> },
+        { path: 'attention', element: <AttentionPage /> },
+        { path: 'outreach', element: <OutreachPage /> },
         { path: 'conversations', element: <ConversationRoute /> },
         { path: 'conversations/:conversationId', element: <ConversationRoute /> },
-        { path: 'media', element: <MediaPage /> },
+        { path: 'media', element: <MediaRoute /> },
+        { path: 'media-library', element: <MediaLibraryPage /> },
         { path: 'performance', element: <PerformancePage /> },
         { path: 'operations', element: <OperationsPage /> },
         { path: 'settings', element: <SettingsRoute /> },

apps/dashboard/src/app/shell-status-panel.css

@@ -0,0 +1,4 @@
+.shell-status { display: grid; gap: .45rem; margin: 1rem .5rem; padding: .8rem; color: var(--muted); background: var(--surface); border: 1px solid var(--border); border-radius: .75rem; font-size: .75rem; }
+.shell-status strong { color: #e9f1ec; }
+.shell-status .button { margin-top: .3rem; }
+.shell-warning { color: var(--warning); }

apps/dashboard/src/app/shell-status-panel.tsx

@@ -0,0 +1,26 @@
+import { useState } from 'react';
+import { useStatsQuery, useSetRunningMutation } from '../api/queries.js';
+import { ConfirmationDialog } from '../components/confirmation-dialog.js';
+import { useSyncStatusQuery } from '../features/operations/operations-queries.js';
+import { useLoginStatusQuery } from '../features/settings/settings-queries.js';
+import { useDashboardRealtime } from './realtime-provider.js';
+import { deriveShellStatus } from './shell-status.js';
+import './shell-status-panel.css';
+
+export function ShellStatusPanel() {
+  const stats = useStatsQuery();
+  const reddit = useLoginStatusQuery();
+  const sync = useSyncStatusQuery();
+  const realtime = useDashboardRealtime();
+  const control = useSetRunningMutation();
+  const [confirming, setConfirming] = useState<'start' | 'stop' | null>(null);
+  const status = deriveShellStatus({ stats: stats.data, reddit: reddit.data, sync: sync.data, realtime: realtime.connection });
+  return <>
+    <section aria-label="Platform status" className="shell-status">
+      <strong>{status.bot}</strong><span>{status.reddit}</span><span>{status.realtime}</span><span>{status.sync}</span>
+      {status.cooldown ? <span className="shell-warning">Cooldown: {status.cooldown}</span> : null}
+      <button aria-label={`${status.controlAction === 'start' ? 'Start' : 'Stop'} bot from global status`} className={status.controlAction === 'start' ? 'button primary' : 'button danger'} disabled={status.controlDisabled || control.isPending} onClick={() => setConfirming(status.controlAction)} type="button">{status.controlAction === 'start' ? 'Start bot' : 'Stop bot'}</button>
+    </section>
+    {confirming ? <ConfirmationDialog action={confirming} isPending={control.isPending} onCancel={() => setConfirming(null)} onConfirm={() => control.mutate(confirming === 'start', { onSuccess: () => setConfirming(null) })} /> : null}
+  </>;
+}

apps/dashboard/src/app/shell-status.ts

@@ -0,0 +1,39 @@
+import type { RealtimeConnectionSnapshot } from '../features/operations/realtime-client.js';
+
+interface ShellStatusInput {
+  stats?: { isRunning: boolean; dryRunMode: boolean; invitationCooldown: { reason: string } | null };
+  reddit?: { ready: boolean; loggedIn?: boolean; status?: string; error?: string };
+  realtime: RealtimeConnectionSnapshot;
+  sync?: { syncing: boolean; syncingKind?: string | null };
+}
+
+export interface ShellStatus {
+  bot: string;
+  reddit: string;
+  realtime: string;
+  cooldown: string | null;
+  sync: string;
+  controlAction: 'start' | 'stop';
+  controlDisabled: boolean;
+}
+
+function sentence(value: string): string { return value.charAt(0).toUpperCase() + value.slice(1); }
+
+export function deriveShellStatus(input: ShellStatusInput): ShellStatus {
+  const stats = input.stats;
+  const realtime = input.realtime.status === 'connected'
+    ? 'Realtime connected'
+    : `Realtime ${input.realtime.status}${input.realtime.isStale ? ' (stale)' : ''}`;
+  const reddit = input.reddit?.ready
+    ? input.reddit.loggedIn ? `Reddit ${input.reddit.status ?? 'authenticated'}` : 'Reddit login required'
+    : 'Reddit session unavailable';
+  return {
+    bot: stats ? `${stats.isRunning ? 'Running' : 'Stopped'}${stats.dryRunMode ? ' (dry run)' : ''}` : 'Bot state unavailable',
+    reddit,
+    realtime,
+    cooldown: stats?.invitationCooldown?.reason ?? null,
+    sync: input.sync?.syncing ? `${sentence(input.sync.syncingKind ?? 'unknown')} sync active` : 'No active sync',
+    controlAction: stats?.isRunning ? 'stop' : 'start',
+    controlDisabled: stats === undefined,
+  };
+}

apps/dashboard/src/components/account-owner-badge.tsx

@@ -0,0 +1,11 @@
+import type { RedditAccountOwner } from '../../../../packages/api-contracts/src/index.js';
+import { RedditUsernameLink } from './reddit-username-link.js';
+
+export function AccountOwnerBadge({ owner }: { owner?: RedditAccountOwner }) {
+  return (
+    <span className={owner ? 'account-owner-badge' : 'account-owner-badge is-unassigned'}>
+      <span aria-hidden="true">Account</span>
+      {owner ? <RedditUsernameLink username={owner.redditUsername} /> : <strong>Unassigned legacy content</strong>}
+    </span>
+  );
+}

apps/dashboard/src/components/confirmation-dialog.tsx

@@ -1,23 +1,18 @@
-import { useEffect, useRef } from 'react';
+import { Modal } from './modal.js';
 
 interface ConfirmationDialogProps {
   action: 'start' | 'stop';
+  errorMessage?: string | null;
   isPending: boolean;
   onCancel(): void;
   onConfirm(): void;
 }
 
-export function ConfirmationDialog({ action, isPending, onCancel, onConfirm }: ConfirmationDialogProps) {
-  const cancelButtonRef = useRef<HTMLButtonElement>(null);
+export function ConfirmationDialog({ action, errorMessage = null, isPending, onCancel, onConfirm }: ConfirmationDialogProps) {
   const isStarting = action === 'start';
 
-  useEffect(() => {
-    cancelButtonRef.current?.focus();
-  }, []);
-
   return (
-    <div aria-labelledby="confirmation-title" aria-modal="true" className="dialog-backdrop" role="dialog">
-      <div className="dialog-card">
+    <Modal className="dialog-card" isDismissLocked={isPending} labelledBy="confirmation-title" onClose={onCancel}>
       <span className="eyebrow">Confirm action</span>
       <h2 id="confirmation-title">{isStarting ? 'Start bot?' : 'Stop bot?'}</h2>
       <p>
@@ -25,15 +20,15 @@ export function ConfirmationDialog({ action, isPending, onCancel, onConfirm }: C
           ? 'The bot will resume automated processing.'
           : 'The bot will pause after its current operation.'}
       </p>
+      {errorMessage ? <p className="dialog-error" role="alert">{errorMessage}</p> : null}
       <div className="dialog-actions">
-          <button className="button secondary" disabled={isPending} onClick={onCancel} ref={cancelButtonRef} type="button">
+        <button autoFocus className="button secondary" disabled={isPending} onClick={onCancel} type="button">
           Cancel
         </button>
         <button className={isStarting ? 'button primary' : 'button danger'} disabled={isPending} onClick={onConfirm} type="button">
           {isPending ? 'Applying…' : `Confirm ${action}`}
         </button>
       </div>
-      </div>
-    </div>
+    </Modal>
   );
 }

apps/dashboard/src/components/modal.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useRef, useState, type PropsWithChildren, type ReactNode } from 'react';
+
+interface ModalProps {
+  /** Class applied to the <dialog> element itself (it is the visible card). */
+  className?: string;
+  /** Blocks Escape/backdrop dismissal while a mutation is in flight. */
+  isDismissLocked?: boolean;
+  /** Close when the backdrop (the ::backdrop area of the dialog) is pressed. */
+  closeOnBackdrop?: boolean;
+  label?: string;
+  labelledBy?: string;
+  onClose(): void;
+}
+
+/**
+ * Shared modal built on native <dialog>.showModal(): the browser provides
+ * focus trapping, inert background, and Escape handling. Render conditionally;
+ * mounting opens the dialog and unmounting restores focus to the opener.
+ */
+export function Modal({
+  children,
+  className,
+  closeOnBackdrop = false,
+  isDismissLocked = false,
+  label,
+  labelledBy,
+  onClose,
+}: PropsWithChildren<ModalProps>): ReactNode {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+  const dismissLockedRef = useRef(isDismissLocked);
+  dismissLockedRef.current = isDismissLocked;
+
+  // Captured at first render, before autoFocus moves focus into the dialog.
+  const [previouslyFocused] = useState(() => document.activeElement);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (!dialog.open) {
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    }
+    return () => {
+      if (previouslyFocused instanceof HTMLElement && previouslyFocused.isConnected) {
+        previouslyFocused.focus();
+      }
+    };
+  }, [previouslyFocused]);
+
+  function requestClose(): void {
+    if (!dismissLockedRef.current) onCloseRef.current();
+  }
+
+  return (
+    <dialog
+      aria-label={label}
+      aria-labelledby={labelledBy}
+      className={className ? `modal ${className}` : 'modal'}
+      onCancel={(event) => {
+        event.preventDefault();
+        requestClose();
+      }}
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          event.preventDefault();
+          requestClose();
+        }
+      }}
+      onMouseDown={(event) => {
+        if (closeOnBackdrop && event.target === event.currentTarget) requestClose();
+      }}
+      ref={dialogRef}
+    >
+      {children}
+    </dialog>
+  );
+}

apps/dashboard/src/components/origin-post.tsx

@@ -0,0 +1,125 @@
+import { useState, type ReactNode } from 'react';
+import { Modal } from './modal.js';
+
+export interface OriginPost {
+  title: string;
+  url: string;
+  imageUrl?: string | null;
+  subreddit?: string;
+  postedAt?: number;
+}
+
+export function formatPostAge(postedAt: number, now = Date.now()): string {
+  const elapsedSeconds = Math.max(0, Math.floor((now - postedAt) / 1000));
+  if (elapsedSeconds < 60) return 'now';
+  const elapsedMinutes = Math.floor(elapsedSeconds / 60);
+  if (elapsedMinutes < 60) return `${elapsedMinutes}m ago`;
+  const elapsedHours = Math.floor(elapsedMinutes / 60);
+  if (elapsedHours < 24) return `${elapsedHours}h ago`;
+  const elapsedDays = Math.floor(elapsedHours / 24);
+  if (elapsedDays < 30) return `${elapsedDays}d ago`;
+  const elapsedMonths = Math.floor(elapsedDays / 30);
+  if (elapsedMonths < 12) return `${elapsedMonths}mo ago`;
+  return `${Math.floor(elapsedMonths / 12)}y ago`;
+}
+
+function PostOriginMeta({ post }: { post: OriginPost }) {
+  return (
+    <small>
+      Started from {post.subreddit ? `r/${post.subreddit}` : 'Reddit'}
+      {post.postedAt ? (
+        <> · <time dateTime={new Date(post.postedAt).toISOString()} title={new Date(post.postedAt).toLocaleString()}>{formatPostAge(post.postedAt)}</time></>
+      ) : null}
+    </small>
+  );
+}
+
+export function OriginPostCard({ post }: { post: OriginPost }) {
+  const [isImageRevealed, setIsImageRevealed] = useState(false);
+  const [isImagePreviewOpen, setIsImagePreviewOpen] = useState(false);
+
+  return (
+    <>
+      <div className="origin-post-card">
+        {post.imageUrl ? (
+          <div className="origin-post-image">
+            <button
+              aria-label={isImageRevealed
+                ? `View source image full screen: ${post.title}`
+                : `Reveal source image: ${post.title}`}
+              className="origin-post-image-preview-trigger"
+              onClick={() => {
+                if (isImageRevealed) setIsImagePreviewOpen(true);
+                else setIsImageRevealed(true);
+              }}
+              type="button"
+            >
+              <img alt={`Source post: ${post.title}`} className={isImageRevealed ? undefined : 'is-blurred'} loading="lazy" src={post.imageUrl} />
+            </button>
+            <button
+              aria-pressed={isImageRevealed}
+              className="origin-post-image-reveal"
+              onClick={() => setIsImageRevealed((current) => !current)}
+              type="button"
+            >
+              {isImageRevealed ? 'Blur original image' : 'Reveal original image'}
+            </button>
+          </div>
+        ) : null}
+        <a aria-label={post.title} className="origin-post-copy" href={post.url} rel="noreferrer" target="_blank">
+          <PostOriginMeta post={post} />
+          <strong>{post.title}</strong>
+          <span>Open original post <span aria-hidden="true">↗</span></span>
+        </a>
+      </div>
+      {isImagePreviewOpen && post.imageUrl ? (
+        <Modal
+          className="origin-image-preview"
+          closeOnBackdrop
+          label={`Source image: ${post.title}`}
+          onClose={() => setIsImagePreviewOpen(false)}
+        >
+          <div className="origin-image-preview-content">
+            <img alt={`Source post: ${post.title}`} src={post.imageUrl} />
+            <button aria-label="Close source image preview" autoFocus onClick={() => setIsImagePreviewOpen(false)} type="button">×</button>
+          </div>
+        </Modal>
+      ) : null}
+    </>
+  );
+}
+
+export function OriginPostButton({ children, post }: { children: ReactNode; post: OriginPost }) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button className="origin-post-trigger" onClick={() => setIsOpen(true)} type="button">
+        {children}
+      </button>
+      {isOpen ? (
+        <Modal
+          className="origin-post-dialog"
+          closeOnBackdrop
+          labelledBy="origin-post-dialog-title"
+          onClose={() => setIsOpen(false)}
+        >
+          <article>
+            <div className="origin-post-dialog-heading">
+              <span>Conversation origin</span>
+              <button aria-label="Close source post" autoFocus onClick={() => setIsOpen(false)} type="button">×</button>
+            </div>
+            {post.imageUrl ? <img alt={`Source post: ${post.title}`} loading="lazy" src={post.imageUrl} /> : null}
+            <div className="origin-post-dialog-copy">
+              <PostOriginMeta post={post} />
+              <h2 id="origin-post-dialog-title">{post.title}</h2>
+              <a className="button primary" href={post.url} rel="noreferrer" target="_blank">
+                Open Reddit post <span aria-hidden="true">↗</span><span className="sr-only">(opens in a new tab)</span>
+              </a>
+            </div>
+          </article>
+        </Modal>
+      ) : null}
+    </>
+  );
+}

apps/dashboard/src/components/reddit-user-text.tsx

@@ -0,0 +1,16 @@
+import { Fragment } from 'react';
+import { RedditUsernameLink } from './reddit-username-link.js';
+
+const USER_MENTION = /(u\/[A-Za-z0-9_-]+|@?t2_[A-Za-z0-9]+(?::reddit\.com)?)/gi;
+
+export function RedditUserText({ children }: { children: string }) {
+  return children.split(USER_MENTION).map((part, index) => {
+    if (/^u\/(?!t2_)[A-Za-z0-9_-]+$/i.test(part)) {
+      return <RedditUsernameLink key={`${part}-${index}`} username={part} />;
+    }
+    if (/^(?:@?t2_)/i.test(part) || /^u\/t2_/i.test(part)) {
+      return <Fragment key={`${part}-${index}`}>Reddit user</Fragment>;
+    }
+    return <Fragment key={`${part}-${index}`}>{part}</Fragment>;
+  });
+}

apps/dashboard/src/components/reddit-username-link.tsx

@@ -0,0 +1,42 @@
+export interface RedditUsernameLinkProps {
+  username: string;
+  showPrefix?: boolean;
+}
+
+export function normalizeRedditUsername(username: string): string {
+  return username.trim().replace(/^\/?u\//i, '');
+}
+
+export function isDisplayableRedditUsername(username: string): boolean {
+  const normalized = normalizeRedditUsername(username);
+  return normalized.length > 0
+    && !/^(?:me|you|unknown|unknown reddit user)$/i.test(normalized)
+    && !/^t2_/i.test(normalized)
+    && !/^@t2_/i.test(normalized);
+}
+
+export function redditUsernameLabel(username: string, showPrefix = true): string {
+  if (!isDisplayableRedditUsername(username)) return 'Unknown Reddit user';
+  const normalized = normalizeRedditUsername(username);
+  return showPrefix ? `u/${normalized}` : normalized;
+}
+
+export function RedditUsernameLink({ username, showPrefix = true }: RedditUsernameLinkProps) {
+  const normalizedUsername = normalizeRedditUsername(username);
+  const label = redditUsernameLabel(username, showPrefix);
+
+  if (!isDisplayableRedditUsername(username)) {
+    return <span className="reddit-username-link is-unresolved">{label}</span>;
+  }
+
+  return (
+    <a
+      className="reddit-username-link"
+      href={`https://www.reddit.com/u/${encodeURIComponent(normalizedUsername)}`}
+      rel="noreferrer"
+      target="_blank"
+    >
+      {label}
+    </a>
+  );
+}

apps/dashboard/src/features/attention/attention-api.ts

@@ -0,0 +1,16 @@
+import { AttentionResponseSchema } from '../../../../../packages/api-contracts/src/index.js';
+import { createDashboardRequest } from '../../api/request.js';
+
+export function createAttentionApi(fetchImplementation?: typeof fetch) {
+  const request = createDashboardRequest(fetchImplementation);
+  return {
+    async getAttention() {
+      const response = await request('/api/attention');
+      const payload: unknown = await response.json();
+      if (!response.ok) throw new Error(`Attention inbox unavailable (${response.status})`);
+      return AttentionResponseSchema.parse(payload);
+    },
+  };
+}
+
+export const attentionApi = createAttentionApi();

apps/dashboard/src/features/attention/attention-page.tsx

@@ -0,0 +1,86 @@
+import { useQuery } from '@tanstack/react-query';
+import { Link } from 'react-router-dom';
+import type { AttentionItem } from '../../../../../packages/api-contracts/src/index.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
+import { formatExactTime, formatShortRelativeTime } from '../conversations/relative-time.js';
+import { attentionApi } from './attention-api.js';
+import './attention.css';
+
+function relativeTime(timestamp: number, now: number) {
+  return (
+    <time dateTime={new Date(timestamp).toISOString()} title={formatExactTime(timestamp)}>
+      {formatShortRelativeTime(timestamp, now)}
+    </time>
+  );
+}
+
+function actionHint(kind: AttentionItem['kind']): string {
+  switch (kind) {
+    case 'account-login-required':
+      return 'No linked conversation — check Settings.';
+    case 'runtime-failed':
+    case 'invitation-cooldown':
+    default:
+      return 'No linked conversation — check Operations.';
+  }
+}
+
+function itemAction(item: AttentionItem) {
+  if (!item.conversationId) return <span className="attention-item-hint">{actionHint(item.kind)}</span>;
+  return <Link className="button secondary" to={`/conversations/${encodeURIComponent(item.conversationId)}`}>Open conversation</Link>;
+}
+
+export function AttentionPage() {
+  const query = useQuery({ queryKey: ['attention'], queryFn: attentionApi.getAttention, refetchInterval: 30_000 });
+  if (query.isPending) return <div className="page-state" role="status">Loading attention inbox…</div>;
+  if (query.isError) return <div className="page-state error-state" role="alert"><strong>Attention inbox unavailable</strong><span>{query.error.message}</span><button className="button secondary" onClick={() => void query.refetch()} type="button">Retry</button></div>;
+  const now = Date.now();
+  const critical = query.data.items.filter((item) => item.severity === 'critical').length;
+  return (
+    <div className="page attention-page">
+      <header className="page-header">
+        <div>
+          <span className="eyebrow">Operator queue</span>
+          <h1>Needs attention</h1>
+          <p>Boundaries, human handoffs, delivery failures, account problems, and Reddit cooldowns in one actionable inbox.</p>
+        </div>
+        <div className="attention-refresh">
+          <button
+            aria-busy={query.isFetching || undefined}
+            className="button secondary"
+            disabled={query.isFetching}
+            onClick={() => void query.refetch()}
+            type="button"
+          >
+            {query.isFetching ? 'Refreshing…' : 'Refresh'}
+          </button>
+          <span className="attention-refresh-note">Auto-refreshes every 30s</span>
+        </div>
+      </header>
+      <section aria-label="Attention totals" className="status-strip">
+        <div>
+          <span aria-hidden="true" className={`attention-status-dot ${query.data.items.length === 0 ? 'is-clear' : 'is-open'}`} />
+          <div><small>Open items</small><strong>{query.data.items.length}</strong></div>
+        </div>
+        <span className={critical > 0 ? 'pill danger' : 'pill success'}>{critical} critical</span>
+        <span className="status-note">Updated {relativeTime(query.data.generatedAt, now)}</span>
+      </section>
+      {query.data.items.length === 0 ? <div className="empty-state panel"><strong>Nothing needs attention.</strong><span>Automation and account health have no outstanding operator items.</span></div> : (
+        <ol aria-label="Attention items" className="attention-list">{query.data.items.map((item) => (
+          <li className={`attention-item is-${item.severity}`} key={item.id}>
+            <div className="attention-item-heading">
+              <div>
+                <span className={`pill ${item.severity === 'critical' ? 'danger' : 'warning'}`}>{item.kind.replaceAll('-', ' ')}</span>
+                <h2>{item.title}</h2>
+              </div>
+              {relativeTime(item.occurredAt, now)}
+            </div>
+            <p>{item.detail}</p>
+            {item.owner ? <AccountOwnerBadge owner={item.owner} /> : null}
+            {itemAction(item)}
+          </li>
+        ))}</ol>
+      )}
+    </div>
+  );
+}

apps/dashboard/src/features/attention/attention.css

@@ -0,0 +1,14 @@
+.attention-list { display: grid; gap: .8rem; padding: 0; margin: 0; list-style: none; }
+.attention-item { display: grid; gap: .8rem; padding: 1rem; background: var(--surface); border: 1px solid var(--border); border-left: .3rem solid var(--warning); border-radius: .9rem; }
+.attention-item.is-critical { border-left-color: var(--danger); }
+.attention-item-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 1rem; }
+.attention-item-heading > div { display: grid; gap: .55rem; }
+.attention-item-heading time { color: var(--muted); font-size: .8rem; text-align: right; }
+.attention-item p { margin: 0; color: var(--muted); }
+.attention-item .button { justify-self: start; text-decoration: none; }
+.attention-item-hint { justify-self: start; color: var(--muted); font-size: .82rem; font-style: italic; }
+.attention-refresh { display: grid; gap: .3rem; justify-items: end; }
+.attention-refresh-note { color: var(--muted); font-size: .72rem; }
+.attention-status-dot { width: .7rem; height: .7rem; border-radius: 50%; }
+.attention-status-dot.is-clear { background: var(--success-text); box-shadow: 0 0 0 .35rem rgba(170, 240, 196, .12); }
+.attention-status-dot.is-open { background: var(--danger); box-shadow: 0 0 0 .35rem rgba(255, 138, 132, .1); }

apps/dashboard/src/features/conversations/composer-drafts.ts

@@ -0,0 +1,19 @@
+/**
+ * In-memory store of composer drafts keyed by conversation id, so switching
+ * conversations and back restores what the operator was typing.
+ */
+const drafts = new Map<string, string>();
+
+export function getStoredComposerDraft(conversationId: string): string {
+  return drafts.get(conversationId) ?? '';
+}
+
+export function storeComposerDraft(conversationId: string, draft: string): void {
+  if (draft.length === 0) drafts.delete(conversationId);
+  else drafts.set(conversationId, draft);
+}
+
+/** Test helper: clear all stored drafts between test cases. */
+export function resetComposerDrafts(): void {
+  drafts.clear();
+}

apps/dashboard/src/features/conversations/conversation-api.ts

@@ -2,16 +2,22 @@ import type { ZodType } from 'zod';
 import {
   ConversationsResponseSchema,
   ConversationDetailResponseSchema,
+  ConversationMediaShareOptionsResponseSchema,
   ErrorResponseSchema,
+  ProcessedPostsResponseSchema,
   SendReplyRequestSchema,
+  ShareConversationMediaRequestSchema,
   StartConversationRequestSchema,
   StartConversationResponseSchema,
   SuccessResponseSchema,
   SuggestedReplyResponseSchema,
   type ActiveChat,
   type ConversationDetailResponse,
+  type ConversationMediaShareOptions,
+  type ProcessedPost,
   type SuccessResponse,
 } from '../../../../../packages/api-contracts/src/index.js';
+import { createDashboardRequest } from '../../api/request.js';
 
 async function parseResponse<T>(response: Response, schema: ZodType<T>): Promise<T> {
   const payload: unknown = await response.json();
@@ -30,18 +36,23 @@ export interface ConversationApi {
   list(): Promise<ActiveChat[]>;
   detail(id: string): Promise<ConversationDetailResponse>;
   suggestReply(id: string): Promise<string>;
+  suggestMediaAsk(id: string): Promise<string>;
+  mediaShareOptions(id: string): Promise<ConversationMediaShareOptions>;
+  processedPosts(username: string): Promise<ProcessedPost[]>;
   sendReply(id: string, message: string): Promise<SuccessResponse>;
-  startConversation(username: string, message: string): Promise<ActiveChat>;
+  shareMedia(id: string, assetId: string): Promise<SuccessResponse>;
+  startConversation(accountId: string, username: string, message: string): Promise<ActiveChat>;
 }
 
 export function createConversationApi(fetchImplementation?: typeof fetch): ConversationApi {
-  function request(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
-    return (fetchImplementation ?? globalThis.fetch)(input, init);
-  }
+  const request = createDashboardRequest(fetchImplementation);
 
   return {
     async list() {
-      return parseResponse(await request('/api/conversations'), ConversationsResponseSchema);
+      return parseResponse(
+        await request('/api/conversations?includeImageMetadata=true'),
+        ConversationsResponseSchema,
+      );
     },
     async detail(id) {
       return parseResponse(await request(conversationPath(id)), ConversationDetailResponseSchema);
@@ -53,6 +64,25 @@ export function createConversationApi(fetchImplementation?: typeof fetch): Conve
       );
       return response.suggestedReply;
     },
+    async suggestMediaAsk(id) {
+      const response = await parseResponse(
+        await request(`${conversationPath(id)}/suggest-media-ask`, { method: 'POST' }),
+        SuggestedReplyResponseSchema,
+      );
+      return response.suggestedReply;
+    },
+    async mediaShareOptions(id) {
+      return parseResponse(
+        await request(`${conversationPath(id)}/shareable-media`),
+        ConversationMediaShareOptionsResponseSchema,
+      );
+    },
+    async processedPosts(username) {
+      return parseResponse(
+        await request(`/api/posts/by-author/${encodeURIComponent(username.trim().replace(/^u\//i, ''))}`),
+        ProcessedPostsResponseSchema,
+      );
+    },
     async sendReply(id, message) {
       const body = SendReplyRequestSchema.parse({ message: message.trim() });
       return parseResponse(
@@ -64,8 +94,20 @@ export function createConversationApi(fetchImplementation?: typeof fetch): Conve
         SuccessResponseSchema,
       );
     },
-    async startConversation(username, message) {
+    async shareMedia(id, assetId) {
+      const body = ShareConversationMediaRequestSchema.parse({ assetId });
+      return parseResponse(
+        await request(`${conversationPath(id)}/share-media`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+        }),
+        SuccessResponseSchema,
+      );
+    },
+    async startConversation(accountId, username, message) {
       const body = StartConversationRequestSchema.parse({
+        accountId,
         username: username.trim().replace(/^u\//i, ''),
         message: message.trim(),
       });

apps/dashboard/src/features/conversations/conversation-detail.tsx

@@ -1,67 +1,219 @@
-import { useCallback, useRef, useState } from 'react';
-import type { ConversationDetailResponse } from '../../../../../packages/api-contracts/src/index.js';
-import { useConversationDetailQuery, useSendReplyMutation, useSuggestReplyMutation } from './conversation-queries.js';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { ConversationDetailResponse, MediaLibraryAsset } from '../../../../../packages/api-contracts/src/index.js';
+import { RedditUsernameLink, redditUsernameLabel } from '../../components/reddit-username-link.js';
+import { OriginPostCard } from '../../components/origin-post.js';
+import {
+  useConversationDetailQuery,
+  useConversationMediaShareOptionsQuery,
+  useSendReplyMutation,
+  useShareConversationMediaMutation,
+  useSuggestMediaAskMutation,
+  useSuggestReplyMutation,
+} from './conversation-queries.js';
 import { SendConfirmationDialog } from './send-confirmation-dialog.js';
+import { MediaShareConfirmationDialog } from './media-share-confirmation-dialog.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
+import { formatExactTime } from './relative-time.js';
+import { getStoredComposerDraft, storeComposerDraft } from './composer-drafts.js';
+
+/** Reddit chat rejects messages longer than roughly this many characters. */
+export const REDDIT_CHAT_MAX_MESSAGE_LENGTH = 10_000;
+const CHARACTER_WARNING_MARGIN = 500;
+const SUCCESS_NOTICE_DISMISS_MS = 5_000;
+const AT_BOTTOM_THRESHOLD_PX = 48;
 
 interface ConversationDetailProps {
   conversationId: string;
   onClose(): void;
 }
 
-function formatMessageTime(timestamp: number): string {
-  return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(timestamp);
+function mediaPath(localPath: string): string {
+  return `/media/${localPath.split(/[\\/]/).map(encodeURIComponent).join('/')}`;
+}
+
+/** Auto-dismisses a success flag after a few seconds. */
+function useAutoDismiss(isVisible: boolean, dismiss: () => void) {
+  useEffect(() => {
+    if (!isVisible) return;
+    const timer = window.setTimeout(dismiss, SUCCESS_NOTICE_DISMISS_MS);
+    return () => window.clearTimeout(timer);
+  }, [isVisible, dismiss]);
 }
 
 function MessageHistory({ conversation }: { conversation: ConversationDetailResponse }) {
+  const [revealedMedia, setRevealedMedia] = useState<Set<string>>(() => new Set());
+  const listRef = useRef<HTMLOListElement>(null);
+  const isAtBottomRef = useRef(true);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+  const messageCount = conversation.messages?.length ?? 0;
+
+  const scrollToBottom = useCallback(() => {
+    const list = listRef.current;
+    if (!list) return;
+    list.scrollTop = list.scrollHeight;
+    isAtBottomRef.current = true;
+    setIsAtBottom(true);
+  }, []);
+
+  // Stick to the latest message on mount and when new messages arrive,
+  // unless the operator has scrolled up to read history.
+  useEffect(() => {
+    if (isAtBottomRef.current) scrollToBottom();
+  }, [messageCount, scrollToBottom]);
+
+  function handleScroll() {
+    const list = listRef.current;
+    if (!list) return;
+    const atBottom = list.scrollHeight - list.scrollTop - list.clientHeight <= AT_BOTTOM_THRESHOLD_PX;
+    isAtBottomRef.current = atBottom;
+    setIsAtBottom(atBottom);
+  }
+
   if (!conversation.messages || conversation.messages.length === 0) {
     return <div className="conversation-empty-detail">No messages have been loaded for this conversation.</div>;
   }
 
   return (
-    <ol aria-label="Message history" className="conversation-messages">
+    <div className="conversation-messages-shell">
+      <ol aria-label="Message history" className="conversation-messages" onScroll={handleScroll} ref={listRef}>
         {conversation.messages.map((message) => (
-        <li className={message.isSelf ? 'is-self' : 'is-recipient'} key={`${message.timestamp}-${message.sender}-${message.text}`}>
+          <li className={message.isSelf ? 'is-self' : 'is-recipient'} key={message.eventId ?? `${message.timestamp}-${message.sender}-${message.text}`}>
             <div>
-            <strong>{message.isSelf ? 'You' : `u/${conversation.username}`}</strong>
-            <time dateTime={new Date(message.timestamp).toISOString()}>{formatMessageTime(message.timestamp)}</time>
+              <strong>{message.isSelf
+                ? `You${conversation.owner ? ` (u/${conversation.owner.redditUsername})` : ''}`
+                : <RedditUsernameLink username={conversation.username} />}</strong>
+              {message.isAi ? <span aria-label="Sent by AI" className="conversation-ai-badge">AI</span> : null}
+              <time dateTime={new Date(message.timestamp).toISOString()}>{formatExactTime(message.timestamp)}</time>
             </div>
             <p>{message.text}</p>
+            {message.media?.length ? (
+              <div className="conversation-message-images">
+                {message.media.map((media) => {
+                  const mediaKey = `${message.timestamp}-${media.localPath}`;
+                  const sender = message.isSelf ? 'sent by you' : `received from ${redditUsernameLabel(conversation.username)}`;
+                  const isRevealed = revealedMedia.has(mediaKey);
+
+                  return (
+                    <div className="conversation-message-image" key={mediaKey}>
+                    <img
+                      alt={`Image ${sender}`}
+                      className={isRevealed ? undefined : 'is-blurred'}
+                      loading="lazy"
+                      src={mediaPath(media.localPath)}
+                    />
+                      <button
+                        aria-pressed={isRevealed}
+                        className="conversation-image-reveal"
+                        onClick={() => setRevealedMedia((current) => {
+                          const next = new Set(current);
+                          if (next.has(mediaKey)) next.delete(mediaKey);
+                          else next.add(mediaKey);
+                          return next;
+                        })}
+                        type="button"
+                      >
+                        {isRevealed ? 'Blur conversation image' : 'Reveal conversation image'}
+                      </button>
+                    </div>
+                  );
+                })}
+              </div>
+            ) : null}
           </li>
         ))}
       </ol>
+      {!isAtBottom ? (
+        <button className="conversation-jump-latest" onClick={scrollToBottom} type="button">
+          Jump to latest
+        </button>
+      ) : null}
+    </div>
   );
 }
 
-function ConversationComposer({ conversation }: { conversation: ConversationDetailResponse }) {
-  const [draft, setDraft] = useState('');
+function ConversationComposer({ conversation, conversationId }: { conversation: ConversationDetailResponse; conversationId: string }) {
+  const [draft, setDraft] = useState(() => getStoredComposerDraft(conversationId));
+  const [restorableDraft, setRestorableDraft] = useState<string | null>(null);
   const [isConfirming, setIsConfirming] = useState(false);
   const [wasSent, setWasSent] = useState(false);
+  const [selectedAssetId, setSelectedAssetId] = useState<string | null>(null);
+  const [areSavedImagesRevealed, setAreSavedImagesRevealed] = useState(false);
+  const [isMediaShareOpen, setIsMediaShareOpen] = useState(false);
+  const [isConfirmingMedia, setIsConfirmingMedia] = useState(false);
+  const [wasMediaShared, setWasMediaShared] = useState(false);
   const sendButtonRef = useRef<HTMLButtonElement>(null);
-  const suggestionMutation = useSuggestReplyMutation(conversation.roomId ?? conversation.username);
-  const sendMutation = useSendReplyMutation(conversation.roomId ?? conversation.username);
+  const mediaShareSummaryRef = useRef<HTMLElement>(null);
+  const suggestionMutation = useSuggestReplyMutation(conversationId);
+  const mediaAskMutation = useSuggestMediaAskMutation(conversationId);
+  const sendMutation = useSendReplyMutation(conversationId);
+  const mediaOptionsQuery = useConversationMediaShareOptionsQuery(conversationId, isMediaShareOpen);
+  const mediaShareMutation = useShareConversationMediaMutation(conversationId);
+  const mediaOptions = mediaOptionsQuery.data?.assets ?? [];
+  const selectedAsset: MediaLibraryAsset | null = mediaOptions.find((asset) => asset.id === selectedAssetId) ?? null;
   const canSend = draft.trim().length > 0 && !sendMutation.isPending;
+  const automationActive = conversation.automation.status === 'active' && conversation.automation.remainingTurns > 0;
+  const isNearCharacterLimit = draft.length >= REDDIT_CHAT_MAX_MESSAGE_LENGTH - CHARACTER_WARNING_MARGIN;
+
+  const updateDraft = useCallback((next: string) => {
+    setDraft(next);
+    storeComposerDraft(conversationId, next);
+  }, [conversationId]);
+
+  const dismissSent = useCallback(() => setWasSent(false), []);
+  const dismissMediaShared = useCallback(() => setWasMediaShared(false), []);
+  useAutoDismiss(wasSent, dismissSent);
+  useAutoDismiss(wasMediaShared, dismissMediaShared);
 
   const closeConfirmation = useCallback(() => {
     setIsConfirming(false);
     queueMicrotask(() => sendButtonRef.current?.focus());
   }, []);
 
+  const closeMediaConfirmation = useCallback(() => {
+    setIsConfirmingMedia(false);
+    queueMicrotask(() => mediaShareSummaryRef.current?.focus());
+  }, []);
+
+  function applySuggestion(suggestion: string) {
+    const priorDraft = draft;
+    updateDraft(suggestion);
+    if (priorDraft.trim().length > 0 && priorDraft !== suggestion) setRestorableDraft(priorDraft);
+    else setRestorableDraft(null);
+  }
+
   function suggestReply() {
     setWasSent(false);
-    suggestionMutation.mutate(undefined, { onSuccess: (suggestion) => setDraft(suggestion) });
+    suggestionMutation.mutate(undefined, { onSuccess: applySuggestion });
+  }
+
+  function suggestMediaAsk() {
+    setWasSent(false);
+    mediaAskMutation.mutate(undefined, { onSuccess: applySuggestion });
   }
 
   function sendReply() {
     if (!canSend) return;
     sendMutation.mutate(draft, {
       onSuccess() {
-        setDraft('');
+        updateDraft('');
+        setRestorableDraft(null);
         setWasSent(true);
       },
       onSettled: closeConfirmation,
     });
   }
 
+  function shareMedia() {
+    if (!selectedAsset) return;
+    mediaShareMutation.mutate(selectedAsset.id, {
+      onSuccess() {
+        setSelectedAssetId(null);
+        setWasMediaShared(true);
+      },
+      onSettled: closeMediaConfirmation,
+    });
+  }
+
   return (
     <section aria-labelledby="reply-composer-heading" className="conversation-composer">
       <div className="conversation-section-heading">
@@ -69,25 +221,113 @@ function ConversationComposer({ conversation }: { conversation: ConversationDeta
         <button disabled={suggestionMutation.isPending} onClick={suggestReply} type="button">
           {suggestionMutation.isPending ? 'Generating…' : 'Suggest reply'}
         </button>
+        <button disabled={mediaAskMutation.isPending || !automationActive} onClick={suggestMediaAsk} type="button">
+          {mediaAskMutation.isPending ? 'Generating media ask…' : 'Suggest media ask'}
+        </button>
       </div>
-      <label className="sr-only" htmlFor="conversation-reply">Reply to u/{conversation.username}</label>
+      <div
+        className={`conversation-automation-status is-${conversation.automation.status}`}
+        role="status"
+      >
+        <strong>{conversation.automation.remainingTurns} automated {conversation.automation.remainingTurns === 1 ? 'turn' : 'turns'} remaining</strong>
+        <span>{automationStatusMessage(conversation)}</span>
+      </div>
+      <label className="sr-only" htmlFor="conversation-reply">Reply to {redditUsernameLabel(conversation.username)}</label>
       <textarea
         id="conversation-reply"
+        maxLength={REDDIT_CHAT_MAX_MESSAGE_LENGTH}
         onChange={(event) => {
-          setDraft(event.target.value);
+          updateDraft(event.target.value);
+          setRestorableDraft(null);
           setWasSent(false);
         }}
         placeholder="Write or generate a reply"
         rows={5}
         value={draft}
       />
+      {restorableDraft !== null ? (
+        <div className="conversation-inline-notice" role="status">
+          <span>The suggestion replaced your draft.</span>
+          <button
+            onClick={() => {
+              updateDraft(restorableDraft);
+              setRestorableDraft(null);
+            }}
+            type="button"
+          >
+            Undo
+          </button>
+        </div>
+      ) : null}
       {suggestionMutation.isError ? <div className="conversation-inline-error" role="alert">{suggestionMutation.error.message}</div> : null}
+      {mediaAskMutation.isError ? <div className="conversation-inline-error" role="alert">{mediaAskMutation.error.message}</div> : null}
       {sendMutation.isError ? <div className="conversation-inline-error" role="alert">{sendMutation.error.message}</div> : null}
       {wasSent ? (
-        <div aria-label="Reply sent" className="conversation-inline-success" role="status">Reply sent to u/{conversation.username}</div>
+        <div aria-label="Reply sent" className="conversation-inline-success" role="status">Reply sent to <RedditUsernameLink username={conversation.username} /></div>
       ) : null}
+      <details className="conversation-media-share" open={isMediaShareOpen}>
+        <summary
+          onClick={(event) => {
+            event.preventDefault();
+            setIsMediaShareOpen((current) => !current);
+          }}
+          ref={mediaShareSummaryRef}
+        >
+          Share a saved image
+        </summary>
+        <p>Pick any enabled image from your exchange library to send. Images already shared in this conversation are hidden.</p>
+        {mediaOptionsQuery.isLoading ? <span role="status">Loading saved images…</span> : null}
+        {mediaOptionsQuery.isError ? <div className="conversation-inline-error" role="alert">{mediaOptionsQuery.error.message}</div> : null}
+        {mediaOptionsQuery.data?.warning ? <div className="conversation-media-warning" role="status">{mediaOptionsQuery.data.warning}</div> : null}
+        {mediaOptionsQuery.data?.reason ? <div className="conversation-media-unavailable">{mediaOptionsQuery.data.reason}</div> : null}
+        {mediaOptions.length > 0 ? (
+          <>
+            <button className="conversation-media-reveal" onClick={() => setAreSavedImagesRevealed((current) => !current)} type="button">
+              {areSavedImagesRevealed ? 'Blur saved images' : 'Reveal saved images'}
+            </button>
+            {!areSavedImagesRevealed ? (
+              <p className="conversation-media-hint">Reveal images to select one.</p>
+            ) : null}
+            <div aria-label="Saved images available to share" className="conversation-media-options" role="radiogroup">
+              {mediaOptions.map((asset) => (
+                <label className={selectedAssetId === asset.id ? 'is-selected' : ''} key={asset.id}>
+                  <input
+                    checked={selectedAssetId === asset.id}
+                    disabled={!areSavedImagesRevealed}
+                    name="conversation-media-asset"
+                    onChange={() => {
+                      setSelectedAssetId(asset.id);
+                      setWasMediaShared(false);
+                    }}
+                    type="radio"
+                    value={asset.id}
+                  />
+                  <img
+                    alt={`Saved image tagged ${asset.tags.join(', ')}`}
+                    className={areSavedImagesRevealed ? undefined : 'is-blurred'}
+                    src={asset.urlPath}
+                  />
+                  <span>{asset.tags.join(', ')} · {asset.safety.toUpperCase()}</span>
+                </label>
+              ))}
+            </div>
+            <button
+              className="conversation-primary"
+              disabled={!selectedAsset || mediaShareMutation.isPending}
+              onClick={() => setIsConfirmingMedia(true)}
+              type="button"
+            >
+              Review image share
+            </button>
+          </>
+        ) : null}
+        {mediaShareMutation.isError ? <div className="conversation-inline-error" role="alert">{mediaShareMutation.error.message}</div> : null}
+        {wasMediaShared ? <div className="conversation-inline-success" role="status">Saved image shared with {redditUsernameLabel(conversation.username)}.</div> : null}
+      </details>
       <div className="conversation-actions">
-        <span>{draft.length} characters</span>
+        <span className={isNearCharacterLimit ? 'conversation-char-counter is-warning' : 'conversation-char-counter'}>
+          {draft.length} / {REDDIT_CHAT_MAX_MESSAGE_LENGTH}
+        </span>
         <button
           aria-label="Review and send reply"
           className="conversation-primary"
@@ -107,10 +347,34 @@ function ConversationComposer({ conversation }: { conversation: ConversationDeta
           onConfirm={sendReply}
         />
       ) : null}
+      {isConfirmingMedia && selectedAsset ? (
+        <MediaShareConfirmationDialog
+          areImagesRevealed={areSavedImagesRevealed}
+          asset={selectedAsset}
+          isPending={mediaShareMutation.isPending}
+          onCancel={closeMediaConfirmation}
+          onConfirm={shareMedia}
+        />
+      ) : null}
     </section>
   );
 }
 
+function automationStatusMessage(conversation: ConversationDetailResponse): string {
+  switch (conversation.automation.status) {
+    case 'image-received':
+      return 'Image received. Automation is complete.';
+    case 'human-required':
+      return conversation.automation.handoffReason ?? 'Automated turns are exhausted. A human should take over.';
+    case 'boundary':
+      return 'Automation stopped because the user set a boundary.';
+    case 'user-overridden':
+      return 'A manual reply was sent. AI turns are disabled for this conversation.';
+    default:
+      return 'The next unread reply can be handled automatically.';
+  }
+}
+
 export function ConversationDetail({ conversationId, onClose }: ConversationDetailProps) {
   const detailQuery = useConversationDetailQuery(conversationId);
 
@@ -133,7 +397,9 @@ export function ConversationDetail({ conversationId, onClose }: ConversationDeta
       <header>
         <div>
           <span className="conversation-eyebrow">Conversation</span>
-          <h2>u/{conversation.username}</h2>
+          <h2><RedditUsernameLink username={conversation.username} /></h2>
+          <AccountOwnerBadge owner={conversation.owner} />
+          {conversation.sellerDetected ? <span className="conversation-seller-marker">Seller</span> : null}
           {conversation.unread ? <span className="conversation-badge">Unread</span> : null}
         </div>
         <button aria-label="Close conversation" onClick={onClose} type="button">Close</button>
@@ -144,19 +410,18 @@ export function ConversationDetail({ conversationId, onClose }: ConversationDeta
         </div>
       ) : null}
       {conversation.triggeringPost ? (
-        <a
-          aria-label={conversation.triggeringPost.title ?? `Open triggering post ${conversation.triggeringPost.id}`}
-          className="triggering-post"
-          href={conversation.triggeringPost.url}
-          rel="noreferrer"
-          target="_blank"
-        >
-          <span>Started from {conversation.triggeringPost.subreddit ? `r/${conversation.triggeringPost.subreddit}` : 'Reddit'}</span>
-          <strong>{conversation.triggeringPost.title ?? conversation.triggeringPost.id}</strong>
-        </a>
+        <div className="triggering-post">
+          <OriginPostCard post={{
+            title: conversation.triggeringPost.title ?? conversation.triggeringPost.id,
+            url: conversation.triggeringPost.url,
+            imageUrl: conversation.triggeringPost.imageUrl,
+            subreddit: conversation.triggeringPost.subreddit,
+            postedAt: conversation.triggeringPost.postedAt,
+          }} />
+        </div>
       ) : null}
       <MessageHistory conversation={conversation} />
-      <ConversationComposer conversation={conversation} />
+      <ConversationComposer conversation={conversation} conversationId={conversationId} />
     </article>
   );
 }

apps/dashboard/src/features/conversations/conversation-identity.ts

@@ -0,0 +1,12 @@
+import type { ActiveChat } from '../../../../../packages/api-contracts/src/index.js';
+
+export function createOwnedConversationId(accountId: string | undefined, conversationId: string): string {
+  return accountId
+    ? `${encodeURIComponent(accountId)}~${encodeURIComponent(conversationId)}`
+    : conversationId;
+}
+
+export function ownedConversationId(conversation: ActiveChat): string {
+  const conversationId = conversation.roomId ?? conversation.username;
+  return createOwnedConversationId(conversation.owner?.accountId, conversationId);
+}

apps/dashboard/src/features/conversations/conversation-queries.ts

@@ -4,10 +4,18 @@ import { conversationApi } from './conversation-api.js';
 export const conversationQueryKeys = {
   all: ['conversations'] as const,
   detail: (id: string) => ['conversations', 'detail', id] as const,
+  processedPosts: (username: string) => ['conversations', 'processed-posts', username] as const,
+  mediaShareOptions: (id: string) => ['conversations', 'media-share-options', id] as const,
 };
 
+export const CONVERSATION_REFRESH_INTERVAL_MS = 30_000;
+
 export function useConversationsQuery() {
-  return useQuery({ queryKey: conversationQueryKeys.all, queryFn: conversationApi.list });
+  return useQuery({
+    queryKey: conversationQueryKeys.all,
+    queryFn: conversationApi.list,
+    refetchInterval: CONVERSATION_REFRESH_INTERVAL_MS,
+  });
 }
 
 export function useConversationDetailQuery(id: string | null) {
@@ -15,6 +23,7 @@ export function useConversationDetailQuery(id: string | null) {
     queryKey: conversationQueryKeys.detail(id ?? ''),
     queryFn: () => conversationApi.detail(id ?? ''),
     enabled: id !== null,
+    refetchInterval: CONVERSATION_REFRESH_INTERVAL_MS,
   });
 }
 
@@ -22,6 +31,26 @@ export function useSuggestReplyMutation(id: string) {
   return useMutation({ mutationFn: () => conversationApi.suggestReply(id) });
 }
 
+export function useSuggestMediaAskMutation(id: string) {
+  return useMutation({ mutationFn: () => conversationApi.suggestMediaAsk(id) });
+}
+
+export function useConversationMediaShareOptionsQuery(id: string, enabled: boolean) {
+  return useQuery({
+    queryKey: conversationQueryKeys.mediaShareOptions(id),
+    queryFn: () => conversationApi.mediaShareOptions(id),
+    enabled,
+  });
+}
+
+export function useProcessedPostsQuery(username: string) {
+  return useQuery({
+    queryKey: conversationQueryKeys.processedPosts(username),
+    queryFn: () => conversationApi.processedPosts(username),
+    enabled: username.length > 0,
+  });
+}
+
 export function useSendReplyMutation(id: string) {
   const queryClient = useQueryClient();
   return useMutation({
@@ -35,11 +64,25 @@ export function useSendReplyMutation(id: string) {
   });
 }
 
+export function useShareConversationMediaMutation(id: string) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (assetId: string) => conversationApi.shareMedia(id, assetId),
+    async onSuccess() {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: conversationQueryKeys.all }),
+        queryClient.invalidateQueries({ queryKey: conversationQueryKeys.detail(id) }),
+        queryClient.invalidateQueries({ queryKey: conversationQueryKeys.mediaShareOptions(id) }),
+      ]);
+    },
+  });
+}
+
 export function useStartConversationMutation() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: ({ username, message }: { username: string; message: string }) =>
-      conversationApi.startConversation(username, message),
+    mutationFn: ({ accountId, username, message }: { accountId: string; username: string; message: string }) =>
+      conversationApi.startConversation(accountId, username, message),
     async onSuccess() {
       await queryClient.invalidateQueries({ queryKey: conversationQueryKeys.all });
     },

apps/dashboard/src/features/conversations/conversation-route.tsx

@@ -1,22 +1,45 @@
-import { useNavigate, useParams } from 'react-router-dom';
-import { ConversationsPage } from './conversations-page.js';
+import { useNavigate, useParams, useSearchParams } from 'react-router-dom';
+import { ConversationsPage, type ConversationFilters } from './conversations-page.js';
 
 export function ConversationRoute() {
   const navigate = useNavigate();
   const { conversationId } = useParams<{ conversationId: string }>();
+  const [searchParams, setSearchParams] = useSearchParams();
+  const filterValue = searchParams.get('filter');
+  const filters: ConversationFilters = {
+    search: searchParams.get('q') ?? '',
+    showSellers: searchParams.get('showSellers') === 'true',
+    filter:
+      filterValue === 'unread'
+      || filterValue === 'awaiting-reply'
+      || filterValue === 'received-images'
+        ? filterValue
+        : 'all',
+  };
 
   function selectConversation(nextConversationId: string | null) {
+    const suffix = searchParams.size > 0 ? `?${searchParams.toString()}` : '';
     void navigate(
       nextConversationId
-        ? `/conversations/${encodeURIComponent(nextConversationId)}`
-        : '/conversations',
+        ? `/conversations/${encodeURIComponent(nextConversationId)}${suffix}`
+        : `/conversations${suffix}`,
     );
   }
 
+  function updateFilters(next: ConversationFilters) {
+    const params = new URLSearchParams(searchParams);
+    if (next.search) params.set('q', next.search); else params.delete('q');
+    if (next.filter !== 'all') params.set('filter', next.filter); else params.delete('filter');
+    if (next.showSellers) params.set('showSellers', 'true'); else params.delete('showSellers');
+    setSearchParams(params, { replace: true });
+  }
+
   return (
     <ConversationsPage
       selectedConversationId={conversationId ?? null}
       onSelectedConversationChange={selectConversation}
+      filters={filters}
+      onFiltersChange={updateFilters}
     />
   );
 }

apps/dashboard/src/features/conversations/conversations-page.tsx

@@ -1,66 +1,123 @@
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import type { ActiveChat } from '../../../../../packages/api-contracts/src/index.js';
+import { RedditUsernameLink, redditUsernameLabel } from '../../components/reddit-username-link.js';
 import { ConversationDetail } from './conversation-detail.js';
 import { useConversationsQuery } from './conversation-queries.js';
 import { StartConversationForm } from './start-conversation-form.js';
+import { ProcessedUserLookup } from './processed-user-lookup.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
 import './conversations.css';
+import { ownedConversationId } from './conversation-identity.js';
+import { formatExactTime, formatShortRelativeTime } from './relative-time.js';
 
-type ConversationFilter = 'all' | 'unread' | 'awaiting-reply';
+export type ConversationFilter = 'all' | 'unread' | 'awaiting-reply' | 'received-images';
+
+const SMALL_VIEWPORT_QUERY = '(max-width: 51.9999rem)';
+
+export interface ConversationFilters {
+  search: string;
+  filter: ConversationFilter;
+  showSellers: boolean;
+}
 
 export interface ConversationsPageProps {
   selectedConversationId?: string | null;
   onSelectedConversationChange?(conversationId: string | null): void;
-}
-
-function conversationId(conversation: ActiveChat): string {
-  return conversation.roomId ?? conversation.username;
+  filters?: ConversationFilters;
+  onFiltersChange?(filters: ConversationFilters): void;
 }
 
 function matchesFilter(conversation: ActiveChat, filter: ConversationFilter): boolean {
   if (filter === 'unread') return conversation.unread;
   if (filter === 'awaiting-reply') return conversation.isFromUs;
+  if (filter === 'received-images') return conversation.hasReceivedImages === true;
   return true;
 }
 
-function ConversationListItem({ conversation, isSelected, onSelect }: {
+function ConversationListItem({ conversation, isSelected, now, onSelect }: {
   conversation: ActiveChat;
   isSelected: boolean;
+  now: number;
   onSelect(): void;
 }) {
   const state = conversation.unread ? 'Unread' : conversation.isFromUs ? 'Awaiting reply' : 'Up to date';
+  const relativeTime = formatShortRelativeTime(conversation.lastMessageTime, now);
+  const itemClasses = ['conversation-list-item'];
+  if (isSelected) itemClasses.push('is-selected');
+  if (conversation.unread) itemClasses.push('is-unread');
   return (
-    <li>
+    <li className={itemClasses.join(' ')}>
       <button
-        aria-label={`u/${conversation.username}, ${state}`}
+        aria-label={`${redditUsernameLabel(conversation.username)}, ${state}, ${relativeTime}${conversation.sellerDetected ? ', Seller' : ''}${conversation.hasReceivedImages ? ', Image received' : ''}`}
         aria-pressed={isSelected}
-        className={isSelected ? 'conversation-list-item is-selected' : 'conversation-list-item'}
+        className="conversation-list-target"
         onClick={onSelect}
         type="button"
-      >
-        <span className="conversation-list-heading"><strong>u/{conversation.username}</strong><small>{state}</small></span>
+      />
+      <span className="conversation-list-heading">
+        <strong><RedditUsernameLink username={conversation.username} /></strong>
+        <span className="conversation-list-meta">
+          <small>{state}</small>
+          <time dateTime={new Date(conversation.lastMessageTime).toISOString()} title={formatExactTime(conversation.lastMessageTime)}>
+            {relativeTime}
+          </time>
+        </span>
+      </span>
+      <AccountOwnerBadge owner={conversation.owner} />
+      {conversation.sellerDetected ? <span className="conversation-seller-marker">Seller</span> : null}
+      {conversation.hasReceivedImages ? <span className="conversation-image-marker">Image received</span> : null}
       <span>{conversation.lastMessageSnippet || 'No message preview'}</span>
-      </button>
     </li>
   );
 }
 
-export function ConversationsPage({ selectedConversationId, onSelectedConversationChange }: ConversationsPageProps) {
+export function ConversationsPage({ selectedConversationId, onSelectedConversationChange, filters, onFiltersChange }: ConversationsPageProps) {
   const conversationsQuery = useConversationsQuery();
   const [internalSelectedId, setInternalSelectedId] = useState<string | null>(null);
-  const [search, setSearch] = useState('');
-  const [filter, setFilter] = useState<ConversationFilter>('all');
+  const [localFilters, setLocalFilters] = useState<ConversationFilters>({ search: '', filter: 'all', showSellers: false });
   const [isStartingConversation, setIsStartingConversation] = useState(false);
+  const [now, setNow] = useState(() => Date.now());
+  const detailPanelRef = useRef<HTMLElement>(null);
   const activeConversationId = selectedConversationId !== undefined ? selectedConversationId : internalSelectedId;
+  const activeFilters = filters ?? localFilters;
+
+  useEffect(() => {
+    const interval = window.setInterval(() => setNow(Date.now()), 60_000);
+    return () => window.clearInterval(interval);
+  }, []);
+
+  // On small viewports the detail panel sits below the list; bring it into
+  // view when a conversation is picked so the selection isn't invisible.
+  useEffect(() => {
+    if (!activeConversationId) return;
+    if (typeof window.matchMedia !== 'function') return;
+    if (!window.matchMedia(SMALL_VIEWPORT_QUERY).matches) return;
+    detailPanelRef.current?.scrollIntoView?.({ behavior: 'smooth', block: 'start' });
+  }, [activeConversationId]);
+
+  function updateFilters(next: ConversationFilters) {
+    if (filters === undefined) setLocalFilters(next);
+    onFiltersChange?.(next);
+  }
 
   const visibleConversations = useMemo(() => {
-    const normalizedSearch = search.trim().toLowerCase();
-    return (conversationsQuery.data ?? []).filter((conversation) => {
+    const normalizedSearch = activeFilters.search.trim().toLowerCase();
+    return (conversationsQuery.data ?? [])
+      .filter((conversation) => {
         const matchesSearch = normalizedSearch.length === 0
           || conversation.username.toLowerCase().includes(normalizedSearch)
           || conversation.lastMessageSnippet.toLowerCase().includes(normalizedSearch);
-      return matchesSearch && matchesFilter(conversation, filter);
-    });
-  }, [conversationsQuery.data, filter, search]);
+        return matchesSearch
+          && matchesFilter(conversation, activeFilters.filter)
+          && (activeFilters.showSellers || conversation.sellerDetected !== true);
+      })
+      .sort((left, right) => right.lastMessageTime - left.lastMessageTime);
+  }, [activeFilters, conversationsQuery.data]);
+
+  const unreadCount = useMemo(
+    () => (conversationsQuery.data ?? []).filter((conversation) => conversation.unread).length,
+    [conversationsQuery.data],
+  );
 
   function selectConversation(id: string | null) {
     if (selectedConversationId === undefined) setInternalSelectedId(id);
@@ -75,9 +132,22 @@ export function ConversationsPage({ selectedConversationId, onSelectedConversati
           <h1>Conversations</h1>
           <p>Review replies, draft carefully, and send only after confirmation.</p>
         </div>
+        <div className="conversations-header-actions">
+          <div className="conversation-refresh">
+            <button
+              aria-busy={conversationsQuery.isFetching || undefined}
+              disabled={conversationsQuery.isFetching}
+              onClick={() => void conversationsQuery.refetch()}
+              type="button"
+            >
+              {conversationsQuery.isFetching ? 'Refreshing…' : 'Refresh'}
+            </button>
+            <span className="conversation-refresh-note">Auto-refreshes every 30s</span>
+          </div>
           <button className="conversation-primary" onClick={() => setIsStartingConversation((current) => !current)} type="button">
             {isStartingConversation ? 'Close new conversation' : 'New conversation'}
           </button>
+        </div>
       </header>
 
       {isStartingConversation ? (
@@ -86,6 +156,7 @@ export function ConversationsPage({ selectedConversationId, onSelectedConversati
           <StartConversationForm onStarted={(id) => selectConversation(id)} />
         </section>
       ) : null}
+      <ProcessedUserLookup />
 
       <div className="conversation-workspace">
         <section aria-label="Conversation inbox" className="conversation-master">
@@ -93,21 +164,31 @@ export function ConversationsPage({ selectedConversationId, onSelectedConversati
             <label className="sr-only" htmlFor="conversation-search">Search conversations</label>
             <input
               id="conversation-search"
-              onChange={(event) => setSearch(event.target.value)}
+              onChange={(event) => updateFilters({ ...activeFilters, search: event.target.value })}
               placeholder="Search conversations"
               type="search"
-              value={search}
+              value={activeFilters.search}
             />
             <label className="sr-only" htmlFor="conversation-filter">Filter conversations</label>
             <select
               id="conversation-filter"
-              onChange={(event) => setFilter(event.target.value as ConversationFilter)}
-              value={filter}
+              onChange={(event) => updateFilters({ ...activeFilters, filter: event.target.value as ConversationFilter })}
+              value={activeFilters.filter}
             >
               <option value="all">All</option>
               <option value="unread">Unread</option>
               <option value="awaiting-reply">Awaiting reply</option>
+              <option value="received-images">Received images</option>
             </select>
+            <span className="conversation-unread-count">{unreadCount} unread</span>
+            <label className="conversation-seller-toggle">
+              <input
+                checked={activeFilters.showSellers}
+                onChange={(event) => updateFilters({ ...activeFilters, showSellers: event.target.checked })}
+                type="checkbox"
+              />
+              Show sellers
+            </label>
           </div>
           {conversationsQuery.isPending ? (
             <div aria-label="Loading conversations" className="conversation-list-state" role="status">Loading conversations…</div>
@@ -126,16 +207,17 @@ export function ConversationsPage({ selectedConversationId, onSelectedConversati
               {visibleConversations.map((conversation) => (
                 <ConversationListItem
                   conversation={conversation}
-                  isSelected={conversationId(conversation) === activeConversationId}
-                  key={conversationId(conversation)}
-                  onSelect={() => selectConversation(conversationId(conversation))}
+                  isSelected={ownedConversationId(conversation) === activeConversationId}
+                  key={ownedConversationId(conversation)}
+                  now={now}
+                  onSelect={() => selectConversation(ownedConversationId(conversation))}
                 />
               ))}
             </ul>
           )}
         </section>
 
-        <section aria-label="Selected conversation" className="conversation-detail-panel">
+        <section aria-label="Selected conversation" className="conversation-detail-panel" ref={detailPanelRef}>
           {activeConversationId ? (
             <ConversationDetail conversationId={activeConversationId} key={activeConversationId} onClose={() => selectConversation(null)} />
           ) : (

apps/dashboard/src/features/conversations/conversations.css

@@ -14,6 +14,9 @@
 }
 
 .conversations-header h1 { margin-bottom: .4rem; }
+.conversations-header-actions { display: flex; flex-wrap: wrap; align-items: center; gap: .75rem; }
+.conversation-refresh { display: grid; gap: .25rem; justify-items: end; }
+.conversation-refresh-note { color: var(--muted); font-size: .72rem; }
 .conversations-header p { margin-bottom: 0; color: var(--muted); }
 .conversation-eyebrow { display: block; margin-bottom: .4rem; color: var(--accent); font-size: .72rem; font-weight: 800; letter-spacing: .1em; text-transform: uppercase; }
 .conversation-primary { border-color: transparent !important; color: #06140b !important; background: var(--accent) !important; font-weight: 750; }
@@ -22,6 +25,12 @@
 .conversations-page button:disabled { cursor: wait; opacity: .58; }
 .new-conversation-panel { padding: 1rem; margin-bottom: 1rem; background: var(--surface); border: 1px solid var(--border); border-radius: .9rem; }
 .new-conversation-panel h2 { margin-bottom: 1rem; }
+.processed-user-lookup summary { cursor: pointer; }
+.processed-user-lookup summary h2 { display: inline-block; margin: 0; vertical-align: middle; }
+.processed-user-lookup[open] summary { margin-bottom: 1rem; }
+.processed-user-lookup form + p, .processed-user-lookup ol { margin-top: .8rem; }
+.conversation-form-hint { margin: 0; color: var(--muted); }
+.conversation-form-hint a { color: var(--accent); }
 .start-conversation-form { display: grid; gap: .8rem; }
 .conversation-field { display: grid; gap: .35rem; }
 .conversation-field label { color: var(--muted); font-size: .8rem; font-weight: 700; }
@@ -32,13 +41,27 @@
 .conversation-workspace { display: grid; gap: .75rem; }
 .conversation-master, .conversation-detail-panel { min-width: 0; background: var(--surface); border: 1px solid var(--border); border-radius: .9rem; overflow: hidden; }
 .conversation-toolbar { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: .5rem; padding: .75rem; border-bottom: 1px solid var(--border); }
+.conversation-unread-count { grid-column: 1 / -1; color: var(--accent); font-size: .75rem; font-weight: 800; }
+.conversation-seller-toggle { grid-column: 1 / -1; display: inline-flex; align-items: center; gap: .45rem; color: var(--muted); font-size: .78rem; font-weight: 700; }
+.conversation-seller-toggle input { width: auto; accent-color: var(--accent); }
 .conversation-list { display: grid; gap: .35rem; max-height: 46rem; padding: .5rem; margin: 0; overflow: auto; list-style: none; }
-.conversation-list-item { display: grid; gap: .4rem; width: 100%; padding: .8rem !important; text-align: left; background: transparent !important; border-color: transparent !important; }
-.conversation-list-item:hover { background: var(--surface-raised) !important; }
-.conversation-list-item.is-selected { background: var(--accent-dark) !important; border-color: #28593d !important; }
+.conversation-list-item { position: relative; display: grid; gap: .4rem; width: 100%; padding: .8rem; text-align: left; background: transparent; border: 1px solid transparent; border-radius: .6rem; }
+.conversation-list-item:hover { background: var(--surface-raised); }
+.conversation-list-item.is-selected { background: var(--accent-dark); border-color: #28593d; }
+.conversation-list-item.is-unread { padding-left: 1.4rem; }
+.conversation-list-item.is-unread::before { content: ''; position: absolute; top: 1.2rem; left: .55rem; width: .45rem; height: .45rem; background: var(--accent); border-radius: 50%; }
+.conversation-list-item.is-unread .conversation-list-heading strong { font-weight: 900; }
+.conversation-list-target { position: absolute; inset: 0; z-index: 0; min-height: 0 !important; padding: 0 !important; background: transparent !important; border: 0 !important; }
+.conversation-list-target:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
+.conversation-list-item > span { position: relative; z-index: 1; pointer-events: none; }
+.conversation-list-item .reddit-username-link { pointer-events: auto; }
 .conversation-list-item > span:last-child { overflow: hidden; color: var(--muted); font-size: .82rem; text-overflow: ellipsis; white-space: nowrap; }
 .conversation-list-heading { display: flex; align-items: center; justify-content: space-between; gap: .5rem; }
 .conversation-list-heading small { color: var(--accent); }
+.conversation-list-meta { display: flex; align-items: center; gap: .45rem; }
+.conversation-list-meta time { color: var(--muted); font-size: .7rem; white-space: nowrap; }
+.conversation-image-marker { justify-self: start; padding: .18rem .45rem; color: #d8e8ff !important; background: #18324d; border: 1px solid #315d85; border-radius: 999px; font-size: .68rem !important; font-weight: 750; }
+.conversation-seller-marker { display: inline-flex; justify-self: start; padding: .18rem .45rem; margin-right: .35rem; color: #ffd6d0 !important; background: #4b1e1a; border: 1px solid #874139; border-radius: 999px; font-size: .68rem !important; font-weight: 800; }
 .conversation-list-state, .conversation-detail-state { display: grid; place-items: center; align-content: center; gap: .5rem; min-height: 16rem; padding: 1.5rem; color: var(--muted); text-align: center; }
 .conversation-list-state strong, .conversation-detail-state strong { color: #e9f1ec; }
 .conversation-detail { min-height: 32rem; }
@@ -46,8 +69,9 @@
 .conversation-detail h2 { display: inline; margin-right: .6rem; }
 .conversation-badge { display: inline-flex; padding: .2rem .45rem; color: #aaf0c4; background: #163a26; border-radius: 999px; font-size: .7rem; font-weight: 800; }
 .conversation-sync-notice { padding: .75rem 1rem; color: #ffe1a0; background: #2a2111; border-bottom: 1px solid #59451e; }
-.triggering-post { display: grid; gap: .2rem; margin: 1rem; padding: .75rem; color: inherit; background: var(--surface-raised); border: 1px solid var(--border); border-radius: .65rem; text-decoration: none; }
-.triggering-post span { color: var(--muted); font-size: .75rem; }
+.triggering-post { margin: 1rem; padding: .75rem; background: var(--surface-raised); border: 1px solid var(--border); border-radius: .65rem; }
+.conversation-messages-shell { position: relative; }
+.conversation-jump-latest { position: absolute; right: 1rem; bottom: .75rem; z-index: 2; padding: .35rem .7rem !important; min-height: 2rem !important; color: #06140b !important; background: var(--accent) !important; border-color: transparent !important; border-radius: 999px !important; font-size: .78rem; font-weight: 800; box-shadow: 0 .4rem 1.2rem rgba(0, 0, 0, .35); }
 .conversation-messages { display: grid; gap: .75rem; max-height: 30rem; padding: 1rem; margin: 0; overflow: auto; list-style: none; }
 .conversation-messages li { max-width: 85%; padding: .7rem .8rem; border-radius: .8rem; }
 .conversation-messages li.is-self { justify-self: end; background: var(--accent-dark); }
@@ -55,16 +79,43 @@
 .conversation-messages li > div { display: flex; justify-content: space-between; gap: 1rem; margin-bottom: .35rem; }
 .conversation-messages time { color: var(--muted); font-size: .7rem; }
 .conversation-messages p { margin: 0; line-height: 1.45; white-space: pre-wrap; }
+.conversation-message-images { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(12rem, 100%), 1fr)); gap: .5rem; margin-top: .65rem; }
+.conversation-message-image { position: relative; overflow: hidden; border-radius: .6rem; }
+.conversation-message-images img { display: block; width: 100%; max-width: 28rem; max-height: 32rem; object-fit: contain; background: #08100c; border: 1px solid var(--border); border-radius: .6rem; transition: filter 160ms ease, transform 160ms ease; }
+.conversation-message-images img.is-blurred { filter: blur(24px) brightness(.55); transform: scale(1.12); }
+.conversation-image-reveal { position: absolute; bottom: .5rem; left: .5rem; min-height: 2rem !important; padding: .35rem .6rem !important; color: white !important; background: rgba(0, 0, 0, .76) !important; border-color: rgba(255, 255, 255, .45) !important; font-size: .75rem; font-weight: 800; }
+.conversation-image-reveal:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 .conversation-empty-detail { padding: 2rem; color: var(--muted); text-align: center; }
 .conversation-composer { display: grid; gap: .65rem; padding: 1rem; border-top: 1px solid var(--border); }
 .conversation-section-heading, .conversation-actions { display: flex; align-items: center; justify-content: space-between; gap: .75rem; }
 .conversation-section-heading h3 { margin: 0; }
 .conversation-actions > span { color: var(--muted); font-size: .75rem; }
-.conversation-inline-error, .conversation-inline-success { padding: .65rem .75rem; border-radius: .55rem; }
+.conversation-char-counter.is-warning { color: var(--warning-text) !important; font-weight: 800; }
+.conversation-inline-error, .conversation-inline-success, .conversation-inline-notice { padding: .65rem .75rem; border-radius: .55rem; }
+.conversation-inline-notice { display: flex; align-items: center; justify-content: space-between; gap: .75rem; color: var(--warning-text); background: var(--warning-bg); border: 1px solid var(--warning-border); }
+.conversation-inline-notice button { min-height: 2rem !important; padding: .3rem .65rem !important; }
 .conversation-inline-error { color: #ffd1ce; background: #461b18; border: 1px solid #80352f; }
 .conversation-inline-success { color: #b9f3ce; background: #163a26; border: 1px solid #28593d; }
-.conversation-dialog-backdrop { position: fixed; inset: 0; z-index: 70; display: grid; place-items: center; padding: 1rem; background: rgba(0, 0, 0, .74); }
-.conversation-dialog { width: min(30rem, 100%); padding: 1.25rem; background: var(--surface-raised); border: 1px solid var(--border); border-radius: .9rem; box-shadow: 0 2rem 5rem rgba(0, 0, 0, .45); }
+.conversation-media-share { display: grid; gap: .7rem; padding: .75rem; background: #0b1410; border: 1px solid var(--border); border-radius: .65rem; }
+.conversation-media-share[open] > * + * { margin-top: .7rem; }
+.conversation-media-share summary { color: #e9f1ec; font-weight: 800; cursor: pointer; }
+.conversation-media-share p, .conversation-media-unavailable { margin: 0; color: var(--muted); font-size: .8rem; }
+.conversation-media-reveal { justify-self: start; }
+.conversation-media-hint { color: var(--warning-text) !important; font-size: .78rem !important; font-weight: 700; }
+.conversation-media-warning { margin: 0; padding: .5rem .65rem; border-radius: .5rem; border: 1px solid var(--warning-text); background: color-mix(in srgb, var(--warning-text) 12%, transparent); color: var(--warning-text); font-size: .78rem; font-weight: 700; }
+.conversation-media-options { display: grid; grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr)); gap: .65rem; }
+.conversation-media-options label { display: grid; gap: .35rem; padding: .35rem; overflow: hidden; border: 1px solid var(--border); border-radius: .55rem; cursor: pointer; }
+.conversation-media-options label.is-selected { border-color: var(--accent); box-shadow: 0 0 0 1px var(--accent); }
+.conversation-media-options label:focus-within { outline: 2px solid var(--accent); outline-offset: 2px; }
+.conversation-media-options input { position: absolute; opacity: 0; pointer-events: none; }
+.conversation-media-options img { display: block; width: 100%; height: 8rem; object-fit: contain; background: #050907; border-radius: .35rem; transition: filter 160ms ease, transform 160ms ease; }
+.conversation-media-options img.is-blurred { filter: blur(22px) brightness(.55); transform: scale(1.1); }
+.conversation-media-options span { color: var(--muted); font-size: .7rem; text-transform: capitalize; }
+.conversation-media-confirmation img { display: block; width: 100%; max-height: 55vh; margin: 1rem 0; object-fit: contain; background: #050907; border-radius: .55rem; transition: filter 160ms ease; }
+.conversation-media-confirmation img.is-blurred { filter: blur(24px) brightness(.55); }
+.conversation-media-confirmation .conversation-message-image { overflow: hidden; border-radius: .55rem; }
+dialog.conversation-dialog { width: min(30rem, calc(100% - 2rem)); }
+dialog.conversation-media-confirmation { width: min(34rem, calc(100% - 2rem)); }
 .conversation-dialog p { color: var(--muted); }
 .conversation-dialog blockquote { max-height: 12rem; padding: .75rem; margin: 1rem 0; overflow: auto; background: #0b1410; border-left: 3px solid var(--accent); white-space: pre-wrap; }
 .conversation-dialog .conversation-actions { justify-content: flex-end; }
@@ -75,3 +126,55 @@
   .start-conversation-form { grid-template-columns: minmax(12rem, .5fr) minmax(18rem, 1fr) auto; align-items: end; }
   .conversation-workspace { grid-template-columns: minmax(17rem, .75fr) minmax(28rem, 1.5fr); }
 }
+.conversation-automation-status {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.75rem 0.875rem;
+  border: 1px solid var(--border);
+  border-radius: 0.625rem;
+  background: rgba(54, 116, 181, 0.08);
+}
+
+.conversation-automation-status span {
+  color: var(--muted);
+  text-align: right;
+}
+
+.conversation-automation-status.is-human-required,
+.conversation-automation-status.is-boundary,
+.conversation-automation-status.is-user-overridden {
+  border-color: #d8943a;
+  background: rgba(216, 148, 58, 0.12);
+}
+
+.conversation-automation-status.is-image-received {
+  border-color: #4d9b68;
+  background: rgba(77, 155, 104, 0.12);
+}
+
+@media (max-width: 640px) {
+  .conversation-automation-status {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  .conversation-automation-status span {
+    text-align: left;
+  }
+}
+.conversation-ai-badge {
+  display: inline-flex;
+  align-items: center;
+  min-height: 1.25rem;
+  padding: 0.125rem 0.4rem;
+  border: 1px solid rgba(99, 102, 241, 0.35);
+  border-radius: 999px;
+  background: rgba(99, 102, 241, 0.12);
+  color: #a5b4fc;
+  font-size: 0.6875rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  line-height: 1;
+}

apps/dashboard/src/features/conversations/media-share-confirmation-dialog.tsx

@@ -0,0 +1,56 @@
+import { useState } from 'react';
+import type { MediaLibraryAsset } from '../../../../../packages/api-contracts/src/index.js';
+import { Modal } from '../../components/modal.js';
+
+interface MediaShareConfirmationDialogProps {
+  asset: MediaLibraryAsset;
+  /** Whether the operator already revealed the saved images in the composer. */
+  areImagesRevealed: boolean;
+  isPending: boolean;
+  onCancel(): void;
+  onConfirm(): void;
+}
+
+export function MediaShareConfirmationDialog({ asset, areImagesRevealed, isPending, onCancel, onConfirm }: MediaShareConfirmationDialogProps) {
+  const [isRevealed, setIsRevealed] = useState(areImagesRevealed);
+
+  return (
+    <Modal
+      className="dialog-card conversation-dialog conversation-media-confirmation"
+      isDismissLocked={isPending}
+      labelledBy="media-share-confirmation-title"
+      onClose={onCancel}
+    >
+      <span className="conversation-eyebrow">Confirm image</span>
+      <h2 id="media-share-confirmation-title">Share this saved image?</h2>
+      <p>This sends immediately through Reddit chat, then asks them to reciprocate without pressure.</p>
+      <div className="conversation-message-image">
+        <img
+          alt={`Saved image tagged ${asset.tags.join(', ')}`}
+          className={isRevealed ? undefined : 'is-blurred'}
+          src={asset.urlPath}
+        />
+        <button
+          aria-pressed={isRevealed}
+          className="conversation-image-reveal"
+          onClick={() => setIsRevealed((current) => !current)}
+          type="button"
+        >
+          {isRevealed ? 'Blur image' : 'Reveal image'}
+        </button>
+      </div>
+      <div className="conversation-actions">
+        <button autoFocus disabled={isPending} onClick={onCancel} type="button">Cancel</button>
+        <button
+          aria-busy={isPending || undefined}
+          className="conversation-primary"
+          disabled={isPending}
+          onClick={onConfirm}
+          type="button"
+        >
+          {isPending ? 'Sharing…' : 'Confirm image share'}
+        </button>
+      </div>
+    </Modal>
+  );
+}

apps/dashboard/src/features/conversations/processed-user-lookup.tsx

@@ -0,0 +1,40 @@
+import { useState } from 'react';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
+import { RedditUsernameLink, redditUsernameLabel } from '../../components/reddit-username-link.js';
+import { useProcessedPostsQuery } from './conversation-queries.js';
+
+export function ProcessedUserLookup() {
+  const [input, setInput] = useState('');
+  const [username, setUsername] = useState('');
+  const postsQuery = useProcessedPostsQuery(username);
+  // Only show results that belong to the current lookup; switching the
+  // username changes the query key, which clears stale data automatically.
+  const showResults = postsQuery.data !== undefined && !postsQuery.isFetching;
+
+  return (
+    <details className="new-conversation-panel processed-user-lookup">
+      <summary>
+        <h2 id="processed-user-heading">Processed user lookup</h2>
+      </summary>
+      <form
+        className="start-conversation-form processed-user-form"
+        onSubmit={(event) => { event.preventDefault(); setUsername(input.trim().replace(/^u\//i, '')); }}
+      >
+        <div className="conversation-field">
+          <label htmlFor="processed-user">Lookup Reddit username</label>
+          <input autoComplete="off" id="processed-user" onChange={(event) => setInput(event.target.value)} value={input} />
+        </div>
+        <button className="conversation-primary" disabled={input.trim().length === 0} type="submit">Look up user</button>
+      </form>
+      {postsQuery.isFetching && username ? <p role="status">Looking up processed posts...</p> : null}
+      {postsQuery.isError ? <p className="conversation-inline-error" role="alert">{postsQuery.error.message}</p> : null}
+      {showResults && postsQuery.data ? (
+        postsQuery.data.length === 0 ? <p>No processed posts found for <RedditUsernameLink username={username} />.</p> : (
+          <ol aria-label={`Processed posts for ${redditUsernameLabel(username)}`}>
+            {postsQuery.data.map((post) => <li key={`${post.owner?.accountId ?? 'legacy'}:${post.id}`}><strong>{post.title}</strong><AccountOwnerBadge owner={post.owner} /><span>r/{post.subreddit} · {post.messageSent ? 'Message sent' : post.error ?? 'Processed'}</span></li>)}
+          </ol>
+        )
+      ) : null}
+    </details>
+  );
+}

apps/dashboard/src/features/conversations/relative-time.ts

@@ -0,0 +1,20 @@
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+const MONTH_MS = 30 * DAY_MS;
+const YEAR_MS = 365 * DAY_MS;
+
+export function formatShortRelativeTime(timestamp: number, now: number): string {
+  const elapsed = Math.max(0, now - timestamp);
+
+  if (elapsed < MINUTE_MS) return 'just now';
+  if (elapsed < HOUR_MS) return `${Math.floor(elapsed / MINUTE_MS)}m ago`;
+  if (elapsed < DAY_MS) return `${Math.floor(elapsed / HOUR_MS)}h ago`;
+  if (elapsed < MONTH_MS) return `${Math.floor(elapsed / DAY_MS)}d ago`;
+  if (elapsed < YEAR_MS) return `${Math.floor(elapsed / MONTH_MS)}mo ago`;
+  return `${Math.floor(elapsed / YEAR_MS)}y ago`;
+}
+
+export function formatExactTime(timestamp: number): string {
+  return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(timestamp);
+}

apps/dashboard/src/features/conversations/send-confirmation-dialog.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { Modal } from '../../components/modal.js';
 
 interface SendConfirmationDialogProps {
   draft: string;
@@ -8,31 +8,29 @@ interface SendConfirmationDialogProps {
 }
 
 export function SendConfirmationDialog({ draft, isPending, onCancel, onConfirm }: SendConfirmationDialogProps) {
-  const cancelButtonRef = useRef<HTMLButtonElement>(null);
-
-  useEffect(() => {
-    cancelButtonRef.current?.focus();
-    function handleKeyDown(event: KeyboardEvent) {
-      if (event.key === 'Escape' && !isPending) onCancel();
-    }
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [isPending, onCancel]);
-
   return (
-    <div aria-labelledby="send-confirmation-title" aria-modal="true" className="conversation-dialog-backdrop" role="dialog">
-      <div className="conversation-dialog">
+    <Modal
+      className="dialog-card conversation-dialog"
+      isDismissLocked={isPending}
+      labelledBy="send-confirmation-title"
+      onClose={onCancel}
+    >
       <span className="conversation-eyebrow">Confirm message</span>
       <h2 id="send-confirmation-title">Send this reply?</h2>
       <p>This sends immediately through Reddit chat.</p>
       <blockquote>{draft}</blockquote>
       <div className="conversation-actions">
-          <button disabled={isPending} onClick={onCancel} ref={cancelButtonRef} type="button">Cancel</button>
-          <button className="conversation-primary" disabled={isPending} onClick={onConfirm} type="button">
+        <button autoFocus disabled={isPending} onClick={onCancel} type="button">Cancel</button>
+        <button
+          aria-busy={isPending || undefined}
+          className="conversation-primary"
+          disabled={isPending}
+          onClick={onConfirm}
+          type="button"
+        >
           {isPending ? 'Sending…' : 'Confirm send'}
         </button>
       </div>
-      </div>
-    </div>
+    </Modal>
   );
 }

apps/dashboard/src/features/conversations/start-conversation-form.tsx

@@ -1,5 +1,11 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { RedditUsernameLink } from '../../components/reddit-username-link.js';
 import { useStartConversationMutation } from './conversation-queries.js';
+import { useRedditAccountsQuery } from '../settings/settings-queries.js';
+import { ownedConversationId } from './conversation-identity.js';
+
+const SUCCESS_NOTICE_DISMISS_MS = 5_000;
 
 interface StartConversationFormProps {
   onStarted(conversationId: string): void;
@@ -8,21 +14,45 @@ interface StartConversationFormProps {
 export function StartConversationForm({ onStarted }: StartConversationFormProps) {
   const [username, setUsername] = useState('');
   const [message, setMessage] = useState('');
+  const accountsQuery = useRedditAccountsQuery();
+  const runningAccounts = (accountsQuery.data ?? []).filter((account) => account.isRunning);
+  const [selectedAccountId, setSelectedAccountId] = useState('');
+  const accountId = selectedAccountId || runningAccounts[0]?.accountId || '';
   const [successUsername, setSuccessUsername] = useState<string | null>(null);
   const mutation = useStartConversationMutation();
-  const canSubmit = username.trim().length > 0 && message.trim().length > 0 && !mutation.isPending;
+  const canSubmit = accountId.length > 0 && username.trim().length > 0 && message.trim().length > 0 && !mutation.isPending;
+
+  useEffect(() => {
+    if (successUsername === null) return;
+    const timer = window.setTimeout(() => setSuccessUsername(null), SUCCESS_NOTICE_DISMISS_MS);
+    return () => window.clearTimeout(timer);
+  }, [successUsername]);
+
+  if (accountsQuery.isPending) {
+    return <p className="conversation-form-hint" role="status">Loading Reddit accounts…</p>;
+  }
+  if (accountsQuery.isError) {
+    return <div className="conversation-inline-error" role="alert">{accountsQuery.error.message}</div>;
+  }
+  if (runningAccounts.length === 0) {
+    return (
+      <p className="conversation-form-hint">
+        No running accounts — start one in <Link to="/settings">Settings</Link>.
+      </p>
+    );
+  }
 
   function submit(event: React.FormEvent<HTMLFormElement>) {
     event.preventDefault();
     if (!canSubmit) return;
     mutation.mutate(
-      { username, message },
+      { accountId, username, message },
       {
         onSuccess(chat) {
           setSuccessUsername(chat.username);
           setUsername('');
           setMessage('');
-          onStarted(chat.roomId ?? chat.username);
+          onStarted(ownedConversationId(chat));
         },
       },
     );
@@ -30,6 +60,12 @@ export function StartConversationForm({ onStarted }: StartConversationFormProps)
 
   return (
     <form className="start-conversation-form" onSubmit={submit}>
+      <div className="conversation-field">
+        <label htmlFor="new-conversation-account">Send from account</label>
+        <select id="new-conversation-account" onChange={(event) => setSelectedAccountId(event.target.value)} value={accountId}>
+          {runningAccounts.map((account) => <option key={account.accountId} value={account.accountId}>u/{account.redditUsername}</option>)}
+        </select>
+      </div>
       <div className="conversation-field">
         <label htmlFor="new-conversation-username">Reddit username</label>
         <input
@@ -53,7 +89,7 @@ export function StartConversationForm({ onStarted }: StartConversationFormProps)
       {mutation.isError ? <div className="conversation-inline-error" role="alert">{mutation.error.message}</div> : null}
       {successUsername ? (
         <div aria-label="Conversation started" className="conversation-inline-success" role="status">
-          Conversation started with u/{successUsername}
+          Conversation started with <RedditUsernameLink username={successUsername} />
         </div>
       ) : null}
       <button className="conversation-primary" disabled={!canSubmit} type="submit">

apps/dashboard/src/features/media-library/api.ts

@@ -0,0 +1,51 @@
+import type { ZodType } from 'zod';
+import {
+  ErrorResponseSchema,
+  MediaLibraryAssetSchema,
+  MediaLibraryResponseSchema,
+  type MediaLibraryAsset,
+  type MediaLibraryUpdate,
+} from '../../../../../packages/api-contracts/src/index.js';
+import { dashboardRequest } from '../../api/request.js';
+
+async function parseResponse<T>(response: Response, schema: ZodType<T>): Promise<T> {
+  const payload: unknown = await response.json();
+  if (!response.ok) {
+    const parsed = ErrorResponseSchema.safeParse(payload);
+    throw new Error(parsed.success ? parsed.data.error : `Request failed (${response.status})`);
+  }
+  return schema.parse(payload);
+}
+
+export function fetchMediaLibrary(): Promise<MediaLibraryAsset[]> {
+  return dashboardRequest('/api/media-library').then((response) => parseResponse(response, MediaLibraryResponseSchema));
+}
+
+export function uploadMediaLibraryImage(file: File): Promise<MediaLibraryAsset> {
+  return dashboardRequest('/api/media-library', {
+    method: 'POST',
+    headers: {
+      'Content-Type': file.type,
+      'X-File-Name': encodeURIComponent(file.name),
+      'X-Consent-Confirmed': 'true',
+    },
+    body: file,
+  }).then((response) => parseResponse(response, MediaLibraryAssetSchema));
+}
+
+export function updateMediaLibraryImage(id: string, update: MediaLibraryUpdate): Promise<MediaLibraryAsset> {
+  return dashboardRequest(`/api/media-library/${encodeURIComponent(id)}`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(update),
+  }).then((response) => parseResponse(response, MediaLibraryAssetSchema));
+}
+
+export async function deleteMediaLibraryImage(id: string): Promise<void> {
+  const response = await dashboardRequest(`/api/media-library/${encodeURIComponent(id)}`, { method: 'DELETE' });
+  const payload: unknown = await response.json();
+  if (!response.ok) {
+    const parsed = ErrorResponseSchema.safeParse(payload);
+    throw new Error(parsed.success ? parsed.data.error : `Request failed (${response.status})`);
+  }
+}

apps/dashboard/src/features/media-library/media-library-page.tsx

@@ -0,0 +1,307 @@
+import { useEffect, useRef, useState, type ChangeEvent } from 'react';
+import type { MediaLibraryAsset, MediaLibraryTag, MediaLibraryUpdate } from '../../../../../packages/api-contracts/src/index.js';
+import { MediaPreviewDialog } from '../media/media-preview-dialog.js';
+import { useDeleteMediaLibraryMutation, useMediaLibraryQuery, useUpdateMediaLibraryMutation, useUploadMediaLibraryMutation } from './queries.js';
+import './media-library.css';
+
+const TAGS: readonly MediaLibraryTag[] = ['selfie', 'chest', 'topless', 'feet', 'penis'];
+const MAX_UPLOAD_BYTES = 15 * 1024 * 1024;
+const NOTICE_MS = 5_000;
+
+export function MediaLibraryPage() {
+  const query = useMediaLibraryQuery();
+  const upload = useUploadMediaLibraryMutation();
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [file, setFile] = useState<File | null>(null);
+  const [fileError, setFileError] = useState<string | null>(null);
+  const [consent, setConsent] = useState(false);
+  const [thumbnailUrl, setThumbnailUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!file || typeof URL.createObjectURL !== 'function') {
+      setThumbnailUrl(null);
+      return;
+    }
+    const url = URL.createObjectURL(file);
+    setThumbnailUrl(url);
+    return () => {
+      if (typeof URL.revokeObjectURL === 'function') URL.revokeObjectURL(url);
+    };
+  }, [file]);
+
+  const uploadSucceeded = upload.isSuccess;
+  useEffect(() => {
+    if (!uploadSucceeded) return;
+    const timer = setTimeout(() => upload.reset(), NOTICE_MS);
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [uploadSucceeded]);
+
+  function handleFileChange(event: ChangeEvent<HTMLInputElement>) {
+    const picked = event.target.files?.[0] ?? null;
+    if (!picked) {
+      setFile(null);
+      setFileError(null);
+      return;
+    }
+    if (!picked.type.startsWith('image/')) {
+      setFile(null);
+      setFileError('Only image files can be uploaded.');
+      event.target.value = '';
+      return;
+    }
+    if (picked.size > MAX_UPLOAD_BYTES) {
+      setFile(null);
+      setFileError('Images must be 15 MB or smaller.');
+      event.target.value = '';
+      return;
+    }
+    setFileError(null);
+    setFile(picked);
+  }
+
+  if (query.isPending) return <div className="page-state" role="status"><span className="spinner" />Loading exchange library…</div>;
+  if (query.isError) {
+    return (
+      <div className="page-state error-state" role="alert">
+        <strong>Exchange library unavailable</strong>
+        <span>{query.error.message}</span>
+        <button
+          aria-busy={query.isFetching || undefined}
+          className="button secondary"
+          disabled={query.isFetching}
+          onClick={() => void query.refetch()}
+          type="button"
+        >
+          {query.isFetching ? 'Refreshing…' : 'Retry'}
+        </button>
+      </div>
+    );
+  }
+
+  const assets = query.data ?? [];
+  return (
+    <div className="page exchange-library-page">
+      <header className="page-header">
+        <div>
+          <span className="eyebrow">Operator-owned media</span>
+          <h1>Exchange library</h1>
+          <p>Add consented images, review the automatic anatomy classification, and control what the bot may send after a request.</p>
+        </div>
+      </header>
+
+      <section aria-label="Nonspecific request progression" className="exchange-ladder">
+        <div><span>First ask</span><strong>Random SFW</strong><small>Selfie, chest, or feet</small></div>
+        <div><span>Asked again</span><strong>Broader reveal</strong><small>SFW or topless</small></div>
+        <div><span>Further ask</span><strong>Full library</strong><small>Still exact-match when named</small></div>
+      </section>
+
+      <section className="panel library-upload-panel">
+        <div>
+          <span className="eyebrow">Add an image</span>
+          <h2>Strip metadata and classify</h2>
+          <p>JPEG, PNG, or WebP up to 15 MB. Location and camera metadata are removed before the cleaned image is sent to the configured OpenRouter model for classification.</p>
+        </div>
+        <label className="library-file-field">
+          <span>Choose image</span>
+          <input accept="image/jpeg,image/png,image/webp" onChange={handleFileChange} ref={fileInputRef} type="file" />
+          {thumbnailUrl ? <img alt={`Preview of ${file?.name ?? 'selected image'}`} className="library-upload-thumbnail" src={thumbnailUrl} /> : null}
+          <small>{file ? file.name : 'No image selected'}</small>
+        </label>
+        {fileError ? <div className="media-notice error" role="alert">{fileError}</div> : null}
+        <label className="library-consent-field">
+          <input checked={consent} onChange={(event) => setConsent(event.target.checked)} type="checkbox" />
+          <span>I confirm every depicted adult consented to this image being stored and sent by the bot.</span>
+        </label>
+        <button
+          aria-busy={upload.isPending || undefined}
+          className="button primary"
+          disabled={!file || !consent || upload.isPending}
+          onClick={() => file && upload.mutate(file, {
+            onSuccess: () => {
+              setFile(null);
+              setConsent(false);
+              if (fileInputRef.current) fileInputRef.current.value = '';
+            },
+          })}
+          type="button"
+        >
+          {upload.isPending ? 'Classifying…' : 'Upload and classify'}
+        </button>
+        {upload.isError ? <div className="media-notice error" role="alert">{upload.error.message}</div> : null}
+        {upload.isSuccess ? <div className="media-notice success" role="status">Image added. Review its tags before relying on it.</div> : null}
+      </section>
+
+      <div className="library-section-heading">
+        <div><span className="eyebrow">Available inventory</span><h2>{assets.length} {assets.length === 1 ? 'image' : 'images'}</h2></div>
+        <small>Images remain private and blurred until revealed.</small>
+      </div>
+      {assets.length === 0 ? (
+        <section className="panel empty-state"><strong>No exchange images yet.</strong><span>Add the first consented image above.</span></section>
+      ) : (
+        <section aria-label="Exchange library images" className="library-grid">
+          {assets.map((asset) => <LibraryAssetCard asset={asset} key={asset.id} />)}
+        </section>
+      )}
+    </div>
+  );
+}
+
+function LibraryAssetCard({ asset }: { asset: MediaLibraryAsset }) {
+  const updateMutation = useUpdateMediaLibraryMutation();
+  const deleteMutation = useDeleteMediaLibraryMutation();
+  const [revealed, setRevealed] = useState(false);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [isDirty, setIsDirty] = useState(false);
+  const [showSaved, setShowSaved] = useState(false);
+  const [isPreviewOpen, setIsPreviewOpen] = useState(false);
+  const [form, setForm] = useState<MediaLibraryUpdate>(() => ({
+    tags: asset.tags,
+    safety: asset.safety === 'nsfw' ? 'nsfw' : 'sfw',
+    enabled: asset.enabled,
+  }));
+
+  // Refetches must not clobber a form the operator has touched.
+  useEffect(() => {
+    if (isDirty) return;
+    setForm({ tags: asset.tags, safety: asset.safety === 'nsfw' ? 'nsfw' : 'sfw', enabled: asset.enabled });
+  }, [asset, isDirty]);
+
+  useEffect(() => {
+    if (!showSaved) return;
+    const timer = setTimeout(() => setShowSaved(false), NOTICE_MS);
+    return () => clearTimeout(timer);
+  }, [showSaved]);
+
+  // Armed delete confirmation reverts to the safe state if left alone.
+  useEffect(() => {
+    if (!confirmDelete) return;
+    const timer = setTimeout(() => setConfirmDelete(false), NOTICE_MS);
+    return () => clearTimeout(timer);
+  }, [confirmDelete]);
+
+  function editForm(update: (current: MediaLibraryUpdate) => MediaLibraryUpdate) {
+    setIsDirty(true);
+    setForm(update);
+  }
+
+  function toggleTag(tag: MediaLibraryTag) {
+    editForm((current) => ({
+      ...current,
+      tags: current.tags.includes(tag) ? current.tags.filter((item) => item !== tag) : [...current.tags, tag],
+    }));
+  }
+
+  const alt = `Library image tagged ${asset.tags.join(', ') || 'unclassified'}`;
+  const needsReview = asset.classificationStatus === 'failed' || asset.safety === 'unknown' || (asset.confidence ?? 0) < 0.7;
+  return (
+    <article className={asset.enabled ? 'library-card is-enabled' : 'library-card'}>
+      <div className="library-image-frame">
+        <button
+          aria-label={revealed ? `View ${asset.fileName} larger` : `Reveal library image ${asset.fileName}`}
+          className="library-image-button"
+          onClick={() => {
+            if (revealed) setIsPreviewOpen(true);
+            else setRevealed(true);
+          }}
+          type="button"
+        >
+          <img alt={alt} className={revealed ? '' : 'is-blurred'} src={asset.urlPath} />
+        </button>
+        <button
+          aria-label={revealed ? `Blur ${asset.fileName}` : `Reveal ${asset.fileName}`}
+          aria-pressed={revealed}
+          className="library-reveal"
+          onClick={() => setRevealed((value) => !value)}
+          type="button"
+        >
+          {revealed ? 'Blur' : 'Reveal'}
+        </button>
+        <span className={`library-safety is-${asset.safety}`}>{asset.safety.toUpperCase()}</span>
+      </div>
+      <div className="library-card-body">
+        <div className="library-card-title">
+          <strong>{asset.fileName}</strong>
+          <span className="library-card-pills">
+            {isDirty ? <span className="pill warning">Unsaved changes</span> : null}
+            <span className={asset.enabled ? 'pill success' : 'pill neutral'}>{asset.enabled ? 'Enabled' : 'Disabled'}</span>
+          </span>
+        </div>
+        {asset.description ? <p>{asset.description}</p> : <p>AI classification was unavailable. Add tags manually.</p>}
+        <small>{asset.width} × {asset.height} · {formatBytes(asset.sizeBytes)}{asset.confidence === null ? '' : ` · ${Math.round(asset.confidence * 100)}% confidence`}</small>
+        <small>{asset.sendCount === 0 ? 'Never sent' : `Sent ${asset.sendCount} ${asset.sendCount === 1 ? 'time' : 'times'}${asset.lastSentAt ? ` · last ${formatDate(asset.lastSentAt)}` : ''}`}</small>
+        <fieldset>
+          <legend>Anatomy tags</legend>
+          <div className="library-tag-grid">
+            {TAGS.map((tag) => <label key={tag}><input checked={form.tags.includes(tag)} onChange={() => toggleTag(tag)} type="checkbox" /><span>{tag}</span></label>)}
+          </div>
+        </fieldset>
+        <div className="library-controls">
+          <label>Safety<select onChange={(event) => editForm((current) => ({ ...current, safety: event.target.value as 'sfw' | 'nsfw' }))} value={form.safety}><option value="sfw">SFW</option><option value="nsfw">NSFW</option></select></label>
+          <div className="library-enable-group">
+            <label className="library-enable"><input checked={form.enabled} onChange={(event) => editForm((current) => ({ ...current, enabled: event.target.checked }))} type="checkbox" /><span>Available to bot</span></label>
+            {needsReview ? <div className="library-review-note" role="status">Review the AI result before enabling this image.</div> : null}
+          </div>
+        </div>
+        {updateMutation.isError ? <div className="media-notice error" role="alert">{updateMutation.error.message}</div> : null}
+        {deleteMutation.isError ? <div className="media-notice error" role="alert">{deleteMutation.error.message}</div> : null}
+        <div className="library-card-actions">
+          <button
+            aria-busy={updateMutation.isPending || undefined}
+            className="button primary"
+            disabled={form.tags.length === 0 || updateMutation.isPending}
+            onClick={() => updateMutation.mutate({ id: asset.id, update: form }, {
+              onSuccess: () => {
+                setIsDirty(false);
+                setShowSaved(true);
+              },
+            })}
+            type="button"
+          >
+            {updateMutation.isPending ? 'Saving…' : 'Save changes'}
+          </button>
+          {showSaved ? <span className="library-saved-notice" role="status">Saved</span> : null}
+          {confirmDelete ? (
+            <>
+              <button className="button secondary" onClick={() => setConfirmDelete(false)} type="button">Cancel</button>
+              <button
+                aria-busy={deleteMutation.isPending || undefined}
+                className="button danger"
+                disabled={deleteMutation.isPending}
+                onClick={() => deleteMutation.mutate(asset.id)}
+                type="button"
+              >
+                Confirm delete
+              </button>
+            </>
+          ) : (
+            <button className="button secondary" onClick={() => setConfirmDelete(true)} type="button">Delete</button>
+          )}
+        </div>
+        {form.tags.length === 0 ? <small className="library-save-hint">Select at least one tag to save</small> : null}
+      </div>
+      {isPreviewOpen ? (
+        <MediaPreviewDialog
+          entries={[{
+            id: asset.id,
+            src: asset.urlPath,
+            alt,
+            label: `Preview of ${asset.fileName}`,
+            captionTitle: asset.fileName,
+            captionSubtitle: `${asset.width} × ${asset.height}`,
+          }]}
+          index={0}
+          onClose={() => setIsPreviewOpen(false)}
+        />
+      ) : null}
+    </article>
+  );
+}
+
+function formatBytes(value: number): string {
+  return value < 1024 * 1024 ? `${Math.round(value / 1024)} KB` : `${(value / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatDate(value: number): string {
+  return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(value);
+}

apps/dashboard/src/features/media-library/media-library.css

@@ -0,0 +1,64 @@
+.exchange-library-page { --library-cyan: #7dd8d0; --library-violet: #b7a0ff; }
+.exchange-ladder { display: grid; gap: 1px; margin-bottom: 1rem; overflow: hidden; border: 1px solid var(--border); border-radius: .9rem; background: var(--border); }
+.exchange-ladder > div { position: relative; display: grid; gap: .25rem; min-height: 8rem; padding: 1.15rem; background: linear-gradient(145deg, #111c18, #14211d); }
+.exchange-ladder > div::after { content: ''; position: absolute; inset: auto 1.15rem 0; height: .2rem; background: var(--accent); }
+.exchange-ladder > div:nth-child(2)::after { background: var(--library-cyan); }
+.exchange-ladder > div:nth-child(3)::after { background: var(--library-violet); }
+.exchange-ladder span { color: var(--muted); font-size: .72rem; font-weight: 800; letter-spacing: .08em; text-transform: uppercase; }
+.exchange-ladder strong { align-self: end; font-size: 1.2rem; }
+.exchange-ladder small { color: var(--muted); }
+.library-upload-panel { display: grid; gap: 1rem; margin-bottom: 2rem; }
+.library-upload-panel p { margin: .35rem 0 0; color: var(--muted); }
+.library-file-field { display: grid; gap: .4rem; padding: 1rem; border: 1px dashed #4d685d; border-radius: .75rem; background: #0c1511; }
+.library-file-field span { font-weight: 750; }
+.library-file-field small { color: var(--muted); }
+.library-file-field input { color: var(--muted); }
+.library-consent-field, .library-enable { display: flex; align-items: flex-start; gap: .65rem; color: var(--muted); }
+.library-consent-field input, .library-enable input { flex: 0 0 auto; width: 1.1rem; height: 1.1rem; margin-top: .1rem; accent-color: var(--accent); }
+.library-upload-panel > .button { justify-self: start; }
+.library-section-heading { display: flex; align-items: end; justify-content: space-between; gap: 1rem; margin-bottom: 1rem; }
+.library-section-heading small { color: var(--muted); text-align: right; }
+.library-grid { display: grid; gap: 1rem; }
+.library-card { overflow: hidden; border: 1px solid var(--border); border-radius: .9rem; background: var(--surface); }
+.library-card.is-enabled { border-color: #386d4d; box-shadow: inset 0 0 0 1px rgba(117, 214, 157, .08); }
+.library-image-frame { position: relative; min-height: 17rem; overflow: hidden; background: #050907; }
+.library-image-button { display: block; width: 100%; padding: 0; border: 0; background: transparent; cursor: zoom-in; }
+.library-image-button:focus-visible { outline: 2px solid var(--accent); outline-offset: -4px; }
+.library-image-frame img { display: block; width: 100%; height: 17rem; object-fit: contain; transition: filter 180ms ease, transform 180ms ease; }
+.library-image-frame img.is-blurred { filter: blur(24px) brightness(.5); transform: scale(1.12); }
+.library-reveal { position: absolute; right: .75rem; bottom: .75rem; padding: .45rem .65rem; color: white; border: 1px solid rgba(255,255,255,.35); border-radius: .55rem; background: rgba(0,0,0,.78); font-weight: 750; }
+.library-safety { position: absolute; top: .75rem; left: .75rem; padding: .3rem .5rem; border-radius: 999px; color: #08110d; background: var(--muted); font-size: .68rem; font-weight: 900; letter-spacing: .08em; }
+.library-safety.is-sfw { background: var(--accent); }
+.library-safety.is-nsfw { color: #21132d; background: var(--library-violet); }
+.library-safety.is-unknown { color: var(--warning-text); background: var(--warning-bg); border: 1px solid var(--warning-border); }
+.library-card-body { display: grid; gap: .85rem; padding: 1rem; }
+.library-card-title { display: flex; align-items: flex-start; justify-content: space-between; gap: 1rem; }
+.library-card-title strong { overflow-wrap: anywhere; }
+.library-card-body p { margin: 0; color: var(--muted); line-height: 1.45; }
+.library-card-body > small { color: var(--muted); }
+.library-review-note { padding: .6rem .7rem; color: var(--warning-text); border: 1px solid var(--warning-border); border-radius: .55rem; background: var(--warning-bg); font-size: .82rem; }
+.library-card-pills { display: flex; flex-wrap: wrap; gap: .35rem; justify-content: flex-end; }
+.library-enable-group { display: grid; gap: .5rem; }
+.library-save-hint { color: var(--warning-text); }
+.library-saved-notice { align-self: center; color: var(--success-text); font-weight: 750; }
+.library-upload-thumbnail { display: block; max-width: 8rem; max-height: 8rem; border: 1px solid var(--border); border-radius: .5rem; object-fit: cover; }
+.library-card fieldset { padding: 0; margin: 0; border: 0; }
+.library-card legend { margin-bottom: .55rem; color: var(--muted); font-size: .78rem; font-weight: 750; }
+.library-tag-grid { display: flex; flex-wrap: wrap; gap: .45rem; }
+.library-tag-grid label { position: relative; }
+.library-tag-grid input { position: absolute; opacity: 0; pointer-events: none; }
+.library-tag-grid span { display: block; padding: .35rem .6rem; border: 1px solid var(--border); border-radius: 999px; color: var(--muted); background: #0c1511; text-transform: capitalize; cursor: pointer; }
+.library-tag-grid input:checked + span { color: #07130c; border-color: var(--accent); background: var(--accent); font-weight: 800; }
+.library-tag-grid input:focus-visible + span { outline: 2px solid white; outline-offset: 2px; }
+.library-controls { display: grid; gap: .8rem; }
+.library-controls > label:first-child { display: grid; gap: .35rem; color: var(--muted); font-size: .8rem; font-weight: 750; }
+.library-controls select { min-height: 2.5rem; padding: .45rem; color: white; border: 1px solid var(--border); border-radius: .55rem; background: var(--surface-raised); }
+.library-card-actions { display: flex; flex-wrap: wrap; gap: .55rem; padding-top: .25rem; }
+@media (min-width: 48rem) {
+  .exchange-ladder { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+  .library-upload-panel { grid-template-columns: minmax(16rem, 1fr) minmax(18rem, 1.2fr); align-items: center; }
+  .library-upload-panel .library-consent-field, .library-upload-panel .media-notice { grid-column: 1 / -1; }
+  .library-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .library-controls { grid-template-columns: 1fr 1fr; align-items: end; }
+}
+@media (prefers-reduced-motion: reduce) { .library-image-frame img { transition: none; } }

apps/dashboard/src/features/media-library/queries.ts

@@ -0,0 +1,33 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { MediaLibraryUpdate } from '../../../../../packages/api-contracts/src/index.js';
+import { deleteMediaLibraryImage, fetchMediaLibrary, updateMediaLibraryImage, uploadMediaLibraryImage } from './api.js';
+
+export const mediaLibraryQueryKey = ['dashboard', 'media-library'] as const;
+
+export function useMediaLibraryQuery() {
+  return useQuery({ queryKey: mediaLibraryQueryKey, queryFn: fetchMediaLibrary });
+}
+
+export function useUploadMediaLibraryMutation() {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: uploadMediaLibraryImage,
+    onSuccess: () => client.invalidateQueries({ queryKey: mediaLibraryQueryKey }),
+  });
+}
+
+export function useUpdateMediaLibraryMutation() {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, update }: { id: string; update: MediaLibraryUpdate }) => updateMediaLibraryImage(id, update),
+    onSuccess: () => client.invalidateQueries({ queryKey: mediaLibraryQueryKey }),
+  });
+}
+
+export function useDeleteMediaLibraryMutation() {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: deleteMediaLibraryImage,
+    onSuccess: () => client.invalidateQueries({ queryKey: mediaLibraryQueryKey }),
+  });
+}

apps/dashboard/src/features/media/api.ts

@@ -7,6 +7,7 @@ import {
   type MediaItem,
   type MediaSyncStatus,
 } from '../../../../../packages/api-contracts/src/index.js';
+import { dashboardRequest } from '../../api/request.js';
 
 async function parseResponse<T>(response: Response, schema: ZodType<T>): Promise<T> {
   const payload: unknown = await response.json();
@@ -18,7 +19,7 @@ async function parseResponse<T>(response: Response, schema: ZodType<T>): Promise
 }
 
 function request(path: string, init?: RequestInit): Promise<Response> {
-  return globalThis.fetch(path, { credentials: 'same-origin', ...init });
+  return dashboardRequest(path, init);
 }
 
 export async function fetchMedia(): Promise<MediaItem[]> {

apps/dashboard/src/features/media/filters.ts

@@ -15,6 +15,12 @@ export function mediaType(item: MediaItem): 'image' | 'gif' {
   return item.fileName.toLowerCase().endsWith('.gif') ? 'gif' : 'image';
 }
 
+export function mediaAlt(item: MediaItem): string {
+  const kind = mediaType(item) === 'gif' ? 'GIF' : 'Image';
+  const date = new Intl.DateTimeFormat(undefined, { day: 'numeric', month: 'short' }).format(item.timestamp);
+  return `${kind} from u/${item.sender}, ${date}`;
+}
+
 export function filterMedia(items: MediaItem[], filters: MediaFilters, now: number): MediaItem[] {
   const rangeMs = {
     all: null,
@@ -23,11 +29,13 @@ export function filterMedia(items: MediaItem[], filters: MediaFilters, now: numb
     '30d': 30 * 86_400_000,
   }[filters.dateRange];
 
-  return items.filter((item) => {
+  return items
+    .filter((item) => {
       if (filters.conversation !== 'all' && mediaConversation(item) !== filters.conversation) return false;
       if (filters.sender !== 'all' && item.sender !== filters.sender) return false;
       if (filters.type !== 'all' && mediaType(item) !== filters.type) return false;
       if (rangeMs !== null && item.timestamp < now - rangeMs) return false;
       return true;
-  });
+    })
+    .sort((left, right) => right.timestamp - left.timestamp);
 }

apps/dashboard/src/features/media/full-sync-dialog.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { Modal } from '../../components/modal.js';
 
 interface FullSyncDialogProps {
   isPending: boolean;
@@ -7,27 +7,24 @@ interface FullSyncDialogProps {
 }
 
 export function FullSyncDialog({ isPending, onCancel, onConfirm }: FullSyncDialogProps) {
-  const cancelButtonRef = useRef<HTMLButtonElement>(null);
-
-  useEffect(() => {
-    cancelButtonRef.current?.focus();
-  }, []);
-
   return (
-    <div aria-labelledby="full-sync-title" aria-modal="true" className="dialog-backdrop" role="dialog">
-      <div className="dialog-card">
+    <Modal
+      className="dialog-card"
+      isDismissLocked={isPending}
+      labelledBy="full-sync-title"
+      onClose={onCancel}
+    >
       <span className="eyebrow">Confirm expensive action</span>
       <h2 id="full-sync-title">Run full media sync?</h2>
       <p>This scans every conversation and can take several minutes. Routine refreshes should use Sync new media.</p>
       <div className="dialog-actions">
-          <button className="button secondary" disabled={isPending} onClick={onCancel} ref={cancelButtonRef} type="button">
+        <button autoFocus className="button secondary" disabled={isPending} onClick={onCancel} type="button">
           Cancel
         </button>
-          <button className="button danger" disabled={isPending} onClick={onConfirm} type="button">
+        <button aria-busy={isPending || undefined} className="button danger" disabled={isPending} onClick={onConfirm} type="button">
           {isPending ? 'Syncing…' : 'Run full sync'}
         </button>
       </div>
-      </div>
-    </div>
+    </Modal>
   );
 }

apps/dashboard/src/features/media/media-card.tsx

@@ -1,38 +1,62 @@
 import type { MediaItem } from '../../../../../packages/api-contracts/src/index.js';
-import { mediaConversation, mediaType } from './filters.js';
+import { Link } from 'react-router-dom';
+import { RedditUsernameLink } from '../../components/reddit-username-link.js';
+import { createOwnedConversationId } from '../conversations/conversation-identity.js';
+import { mediaAlt, mediaConversation, mediaType } from './filters.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
 
 interface MediaCardProps {
   item: MediaItem;
   isRevealed: boolean;
   onToggleReveal(): void;
+  onOpenPreview(): void;
 }
 
 function formatMediaDate(timestamp: number): string {
   return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(timestamp);
 }
 
-export function MediaCard({ item, isRevealed, onToggleReveal }: MediaCardProps) {
+export function MediaCard({ item, isRevealed, onToggleReveal, onOpenPreview }: MediaCardProps) {
+  const conversationId = item.chatRoomId ?? item.chatUsername;
+  const conversationPath = conversationId
+    ? `/conversations/${encodeURIComponent(createOwnedConversationId(item.owner?.accountId, conversationId))}`
+    : null;
+
   return (
     <article className="media-card">
       <div className="media-preview">
-        <img
-          alt={`Media from ${item.sender}`}
-          className={isRevealed ? 'media-image' : 'media-image is-blurred'}
-          loading="lazy"
-          src={item.urlPath}
-        />
+        <button
+          aria-label={isRevealed ? `View media from ${item.sender} larger` : `Reveal media from ${item.sender}`}
+          className="media-preview-button"
+          onClick={() => {
+            if (isRevealed) onOpenPreview();
+            else onToggleReveal();
+          }}
+          type="button"
+        >
+          <img alt={mediaAlt(item)} className={isRevealed ? 'media-image' : 'media-image is-blurred'} loading="lazy" src={item.urlPath} />
+        </button>
         {!isRevealed ? <span className="privacy-label">Private media hidden</span> : null}
       </div>
       <div className="media-card-body">
+        <AccountOwnerBadge owner={item.owner} />
         <div>
-          <strong>{item.sender}</strong>
-          <span>{mediaConversation(item)}</span>
+          <strong><span className="media-link-prefix">From</span> <RedditUsernameLink showPrefix={false} username={item.sender} /></strong>
+          <span><span className="media-link-prefix">Conversation</span> {item.chatUsername
+            ? <RedditUsernameLink showPrefix={false} username={item.chatUsername} />
+            : mediaConversation(item)}</span>
         </div>
         <dl>
           <div><dt>Type</dt><dd>{mediaType(item) === 'gif' ? 'GIF' : 'Image'}</dd></div>
           <div><dt>Received</dt><dd>{formatMediaDate(item.timestamp)}</dd></div>
         </dl>
+        {conversationPath ? (
+          <Link className="button secondary media-conversation-link" to={conversationPath}>
+            Open conversation
+          </Link>
+        ) : null}
         <button
+          aria-pressed={isRevealed}
           className="button secondary media-reveal"
           onClick={onToggleReveal}
           type="button"

apps/dashboard/src/features/media/media-page.tsx

@@ -1,17 +1,21 @@
-import { useMemo, useState } from 'react';
-import { filterMedia, mediaConversation, type MediaFilters } from './filters.js';
+import { useEffect, useMemo, useState } from 'react';
+import { filterMedia, mediaAlt, mediaConversation, type MediaFilters } from './filters.js';
 import { FullSyncDialog } from './full-sync-dialog.js';
 import { MediaCard } from './media-card.js';
+import { MediaPreviewDialog, type MediaPreviewEntry } from './media-preview-dialog.js';
 import { useMediaQuery, useMediaSyncStatusQuery, useTriggerMediaSyncMutation } from './queries.js';
 import './media.css';
 
-const initialFilters: MediaFilters = {
+export const initialMediaFilters: MediaFilters = {
   conversation: 'all',
   sender: 'all',
   type: 'all',
   dateRange: 'all',
 };
 
+const PAGE_SIZE = 48;
+const SUCCESS_NOTICE_MS = 5_000;
+
 function errorMessage(error: Error | null): string {
   return error?.message ?? 'Something went wrong.';
 }
@@ -20,17 +24,26 @@ function formatLastSync(timestamp: number): string {
   return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(timestamp);
 }
 
-export function MediaPage() {
+export interface MediaPageProps {
+  filters?: MediaFilters;
+  onFiltersChange?(filters: MediaFilters): void;
+}
+
+export function MediaPage({ filters: controlledFilters, onFiltersChange }: MediaPageProps) {
   const mediaQuery = useMediaQuery();
   const statusQuery = useMediaSyncStatusQuery();
   const syncMutation = useTriggerMediaSyncMutation();
-  const [filters, setFilters] = useState<MediaFilters>(initialFilters);
+  const [localFilters, setLocalFilters] = useState<MediaFilters>(initialMediaFilters);
+  const filters = controlledFilters ?? localFilters;
   const [revealedIds, setRevealedIds] = useState<Set<string>>(() => new Set());
   const [isRevealAll, setIsRevealAll] = useState(false);
   const [isFullSyncDialogOpen, setIsFullSyncDialogOpen] = useState(false);
+  const [previewItemId, setPreviewItemId] = useState<string | null>(null);
+  const [visibleLimit, setVisibleLimit] = useState(PAGE_SIZE);
 
   const items = mediaQuery.data ?? [];
   const visibleItems = useMemo(() => filterMedia(items, filters, Date.now()), [items, filters]);
+  const displayedItems = visibleItems.slice(0, visibleLimit);
   const conversations = useMemo(
     () => [...new Set(items.map(mediaConversation))].sort((left, right) => left.localeCompare(right)),
     [items],
@@ -40,9 +53,37 @@ export function MediaPage() {
     [items],
   );
   const isSyncBusy = statusQuery.data?.isSyncing === true || syncMutation.isPending;
+  const isFiltered = filters.conversation !== 'all' || filters.sender !== 'all' || filters.type !== 'all' || filters.dateRange !== 'all';
+  const previewIndex = previewItemId === null ? -1 : visibleItems.findIndex((item) => item.id === previewItemId);
+  const previewEntries: MediaPreviewEntry[] = useMemo(
+    () => visibleItems.map((item) => ({
+      id: item.id,
+      src: item.urlPath,
+      alt: mediaAlt(item),
+      label: `Media from ${item.sender}`,
+      captionTitle: `u/${item.sender}`,
+      captionSubtitle: formatLastSync(item.timestamp),
+    })),
+    [visibleItems],
+  );
+
+  const isSyncSuccess = syncMutation.isSuccess;
+  useEffect(() => {
+    if (!isSyncSuccess) return;
+    const timer = setTimeout(() => syncMutation.reset(), SUCCESS_NOTICE_MS);
+    return () => clearTimeout(timer);
+    // syncMutation is a fresh object every render; keying on isSuccess is intentional.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isSyncSuccess]);
+
+  function updateFilters(next: MediaFilters) {
+    if (controlledFilters === undefined) setLocalFilters(next);
+    onFiltersChange?.(next);
+    setVisibleLimit(PAGE_SIZE);
+  }
 
   function updateFilter<Key extends keyof MediaFilters>(key: Key, value: MediaFilters[Key]) {
-    setFilters((current) => ({ ...current, [key]: value }));
+    updateFilters({ ...filters, [key]: value });
   }
 
   function toggleItem(itemId: string) {
@@ -79,7 +120,15 @@ export function MediaPage() {
       <div className="page-state error-state" role="alert">
         <strong>Media unavailable</strong>
         <span>{errorMessage(mediaQuery.error)}</span>
-        <button className="button secondary" onClick={() => void mediaQuery.refetch()} type="button">Retry media</button>
+        <button
+          aria-busy={mediaQuery.isFetching || undefined}
+          className="button secondary"
+          disabled={mediaQuery.isFetching}
+          onClick={() => void mediaQuery.refetch()}
+          type="button"
+        >
+          {mediaQuery.isFetching ? 'Refreshing…' : 'Retry media'}
+        </button>
       </div>
     );
   }
@@ -95,11 +144,9 @@ export function MediaPage() {
         <div className="header-actions">
           {items.length > 0 ? (
             <button
+              aria-pressed={isRevealAll}
               className="button secondary"
-              onClick={() => {
-                setIsRevealAll((current) => !current);
-                setRevealedIds(new Set());
-              }}
+              onClick={() => setIsRevealAll((current) => !current)}
               type="button"
             >
               {isRevealAll ? 'Blur all media' : 'Reveal all media'}
@@ -116,7 +163,7 @@ export function MediaPage() {
           >
             Full sync
           </button>
-          <button className="button primary" disabled={isSyncBusy} onClick={() => runSync(false)} type="button">
+          <button aria-busy={isSyncBusy || undefined} className="button primary" disabled={isSyncBusy} onClick={() => runSync(false)} type="button">
             {isSyncBusy ? 'Syncing…' : 'Sync new media'}
           </button>
         </div>
@@ -127,7 +174,15 @@ export function MediaPage() {
         {statusQuery.isError ? (
           <div role="alert">
             <span>{errorMessage(statusQuery.error)}</span>
-            <button className="button secondary" onClick={() => void statusQuery.refetch()} type="button">Retry sync status</button>
+            <button
+              aria-busy={statusQuery.isFetching || undefined}
+              className="button secondary"
+              disabled={statusQuery.isFetching}
+              onClick={() => void statusQuery.refetch()}
+              type="button"
+            >
+              {statusQuery.isFetching ? 'Refreshing…' : 'Retry sync status'}
+            </button>
           </div>
         ) : null}
         {statusQuery.data ? (
@@ -177,21 +232,45 @@ export function MediaPage() {
                 <option value="all">Any time</option><option value="24h">Past 24 hours</option><option value="7d">Past 7 days</option><option value="30d">Past 30 days</option>
               </select>
             </label>
+            <div className="media-filter-summary">
+              <span role="status">Showing {displayedItems.length} of {items.length} items</span>
+              {isFiltered ? (
+                <button className="button secondary" onClick={() => updateFilters(initialMediaFilters)} type="button">
+                  Clear filters
+                </button>
+              ) : null}
+            </div>
           </section>
 
           {visibleItems.length === 0 ? (
-            <section className="panel empty-state"><strong>No media matches these filters.</strong><span>Try broadening one or more filters.</span></section>
+            <section className="panel empty-state">
+              <strong>No media matches these filters.</strong>
+              <span>Try broadening one or more filters.</span>
+              <button className="button secondary" onClick={() => updateFilters(initialMediaFilters)} type="button">
+                Clear filters
+              </button>
+            </section>
           ) : (
+            <>
               <section aria-label="Media gallery" className="media-grid">
-              {visibleItems.map((item) => (
+                {displayedItems.map((item) => (
                   <MediaCard
                     isRevealed={isRevealAll || revealedIds.has(item.id)}
                     item={item}
                     key={item.id}
+                    onOpenPreview={() => setPreviewItemId(item.id)}
                     onToggleReveal={() => toggleItem(item.id)}
                   />
                 ))}
               </section>
+              {visibleItems.length > displayedItems.length ? (
+                <div className="media-load-more">
+                  <button className="button secondary" onClick={() => setVisibleLimit((current) => current + PAGE_SIZE)} type="button">
+                    Load more ({visibleItems.length - displayedItems.length} remaining)
+                  </button>
+                </div>
+              ) : null}
+            </>
           )}
         </>
       )}
@@ -203,6 +282,14 @@ export function MediaPage() {
           onConfirm={() => runSync(true)}
         />
       ) : null}
+      {previewIndex >= 0 ? (
+        <MediaPreviewDialog
+          entries={previewEntries}
+          index={previewIndex}
+          onClose={() => setPreviewItemId(null)}
+          onNavigate={(nextIndex) => setPreviewItemId(visibleItems[nextIndex]?.id ?? null)}
+        />
+      ) : null}
     </div>
   );
 }

apps/dashboard/src/features/media/media-preview-dialog.tsx

@@ -0,0 +1,119 @@
+import { useEffect, useState } from 'react';
+import { Modal } from '../../components/modal.js';
+
+export interface MediaPreviewEntry {
+  id: string;
+  src: string;
+  alt: string;
+  /** Accessible name for the dialog. */
+  label: string;
+  /** Caption bar: sender (or file name) plus optional date line. */
+  captionTitle: string;
+  captionSubtitle?: string;
+}
+
+interface MediaPreviewDialogProps {
+  entries: MediaPreviewEntry[];
+  index: number;
+  onNavigate?(index: number): void;
+  onClose(): void;
+}
+
+/**
+ * Full-screen lightbox for conversation and library media. When more than one
+ * entry is provided, previous/next buttons and ArrowLeft/ArrowRight navigate
+ * the visible set.
+ */
+export function MediaPreviewDialog({ entries, index, onNavigate, onClose }: MediaPreviewDialogProps) {
+  const entry = entries[index];
+  const [isLoaded, setIsLoaded] = useState(false);
+  useEffect(() => {
+    setIsLoaded(false);
+  }, [entry?.src]);
+
+  const hasPrevious = index > 0;
+  const hasNext = index < entries.length - 1;
+  const canNavigate = entries.length > 1 && onNavigate !== undefined;
+
+  // Arrow keys navigate regardless of which control inside the modal holds
+  // focus (a nav button can become disabled, dropping focus).
+  useEffect(() => {
+    if (!canNavigate) return;
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === 'ArrowLeft' && hasPrevious) {
+        event.preventDefault();
+        onNavigate?.(index - 1);
+      } else if (event.key === 'ArrowRight' && hasNext) {
+        event.preventDefault();
+        onNavigate?.(index + 1);
+      }
+    }
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [canNavigate, hasPrevious, hasNext, index, onNavigate]);
+
+  if (!entry) return null;
+
+  function goPrevious() {
+    if (hasPrevious) onNavigate?.(index - 1);
+  }
+
+  function goNext() {
+    if (hasNext) onNavigate?.(index + 1);
+  }
+
+  return (
+    <Modal className="media-preview-dialog" closeOnBackdrop label={entry.label} onClose={onClose}>
+      <div className="media-preview-dialog-content">
+        {!isLoaded ? (
+          <span className="media-preview-dialog-loading" role="status">
+            <span className="spinner" />
+            <span className="sr-only">Loading full-size media</span>
+          </span>
+        ) : null}
+        <img
+          alt={entry.alt}
+          className={isLoaded ? 'media-preview-dialog-image' : 'media-preview-dialog-image is-loading'}
+          onLoad={() => setIsLoaded(true)}
+          src={entry.src}
+        />
+        <button
+          aria-label="Close media preview"
+          autoFocus
+          className="media-preview-dialog-close"
+          onClick={onClose}
+          type="button"
+        >
+          ×
+        </button>
+        {canNavigate ? (
+          <>
+            <button
+              aria-label="Previous media"
+              className="media-preview-dialog-nav is-previous"
+              disabled={!hasPrevious}
+              onClick={goPrevious}
+              type="button"
+            >
+              ‹
+            </button>
+            <button
+              aria-label="Next media"
+              className="media-preview-dialog-nav is-next"
+              disabled={!hasNext}
+              onClick={goNext}
+              type="button"
+            >
+              ›
+            </button>
+          </>
+        ) : null}
+        <div className="media-preview-dialog-caption">
+          <strong>{entry.captionTitle}</strong>
+          {entry.captionSubtitle ? <span>{entry.captionSubtitle}</span> : null}
+          {canNavigate ? <span>{index + 1} of {entries.length}</span> : null}
+        </div>
+      </div>
+    </Modal>
+  );
+}

apps/dashboard/src/features/media/media-route.tsx

@@ -0,0 +1,32 @@
+import { useSearchParams } from 'react-router-dom';
+import type { MediaFilters } from './filters.js';
+import { initialMediaFilters, MediaPage } from './media-page.js';
+
+function parseType(value: string | null): MediaFilters['type'] {
+  return value === 'image' || value === 'gif' ? value : 'all';
+}
+
+function parseDateRange(value: string | null): MediaFilters['dateRange'] {
+  return value === '24h' || value === '7d' || value === '30d' ? value : 'all';
+}
+
+export function MediaRoute() {
+  const [searchParams, setSearchParams] = useSearchParams();
+  const filters: MediaFilters = {
+    conversation: searchParams.get('conversation') ?? initialMediaFilters.conversation,
+    sender: searchParams.get('sender') ?? initialMediaFilters.sender,
+    type: parseType(searchParams.get('type')),
+    dateRange: parseDateRange(searchParams.get('range')),
+  };
+
+  function updateFilters(next: MediaFilters) {
+    const params = new URLSearchParams();
+    if (next.conversation !== 'all') params.set('conversation', next.conversation);
+    if (next.sender !== 'all') params.set('sender', next.sender);
+    if (next.type !== 'all') params.set('type', next.type);
+    if (next.dateRange !== 'all') params.set('range', next.dateRange);
+    setSearchParams(params, { replace: true });
+  }
+
+  return <MediaPage filters={filters} onFiltersChange={updateFilters} />;
+}

apps/dashboard/src/features/media/media.css

@@ -3,27 +3,50 @@
 .media-sync-status > div[role="alert"] { width: 100%; justify-content: space-between; }
 .media-sync-status .spinner { width: 1rem; height: 1rem; }
 .media-notice { padding: .8rem 1rem; margin-bottom: 1rem; border-radius: .75rem; font-weight: 700; }
-.media-notice.success { color: #aaf0c4; background: #163a26; border: 1px solid #28593d; }
-.media-notice.error { color: #ffd1ce; background: #461b18; border: 1px solid #80352f; }
+.media-notice.success { color: var(--success-text); background: var(--success-bg); border: 1px solid var(--success-border); }
+.media-notice.error { color: var(--danger-text); background: var(--danger-bg); border: 1px solid var(--danger-border); }
 .media-filters { display: grid; grid-template-columns: 1fr; gap: .8rem; margin-bottom: 1rem; }
 .media-filters label { display: grid; gap: .35rem; color: var(--muted); font-size: .78rem; font-weight: 750; }
 .media-filters select { width: 100%; min-height: 2.6rem; padding: .5rem .7rem; color: #e9f1ec; background: var(--surface-raised); border: 1px solid var(--border); border-radius: .6rem; }
-.media-filters select:focus-visible, .media-reveal:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.media-filters select:focus-visible, .media-reveal:focus-visible, .media-conversation-link:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.media-filter-summary { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: .6rem; grid-column: 1 / -1; color: var(--muted); font-size: .82rem; }
 .media-grid { display: grid; grid-template-columns: 1fr; gap: 1rem; }
+.media-load-more { display: flex; justify-content: center; margin-top: 1rem; }
 .media-card { min-width: 0; overflow: hidden; background: var(--surface); border: 1px solid var(--border); border-radius: .9rem; }
 .media-preview { position: relative; display: grid; place-items: center; aspect-ratio: 4 / 3; overflow: hidden; background: #050907; }
+.media-preview-button { width: 100%; height: 100%; padding: 0; border: 0; background: transparent; cursor: zoom-in; }
+.media-preview-button:focus-visible { outline: 2px solid var(--accent); outline-offset: -4px; }
 .media-image { width: 100%; height: 100%; object-fit: cover; transition: filter 160ms ease, transform 160ms ease; }
 .media-image.is-blurred { filter: blur(24px) brightness(.55); transform: scale(1.12); }
 .privacy-label { position: absolute; padding: .45rem .65rem; color: white; background: rgba(0, 0, 0, .72); border-radius: 999px; font-size: .75rem; font-weight: 800; }
 .media-card-body { display: grid; gap: .8rem; padding: .9rem; }
 .media-card-body > div:first-child { display: flex; justify-content: space-between; gap: .75rem; }
 .media-card-body > div:first-child span { color: var(--muted); }
+.media-link-prefix { color: var(--muted); font-size: .72rem; font-weight: 800; letter-spacing: .05em; text-transform: uppercase; }
 .media-card-body dl { display: grid; gap: .4rem; margin: 0; }
 .media-card-body dl div { display: flex; justify-content: space-between; gap: .75rem; }
 .media-card-body dt { color: var(--muted); }
 .media-card-body dd { margin: 0; text-align: right; }
+.media-conversation-link { display: flex; align-items: center; justify-content: center; width: 100%; text-decoration: none; }
 .media-reveal { width: 100%; }
 
+/* Full-screen lightbox rendered through the shared <dialog> Modal. */
+dialog.media-preview-dialog { width: 100vw; height: 100vh; max-width: 100vw; max-height: 100vh; padding: 1rem; border: 0; background: transparent; }
+dialog.media-preview-dialog::backdrop { background: rgba(0, 0, 0, .9); }
+.media-preview-dialog-content { position: relative; display: flex; align-items: center; justify-content: center; width: 100%; height: 100%; }
+.media-preview-dialog-image { display: block; width: auto; height: auto; max-width: 100%; max-height: calc(100% - 3.6rem); object-fit: contain; }
+.media-preview-dialog-image.is-loading { opacity: 0; }
+.media-preview-dialog-loading { position: absolute; display: grid; place-items: center; color: white; }
+.media-preview-dialog-close { position: absolute; top: .5rem; right: .5rem; width: 2.75rem; height: 2.75rem; padding: 0; border: 1px solid rgba(255, 255, 255, .5); border-radius: 50%; color: white; background: rgba(0, 0, 0, .7); font-size: 2rem; line-height: 1; cursor: pointer; }
+.media-preview-dialog-close:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+.media-preview-dialog-nav { position: absolute; top: 50%; width: 2.75rem; height: 2.75rem; padding: 0; transform: translateY(-50%); border: 1px solid rgba(255, 255, 255, .5); border-radius: 50%; color: white; background: rgba(0, 0, 0, .7); font-size: 1.8rem; line-height: 1; cursor: pointer; }
+.media-preview-dialog-nav:disabled { opacity: .35; }
+.media-preview-dialog-nav.is-previous { left: .5rem; }
+.media-preview-dialog-nav.is-next { right: .5rem; }
+.media-preview-dialog-nav:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+.media-preview-dialog-caption { position: absolute; bottom: 0; left: 50%; display: flex; flex-wrap: wrap; align-items: baseline; justify-content: center; gap: .35rem .8rem; max-width: 100%; padding: .55rem .9rem; transform: translateX(-50%); color: white; background: rgba(0, 0, 0, .72); border-radius: .6rem .6rem 0 0; font-size: .82rem; }
+.media-preview-dialog-caption span { color: rgba(255, 255, 255, .75); }
+
 @media (min-width: 40rem) {
   .media-filters { grid-template-columns: repeat(2, minmax(0, 1fr)); }
   .media-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }

apps/dashboard/src/features/operations/live-console-model.ts

@@ -24,7 +24,8 @@ export type LiveConsoleAction =
   | { type: 'set-paused'; paused: boolean }
   | { type: 'set-auto-scroll'; enabled: boolean }
   | { type: 'set-level'; level: ConsoleLevelFilter }
-  | { type: 'set-search'; search: string };
+  | { type: 'set-search'; search: string }
+  | { type: 'clear' };
 
 function boundedAppend(
   entries: readonly ConsoleEntry[],
@@ -89,6 +90,8 @@ export function reduceLiveConsoleState(
       return { ...state, level: action.level };
     case 'set-search':
       return { ...state, search: action.search };
+    case 'clear':
+      return { ...state, entries: [], pendingEntries: [] };
   }
 }
 

apps/dashboard/src/features/operations/operations-api.ts

@@ -2,7 +2,10 @@ import { z } from 'zod';
 import {
   ActivityResponseSchema,
   ChatSyncStatusSchema,
+  ChatSyncTriggerResponseSchema,
+  FetchAllChatsResponseSchema,
 } from '../../../../../packages/api-contracts/src/index.js';
+import { createDashboardRequest } from '../../api/request.js';
 
 export const RawLogEntrySchema = z.strictObject({
   timestamp: z.number(),
@@ -32,9 +35,7 @@ async function parseResponse<T>(
 }
 
 export function createOperationsApi(fetchImplementation?: typeof fetch) {
-  function request(path: string): Promise<Response> {
-    return (fetchImplementation ?? globalThis.fetch)(path);
-  }
+  const request = createDashboardRequest(fetchImplementation);
   return {
     async getActivity() {
       return parseResponse(await request('/api/activity'), ActivityResponseSchema);
@@ -48,6 +49,18 @@ export function createOperationsApi(fetchImplementation?: typeof fetch) {
     async getSyncStatus() {
       return parseResponse(await request('/api/chats/sync'), ChatSyncStatusSchema);
     },
+    async triggerSync(kind: 'delta' | 'full') {
+      const result = await parseResponse(
+        await request(`/api/chats/sync/${kind}`, { method: 'POST' }),
+        ChatSyncTriggerResponseSchema,
+      );
+      if (!('success' in result)) throw new Error(result.error);
+      if (!result.success) throw new Error(result.reason);
+      return result;
+    },
+    async fetchAllChats() {
+      return parseResponse(await request('/api/chats/fetch-all', { method: 'POST' }), FetchAllChatsResponseSchema);
+    },
   };
 }
 

apps/dashboard/src/features/operations/operations-page.tsx

@@ -1,6 +1,11 @@
 import { useEffect, useReducer, useRef, useState } from 'react';
-import { useQueryClient } from '@tanstack/react-query';
-import type { ActivityItem, ChatSyncStatus, DashboardEvent } from '../../../../../packages/api-contracts/src/index.js';
+import type { ActivityItem, ChatSyncStatus, DashboardEvent, RedditAccountOwner } from '../../../../../packages/api-contracts/src/index.js';
+import { useDashboardRealtime } from '../../app/realtime-provider.js';
+import { Modal } from '../../components/modal.js';
+import { RedditUsernameLink } from '../../components/reddit-username-link.js';
+import { RedditUserText } from '../../components/reddit-user-text.js';
+import { OriginPostButton } from '../../components/origin-post.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
 import {
   createLiveConsoleState,
   reduceLiveConsoleState,
@@ -8,13 +13,8 @@ import {
   type ConsoleEntry,
   type ConsoleLevelFilter,
 } from './live-console-model.js';
-import { useActivityQuery, useLogsQuery, useSyncStatusQuery } from './operations-queries.js';
-import {
-  createBrowserEventSource,
-  createDashboardRealtimeClient,
-  queryKeysForDashboardEvent,
-  type RealtimeConnectionSnapshot,
-} from './realtime-client.js';
+import { useActivityQuery, useFetchAllChatsMutation, useLogsQuery, useSyncStatusQuery, useTriggerChatSyncMutation } from './operations-queries.js';
+import type { RealtimeConnectionSnapshot } from './realtime-client.js';
 import './operations.css';
 
 function formatTimestamp(timestamp: number | string): string {
@@ -29,10 +29,15 @@ function ActivityView({ items }: { items: readonly ActivityItem[] }) {
     <p className="feature-empty">No recent operator activity.</p>
   ) : (
     <ol className="operations-activity-list">
-      {items.map((item) => (
-        <li key={`${item.timestamp}-${item.message}`}>
+      {items.map((item, index) => (
+        <li key={`${item.timestamp}-${index}`}>
           <span className={`activity-marker ${item.type}`} aria-hidden="true" />
-          <div><strong>{item.message}</strong><small>{formatTimestamp(item.timestamp)}{item.recipient ? ` · u/${item.recipient}` : ''}</small></div>
+          <AccountOwnerBadge owner={item.owner} />
+          <div><strong>{item.postUrl && item.postTitle ? (
+            <OriginPostButton post={{ title: item.postTitle, url: item.postUrl, imageUrl: item.imageUrl }}>
+              {item.message}
+            </OriginPostButton>
+          ) : <RedditUserText>{item.message}</RedditUserText>}</strong><small>{formatTimestamp(item.timestamp)}{item.recipient && !item.message.includes(`u/${item.recipient}`) ? <> · <RedditUsernameLink username={item.recipient} /></> : null}</small></div>
         </li>
       ))}
     </ol>
@@ -68,24 +73,72 @@ function connectionLabel(snapshot: RealtimeConnectionSnapshot): string {
   }
 }
 
+export function accountOwnerFromLogData(data: unknown): RedditAccountOwner | undefined {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return undefined;
+  const accountId = Reflect.get(data, 'accountId');
+  const redditUsername = Reflect.get(data, 'redditUsername');
+  return typeof accountId === 'string' && accountId.length > 0
+    && typeof redditUsername === 'string' && redditUsername.length > 0
+    ? { accountId, redditUsername }
+    : undefined;
+}
+
 export interface OperationsPageProps {
   realtimeEnabled?: boolean;
 }
 
+const NOTICE_DISMISS_MS = 5_000;
+
+const expensiveSyncCopy = {
+  full: {
+    title: 'Run a full cache sync?',
+    body: 'This rebuilds the entire chat cache and can take significantly longer than a delta sync.',
+    confirmLabel: 'Run full sync',
+  },
+  'fetch-all': {
+    title: 'Fetch every chat now?',
+    body: 'This is a legacy blocking operation that fetches every chat and may take a while.',
+    confirmLabel: 'Start fetching',
+  },
+} as const;
+
+function ConfirmSyncDialog({ kind, onCancel, onConfirm }: {
+  kind: 'full' | 'fetch-all';
+  onCancel(): void;
+  onConfirm(): void;
+}) {
+  const copy = expensiveSyncCopy[kind];
+  return (
+    <Modal className="dialog-card" labelledBy="confirm-sync-title" onClose={onCancel}>
+      <span className="eyebrow">Confirm action</span>
+      <h2 id="confirm-sync-title">{copy.title}</h2>
+      <p>{copy.body}</p>
+      <div className="dialog-actions">
+        <button autoFocus className="button secondary" onClick={onCancel} type="button">Cancel</button>
+        <button className="button primary" onClick={onConfirm} type="button">{copy.confirmLabel}</button>
+      </div>
+    </Modal>
+  );
+}
+
 export function OperationsPage({ realtimeEnabled = true }: OperationsPageProps) {
-  const queryClient = useQueryClient();
+  const realtime = useDashboardRealtime();
   const activityQuery = useActivityQuery();
   const logsQuery = useLogsQuery();
   const syncQuery = useSyncStatusQuery();
+  const syncMutation = useTriggerChatSyncMutation();
+  const fetchAllMutation = useFetchAllChatsMutation();
+  const [consoleClearNotice, setConsoleClearNotice] = useState(false);
+  const [pendingSyncConfirm, setPendingSyncConfirm] = useState<'full' | 'fetch-all' | null>(null);
+  const [pauseAnnouncement, setPauseAnnouncement] = useState('');
+  const [isPinnedToBottom, setIsPinnedToBottom] = useState(true);
   const [consoleState, dispatchConsole] = useReducer(
     reduceLiveConsoleState,
     createLiveConsoleState(500),
   );
-  const [connection, setConnection] = useState<RealtimeConnectionSnapshot>({
-    status: 'idle',
-    isStale: true,
-  });
+  const connection = realtimeEnabled ? realtime.connection : { status: 'idle', isStale: true } as const;
   const consoleEnd = useRef<HTMLDivElement>(null);
+  const consoleViewport = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
     logsQuery.data?.forEach((entry, index) => {
@@ -103,10 +156,7 @@ export function OperationsPage({ realtimeEnabled = true }: OperationsPageProps)
   }, [logsQuery.data]);
 
   useEffect(() => {
-    if (!realtimeEnabled || typeof EventSource === 'undefined') {
-      setConnection({ status: 'idle', isStale: true });
-      return;
-    }
+    if (!realtimeEnabled) return;
     function onEvent(event: DashboardEvent): void {
       if (event.type === 'log.created') {
         const entry: ConsoleEntry = {
@@ -118,29 +168,61 @@ export function OperationsPage({ realtimeEnabled = true }: OperationsPageProps)
         };
         dispatchConsole({ type: 'append', entry });
       }
-      for (const queryKey of queryKeysForDashboardEvent(event)) {
-        void queryClient.invalidateQueries({ queryKey });
     }
-    }
-    const client = createDashboardRealtimeClient({
-      sourceFactory: createBrowserEventSource,
-      onEvent,
-      onStateChange: setConnection,
-    });
-    client.start();
-    return () => client.stop();
-  }, [queryClient, realtimeEnabled]);
+    return realtime.subscribe(onEvent);
+  }, [realtime, realtimeEnabled]);
 
   const visibleEntries = selectVisibleConsoleEntries(consoleState);
+  const syncBusy = syncQuery.data?.syncing === true || syncMutation.isPending || fetchAllMutation.isPending;
+
+  function runExpensiveSync(kind: 'full' | 'fetch-all') {
+    setPendingSyncConfirm(null);
+    if (kind === 'full') syncMutation.mutate('full'); else fetchAllMutation.mutate();
+  }
+
+  const resetSyncMutation = syncMutation.reset;
+  const resetFetchAllMutation = fetchAllMutation.reset;
+
+  useEffect(() => {
+    if (!syncMutation.isSuccess) return;
+    const timer = globalThis.setTimeout(() => resetSyncMutation(), NOTICE_DISMISS_MS);
+    return () => globalThis.clearTimeout(timer);
+  }, [resetSyncMutation, syncMutation.isSuccess]);
+
+  useEffect(() => {
+    if (!fetchAllMutation.isSuccess) return;
+    const timer = globalThis.setTimeout(() => resetFetchAllMutation(), NOTICE_DISMISS_MS);
+    return () => globalThis.clearTimeout(timer);
+  }, [fetchAllMutation.isSuccess, resetFetchAllMutation]);
+
+  useEffect(() => {
+    if (!consoleClearNotice) return;
+    const timer = globalThis.setTimeout(() => setConsoleClearNotice(false), NOTICE_DISMISS_MS);
+    return () => globalThis.clearTimeout(timer);
+  }, [consoleClearNotice]);
+
+  function handleConsoleScroll() {
+    const viewport = consoleViewport.current;
+    if (!viewport) return;
+    const atBottom = viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight <= 16;
+    setIsPinnedToBottom(atBottom);
+  }
+
+  function jumpToLatest() {
+    setIsPinnedToBottom(true);
+    consoleEnd.current?.scrollIntoView({ block: 'nearest' });
+  }
+
   useEffect(() => {
     if (
       consoleState.isAutoScrollEnabled &&
+      isPinnedToBottom &&
       !consoleState.isPaused &&
       typeof consoleEnd.current?.scrollIntoView === 'function'
     ) {
       consoleEnd.current.scrollIntoView({ block: 'nearest' });
     }
-  }, [consoleState.entries, consoleState.isAutoScrollEnabled, consoleState.isPaused]);
+  }, [consoleState.entries, consoleState.isAutoScrollEnabled, consoleState.isPaused, isPinnedToBottom]);
 
   return (
     <div className="page operations-page">
@@ -156,24 +238,60 @@ export function OperationsPage({ realtimeEnabled = true }: OperationsPageProps)
         </section>
         <section aria-labelledby="sync-jobs-heading" className="panel feature-panel" role="region">
           <div className="panel-heading"><div><span className="eyebrow">Background work</span><h2 id="sync-jobs-heading">Sync jobs</h2></div></div>
-          {syncQuery.isPending ? <p role="status">Loading sync state…</p> : syncQuery.isError ? <p role="alert">{syncQuery.error.message}</p> : <SyncSummary status={syncQuery.data} />}
+          {syncQuery.isPending ? <p role="status">Loading sync state…</p> : syncQuery.isError ? <p role="alert">{syncQuery.error.message}</p> : <><SyncSummary status={syncQuery.data} /><div className="header-actions"><button className="button secondary" disabled={syncBusy} onClick={() => syncMutation.mutate('delta')} type="button">Sync latest chats</button><button className="button secondary" disabled={syncBusy} onClick={() => setPendingSyncConfirm('full')} type="button">Full cache sync</button><button className="button secondary" disabled={syncBusy} onClick={() => setPendingSyncConfirm('fetch-all')} type="button">Fetch all chats</button></div></>}
+          {syncMutation.isSuccess ? <p role="status">{syncMutation.data.kind === 'delta' ? 'Delta' : 'Full'} sync started. Progress is shown from server status.</p> : null}
+          {fetchAllMutation.isSuccess ? <p role="status">Fetched {fetchAllMutation.data.count} chats.</p> : null}
+          {syncMutation.isError ? <p role="alert">{syncMutation.error.message}</p> : null}
+          {fetchAllMutation.isError ? <p role="alert">{fetchAllMutation.error.message}</p> : null}
         </section>
       </div>
       <section aria-labelledby="live-console-heading" className="panel console-panel" role="region">
-        <div className="panel-heading"><div><span className="eyebrow">Raw diagnostics</span><h2 id="live-console-heading">Live console</h2></div><span className="console-count">{consoleState.entries.length} retained</span></div>
+        <div className="panel-heading"><div><span className="eyebrow">Raw diagnostics</span><h2 id="live-console-heading">Live console</h2></div><span className="console-count">{visibleEntries.length === consoleState.entries.length
+          ? `${consoleState.entries.length} retained`
+          : `${visibleEntries.length} shown · ${consoleState.entries.length} retained`}</span></div>
         <div className="console-controls">
-          <button aria-pressed={consoleState.isPaused} className="button secondary" onClick={() => dispatchConsole({ type: 'set-paused', paused: !consoleState.isPaused })} type="button">{consoleState.isPaused ? `Resume console (${consoleState.pendingEntries.length})` : 'Pause console'}</button>
+          <button
+            aria-pressed={consoleState.isPaused}
+            className="button secondary"
+            onClick={() => {
+              const paused = !consoleState.isPaused;
+              dispatchConsole({ type: 'set-paused', paused });
+              setPauseAnnouncement(paused ? 'Console paused.' : 'Console resumed.');
+            }}
+            type="button"
+          >{consoleState.isPaused ? `Resume console (${consoleState.pendingEntries.length})` : 'Pause console'}</button>
+          <button className="button secondary" onClick={() => { dispatchConsole({ type: 'clear' }); setConsoleClearNotice(true); }} type="button">Clear local console</button>
           <label>Log level<select aria-label="Log level" onChange={(event) => dispatchConsole({ type: 'set-level', level: event.target.value as ConsoleLevelFilter })} value={consoleState.level}><option value="all">All levels</option><option value="debug">Debug</option><option value="info">Info</option><option value="warn">Warning</option><option value="error">Error</option></select></label>
           <label>Search logs<input aria-label="Search logs" onChange={(event) => dispatchConsole({ type: 'set-search', search: event.target.value })} placeholder="Message or metadata" type="search" value={consoleState.search} /></label>
           <label className="checkbox-control"><input checked={consoleState.isAutoScrollEnabled} onChange={(event) => dispatchConsole({ type: 'set-auto-scroll', enabled: event.target.checked })} type="checkbox" />Auto-scroll</label>
         </div>
-        <div aria-live="polite" className="live-console" role="log">
-          {logsQuery.isPending ? <p>Loading logs…</p> : visibleEntries.length === 0 ? <p>No logs match the current filters.</p> : visibleEntries.map((entry) => (
-            <article className={`console-entry ${entry.level}`} key={entry.id}><time dateTime={entry.occurredAt}>{formatTimestamp(entry.occurredAt)}</time><strong>{entry.level.toUpperCase()}</strong><span>{entry.message}</span></article>
-          ))}
+        {consoleClearNotice ? <p role="status">Cleared from this browser view. Server logs were not deleted.</p> : null}
+        <p aria-live="polite" className="sr-only" role="status">{pauseAnnouncement}</p>
+        <div className="live-console" onScroll={handleConsoleScroll} ref={consoleViewport} role="log">
+          {logsQuery.isPending ? <p>Loading logs…</p> : visibleEntries.length === 0 ? <p>No logs match the current filters.</p> : visibleEntries.map((entry) => {
+            const owner = accountOwnerFromLogData(entry.data);
+            return (
+              <article className={`console-entry ${entry.level}`} key={entry.id}>
+                <time dateTime={entry.occurredAt}>{formatTimestamp(entry.occurredAt)}</time>
+                <strong>{entry.level.toUpperCase()}</strong>
+                <span className="console-account">{owner ? <RedditUsernameLink username={owner.redditUsername} /> : 'global'}</span>
+                <span><RedditUserText>{entry.message}</RedditUserText></span>
+              </article>
+            );
+          })}
           <div ref={consoleEnd} />
         </div>
+        {!isPinnedToBottom ? (
+          <button className="button secondary console-jump" onClick={jumpToLatest} type="button">Jump to latest</button>
+        ) : null}
       </section>
+      {pendingSyncConfirm ? (
+        <ConfirmSyncDialog
+          kind={pendingSyncConfirm}
+          onCancel={() => setPendingSyncConfirm(null)}
+          onConfirm={() => runExpensiveSync(pendingSyncConfirm)}
+        />
+      ) : null}
     </div>
   );
 }

apps/dashboard/src/features/operations/operations-queries.ts

@@ -1,4 +1,4 @@
-import { useQuery } from '@tanstack/react-query';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import { operationsApi } from './operations-api.js';
 
 export const operationsQueryKeys = {
@@ -16,5 +16,15 @@ export function useLogsQuery() {
 }
 
 export function useSyncStatusQuery() {
-  return useQuery({ queryKey: operationsQueryKeys.syncStatus, queryFn: operationsApi.getSyncStatus });
+  return useQuery({ queryKey: operationsQueryKeys.syncStatus, queryFn: operationsApi.getSyncStatus, refetchInterval: (query) => query.state.data?.syncing ? 2_000 : false });
+}
+
+export function useTriggerChatSyncMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({ mutationFn: (kind: 'delta' | 'full') => operationsApi.triggerSync(kind), onSettled: () => queryClient.invalidateQueries({ queryKey: operationsQueryKeys.syncStatus }) });
+}
+
+export function useFetchAllChatsMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({ mutationFn: operationsApi.fetchAllChats, onSettled: () => queryClient.invalidateQueries({ queryKey: operationsQueryKeys.syncStatus }) });
 }

apps/dashboard/src/features/operations/operations.css

@@ -1,6 +1,6 @@
 .operations-page { display: grid; gap: .8rem; }
-.connection-banner { display: flex; justify-content: space-between; gap: 1rem; padding: .8rem 1rem; color: #aaf0c4; background: #163a26; border: 1px solid #28593d; border-radius: .75rem; }
-.connection-banner.stale { color: #ffe1a0; background: #2a2111; border-color: #59451e; }
+.connection-banner { display: flex; justify-content: space-between; gap: 1rem; padding: .8rem 1rem; color: var(--success-text); background: var(--success-bg); border: 1px solid var(--success-border); border-radius: .75rem; }
+.connection-banner.stale { color: var(--warning-text); background: var(--warning-bg); border-color: var(--warning-border); }
 .operations-summary-grid { display: grid; gap: .8rem; }
 .operations-activity-list { display: grid; gap: .8rem; padding: 0; margin: 0; list-style: none; }
 .operations-activity-list li { display: flex; gap: .75rem; }
@@ -21,12 +21,16 @@
 .console-controls .checkbox-control { display: flex; flex-direction: row; align-items: center; }
 .console-controls .checkbox-control input { min-height: auto; }
 .live-console { height: min(30rem, 55vh); overflow: auto; padding: .65rem; color: #cbd8d1; background: #050906; border: 1px solid var(--border); border-radius: .6rem; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: .78rem; }
-.console-entry { display: grid; grid-template-columns: 11rem 3.5rem minmax(0, 1fr); gap: .65rem; padding: .35rem; border-bottom: 1px solid #142019; }
+.console-entry { display: grid; grid-template-columns: 11rem 3.5rem minmax(6rem, auto) minmax(0, 1fr); gap: .65rem; padding: .35rem; border-bottom: 1px solid #142019; }
 .console-entry time { color: #708178; }
 .console-entry strong { color: #8da49a; }
+.console-account { color: #708178; }
+.console-account a { color: var(--accent); font-weight: 700; }
 .console-entry.warn strong { color: var(--warning); }
 .console-entry.error strong { color: var(--danger); }
 .live-console > p { color: var(--muted); text-align: center; }
+.console-panel { position: relative; }
+.console-jump { position: absolute; right: 1.6rem; bottom: 1.6rem; box-shadow: 0 .5rem 1.5rem rgba(0, 0, 0, .4); }
 @media (min-width: 56rem) {
   .operations-summary-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
   .console-controls { grid-template-columns: auto minmax(8rem, .45fr) minmax(14rem, 1fr) auto; align-items: end; }

apps/dashboard/src/features/operations/realtime-client.ts

@@ -40,6 +40,7 @@ export interface DashboardRealtimeClientOptions {
   url?: string;
   sourceFactory(url: string): DashboardEventSource;
   onEvent(event: DashboardEvent): void;
+  onConnected?(context: { isReconnect: boolean }): void;
   onStateChange?(snapshot: RealtimeConnectionSnapshot): void;
   onInvalidEvent?(value: unknown): void;
 }
@@ -54,6 +55,7 @@ export function createDashboardRealtimeClient(
 ): DashboardRealtimeClient {
   let source: DashboardEventSource | undefined;
   let snapshot: RealtimeConnectionSnapshot = { status: 'idle', isStale: true };
+  let hasConnected = false;
 
   function update(next: RealtimeConnectionSnapshot): void {
     snapshot = next;
@@ -89,6 +91,8 @@ export function createDashboardRealtimeClient(
       source = options.sourceFactory(options.url ?? '/api/events/stream');
       source.addEventListener('open', () => {
         update({ ...snapshot, status: 'connected', isStale: false });
+        options.onConnected?.({ isReconnect: hasConnected });
+        hasConnected = true;
       });
       source.addEventListener('error', () => {
         update({ ...snapshot, status: 'reconnecting', isStale: true });
@@ -120,11 +124,13 @@ export function queryKeysForDashboardEvent(event: DashboardEvent): readonly Quer
       return [['conversations'], ['operations', 'activity']];
     case 'sync.started':
     case 'sync.progress':
+      return [['operations', 'sync-status']];
     case 'sync.completed':
-    case 'sync.failed':
       return [['operations', 'sync-status'], ['conversations'], ['media']];
+    case 'sync.failed':
+      return [['operations', 'sync-status']];
     case 'reddit.session.changed':
-      return [['reddit', 'session']];
+      return [['dashboard', 'login', 'status']];
     case 'log.created':
       return [];
   }

apps/dashboard/src/features/operations/realtime-fallback.ts

@@ -0,0 +1,54 @@
+export interface PollingScheduler {
+  setInterval(callback: () => void, intervalMs: number): unknown;
+  clearInterval(handle: unknown): void;
+}
+
+export interface VisibilitySource {
+  isVisible(): boolean;
+  subscribe(listener: () => void): () => void;
+}
+
+export interface VisibilityAwarePollingFallback {
+  start(): void;
+  stop(): void;
+  setStale(stale: boolean): void;
+}
+
+export function createVisibilityAwarePollingFallback(options: {
+  intervalMs: number;
+  poll(): void;
+  scheduler: PollingScheduler;
+  visibility: VisibilitySource;
+}): VisibilityAwarePollingFallback {
+  let stale = false;
+  let timer: unknown;
+  let unsubscribe: (() => void) | undefined;
+  const pollIfNeeded = () => { if (stale && options.visibility.isVisible()) options.poll(); };
+  return {
+    start() {
+      if (timer !== undefined) return;
+      timer = options.scheduler.setInterval(pollIfNeeded, options.intervalMs);
+      unsubscribe = options.visibility.subscribe(pollIfNeeded);
+    },
+    stop() {
+      if (timer !== undefined) options.scheduler.clearInterval(timer);
+      timer = undefined;
+      unsubscribe?.();
+      unsubscribe = undefined;
+    },
+    setStale(value) { stale = value; },
+  };
+}
+
+export const browserVisibilitySource: VisibilitySource = {
+  isVisible: () => document.visibilityState === 'visible',
+  subscribe(listener) {
+    document.addEventListener('visibilitychange', listener);
+    return () => document.removeEventListener('visibilitychange', listener);
+  },
+};
+
+export const browserPollingScheduler: PollingScheduler = {
+  setInterval: (callback, intervalMs) => window.setInterval(callback, intervalMs),
+  clearInterval: (handle) => { if (typeof handle === 'number') window.clearInterval(handle); },
+};

apps/dashboard/src/features/outreach/outreach-api.ts

@@ -0,0 +1,22 @@
+import { OutreachFunnelResponseSchema } from '../../../../../packages/api-contracts/src/index.js';
+import { createDashboardRequest } from '../../api/request.js';
+
+export function createOutreachApi(fetchImplementation?: typeof fetch) {
+  const request = createDashboardRequest(fetchImplementation);
+  return {
+    async getFunnel() {
+      const response = await request('/api/outreach');
+      const payload: unknown = await response.json();
+      if (!response.ok) {
+        const message = typeof payload === 'object' && payload !== null && 'error' in payload
+          && typeof payload.error === 'string'
+          ? payload.error
+          : `Outreach funnel unavailable (${response.status})`;
+        throw new Error(message);
+      }
+      return OutreachFunnelResponseSchema.parse(payload);
+    },
+  };
+}
+
+export const outreachApi = createOutreachApi();

apps/dashboard/src/features/outreach/outreach-page.tsx

@@ -0,0 +1,160 @@
+import { useEffect, useState } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import type { OutreachCandidate, OutreachCandidateStatus } from '../../../../../packages/api-contracts/src/index.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
+import { RedditUsernameLink } from '../../components/reddit-username-link.js';
+import { formatExactTime, formatShortRelativeTime } from '../conversations/relative-time.js';
+import { outreachApi } from './outreach-api.js';
+import './outreach.css';
+
+const STAGES: ReadonlyArray<{
+  status: OutreachCandidateStatus;
+  label: string;
+  description: string;
+}> = [
+  { status: 'discovered', label: 'Waiting', description: 'Found and queued' },
+  { status: 'screening', label: 'Screening', description: 'Checking eligibility' },
+  { status: 'ready', label: 'Ready', description: 'Message prepared' },
+  { status: 'sending', label: 'Sending', description: 'Assigned to account' },
+  { status: 'retryable', label: 'Retrying', description: 'Cooling down' },
+];
+
+const KNOWN_STATUSES = new Set<string>(STAGES.map((stage) => stage.status));
+
+function statusLabel(status: OutreachCandidateStatus): string {
+  const stage = STAGES.find((candidate) => candidate.status === status);
+  if (stage) return stage.label;
+  // Unknown statuses fall back to a readable neutral label instead of the raw enum.
+  const readable = String(status).replaceAll(/[-_]/g, ' ');
+  return readable.charAt(0).toUpperCase() + readable.slice(1);
+}
+
+function formatWaitTime(timestamp: number, now: number): string {
+  const remaining = Math.max(0, timestamp - now);
+  if (remaining < 60_000) return 'in under a minute';
+  if (remaining < 3_600_000) return `in ${Math.ceil(remaining / 60_000)}m`;
+  if (remaining < 86_400_000) return `in ${Math.ceil(remaining / 3_600_000)}h`;
+  return `in ${Math.ceil(remaining / 86_400_000)}d`;
+}
+
+function CandidateCard({ candidate, now }: { candidate: OutreachCandidate; now: number }) {
+  const waitingUntil = candidate.availableAt > now;
+  const isKnownStatus = KNOWN_STATUSES.has(candidate.status);
+  return (
+    <li className={`outreach-candidate ${isKnownStatus ? `is-${candidate.status}` : 'is-unknown'}`}>
+      <div className="candidate-status-rail" aria-hidden="true"><span /></div>
+      <article>
+        <div className="candidate-heading">
+          <div className="candidate-labels">
+            <span className={`candidate-status ${isKnownStatus ? `status-${candidate.status}` : 'status-neutral'}`}>{statusLabel(candidate.status)}</span>
+            <span>r/{candidate.subreddit}</span>
+            <span>{candidate.sourceType === 'image' ? 'Image post' : 'Chat post'}</span>
+          </div>
+          <time dateTime={new Date(candidate.discoveredAt).toISOString()} title={formatExactTime(candidate.discoveredAt)}>
+            queued {formatShortRelativeTime(candidate.discoveredAt, now)}
+          </time>
+        </div>
+        <a className="candidate-title" href={candidate.postUrl} rel="noreferrer" target="_blank">
+          {candidate.title} <span aria-hidden="true">↗</span>
+        </a>
+        <span className="sr-only">(opens Reddit in a new tab)</span>
+        <div className="candidate-meta">
+          <RedditUsernameLink username={candidate.author} />
+          <span>{candidate.hasPreparedMessage ? 'Message prepared' : 'Not prepared yet'}</span>
+          <span>{candidate.attemptCount} {candidate.attemptCount === 1 ? 'attempt' : 'attempts'}</span>
+          {waitingUntil ? <span title={formatExactTime(candidate.availableAt)}>Retry {formatWaitTime(candidate.availableAt, now)}</span> : null}
+        </div>
+        {candidate.note ? <p className="candidate-note"><strong>Latest note</strong>{candidate.note}</p> : null}
+        {candidate.owner ? <AccountOwnerBadge owner={candidate.owner} /> : null}
+      </article>
+    </li>
+  );
+}
+
+export function OutreachPage() {
+  const query = useQuery({
+    queryKey: ['outreach', 'funnel'],
+    queryFn: outreachApi.getFunnel,
+    refetchInterval: 10_000,
+  });
+
+  // Single client-side clock for every displayed offset: retry countdowns tick
+  // every second while visible, everything else every 10 seconds.
+  const [now, setNow] = useState(() => Date.now());
+  const hasVisibleCountdown = (query.data?.candidates ?? []).some((candidate) => candidate.availableAt > now);
+  useEffect(() => {
+    const interval = setInterval(() => setNow(Date.now()), hasVisibleCountdown ? 1_000 : 10_000);
+    return () => clearInterval(interval);
+  }, [hasVisibleCountdown]);
+
+  if (query.isPending) return <div className="page-state" role="status"><span className="spinner" />Loading outreach funnel…</div>;
+  if (query.isError) {
+    return (
+      <div className="page-state error-state" role="alert">
+        <strong>Outreach funnel unavailable</strong>
+        <span>{query.error.message}</span>
+        <button
+          aria-busy={query.isFetching || undefined}
+          className="button secondary"
+          disabled={query.isFetching}
+          onClick={() => void query.refetch()}
+          type="button"
+        >
+          {query.isFetching ? 'Refreshing…' : 'Retry'}
+        </button>
+      </div>
+    );
+  }
+
+  const { data } = query;
+  return (
+    <div className="page outreach-page">
+      <header className="page-header">
+        <div><span className="eyebrow">Live candidate queue</span><h1>Outreach funnel</h1><p>Follow every potential post from discovery to delivery, and see exactly where the remaining queue is waiting.</p></div>
+        <button
+          aria-busy={query.isFetching || undefined}
+          className="button secondary"
+          disabled={query.isFetching}
+          onClick={() => void query.refetch()}
+          type="button"
+        >
+          {query.isFetching ? 'Refreshing…' : 'Refresh'}
+        </button>
+      </header>
+
+      <section aria-labelledby="active-funnel-heading" className="outreach-runway">
+        <div className="runway-heading">
+          <div><span className="eyebrow">Current burn-down</span><h2 id="active-funnel-heading">{data.activeCount} active {data.activeCount === 1 ? 'post' : 'posts'}</h2></div>
+          <div className="runway-outcomes"><span><strong>{data.outcomes.sent}</strong> sent</span><span><strong>{data.outcomes.rejected}</strong> screened out</span></div>
+        </div>
+        <ol className="outreach-stages">
+          {STAGES.map((stage) => (
+            <li className={`stage-${stage.status}`} key={stage.status}>
+              <span className="stage-marker" aria-hidden="true" />
+              <div><span>{stage.label}</span><small>{stage.description}</small></div>
+              <strong>{data.stages[stage.status]}</strong>
+            </li>
+          ))}
+        </ol>
+        <p className="runway-caption">Retrying posts loop back to Ready when their cooldown expires. Sent and screened-out totals cover the lifetime of this queue.</p>
+      </section>
+
+      <section aria-labelledby="active-candidates-heading" className="candidate-section">
+        <div className="panel-heading">
+          <div><span className="eyebrow">Potential posts</span><h2 id="active-candidates-heading">Active queue</h2></div>
+          <span className="candidate-updated">
+            {data.candidates.length < data.activeCount ? `Showing ${data.candidates.length} of ${data.activeCount} · ` : ''}
+            Updated {formatShortRelativeTime(data.generatedAt, now)} · Auto-updates every 10s
+          </span>
+        </div>
+        {data.candidates.length === 0 ? (
+          <div className="empty-state panel"><strong>The active queue is clear.</strong><span>New potential posts will appear here as discovery finds them.</span></div>
+        ) : (
+          <ol aria-label="Active outreach candidates" className="outreach-candidates">
+            {data.candidates.map((candidate) => <CandidateCard candidate={candidate} key={candidate.postId} now={now} />)}
+          </ol>
+        )}
+      </section>
+    </div>
+  );
+}

apps/dashboard/src/features/outreach/outreach.css

@@ -0,0 +1,59 @@
+.outreach-page { display: grid; gap: 1rem; }
+.outreach-runway { position: relative; overflow: hidden; padding: 1.2rem; background: #101a16; border: 1px solid #355044; border-radius: 1rem; }
+.outreach-runway::before { position: absolute; inset: 0; content: ""; pointer-events: none; background: radial-gradient(circle at 12% -20%, rgba(117, 214, 157, .16), transparent 34%); }
+.runway-heading { position: relative; display: flex; flex-wrap: wrap; justify-content: space-between; align-items: flex-start; gap: 1rem; margin-bottom: 1.2rem; }
+.runway-heading h2 { font-size: clamp(1.55rem, 3vw, 2.25rem); letter-spacing: -.045em; }
+.runway-outcomes { display: flex; gap: .5rem; }
+.runway-outcomes span { display: grid; min-width: 5.7rem; padding: .55rem .7rem; color: var(--muted); background: rgba(9, 17, 14, .7); border: 1px solid var(--border); border-radius: .65rem; font-size: .72rem; }
+.runway-outcomes strong { color: #e9f1ec; font-size: 1.15rem; }
+.outreach-stages { position: relative; display: grid; gap: .55rem; padding: 0; margin: 0; list-style: none; }
+.outreach-stages li { display: grid; grid-template-columns: auto minmax(0, 1fr) auto; align-items: center; gap: .75rem; padding: .75rem; background: rgba(23, 35, 30, .86); border: 1px solid var(--border); border-radius: .75rem; }
+.outreach-stages li > div { display: grid; gap: .05rem; }
+.outreach-stages li span { font-weight: 750; }
+.outreach-stages li small { color: var(--muted); }
+.outreach-stages li > strong { font-size: 1.4rem; }
+.stage-marker { width: .65rem; height: .65rem; border-radius: 50%; background: #668077; box-shadow: 0 0 0 .25rem rgba(102, 128, 119, .12); }
+.stage-screening .stage-marker { background: #86b7d7; }
+.stage-ready .stage-marker { background: var(--accent); }
+.stage-sending .stage-marker { background: #c1ef91; box-shadow: 0 0 0 .25rem rgba(193, 239, 145, .12); }
+.stage-retryable .stage-marker { background: var(--warning); }
+.runway-caption { position: relative; margin: .9rem 0 0; color: var(--muted); font-size: .78rem; }
+.candidate-section { margin-top: .5rem; }
+.candidate-updated { color: var(--muted); font-size: .8rem; }
+.outreach-candidates { display: grid; gap: .7rem; padding: 0; margin: 0; list-style: none; }
+.outreach-candidate { display: grid; grid-template-columns: .32rem minmax(0, 1fr); overflow: hidden; background: var(--surface); border: 1px solid var(--border); border-radius: .85rem; }
+.candidate-status-rail { background: #668077; }
+.candidate-status-rail span { display: block; width: 100%; height: 3.1rem; background: #8ca49c; }
+.outreach-candidate.is-screening .candidate-status-rail span { background: #86b7d7; }
+.outreach-candidate.is-ready .candidate-status-rail span { background: var(--accent); }
+.outreach-candidate.is-sending .candidate-status-rail span { background: #c1ef91; }
+.outreach-candidate.is-retryable .candidate-status-rail span { background: var(--warning); }
+.outreach-candidate article { display: grid; gap: .7rem; min-width: 0; padding: .9rem 1rem; }
+.candidate-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: .75rem; }
+.candidate-labels { display: flex; flex-wrap: wrap; align-items: center; gap: .45rem; color: var(--muted); font-size: .72rem; }
+.candidate-status { padding: .25rem .45rem; color: #dce8e2; background: #2b3832; border-radius: .35rem; font-weight: 800; }
+.status-neutral { color: #dce8e2; background: #2b3832; }
+.status-screening { color: #d6edfc; background: #243a48; }
+.status-ready, .status-sending { color: var(--success-text); background: var(--success-bg); }
+.status-retryable { color: var(--warning-text); background: #42351b; }
+.candidate-heading time { flex: 0 0 auto; color: var(--muted); font-size: .74rem; }
+.candidate-title { width: fit-content; max-width: 100%; color: #eef6f1; font-size: 1rem; font-weight: 720; line-height: 1.35; text-decoration-color: #426655; text-underline-offset: .22em; overflow-wrap: anywhere; }
+.candidate-title:hover { text-decoration-color: var(--accent); }
+.candidate-meta { display: flex; flex-wrap: wrap; gap: .4rem .8rem; color: var(--muted); font-size: .76rem; }
+.candidate-note { display: grid; gap: .18rem; margin: 0; padding: .55rem .7rem; color: #d9c99e; background: #251f13; border-left: 2px solid var(--warning); border-radius: .35rem; font-size: .78rem; overflow-wrap: anywhere; }
+.candidate-note strong { color: var(--warning-text); font-size: .68rem; letter-spacing: .06em; text-transform: uppercase; }
+.outreach-candidate .account-owner-badge { margin-top: -.1rem; }
+
+@media (min-width: 64rem) {
+  .outreach-stages { grid-template-columns: repeat(5, minmax(0, 1fr)); gap: 0; }
+  .outreach-stages::before { position: absolute; top: 50%; left: 8%; right: 8%; height: 1px; content: ""; background: #3f5a4e; }
+  .outreach-stages li { position: relative; grid-template-columns: auto minmax(0, 1fr); margin-right: .55rem; }
+  .outreach-stages li:last-child { margin-right: 0; }
+  .outreach-stages li > strong { grid-column: 2; }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .outreach-candidate.is-screening .candidate-status-rail span,
+  .outreach-candidate.is-sending .candidate-status-rail span { animation: queue-pulse 2.4s ease-in-out infinite; }
+  @keyframes queue-pulse { 50% { opacity: .45; } }
+}

apps/dashboard/src/features/overview/overview-page.tsx

@@ -1,8 +1,13 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { useQueryClient } from '@tanstack/react-query';
 import { dashboardQueryKeys, useSetRunningMutation, useStatsQuery, useTimersQuery } from '../../api/queries.js';
 import type { BotStats, Timers } from '../../api/contracts.js';
+import type { AccountStatus } from '../../../../../packages/api-contracts/src/index.js';
 import { ConfirmationDialog } from '../../components/confirmation-dialog.js';
+import { RedditUserText } from '../../components/reddit-user-text.js';
+import { OriginPostButton } from '../../components/origin-post.js';
+import { RecentMessagesPanel } from './recent-messages.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
 
 function errorMessage(error: Error | null): string {
   return error?.message ?? 'Something went wrong.';
@@ -12,6 +17,27 @@ function formatTime(timestamp: number): string {
   return new Intl.DateTimeFormat(undefined, { hour: '2-digit', minute: '2-digit' }).format(timestamp);
 }
 
+function formatMetricValue(value: number): string {
+  return value.toLocaleString();
+}
+
+function formatCountdown(remainingMs: number): string {
+  const totalSeconds = Math.max(0, Math.ceil(remainingMs / 1_000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+
+/** Ticks a client clock so time-derived UI flips without a refetch. */
+function useNow(intervalMs = 1_000): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const timer = globalThis.setInterval(() => setNow(Date.now()), intervalMs);
+    return () => globalThis.clearInterval(timer);
+  }, [intervalMs]);
+  return now;
+}
+
 function MetricCard({ label, value, detail, metric }: { label: string; value: string | number; detail: string; metric: string }) {
   return (
     <article className="metric-card">
@@ -23,7 +49,8 @@ function MetricCard({ label, value, detail, metric }: { label: string; value: st
 }
 
 function TimersPanel({ timers }: { timers: Timers }) {
-  const isReady = timers.nextMessageAvailableAt === null || timers.nextMessageAvailableAt <= Date.now();
+  const now = useNow();
+  const isReady = timers.nextMessageAvailableAt === null || timers.nextMessageAvailableAt <= now;
   return (
     <section aria-labelledby="timers-heading" className="panel">
       <div className="panel-heading">
@@ -36,7 +63,9 @@ function TimersPanel({ timers }: { timers: Timers }) {
       <dl className="definition-list">
         <div>
           <dt>Next message</dt>
-          <dd>{isReady ? 'Available now' : formatTime(timers.nextMessageAvailableAt ?? Date.now())}</dd>
+          <dd>{isReady
+            ? 'Available now'
+            : `Ready in ${formatCountdown((timers.nextMessageAvailableAt ?? now) - now)} (${formatTime(timers.nextMessageAvailableAt ?? now)})`}</dd>
         </div>
         <div>
           <dt>Hourly allowance</dt>
@@ -51,6 +80,63 @@ function TimersPanel({ timers }: { timers: Timers }) {
   );
 }
 
+const sendingStateCopy: Record<AccountStatus['sendingState'], { label: string; tone: 'success' | 'warning' | 'neutral'; detail: string }> = {
+  ready: { label: 'Ready', tone: 'success', detail: 'Available for the next outbound candidate.' },
+  'bot-stopped': { label: 'Bot stopped', tone: 'neutral', detail: 'Global sending is stopped.' },
+  'runtime-stopped': { label: 'Runtime stopped', tone: 'warning', detail: 'This account runtime is not running.' },
+  'runtime-failed': { label: 'Runtime failed', tone: 'warning', detail: 'This account runtime needs attention.' },
+  'login-required': { label: 'Login required', tone: 'warning', detail: 'Refresh this account session before it can send.' },
+  'matrix-cooldown': { label: 'Matrix cooldown', tone: 'warning', detail: 'Only this account is paused by Reddit chat throttling.' },
+  'replies-prioritized': { label: 'Replies first', tone: 'neutral', detail: 'Inbound replies are being handled before new outreach.' },
+  pacing: { label: 'Pacing', tone: 'neutral', detail: 'Waiting for the account sending window.' },
+};
+
+function AccountStatusPanel({ accounts }: { accounts: readonly AccountStatus[] }) {
+  return (
+    <section aria-labelledby="account-status-heading" className="panel account-status-panel">
+      <div className="panel-heading">
+        <div><span className="eyebrow">Multi-account delivery</span><h2 id="account-status-heading">Account status</h2></div>
+        <span className="pill neutral">{accounts.length} configured</span>
+      </div>
+      {accounts.length === 0 ? <div className="empty-state"><strong>No accounts configured.</strong><span>Add an account under Settings → Access.</span></div> : (
+        <div className="account-status-grid">
+          {accounts.map((account) => {
+            const state = sendingStateCopy[account.sendingState];
+            return (
+              <article aria-label={`Status for u/${account.redditUsername}`} className="account-status-card" key={account.accountId}>
+                <div className="account-status-heading">
+                  <AccountOwnerBadge owner={account} />
+                  <span className={`pill ${state.tone}`}>{state.label}</span>
+                </div>
+                <p>{state.detail}</p>
+                <dl className="account-status-details">
+                  <div><dt>Runtime</dt><dd>{account.runtimeState}</dd></div>
+                  <div><dt>Authentication</dt><dd>{account.authenticated ? 'Authenticated' : 'Unavailable'}</dd></div>
+                  <div><dt>Hourly usage</dt><dd>{account.messagesThisHour} of {account.maxMessagesPerHour}</dd></div>
+                  <div><dt>Remaining</dt><dd>{account.messagesRemaining}</dd></div>
+                  <div><dt>Allowance resets</dt><dd>{formatTime(account.hourlyResetAt)}</dd></div>
+                  <div><dt>Pending replies</dt><dd>{account.actionableReplies}</dd></div>
+                </dl>
+                {account.nextMessageAvailableAt && account.nextMessageAvailableAt > Date.now() && !account.invitationCooldown
+                  ? <p className="account-status-note">Next send: {formatTime(account.nextMessageAvailableAt)}</p>
+                  : null}
+                {account.invitationCooldown ? (
+                  <div className="account-status-warning">
+                    <strong>Cooldown until {formatTime(account.invitationCooldown.until)}</strong>
+                    <span>{account.invitationCooldown.reason}</span>
+                    {account.invitationCooldown.redditCode ? <code>{account.invitationCooldown.redditCode}</code> : null}
+                  </div>
+                ) : null}
+                {account.failure ? <div className="account-status-warning is-error" role="alert"><strong>Runtime failure</strong><span>{account.failure}</span></div> : null}
+              </article>
+            );
+          })}
+        </div>
+      )}
+    </section>
+  );
+}
+
 function ActivityPanel({ stats }: { stats: BotStats }) {
   return (
     <section aria-labelledby="activity-heading" className="panel activity-panel">
@@ -67,10 +153,14 @@ function ActivityPanel({ stats }: { stats: BotStats }) {
         </div>
       ) : (
         <ol className="activity-list">
-          {stats.recentActivity.map((item) => (
-            <li key={`${item.timestamp}-${item.message}`}>
+          {stats.recentActivity.map((item, index) => (
+            <li key={`${item.timestamp}-${index}`}>
               <span className={`activity-marker ${item.type}`} aria-hidden="true" />
-              <div><strong>{item.message}</strong><small>{formatTime(item.timestamp)}</small></div>
+              <div><strong>{item.postUrl && item.postTitle ? (
+                <OriginPostButton post={{ title: item.postTitle, url: item.postUrl, imageUrl: item.imageUrl }}>
+                  {item.message}
+                </OriginPostButton>
+              ) : <RedditUserText>{item.message}</RedditUserText>}</strong><AccountOwnerBadge owner={item.owner} /><small>{formatTime(item.timestamp)}</small></div>
             </li>
           ))}
         </ol>
@@ -102,6 +192,15 @@ export function OverviewPage() {
   }
 
   if (statsQuery.isPending) {
+    if (statsQuery.isPaused) {
+      return (
+        <div className="page-state error-state" role="alert">
+          <strong>You appear to be offline</strong>
+          <span>The overview will load once the connection returns.</span>
+          <button className="button secondary" onClick={() => void statsQuery.refetch()} type="button">Retry overview</button>
+        </div>
+      );
+    }
     return <div aria-label="Loading overview" className="page-state" role="status"><span className="spinner" />Loading overview…</div>;
   }
 
@@ -128,6 +227,7 @@ export function OverviewPage() {
         </div>
         <div className="header-actions">
           <button
+            aria-busy={isRefreshing ? 'true' : undefined}
             aria-label={isRefreshing ? 'Refreshing overview' : 'Refresh overview'}
             className="button secondary"
             disabled={isRefreshing}
@@ -137,7 +237,6 @@ export function OverviewPage() {
             {isRefreshing ? 'Refreshing…' : 'Refresh'}
           </button>
           <button
-            aria-label={`${action === 'start' ? 'Start' : 'Stop'} bot`}
             className={action === 'start' ? 'button primary' : 'button danger'}
             onClick={() => setConfirmationAction(action)}
             type="button"
@@ -158,18 +257,22 @@ export function OverviewPage() {
 
       {stats.invitationCooldown ? (
         <div className="cooldown-banner" role="status">
-          <strong>Reddit invitation cooldown</strong>
+          <strong>{stats.invitationCooldown.redditUsername
+            ? `u/${stats.invitationCooldown.redditUsername} invitation cooldown`
+            : 'Reddit invitation cooldown'}</strong>
           <span>{stats.invitationCooldown.reason}</span>
         </div>
       ) : null}
 
       <section aria-label="Key metrics" className="metrics-grid">
-        <MetricCard detail="All recorded sends" label="Messages sent" metric="messages-sent" value={stats.totalMessagesSent} />
-        <MetricCard detail={`${stats.responseRate}% response rate`} label="Responses" metric="responses" value={stats.totalResponses} />
-        <MetricCard detail="Posts evaluated" label="Processed" metric="processed" value={stats.totalProcessed} />
-        <MetricCard detail={`Limit ${stats.maxMessagesPerHour}`} label="This hour" metric="messages-hour" value={stats.messagesThisHour} />
+        <MetricCard detail="All recorded sends" label="Messages sent" metric="messages-sent" value={formatMetricValue(stats.totalMessagesSent)} />
+        <MetricCard detail={`${stats.responseRate}% response rate`} label="Responses" metric="responses" value={formatMetricValue(stats.totalResponses)} />
+        <MetricCard detail="Posts evaluated" label="Processed" metric="processed" value={formatMetricValue(stats.totalProcessed)} />
+        <MetricCard detail={`Limit ${formatMetricValue(stats.maxMessagesPerHour)}`} label="This hour" metric="messages-hour" value={formatMetricValue(stats.messagesThisHour)} />
       </section>
 
+      <AccountStatusPanel accounts={stats.accounts} />
+
       <div className="overview-grid">
         {timersQuery.isPending ? (
           <section aria-label="Loading timers" className="panel panel-loading" role="status"><span className="spinner" />Loading sending window…</section>
@@ -184,13 +287,14 @@ export function OverviewPage() {
         )}
         <ActivityPanel stats={stats} />
       </div>
+      <RecentMessagesPanel />
 
-      {controlMutation.isError ? <div className="toast error" role="alert">{errorMessage(controlMutation.error)}</div> : null}
       {confirmationAction ? (
         <ConfirmationDialog
           action={confirmationAction}
+          errorMessage={controlMutation.isError ? errorMessage(controlMutation.error) : null}
           isPending={controlMutation.isPending}
-          onCancel={() => setConfirmationAction(null)}
+          onCancel={() => { setConfirmationAction(null); controlMutation.reset(); }}
           onConfirm={confirmControl}
         />
       ) : null}

apps/dashboard/src/features/overview/recent-messages.tsx

@@ -0,0 +1,46 @@
+import { useQuery } from '@tanstack/react-query';
+import { MessagesResponseSchema, type SentMessage } from '../../../../../packages/api-contracts/src/index.js';
+import { dashboardRequest } from '../../api/request.js';
+import { AccountOwnerBadge } from '../../components/account-owner-badge.js';
+import { RedditUsernameLink } from '../../components/reddit-username-link.js';
+
+async function loadRecentMessages(): Promise<SentMessage[]> {
+  const response = await dashboardRequest('/api/messages');
+  const payload: unknown = await response.json();
+  if (!response.ok) throw new Error(`Could not load recent messages (${response.status})`);
+  return MessagesResponseSchema.parse(payload);
+}
+
+function formatSentAt(timestamp: number): string {
+  return new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' }).format(timestamp);
+}
+
+export function RecentMessagesPanel() {
+  const query = useQuery({ queryKey: ['overview', 'recent-messages'], queryFn: loadRecentMessages });
+  return (
+    <section aria-labelledby="recent-messages-heading" className="panel">
+      <div className="panel-heading"><div><span className="eyebrow">Durable records</span><h2 id="recent-messages-heading">Recent sent messages</h2></div></div>
+      {query.isPending ? <div className="panel-loading" role="status"><span className="spinner" />Loading recent messages…</div> : null}
+      {query.isError ? (
+        <div className="error-panel" role="alert">
+          <strong>Recent messages unavailable</strong>
+          <span>{query.error.message}</span>
+          <button className="button secondary" onClick={() => void query.refetch()} type="button">Retry messages</button>
+        </div>
+      ) : null}
+      {query.data?.length === 0 ? (
+        <div className="empty-state">
+          <strong>No sent messages recorded yet.</strong>
+          <span>Delivered messages will appear here.</span>
+        </div>
+      ) : null}
+      {query.data && query.data.length > 0 ? (
+        <ol aria-label="Recent sent messages" className="activity-list">
+          {query.data.map((message) => (
+            <li key={message.id}><div><strong><RedditUsernameLink username={message.recipient} /></strong><AccountOwnerBadge owner={message.owner} /><span>{message.message}</span><small>{formatSentAt(message.sentAt)} · {message.gotResponse ? 'Responded' : 'No response recorded'}</small></div></li>
+          ))}
+        </ol>
+      ) : null}
+    </section>
+  );
+}

apps/dashboard/src/features/performance/performance-api.ts

@@ -3,13 +3,18 @@ import {
   StrategyPerformanceResponseSchema,
   SubredditPerformanceResponseSchema,
   SuccessfulExamplesResponseSchema,
+  FunnelResponseSchema,
+  AiUsageSummaryResponseSchema,
 } from '../../../../../packages/api-contracts/src/index.js';
 import type { z } from 'zod';
+import { createDashboardRequest } from '../../api/request.js';
 
 type SubredditPerformanceResponse = z.infer<typeof SubredditPerformanceResponseSchema>;
 type StrategyPerformanceResponse = z.infer<typeof StrategyPerformanceResponseSchema>;
 type DailyTrendResponse = z.infer<typeof DailyTrendResponseSchema>;
 type SuccessfulExamplesResponse = z.infer<typeof SuccessfulExamplesResponseSchema>;
+type FunnelResponse = z.infer<typeof FunnelResponseSchema>;
+type AiUsageSummaryResponse = z.infer<typeof AiUsageSummaryResponseSchema>;
 
 async function parseResponse<T>(
   response: Response,
@@ -34,14 +39,14 @@ export interface PerformanceApi {
   getStrategyPerformance(): Promise<StrategyPerformanceResponse>;
   getDailyTrend(days: number): Promise<DailyTrendResponse>;
   getSuccessfulExamples(): Promise<SuccessfulExamplesResponse>;
+  getFunnel(): Promise<FunnelResponse>;
+  getAiUsage(days: number): Promise<AiUsageSummaryResponse>;
 }
 
 export function createPerformanceApi(
   fetchImplementation?: typeof fetch,
 ) {
-  function request(path: string): Promise<Response> {
-    return (fetchImplementation ?? globalThis.fetch)(path);
-  }
+  const request = createDashboardRequest(fetchImplementation);
   return {
     async getSubredditPerformance() {
       return parseResponse(
@@ -67,6 +72,18 @@ export function createPerformanceApi(
         SuccessfulExamplesResponseSchema,
       );
     },
+    async getFunnel() {
+      return parseResponse(
+        await request('/api/analytics/funnel'),
+        FunnelResponseSchema,
+      );
+    },
+    async getAiUsage(days: number) {
+      return parseResponse(
+        await request(`/api/analytics/ai-usage?days=${days}`),
+        AiUsageSummaryResponseSchema,
+      );
+    },
   } satisfies PerformanceApi;
 }
 

apps/dashboard/src/features/performance/performance-page.tsx

@@ -1,15 +1,21 @@
+import { useState, type ReactNode } from 'react';
+import type { UseQueryResult } from '@tanstack/react-query';
 import type { z } from 'zod';
 import type {
   DailyTrendResponseSchema,
   StrategyPerformanceResponseSchema,
   SubredditPerformanceResponseSchema,
   SuccessfulExample,
+  FunnelResponseSchema,
+  AiUsageSummaryResponseSchema,
 } from '../../../../../packages/api-contracts/src/index.js';
 import {
   useDailyTrendQuery,
   useStrategyPerformanceQuery,
   useSubredditPerformanceQuery,
   useSuccessfulExamplesQuery,
+  useFunnelQuery,
+  useAiUsageQuery,
 } from './performance-queries.js';
 import './performance.css';
 
@@ -17,6 +23,61 @@ const LOW_CONFIDENCE_SAMPLE_SIZE = 20;
 type SubredditPerformance = z.infer<typeof SubredditPerformanceResponseSchema>[number];
 type StrategyPerformance = z.infer<typeof StrategyPerformanceResponseSchema>[number];
 type DailyTrend = z.infer<typeof DailyTrendResponseSchema>[number];
+type Funnel = z.infer<typeof FunnelResponseSchema>;
+type AiUsageSummary = z.infer<typeof AiUsageSummaryResponseSchema>;
+
+function formatTrendDate(isoDate: string): string {
+  const parsed = new Date(`${isoDate}T00:00:00`);
+  if (Number.isNaN(parsed.getTime())) return isoDate;
+  return new Intl.DateTimeFormat(undefined, { day: 'numeric', month: 'short' }).format(parsed);
+}
+
+/** Renders one panel's own loading, error, and data states independently of its siblings. */
+function PanelBody<T>({ query, label, children }: {
+  query: UseQueryResult<T, Error>;
+  label: string;
+  children: (data: T) => ReactNode;
+}) {
+  if (query.isPending) {
+    return <div className="panel-loading" role="status"><span className="spinner" />Loading {label}…</div>;
+  }
+  if (query.isError) {
+    return (
+      <div className="error-panel" role="alert">
+        <strong>{label} unavailable</strong>
+        <span>{query.error.message}</span>
+        <button className="button secondary" onClick={() => void query.refetch()} type="button">Retry {label}</button>
+      </div>
+    );
+  }
+  return <>{children(query.data)}</>;
+}
+
+function formatUsd(value: number): string {
+  return new Intl.NumberFormat(undefined, {
+    style: 'currency', currency: 'USD', minimumFractionDigits: 2, maximumFractionDigits: 4,
+  }).format(value);
+}
+
+function AiUsagePanelBody({ usage }: { usage: AiUsageSummary }) {
+  const successRate = usage.requests > 0 ? Math.round((usage.successes / usage.requests) * 100) : 0;
+  return (
+    <>
+      <div className="panel-heading"><div><span className="eyebrow">OpenRouter · last {usage.days} days</span><h2 id="ai-usage-heading">AI cost and reliability</h2></div><span className="sample-size">{usage.requests} requests</span></div>
+      <div aria-label="AI usage totals" className="metrics-grid performance-metrics">
+        <article className="metric-card"><span>Reported cost</span><strong>{formatUsd(usage.costUsd)}</strong><small>OpenRouter usage accounting</small></article>
+        <article className="metric-card"><span>Tokens</span><strong>{usage.totalTokens.toLocaleString()}</strong><small>{usage.promptTokens.toLocaleString()} prompt · {usage.completionTokens.toLocaleString()} completion</small></article>
+        <article className="metric-card"><span>Success rate</span><strong>{successRate}%</strong><small>{usage.refusals} refusals · {usage.errors} errors/empty</small></article>
+        <article className="metric-card"><span>Average latency</span><strong>{usage.averageLatencyMs.toLocaleString()} ms</strong><small>All recorded attempts</small></article>
+      </div>
+      {usage.models.length === 0 ? <p className="feature-empty">No AI usage has been recorded yet. New requests will appear here.</p> : (
+        <div className="table-scroll"><table aria-label="AI usage by model" className="performance-table"><thead><tr><th scope="col">Model</th><th scope="col">Requests</th><th scope="col">Success</th><th scope="col">Refusals</th><th scope="col">Errors</th><th scope="col">Tokens</th><th scope="col">Cost</th><th scope="col">Latency</th></tr></thead><tbody>{usage.models.map((model) => (
+          <tr key={model.model}><th scope="row">{model.model}</th><td>{model.requests}</td><td>{model.successes}</td><td>{model.refusals}</td><td>{model.errors}</td><td>{model.totalTokens.toLocaleString()}</td><td>{formatUsd(model.costUsd)}</td><td>{model.averageLatencyMs.toLocaleString()} ms</td></tr>
+        ))}</tbody></table></div>
+      )}
+    </>
+  );
+}
 
 function SampleSize({ totalSent }: { totalSent: number }) {
   const isLowConfidence = totalSent < LOW_CONFIDENCE_SAMPLE_SIZE;
@@ -28,6 +89,41 @@ function SampleSize({ totalSent }: { totalSent: number }) {
   );
 }
 
+function FunnelPanelBody({ funnel }: { funnel: Funnel }) {
+  const stages = [
+    ['Processed', funnel.processed],
+    ['Sent', funnel.sent],
+    [`Mature (${funnel.responseWindowHours}h)`, funnel.mature],
+    ['Responded', funnel.responded],
+    ['Engaged', funnel.engaged],
+    ['Images', funnel.images],
+  ] as const;
+  return (
+    <>
+      <div className="panel-heading"><div><span className="eyebrow">Qualified engagement</span><h2 id="funnel-heading">Outcome funnel</h2></div><span className="sample-size">{funnel.pending} awaiting maturity</span></div>
+      <ol className="funnel-list">
+        {stages.map(([label, value], index) => {
+          const previousValue = index > 0 ? stages[index - 1][1] : null;
+          const conversion = previousValue !== null && previousValue > 0
+            ? `${Math.round((value / previousValue) * 100)}% of previous`
+            : null;
+          return (
+            <li key={label}>
+              <span>{label}</span>
+              <span className="funnel-value"><strong>{value.toLocaleString()}</strong>{conversion ? <small className="interval">{conversion}</small> : null}</span>
+            </li>
+          );
+        })}
+      </ol>
+      <div className="guardrail-list" aria-label="Guardrail outcomes">
+        <span>Declined <strong>{funnel.declined}</strong></span>
+        <span>Boundary <strong>{funnel.boundary}</strong></span>
+        <span>Upsell <strong>{funnel.upsell}</strong></span>
+      </div>
+    </>
+  );
+}
+
 function PerformanceTable({
   label,
   rows,
@@ -37,10 +133,18 @@ function PerformanceTable({
   rows: readonly (SubredditPerformance | StrategyPerformance)[];
   rowLabel: (row: SubredditPerformance | StrategyPerformance) => string;
 }) {
+  if (rows.length === 0) {
+    return (
+      <div className="empty-state">
+        <strong>No sends recorded yet.</strong>
+        <span>Rows appear once messages have been sent.</span>
+      </div>
+    );
+  }
   return (
     <div className="table-scroll">
       <table aria-label={label} className="performance-table">
-        <thead><tr><th scope="col">Name</th><th scope="col">Responses</th><th scope="col">Rate</th><th scope="col">Sample</th></tr></thead>
+        <thead><tr><th scope="col">Name</th><th scope="col">Responses</th><th scope="col">Mature response rate</th><th scope="col">Images</th><th scope="col">Image rate</th><th scope="col">Sample</th></tr></thead>
         <tbody>
           {rows.map((row) => (
             <tr key={rowLabel(row)}>
@@ -49,8 +153,10 @@ function PerformanceTable({
                 {'configured' in row && row.configured ? <span className="configured-label">Configured</span> : null}
               </th>
               <td>{row.totalResponses}</td>
-              <td>{row.responseRate}%</td>
-              <td><SampleSize totalSent={row.totalSent} /></td>
+              <td>{row.responseRate}%{row.responseRateLow !== undefined && row.responseRateHigh !== undefined ? <small className="interval">95% CI {row.responseRateLow}–{row.responseRateHigh}%</small> : null}</td>
+              <td>{row.totalImages}</td>
+              <td>{row.imageRate}%</td>
+              <td><SampleSize totalSent={row.totalSent} />{row.pendingSent ? <small className="interval">{row.pendingSent} pending</small> : null}</td>
             </tr>
           ))}
         </tbody>
@@ -59,14 +165,23 @@ function PerformanceTable({
   );
 }
 
-function Trend({ rows }: { rows: readonly DailyTrend[] }) {
+function Trend({ rows, rangeDays }: { rows: readonly DailyTrend[]; rangeDays: number }) {
+  if (rows.length === 0) {
     return (
-    <ol aria-label="30 day response trend" className="trend-list">
+      <div className="empty-state">
+        <strong>No sends recorded yet.</strong>
+        <span>Daily results appear once messages have been sent.</span>
+      </div>
+    );
+  }
+  return (
+    <ol aria-label={`${rangeDays} day response trend`} className="trend-list">
       {rows.map((row) => (
         <li key={row.date}>
-          <time dateTime={row.date}>{row.date}</time>
+          <time dateTime={row.date}>{formatTrendDate(row.date)}</time>
           <span className="trend-track" aria-hidden="true"><span style={{ width: `${Math.max(2, Math.min(100, row.responseRate))}%` }} /></span>
           <strong>{row.responseRate}%</strong>
+          <span>{row.totalImages} images ({row.imageRate}%)</span>
           <SampleSize totalSent={row.totalSent} />
         </li>
       ))}
@@ -82,7 +197,7 @@ function SuccessfulExamples({ examples }: { examples: readonly SuccessfulExample
         const source = example.subreddit ?? 'unknown source';
         return (
           <article aria-label={`Successful example from ${source}`} className="successful-example" key={example.id}>
-            <div><span className="pill success">Response received</span><small>{source}</small></div>
+            <div><span className="pill success">Response received</span>{example.gotImage ? <span className="pill success">Image received</span> : null}<small>{source}</small></div>
             {example.postTitle ? <h3>{example.postTitle}</h3> : null}
             <blockquote>{example.originalMessage}</blockquote>
             {example.responseSnippet ? <p><strong>Reply:</strong> {example.responseSnippet}</p> : null}
@@ -93,29 +208,66 @@ function SuccessfulExamples({ examples }: { examples: readonly SuccessfulExample
   );
 }
 
+const TREND_RANGES = [7, 30, 90] as const;
+type TrendRange = (typeof TREND_RANGES)[number];
+
 export function PerformancePage() {
+  const [rangeDays, setRangeDays] = useState<TrendRange>(30);
   const subreddits = useSubredditPerformanceQuery();
   const strategies = useStrategyPerformanceQuery();
-  const trend = useDailyTrendQuery(30);
+  const trend = useDailyTrendQuery(rangeDays);
   const examples = useSuccessfulExamplesQuery();
-  const queries = [subreddits, strategies, trend, examples];
-  if (queries.some((query) => query.isPending)) {
-    return <div className="page-state" role="status">Loading performance…</div>;
-  }
-  const failed = queries.find((query) => query.isError);
-  if (failed?.error) {
-    return <div className="page-state error-state" role="alert"><strong>Performance unavailable</strong><span>{failed.error.message}</span></div>;
-  }
+  const funnel = useFunnelQuery();
+  const aiUsage = useAiUsageQuery(rangeDays);
 
   return (
     <div className="page performance-page">
-      <header className="page-header"><div><span className="eyebrow">Decision support</span><h1>Performance</h1><p>Compare response outcomes without hiding the sample sizes behind the percentages.</p></div></header>
-      <section aria-labelledby="trend-heading" className="panel feature-panel"><div className="panel-heading"><div><span className="eyebrow">Last 30 days</span><h2 id="trend-heading">Response trend</h2></div></div><Trend rows={trend.data ?? []} /></section>
-      <div className="performance-grid">
-        <section aria-labelledby="subreddit-heading" className="panel feature-panel"><div className="panel-heading"><h2 id="subreddit-heading">By subreddit</h2></div><PerformanceTable label="Subreddit performance" rows={subreddits.data ?? []} rowLabel={(row) => 'subreddit' in row ? row.subreddit : row.strategyId} /></section>
-        <section aria-labelledby="strategy-heading" className="panel feature-panel"><div className="panel-heading"><h2 id="strategy-heading">By strategy</h2></div><PerformanceTable label="Strategy performance" rows={strategies.data ?? []} rowLabel={(row) => 'strategyId' in row ? row.strategyId : row.subreddit} /></section>
+      <header className="page-header">
+        <div><span className="eyebrow">Decision support</span><h1>Performance</h1><p>Compare response and received-image outcomes without hiding the sample sizes behind the percentages.</p></div>
+        <div aria-label="Date range" className="header-actions" role="group">
+          {TREND_RANGES.map((days) => (
+            <button
+              aria-pressed={rangeDays === days}
+              className={rangeDays === days ? 'button primary' : 'button secondary'}
+              key={days}
+              onClick={() => setRangeDays(days)}
+              type="button"
+            >
+              {days} days
+            </button>
+          ))}
         </div>
-      <section aria-labelledby="examples-heading" className="panel feature-panel"><div className="panel-heading"><div><span className="eyebrow">What worked</span><h2 id="examples-heading">Successful examples</h2></div></div><SuccessfulExamples examples={examples.data ?? []} /></section>
+      </header>
+      <section aria-labelledby="funnel-heading-anchor" className="panel feature-panel">
+        <span className="sr-only" id="funnel-heading-anchor">Outcome funnel</span>
+        <PanelBody label="outcome funnel" query={funnel}>{(data) => <FunnelPanelBody funnel={data} />}</PanelBody>
+      </section>
+      <section aria-labelledby="ai-usage-heading-anchor" className="panel feature-panel">
+        <span className="sr-only" id="ai-usage-heading-anchor">AI cost and reliability</span>
+        <PanelBody label="AI usage" query={aiUsage}>{(data) => <AiUsagePanelBody usage={data} />}</PanelBody>
+      </section>
+      <section aria-labelledby="trend-heading" className="panel feature-panel">
+        <div className="panel-heading"><div><span className="eyebrow">Last {rangeDays} days</span><h2 id="trend-heading">Response trend</h2></div></div>
+        <PanelBody label="response trend" query={trend}>{(data) => <Trend rangeDays={rangeDays} rows={data} />}</PanelBody>
+      </section>
+      <div className="performance-grid">
+        <section aria-labelledby="subreddit-heading" className="panel feature-panel">
+          <div className="panel-heading"><h2 id="subreddit-heading">By subreddit</h2></div>
+          <PanelBody label="subreddit performance" query={subreddits}>
+            {(data) => <PerformanceTable label="Subreddit performance" rowLabel={(row) => 'subreddit' in row ? row.subreddit : row.strategyId} rows={data} />}
+          </PanelBody>
+        </section>
+        <section aria-labelledby="strategy-heading" className="panel feature-panel">
+          <div className="panel-heading"><h2 id="strategy-heading">By strategy</h2></div>
+          <PanelBody label="strategy performance" query={strategies}>
+            {(data) => <PerformanceTable label="Strategy performance" rowLabel={(row) => 'strategyId' in row ? row.strategyId : row.subreddit} rows={data} />}
+          </PanelBody>
+        </section>
+      </div>
+      <section aria-labelledby="examples-heading" className="panel feature-panel">
+        <div className="panel-heading"><div><span className="eyebrow">What worked</span><h2 id="examples-heading">Successful examples</h2></div></div>
+        <PanelBody label="successful examples" query={examples}>{(data) => <SuccessfulExamples examples={data} />}</PanelBody>
+      </section>
     </div>
   );
 }

apps/dashboard/src/features/performance/performance-queries.ts

@@ -6,6 +6,8 @@ export const performanceQueryKeys = {
   strategies: ['performance', 'strategies'] as const,
   trend: (days: number) => ['performance', 'trend', days] as const,
   successfulExamples: ['performance', 'successful-examples'] as const,
+  funnel: ['performance', 'funnel'] as const,
+  aiUsage: (days: number) => ['performance', 'ai-usage', days] as const,
 };
 
 export function useSubredditPerformanceQuery() {
@@ -35,3 +37,17 @@ export function useSuccessfulExamplesQuery() {
     queryFn: performanceApi.getSuccessfulExamples,
   });
 }
+
+export function useFunnelQuery() {
+  return useQuery({
+    queryKey: performanceQueryKeys.funnel,
+    queryFn: performanceApi.getFunnel,
+  });
+}
+
+export function useAiUsageQuery(days: number) {
+  return useQuery({
+    queryKey: performanceQueryKeys.aiUsage(days),
+    queryFn: () => performanceApi.getAiUsage(days),
+  });
+}

apps/dashboard/src/features/performance/performance.css

@@ -9,8 +9,20 @@
 .configured-label, .confidence-warning { display: block; margin-top: .2rem; color: var(--accent); font-size: .68rem; font-weight: 750; }
 .confidence-warning { color: var(--warning); }
 .sample-size { white-space: nowrap; color: var(--muted); }
+.interval { display: block; margin-top: .2rem; color: var(--muted); white-space: nowrap; }
+.funnel-list { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: .6rem; padding: 0; margin: 0; list-style: none; }
+.funnel-list li { display: flex; justify-content: space-between; gap: 1rem; padding: .8rem; background: var(--surface-raised); border: 1px solid var(--border); border-radius: .65rem; }
+.funnel-value { display: grid; gap: .1rem; text-align: right; }
+.guardrail-list { display: flex; flex-wrap: wrap; gap: .6rem; margin-top: .7rem; color: var(--muted); }
+.guardrail-list span { padding: .45rem .65rem; border: 1px solid var(--border); border-radius: 999px; }
 .trend-list { display: grid; gap: .65rem; padding: 0; margin: 0; list-style: none; }
-.trend-list li { display: grid; grid-template-columns: 6.5rem minmax(5rem, 1fr) 3rem 6rem; align-items: center; gap: .75rem; }
+/* Narrow screens: wrap each day into two rows instead of forcing a wide grid. */
+.trend-list li { display: grid; grid-template-columns: 4.5rem minmax(4rem, 1fr) 3rem; align-items: center; gap: .4rem .75rem; }
+.trend-list li > span:not(.trend-track), .trend-list li .sample-size { grid-column: span 3; font-size: .78rem; }
+@media (min-width: 48rem) {
+  .trend-list li { grid-template-columns: 6.5rem minmax(5rem, 1fr) 3rem 8rem 6rem; gap: .75rem; }
+  .trend-list li > span:not(.trend-track), .trend-list li .sample-size { grid-column: auto; font-size: inherit; }
+}
 .trend-track { height: .5rem; overflow: hidden; background: var(--border); border-radius: 999px; }
 .trend-track span { display: block; height: 100%; background: var(--accent); border-radius: inherit; }
 .example-grid { display: grid; gap: .75rem; }
@@ -21,4 +33,4 @@
 .successful-example blockquote { margin: 1rem 0; padding-left: 1rem; border-left: 2px solid var(--accent); }
 .successful-example p { margin-bottom: 0; color: var(--muted); }
 .feature-empty { color: var(--muted); }
-@media (min-width: 64rem) { .performance-grid, .example-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (min-width: 64rem) { .performance-grid, .example-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } .funnel-list { grid-template-columns: repeat(6, minmax(0, 1fr)); } }

apps/dashboard/src/features/settings/access-panel.tsx

@@ -1,4 +1,10 @@
-import { useLoginInfoQuery, useLoginStatusQuery, useStartLoginMutation } from './settings-queries.js';
+import { useEffect, useRef, useState } from 'react';
+import { RedditUsernameLink } from '../../components/reddit-username-link.js';
+import {
+  useImportRedditSessionMutation,
+  useLoginStatusQuery,
+  useRedditAccountsQuery,
+} from './settings-queries.js';
 
 function errorMessage(error: Error | null): string {
   return error?.message ?? 'Something went wrong.';
@@ -16,44 +22,91 @@ function sessionLabel(status: ReturnType<typeof useLoginStatusQuery>['data']): s
   }[status.status];
 }
 
-function noVncUrl(publicUrl: string | null, port: number): string {
-  if (publicUrl) return publicUrl;
-  return `${window.location.protocol}//${window.location.hostname}:${port}/vnc.html?autoconnect=true&resize=scale`;
-}
-
 export function AccessPanel() {
-  const infoQuery = useLoginInfoQuery();
   const statusQuery = useLoginStatusQuery();
-  const loginMutation = useStartLoginMutation();
+  const accountsQuery = useRedditAccountsQuery();
+  const importMutation = useImportRedditSessionMutation();
+  const importInput = useRef<HTMLInputElement>(null);
+  const [importFileError, setImportFileError] = useState<string | null>(null);
+  const resetImportMutation = importMutation.reset;
 
-  if (infoQuery.isPending || statusQuery.isPending) {
-    return <section aria-label="Loading access" className="panel panel-loading" role="status"><span className="spinner" />Loading Reddit access…</section>;
+  useEffect(() => {
+    if (!importMutation.isSuccess) return;
+    const timer = globalThis.setTimeout(() => resetImportMutation(), 5_000);
+    return () => globalThis.clearTimeout(timer);
+  }, [importMutation.isSuccess, resetImportMutation]);
+
+  async function importSession(file: File | undefined) {
+    if (!file) return;
+    setImportFileError(null);
+    let exported: unknown;
+    try {
+      exported = JSON.parse(await file.text());
+    } catch {
+      importMutation.reset();
+      setImportFileError("That file isn't valid JSON. Export a fresh session dump from the extension and try again.");
+      return;
+    }
+    importMutation.mutate(exported);
   }
 
-  if (infoQuery.isError || statusQuery.isError) {
-    const error = infoQuery.error ?? statusQuery.error;
+  if (statusQuery.isPending) {
+    return <section aria-label="Loading access" className="panel panel-loading" role="status"><span className="spinner" />Loading Reddit access...</section>;
+  }
+
+  if (statusQuery.isError) {
     return (
       <section className="panel error-panel" role="alert">
-        <strong>Reddit access unavailable</strong><span>{errorMessage(error)}</span>
-        <button className="button secondary" onClick={() => void Promise.all([infoQuery.refetch(), statusQuery.refetch()])} type="button">Retry access</button>
+        <strong>Reddit access unavailable</strong><span>{errorMessage(statusQuery.error)}</span>
+        <button className="button secondary" onClick={() => void statusQuery.refetch()} type="button">Retry access</button>
       </section>
     );
   }
 
-  const info = infoQuery.data;
+  const session = statusQuery.data;
+  const username = session.ready && 'loggedIn' in session && session.loggedIn ? session.username ?? null : null;
   return (
     <section aria-labelledby="access-heading" className="panel settings-section">
-      <div className="panel-heading"><div><span className="eyebrow">Browser session</span><h2 id="access-heading">Access</h2></div><span className={statusQuery.data.ready && 'status' in statusQuery.data && statusQuery.data.loggedIn ? 'pill success' : 'pill warning'}>{sessionLabel(statusQuery.data)}</span></div>
-      <p className="settings-copy">Open Reddit in the managed browser, complete login through noVNC, then recheck the session. Credentials are never entered or displayed here.</p>
-      <div className="access-actions">
-        <button className="button primary" disabled={loginMutation.isPending} onClick={() => loginMutation.mutate()} type="button">{loginMutation.isPending ? 'Opening login…' : 'Open Reddit login'}</button>
-        <button className="button secondary" disabled={statusQuery.isFetching} onClick={() => void statusQuery.refetch()} type="button">{statusQuery.isFetching ? 'Checking session…' : 'Recheck session'}</button>
-        {info.vncEnabled ? <a className="button secondary" href={noVncUrl(info.publicUrl, info.novncPort)} rel="noreferrer" target="_blank">Open noVNC login window</a> : null}
+      <div className="panel-heading"><div><span className="eyebrow">Reddit accounts</span><h2 id="access-heading">Access</h2></div><span className={session.ready && 'status' in session && session.loggedIn ? 'pill success' : 'pill warning'}>{sessionLabel(session)}</span></div>
+      <p className="settings-copy">Add each Reddit account with its own extension session dump. Content and sync state stay owned by that account in the database. Any account with an expired login pauses while waiting for a fresh session dump; other accounts keep running.</p>
+      {username ? <p className="settings-copy">Verified account: <strong><RedditUsernameLink username={username} /></strong>.</p> : null}
+      <div aria-label="Reddit accounts" className="reddit-account-list">
+        {accountsQuery.isPending ? <p className="settings-copy" role="status"><span className="spinner" /> Loading Reddit accounts…</p> : null}
+        {accountsQuery.isError ? (
+          <div className="settings-notice error" role="alert">
+            <span>Could not load Reddit accounts: {errorMessage(accountsQuery.error)}</span>{' '}
+            <button className="button secondary" onClick={() => void accountsQuery.refetch()} type="button">Retry accounts</button>
           </div>
-      {!info.vncEnabled ? <div className="settings-notice warning" role="status">noVNC is not available in this deployment.</div> : null}
-      {info.passwordRequired ? <p className="settings-copy">A VNC password is required.</p> : null}
-      {loginMutation.isSuccess ? <div className="settings-notice success" role="status">Login page opened.</div> : null}
-      {loginMutation.isError ? <div className="settings-notice error" role="alert">{errorMessage(loginMutation.error)}</div> : null}
+        ) : null}
+        {(accountsQuery.data ?? []).map((account) => (
+          <div className={account.isRunning ? 'reddit-account-row is-active' : 'reddit-account-row'} key={account.accountId}>
+            <div><strong><RedditUsernameLink username={account.redditUsername} /></strong><span>{account.isRunning ? 'Running independently' : 'Waiting for a refreshed session'}</span></div>
+            <span className={account.isRunning ? 'pill success' : 'pill warning'}>{account.isRunning ? 'Running' : 'Paused'}</span>
+          </div>
+        ))}
+        {accountsQuery.isSuccess && accountsQuery.data.length === 0 ? <p className="settings-copy">No Reddit accounts have been added yet.</p> : null}
+      </div>
+      <div className="access-actions">
+        <input
+          accept="application/json"
+          aria-label="Reddit session export"
+          className="sr-only"
+          onChange={(event) => {
+            const file = event.target.files?.[0];
+            // Reset the input so picking the same file again re-triggers change.
+            event.target.value = '';
+            void importSession(file);
+          }}
+          ref={importInput}
+          type="file"
+        />
+        <button className="button primary" disabled={importMutation.isPending} onClick={() => importInput.current?.click()} type="button">{importMutation.isPending ? 'Adding account...' : 'Add or refresh account'}</button>
+        <button aria-busy={statusQuery.isFetching ? 'true' : undefined} className="button secondary" disabled={statusQuery.isFetching} onClick={() => void statusQuery.refetch()} type="button">{statusQuery.isFetching ? 'Checking sessions...' : 'Recheck accounts'}</button>
+      </div>
+      <p className="settings-copy">Open Reddit Chat in Chrome for the account you want to add, wait for the extension badge to show OK, then upload its JSON dump. It contains login credentials; do not share it.</p>
+      {importFileError ? <div className="settings-notice error" role="alert">{importFileError}</div> : null}
+      {importMutation.isSuccess ? <div className="settings-notice success" role="status"><span>Reddit session imported and verified.</span> <span>Account runtime is running independently.</span></div> : null}
+      {importMutation.isError ? <div className="settings-notice error" role="alert">{errorMessage(importMutation.error)}</div> : null}
     </section>
   );
 }

apps/dashboard/src/features/settings/risk-dialog.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { Modal } from '../../components/modal.js';
 
 interface RiskDialogProps {
   reasons: string[];
@@ -8,27 +8,19 @@ interface RiskDialogProps {
 }
 
 export function RiskDialog({ reasons, isPending, onCancel, onConfirm }: RiskDialogProps) {
-  const cancelButtonRef = useRef<HTMLButtonElement>(null);
-
-  useEffect(() => {
-    cancelButtonRef.current?.focus();
-  }, []);
-
   return (
-    <div aria-labelledby="risk-settings-title" aria-modal="true" className="dialog-backdrop" role="dialog">
-      <div className="dialog-card">
+    <Modal className="dialog-card" isDismissLocked={isPending} labelledBy="risk-settings-title" onClose={onCancel}>
       <span className="eyebrow">Confirm operational risk</span>
       <h2 id="risk-settings-title">Confirm risky settings</h2>
       <ul className="risk-list">
         {reasons.map((reason) => <li key={reason}>{reason}</li>)}
       </ul>
       <div className="dialog-actions">
-          <button className="button secondary" disabled={isPending} onClick={onCancel} ref={cancelButtonRef} type="button">Cancel</button>
+        <button autoFocus className="button secondary" disabled={isPending} onClick={onCancel} type="button">Cancel</button>
         <button className="button danger" disabled={isPending} onClick={onConfirm} type="button">
           {isPending ? 'Applying…' : 'Apply risky settings'}
         </button>
       </div>
-      </div>
-    </div>
+    </Modal>
   );
 }

apps/dashboard/src/features/settings/settings-api.ts

@@ -4,13 +4,16 @@ import {
   ConfigUpdateRequestSchema,
   ConfigUpdateResponseSchema,
   ErrorResponseSchema,
-  LoginInfoResponseSchema,
-  LoginStartResponseSchema,
   LoginStatusResponseSchema,
+  RedditAccountsResponseSchema,
+  RedditCookieImportRequestSchema,
+  RedditCookieImportResponseSchema,
   type ConfigResponse,
   type ConfigUpdateRequest,
   type LoginStatusResponse,
+  type RedditAccountSummary,
 } from '../../../../../packages/api-contracts/src/index.js';
+import { dashboardRequest } from '../../api/request.js';
 
 async function parseResponse<T>(response: Response, schema: ZodType<T>): Promise<T> {
   const payload: unknown = await response.json();
@@ -22,7 +25,7 @@ async function parseResponse<T>(response: Response, schema: ZodType<T>): Promise
 }
 
 function request(path: string, init?: RequestInit): Promise<Response> {
-  return globalThis.fetch(path, { credentials: 'same-origin', ...init });
+  return dashboardRequest(path, init);
 }
 
 export function fetchSettings(): Promise<ConfigResponse> {
@@ -41,18 +44,24 @@ export async function saveSettings(updates: ConfigUpdateRequest) {
   );
 }
 
-export function fetchLoginInfo() {
-  return request('/api/login/info').then((response) => parseResponse(response, LoginInfoResponseSchema));
-}
-
 export function fetchLoginStatus(): Promise<LoginStatusResponse> {
   return request('/api/login/status').then((response) => parseResponse(response, LoginStatusResponseSchema));
 }
 
-export async function startLogin(): Promise<void> {
+export function fetchRedditAccounts(): Promise<RedditAccountSummary[]> {
+  return request('/api/accounts').then((response) => parseResponse(response, RedditAccountsResponseSchema));
+}
+
+export async function importRedditSession(exported: unknown): Promise<RedditAccountSummary> {
+  const body = RedditCookieImportRequestSchema.parse(exported);
   const response = await parseResponse(
-    await request('/api/login/start', { method: 'POST' }),
-    LoginStartResponseSchema,
+    await request('/api/login/session-import', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }),
+    RedditCookieImportResponseSchema,
   );
   if (!response.ok) throw new Error(response.error);
+  return response.account;
 }

apps/dashboard/src/features/settings/settings-editor.tsx

@@ -1,9 +1,17 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
+import { useBlocker } from 'react-router-dom';
 import type { ConfigResponse, ConfigUpdateRequest } from '../../../../../packages/api-contracts/src/index.js';
+import { Modal } from '../../components/modal.js';
 import { AccessPanel } from './access-panel.js';
 import { RiskDialog } from './risk-dialog.js';
 import { useSaveSettingsMutation } from './settings-queries.js';
-import { createSettingsDraft, isDraftDirty, validateSettingsDraft, type SettingsDraft } from './settings-model.js';
+import {
+  changedDraftFields,
+  createSettingsDraft,
+  isDraftDirty,
+  validateSettingsDraft,
+  type SettingsDraft,
+} from './settings-model.js';
 import { BehaviourSection, MonitoringSection, RateLimitsSection } from './settings-sections.js';
 import type { SettingsSection } from './settings-page.js';
 
@@ -21,13 +29,51 @@ function errorMessage(error: Error | null): string {
   return error?.message ?? 'Something went wrong.';
 }
 
+function DiscardDraftDialog({ title, body, onDiscard, onStay }: {
+  title: string;
+  body: string;
+  onDiscard(): void;
+  onStay(): void;
+}) {
+  return (
+    <Modal className="dialog-card" labelledBy="discard-draft-title" onClose={onStay}>
+      <span className="eyebrow">Unsaved changes</span>
+      <h2 id="discard-draft-title">{title}</h2>
+      <p>{body}</p>
+      <div className="dialog-actions">
+        <button autoFocus className="button secondary" onClick={onStay} type="button">Stay</button>
+        <button className="button danger" onClick={onDiscard} type="button">Discard changes</button>
+      </div>
+    </Modal>
+  );
+}
+
 export function SettingsEditor({ config, section }: SettingsEditorProps) {
   const [persistedDraft, setPersistedDraft] = useState<SettingsDraft>(() => createSettingsDraft(config));
   const [draft, setDraft] = useState<SettingsDraft>(persistedDraft);
   const [errors, setErrors] = useState<Record<string, string>>({});
   const [pendingRiskySave, setPendingRiskySave] = useState<PendingRiskySave | null>(null);
+  const [isResetConfirmOpen, setIsResetConfirmOpen] = useState(false);
+  const [serverChangedNotice, setServerChangedNotice] = useState(false);
+  const [focusFirstErrorToken, setFocusFirstErrorToken] = useState(0);
   const saveMutation = useSaveSettingsMutation();
   const isDirty = isDraftDirty(draft, persistedDraft);
+  const seededConfig = useRef(config);
+
+  // Reconcile server refetches: re-seed a clean editor, warn a dirty one.
+  useEffect(() => {
+    if (seededConfig.current === config) return;
+    seededConfig.current = config;
+    const serverDraft = createSettingsDraft(config);
+    if (!isDraftDirty(serverDraft, persistedDraft)) return;
+    setPersistedDraft(serverDraft);
+    if (isDraftDirty(draft, persistedDraft)) {
+      setServerChangedNotice(true);
+    } else {
+      setDraft(serverDraft);
+      setServerChangedNotice(false);
+    }
+  }, [config, draft, persistedDraft]);
 
   useEffect(() => {
     function warnBeforeUnload(event: BeforeUnloadEvent) {
@@ -39,16 +85,30 @@ export function SettingsEditor({ config, section }: SettingsEditorProps) {
     return () => window.removeEventListener('beforeunload', warnBeforeUnload);
   }, [isDirty]);
 
+  // Guard in-app navigation away from settings while the draft is dirty.
+  // Section switches only change the query string, so they stay unblocked.
+  const navigationBlocker = useBlocker(({ currentLocation, nextLocation }) =>
+    isDirty && currentLocation.pathname !== nextLocation.pathname);
+
+  // After a failed save attempt, move focus to the first invalid control on screen.
+  useEffect(() => {
+    if (focusFirstErrorToken === 0) return;
+    const firstInvalid = document.querySelector<HTMLElement>('[aria-invalid="true"]');
+    firstInvalid?.focus();
+  }, [focusFirstErrorToken]);
+
   function applySavedResponse(response: Awaited<ReturnType<typeof saveMutation.mutateAsync>>) {
     const nextConfig: ConfigResponse = {
       ...response.config,
       subreddits: response.subreddits,
       tones: config.tones,
+      advanced: response.advanced ?? config.advanced,
     };
     const nextDraft = createSettingsDraft(nextConfig);
     setPersistedDraft(nextDraft);
     setDraft(nextDraft);
     setPendingRiskySave(null);
+    setServerChangedNotice(false);
   }
 
   function submit(payload: ConfigUpdateRequest) {
@@ -57,15 +117,32 @@ export function SettingsEditor({ config, section }: SettingsEditorProps) {
 
   function updateDraft(nextDraft: SettingsDraft) {
     saveMutation.reset();
-    setErrors({});
+    const editedFields = changedDraftFields(draft, nextDraft);
+    setErrors((currentErrors) => {
+      if (editedFields.length === 0) return currentErrors;
+      const next = { ...currentErrors };
+      for (const field of editedFields) delete next[field];
+      return next;
+    });
     setDraft(nextDraft);
   }
 
+  function resetDraft() {
+    setDraft(persistedDraft);
+    setErrors({});
+    setServerChangedNotice(false);
+    setIsResetConfirmOpen(false);
+    saveMutation.reset();
+  }
+
   function prepareSave() {
     saveMutation.reset();
     const validation = validateSettingsDraft(draft);
     setErrors(validation.errors);
-    if (!validation.data) return;
+    if (!validation.data) {
+      setFocusFirstErrorToken((token) => token + 1);
+      return;
+    }
 
     const reasons: string[] = [];
     if (persistedDraft.dryRun && !validation.data.dryRun) {
@@ -75,6 +152,19 @@ export function SettingsEditor({ config, section }: SettingsEditorProps) {
     if (validation.data.maxMessagesPerHour > 20 && validation.data.maxMessagesPerHour > persistedLimit) {
       reasons.push(`The limit will allow ${validation.data.maxMessagesPerHour} messages per hour.`);
     }
+    // Match persisted rows BY NAME: row insertion or reordering must never make
+    // an autonomous mode look pre-approved because of a shifted index.
+    const persistedModeByName = new Map(persistedDraft.subreddits.map((subreddit) => [
+      subreddit.name.trim().toLowerCase(),
+      subreddit.conversationMode,
+    ]));
+    const enablesAutonomousR4R = validation.data.payload.subreddits?.some((subreddit) => (
+      (subreddit.conversation.mode === 'r4r' || subreddit.conversation.mode === 'r4r-media')
+      && persistedModeByName.get(subreddit.name.trim().toLowerCase()) !== subreddit.conversation.mode
+    ));
+    if (enablesAutonomousR4R) {
+      reasons.push('Autonomous R4R will send conversational replies without approval for the selected subreddit. The hybrid mode can make one optional image request after rapport. Existing conversations keep their snapshotted policy.');
+    }
 
     if (reasons.length > 0) {
       setPendingRiskySave({ payload: validation.data.payload, reasons });
@@ -83,6 +173,8 @@ export function SettingsEditor({ config, section }: SettingsEditorProps) {
     submit(validation.data.payload);
   }
 
+  const errorCount = Object.keys(errors).length;
+
   return (
     <>
       {section === 'monitoring' ? <MonitoringSection draft={draft} errors={errors} onChange={updateDraft} /> : null}
@@ -94,12 +186,18 @@ export function SettingsEditor({ config, section }: SettingsEditorProps) {
         <div className="settings-save-bar">
           <div aria-live="polite">
             {isDirty ? <span role="status">You have unsaved changes.</span> : <span>All changes saved.</span>}
+            {serverChangedNotice ? <strong className="save-warning" role="status">Settings changed on the server — Reset to load them.</strong> : null}
+            {errorCount > 0 ? (
+              <strong className="save-error" role="alert">
+                {errorCount === 1 ? 'Resolve 1 validation error before saving.' : `Resolve ${errorCount} validation errors before saving.`}
+              </strong>
+            ) : null}
             {saveMutation.isSuccess ? <strong className="save-success">Settings saved.</strong> : null}
             {saveMutation.isError ? <strong className="save-error" role="alert">{errorMessage(saveMutation.error)}</strong> : null}
           </div>
           <div className="header-actions">
-            <button className="button secondary" disabled={!isDirty || saveMutation.isPending} onClick={() => { setDraft(persistedDraft); setErrors({}); saveMutation.reset(); }} type="button">Reset changes</button>
-            <button aria-label={saveMutation.isPending ? 'Saving settings' : 'Save settings'} className="button primary" disabled={!isDirty || saveMutation.isPending} onClick={prepareSave} type="button">{saveMutation.isPending ? 'Saving…' : 'Save settings'}</button>
+            <button className="button secondary" disabled={(!isDirty && !serverChangedNotice) || saveMutation.isPending} onClick={() => { if (isDirty) setIsResetConfirmOpen(true); else resetDraft(); }} type="button">Reset changes</button>
+            <button aria-busy={saveMutation.isPending ? 'true' : undefined} aria-label={saveMutation.isPending ? 'Saving settings' : 'Save settings'} className="button primary" disabled={!isDirty || saveMutation.isPending} onClick={prepareSave} type="button">{saveMutation.isPending ? 'Saving…' : 'Save settings'}</button>
           </div>
         </div>
       ) : null}
@@ -112,6 +210,22 @@ export function SettingsEditor({ config, section }: SettingsEditorProps) {
           reasons={pendingRiskySave.reasons}
         />
       ) : null}
+      {isResetConfirmOpen ? (
+        <DiscardDraftDialog
+          body="Your unsaved edits will be replaced with the last saved settings."
+          onDiscard={resetDraft}
+          onStay={() => setIsResetConfirmOpen(false)}
+          title="Discard unsaved settings?"
+        />
+      ) : null}
+      {navigationBlocker.state === 'blocked' ? (
+        <DiscardDraftDialog
+          body="Leaving this page will discard your unsaved settings."
+          onDiscard={() => navigationBlocker.proceed()}
+          onStay={() => navigationBlocker.reset()}
+          title="Discard unsaved settings?"
+        />
+      ) : null}
     </>
   );
 }

apps/dashboard/src/features/settings/settings-model.ts

@@ -8,11 +8,17 @@ import {
 } from '../../../../../packages/api-contracts/src/index.js';
 
 export interface SubredditDraft {
+  /** Stable client-side row identity for React keys; excluded from dirty comparison. */
+  rowId: string;
   name: string;
+  enabled: boolean;
   type: 'image' | 'chat';
   weight: string;
   tone: z.infer<typeof ToneKeySchema>;
   scripted: string;
+  conversationMode: 'legacy' | 'r4r' | 'r4r-media' | 'manual';
+  maxAutomatedTurns: string;
+  rapportTurnsBeforeMediaAsk: string;
 }
 
 export interface SettingsDraft {
@@ -22,7 +28,9 @@ export interface SettingsDraft {
   dryRun: boolean;
   prioritizeRecentPosts: boolean;
   recentWindowMinutes: string;
+  maxReadyCandidates: string;
   subreddits: SubredditDraft[];
+  advancedConfigJson: string;
 }
 
 export interface ValidatedSettings {
@@ -48,6 +56,7 @@ const ValidatedSettingsSchema = z.strictObject({
   dryRun: z.boolean(),
   prioritizeRecentPosts: z.boolean(),
   recentWindowMinutes: z.number().finite().positive('Recent window must be greater than 0 minutes.'),
+  maxReadyCandidates: z.number().int().min(1, 'Ready-post limit must be at least 1.').max(500, 'Ready-post limit cannot exceed 500.'),
   subreddits: z.array(EditableSubredditSchema).min(1, 'At least one subreddit is required.'),
 }).superRefine((value, context) => {
   const names = value.subreddits.map((subreddit) => subreddit.name.trim().toLowerCase());
@@ -56,6 +65,13 @@ const ValidatedSettingsSchema = z.strictObject({
   }
 });
 
+let nextRowId = 0;
+
+export function createSubredditRowId(): string {
+  nextRowId += 1;
+  return `subreddit-row-${nextRowId}`;
+}
+
 export function createSettingsDraft(config: ConfigResponse): SettingsDraft {
   return {
     minDelayMinutes: String(config.rateLimit.minDelayBetweenMessagesMs / 60_000),
@@ -64,13 +80,20 @@ export function createSettingsDraft(config: ConfigResponse): SettingsDraft {
     dryRun: config.browser.dryRun,
     prioritizeRecentPosts: config.reddit.prioritizeRecentPosts,
     recentWindowMinutes: String(config.reddit.recentWindowMinutes),
+    maxReadyCandidates: String(config.reddit.maxReadyCandidates),
     subreddits: config.subreddits.map((subreddit) => ({
+      rowId: createSubredditRowId(),
       name: subreddit.name,
+      enabled: subreddit.enabled,
       type: subreddit.type,
       weight: subreddit.weight === undefined ? '' : String(subreddit.weight),
       tone: subreddit.tone,
       scripted: subreddit.scripted ?? '',
+      conversationMode: subreddit.conversation.mode,
+      maxAutomatedTurns: String(subreddit.conversation.maxAutomatedTurns),
+      rapportTurnsBeforeMediaAsk: String(subreddit.conversation.rapportTurnsBeforeMediaAsk),
     })),
+    advancedConfigJson: config.advanced ? JSON.stringify(config.advanced, null, 2) : '',
   };
 }
 
@@ -80,13 +103,34 @@ export function validateSettingsDraft(draft: SettingsDraft): SettingsValidationR
   if (draft.maxMessagesPerHour.trim() === '') requiredErrors.maxMessagesPerHour = 'Maximum messages per hour is required.';
   if (draft.jitterSeconds.trim() === '') requiredErrors.jitterSeconds = 'Jitter is required.';
   if (draft.recentWindowMinutes.trim() === '') requiredErrors.recentWindowMinutes = 'Recent window is required.';
+  if (draft.maxReadyCandidates.trim() === '') requiredErrors.maxReadyCandidates = 'Ready-post limit is required.';
   draft.subreddits.forEach((subreddit, index) => {
     if (subreddit.name.trim() === '') requiredErrors[`subreddits.${index}.name`] = 'Subreddit name is required.';
     if (subreddit.weight.trim() !== '' && Number(subreddit.weight) <= 0) {
       requiredErrors[`subreddits.${index}.weight`] = 'Subreddit weight must be greater than 0.';
     }
+    if ((subreddit.conversationMode === 'r4r' || subreddit.conversationMode === 'r4r-media')
+      && subreddit.maxAutomatedTurns.trim() === '') {
+      requiredErrors[`subreddits.${index}.maxAutomatedTurns`] = 'Maximum automated turns is required.';
+    }
+    if (subreddit.conversationMode === 'r4r-media' && subreddit.rapportTurnsBeforeMediaAsk.trim() === '') {
+      requiredErrors[`subreddits.${index}.rapportTurnsBeforeMediaAsk`] = 'Rapport turns is required.';
+    }
   });
-  if (Object.keys(requiredErrors).length > 0) return { errors: requiredErrors };
+  let advanced: Record<string, unknown> | undefined;
+  let advancedError: string | undefined;
+  if (draft.advancedConfigJson.trim() !== '') {
+    try {
+      const value: unknown = JSON.parse(draft.advancedConfigJson);
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        advancedError = 'Advanced configuration must be a JSON object.';
+      } else {
+        advanced = value as Record<string, unknown>;
+      }
+    } catch {
+      advancedError = 'Advanced configuration is not valid JSON.';
+    }
+  }
 
   const parsed = ValidatedSettingsSchema.safeParse({
     minDelayMinutes: Number(draft.minDelayMinutes),
@@ -95,23 +139,40 @@ export function validateSettingsDraft(draft: SettingsDraft): SettingsValidationR
     dryRun: draft.dryRun,
     prioritizeRecentPosts: draft.prioritizeRecentPosts,
     recentWindowMinutes: Number(draft.recentWindowMinutes),
+    maxReadyCandidates: Number(draft.maxReadyCandidates),
     subreddits: draft.subreddits.map((subreddit) => ({
       name: subreddit.name.trim(),
+      enabled: subreddit.enabled,
       type: subreddit.type,
       weight: subreddit.weight.trim() === '' ? undefined : Number(subreddit.weight),
       tone: subreddit.tone,
       scripted: subreddit.scripted.trim() === '' ? undefined : subreddit.scripted,
+      conversation: {
+        mode: subreddit.conversationMode,
+        maxAutomatedTurns: subreddit.conversationMode === 'r4r' || subreddit.conversationMode === 'r4r-media'
+          ? Number(subreddit.maxAutomatedTurns)
+          : 3,
+        rapportTurnsBeforeMediaAsk: subreddit.conversationMode === 'r4r-media'
+          ? Number(subreddit.rapportTurnsBeforeMediaAsk)
+          : 3,
+      },
     })),
   });
 
-  if (!parsed.success) {
+  // Run required-field and schema validation in one pass so every problem
+  // surfaces on the first save attempt. Required-field messages win per field.
   const errors: Record<string, string> = {};
+  if (!parsed.success) {
     for (const issue of parsed.error.issues) {
-      const path = issue.path.join('.');
+      const pathParts = [...issue.path];
+      if (pathParts[0] === 'subreddits' && pathParts[2] === 'conversation') pathParts.splice(2, 1);
+      const path = pathParts.join('.');
       if (!(path in errors)) errors[path] = issue.message;
     }
-    return { errors };
   }
+  if (advancedError) errors.advancedConfigJson = advancedError;
+  Object.assign(errors, requiredErrors);
+  if (!parsed.success || Object.keys(errors).length > 0) return { errors };
 
   const payload = ConfigUpdateRequestSchema.parse({
     rateLimit: {
@@ -123,8 +184,10 @@ export function validateSettingsDraft(draft: SettingsDraft): SettingsValidationR
     reddit: {
       prioritizeRecentPosts: parsed.data.prioritizeRecentPosts,
       recentWindowMinutes: parsed.data.recentWindowMinutes,
+      maxReadyCandidates: parsed.data.maxReadyCandidates,
     },
     subreddits: parsed.data.subreddits,
+    ...(advanced ? { advanced } : {}),
   });
 
   return {
@@ -137,6 +200,46 @@ export function validateSettingsDraft(draft: SettingsDraft): SettingsValidationR
   };
 }
 
+function comparableDraft(draft: SettingsDraft): unknown {
+  return {
+    ...draft,
+    subreddits: draft.subreddits.map(({ rowId: _rowId, ...subreddit }) => subreddit),
+  };
+}
+
 export function isDraftDirty(draft: SettingsDraft, persisted: SettingsDraft): boolean {
-  return JSON.stringify(draft) !== JSON.stringify(persisted);
+  return JSON.stringify(comparableDraft(draft)) !== JSON.stringify(comparableDraft(persisted));
+}
+
+/**
+ * Field keys (matching validation error keys) whose values differ between two drafts.
+ * Used to clear validation errors only for the fields the user edited.
+ */
+export function changedDraftFields(previous: SettingsDraft, next: SettingsDraft): string[] {
+  const changed: string[] = [];
+  const topLevelKeys = ['minDelayMinutes', 'maxMessagesPerHour', 'jitterSeconds', 'dryRun', 'prioritizeRecentPosts', 'recentWindowMinutes', 'maxReadyCandidates', 'advancedConfigJson'] as const;
+  for (const key of topLevelKeys) {
+    if (previous[key] !== next[key]) changed.push(key);
+  }
+  if (previous.subreddits.length !== next.subreddits.length) {
+    changed.push('subreddits');
+    // Row indices shift on add/remove, so any indexed subreddit error may be stale.
+    for (let index = 0; index < Math.max(previous.subreddits.length, next.subreddits.length); index += 1) {
+      for (const field of ['name', 'weight', 'maxAutomatedTurns', 'rapportTurnsBeforeMediaAsk'] as const) {
+        changed.push(`subreddits.${index}.${field}`);
+      }
+    }
+    return changed;
+  }
+  next.subreddits.forEach((subreddit, index) => {
+    const previousSubreddit = previous.subreddits[index];
+    if (!previousSubreddit) return;
+    for (const field of ['name', 'enabled', 'type', 'weight', 'tone', 'scripted', 'conversationMode', 'maxAutomatedTurns', 'rapportTurnsBeforeMediaAsk'] as const) {
+      if (previousSubreddit[field] !== subreddit[field]) {
+        changed.push(`subreddits.${index}.${field}`);
+        if (field === 'name') changed.push('subreddits');
+      }
+    }
+  });
+  return changed;
 }

apps/dashboard/src/features/settings/settings-page.tsx

@@ -13,7 +13,7 @@ const sections: ReadonlyArray<{ id: SettingsSection; label: string; description:
   { id: 'monitoring', label: 'Monitoring', description: 'Post discovery and recency' },
   { id: 'rate-limits', label: 'Rate limits', description: 'Sending pace and safeguards' },
   { id: 'behaviour', label: 'Behaviour', description: 'Dry run and subreddits' },
-  { id: 'access', label: 'Access', description: 'Reddit browser session' },
+  { id: 'access', label: 'Access', description: 'Extension session dump' },
 ];
 
 function errorMessage(error: Error | null): string {
@@ -26,7 +26,7 @@ export function SettingsPage({ section, onSectionChange }: SettingsPageProps) {
   return (
     <div className="page settings-page">
       <header className="page-header">
-        <div><span className="eyebrow">Platform configuration</span><h1>Settings</h1><p>Manage supported runtime behaviour and Reddit browser access.</p></div>
+        <div><span className="eyebrow">Platform configuration</span><h1>Settings</h1><p>Manage supported runtime behaviour and Reddit account access.</p></div>
       </header>
       <nav aria-label="Settings sections" className="settings-navigation">
         {sections.map((item) => (

apps/dashboard/src/features/settings/settings-queries.ts

@@ -1,11 +1,11 @@
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import type { ConfigResponse } from '../../../../../packages/api-contracts/src/index.js';
-import { fetchLoginInfo, fetchLoginStatus, fetchSettings, saveSettings, startLogin } from './settings-api.js';
+import { fetchLoginStatus, fetchRedditAccounts, fetchSettings, importRedditSession, saveSettings } from './settings-api.js';
 
 export const settingsQueryKeys = {
   config: ['dashboard', 'config'] as const,
-  loginInfo: ['dashboard', 'login', 'info'] as const,
   loginStatus: ['dashboard', 'login', 'status'] as const,
+  accounts: ['dashboard', 'reddit-accounts'] as const,
 };
 
 export function useSettingsQuery() {
@@ -21,25 +21,33 @@ export function useSaveSettingsMutation() {
         ...response.config,
         subreddits: response.subreddits,
         tones: current?.tones ?? [],
+        advanced: response.advanced ?? current?.advanced,
       }));
     },
   });
 }
 
-export function useLoginInfoQuery() {
-  return useQuery({ queryKey: settingsQueryKeys.loginInfo, queryFn: fetchLoginInfo });
-}
-
 export function useLoginStatusQuery() {
   return useQuery({ queryKey: settingsQueryKeys.loginStatus, queryFn: fetchLoginStatus });
 }
 
-export function useStartLoginMutation() {
+export function useRedditAccountsQuery() {
+  return useQuery({ queryKey: settingsQueryKeys.accounts, queryFn: fetchRedditAccounts });
+}
+
+function invalidateAccountContent(queryClient: ReturnType<typeof useQueryClient>) {
+  void queryClient.invalidateQueries({ queryKey: settingsQueryKeys.loginStatus });
+  void queryClient.invalidateQueries({ queryKey: settingsQueryKeys.accounts });
+  void queryClient.invalidateQueries({ queryKey: ['dashboard', 'conversations'] });
+  void queryClient.invalidateQueries({ queryKey: ['dashboard', 'media'] });
+}
+
+export function useImportRedditSessionMutation() {
   const queryClient = useQueryClient();
   return useMutation({
-    mutationFn: startLogin,
+    mutationFn: importRedditSession,
     onSuccess() {
-      void queryClient.invalidateQueries({ queryKey: settingsQueryKeys.loginStatus });
+      invalidateAccountContent(queryClient);
     },
   });
 }

apps/dashboard/src/features/settings/settings-sections.tsx

@@ -1,5 +1,5 @@
 import type { ConfigResponse } from '../../../../../packages/api-contracts/src/index.js';
-import type { SettingsDraft, SubredditDraft } from './settings-model.js';
+import { createSubredditRowId, type SettingsDraft, type SubredditDraft } from './settings-model.js';
 
 interface SectionProps {
   draft: SettingsDraft;
@@ -58,6 +58,14 @@ export function MonitoringSection({ draft, errors, onChange }: SectionProps) {
         onChange={(recentWindowMinutes) => onChange({ ...draft, recentWindowMinutes })}
         value={draft.recentWindowMinutes}
       />
+      <NumberField
+        error={errors.maxReadyCandidates}
+        label="Maximum ready posts"
+        min={1}
+        name="maximum-ready-posts"
+        onChange={(maxReadyCandidates) => onChange({ ...draft, maxReadyCandidates })}
+        value={draft.maxReadyCandidates}
+      />
     </section>
   );
 }
@@ -122,7 +130,7 @@ export function BehaviourSection({ config, draft, errors, onChange }: SectionPro
             ...draft,
             subreddits: [
               ...draft.subreddits,
-              { name: '', type: 'image', weight: '1', tone: 'default', scripted: '' },
+              { rowId: createSubredditRowId(), name: '', enabled: true, type: 'image', weight: '1', tone: 'default', scripted: '', conversationMode: 'legacy', maxAutomatedTurns: '3', rapportTurnsBeforeMediaAsk: '3' },
             ],
           })}
           type="button"
@@ -133,7 +141,7 @@ export function BehaviourSection({ config, draft, errors, onChange }: SectionPro
       {errors.subreddits ? <p className="field-error" role="alert">{errors.subreddits}</p> : null}
       <div className="subreddit-list">
         {draft.subreddits.map((subreddit, index) => (
-          <fieldset className="subreddit-row" key={index}>
+          <fieldset className="subreddit-row" key={subreddit.rowId}>
             <legend>Subreddit {index + 1}</legend>
             <label className="settings-field">
               <span>Name</span>
@@ -157,6 +165,15 @@ export function BehaviourSection({ config, draft, errors, onChange }: SectionPro
                 <option value="image">Image</option><option value="chat">Chat</option>
               </select>
             </label>
+            <label className="toggle-field">
+              <input
+                aria-label={`Subreddit ${index + 1} enabled`}
+                checked={subreddit.enabled}
+                onChange={(event) => onChange(updateSubreddit(draft, index, { ...subreddit, enabled: event.target.checked }))}
+                type="checkbox"
+              />
+              <span><strong>Enabled</strong><small>Disabled subreddits are not polled.</small></span>
+            </label>
             <label className="settings-field">
               <span>Weight</span>
               <input
@@ -181,6 +198,63 @@ export function BehaviourSection({ config, draft, errors, onChange }: SectionPro
                 {config.tones.map((tone) => <option key={tone} value={tone}>{tone}</option>)}
               </select>
             </label>
+            <label className="settings-field">
+              <span>Conversation behaviour</span>
+              <select
+                aria-label={`Subreddit ${index + 1} conversation behaviour`}
+                onChange={(event) => onChange(updateSubreddit(draft, index, {
+                  ...subreddit,
+                  conversationMode: event.target.value as SubredditDraft['conversationMode'],
+                }))}
+                value={subreddit.conversationMode}
+              >
+                <option value="legacy">Legacy media asks</option>
+                <option value="r4r">Autonomous R4R conversation</option>
+                <option value="r4r-media">R4R then one media ask</option>
+                <option value="manual">Manual only</option>
+              </select>
+              <small>{subreddit.conversationMode === 'r4r'
+                ? 'Continues general conversation autonomously. It will not request sexual media.'
+                : subreddit.conversationMode === 'r4r-media'
+                  ? 'Builds rapport autonomously, then makes one optional, non-explicit image request.'
+                : subreddit.conversationMode === 'manual'
+                  ? 'Incoming replies are marked for human handling and are never answered automatically.'
+                  : 'Preserves the existing three-turn media-request flow.'}</small>
+            </label>
+            {subreddit.conversationMode === 'r4r' || subreddit.conversationMode === 'r4r-media' ? (
+              <label className="settings-field">
+                <span>Maximum automated turns</span>
+                <input
+                  aria-describedby={errors[`subreddits.${index}.maxAutomatedTurns`] ? `subreddit-${index}-max-turns-error` : undefined}
+                  aria-invalid={errors[`subreddits.${index}.maxAutomatedTurns`] ? 'true' : undefined}
+                  aria-label={`Subreddit ${index + 1} maximum automated turns`}
+                  max="20"
+                  min="1"
+                  onChange={(event) => onChange(updateSubreddit(draft, index, { ...subreddit, maxAutomatedTurns: event.target.value }))}
+                  step="1"
+                  type="number"
+                  value={subreddit.maxAutomatedTurns}
+                />
+                {errors[`subreddits.${index}.maxAutomatedTurns`] ? <small className="field-error" id={`subreddit-${index}-max-turns-error`}>{errors[`subreddits.${index}.maxAutomatedTurns`]}</small> : null}
+              </label>
+            ) : null}
+            {subreddit.conversationMode === 'r4r-media' ? (
+              <label className="settings-field">
+                <span>Rapport turns before media ask</span>
+                <input
+                  aria-describedby={errors[`subreddits.${index}.rapportTurnsBeforeMediaAsk`] ? `subreddit-${index}-rapport-turns-error` : undefined}
+                  aria-invalid={errors[`subreddits.${index}.rapportTurnsBeforeMediaAsk`] ? 'true' : undefined}
+                  aria-label={`Subreddit ${index + 1} rapport turns before media ask`}
+                  max="19"
+                  min="1"
+                  onChange={(event) => onChange(updateSubreddit(draft, index, { ...subreddit, rapportTurnsBeforeMediaAsk: event.target.value }))}
+                  step="1"
+                  type="number"
+                  value={subreddit.rapportTurnsBeforeMediaAsk}
+                />
+                {errors[`subreddits.${index}.rapportTurnsBeforeMediaAsk`] ? <small className="field-error" id={`subreddit-${index}-rapport-turns-error`}>{errors[`subreddits.${index}.rapportTurnsBeforeMediaAsk`]}</small> : null}
+              </label>
+            ) : null}
             <label className="settings-field scripted-field">
               <span>Scripted message (optional)</span>
               <textarea
@@ -204,6 +278,23 @@ export function BehaviourSection({ config, draft, errors, onChange }: SectionPro
           </fieldset>
         ))}
       </div>
+      {config.advanced ? (
+        <div className="advanced-settings">
+          <div><h3>Advanced application configuration</h3><p>Models, prompts, filtering, media sync, and strategy settings. Some changes take effect after a restart.</p></div>
+          <label className="settings-field">
+            <span>Advanced configuration (JSON)</span>
+            <textarea
+              aria-invalid={errors.advancedConfigJson ? 'true' : undefined}
+              aria-label="Advanced configuration JSON"
+              onChange={(event) => onChange({ ...draft, advancedConfigJson: event.target.value })}
+              rows={24}
+              spellCheck={false}
+              value={draft.advancedConfigJson}
+            />
+            {errors.advancedConfigJson ? <small className="field-error">{errors.advancedConfigJson}</small> : null}
+          </label>
+        </div>
+      ) : null}
     </section>
   );
 }

apps/dashboard/src/features/settings/settings.css

@@ -28,13 +28,14 @@
 .settings-save-bar { position: sticky; bottom: 1rem; display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 1rem; padding: .9rem 1rem; margin-top: 1rem; background: rgba(23, 35, 30, .97); border: 1px solid var(--border); border-radius: .8rem; box-shadow: 0 1rem 3rem rgba(0, 0, 0, .3); }
 .settings-save-bar > div:first-child { display: grid; gap: .15rem; color: var(--muted); }
 .save-success { color: var(--accent); }
+.save-warning { color: var(--warning); }
 .risk-list { display: grid; gap: .5rem; padding-left: 1.2rem; color: var(--warning); }
 .access-actions { display: flex; flex-wrap: wrap; gap: .75rem; }
 .access-actions a { display: inline-flex; align-items: center; text-decoration: none; }
 .settings-notice { padding: .75rem; border-radius: .65rem; }
-.settings-notice.success { color: #aaf0c4; background: #163a26; }
-.settings-notice.warning { color: #ffe1a0; background: #42351b; }
-.settings-notice.error { color: #ffd1ce; background: #461b18; }
+.settings-notice.success { color: var(--success-text); background: var(--success-bg); }
+.settings-notice.warning { color: var(--warning-text); background: var(--warning-bg); }
+.settings-notice.error { color: var(--danger-text); background: var(--danger-bg); }
 
 @media (min-width: 42rem) {
   .settings-navigation { grid-template-columns: repeat(2, minmax(0, 1fr)); }
@@ -46,3 +47,26 @@
 @media (min-width: 70rem) {
   .settings-navigation { grid-template-columns: repeat(4, minmax(0, 1fr)); }
 }
+.reddit-account-list {
+  display: grid;
+  gap: .65rem;
+}
+
+.reddit-account-row {
+  align-items: center;
+  border: 1px solid var(--border);
+  border-radius: .75rem;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+  padding: .75rem;
+}
+
+.reddit-account-row.is-active {
+  border-color: var(--accent);
+}
+
+.reddit-account-row > div {
+  display: grid;
+  gap: .2rem;
+}

apps/dashboard/src/styles.css

@@ -12,14 +12,27 @@
   --accent-dark: #153c28;
   --danger: #ff8a84;
   --warning: #f3c76b;
+  --success-text: #aaf0c4;
+  --success-bg: #163a26;
+  --success-border: #28593d;
+  --warning-text: #ffe1a0;
+  --warning-bg: #2a2111;
+  --warning-border: #59451e;
+  --danger-text: #ffd1ce;
+  --danger-bg: #461b18;
+  --danger-border: #80352f;
 }
 
 * { box-sizing: border-box; }
 body { margin: 0; min-width: 320px; min-height: 100vh; }
 button, input { font: inherit; }
 button { cursor: pointer; }
-button:disabled { cursor: wait; opacity: .6; }
+button:disabled { cursor: not-allowed; opacity: .6; }
+button[aria-busy="true"]:disabled { cursor: wait; }
+.sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
 a { color: inherit; }
+.reddit-username-link { color: var(--accent); text-decoration: underline; text-decoration-thickness: .08em; text-underline-offset: .16em; }
+.reddit-username-link:hover { color: #aaf0c4; }
 
 .skip-link { position: fixed; left: 1rem; top: -5rem; z-index: 100; background: white; color: black; padding: .75rem 1rem; border-radius: .5rem; }
 .skip-link:focus { top: 1rem; }
@@ -40,6 +53,7 @@ nav { display: grid; gap: .35rem; }
 .navigation-backdrop { position: fixed; inset: 0; z-index: 20; width: 100%; border: 0; background: rgba(0, 0, 0, .6); }
 .workspace { min-height: 100vh; }
 .mobile-header { position: sticky; top: 0; z-index: 15; display: flex; align-items: center; justify-content: space-between; height: 4rem; padding: 0 1rem; background: rgba(9, 17, 14, .92); border-bottom: 1px solid var(--border); backdrop-filter: blur(12px); font-weight: 700; }
+.mobile-header-actions { display: flex; gap: .55rem; }
 .icon-button { width: 2.5rem; height: 2.5rem; border: 1px solid var(--border); border-radius: .6rem; color: white; background: var(--surface); font-size: 1.25rem; }
 main { min-height: calc(100vh - 4rem); }
 .page { width: min(78rem, 100%); margin: 0 auto; padding: 1.5rem 1rem 4rem; }
@@ -63,16 +77,31 @@ h2 { margin-bottom: 0; font-size: 1.1rem; }
 .status-dot.stopped { background: var(--danger); box-shadow: 0 0 0 .35rem rgba(255, 138, 132, .1); }
 .pill { display: inline-flex; align-items: center; padding: .3rem .55rem; border-radius: 999px; font-size: .75rem; font-weight: 800; }
 .pill.neutral { color: #d4dfda; background: #2b3832; }
-.pill.success { color: #aaf0c4; background: #163a26; }
-.pill.warning { color: #ffe1a0; background: #42351b; }
+.pill.success { color: var(--success-text); background: var(--success-bg); }
+.pill.warning { color: var(--warning-text); background: #42351b; }
+.pill.danger { color: var(--danger-text); background: var(--danger-bg); }
 .status-note { margin-left: auto; color: var(--muted); font-size: .85rem; }
-.cooldown-banner { display: grid; gap: .25rem; padding: .9rem 1rem; margin-bottom: 1rem; color: #ffe1a0; background: #2a2111; border: 1px solid #59451e; border-radius: .8rem; }
+.cooldown-banner { display: grid; gap: .25rem; padding: .9rem 1rem; margin-bottom: 1rem; color: var(--warning-text); background: var(--warning-bg); border: 1px solid var(--warning-border); border-radius: .8rem; }
 .cooldown-banner span { font-size: .85rem; }
 .metrics-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: .75rem; margin-bottom: .75rem; }
 .metric-card, .panel { background: var(--surface); border: 1px solid var(--border); border-radius: .9rem; }
 .metric-card { display: grid; gap: .3rem; padding: 1rem; }
 .metric-card > span, .metric-card small { color: var(--muted); }
 .metric-card strong { font-size: 1.75rem; letter-spacing: -.04em; }
+.account-status-panel { margin-bottom: .75rem; }
+.account-status-grid { display: grid; gap: .75rem; }
+.account-status-card { display: grid; gap: .75rem; padding: .9rem; background: var(--surface-raised); border: 1px solid var(--border); border-radius: .75rem; }
+.account-status-heading { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: .75rem; }
+.account-status-card > p { margin: 0; color: var(--muted); font-size: .85rem; }
+.account-status-details { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: .45rem .9rem; margin: 0; }
+.account-status-details div { display: grid; gap: .1rem; }
+.account-status-details dt { color: var(--muted); font-size: .72rem; }
+.account-status-details dd { margin: 0; font-weight: 700; text-transform: capitalize; }
+.account-status-note { color: var(--muted); }
+.account-status-warning { display: grid; gap: .25rem; padding: .65rem; color: var(--warning-text); background: var(--warning-bg); border: 1px solid var(--warning-border); border-radius: .55rem; }
+.account-status-warning span { font-size: .8rem; }
+.account-status-warning code { width: fit-content; padding: .15rem .3rem; color: inherit; background: rgba(0, 0, 0, .25); border-radius: .25rem; }
+.account-status-warning.is-error { color: var(--danger-text); background: var(--danger-bg); border-color: var(--danger-border); }
 .overview-grid { display: grid; gap: .75rem; }
 .panel { padding: 1rem; }
 .panel-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 1rem; margin-bottom: 1rem; }
@@ -86,6 +115,35 @@ h2 { margin-bottom: 0; font-size: 1.1rem; }
 .activity-list li { display: flex; align-items: flex-start; gap: .75rem; }
 .activity-list li div { display: grid; gap: .15rem; }
 .activity-list small { color: var(--muted); }
+.origin-post-trigger { padding: 0; color: inherit; background: transparent; border: 0; font: inherit; font-weight: inherit; text-align: left; text-decoration: underline; text-decoration-color: var(--accent); text-underline-offset: .2em; cursor: pointer; }
+.origin-post-trigger:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+dialog.origin-post-dialog { width: min(34rem, calc(100% - 2rem)); max-height: calc(100vh - 2rem); padding: 0; overflow: auto; background: var(--surface-raised); border: 1px solid var(--border); border-radius: 1rem; box-shadow: 0 2rem 5rem rgba(0, 0, 0, .5); }
+dialog.origin-post-dialog::backdrop { background: rgba(0, 0, 0, .82); }
+.origin-post-dialog img { display: block; width: 100%; max-height: 28rem; object-fit: contain; background: #050907; }
+.origin-post-dialog-heading { display: flex; align-items: center; justify-content: space-between; padding: .65rem .8rem; color: var(--muted); border-bottom: 1px solid var(--border); font-size: .75rem; font-weight: 800; letter-spacing: .08em; text-transform: uppercase; }
+.origin-post-dialog-heading button { width: 2.25rem; height: 2.25rem; padding: 0; color: inherit; background: transparent; border: 0; font-size: 1.6rem; cursor: pointer; }
+.origin-post-dialog-copy { display: grid; gap: .7rem; padding: 1rem; }
+.origin-post-dialog-copy h2 { margin: 0; font-size: 1.25rem; }
+.origin-post-dialog-copy small { color: var(--muted); }
+.origin-post-dialog-copy a { justify-self: start; text-decoration: none; }
+.origin-post-card { display: grid; grid-template-columns: auto minmax(0, 1fr); gap: .8rem; align-items: center; }
+.origin-post-image { position: relative; width: 5rem; height: 5rem; overflow: hidden; background: #050907; border-radius: .45rem; }
+.origin-post-image-preview-trigger { display: block; width: 100%; height: 100%; min-height: 0; padding: 0; overflow: hidden; background: transparent; border: 0; border-radius: inherit; cursor: zoom-in; }
+.origin-post-image-preview-trigger:disabled { cursor: default; }
+.origin-post-image-preview-trigger:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
+.origin-post-image img { display: block; width: 100%; height: 100%; object-fit: cover; transition: filter 160ms ease, transform 160ms ease; }
+.origin-post-image img.is-blurred { filter: blur(18px) brightness(.55); transform: scale(1.12); }
+.origin-post-image .origin-post-image-reveal { position: absolute; right: .2rem; bottom: .2rem; min-height: auto; padding: .2rem .3rem; border: 1px solid rgba(255, 255, 255, .45); border-radius: .3rem; color: white; background: rgba(0, 0, 0, .76); font-size: .58rem; font-weight: 800; }
+.origin-post-image-reveal:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
+dialog.origin-image-preview { width: 100vw; height: 100vh; max-width: 100vw; max-height: 100vh; padding: 1rem; background: transparent; }
+dialog.origin-image-preview::backdrop { background: rgba(0, 0, 0, .92); }
+.origin-image-preview-content { position: relative; display: flex; align-items: center; justify-content: center; width: 100%; height: 100%; }
+.origin-image-preview-content img { display: block; width: auto; height: auto; max-width: 100%; max-height: 100%; object-fit: contain; }
+.origin-image-preview-content button { position: absolute; top: .5rem; right: .5rem; width: 2.75rem; height: 2.75rem; padding: 0; border: 1px solid rgba(255, 255, 255, .5); border-radius: 50%; color: white; background: rgba(0, 0, 0, .7); font-size: 2rem; line-height: 1; cursor: pointer; }
+.origin-image-preview-content button:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+.origin-post-copy { display: grid; gap: .2rem; min-width: 0; color: inherit; text-decoration: none; }
+.origin-post-card small, .origin-post-card span { color: var(--muted); font-size: .75rem; }
+.origin-post-card strong { overflow-wrap: anywhere; }
 .activity-marker { flex: 0 0 auto; width: .55rem; height: .55rem; margin-top: .3rem; border-radius: 50%; background: var(--muted); }
 .activity-marker.sent, .activity-marker.response { background: var(--accent); }
 .activity-marker.error { background: var(--danger); }
@@ -94,12 +152,34 @@ h2 { margin-bottom: 0; font-size: 1.1rem; }
 .error-panel, .panel-loading { display: grid; place-items: center; align-content: center; gap: .75rem; min-height: 14rem; text-align: center; color: var(--muted); }
 .spinner { width: 1.4rem; height: 1.4rem; border: 2px solid var(--border); border-top-color: var(--accent); border-radius: 50%; animation: spin .8s linear infinite; }
 @keyframes spin { to { transform: rotate(360deg); } }
-.dialog-backdrop { position: fixed; inset: 0; z-index: 60; display: grid; place-items: center; padding: 1rem; background: rgba(0, 0, 0, .72); }
-.dialog-card { width: min(28rem, 100%); padding: 1.4rem; background: var(--surface-raised); border: 1px solid var(--border); border-radius: 1rem; box-shadow: 0 2rem 5rem rgba(0, 0, 0, .4); }
+dialog.modal { color: inherit; border: 0; background: transparent; }
+dialog.modal::backdrop { background: rgba(0, 0, 0, .72); }
+body:has(dialog.modal[open]) { overflow: hidden; }
+dialog.dialog-card { width: min(28rem, calc(100% - 2rem)); padding: 1.4rem; background: var(--surface-raised); border: 1px solid var(--border); border-radius: 1rem; box-shadow: 0 2rem 5rem rgba(0, 0, 0, .4); }
 .dialog-card p { color: var(--muted); }
+.dialog-error { padding: .65rem .8rem; color: var(--danger-text); background: var(--danger-bg); border: 1px solid var(--danger-border); border-radius: .55rem; }
 .dialog-actions { justify-content: flex-end; margin-top: 1.5rem; }
-.toast { position: fixed; right: 1rem; bottom: 1rem; max-width: 25rem; padding: .8rem 1rem; border-radius: .7rem; }
-.toast.error { color: #ffd1ce; background: #461b18; border: 1px solid #80352f; }
+.toast { position: fixed; right: 1rem; bottom: 1rem; z-index: 110; display: flex; align-items: baseline; gap: .6rem; max-width: 25rem; padding: .8rem 1rem; border-radius: .7rem; }
+.toast.error { color: var(--danger-text); background: var(--danger-bg); border: 1px solid var(--danger-border); }
+.toast button { min-height: auto; padding: 0; color: inherit; background: transparent; border: 0; font-weight: 800; text-decoration: underline; }
+
+.account-owner-badge {
+  align-self: flex-start;
+  align-items: center;
+  background: color-mix(in srgb, var(--accent, #ff6534) 12%, transparent);
+  border: 1px solid color-mix(in srgb, var(--accent, #ff6534) 35%, transparent);
+  border-radius: 999px;
+  display: inline-flex;
+  font-size: .75rem;
+  gap: .35rem;
+  padding: .2rem .55rem;
+  width: fit-content;
+}
+
+.account-owner-badge.is-unassigned {
+  background: color-mix(in srgb, #d99a24 12%, transparent);
+  border-color: color-mix(in srgb, #d99a24 40%, transparent);
+}
 
 @media (min-width: 48rem) {
   .sidebar { visibility: visible; transform: none; }
@@ -109,5 +189,6 @@ h2 { margin-bottom: 0; font-size: 1.1rem; }
   .page { padding: 3rem 2rem 5rem; }
   .navigation-backdrop { display: none; }
   .metrics-grid { grid-template-columns: repeat(4, minmax(0, 1fr)); }
+  .account-status-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
   .overview-grid { grid-template-columns: minmax(18rem, .8fr) minmax(22rem, 1.2fr); }
 }

apps/dashboard/vite.config.ts

@@ -12,6 +12,7 @@ export default defineConfig({
   server: {
     proxy: {
       '/api': 'http://localhost:3000',
+      '/media': 'http://localhost:3000',
     },
   },
 });

config.yaml

@@ -48,6 +48,7 @@ reddit:
   filterSellers: true  # Skip profiles that appear to be OnlyFans/content sellers
   prioritizeRecentPosts: true  # Prefer posts within recentWindowMinutes; older posts only as fallback
   recentWindowMinutes: 30
+  maxReadyCandidates: 25  # Pause screening when this many posts are ready to send
   # sellerKeywords: [...]  # Uncomment to override default keyword list
 
 openrouter:
@@ -67,19 +68,33 @@ openrouter:
     - "meta-llama/llama-4-maverick"       # ~$0.38/M
     - "deepseek/deepseek-chat-v3.1"       # ~$0.50/M
   imageAnalysisPrompt: |
-    You're analyzing images.
+    Analyze this adult image using only directly visible evidence.
 
-    Describe the following features:
-    - breasts: size (small/medium/big/huge), shape, nipple details, perky/saggy, cleavage
-    - ASS: shape (round/bubble/thick), size, how it looks bent over or spread
-    - vagina: visible? shaved/trimmed/bush, lips visible, spread or closed
-    - BODY: thick/slim/curvy/fit, belly, thighs, waist, tan lines
-    - POSE: bent over, spreading, on all fours, lying back, standing
-    - VIBE: shy/confident/slutty/teasing, eye contact, facial expression
-    - EXTRAS: tattoos, piercings, lingerie, toys, setting
+    Strict grounding rules:
+    - Never infer, predict, or imagine obscured anatomy, off-frame body parts,
+      hidden details, or how something would look in another pose.
+    - Do not infer overall body type from a close crop.
+    - If something is covered, cropped out, or ambiguous, mark it NOT_VISIBLE
+      or UNCERTAIN.
+    - Explicit language does not permit inference. Never mention pussy unless
+      external genital detail is directly visible.
 
-    Be graphic. Describe exactly what you see. No clinical terms.
-    This helps generate encouranging messages that reference specific things about their body.
+    Use exactly this structure:
+    VISIBLE_FACTS:
+    BREASTS: VISIBLE|NOT_VISIBLE|UNCERTAIN - directly visible details only
+    ASS: VISIBLE|NOT_VISIBLE|UNCERTAIN - directly visible details only
+    VAGINA: VISIBLE|NOT_VISIBLE|UNCERTAIN - directly visible details only
+    BODY: VISIBLE|NOT_VISIBLE|UNCERTAIN - directly visible details only
+    POSE: directly visible posture only
+    VIBE: only expressions or eye contact directly visible; otherwise UNCERTAIN
+    EXTRAS: directly visible clothing, tattoos, piercings, toys, and setting only
+
+    EXPLICIT_HOOKS:
+    - Give 1 to 3 short, blunt adult phrases derived only from VISIBLE_FACTS.
+    - Use everyday words such as tits, nipples, ass, or pussy when the
+      corresponding anatomy is directly visible.
+    - Never mention hidden breasts, nipples, ass, or pussy.
+    - Do not add new visual claims or predictions.
 
     Then rate her attractiveness on a 1-100 scale using these percentile anchors:
     - 30 = noticeably below average
@@ -94,7 +109,7 @@ openrouter:
     RATING:<number>
     Then on the next line: REASON:<one sentence explaining the score>
 
-    Be critical and honest. Act within guidelines.
+    Be critical and honest. Keep the complete response under 300 words.
   messageGenerationPrompt: |
     Based on this image analysis: {analysis}
     Post title: {title}
@@ -104,21 +119,23 @@ openrouter:
     Attractiveness rating (1-100 scale, 50 = average): {rating}
     If the rating is below 60, lean harder into making her feel sexy and desired — emphasize how hot her pic looks. If the rating is 75+, you can be more confidently flirty without overdoing the flattery.
 
-    Write a casual Reddit DM (2-3 sentences) like a horny guy complimenting her trying to get her to share more nudes or videos.
+    Write a casual Reddit DM (1-3 short sentences) like a horny guy reacting naturally to her post.
 
     MUST follow:
     - Start sentences with capital letters, use proper capitalisation
     - Use explicit terms: tits, ass, pussy, boobs (NOT breasts, buttocks, etc)
     - Reference something SPECIFIC from the analysis (her tits, ass, pussy, body, pose)
     - Be direct and confident, not flowery or poetic
-    - End with a hook that encourages them to share MORE (nudes/videos)
+    - Follow the selected STYLE exactly, especially its required opening and ending shape
+    - Make the message feel materially different from the recent messages supplied below
 
-    GOOD HOOKS (use these styles):
-    - "I'd love if you have any other pics to share?"
-    - "I bet they'd look great coated..."
-    - "Got any more pics?"
+    POSSIBLE HOOKS (only when the selected STYLE calls for one):
+    - A specific question about the post
+    - A playful prediction or challenge
+    - A conditional invitation to share something else
+    - A statement of desire with no question
 
-    BAD HOOKS (never use):
+    BAD HOOKS:
     - "How's your day?"
     - "What are you up to?"
     - Generic small talk questions
@@ -130,12 +147,11 @@ openrouter:
     - Use clinical terms like "breasts", "buttocks", "posterior", "physique"
     - Write long elaborate sentences
     - Use all lowercase
+    - Default to opening with "Damn", "Wow", "Holy shit", or the same reaction used recently
+    - Default to closing with "Got any more pics?", "More please", or a near-copy of a recent closing
     - Use em dashes (—) or en dashes (–). Use commas, full stops, or separate sentences instead. This is a dead giveaway for AI writing.
-
-    Examples of good messages:
-    - "Damn those tits are perfect. I'd love to see more if you're willing😏"
-    - "Holy shit that ass is incredible. Got any more pics?"
-    - "Those curves are insane, love how your tits look in that pose. More please?"
+    - Mention, mirror, or acknowledge the recipient's location
+    - Claim or imply you are in the same, nearby, or local area as the recipient, calculate distance, or suggest meeting in person
 
     Just write the message, nothing else.
 
@@ -150,15 +166,15 @@ openrouter:
 
     YOUR PERSONA:
     - You are male, based in the UK, pick a random age between 30 and 35 for this message
-    - Roughly half the time, mention (or imply) you're married/have a wife and are looking for something on the side; the other half, don't mention relationship status at all
-    - Don't force the married angle if their post wouldn't vibe with it, read the room
+    - Do not mention relationship status unless the selected STYLE explicitly requires it
     - Use British English spelling and phrasing (e.g. "mate", "knackered", "fancy", "cheeky") where it feels natural, not forced
+    - You may state that you are in the UK, but never mention or acknowledge the recipient's location
 
     Write a casual Reddit DM (1-2 sentences) opening a chat.
 
     MUST follow:
-    - Lead with your age/gender/location tag (e.g. "32M UK", "34M UK married") when it fits naturally
-    - Reference something SPECIFIC from their title/body (their mood, what they're into, vibe, age, location)
+    - Include your age/gender/location naturally, but place it where the selected STYLE requires
+    - Reference something SPECIFIC from their title/body (their mood, what they're into, vibe, or age), but never their location
     - Be confident and direct, flirty but not creepy
     - Use proper capitalisation, no AI/clinical language
     - End with a hook that invites a reply (ask them what they're into, offer something playful)
@@ -168,52 +184,79 @@ openrouter:
     - Open with "Hey there" / "How's your day"
     - Write more than 2 sentences
     - Be generic, "wanna chat?" alone is too weak
+    - Reuse the opening words, sentence pattern, or closing question from a recent message
     - Claim to be a different age/gender than the persona above
+    - Mention or acknowledge the recipient's location
+    - Say you are also/nearby/local to the recipient, calculate distance, or suggest meeting in person
     - Use em dashes (—) or en dashes (–) anywhere in the message. Use commas, full stops, or separate sentences instead. This is a dead giveaway for AI writing.
 
-    Examples of good openers:
-    - "32M UK, married and bored while the wife's out. Your post caught my eye, what are you into tonight?"
-    - "34M UK here, love that you're up late looking for trouble. Fancy telling me what gets you going?"
-    - "33M from the UK, your vibe is exactly my type. Tell me what you'd want a stranger to do to you."
-
     Just write the message, nothing else.
 
 strategies:
   explorationRate: 0.2  # 20% of the time try a random strategy instead of the best
-  minSamples: 5         # Min messages sent before trusting a strategy's response rate
+  minSamples: 20        # Mature outcomes required before exploiting a strategy
+  responseWindowHours: 12  # Age unanswered sends before including them in strategy performance
   variants:
-    - id: compliment_direct
+    - id: reaction_statement
       weight: 1
       promptOverride: |
-        STYLE: Focus on a direct, specific compliment about ONE body part from the analysis.
-        Keep it short and punchy. End with a simple "got more?" style hook.
-    - id: teasing
+        STYLE: REACTION STATEMENT. Open with a short physical reaction that is NOT "Damn", "Wow", or "Holy shit".
+        Mention one specific visible detail. Finish with a confident statement of desire, not a question and not a request for more.
+    - id: question_first
       weight: 1
       promptOverride: |
-        STYLE: Be more teasing and playful. Light humor, like you're flirting.
-        End with a flirty challenge or dare that makes her want to respond.
-    - id: detailed_appreciation
+        STYLE: QUESTION FIRST. The very first sentence must be a specific, answerable question about her post, pose, outfit, or title.
+        Follow with one concise explicit compliment. Do not ask whether she has more pics.
+    - id: title_callback
       weight: 1
       promptOverride: |
-        STYLE: Reference 2-3 specific things from the analysis to show you actually looked.
-        Be enthusiastic but not over the top. End with asking for more.
+        STYLE: TITLE CALLBACK. Open by naturally echoing or answering the post title, without quoting it verbatim.
+        Turn that callback into a playful compliment. End with an optional, conditional invitation rather than a generic request.
+    - id: teasing_challenge
+      weight: 1
+      promptOverride: |
+        STYLE: TEASING CHALLENGE. Open with a playful assumption, prediction, or mild challenge based on one visible detail.
+        Do not open with a compliment. End with a short dare or question that is specific to the challenge.
+    - id: concise_observation
+      weight: 1
+      promptOverride: |
+        STYLE: CONCISE OBSERVATION. Write exactly one sentence about the most distinctive visible detail in the analysis.
+        Do not ask a question, request more content, or begin with an interjection.
+    - id: imagined_scenario
+      weight: 1
+      promptOverride: |
+        STYLE: IMAGINED SCENARIO. Open with a brief, concrete scenario inspired by the pose or setting, then say what it makes you want.
+        End on the scenario itself. Do not use a generic compliment opener or ask "got more?".
 
 chatStrategies:
   explorationRate: 0.2
-  minSamples: 5
+  minSamples: 20
+  responseWindowHours: 12
   variants:
-    - id: chat_direct
+    - id: chat_identity_first
       weight: 1
       promptOverride: |
-        STYLE: Direct opener. Open with your own age/gender, reference theirs, and ask one specific question about what they're into. No em dashes.
-    - id: chat_playful
+        STYLE: IDENTITY FIRST. Open with your age/gender/location tag, then make one specific reference to their post and ask one answerable question.
+    - id: chat_question_first
       weight: 1
       promptOverride: |
-        STYLE: Playful and teasing. Light humour, mild flirty challenge, end with a hook that's hard to ignore. No em dashes.
-    - id: chat_mirror
+        STYLE: QUESTION FIRST. Open with a specific question prompted by their title or body. Put your age/gender/location naturally in the second sentence.
+    - id: chat_post_callback
       weight: 1
       promptOverride: |
-        STYLE: Mirror their energy. Match the vibe of their post (shy/horny/bored/dom/sub) and respond in kind. Be specific to what they wrote. No em dashes.
+        STYLE: POST CALLBACK. Open by responding to a distinctive phrase, request, or mood from their post. Add your age/gender/location later and close with a playful offer.
+    - id: chat_playful_assumption
+      weight: 1
+      promptOverride: |
+        STYLE: PLAYFUL ASSUMPTION. Start with a light, post-specific assumption about the kind of chat or trouble they want. Include your identity naturally and end with a mild challenge.
+    - id: chat_mirror_statement
+      weight: 1
+      promptOverride: |
+        STYLE: MIRROR STATEMENT. Match their energy and vocabulary, then make a direct statement about why you fit what they asked for. Include your identity, but do not end with a question.
+    - id: chat_married_disclosure
+      weight: 1
+      promptOverride: |
+        STYLE: MARRIED DISCLOSURE. Mention naturally in the first sentence that you are married or have a wife, then connect it to one specific detail from their post that caught your attention. Include your age, gender, and UK location naturally, and end with one answerable, post-specific hook. Do not claim an open marriage, your wife's permission or involvement, secrecy, unhappiness, or any other detail about the marriage.
 
 rateLimit:
   minDelayBetweenMessagesMs: 15000

docker-compose.yml

@@ -8,34 +8,15 @@ services:
     dns:
       - 1.1.1.1
       - 8.8.8.8
-    # Persist the database, browser session, and Matrix credentials in a
-    # named docker volume — a `./data` bind mount gets wiped on every Dokploy
-    # redeploy because the deploy dir is rebuilt, which loses the cookies and
-    # the captured Matrix token and triggers the slow re-login + token-sniff
-    # path on every restart.
     volumes:
       - reddit_bot_data:/app/data
-    # The dashboard goes through Traefik. noVNC must bypass the upstream
-    # proxy because it strips WebSocket Upgrade requests needed by websockify.
-    # Restrict host port 16080 with the host firewall; VNC_PASSWORD still
-    # authenticates the VNC session.
-    ports:
-      - "16080:6080"
     expose:
-      - "3000"   # Web dashboard
+      - "3000"
     environment:
       - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
-      # Required whenever the web dashboard is enabled; never commit its value.
       - WEB_DASHBOARD_TOKEN=${WEB_DASHBOARD_TOKEN}
-      - REDDIT_USERNAME=${REDDIT_USERNAME}
-      - REDDIT_PASSWORD=${REDDIT_PASSWORD}
-      # Chromium runs headed under Xvfb so a human can complete login over noVNC.
-      - BROWSER_HEADLESS=false
-      # Required to lock down the VNC endpoint.
-      - VNC_PASSWORD=${VNC_PASSWORD}
-      # Direct noVNC URL, e.g. http://<dokploy-host>:16080. It must not go
-      # through the WebSocket-stripping reverse proxy.
-      - NOVNC_PUBLIC_URL=${NOVNC_PUBLIC_URL}
+      - REDDIT_BOT_AGENT_READ_TOKEN=${REDDIT_BOT_AGENT_READ_TOKEN:-}
+      - REDDIT_BOT_AGENT_CONTROL_TOKEN=${REDDIT_BOT_AGENT_CONTROL_TOKEN:-}
 
 volumes:
   reddit_bot_data:

docker/entrypoint.sh

@@ -1,229 +0,0 @@
-#!/usr/bin/env bash
-# Start Xvfb + x11vnc + noVNC so a human can complete Reddit login
-# through the dashboard, then exec the Node bot which drives Chromium
-# on that virtual display.
-set -euo pipefail
-
-DISPLAY_NUM="${VNC_DISPLAY_NUM:-99}"
-VNC_PORT="${VNC_PORT:-5900}"
-NOVNC_PORT="${NOVNC_PORT:-6080}"
-GEOMETRY="${SCREEN_GEOMETRY:-1280x800x24}"
-BROWSER_SESSION_DIR="${BROWSER_SESSION_DIR:-/app/data/browser-session}"
-CHROME_CDP_PORT="${CHROME_CDP_PORT:-9222}"
-GOOGLE_CHROME_BIN="${GOOGLE_CHROME_BIN:-google-chrome}"
-NATIVE_LOGIN_EXIT_CODE=75
-export CHROME_CDP_URL="${CHROME_CDP_URL:-http://127.0.0.1:${CHROME_CDP_PORT}}"
-export DISPLAY=":${DISPLAY_NUM}"
-
-# noVNC ships under different paths depending on the distro; find the web root once.
-if [ -d /usr/share/novnc ]; then
-  NOVNC_WEB_DIR=/usr/share/novnc
-elif [ -d /usr/share/webapps/novnc ]; then
-  NOVNC_WEB_DIR=/usr/share/webapps/novnc
-else
-  echo "[entrypoint] could not locate noVNC web root" >&2
-  exit 1
-fi
-
-# Make / on the noVNC server land on vnc.html with autoconnect.
-if [ ! -e "${NOVNC_WEB_DIR}/index.html" ] && [ -e "${NOVNC_WEB_DIR}/vnc.html" ]; then
-  ln -sf vnc.html "${NOVNC_WEB_DIR}/index.html"
-fi
-
-# Clear any stale lock from a prior unclean exit — otherwise Xvfb refuses
-# to bind to the display and the bot starts up with no X server.
-rm -f "/tmp/.X${DISPLAY_NUM}-lock" "/tmp/.X11-unix/X${DISPLAY_NUM}" 2>/dev/null || true
-
-# Persistent profiles retain Chromium's singleton artifacts when a container
-# is replaced before Chromium exits cleanly. Remove only those locks; cookies,
-# local storage, and the rest of the authenticated profile remain untouched.
-rm -f \
-  "${BROWSER_SESSION_DIR}/SingletonLock" \
-  "${BROWSER_SESSION_DIR}/SingletonSocket" \
-  "${BROWSER_SESSION_DIR}/SingletonCookie" \
-  2>/dev/null || true
-
-echo "[entrypoint] starting Xvfb on ${DISPLAY} (${GEOMETRY})"
-Xvfb "${DISPLAY}" -screen 0 "${GEOMETRY}" -ac +extension RANDR &
-XVFB_PID=$!
-
-# Give Xvfb a moment to come up. Requires x11-utils (xdpyinfo).
-XVFB_READY=0
-for i in $(seq 1 50); do
-  if xdpyinfo -display "${DISPLAY}" >/dev/null 2>&1; then
-    echo "[entrypoint] Xvfb is ready after ${i} checks"
-    XVFB_READY=1
-    break
-  fi
-  sleep 0.2
-done
-
-if [ "${XVFB_READY}" != "1" ]; then
-  echo "[entrypoint] FATAL: Xvfb did not respond after 10s — refusing to launch bot without a display" >&2
-  exit 1
-fi
-
-# Minimal window manager so dialogs and tabs aren't stuck behind the root window.
-if command -v fluxbox >/dev/null 2>&1; then
-  fluxbox >/dev/null 2>&1 &
-fi
-
-VNC_ARGS=(-display "${DISPLAY}" -forever -shared -rfbport "${VNC_PORT}")
-if [ -n "${VNC_PASSWORD:-}" ]; then
-  mkdir -p /root/.vnc
-  x11vnc -storepasswd "${VNC_PASSWORD}" /root/.vnc/passwd >/dev/null
-  VNC_ARGS+=(-rfbauth /root/.vnc/passwd)
-  echo "[entrypoint] x11vnc starting with password auth"
-else
-  VNC_ARGS+=(-nopw)
-  echo "[entrypoint] WARNING: VNC_PASSWORD not set — VNC has no auth"
-fi
-
-x11vnc "${VNC_ARGS[@]}" >/var/log/x11vnc.log 2>&1 &
-X11VNC_PID=$!
-
-VNC_READY=0
-for i in $(seq 1 50); do
-  if ! kill -0 "${X11VNC_PID}" 2>/dev/null; then
-    echo "[entrypoint] FATAL: x11vnc exited before becoming ready" >&2
-    cat /var/log/x11vnc.log >&2
-    exit 1
-  fi
-  if (: </dev/tcp/127.0.0.1/${VNC_PORT}) 2>/dev/null; then
-    echo "[entrypoint] VNC server is ready after ${i} checks"
-    VNC_READY=1
-    break
-  fi
-  sleep 0.2
-done
-
-if [ "${VNC_READY}" != "1" ]; then
-  echo "[entrypoint] FATAL: x11vnc did not listen on port ${VNC_PORT} after 10s" >&2
-  cat /var/log/x11vnc.log >&2
-  exit 1
-fi
-
-echo "[entrypoint] starting noVNC (websockify) on :${NOVNC_PORT}"
-websockify --web "${NOVNC_WEB_DIR}" "${NOVNC_PORT}" "localhost:${VNC_PORT}" \
-  >/var/log/websockify.log 2>&1 &
-NOVNC_PID=$!
-
-CHROME_PID=""
-BOT_PID=""
-GATE_PID=""
-
-clear_chrome_locks() {
-  rm -f \
-    "${BROWSER_SESSION_DIR}/SingletonLock" \
-    "${BROWSER_SESSION_DIR}/SingletonSocket" \
-    "${BROWSER_SESSION_DIR}/SingletonCookie" \
-    2>/dev/null || true
-}
-
-stop_chrome() {
-  if [ -n "${CHROME_PID}" ]; then
-    kill "${CHROME_PID}" 2>/dev/null || true
-    wait "${CHROME_PID}" 2>/dev/null || true
-    CHROME_PID=""
-  fi
-  clear_chrome_locks
-}
-
-start_native_login_chrome() {
-  unset CHROME_CDP_URL
-  echo "[entrypoint] starting native Google Chrome login with DevTools disabled"
-  "${GOOGLE_CHROME_BIN}" \
-    --user-data-dir="${BROWSER_SESSION_DIR}" \
-    --no-first-run \
-    --no-default-browser-check \
-    --disable-dev-shm-usage \
-    --no-sandbox \
-    --start-maximized \
-    https://www.reddit.com/login/ \
-    >/var/log/google-chrome-native.log 2>&1 &
-  CHROME_PID=$!
-}
-
-start_controlled_chrome() {
-  export CHROME_CDP_URL="http://127.0.0.1:${CHROME_CDP_PORT}"
-  local chrome_ready=0
-  echo "[entrypoint] starting Google Chrome for authenticated bot control"
-  "${GOOGLE_CHROME_BIN}" \
-    --user-data-dir="${BROWSER_SESSION_DIR}" \
-    --remote-debugging-address=127.0.0.1 \
-    --remote-debugging-port="${CHROME_CDP_PORT}" \
-    --no-first-run \
-    --no-default-browser-check \
-    --disable-dev-shm-usage \
-    --no-sandbox \
-    --start-maximized \
-    about:blank \
-    >/var/log/google-chrome.log 2>&1 &
-  CHROME_PID=$!
-
-  for i in $(seq 1 100); do
-    if ! kill -0 "${CHROME_PID}" 2>/dev/null; then
-      break
-    fi
-    if curl -fsS "${CHROME_CDP_URL}/json/version" >/dev/null 2>&1; then
-      echo "[entrypoint] Google Chrome is ready after ${i} checks"
-      chrome_ready=1
-      break
-    fi
-    sleep 0.2
-  done
-
-  if [ "${chrome_ready}" != "1" ]; then
-    echo "[entrypoint] WARNING: Google Chrome failed to start; using Playwright fallback" >&2
-    stop_chrome
-    unset CHROME_CDP_URL
-  fi
-}
-
-cleanup() {
-  echo "[entrypoint] shutting down"
-  [ -n "${BOT_PID}" ] && kill "${BOT_PID}" 2>/dev/null || true
-  [ -n "${GATE_PID}" ] && kill "${GATE_PID}" 2>/dev/null || true
-  stop_chrome
-  kill "${NOVNC_PID}" "${X11VNC_PID}" "${XVFB_PID}" 2>/dev/null || true
-  wait || true
-}
-trap cleanup TERM INT EXIT
-
-if ! command -v "${GOOGLE_CHROME_BIN}" >/dev/null 2>&1; then
-  echo "[entrypoint] WARNING: Google Chrome is unavailable; using Playwright fallback" >&2
-  unset CHROME_CDP_URL
-else
-  start_controlled_chrome
-fi
-
-while true; do
-  echo "[entrypoint] launching bot"
-  set +e
-  node dist/index.js &
-  BOT_PID=$!
-  wait "${BOT_PID}"
-  BOT_EXIT=$?
-  BOT_PID=""
-  set -e
-
-  if [ "${BOT_EXIT}" -ne "${NATIVE_LOGIN_EXIT_CODE}" ]; then
-    exit "${BOT_EXIT}"
-  fi
-
-  echo "[entrypoint] bot requested native Reddit login mode"
-  stop_chrome
-  start_native_login_chrome
-  node dist/native-login-gate.js &
-  GATE_PID=$!
-  wait "${GATE_PID}"
-  GATE_EXIT=$?
-  GATE_PID=""
-  if [ "${GATE_EXIT}" -ne 0 ]; then
-    exit "${GATE_EXIT}"
-  fi
-
-  echo "[entrypoint] human completed login handoff; enabling authenticated control"
-  stop_chrome
-  start_controlled_chrome
-done

docs/README.md

@@ -0,0 +1,59 @@
+# RedditBot documentation
+
+This directory is the starting point for agents and maintainers. It explains the system at the level needed to make safe changes; source code, tests, database migrations, and the generated API reference remain authoritative.
+
+## Read this first
+
+RedditBot is a stateful, multi-account outreach and conversation application. It discovers eligible Reddit posts, prepares AI-generated openers, sends them through Reddit's Matrix chat service, follows replies under bounded policies, records outcomes, and exposes an authenticated operator dashboard and agent API.
+
+The most important operational fact is that local and production configuration may be live-capable. Installing dependencies, building, and testing are safe. Starting the backend, invoking control endpoints, importing sessions, sending messages, or deploying may affect real Reddit accounts and requires explicit authorization.
+
+## Documentation map
+
+| Document | Use it when |
+| --- | --- |
+| [Product goals and safety](product-and-safety.md) | You need the purpose, product boundaries, eligibility policy, or definition of success. |
+| [Architecture](architecture.md) | You need the system shape, process lifecycle, dependency boundaries, or repository map. |
+| [Runtime flows](data-flow.md) | You are changing discovery, screening, candidate delivery, replies, chat sync, media, or realtime updates. |
+| [Service map](services.md) | You need to find the module that owns a responsibility or identify extension seams. |
+| [Data model](database.md) | You are changing persistence, migrations, account scoping, idempotency, or analytics. |
+| [Configuration](configuration.md) | You are adding a setting, changing precedence, or diagnosing startup validation. |
+| [API](api.md) | You are using or changing HTTP/MCP operations. This file is generated. |
+| [Frontend](frontend.md) | You are changing the React dashboard, shared contracts, queries, routes, or SSE behavior. |
+| [Development and testing](development.md) | You are setting up locally, implementing a change, or choosing verification commands. |
+| [Deployment and operations](deployment.md) | You are diagnosing or performing Docker/Dokploy work, backups, recovery, or live verification. |
+
+## Fast orientation by task
+
+- Candidate selection or outreach: read product-and-safety, data-flow, services, and database.
+- Conversation automation: read product-and-safety, data-flow, and the conversation state/claim sections in database.
+- Dashboard/API work: read frontend, api, and architecture.
+- Authentication or account work: read architecture, configuration, database, and deployment.
+- Production incident: read deployment first, then the flow and service that own the failing state.
+- Schema or config change: read database/configuration and update both transport contracts and tests where applicable.
+
+## Sources of truth
+
+Use this order when facts conflict:
+
+1. Observable behavior and focused tests.
+2. Shared Zod transport contracts in `packages/api-contracts/src/`.
+3. Runtime Zod configuration in `src/config/index.ts` and migrations in `src/database/client.ts`.
+4. Owning implementation under `src/` or `apps/dashboard/src/`.
+5. Generated `docs/api.md` and live `/api/openapi.json`.
+6. Narrative documentation in this directory.
+
+Documentation should explain why boundaries exist and where behavior lives. Avoid copying entire schemas, hard-coded production identifiers, current counts, or secrets into prose.
+
+## Keeping documentation current
+
+Every code change must include the documentation changes needed to keep this map accurate. In particular:
+
+- Add or remove links here when documents change.
+- Update architecture and service ownership when dependencies move.
+- Update runtime flows when ordering, eligibility, retries, or idempotency changes.
+- Update configuration and data model documents with schema changes.
+- Run `npm run docs:api` after modifying `src/web/api-catalog.ts`.
+- Keep historical plans out of current-state documents; use Git history for retired designs.
+
+See the repository-level [`agents.md`](../agents.md) for the mandatory agent workflow.

docs/configuration.md

@@ -1,488 +1,104 @@
-# Configuration Guide
+# Configuration
 
-Complete reference for configuring RedditBot.
+## Precedence and lifecycle
 
----
+Configuration is validated by `ConfigSchema` in `src/config/index.ts`.
 
-## Table of Contents
+1. `DATABASE_PATH` identifies the database before application settings can be read.
+2. If `app_config` exists, the application-owned configuration is loaded from SQLite.
+3. Otherwise, `config.yaml` is loaded once and the validated application-owned subset is seeded into SQLite.
+4. Environment-owned secrets and database location are injected on every start.
 
-1. [Configuration Overview](#configuration-overview)
-2. [Configuration Files](#configuration-files)
-3. [Environment Variables](#environment-variables)
-4. [config.yaml Reference](#configyaml-reference)
-5. [Runtime Configuration](#runtime-configuration)
-6. [Configuration Validation](#configuration-validation)
-7. [Troubleshooting](#troubleshooting)
+After the initial seed, editing `config.yaml` does not replace an existing `app_config` row. Use the authenticated settings/API workflow or a deliberate database migration. The config route validates the complete result before saving.
 
----
+## Environment-owned values
 
-## Configuration Overview
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `OPENROUTER_API_KEY` | Yes | OpenRouter authentication. |
+| `WEB_DASHBOARD_TOKEN` | When web is enabled | Administrator UI/API credential. |
+| `DATABASE_PATH` | No | SQLite location; defaults to `./data/reddit-bot.db`. |
+| `REDDIT_BOT_AGENT_READ_TOKEN` | No | Read-only API/SSE bearer credential. |
+| `REDDIT_BOT_AGENT_CONTROL_TOKEN` | No | Read plus versioned control/job bearer credential. |
+| `REDDIT_BOT_API_URL` | MCP only | Base URL; defaults to `http://127.0.0.1:3000`. |
+| `REDDIT_BOT_AGENT_TOKEN` | MCP only | Preferred MCP bearer credential override. |
 
-RedditBot uses a layered configuration approach:
+Never document real values. `.env` is ignored and may contain production credentials; do not print or blindly source it.
 
-```
-┌──────────────────────────────────────────────────────────────┐
-│                    Priority Order (High → Low)                │
-├──────────────────────────────────────────────────────────────┤
-│ 1. Environment Variables                                     │
-│    (OPENROUTER_API_KEY, REDDIT_USERNAME, etc.)               │
-│                                                              │
-│ 2. config.yaml                                               │
-│    (Primary configuration file)                              │
-│                                                              │
-│ 3. Defaults                                                  │
-│    (Hardcoded defaults in code)                              │
-└──────────────────────────────────────────────────────────────┘
-```
+## Application sections
 
-Configuration is loaded at startup by `loadConfig()` in `src/config/index.ts`, which:
+### `reddit`
 
-1. Reads `config.yaml` from the project root
-2. Merges environment variable overrides
-3. Validates the entire configuration tree using Zod
-4. Returns a strongly-typed `Config` object
+- `subreddits`: at least one item with `name`, `enabled`, `type`, optional `weight`, `tone`, optional scripted opener, and conversation policy.
+- `pollIntervalMs`: legacy/scheduled polling cadence.
+- `userAgent`: Reddit JSON request identifier.
+- `targetGenders`: allowed parsed values.
+- `filterSellers`, `sellerKeywords`, `sellerDomains`: seller policy inputs. The defaults treat Telegram references, including `t.me` and `telegram.me` links, as seller signals alongside paid-content platforms and payment prompts.
+- `prioritizeRecentPosts`, `recentWindowMinutes`: recency/fallback behavior.
+- `maxReadyCandidates`: hard ceiling for the active candidate target; valid range 1–500. Runtime lowers the actual target to what authenticated running accounts can send within `recentWindowMinutes` under current rolling-hour and message-spacing limits.
 
----
+Subreddit `type` is `image` or `chat`. Conversation policy contains `mode`, `maxAutomatedTurns`, and `rapportTurnsBeforeMediaAsk`; hybrid rapport turns must be lower than the maximum.
 
-## Configuration Files
+### `openrouter`
 
-### config.yaml
+Contains image/chat primary and fallback models plus the analysis, message, and chat-opener prompt templates. The API key is environment-only. Model fallback and prompt changes affect cost, behavior, and experiment attribution and need focused tests plus operator-visible metadata.
 
-The primary configuration file, located at the project root:
+### `rateLimit`
 
-```
-RedditBot/
-├── config.yaml          # ← Main configuration
-├── package.json
-├── tsconfig.json
-└── src/
-```
+- `minDelayBetweenMessagesMs`;
+- `maxMessagesPerHour`;
+- `jitterMs`.
 
-### Data Directory
+These are per account. Reddit JSON request pacing is separately controlled by `RedditRequestCoordinator` and is process-global.
 
-Runtime data is stored in `data/` (created automatically):
+### `browser`
 
-```
-data/
-├── reddit-bot.db        # SQLite database
-├── browser/             # Browser session data (cookies, storage)
-├── media/               # Downloaded media files
-│   ├── index.json       # Media index (SHA-1 → filename)
-│   ├── abc123.jpg       # Media file 1
-│   └── def456.png       # Media file 2
-└── chats/               # Cached conversation JSON files
-    ├── chat_abc123.json
-    └── chat_def456.json
-```
+- `sessionDir`: root for persistent account browser profiles.
+- `dryRun`: when true, candidate preparation may run but remote sends must not.
 
----
+Treat changing `dryRun` from true to false as enabling a real side effect.
 
-## Environment Variables
+### `database`
 
-Environment variables override corresponding values in `config.yaml`.
+Contains `path`, but runtime ownership is `DATABASE_PATH`, not the persisted application config.
 
-| Variable | Required | Type | Description | Example |
-|---|---|---|---|---|
-| `OPENROUTER_API_KEY` | Yes | string | OpenRouter API key for AI services | `sk-or-v1-abc123...` |
-| `REDDIT_USERNAME` | Yes | string | Reddit username for authentication | `MyBotUser` |
-| `REDDIT_PASSWORD` | Yes | string | Reddit password for authentication | `secret123` |
-| `BROWSER_HEADLESS` | No | boolean | Run browser in headless mode | `true` or `false` |
+### `media`
 
-### Setting Environment Variables
+Controls periodic sync enablement and interval. Media work remains authentication-bound.
 
-**Option 1: `.env` file** (recommended for development)
+### `strategies` and `chatStrategies`
 
-Create a `.env` file in the project root:
+Each has exploration rate, minimum mature samples, response window, and weighted variants. Variants include an ID and prompt override. Image and chat sources use separate sections so their results are not compared as one experiment.
 
-```env
-OPENROUTER_API_KEY=sk-or-v1-abc123...
-REDDIT_USERNAME=MyBotUser
-REDDIT_PASSWORD=secret123
-BROWSER_HEADLESS=true
-```
-
-> **Note**: Add `.env` to `.gitignore` - never commit credentials.
-
-**Option 2: Shell export**
-
-```bash
-export OPENROUTER_API_KEY=sk-or-v1-abc123...
-export REDDIT_USERNAME=MyBotUser
-export REDDIT_PASSWORD=secret123
-```
-
-**Option 3: Docker**
-
-Pass via `docker-compose.yml` or Docker CLI:
-
-```yaml
-environment:
-  - OPENROUTER_API_KEY=sk-or-v1-abc123...
-  - REDDIT_USERNAME=MyBotUser
-  - REDDIT_PASSWORD=secret123
-```
-
----
-
-## config.yaml Reference
-
-Complete reference for every configuration option.
-
-### Reddit Settings
-
-```yaml
-reddit:
-  # Subreddits to monitor for new posts
-  subreddits:
-    - gonewild
-    - ratemyboobs
-    - HomemadeNsfw
-    - realgirls
-    - plussize_gonewild
-    # ... add or remove subreddits
-
-  # Minutes between polling cycles
-  pollInterval: 15
-
-  # Target gender for image analysis filtering
-  # Options: "F" (female), "M" (male)
-  targetGender: "F"
-
-  # Keywords used to detect sellers/spam profiles
-  # Posts from users matching these keywords are skipped
-  sellerKeywords:
-    - seller
-    - onlyfans
-    - link in bio
-    - check my profile
-    - promo
-    - discount
-    - affiliate
-```
-
-### OpenRouter AI Settings
-
-```yaml
-openrouter:
-  # OpenRouter API key (can also be set via OPENROUTER_API_KEY env var)
-  apiKey: "sk-or-v1-abc123..."
-
-  # Primary AI model for image analysis
-  # Models must be available on OpenRouter
-  model: "meta-llama/llama-3.2-90b-vision-preview"
-
-  # Fallback models tried if the primary model refuses or fails
-  fallbackModels:
-    - "google/gemini-2.0-flash-001"
-    - "meta-llama/llama-3.2-11b-vision-instruct"
-
-  # Quick detection model (cheaper/faster, used for gender pre-filter)
-  quickModel: "google/gemini-2.0-flash-lite-001"
-
-  # System prompt for image analysis
-  # The AI will describe the image and detect gender
-  systemPrompt: |
-    Analyze this image and provide:
-    1. Gender detected (F or M)
-    2. Detailed description of the image content
-    3. Notable features (hair color, clothing, setting, etc.)
-    
-    Return as JSON: {"gender": "F", "description": "...", "features": [...]}
-
-  # System prompt for message generation
-  # Used when crafting DMs to post authors
-  messagePrompt: |
-    Generate a natural, friendly DM for this Reddit post.
-    
-    Image analysis: {description}
-    Post title: {title}
-    Strategy: {strategy}
-    
-    Guidelines:
-    - Be complimentary but not creepy
-    - Reference something specific from the image
-    - Keep it under 2 sentences
-    - Sound like a genuine person, not a bot
-    - Do NOT ask for anything in return
-```
-
-### Rate Limiting
-
-```yaml
-rateLimit:
-  # Minimum delay between messages (milliseconds)
-  # Higher values reduce detection risk
-  minDelayMs: 30000
-
-  # Maximum messages per hour
-  # Bot will pause when this limit is reached
-  maxMessagesPerHour: 20
-
-  # Random jitter added to delay (milliseconds)
-  # Adds unpredictability to timing
-  jitterMs: 15000
-```
-
-**Timing example with defaults:**
-```
-Minimum delay: 30,000ms (30 seconds)
-Jitter: 0 to 15,000ms (0-15 seconds)
-Effective delay: 30-45 seconds between messages
-Max messages: 20 per hour
-```
-
-### Browser Settings
-
-```yaml
-browser:
-  # Run browser in headless mode (no UI)
-  # Set to false for debugging
-  headless: true
-
-  # Directory for persistent browser data
-  # Cookies and session storage are saved here
-  userDataDir: "./data/browser"
-```
-
-**Browser session persistence:**
-
-```
-data/browser/
-├── Default/
-│   ├── Cookies           # Reddit session cookies
-│   ├── Local Storage     # Local storage data
-│   └── Preferences       # Browser preferences
-├── Login Data            # Saved login info
-└── Preferences           # Browser state
-```
-
-> **Important**: Keep this directory intact. Deleting it requires re-login.
-
-### Database Settings
-
-```yaml
-database:
-  # Path to SQLite database file
-  path: "./data/reddit-bot.db"
-```
-
-The database is auto-created on first run. Migrations run automatically on startup.
-
-### Media Sync Settings
-
-```yaml
-mediaSync:
-  # Enable periodic media synchronization
-  enabled: true
-
-  # Interval between sync cycles (minutes)
-  intervalMinutes: 30
-```
-
-**Sync behavior:**
-- **Incremental sync** (automatic): Downloads media from top 10 conversations
-- **Full sync** (manual via dashboard): Downloads media from all conversations
-
-### Auto-Reply Settings
-
-```yaml
-autoReply:
-  # Enable automatic chat replies
-  enabled: true
-
-  # Auto-send replies (true) or mark as pending for approval (false)
-  autoSend: false
-
-  # Minutes between checking for new messages
-  checkInterval: 10
-```
-
-**Reply modes:**
-
-| autoSend | Behavior |
-|---|---|
-| `true` | Bot sends AI-generated replies automatically |
-| `false` | Bot suggests replies, user approves via dashboard |
-
-### Strategy Variants (A/B Testing)
-
-```yaml
-strategyVariants:
-  # Variant 1: Compliment-based
-  - name: "compliment"
-    prompt: |
-      Write a friendly compliment about the person's appearance.
-      Be genuine and specific. Keep it short and natural.
-    enabled: true
-
-  # Variant 2: Question-based
-  - name: "question"
-    prompt: |
-      Write a friendly message that includes a question.
-      Engage them in conversation naturally.
-    enabled: true
-
-  # Variant 3: Casual observation
-  - name: "observation"
-    prompt: |
-      Write a casual observation about the photo or setting.
-      Sound like you're commenting to a friend.
-    enabled: true
-```
-
-### Web Dashboard Settings
-
-```yaml
-web:
-  # Port for the web dashboard
-  port: 3000
-```
-
-### Global Settings
-
-```yaml
-# Global dry run mode
-# When true, all actions are logged but not actually performed
-dryRun: false
-
-# Number of successful message examples to include in prompts
-fewShotExamples: 3
-
-# Minimum responses needed before trusting strategy stats
-minStrategySamples: 10
-
-# Exploration rate for A/B testing (0.0 to 1.0)
-# 0.15 = 15% of messages use random variants (exploration)
-explorationRate: 0.15
-```
+### `web`
 
----
-
-## Runtime Configuration
-
-The following settings can be modified via the web dashboard without restarting the bot:
-
-| Setting | Endpoint | Type | Description |
-|---|---|---|---|
-| `rateLimit.minDelayMs` | `PUT /api/config` | number | Message delay |
-| `rateLimit.maxMessagesPerHour` | `PUT /api/config` | number | Hourly cap |
-| `rateLimit.jitterMs` | `PUT /api/config` | number | Jitter range |
-| `reddit.pollInterval` | `PUT /api/config` | number | Poll frequency |
-| `dryRun` | `PUT /api/config` | boolean | Dry run mode |
-
-### Updating Runtime Config
-
-Via dashboard:
-1. Open the settings modal
-2. Modify desired values
-3. Click "Save"
-
-Via API:
-```bash
-curl -X PUT http://localhost:3000/api/config \
-  -H "Content-Type: application/json" \
-  -d '{
-    "rateLimit": {
-      "minDelayMs": 45000,
-      "maxMessagesPerHour": 15,
-      "jitterMs": 20000
-    },
-    "dryRun": true
-  }'
-```
-
-> **Note**: Runtime changes are in-memory only. They are lost when the bot restarts. To make changes persistent, update `config.yaml`.
+Controls enabled state, port, optional tokens after environment injection, and dangerous debug endpoint enablement. Production secrets should never live in YAML.
 
----
-
-## Configuration Validation
+## Runtime-editable subset
 
-All configuration is validated using Zod at startup. Invalid configuration will cause the bot to exit with a descriptive error.
-
-### Validation Rules
-
-| Field | Validation |
-|---|---|
-| `reddit.subreddits` | Must be non-empty array of strings |
-| `reddit.pollInterval` | Must be positive integer |
-| `reddit.targetGender` | Must be "F" or "M" |
-| `openrouter.apiKey` | Must be non-empty string |
-| `openrouter.model` | Must be non-empty string |
-| `openrouter.fallbackModels` | Must be non-empty array |
-| `rateLimit.minDelayMs` | Must be positive integer |
-| `rateLimit.maxMessagesPerHour` | Must be positive integer |
-| `rateLimit.jitterMs` | Must be non-negative integer |
-| `browser.headless` | Must be boolean |
-| `browser.userDataDir` | Must be non-empty string |
-| `database.path` | Must be non-empty string |
-| `mediaSync.enabled` | Must be boolean |
-| `mediaSync.intervalMinutes` | Must be positive integer (if enabled) |
-| `autoReply.enabled` | Must be boolean |
-| `autoReply.autoSend` | Must be boolean |
-| `autoReply.checkInterval` | Must be positive integer (if enabled) |
-| `strategyVariants` | Must be array with name + prompt |
-| `web.port` | Must be integer 1-65535 |
-| `dryRun` | Must be boolean |
+The dashboard/API exposes a deliberate subset: rate limits, dry-run, recency and ready-funnel limits, subreddit definitions/conversation behavior, and selected advanced configuration. Shared transport schemas live in `packages/api-contracts/src/config.ts`; the backend source schema is still the final validator.
 
-### Common Validation Errors
+When adding a runtime-editable setting, update all of:
 
-**Error**: `Invalid config: openrouter.apiKey must be a string`
-**Fix**: Set `OPENROUTER_API_KEY` environment variable or add `apiKey` to `config.yaml`
+1. `ConfigSchema` and defaults.
+2. `config.yaml` seed/example when appropriate.
+3. `ConfigStore` persistence rules if ownership changes.
+4. Shared request/response schemas.
+5. The config route's merge/write/read-back behavior.
+6. Dashboard model/control.
+7. backend, contract, route, and dashboard tests.
+8. this document.
 
-**Error**: `Invalid config: reddit.subreddits must be a non-empty array`
-**Fix**: Add at least one subreddit to `reddit.subreddits` in `config.yaml`
+## Validation and change safety
 
-**Error**: `Invalid config: browser.userDataDir must be a string`
-**Fix**: Ensure `browser.userDataDir` is set in `config.yaml`
+- Use Zod for every external or persisted shape.
+- Reject unknown transport fields with strict contracts.
+- Validate relationships (not just types), such as the hybrid turn constraint.
+- Do not log the full config because it contains injected secrets in memory.
+- Configuration that affects running account objects may not be fully hot-reloaded; inspect the owning service before claiming immediate effect.
+- A production `PUT /api/config` should be followed by an authenticated GET read-back. Do not infer persistence from a 2xx alone.
+- A subreddit listing 404 is persisted as disabled so every account runtime stops polling it.
 
----
+## Local safe setup
 
-## Troubleshooting
-
-### Configuration Not Loading
-
-**Symptom**: Bot fails to start with validation errors.
-
-**Steps**:
-1. Verify `config.yaml` is in the project root
-2. Check YAML syntax (use a YAML linter)
-3. Verify environment variables are set correctly
-4. Check bot logs for specific validation errors
-
-### Credentials Not Working
-
-**Symptom**: Browser login fails.
-
-**Steps**:
-1. Verify `REDDIT_USERNAME` and `REDDIT_PASSWORD` are correct
-2. Check that the account is not locked or requires 2FA
-3. Try manual login via `npm run login`
-4. Ensure `BROWSER_HEADLESS=false` for debugging login issues
-
-### AI Not Working
-
-**Symptom**: Image analysis fails or returns errors.
-
-**Steps**:
-1. Verify `OPENROUTER_API_KEY` is valid
-2. Check API key has sufficient balance
-3. Verify `openrouter.model` is available on OpenRouter
-4. Check fallback models are set correctly
-5. Review logs for specific AI errors
-
-### Browser Session Expired
-
-**Symptom**: Bot stops with "Browser session expired" error.
-
-**Steps**:
-1. Delete `data/browser/` directory
-2. Run `npm run login` to re-authenticate
-3. Restart the bot
-
-### Port Already in Use
-
-**Symptom**: Dashboard fails to start with "Port already in use".
-
-**Steps**:
-1. Change `web.port` in `config.yaml`
-2. Or kill the process using the port: `lsof -i :3000`
+Install dependencies and run builds/tests without starting the application. If a local backend is explicitly needed, use a dry-run configuration and verify the database path/port before starting. Importing a real session or calling the start control is a separate live-capable action.

docs/data-flow.md

@@ -1,875 +1,123 @@
-# Data Flow Documentation
+# Runtime flows
 
-Complete documentation of data flows through the RedditBot system.
+## Candidate funnel
 
----
+The production multi-account path is three independent loops backed by `candidate_queue`.
 
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Post Processing Flow](#post-processing-flow)
-3. [Response Monitoring Flow](#response-monitoring-flow)
-4. [Chat Interaction Flow](#chat-interaction-flow)
-5. [Strategy Selection Flow](#strategy-selection-flow)
-6. [Media Sync Flow](#media-sync-flow)
-7. [Auto-Reply Flow](#auto-reply-flow)
-8. [Dashboard Data Flow](#dashboard-data-flow)
-9. [Error Recovery Flows](#error-recovery-flows)
-10. [Data Lifecycle](#data-lifecycle)
-
----
-
-## Overview
-
-RedditBot processes data through several interconnected pipelines:
-
-```
-┌─────────────┐     ┌──────────────┐     ┌─────────────┐
-│  Reddit API │────►│  Monitor     │────►│  Processor  │
-│  (Posts)    │     │  Service     │     │  Service    │
-└─────────────┘     └──────────────┘     └──────┬──────┘
-                                                │
-                     ┌──────────────┐           ▼
-                     │  Response    │     ┌──────────────┐
-                     │  Checker     │◄────│  OpenRouter  │
-                     └──────────────┘     │  (AI)        │
-                                          └──────────────┘
-                                                │
-                     ┌──────────────┐           ▼
-                     │  Chat        │     ┌──────────────┐
-                     │  Service     │◄────│  Message     │
-                     └──────────────┘     │  Sender      │
-                                          └──────────────┘
-                                                │
-                     ┌──────────────┐           ▼
-                     │  Media       │     ┌──────────────┐
-                     │  Service     │◄────│  SQLite DB   │
-                     └──────────────┘     └──────────────┘
-                                                │
-                     ┌──────────────┐           │
-                     │  Dashboard   │◄──────────┘
-                     │  (Express)   │
-                     └──────────────┘
+```mermaid
+stateDiagram-v2
+    [*] --> discovered: listing intake
+    discovered --> screening: leased by screening worker
+    screening --> ready: eligibility and preparation pass
+    screening --> retry_wait: transient failure
+    screening --> rejected: terminal eligibility or AI failure
+    ready --> sending: leased to available account
+    sending --> sent: Matrix confirms conversation
+    sending --> retry_wait: account cooldown or transient failure
+    sending --> rejected: terminal delivery result
+    retry_wait --> discovered: screening retry due
+    retry_wait --> ready: delivery retry due
+    discovered --> expired: outside configured recent window
+    ready --> expired: outside configured recent window
 ```
 
----
+### 1. Discovery
 
-## Post Processing Flow
+The discovery loop rotates through enabled subreddits and authenticated runtimes. A runtime fetches Reddit `/new` data using the process-shared `RedditRequestCoordinator`. Intake deduplicates post IDs and authors, excludes processed/contacted history, stores the full post snapshot, source type, weight, and timestamps, and logs exact intake counts.
 
-The primary data flow for discovering, analyzing, and messaging about new posts.
+The queue grows to a demand-based target rather than a fixed backlog. The target is the smaller of configured `reddit.maxReadyCandidates` and the work that authenticated running accounts can still send within the recent-post window, accounting for rolling hourly capacity and minimum message spacing. Intake admits only the current deficit, newest Reddit posts first, pauses at zero outbound capacity, and reports fetched posts left unevaluated because the funnel is full. Reddit request pacing, not a tight application poll, remains the primary request limiter.
 
-### Stage 1: Discovery
+### 2. Screening and preparation
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     MonitorService                              │
-│                                                                 │
-│  1. Shuffle subreddit order                                    │
-│  2. For each subreddit:                                        │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  RedditApi.fetchPosts(subreddit)                    │    │
-│     │                                                     │    │
-│     │  HTTP: GET /r/{subreddit}/new.json?limit=100        │    │
-│     │                                                     │    │
-│     │  Response: {                                        │    │
-│     │    data: {                                          │    │
-│     │      children: [                                   │    │
-│     │        {                                            │    │
-│     │          data: {                                   │    │
-│     │            id: "abc123",                           │    │
-│     │            subreddit: "gonewild",                  │    │
-│     │            author: "user123",                      │    │
-│     │            title: "Summer vibes",                  │    │
-│     │            url: "https://...",                     │    │
-│     │            preview: { reddits: [...] },            │    │
-│     │            thumbnail: "https://...",               │    │
-│     │            post_hint: "image",                     │    │
-│     │            over_18: true                           │    │
-│     │          }                                          │    │
-│     │        }                                           │    │
-│     │      ]                                             │    │
-│     │    }                                               │    │
-│     │  }                                                 │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  3. Filter posts:                                              │
-│     ├─► post_hint === "image"                                  │
-│     ├─► author exists and is not deleted                       │
-│     ├─► image_url can be extracted                             │
-│     └─► Author not in seller/spam list                         │
-│                                                                 │
-│  4. Cross-reference with DB:                                   │
-│     ├─► PostsRepository.getById(postId) → skip if exists       │
-│     └─► MessagesRepository.getByAuthor(author) → skip if sent  │
-│                                                                 │
-│  5. Return newest valid post                                   │
-└─────────────────────────────────────────────────────────────────┘
+A screening worker leases one discovered candidate. `MonitorService.screenCandidate()` applies cheap rules before expensive/networked rules:
+
+1. Global processed-post and recipient-history checks.
+2. For chat sources, self-declared gender and adult age parsing.
+3. Seller evidence from the post, profile/about, and recent activity.
+4. Source-specific preparation in `ProcessorService`.
+
+For image posts, preparation downloads and validates the image, detects target gender, performs model analysis, selects an image strategy, and generates an opener. For chat posts, it selects a chat strategy and generates from the post text. Both paths apply outbound safety checks and return either a prepared immutable result or an explicit skip reason.
+
+Terminal results become rejected candidates. Rate limits and transient failures become retryable candidates. Prepared candidates become ready; the persisted snapshot means a different account can deliver without repeating AI work.
+
+### 3. Dispatch
+
+An account is eligible for new outreach only when its runtime is running, both identities verify, it has no actionable reply backlog, there is no invitation cooldown, and its rate limiter permits a send. Available accounts are ordered by their current hourly send count.
+
+Matrix cooldowns retain the operation that triggered them. A room-creation or invitation limit pauses new outreach but does not suppress replies in existing rooms; a limit returned while sending into an existing room pauses those sends as well.
+
+Screening, retry promotion, dispatch, and the operator's active-queue view are ordered by the Reddit post creation time, newest first; source priority is only a tie-breaker. The dispatch worker leases the newest ready candidate for an account, materializes the processed post in that account's repository, applies the account rate limiter, checks dry-run, and atomically claims the recipient globally. `ChatService.startConversationDetailed()` returns one of:
+
+- `sent`: persist the message and outcome metadata, commit recipient history, update activity, and mark the candidate sent;
+- `terminal`: release the recipient reservation and reject the candidate;
+- `retryable`: release/defer so another healthy account can claim it soon.
+
+Only Matrix confirmation makes a send successful. A healthy HTTP process, room identifier lookup, or attempted request does not.
+
+## Reddit request and cooldown flow
+
+Every runtime shares one `RedditRequestCoordinator`, because Reddit can enforce limits by origin as well as account. JSON requests are serialized with a minimum interval; failed requests consume spacing too. A 429 extends the global cooldown using the server delay plus a buffer. Broad 403 behavior can also result in coordinated backoff. A listing 404 is treated as terminal for that subreddit and persisted as `enabled=false`.
+
+Do not add local retries around this layer without preserving the shared schedule. Per-account bursts defeat the coordinator.
+
+## Reply-first conversation automation
+
+Each account runtime refreshes recent chats and processes actionable inbound conversations oldest-first before it can accept new outreach. After the initial conservative startup scan, the persisted latest Matrix message event plus the worker's prior-scan watermark is authoritative: a newly observed inbound event newer than the confirmed opener remains actionable even if Matrix's presentation-only unread notification count has already returned to zero. On startup, read-marked rooms without a pending reply claim are not revived. Durable event claims, conversation policy state, and a later outbound event prevent duplicate replies.
+
+Outgoing Matrix events are attributed against the recorded opener, durable automated-reply fingerprints, and confirmed exchange-library event records. If synchronization observes an unmatched outgoing message, the conversation becomes operator-owned before another reply can be generated. An unmatched outgoing message also supersedes, rather than confirms, a pending automated claim; only the claimed reply text can reconcile that claim as sent.
+
+```mermaid
+flowchart TD
+    IN["Unread inbound Matrix event"] --> VERIFIED{"Confirmed after a recorded opener?"}
+    VERIFIED -- no --> IGNORE["Ignore as unverified"]
+    VERIFIED -- yes --> CLAIM{"Durable event claim exists?"}
+    CLAIM -- sent --> IGNORE
+    CLAIM -- pending --> RECON["Reconcile against Matrix history"]
+    CLAIM -- no --> STATE["Load or snapshot conversation policy"]
+    STATE --> STOP{"Manual, seller, image, boundary, unsafe, or turn limit?"}
+    STOP -- yes --> HANDOFF["Persist terminal/human-required outcome"]
+    STOP -- no --> GEN["Generate policy-specific reply"]
+    GEN --> SAFE{"Outbound checks pass?"}
+    SAFE -- no --> HANDOFF
+    SAFE -- yes --> PERSIST["Persist intended reply claim"]
+    PERSIST --> WAIT["Wait for the account rate limiter"]
+    WAIT --> RECHECK{"Refresh Matrix; claimed event still latest and safe?"}
+    RECHECK -- no --> SUPERSEDE["Mark claim superseded; persist boundary/handoff if present"]
+    RECHECK -- yes --> SNAPSHOT["Persist intended conversation state"]
+    SNAPSHOT --> SEND["Matrix send"]
+    SEND --> MARK["Mark claim sent and record latency"]
 ```
 
-### Stage 2: Image Processing
+The inbound event key, intended reply, claim status, and conversation state make retries idempotent. Immediately after any limiter wait, automation refreshes Matrix and revalidates the latest inbound event, boundaries, images, seller evidence, policy status, and the one-media-request limit. Newer state makes the old claim terminally `superseded`; it is never sent. If the process dies after Matrix accepted a reply, reconciliation finds the outbound event and marks the old claim sent instead of sending it again.
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    ProcessorService                             │
-│                                                                 │
-│  1. Download Image                                             │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  ImageService.downloadImage(url)                    │    │
-│     │                                                     │    │
-│     │  HTTP: GET {image_url}                              │    │
-│     │                                                     │    │
-│     │  Response: Binary image data                        │    │
-│     │                                                     │    │
-│     │  Validation:                                        │    │
-│     │    ├─► MIME type: image/jpeg | png | webp           │    │
-│     │    ├─► File size: < 10MB                            │    │
-│     │    └─► Not empty/broken                             │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  2. Convert to base64                                          │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  Buffer.toString('base64')                          │    │
-│     │                                                     │    │
-│     │  Result: "data:image/jpeg;base64,/9j/4AAQSkZJR..." │    │
-│     └─────────────────────────────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────────┘
-```
+Legacy conversations may make at most one optional autonomous media request, including a request already present in the opener. The hybrid policy retains its single rapport-gated media ask. Deterministic, sequence-aware refusal checks run before generation and again at send time; generated media asks must pass the same non-explicit, non-coercive validator.
 
-### Stage 3: Gender Detection (Pre-Filter)
+## Chat and media synchronization
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                   OpenRouterService                             │
-│                                                                 │
-│  1. detectGenderOnly(imageBase64)                              │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  HTTP: POST https://openrouter.ai/api/v1/chat/      │    │
-│     │        completions                                  │    │
-│     │                                                     │    │
-│     │  Request: {                                         │    │
-│     │    model: "fast-model",                             │    │
-│     │    messages: [                                     │    │
-│     │      {                                               │    │
-│     │        role: "user",                                │    │
-│     │        content: [                                  │    │
-│     │          { type: "text", text: "Is this F or M?" }, │    │
-│     │          { type: "image_url", image_url: {...} }    │    │
-│     │        ]                                            │    │
-│     │      }                                              │    │
-│     │    ]                                                │    │
-│     │  }                                                  │    │
-│     │                                                     │    │
-│     │  Response: {                                        │    │
-│     │    choices: [{ message: { content: "F" } }]         │    │
-│     │  }                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  3. Compare with config.targetGender                           │
-│     ├─► Match: continue to full analysis                       │
-│     └─► No match: SKIP post (log: "Gender mismatch, skipping") │
-└─────────────────────────────────────────────────────────────────┘
-```
+`ChatService` communicates with Reddit's Matrix homeserver, maintains an account-scoped SQLite-backed cache, resolves `t2_` identities to Reddit usernames, and emits sync progress/new-reply callbacks. Startup chooses full or delta sync from persisted cursor state. Operators can explicitly run tracked sync jobs through the versioned API.
 
-### Stage 4: Strategy Selection
+`MediaService` resolves Matrix media, downloads it into the persistent data directory, and writes an account-scoped media index. `MediaSyncService` schedules incremental work only while the account is authenticated. The media listing reads persisted indexes for every stored account, including accounts whose runtimes are stopped or require login, and exposes received items only: records attributed to the owning Reddit/Matrix account are excluded, including historical self-sender forms. Private media is served behind the same authorization boundary as the dashboard and APIs.
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                  StrategySelector                               │
-│                                                                 │
-│  1. Get strategy statistics from DB                            │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  MessagesRepository.getStrategyStats()              │    │
-│     │                                                     │    │
-│     │  Result: {                                          │    │
-│     │    variant_a: { sent: 50, responded: 15, rate: 0.30 },│
-│     │    variant_b: { sent: 30, responded: 12, rate: 0.40 },│
-│     │    variant_c: { sent: 5,  responded: 1,  rate: 0.20 } │
-│     │  }                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  2. Apply exploration/exploit algorithm                        │
-│     ├─► Random roll < explorationRate → pick random variant    │
-│     └─► Otherwise → pick highest response rate (min samples)   │
-│                                                                 │
-│  3. Return selected variant name                               │
-│     Example: "variant_b"                                       │
-└─────────────────────────────────────────────────────────────────┘
-```
+The process-global exchange library is separate. Dashboard uploads are decoded and re-encoded with `sharp`, which validates the actual JPEG/PNG/WebP contents, applies orientation, and removes EXIF/location/camera metadata. OpenRouter then assigns overlapping anatomy tags plus SFW/NSFW classification. Failed or low-confidence classifications remain disabled until the operator corrects them.
 
-### Stage 5: Full AI Analysis
+For each latest inbound text event, `MediaLibraryExchangeService` detects direct or indirect image requests before normal reply generation. Exact requests require the matching tag. Generic requests use the conversation's completed library-send count to broaden the eligible safety tier and randomly choose an unused asset. A unique durable reservation on account + conversation + asset prevents reuse, while account + conversation + inbound event makes restart handling idempotent.
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                   OpenRouterService                             │
-│                                                                 │
-│  1. analyzeImage(imageBase64)                                  │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  HTTP: POST https://openrouter.ai/api/v1/chat/      │    │
-│     │        completions                                  │    │
-│     │                                                     │    │
-│     │  Request: {                                         │    │
-│     │    model: "primary-model",                          │    │
-│     │    messages: [                                     │    │
-│     │      {                                               │    │
-│     │        role: "system",                               │    │
-│     │        content: config.openrouter.systemPrompt       │    │
-│     │      },                                              │    │
-│     │      {                                               │    │
-│     │        role: "user",                                │    │
-│     │        content: [                                  │    │
-│     │          { type: "text", text: "Describe this image" },│
-│     │          { type: "image_url", image_url: {...} }    │    │
-│     │        ]                                            │    │
-│     │      }                                              │    │
-│     │    ]                                                │    │
-│     │  }                                                  │    │
-│     │                                                     │    │
-│     │  Response: {                                        │    │
-│     │    choices: [{                                      │    │
-│     │      message: {                                     │    │
-│     │        content: '{"gender":"F","description":"..."}' │   │
-│     │      }                                              │    │
-│     │    }]                                               │    │
-│     │  }                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  2. Check for refusal                                          │
-│     ├─► If refused → try fallback models                       │
-│     └─► If all failed → mark post with error, skip            │
-│                                                                 │
-│  3. Parse and return ImageAnalysis                             │
-│     { gender: "F", description: "Young woman, blonde hair..." }│
-└─────────────────────────────────────────────────────────────────┘
-```
+After the normal reply limiter waits, automation refreshes Matrix and rechecks that the same inbound request is still latest and that no image, boundary, seller signal, or other terminal state has appeared. It then uploads the private file to Matrix, sends an `m.image` event with a stable transaction ID, and only after confirmation sends the optional reciprocal text. If the image is confirmed but the text is not, the asset remains consumed and the conversation is handed to the operator rather than risking a duplicate.
 
-### Stage 6: Message Generation
+The conversation UI also supports an explicitly confirmed manual choice from this same eligible set. Its read endpoint reports request-matched options without exposing filesystem paths. The send endpoint refreshes the conversation inside the owning account's rate limiter, rechecks the latest inbound request and safety boundaries, reserves the selected asset in the same durable ledger, and uses the same Matrix image-plus-reciprocal delivery path. A successful manual share marks automation as user-overridden.
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                   OpenRouterService                             │
-│                                                                 │
-│  1. Retrieve few-shot examples                                 │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  SuccessfulMessagesRepository.getExamples(          │    │
-│     │    subreddit, count: 3                               │    │
-│     │  )                                                  │    │
-│     │                                                     │    │
-│     │  Result: [                                          │    │
-│     │    {                                                │    │
-│     │      original_message: "Hey, you look amazing...",   │    │
-│     │      response_snippet: "Thank you so much!",        │    │
-│     │      subreddit: "gonewild"                          │    │
-│     │    },                                               │    │
-│     │    // ... more examples                             │    │
-│     │  ]                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  2. Generate message                                           │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  HTTP: POST https://openrouter.ai/api/v1/chat/      │    │
-│     │        completions                                  │    │
-│     │                                                     │    │
-│     │  Request: {                                         │    │
-│     │    model: "primary-model",                          │    │
-│     │    messages: [                                     │    │
-│     │      { role: "system", content: messagePrompt },     │    │
-│     │      { role: "user", content: [                     │    │
-│     │          `Image: ${imageAnalysis.description}`,      │    │
-│     │          `Post title: ${postTitle}`,                 │    │
-│     │          `Strategy: ${selectedVariant}`,             │    │
-│     │          `Examples: ${JSON.stringify(examples)}`     │    │
-│     │        ]                                            │    │
-│     │      }                                              │    │
-│     │    ]                                                │    │
-│     │  }                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  3. Return generated message                                   │
-│     "Hey, I came across your post and..."                      │
-└─────────────────────────────────────────────────────────────────┘
-```
+Conversation performance is derived from the complete attributed inbound transcript. Engagement cannot become a prompt-learning example while automation is active, and a later decline, boundary, or upsell removes an earlier example before future prompts load it.
 
-### Stage 7: DM Sending
+## Dashboard data and events
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    MessagePage                                  │
-│                                                                 │
-│  1. Navigate to compose page                                   │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  page.goto("https://www.reddit.com/compose?to=      │    │
-│     │        user123")                                     │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  2. Fill recipient field                                       │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  page.evaluate(() => {                               │    │
-│     │    const input = document.querySelector(             │    │
-│     │      'faceplate-autocomplete input'                  │    │
-│     │    );                                                │    │
-│     │    input.value = "user123";                          │    │
-│     │    input.dispatchEvent(new Event('input',            │    │
-│     │      { bubbles: true }));                            │    │
-│     │  });                                                 │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  3. Fill subject field ("Stunning")                            │
-│  4. Fill body field (generated message)                        │
-│  5. Click send button                                          │
-│  6. Verify success (check for confirmation)                    │
-│                                                                 │
-│  Result: true (sent) or false (failed)                         │
-└─────────────────────────────────────────────────────────────────┘
-```
+Routes assemble snapshots from repositories and injected services. `LogBroadcaster`/the realtime event hub publishes typed events for bot state, sends, failures, conversations, replies, sync, sessions, rate limits, and logs. The React client validates incoming events, invalidates matching TanStack Query keys, and reconnects with replay support. Cached screens remain visible but stale during a disconnect.
 
-### Stage 8: Database Recording
+## Failure classification
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      Database                                   │
-│                                                                 │
-│  1. INSERT INTO processed_posts                                │
-│     VALUES (                                                   │
-│       'abc123',    -- post_id                                  │
-│       'gonewild',  -- subreddit                                │
-│       'user123',   -- author                                   │
-│       'Summer vibes',           -- title                       │
-│       'https://...',           -- image_url                    │
-│       '{"gender":"F",...}',   -- image_analysis                │
-│       'Hey, I came across...',  -- generated_message           │
-│       1716234567,              -- processed_at                 │
-│       1,                     -- message_sent                   │
-│       NULL                    -- error                         │
-│     );                                                         │
-│                                                                 │
-│  2. INSERT INTO sent_messages                                  │
-│     VALUES (                                                   │
-│       NULL,          -- id (auto)                              │
-│       'abc123',    -- post_id                                  │
-│       'user123',   -- recipient                                │
-│       'Stunning',  -- subject                                  │
-│       'Hey, I came across...',  -- message                     │
-│       1716234567,  -- sent_at                                  │
-│       'variant_b', -- strategy_id                              │
-│       0,         - - got_response                              │
-│       NULL         -- response_checked_at                      │
-│     );                                                         │
-└─────────────────────────────────────────────────────────────────┘
-```
+Use three categories consistently:
 
----
+- Terminal: the candidate/action is unsuitable or impossible; persist a reason and do not retry automatically.
+- Retryable: service limits, temporary auth/network errors, or account cooldown; preserve the candidate and retry time.
+- Human-required: policy or safety cannot continue autonomously; stop automation and surface an attention item.
 
-## Response Monitoring Flow
-
-How the bot detects and records user replies to sent DMs.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                  ResponseCheckerService                         │
-│                                                                 │
-│  1. Navigate to inbox                                          │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  page.goto("https://www.reddit.com/message/inbox")  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  2. Parse inbox items                                          │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  Extract from page:                                 │    │
-│     │  [                                                    │    │
-│     │    {                                                 │    │
-│     │      from: "user456",                                │    │
-│     │      subject: "Re: Stunning",                        │    │
-│     │      snippet: "Thank you so much! 😊",               │    │
-│     │      timestamp: 1716234000,                          │    │
-│     │      link: "/message/xyz789"                         │    │
-│     │    },                                               │    │
-│     │    // ... more messages                              │    │
-│     │  ]                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  3. Match responses to sent messages                           │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  For each inbox item:                               │    │
-│     │    ├─► MessagesRepository.getByRecipient(from)       │    │
-│     │    ├─► Find unmatched message within time window     │    │
-│     │    ├─► Update: got_response = 1                     │    │
-│     │    ├─► Update: response_checked_at = now            │    │
-│     │    └─► Store in successful_messages                 │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  4. Update strategy statistics                                 │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  MessagesRepository.updateStrategyStats(            │    │
-│     │    strategy_id, got_response: true                  │    │
-│     │  )                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  5. Log results                                                │
-│     └─► "Found 3 responses, updated 2 strategies"              │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Chat Interaction Flow
-
-How the bot interacts with Reddit chat conversations.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     ChatService                                 │
-│                                                                 │
-│  ──── PHASE 1: FETCH CHATS ──────────────────────────────────  │
-│                                                                 │
-│  1. Navigate to chat page                                      │
-│     page.goto("https://chat.reddit.com")                       │
-│                                                                 │
-│  2. Traverse shadow DOM for conversations                      │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  page.evaluate(() => {                              │    │
-│     │    // JS injection to pierce shadow DOM            │    │
-│     │    const roots = document.querySelectorAll(        │    │
-│     │      'faceplate-chat-list'                          │    │
-│     │    );                                               │    │
-│     │    const chats = [];                                │    │
-│     │    roots.forEach(root => {                          │    │
-│     │      const shadow = root.shadowRoot;                │    │
-│     │      const items = shadow.querySelectorAll(         │    │
-│     │        '.chat-item'                                 │    │
-│     │      );                                             │    │
-│     │      items.forEach(item => {                        │    │
-│     │        chats.push({                                 │    │
-│     │          id: item.dataset.chatId,                   │    │
-│     │          participant: item.querySelector(           │    │
-│     │            '.username'                              │    │
-│     │          ).textContent,                             │    │
-│     │          lastMessage: item.querySelector(           │    │
-│     │            '.message'                               │    │
-│     │          ).textContent,                             │    │
-│     │          timestamp: item.dataset.timestamp          │    │
-│     │        });                                          │    │
-│     │      });                                            │    │
-│     │    });                                              │    │
-│     │    return chats;                                    │    │
-│     │  });                                                │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  3. Cache results                                              │
-│     └─► Save to memory + disk JSON                             │
-│                                                                 │
-│  ──── PHASE 2: LOAD CONVERSATION ────────────────────────────  │
-│                                                                 │
-│  1. Check cache                                                │
-│     ├─► If cached and fresh: return from memory                │
-│     └─► If not: fetch from disk or Reddit                      │
-│                                                                 │
-│  2. Fetch full history (pagination)                            │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  For each page of messages:                         │    │
-│     │    ├─► Navigate to chat view                        │    │
-│     │    ├─► Extract messages from shadow DOM            │    │
-│     │    ├─► Scroll to load more (infinite scroll)       │    │
-│     │    └─► Repeat until all loaded                     │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  3. Return conversation object                                 │
-│     {                                                           │
-│       chatId: "abc123",                                        │
-│       participants: ["user456", "bot"],                        │
-│       messages: [                                              │
-│         { author: "user456", text: "Hey!", timestamp: ... },   │
-│         { author: "bot", text: "Hi there!", timestamp: ... },  │
-│         // ... more messages                                   │
-│       ],                                                       │
-│       lastUpdated: 1716234567                                  │
-│     }                                                           │
-│                                                                 │
-│  ──── PHASE 3: SEND MESSAGE ─────────────────────────────────  │
-│                                                                 │
-│  1. Navigate to chat view                                      │
-│  2. Fill message input (shadow DOM)                            │
-│  3. Apply typing delay (human-like)                            │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  const typingDelay = random(500, 2000);             │    │
-│     │  await page.waitForTimeout(typingDelay);            │    │
-│     │                                                     │    │
-│     │  // Simulate typing character by character           │    │
-│     │  for (const char of message) {                      │    │
-│     │    input.value += char;                              │    │
-│     │    await page.waitForTimeout(random(30, 100));      │    │
-│     │  }                                                  │    │
-│     └─────────────────────────────────────────────────────┘    │
-│  4. Submit message                                             │
-│  5. Verify delivery (check for sent indicator)                 │
-│                                                                 │
-│  Result: true (delivered) or false (failed)                    │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Strategy Selection Flow
-
-How A/B test variants are selected and updated.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                  StrategySelector                               │
-│                                                                 │
-│  SELECT STRATEGY                                               │
-│  ────────────────────────────────────────────────────────────  │
-│                                                                 │
-│  Input: subreddit, author                                      │
-│                                                                 │
-│  1. Get stats from DB                                          │
-│     ┌─────────────────────────────────────────────────────┐    │
-│     │  SELECT strategy_id,                              │    │
-│     │         COUNT(*) as sent,                         │    │
-│     │         SUM(got_response) as responded             │    │
-│     │  FROM sent_messages                                │    │
-│     │  GROUP BY strategy_id                              │    │
-│     └─────────────────────────────────────────────────────┘    │
-│                                                                 │
-│  2. Calculate response rates                                   │
-│     variant_a: 15/50 = 30%                                     │
-│     variant_b: 12/30 = 40%                                     │
-│     variant_c: 1/5 = 20%                                       │
-│                                                                 │
-│  3. Filter by minimum samples                                  │
-│     minSamples = 10                                            │
-│     variant_c excluded (only 5 sends)                          │
-│                                                                 │
-│  4. Explore vs Exploit                                         │
-│     random() < explorationRate (e.g., 0.15)?                   │
-│     ├─► Yes: Random pick from enabled variants                 │
-│     └─► No: Pick highest rate (variant_b at 40%)              │
-│                                                                 │
-│  Output: selected variant name                                 │
-│                                                                 │
-│  ──── UPDATE STATS ──────────────────────────────────────────  │
-│                                                                 │
-│  Input: strategy_id, got_response (boolean)                    │
-│                                                                 │
-│  1. Record in sent_messages                                    │
-│     UPDATE sent_messages                                       │
-│     SET got_response = 1,                                      │
-│         response_checked_at = now                               │
-│     WHERE id = ?                                               │
-│                                                                 │
-│  2. If successful: store in successful_messages                │
-│     INSERT INTO successful_messages                            │
-│     VALUES (original_message, image_analysis, post_title,      │
-│              response_snippet, subreddit, now)                 │
-│                                                                 │
-│  3. Update strategy statistics                                 │
-│     (reflected in next selectStrategy call)                    │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Media Sync Flow
-
-How media files are downloaded and synchronized from chat conversations.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                  MediaSyncService                               │
-│                                                                 │
-│  ──── TRIGGER ────────────────────────────────────────────────  │
-│                                                                 │
-│  Scheduled: every N minutes (config.mediaSync.intervalMinutes) │
-│ Manual: POST /api/media/sync (incremental)                     │
-│ Manual: POST /api/media/sync/full (full)                       │
-│                                                                 │
-│  ──── INCREMENTAL SYNC ──────────────────────────────────────  │
-│                                                                 │
-│  1. Get top 10 conversations from ChatService                  │
-│  2. For each conversation:                                     │
-│     ├─► Check if media already downloaded (index lookup)       │
-│     ├─► If not: download media                                 │
-│     │   └─► MediaService.downloadMedia(chatId)                │
-│     └─► Update index                                         │
-│                                                                 │
-│  ──── FULL SYNC ──────────────────────────────────────────────  │
-│                                                                 │
-│  1. Get ALL conversations from ChatService                     │
-│  2. For each conversation:                                     │
-│     ├─► Download any missing media                             │
-│     └─► Update index                                         │
-│                                                                 │
-│  ──── MEDIA DOWNLOAD (MediaService) ──────────────────────────  │
-│                                                                 │
-│  1. Extract media URLs from conversation messages              │
-│  2. For each URL:                                              │
-│     ├─► Check if Matrix thumbnail                              │
-│     │   └─► Resolve to full resolution URL                    │
-│     ├─► Download via Playwright                                │
-│     ├─► Compute SHA-1 hash                                     │
-│     ├─► Check if already exists (dedup)                        │
-│     ├─► Save to data/media/{hash}.{ext}                        │
-│     └─► Update index JSON                                      │
-│                                                                 │
-│  Output: Array of saved file paths                             │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Auto-Reply Flow
-
-How the bot automatically replies to chat messages.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                  AutoReplyService                               │
-│                                                                 │
-│  Scheduled: every N minutes (config.autoReply.checkInterval)   │
-│                                                                 │
-│  1. Get cached conversations                                   │
-│  2. For each conversation:                                     │
-│     │                                                         │
-│     ├─► Check for new/unread messages                          │
-│     │   └─► If no new messages: continue                       │
-│     │                                                         │
-│     ├─► Detect upsell/spam keywords                            │
-│     │   ├─► "onlyfans", "link in bio", "check my..."          │
-│     │   ├─► If detected: flag conversation, skip reply         │
-│     │   └─► If not: continue                                   │
-│     │                                                         │
-│     ├─► Generate AI reply suggestion                           │
-│     │   ┌─────────────────────────────────────────────────┐   │
-│     │   │  OpenRouter.generateReply(conversationHistory)  │   │
-│     │   │                                                   │   │
-│     │   │  Request: {                                      │   │
-│     │   │    messages: [                                   │   │
-│     │   │      { role: "system", content: replyPrompt },    │   │
-│     │   │      { role: "user", content: conversation }      │   │
-│     │   │    ]                                              │   │
-│     │   │  }                                                │   │
-│     │   │                                                   │   │
-│     │   │  Response: "Thanks for reaching out! 😊"         │   │
-│     │   │                                                   │   │
-│     │   │  Reply: "Thanks for reaching out! 😊"            │   │
-│     │   └─────────────────────────────────────────────────┘   │
-│     │                                                         │
-│     ├─► If autoSend = true:                                  │
-│     │   └─► ChatService.sendMessage(chatId, reply)           │
-│     │       └─► Log: "Auto-sent reply to {user}"             │
-│     │                                                         │
-│     └─► If autoSend = false:                                 │
-│         └─► Mark as pending (visible in dashboard)           │
-│             └─► User can approve/reject via dashboard        │
-│                                                                 │
-│  Output: Summary of actions taken                              │
-│  "Checked 15 conversations: 3 new messages, 1 reply sent"     │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Dashboard Data Flow
-
-How data flows from services to the web dashboard.
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    WebServer (Express)                          │
-│                                                                 │
-│  ──── REST API ───────────────────────────────────────────────  │
-│                                                                 │
-│  GET /api/stats                                                │
-│     ├─► Read from:                                             │
-│     │   ├─► Bot running state (in-memory)                      │
-│     │   ├─► PostsRepository.countProcessed()                   │
-│     │   ├─► MessagesRepository.countSent()                     │
-│     │   ├─► MessagesRepository.countResponded()                │
-│     │   └─► Calculate response rate                            │
-│     └─► Return: { running, processed, sent, responded, rate }  │
-│                                                                 │
-│  GET /api/messages                                             │
-│     └─► MessagesRepository.getRecent(limit: 50)                │
-│                                                                 │
-│  GET /api/analytics/by-strategy                                │
-│     └─► MessagesRepository.getStrategyStats()                  │
-│                                                                 │
-│  PUT /api/config                                               │
-│     ├─► Validate new config values                             │
-│     ├─► Update in-memory config                                │
-│     └─► Return updated config                                  │
-│                                                                 │
-│  ──── SSE LOG STREAMING ──────────────────────────────────────  │
-│                                                                 │
-│  GET /api/logs/stream                                          │
-│     ├─► Client connects                                        │
-│     ├─► Send any pending log entries                           │
-│     ├─► Subscribe to logger buffer                             │
-│     ├─► Push new entries as they arrive                        │
-│     │   └─► Event: log                                         │
-│     │   └─► Data: { level, message, timestamp }                │
-│     └─► On disconnect: unsubscribe                             │
-│                                                                 │
-│  ──── FRONTEND (public/index.html) ───────────────────────────  │
-│                                                                 │
-│  JavaScript polls API endpoints:                               │
-│     ├─► /api/stats every 5 seconds                             │
-│     ├─► /api/messages every 10 seconds                         │
-│     ├─► /api/timers every 2 seconds                            │
-│     └─► SSE /api/logs/stream (persistent connection)           │
-│                                                                 │
-│  Updates DOM in real-time:                                     │
-│     ├─► Stats cards (processed, sent, responded, rate)         │
-│     ├─► Activity feed (scrolling list)                         │
-│     ├─► Message viewer (click to expand)                       │
-│     ├─► Chat browser (conversation list)                       │
-│     ├─► Media gallery (image grid)                             │
-│     └─► Rate limiter timers (countdown)                        │
-└─────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Error Recovery Flows
-
-### AI Refusal Recovery
-
-```
-1. OpenRouter.analyzeImage() returns refusal
-   │
-   ├─► Detect refusal via heuristic patterns
-   │   ├─► "cannot analyze"
-   │   ├─► "against policy"
-   │   └─► "unable to process"
-   │
-   ├─► Try next model in fallback chain
-   │   ├─► OpenRouter.fallbackModels[0]
-   │   ├─► OpenRouter.fallbackModels[1]
-   │   └─► ...
-   │
-   └─► If all models refuse:
-       ├─► Mark post as processed with error
-       ├─► Log: "All models refused to analyze post {id}"
-       └─► Continue to next post
-```
-
-### Network Error Recovery
-
-```
-1. RedditApi.fetchPosts() throws error
-   │
-   └─► withRetry() wrapper handles recovery:
-       ├─► Retry 1: wait 5s
-       ├─► Retry 2: wait 15s
-       ├─► Retry 3: wait 45s
-       └─► After 3 failures:
-           ├─► Log error
-           ├─► Skip this subreddit
-           └─► Continue to next subreddit
-```
-
-### Browser Session Recovery
-
-```
-1. BrowserClient.verifySession() returns false
-   │
-   ├─► Check for expired cookies
-   │
-   ├─► Attempt automated re-login
-   │   ├─► BrowserClient.login()
-   │   └─► If success: continue
-   │
-   └─► If re-login fails:
-       ├─► Log error: "Browser session expired"
-       ├─► Stop bot
-       └─► Require manual login (scripts/login.ts)
-```
-
----
-
-## Data Lifecycle
-
-### Post Data
-
-```
-Discovered (MonitorService)
-  │
-  ├─► Stored in processed_posts (pending)
-  │
-  ├─► Processed (ProcessorService)
-  │   ├─► image_analysis updated
-  │   ├─► generated_message updated
-  │   └─► message_sent updated
-  │
-  └─► Archived (retention policy TBD)
-      └─► Kept indefinitely for analytics
-```
-
-### Message Data
-
-```
-Generated (ProcessorService)
-  │
-  ├─► Stored in sent_messages (got_response = 0)
-  │
-  ├─► Response checked (ResponseCheckerService)
-  │   ├─► got_response = 1
-  │   └─► response_checked_at set
-  │
-  ├─► If responded:
-  │   └─► Copied to successful_messages (for learning)
-  │
-  └─► Retained indefinitely for analytics
-```
-
-### Learning Data
-
-```
-Successful pair created (ResponseCheckerService)
-  │
-  ├─► Stored in successful_messages
-  │   ├─► original_message
-  │   ├─► image_analysis
-  │   ├─► post_title
-  │   ├─► response_snippet
-  │   └─► subreddit (for weighted selection)
-  │
-  ├─► Retrieved for few-shot learning
-  │   └─► Included in OpenRouter.generateMessage() prompt
-  │
-  └─► Retained indefinitely (grows bot intelligence)
-```
-
-### Chat Data
-
-```
-Conversation discovered (ChatService)
-  │
-  ├─► Cached in memory
-  ├─► Persisted to disk JSON
-  │
-  ├─► Messages added as they arrive
-  │
-  ├─► Media downloaded (MediaService)
-  │   └─► Stored in data/media/
-  │
-  └─► Retained until manually cleared
-      └─► No automatic cleanup (TBD)
-```
-
-### Media Data
-
-```
-Media URL discovered
-  │
-  ├─► Downloaded (MediaService)
-  │   ├─► Matrix thumbnails resolved
-  │   ├─► SHA-1 hash computed
-  │   └─► Saved to data/media/{hash}.{ext}
-  │
-  ├─► Indexed in data/media/index.json
-  │
-  ├─► Deduplicated (hash check before download)
-  │
-  └─► Retained until manually cleared
-      └─► No automatic cleanup (TBD)
-```
+Avoid converting errors into generic skips. Operational diagnosis depends on preserving which stage failed and why.

docs/database.md

@@ -1,550 +1,110 @@
-# Database Schema
+# Data model and persistence
 
-Complete reference for the SQLite database schema, migrations, and query patterns.
+## Storage model
 
----
+The application uses one `better-sqlite3` database, normally `data/reddit-bot.db`, in WAL mode with foreign keys enabled. The persistent Docker volume also holds browser profiles and downloaded media, so a database-only backup is not a complete account/content backup.
 
-## Table of Contents
+`src/database/client.ts` is the schema authority. Migrations are ordered functions guarded by SQLite `PRAGMA user_version` and run inside transactions. The repository does not use an ORM.
 
-1. [Overview](#overview)
-2. [Database File](#database-file)
-3. [Schema](#schema)
-4. [Indexes](#indexes)
-5. [Migrations](#migrations)
-6. [Query Patterns](#query-patterns)
-7. [Repository Methods](#repository-methods)
-8. [Data Retention](#data-retention)
-
----
-
-## Overview
-
-RedditBot uses SQLite (via `better-sqlite3`) for persistent storage. The database tracks processed posts, sent messages, and successful message/response pairs.
-
-**Features**:
-- WAL mode for better concurrent read performance
-- Foreign key constraints enabled
-- Progressive migrations for schema evolution
-- Repository pattern for data access
-
----
-
-## Database File
-
-**Default path**: `./data/reddit-bot.db`
-
-Configured in `config.yaml`:
-
-```yaml
-database:
-  path: "./data/reddit-bot.db"
-```
-
-The database file is auto-created on first run.
-
----
-
-## Schema
-
-### Table: `processed_posts`
-
-Tracks all posts that have been discovered and processed.
-
-```sql
-CREATE TABLE processed_posts (
-  id TEXT PRIMARY KEY,           -- Reddit post ID
-  subreddit TEXT NOT NULL,       -- Source subreddit
-  author TEXT NOT NULL,          -- Post author username
-  title TEXT,                    -- Post title
-  image_url TEXT,                -- Original image URL
-  image_analysis TEXT,           -- AI-generated JSON description
-  generated_message TEXT,        -- AI-generated DM text
-  processed_at INTEGER NOT NULL, -- Unix timestamp
-  message_sent INTEGER DEFAULT 0, -- 0 = not sent, 1 = sent
-  error TEXT                     -- Error message if processing failed
-);
-```
-
-**Column Details**:
-
-| Column | Type | Constraints | Description |
-|---|---|---|---|
-| `id` | TEXT | PRIMARY KEY | Reddit post ID (e.g., "abc123") |
-| `subreddit` | TEXT | NOT NULL | Source subreddit name |
-| `author` | TEXT | NOT NULL | Post author username |
-| `title` | TEXT | | Post title (nullable if unavailable) |
-| `image_url` | TEXT | | Original image URL |
-| `image_analysis` | TEXT | | JSON string from AI analysis |
-| `generated_message` | TEXT | | The DM text that was generated |
-| `processed_at` | INTEGER | NOT NULL | Unix timestamp when processed |
-| `message_sent` | INTEGER | DEFAULT 0 | 0 = not sent, 1 = successfully sent |
-| `error` | TEXT | | Error message if processing failed |
-
-**Example Row**:
-
-```json
-{
-  "id": "abc123",
-  "subreddit": "gonewild",
-  "author": "user123",
-  "title": "Summer vibes",
-  "image_url": "https://i.redd.it/abc123.jpg",
-  "image_analysis": "{\"gender\":\"F\",\"description\":\"Young woman...\"}",
-  "generated_message": "Hey, you look amazing...",
-  "processed_at": 1716234567,
-  "message_sent": 1,
-  "error": null
-}
-```
-
----
-
-### Table: `sent_messages`
-
-Tracks all DMs sent by the bot.
-
-```sql
-CREATE TABLE sent_messages (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  post_id TEXT NOT NULL,
-  recipient TEXT NOT NULL,
-  subject TEXT DEFAULT 'Stunning',
-  message TEXT NOT NULL,
-  sent_at INTEGER NOT NULL,
-  strategy_id TEXT,
-  got_response INTEGER DEFAULT 0,
-  response_checked_at INTEGER,
-  FOREIGN KEY (post_id) REFERENCES processed_posts(id)
-);
-```
-
-**Column Details**:
-
-| Column | Type | Constraints | Description |
-|---|---|---|---|
-| `id` | INTEGER | PRIMARY KEY AUTOINCREMENT | Internal ID |
-| `post_id` | TEXT | NOT NULL, FK | Source post ID |
-| `recipient` | TEXT | NOT NULL | Recipient username |
-| `subject` | TEXT | DEFAULT 'Stunning' | DM subject line |
-| `message` | TEXT | NOT NULL | DM body text |
-| `sent_at` | INTEGER | NOT NULL | Unix timestamp when sent |
-| `strategy_id` | TEXT | | A/B test variant name |
-| `got_response` | INTEGER | DEFAULT 0 | 0 = no response, 1 = responded |
-| `response_checked_at` | INTEGER | | Timestamp of last response check |
-
-**Example Row**:
-
-```json
-{
-  "id": 1,
-  "post_id": "abc123",
-  "recipient": "user123",
-  "subject": "Stunning",
-  "message": "Hey, you look amazing...",
-  "sent_at": 1716234567,
-  "strategy_id": "compliment",
-  "got_response": 1,
-  "response_checked_at": 1716238167
-}
-```
-
----
-
-### Table: `successful_messages`
-
-Stores successful message/response pairs for few-shot learning.
-
-```sql
-CREATE TABLE successful_messages (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  sent_message_id INTEGER,
-  original_message TEXT NOT NULL,
-  image_analysis TEXT,
-  post_title TEXT,
-  response_snippet TEXT,
-  subreddit TEXT,
-  created_at INTEGER NOT NULL,
-  FOREIGN KEY (sent_message_id) REFERENCES sent_messages(id)
-);
-```
-
-**Column Details**:
-
-| Column | Type | Constraints | Description |
-|---|---|---|---|
-| `id` | INTEGER | PRIMARY KEY AUTOINCREMENT | Internal ID |
-| `sent_message_id` | INTEGER | FK, nullable | Related sent message ID |
-| `original_message` | TEXT | NOT NULL | The DM that got a response |
-| `image_analysis` | TEXT | | Context from image analysis |
-| `post_title` | TEXT | | Original post title |
-| `response_snippet` | TEXT | | First reply text |
-| `subreddit` | TEXT | | For weighted example selection |
-| `created_at` | INTEGER | NOT NULL | Unix timestamp |
-
-**Example Row**:
-
-```json
-{
-  "id": 1,
-  "sent_message_id": 1,
-  "original_message": "Hey, you look amazing...",
-  "image_analysis": "{\"gender\":\"F\",\"description\":\"...\"}",
-  "post_title": "Summer vibes",
-  "response_snippet": "Thank you so much! 😊",
-  "subreddit": "gonewild",
-  "created_at": 1716238167
-}
-```
-
----
-
-## Indexes
-
-### `processed_posts` Indexes
-
-```sql
-CREATE INDEX idx_posts_subreddit ON processed_posts(subreddit);
-CREATE INDEX idx_posts_author ON processed_posts(author);
-```
-
-**Purpose**: Fast lookup by subreddit (for processing stats) and by author (for skip-checking).
-
----
-
-### `sent_messages` Indexes
-
-```sql
-CREATE INDEX idx_messages_recipient ON sent_messages(recipient);
-CREATE INDEX idx_messages_strategy ON sent_messages(strategy_id);
-CREATE INDEX idx_messages_response ON sent_messages(got_response);
-```
-
-**Purpose**:
-- `idx_messages_recipient`: Fast lookup when matching responses
-- `idx_messages_strategy`: Analytics by strategy variant
-- `idx_messages_response`: Filter for responded/not-responded
-
----
+## Ownership categories
 
-### `successful_messages` Indexes
+### Account registry and account content
 
-```sql
-CREATE INDEX idx_success_subreddit ON successful_messages(subreddit);
-CREATE INDEX idx_success_message ON successful_messages(sent_message_id);
-```
+- `reddit_accounts`: verified Reddit/Matrix identity, encrypted-at-rest only to the degree provided by the host/volume, cookie JSON, Matrix credentials, active/status timestamps.
+- `reddit_conversations`: account-scoped cached Matrix conversation payloads.
+- `reddit_account_sync_state`: account-scoped sync cursor, full/delta timestamps, and invitation cooldown.
+- `reddit_media`: account-scoped private-media metadata and relative file path.
+- `media_library_assets`: process-global operator-owned image metadata, overlapping anatomy tags, SFW/NSFW classification, consent time, enablement, dimensions, hash, and private relative path.
+- `media_library_sends`: account/conversation/inbound-event reservation and confirmed/failed Matrix delivery audit for a shared library asset.
 
-**Purpose**:
-- `idx_success_subreddit`: Weighted example selection by subreddit
-- `idx_success_message`: Link back to sent message
+The special legacy-unassigned account exists only to preserve rows created before account ownership was introduced. New runtime data must use a verified account ID.
 
----
+### Outreach and outcomes
 
-## Migrations
+- `processed_posts`: account/post key, source metadata, analysis, generated opener, send marker, and terminal error/rejection reason.
+- `sent_messages`: account-owned opener/reply attribution, strategy/experiment/model metadata, Matrix room, response/image flags, and source type.
+- `successful_messages`: mature positive examples for prompt context; terminal negative reclassification removes the linked example.
+- `conversation_outcomes`: normalized outcome for a sent message (`engaged`, `declined`, `boundary`, `upsell`, or `unknown`).
+- `activity_log`: operator-facing events with optional recipient/post context.
+- `reddit_users`: global mapping between Reddit fullname/username and Matrix identity.
+- `recipient_suppressions`: process-global recipient reservation/contact record used to prevent cross-account duplicates.
 
-Migrations are defined in `src/database/client.ts` and run automatically on every startup.
+### Durable work and idempotency
 
-### Migration Logic
+- `candidate_queue`: global candidate snapshot, source/priority, state, prepared payload, worker lease, retry timing, selected account, and rejection/error details.
+- `delivery_outbox`: account-scoped prepared delivery and idempotency status retained for legacy/recovery paths.
+- `conversation_states`: account/conversation policy and derived state JSON.
+- `conversation_automation_claims`: account/conversation/inbound-event claim with intended reply and `pending`, `sent`, or terminal `superseded` state plus audit timestamps.
+- `runtime_state`: small process controls such as whether bot work is running.
 
-```typescript
-// Pseudo-code for migration process
-function runMigrations(db: Database) {
-  // Enable features
-  db.exec("PRAGMA journal_mode=WAL;");
-  db.exec("PRAGMA foreign_keys=ON;");
+### Configuration and telemetry
 
-  // Create tables if they don't exist
-  db.exec(`CREATE TABLE IF NOT EXISTS processed_posts (...)`);
-  db.exec(`CREATE TABLE IF NOT EXISTS sent_messages (...)`);
-  db.exec(`CREATE TABLE IF NOT EXISTS successful_messages (...)`);
+- `app_config`: one secret-free validated application configuration record.
+- `ai_usage`: requested/actual model, token/cost, latency, success/error, purpose, and account attribution.
+- `legacy_content_imports`: records one-time imports from legacy content stores.
 
-  // Create indexes if they don't exist
-  db.exec(`CREATE INDEX IF NOT EXISTS idx_posts_subreddit ON processed_posts(subreddit)`);
-  // ... more indexes
+## Critical invariants
 
-  // Safe column additions (for schema evolution)
-  db.exec(`ALTER TABLE processed_posts ADD COLUMN error TEXT`);
-}
-```
+1. Account-produced rows carry `account_id`; cross-account views must opt into global queries explicitly.
+2. Recipient identity comparisons are case-insensitive and global for outreach suppression.
+3. A sent message is persisted only after remote confirmation.
+4. Candidate and automation claims are lease/claim based; a worker must own the expected lease before it changes state.
+5. Conversation policy is snapshotted in state JSON when automation starts for that conversation.
+6. Secrets and the database path are not stored in `app_config`.
+7. Private media paths in SQLite are relative to the persistent data root; HTTP access remains authenticated.
+8. Received `reddit_media` and operator `media_library_assets` are separate ownership domains; no automatic copy or promotion exists.
+9. A library image content hash has at most one reservation per account conversation, even if the same file is later re-uploaded under a new asset ID; an inbound request also has at most one selected asset. Failed or uncertain attempts remain reserved to prevent duplicates.
 
-### Migration Safety
+## Repository map
 
-- All `CREATE TABLE` statements use `IF NOT EXISTS`
-- All `CREATE INDEX` statements use `IF NOT EXISTS`
-- Column additions use `ALTER TABLE ADD COLUMN IF NOT EXISTS` pattern
-- Migrations are idempotent (safe to run multiple times)
+`src/database/repositories.ts` contains the domain repositories for posts/messages/outcomes/activity/outbox/state/claims/users/recipient history. `account-repositories.ts` owns account records and cached account content. Candidate and AI telemetry have dedicated repositories.
 
-### Adding New Columns
+Prefer narrow repository methods such as `claimReady`, `markSent`, or `getByChatRoomId` to exposing SQL or generic CRUD. This keeps transaction and ownership rules near the schema.
 
-When adding new columns to existing tables:
+## Candidate leases
 
-```typescript
-// In src/database/client.ts
-const tableInfo = db.prepare(`PRAGMA table_info(processed_posts)`).all();
-const hasErrorColumn = tableInfo.some((col: any) => col.name === 'error');
+Discovery inserts candidates without overwriting terminal work. Screening and dispatch use a worker ID plus lease expiry. On startup all interrupted leases can be recovered; during operation expired leases are recovered and due retries promoted. A transient account failure belongs to the selected account, so delivery can be made visible quickly for another eligible runtime without losing the prepared candidate.
 
-if (!hasErrorColumn) {
-  db.exec("ALTER TABLE processed_posts ADD COLUMN error TEXT");
-}
-```
+Any new candidate state needs:
 
----
+- an allowed predecessor and terminal/retry semantics;
+- a lease ownership rule;
+- recovery behavior after process death;
+- counts/reasons for the operator funnel;
+- tests for stale lease, wrong owner, restart, and duplicate post/author cases.
 
-## Query Patterns
+## Conversation reply claims
 
-### Post Processing
+The unique identity is account + conversation + inbound message key. The claim persists the intended reply before the remote send. A pending claim is not blindly retried: Matrix history is checked first. After rate-limit waiting, Matrix is refreshed again; a newer event, boundary, received image, seller signal, operator-owned state, or repeated media request changes the claim to `superseded` and records `superseded_at`. This closes both the process-crash window between remote acceptance and local completion and the stale-send window while a reply is queued.
 
-**Check if post was already processed**:
+Changes to this flow must prove at-most-once observable replies across retry and restart tests.
 
-```sql
-SELECT id FROM processed_posts WHERE id = ?;
-```
+Outcome rows are re-evaluated from the complete attributed recipient transcript. Negative outcomes take precedence over reciprocal activity. `successful_messages` rows are created only after the conversation becomes terminal/human-owned and are deleted by `sent_message_id` when later evidence changes the outcome.
 
-**Mark post as processed**:
+## Configuration persistence
 
-```sql
-INSERT OR REPLACE INTO processed_posts 
-  (id, subreddit, author, title, image_url, image_analysis, 
-   generated_message, processed_at, message_sent, error)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
-```
+On an empty database, `config.yaml` is parsed, environment-owned values are injected, the result is validated, and the application-owned subset is saved to `app_config`. Later starts load SQLite first. Dashboard changes update that record.
 
-**Mark post as sent**:
+The persisted record excludes:
 
-```sql
-UPDATE processed_posts 
-SET message_sent = 1 
-WHERE id = ?;
-```
+- `OPENROUTER_API_KEY`;
+- dashboard/agent tokens;
+- `DATABASE_PATH`.
 
-**Update post with analysis**:
+Those values are supplied by the environment on every load.
 
-```sql
-UPDATE processed_posts 
-SET image_analysis = ?, generated_message = ? 
-WHERE id = ?;
-```
+## Adding a migration
 
----
+1. Inspect the final schema and all repository assumptions.
+2. Append one migration function; never reorder or modify an already-released migration.
+3. Make the operation transactional and compatible with existing data.
+4. Use `addColumnIfNotExists` only where repeatability is appropriate; table rebuilds need explicit foreign-key handling and `foreign_key_check`.
+5. Update repository types and operations.
+6. Add tests for a fresh in-memory database and, when relevant, an older schema upgraded in place.
+7. Update this document and affected API/contracts.
 
-### Message Tracking
+Do not edit a live SQLite file by hand. Back it up, stop writers when required, apply code-owned migrations, and verify `integrity_check`, `foreign_key_check`, row counts, and application reads.
 
-**Record a sent message**:
+## Backup and recovery
 
-```sql
-INSERT INTO sent_messages 
-  (post_id, recipient, subject, message, sent_at, strategy_id)
-VALUES (?, ?, 'Stunning', ?, ?, ?);
-```
-
-**Get recent messages**:
-
-```sql
-SELECT * FROM sent_messages 
-ORDER BY sent_at DESC 
-LIMIT ?;
-```
-
-**Update response status**:
-
-```sql
-UPDATE sent_messages 
-SET got_response = 1, response_checked_at = ? 
-WHERE id = ?;
-```
-
-**Check if user was previously messaged**:
-
-```sql
-SELECT COUNT(*) FROM sent_messages WHERE recipient = ?;
-```
-
----
-
-### Strategy Analytics
-
-**Get strategy statistics**:
-
-```sql
-SELECT 
-  strategy_id,
-  COUNT(*) as sent,
-  SUM(got_response) as responded
-FROM sent_messages
-WHERE strategy_id IS NOT NULL
-GROUP BY strategy_id;
-```
-
-**Get response rate by subreddit**:
-
-```sql
-SELECT 
-  p.subreddit,
-  COUNT(*) as sent,
-  SUM(s.got_response) as responded
-FROM sent_messages s
-JOIN processed_posts p ON s.post_id = p.id
-GROUP BY p.subreddit;
-```
-
-**Get daily response trend**:
-
-```sql
-SELECT 
-  DATE(sent_at, 'unixepoch') as date,
-  COUNT(*) as sent,
-  SUM(got_response) as responded
-FROM sent_messages
-GROUP BY DATE(sent_at, 'unixepoch')
-ORDER BY date DESC
-LIMIT 30;
-```
-
----
-
-### Few-Shot Learning
-
-**Get successful examples for a subreddit**:
-
-```sql
-SELECT 
-  original_message,
-  image_analysis,
-  post_title,
-  response_snippet
-FROM successful_messages
-WHERE subreddit = ?
-ORDER BY created_at DESC
-LIMIT 3;
-```
-
-**Store successful pair**:
-
-```sql
-INSERT INTO successful_messages 
-  (sent_message_id, original_message, image_analysis, 
-   post_title, response_snippet, subreddit, created_at)
-VALUES (?, ?, ?, ?, ?, ?, ?);
-```
-
----
-
-## Repository Methods
-
-### PostsRepository
-
-```typescript
-class PostsRepository {
-  /** Check if a post was already processed */
-  getById(id: string): ProcessedPost | undefined
-
-  /** Mark a post as processed */
-  insert(post: ProcessedPostInsert): void
-
-  /** Mark a post as having a message sent */
-  markSent(id: string): void
-
-  /** Update post with AI analysis results */
-  updateAnalysis(id: string, analysis: string, message: string): void
-
-  /** Get total count of processed posts */
-  count(): number
-
-  /** Get count by subreddit */
-  countBySubreddit(subreddit: string): number
-}
-```
-
-### MessagesRepository
-
-```typescript
-class MessagesRepository {
-  /** Record a sent message */
-  insert(message: MessageInsert): number
-
-  /** Get recent sent messages */
-  getRecent(limit: number): SentMessage[]
-
-  /** Get messages by recipient */
-  getByRecipient(recipient: string): SentMessage[]
-
-  /** Update response status */
-  markResponded(id: number, checkedAt: number): void
-
-  /** Get strategy statistics */
-  getStrategyStats(): StrategyStat[]
-
-  /** Get response rate by subreddit */
-  getSubredditStats(): SubredditStat[]
-
-  /** Get daily response trend */
-  getDailyTrend(days: number): DailyTrend[]
-
-  /** Get total count of sent messages */
-  count(): number
-
-  /** Get count of responded messages */
-  countResponded(): number
-}
-```
-
-### SuccessfulMessagesRepository
-
-```typescript
-class SuccessfulMessagesRepository {
-  /** Store a successful message/response pair */
-  insert(pair: SuccessfulMessageInsert): void
-
-  /** Get examples for few-shot learning */
-  getExamples(subreddit: string, count: number): Example[]
-
-  /** Get total count */
-  count(): number
-
-  /** Get recent examples */
-  getRecent(limit: number): SuccessfulMessage[]
-}
-```
-
----
-
-## Data Retention
-
-### Current Behavior
-
-All data is retained indefinitely. There is no automatic cleanup or retention policy.
-
-| Table | Retention | Notes |
-|---|---|---|
-| `processed_posts` | Indefinite | Grows with each post processed |
-| `sent_messages` | Indefinite | Grows with each message sent |
-| `successful_messages` | Indefinite | Grows with each response received |
-
-### Estimated Growth
-
-With default settings (20 messages/hour, 24/7 operation):
-
-| Timeframe | Posts | Messages | Responses (est. 30%) |
-|---|---|---|---|
-| 1 day | ~480 | ~288 | ~86 |
-| 1 week | ~3,360 | ~2,016 | ~605 |
-| 1 month | ~14,400 | ~8,640 | ~2,592 |
-| 1 year | ~175,200 | ~105,120 | ~31,536 |
-
-### Recommended Cleanup (Future)
-
-Consider implementing automated cleanup:
-
-```sql
--- Archive old processed posts
-CREATE TABLE processed_posts_archive AS
-SELECT * FROM processed_posts
-WHERE processed_at < ?;
-
--- Delete archived posts
-DELETE FROM processed_posts
-WHERE processed_at < ?;
-
--- Keep last N months of data
-```
-
-> **Note**: Successful messages should NEVER be deleted as they are used for few-shot learning.
+For a running WAL database, use SQLite's online backup mechanism or stop the container before copying the database plus `-wal`/`-shm` state. A full production backup should include the entire persistent volume because sessions and media live beside the database. Validate that the backup can be opened and contains expected tables before any destructive reset.

docs/deployment.md

@@ -1,413 +1,132 @@
-# Deployment Guide
+# Deployment and operations
 
-Complete guide for deploying RedditBot in various environments.
+## Production model
 
----
+The production unit is the `reddit-bot` Docker Compose service. The image uses the Playwright base, installs/builds the Node application, serves the compiled React dashboard and Express API on port 3000, and stores state under `/app/data` on the named `reddit_bot_data` volume.
 
-## Table of Contents
+The container does not run VNC, accept Reddit passwords, or scrape a Matrix token from a login browser. Account authentication enters through a locally exported session dump and is persisted in the sensitive volume.
 
-1. [Prerequisites](#prerequisites)
-2. [Local Development](#local-development)
-3. [Docker Deployment](#docker-deployment)
-4. [Docker Compose](#docker-compose)
-5. [Dokploy Deployment](#dokploy-deployment)
-6. [Production Considerations](#production-considerations)
-7. [Monitoring & Maintenance](#monitoring--maintenance)
-8. [Troubleshooting](#troubleshooting-1)
+## Authority and safety
 
----
+Deployment, restart, start/resume, session import, configuration mutation, send actions, and data deletion are separate operations. Only perform the ones the user explicitly requested. In particular, “commit and push” does not authorize a Dokploy deployment or bot restart.
 
-## Prerequisites
+Before any live operation:
 
-### Required
+1. Confirm the target is the RedditBot Compose service, not the whole Dokploy host/instance.
+2. Inspect current Git revision, worktree/remote state, deployment state, bot running/paused state, account runtimes, and recent errors.
+3. Identify whether the action can send messages or change account state.
+4. Back up affected persistent state before destructive or migration-heavy work.
+5. Define observable success criteria and a recovery path.
 
-| Requirement | Version | Notes |
-|---|---|---|
-| Node.js | 18+ | LTS recommended |
-| npm | 9+ | Or yarn/pnpm |
-| OpenRouter API Key | - | Sign up at [openrouter.ai](https://openrouter.ai) |
-| Reddit Account | - | With DM permissions enabled |
+## Required environment
 
-### Recommended
+The Compose service passes:
 
-| Requirement | Notes |
-|---|---|
-| 1 GB RAM | Minimum for browser automation |
-| 1 CPU core | More for higher message throughput |
-| 5 GB disk | For database, media, and browser data |
+- `OPENROUTER_API_KEY`;
+- `WEB_DASHBOARD_TOKEN`;
+- optional `REDDIT_BOT_AGENT_READ_TOKEN`;
+- optional `REDDIT_BOT_AGENT_CONTROL_TOKEN`.
 
----
+Dokploy access credentials are stored in the ignored repository `.env`. Use them only when access is explicitly requested. Never print the file, include tokens in commands that will be echoed, commit them, or copy response metadata containing credentials. Follow redirects for Dokploy API calls.
 
-## Local Development
+## Persistence
 
-### 1. Clone and Install
+`reddit_bot_data:/app/data` contains:
 
-```bash
-git clone <repository-url>
-cd RedditBot
-npm install
-```
+- SQLite database and WAL files;
+- imported browser/account sessions;
+- cached Matrix credentials/state;
+- downloaded private media;
+- per-account browser profiles.
 
-### 2. Configure
+A volume replacement or deletion is therefore a destructive account-and-content reset. Verify a readable backup before touching it and state exactly what will be lost. Removing a Compose application and deleting its volume are not the same action.
 
-Create `config.yaml`:
+## Deployment procedure
 
-```yaml
-reddit:
-  subreddits:
-    - gonewild
-  pollInterval: 15
-  targetGender: "F"
-  sellerKeywords:
-    - seller
-    - onlyfans
+Use the actual current Dokploy API/Compose identifiers from a read-only lookup; do not copy identifiers into documentation or assume an older deployment still has the same ID.
 
-openrouter:
-  apiKey: "sk-or-v1-your-key-here"
-  model: "meta-llama/llama-3.2-90b-vision-preview"
-  fallbackModels:
-    - "google/gemini-2.0-flash-001"
+1. Confirm the intended commit exists on the tracked remote branch.
+2. Read current Compose/deployment status and capture the prior image/revision if available.
+3. Confirm whether the bot must remain paused through deployment. Do not change persisted running state unless authorized.
+4. Trigger the bounded Compose deployment.
+5. Poll the deployment record to a terminal success/failure state; an accepted trigger is not completion.
+6. Verify the running container is the new deployment and is not restarting.
+7. Verify public `GET /healthz` and authenticated `GET /api/v1/readyz`/overview as appropriate.
+8. Verify account runtime count/state, bot paused/running state, sync/cooldown state, and recent sanitized logs.
+9. Verify the persistent volume is mounted and pre-deployment data is readable.
 
-rateLimit:
-  minDelayMs: 30000
-  maxMessagesPerHour: 20
-  jitterMs: 15000
+Do not use a green container health badge as the only evidence. The process may be healthy while account runtimes are logged out, the bot is paused, Matrix is degraded, or candidate/reply work is blocked.
 
-browser:
-  headless: true
-  userDataDir: "./data/browser"
+## Health semantics
 
-database:
-  path: "./data/reddit-bot.db"
+- `/healthz`: unauthenticated process liveness only; intentionally reveals no private state.
+- `/api/v1/readyz`: authenticated component readiness and degraded authentication state.
+- `/api/v1/overview`: consolidated runtime, account, sync, rate-limit, candidate/reply, and recent-error view.
+- `/api/stats`, `/api/attention`, `/api/outreach`: operator-level workload detail.
+- `/api/events/stream`: realtime signal, not a replacement for snapshot checks.
 
-web:
-  port: 3000
+Success should distinguish:
 
-dryRun: true  # Start in dry run mode
-```
+- process/container running;
+- API reachable and authenticated;
+- database/volume mounted;
+- accounts restored and verified;
+- bot intentionally paused or running;
+- no crash loop or new high-severity errors;
+- requested workload actually completed.
 
-Set environment variables:
+## Account session operations
 
-```bash
-export REDDIT_USERNAME="your-username"
-export REDDIT_PASSWORD="your-password"
-```
+The supported workflow is:
 
-### 3. Initial Login
+1. Load `extensions/reddit-session-exporter` into the operator's local Chrome.
+2. Sign in to Reddit locally and open Reddit Chat.
+3. Export a combined Reddit cookie + Matrix session JSON.
+4. Upload it through Settings > Access.
+5. Wait for both Reddit and Matrix identities to verify and for the matching runtime to be replaced/started.
+6. Delete the local export file.
 
-Run the login script to establish a browser session:
+The dump is a bearer credential bundle. Do not inspect or paste it into logs. An account with one valid half is still unavailable for work.
 
-```bash
-npm run login
-```
+## Incident diagnosis
 
-This will:
-1. Open a browser window
-2. Navigate to Reddit login
-3. Wait for you to complete login (including 2FA if enabled)
-4. Save cookies to `data/browser/`
-
-### 4. Start the Bot
-
-```bash
-# Development (with TypeScript execution)
-npm run dev
+### No new outreach
 
-# Production (compiled JavaScript)
-npm start
-```
+Check, in order: persisted bot running state, the per-account delivery states on Overview, enabled/running account count, full authentication, reply backlog, account send timer/hourly cap, account-specific Matrix cooldown, global Reddit cooldown, candidate funnel counts/reasons, enabled subreddit count, recent intake/screening logs, and OpenRouter failures.
 
-### 5. Access Dashboard
+Do not infer “no candidates” from “fetched N posts.” Inspect already processed/contacted, age/gender, seller, expired, AI skip, ready, retry, and rejected counts.
 
-Open http://localhost:3000 in your browser.
+### Conversations appear stale
 
----
+Separate Matrix remote acceptance from cached/dashboard visibility. Inspect Matrix identity/whoami, sync cursor/status, last full/delta sync, new event IDs, username enrichment, HTTP conversation snapshot, SSE validation/reconnect, and client query invalidation. A stale dashboard can coexist with a successful remote send.
 
-## Docker Deployment
+### Reddit 403/429/404
 
-### Build the Image
+- 429: honor `retryAfterMs` through the shared coordinator and avoid additional account requests.
+- repeated/broad 403: treat as a possible service-wide anti-abuse block; inspect successful requests and shared cooldown rather than declaring every subreddit private.
+- listing 404: the code disables that configured subreddit persistently.
 
-```bash
-docker build -t reddit-bot .
-```
+### Database problems
 
-### Run the Container
+Stop writers if recovery needs file operations. Back up the entire data directory, inspect SQLite `integrity_check`/`foreign_key_check`, WAL state, disk capacity/permissions, migration version, and recent logs. Do not create an empty replacement database over the original.
 
-```bash
-docker run -d \
-  --name reddit-bot \
-  -p 3000:3000 \
-  -v $(pwd)/data:/app/data \
-  -e OPENROUTER_API_KEY=sk-or-v1-your-key \
-  -e REDDIT_USERNAME=your-username \
-  -e REDDIT_PASSWORD=your-password \
-  -e BROWSER_HEADLESS=true \
-  reddit-bot:latest
-```
-
-### Dockerfile Structure
-
-```dockerfile
-# Build stage
-FROM node:18-alpine AS builder
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-COPY . .
-RUN npm run build
-
-# Production stage
-FROM node:18-alpine
-WORKDIR /app
-COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/node_modules ./node_modules
-COPY --from=builder /app/config.yaml ./config.yaml
-COPY --from=builder /app/package.json ./package.json
-
-EXPOSE 3000
-CMD ["node", "dist/index.js"]
-```
+## Backup and destructive recovery
 
----
+For routine backups, prefer a volume-level snapshot or a consistent SQLite online backup plus browser/media directories. For a reset:
 
-## Docker Compose
+1. State whether scope is one account, selected content, the RedditBot volume, the Compose application, or the Dokploy instance.
+2. Capture and validate a backup.
+3. Stop relevant writers.
+4. Resolve explicit volume/container/app identifiers with read-only inspection.
+5. Perform only the authorized deletion.
+6. Recreate/deploy, then verify health, schema, accounts, and persistence.
+7. Report what was removed and whether/how it can be restored.
 
-### docker-compose.yml
+## Routine checks
 
-```yaml
-version: '3.8'
+- Review attention items, failed/retrying candidates, reply backlog age, account authentication, invitation/global cooldowns, model errors/cost, and disk/volume health.
+- Review response/image rates only with mature sample counts and by source/strategy/account context.
+- Back up before migrations, account resets, or Compose/volume changes.
+- Rotate dashboard, agent, OpenRouter, Reddit, and Matrix credentials after suspected exposure.
 
-services:
-  reddit-bot:
-    build: .
-    container_name: reddit-bot
-    ports:
-      - "3000:3000"
-    volumes:
-      - ./data:/app/data
-    environment:
-      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
-      - REDDIT_USERNAME=${REDDIT_USERNAME}
-      - REDDIT_PASSWORD=${REDDIT_PASSWORD}
-      - BROWSER_HEADLESS=true
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "wget", "--spider", "http://localhost:3000/api/stats"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 60s
-```
-
-### Start with Compose
-
-```bash
-# Set environment variables
-cp .env.example .env
-# Edit .env with your credentials
-
-# Build and start
-docker compose up -d --build
-
-# View logs
-docker compose logs -f reddit-bot
-
-# Stop
-docker compose down
-
-# Restart
-docker compose restart
-```
-
----
-
-## Dokploy Deployment
-
-Dokploy is a self-hosted platform for deploying applications. See `DOKPLOY_DEPLOY.md` for detailed instructions.
-
-### Quick Start
-
-1. **Create Application**: In Dokploy dashboard, create a new Docker application
-2. **Set Environment Variables**:
-   - `OPENROUTER_API_KEY`
-   - `REDDIT_USERNAME`
-   - `REDDIT_PASSWORD`
-   - `BROWSER_HEADLESS`
-3. **Mount Volume**: Mount `./data` for persistent storage
-4. **Set Port**: Map container port 3000 to host port
-5. **Deploy**: Push to repository and trigger deployment
-
-### Dokploy Configuration
-
-```yaml
-# Dokploy-specific settings
-app:
-  type: docker
-  repository: <your-repo>
-  branch: main
-  dockerfilePath: Dockerfile
-  
-  environment:
-    OPENROUTER_API_KEY: $OPENROUTER_API_KEY
-    REDDIT_USERNAME: $REDDIT_USERNAME
-    REDDIT_PASSWORD: $REDDIT_PASSWORD
-    BROWSER_HEADLESS: "true"
-  
-  ports:
-    - container: 3000
-      host: 3000
-  
-  volumes:
-    - source: reddit-bot-data
-      target: /app/data
-      type: bind
-  
-  restartPolicy: unless-stopped
-```
-
----
-
-## Production Considerations
-
-### Security
-
-1. **Network Isolation**: Run behind a reverse proxy with authentication
-2. **Environment Variables**: Never commit credentials; use secrets management
-3. **Dashboard Access**: Restrict to internal network or add auth
-4. **Browser Data**: Protect `data/browser/` directory
-
-### Performance
-
-1. **Browser Headless**: Always use headless mode in production
-2. **WAL Mode**: SQLite WAL mode is enabled by default for concurrent reads
-3. **Rate Limiting**: Adjust based on Reddit account age and trust level
-4. **Message Volume**: Start low (10-20/hour) and increase gradually
-
-### Reliability
-
-1. **Auto-restart**: Use `restart: unless-stopped` in Docker
-2. **Health Checks**: Monitor `/api/stats` endpoint
-3. **Logging**: Review logs regularly for errors
-4. **Backups**: Regularly backup `data/reddit-bot.db`
-
-### Monitoring
-
-1. **Dashboard**: Check web dashboard for real-time stats
-2. **Response Rate**: Monitor response rates per strategy/subreddit
-3. **Error Rate**: Watch for AI refusals, send failures
-4. **Browser Health**: Verify session isn't expired
-
-### Scaling
-
-RedditBot is designed as a single-instance application. For scaling:
-
-1. **Multiple Accounts**: Run separate instances per Reddit account
-2. **Subreddit Split**: Distribute subreddits across instances
-3. **Centralized DB**: Consider moving to PostgreSQL for multi-instance
-
----
-
-## Monitoring & Maintenance
-
-### Daily Checks
-
-- [ ] Dashboard shows bot is running
-- [ ] Response rate is reasonable (>10%)
-- [ ] No repeated errors in logs
-- [ ] Browser session is active
-
-### Weekly Tasks
-
-- [ ] Review analytics (strategy performance, subreddit performance)
-- [ ] Check disk usage (media files, database)
-- [ ] Verify backup is working
-- [ ] Review successful messages for quality
-
-### Monthly Tasks
-
-- [ ] Backup database
-- [ ] Review and update strategy variants
-- [ ] Check for OpenRouter model updates
-- [ ] Review and update seller keywords
-- [ ] Verify browser session is still valid
-
-### Backup Procedure
-
-```bash
-# Stop the bot
-docker compose stop
-
-# Backup database
-cp data/reddit-bot.db data/reddit-bot.db.backup.$(date +%Y%m%d)
-
-# Backup browser session (optional)
-tar czf data/browser.backup.$(date +%Y%m%d).tar.gz data/browser/
-
-# Restart the bot
-docker compose start
-```
-
----
-
-## Troubleshooting
-
-### Bot Won't Start
-
-**Symptom**: Bot exits immediately on startup.
-
-**Steps**:
-1. Check logs: `docker compose logs reddit-bot`
-2. Verify `config.yaml` syntax
-3. Verify environment variables are set
-4. Check for Zod validation errors in logs
-
-### Browser Login Fails
-
-**Symptom**: "Browser session expired" or login fails.
-
-**Steps**:
-1. Delete browser data: `rm -rf data/browser/`
-2. Re-run login: `npm run login`
-3. Check Reddit account is not locked
-4. Try `BROWSER_HEADLESS=false` for debugging
-
-### AI Analysis Fails
-
-**Symptom**: All messages show "AI refusal" or analysis errors.
-
-**Steps**:
-1. Verify API key is valid and has balance
-2. Check model availability on OpenRouter
-3. Try changing to a different model
-4. Review logs for specific error messages
-
-### High Error Rate
-
-**Symptom**: Many messages fail to send.
-
-**Steps**:
-1. Check rate limiting (reduce maxMessagesPerHour)
-2. Increase minDelayMs and jitterMs
-3. Check for IP bans (try different network)
-4. Review Reddit account standing
-
-### Dashboard Not Accessible
-
-**Symptom**: Cannot reach http://localhost:3000.
-
-**Steps**:
-1. Verify bot is running (`docker compose ps`)
-2. Check port is not in use: `lsof -i :3000`
-3. Verify firewall allows port 3000
-4. Check web.port in config.yaml
-
-### Database Issues
-
-**Symptom**: Database errors or corruption.
-
-**Steps**:
-1. Stop the bot
-2. Backup the database
-3. Try opening with SQLite viewer to check integrity
-4. If corrupted, restore from backup
-5. Consider enabling automatic backups
+The concise account activation instructions in [`../DOKPLOY_DEPLOY.md`](../DOKPLOY_DEPLOY.md) complement this operational guide.

docs/development.md

@@ -1,514 +1,124 @@
-# Development Guide
+# Development and testing
 
-Guide for contributing to RedditBot development.
+## Prerequisites
 
----
+- Node.js compatible with the lockfile/native `better-sqlite3` build.
+- npm.
+- Playwright system/browser dependencies for browser-backed tests or runtime work.
+- No live account is required for unit, contract, route, or dashboard tests.
 
-## Table of Contents
+NodeNext imports use `.js` suffixes even when the source file is `.ts`. Vitest globals are disabled, so tests import `describe`, `it`, `expect`, and hooks explicitly.
 
-1. [Project Structure](#project-structure)
-2. [Development Setup](#development-setup)
-3. [Coding Standards](#coding-standards)
-4. [Adding a New Service](#adding-a-new-service)
-5. [Adding a New Strategy Variant](#adding-a-new-strategy-variant)
-6. [Debugging](#debugging)
-7. [Common Tasks](#common-tasks)
-8. [Known Issues](#known-issues)
-
----
-
-## Project Structure
-
-```
-RedditBot/
-├── config.yaml              # Main configuration
-├── package.json             # Dependencies and scripts
-├── tsconfig.json            # TypeScript config
-├── Dockerfile               # Container build
-├── docker-compose.yml       # Docker Compose
-├── public/
-│   └── index.html           # Web dashboard (single file)
-├── scripts/
-│   ├── login.ts             # Manual login helper
-│   └── inspect-chat-dom.ts  # DOM inspection debug script
-└── src/
-    ├── index.ts             # Entry point / orchestrator
-    ├── config/
-    │   └── index.ts         # Config loader + Zod schema
-    ├── database/
-    │   ├── client.ts        # SQLite setup + migrations
-    │   └── repositories.ts  # Repository classes
-    ├── reddit/
-    │   └── api.ts           # Reddit API client
-    ├── ai/
-    │   └── openrouter.ts    # OpenRouter AI client
-    ├── browser/
-    │   ├── client.ts        # Playwright browser manager
-    │   ├── message-page.ts  # DM compose automation
-    │   └── media-downloader.ts # Media download
-    ├── services/
-    │   ├── monitor.ts           # Post discovery
-    │   ├── processor.ts         # Processing pipeline
-    │   ├── response-checker.ts  # Response monitoring
-    │   ├── strategy-selector.ts # A/B testing
-    │   ├── chat.ts              # Chat scraping + messaging
-    │   ├── media.ts             # Media management
-    │   ├── media-sync.ts        # Media sync scheduler
-    │   └── auto-reply.ts        # Auto-reply service
-    ├── utils/
-    │   ├── logger.ts      # Winston logger
-    │   ├── rate-limiter.ts # Rate limiting
-    │   ├── retry.ts       # Retry wrapper
-    │   └── image.ts       # Image utilities
-    └── web/
-        └── server.ts      # Express dashboard server
-```
-
----
-
-## Development Setup
-
-### 1. Install Dependencies
+## Safe setup
 
 ```bash
-npm install
+npm ci
+npm run build
+npm test
 ```
 
-### 2. Configure
+Do not start `npm run dev` merely to verify a build. The repository `.env` and persisted database can make the process live-capable. Starting the backend, importing sessions, or toggling the bot to running requires explicit authorization and a confirmed dry-run/live intent.
 
-Copy and edit `config.yaml`:
+If native SQLite bindings fail after a Node upgrade, distinguish pure TypeScript/unit results from database verification. Rebuild/install a compatible `better-sqlite3`; `--ignore-scripts` is not a valid database test environment.
 
-```bash
-cp config.yaml config.yaml.backup  # Backup existing
-# Edit config.yaml with your settings
-```
+## Commands
 
-### 3. Set Environment Variables
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | Compile server and production dashboard. |
+| `npm run build:server` | Run backend TypeScript compiler. |
+| `npm run dashboard:typecheck` | Type-check the React application. |
+| `npm run dashboard:build` | Build dashboard assets. |
+| `npm test` | Run the complete Vitest suite once. |
+| `npm run test:watch` | Watch tests during local development. |
+| `npm run test:coverage` | Run with coverage. |
+| `npm run docs:api` | Regenerate `docs/api.md`. |
+| `npm run docs:api:check` | Fail if generated API documentation is stale. |
+| `npm run mcp` | Start the stdio MCP adapter; requires an authorized running API. |
+| `npm run dev` | Start the live-capable backend watcher. |
+| `npm run dashboard:dev` | Start Vite, proxying API requests to port 3000. |
 
-```bash
-export REDDIT_USERNAME="your-username"
-export REDDIT_PASSWORD="your-password"
-export OPENROUTER_API_KEY="sk-or-v1-your-key"
-```
+## Change workflow
 
-### 4. Initial Login
+1. Read `agents.md`, `docs/README.md`, the routed topic docs, owning source, and focused tests.
+2. Inspect `git status` before editing. Preserve unrelated user changes and do not broadly stage a dirty worktree.
+3. Establish a baseline appropriate to the change. Code-changing tasks follow the repository test-first instructions; docs-only changes use documentation/link checks.
+4. Identify the source-of-truth boundary: config schema, migration, service, shared transport contract, route, or UI feature.
+5. Implement the smallest coherent behavior using dependency injection and single-purpose modules.
+6. Add behavior-focused tests for observable inputs, outputs, state transitions, and side effects.
+7. Update every affected document and regenerate API docs when the catalog changes.
+8. Run focused tests while iterating, then full required checks before publishing.
+9. Review the exact staged diff, commit only the coherent set, push, and verify branch/remote sync.
 
-```bash
-# Open browser for manual login
-npm run login
-```
+## Engineering practices
 
-### 5. Start Development Server
+### Types and validation
 
-```bash
-# Development mode (hot reload with tsx)
-npm run dev
+- No production `any`; use `unknown`, Zod, discriminated unions, or type guards.
+- Keep database/service-private types separate from transport contracts.
+- Parse at boundaries and pass trusted domain values inward.
+- Return explicit terminal/retryable/human-required results where callers must decide policy.
 
-# Production mode (compiled JS)
-npm run build && npm start
-```
+### Service design
 
-### 6. Access Dashboard
-
-Open http://localhost:3000
-
----
-
-## Coding Standards
-
-### TypeScript
-
-- **Strict mode**: No `any` types (use `unknown` with type guards)
-- **Interfaces**: Define interfaces for all data structures
-- **Null checks**: Use optional chaining (`?.`) and nullish coalescing (`??`)
-- **Async/Await**: Use async/await, not `.then()` chains
-
-```typescript
-// Good
-interface PostData {
-  id: string;
-  subreddit: string;
-  author: string;
-}
-
-async function fetchPost(id: string): Promise<PostData> {
-  const response = await api.get(`/posts/${id}`);
-  return response.data;
-}
-
-// Bad
-async function fetchPost(id: any): Promise<any> {
-  return api.get(`/posts/${id}`).then(r => r.data);
-}
-```
+- Constructor-inject external dependencies, clocks, fetchers, schedulers, and persistence seams.
+- Keep process-global coordination separate from account-scoped mutable state.
+- Prefer a small policy/service over another conditional in a composition root or route.
+- Preserve abort signals through queues, sleeps, and remote operations.
 
 ### Logging
 
-Use `winston` logger, never `console.log`:
+Use the injected Winston logger. Include stage, account context (through child loggers), post/conversation IDs, and safe rejection/retry reasons. Never serialize raw Axios/Playwright errors that may include cookies or authorization headers; extract a safe message/status. Avoid high-frequency unchanged status logs.
 
-```typescript
-// Good
-this.logger.info("Processed post {id}", { id: post.id });
-this.logger.warn("AI refusal detected", { postId: post.id });
-this.logger.error("Failed to send DM", { error: err.message });
+### Remote effects
 
-// Bad
-console.log("Processed post", post.id);
-```
+- Check dry-run at the final side-effect boundary.
+- Make retries idempotent and distinguish remote acceptance from local persistence.
+- Reserve recipients/claims before sending and release only on safe failure paths.
+- Treat 403, 404, and 429 according to their typed domain meaning rather than one generic retry.
 
-### Error Handling
+## Test layout and patterns
 
-Use try/catch with structured error handling:
+Tests live in `tests/`; dashboard tests are under `tests/dashboard/`, route/event tests under `tests/web/`, and shared contract tests under `packages/api-contracts/tests/`.
 
-```typescript
-try {
-  await this.processPost(post);
-} catch (err) {
-  this.logger.error("Post processing failed", {
-    postId: post.id,
-    error: err instanceof Error ? err.message : String(err)
-  });
-  // Don't throw - allow other posts to be processed
-}
-```
+Preferred patterns:
 
-### Service Structure
+- in-memory SQLite with real migrations/repositories;
+- fake clock/sleep/fetch functions injected into services;
+- small service fakes implementing narrow interfaces;
+- Testing Library for user-observable React behavior;
+- representative payload parsing for strict Zod contracts;
+- lifecycle/restart tests for queues, claims, and account runtimes.
 
-Follow single responsibility:
+Avoid deleting coverage to make a suite pass, assertions that pin private call order without behavioral value, ESM namespace mocking when injection is available, or tests that read the real `.env`/production data.
 
-```typescript
-class NewService {
-  constructor(
-    private config: Config,
-    private dependency: ExistingService,
-    private logger: Logger
-  ) {}
+## Verification matrix
 
-  async doSomething(input: string): Promise<Result> {
-    // Validate input
-    if (!input) {
-      throw new Error("Input is required");
-    }
+| Change | Minimum focused verification | Final verification |
+| --- | --- | --- |
+| Pure backend/service | owning Vitest files | `npm test`, `npm run build:server` |
+| Database/migration | migration + repository tests | full tests and server build |
+| API/contract | route + contract + auth tests; regenerate docs | full tests, build, `docs:api:check` |
+| Dashboard | feature tests + typecheck | full tests and full build |
+| Docker/deployment | compose/Docker tests + image build as appropriate | health, API, container, logs, and persistence after authorized deploy |
+| Documentation only | generated-doc check + internal link scan | staged diff review |
 
-    // Do work
-    const result = await this.dependency.process(input);
+If the worktree has pre-existing failures or concurrent changes, record the exact baseline and do not attribute them to your change. Never hide a failed required check behind a passing focused test.
 
-    // Return result
-    return result;
-  }
-}
-```
+## Common implementation recipes
 
-### File Organization
+### Add an endpoint
 
-- One class per file (except repositories which share one file)
-- Services in `src/services/`
-- Utilities in `src/utils/`
-- External integrations in their own folders (`src/ai/`, `src/reddit/`, `src/browser/`)
+Create or extend a focused router, validate input, add shared output contracts, register metadata in `api-catalog.ts`, add authorization/behavior tests, consume via dashboard query helpers if needed, regenerate `docs/api.md`, and update the relevant narrative doc.
 
----
+### Add persisted state
 
-## Adding a New Service
+Append a migration, add a narrow repository, wire it through the composition root/runtime, test fresh and restart/upgrade cases, and update `database.md`.
 
-### 1. Create the Service File
+### Change candidate or reply behavior
 
-```typescript
-// src/services/new-service.ts
-import { Config } from '../config';
-import { Logger } from '../utils/logger';
+Start with the durable state transition and idempotency rule. Test rejection/retry/success, process interruption, account ownership, and operator-visible reason counts. Update product, flow, service, and data docs as applicable.
 
-interface NewServiceDeps {
-  config: Config;
-  logger: Logger;
-  // other dependencies
-}
+### Add dashboard state
 
-interface Result {
-  success: boolean;
-  data?: any;
-  error?: string;
-}
-
-export class NewService {
-  constructor(private deps: NewServiceDeps) {}
-
-  async execute(input: string): Promise<Result> {
-    const { config, logger } = this.deps;
-    
-    logger.info("NewService executing", { input });
-    
-    // Implementation here
-    
-    return { success: true };
-  }
-}
-```
-
-### 2. Add to Dependencies Interface
-
-If the service needs other services, add them to the interface:
-
-```typescript
-interface NewServiceDeps {
-  config: Config;
-  logger: Logger;
-  redditApi: RedditApi;
-  openrouter: OpenRouterService;
-}
-```
-
-### 3. Wire Up in main()
-
-In `src/index.ts`, add initialization:
-
-```typescript
-const newService = new NewService({
-  config,
-  logger,
-  redditApi,
-  openrouter
-});
-
-// If it needs to run periodically:
-setInterval(() => {
-  newService.execute(someInput).catch(err => {
-    logger.error("NewService error", { error: err.message });
-  });
-}, intervalMs);
-```
-
-### 4. Add to Web Dashboard (Optional)
-
-If the service needs API endpoints, add them in `src/web/server.ts`:
-
-```typescript
-server.app.get('/api/new-service', async (req, res) => {
-  try {
-    const result = await newService.execute(req.query.input as string);
-    res.json(result);
-  } catch (err) {
-    res.status(500).json({ error: (err as Error).message });
-  }
-});
-```
-
-### 5. Update Config (If Needed)
-
-Add new configuration options to:
-- `config.yaml`
-- `src/config/index.ts` Zod schema
-- Configuration documentation
-
----
-
-## Adding a New Strategy Variant
-
-### 1. Add to config.yaml
-
-```yaml
-strategyVariants:
-  - name: "existing_variant"
-    prompt: "Existing prompt..."
-    enabled: true
-  
-  - name: "new_variant"
-    prompt: |
-      Write a friendly message that references the image content.
-      Be specific and genuine. Keep it under 2 sentences.
-    enabled: true
-```
-
-### 2. No Code Changes Needed
-
-The `StrategySelector` automatically picks up new variants from the config. The algorithm will:
-
-1. Include the new variant in random exploration
-2. Track its response rate once messages are sent
-3. Promote it to exploitation if it has good stats
-
-### 3. Monitor Performance
-
-Check performance via the dashboard or API:
-
-```bash
-curl http://localhost:3000/api/analytics/by-strategy
-```
-
----
-
-## Debugging
-
-### Browser Debugging
-
-Run with visible browser:
-
-```yaml
-# config.yaml
-browser:
-  headless: false
-```
-
-Or set environment variable:
-
-```bash
-BROWSER_HEADLESS=false npm run dev
-```
-
-### DOM Inspection
-
-Use the debug endpoint to inspect Reddit's shadow DOM:
-
-```bash
-curl -X POST http://localhost:3000/api/debug/inspect-dom
-```
-
-Or run the standalone script:
-
-```bash
-npx tsx scripts/inspect-chat-dom.ts
-```
-
-### Logging
-
-Adjust log level by modifying `src/utils/logger.ts`:
-
-```typescript
-const logger = winston.createLogger({
-  level: 'debug',  // Change from 'info' to 'debug'
-  // ...
-});
-```
-
-### Database Inspection
-
-Open the database with SQLite viewer:
-
-```bash
-# Install sqlite3 if needed
-brew install sqlite3
-
-# Open database
-sqlite3 data/reddit-bot.db
-
-# Query
-SELECT * FROM sent_messages LIMIT 5;
-```
-
-### Network Debugging
-
-Enable axios debug:
-
-```typescript
-// In src/reddit/api.ts
-import axios from 'axios';
-axios.defaults.debug = true;
-```
-
----
-
-## Common Tasks
-
-### Add a New Subreddit
-
-```yaml
-# config.yaml
-reddit:
-  subreddits:
-    - gonewild
-    - ratemyboobs
-    - new_subreddit_name  # Add here
-```
-
-### Change AI Model
-
-```yaml
-# config.yaml
-openrouter:
-  model: "new-model-name"
-  fallbackModels:
-    - "fallback-model-1"
-    - "fallback-model-2"
-```
-
-### Adjust Rate Limits
-
-```yaml
-# config.yaml
-rateLimit:
-  minDelayMs: 45000      # Increase delay
-  maxMessagesPerHour: 15  # Reduce cap
-  jitterMs: 20000        # More jitter
-```
-
-### Enable Dry Run
-
-```yaml
-# config.yaml
-dryRun: true  # Logs all actions without sending
-```
-
-Or via dashboard: `PUT /api/config` with `{"dryRun": true}`
-
-### Add Database Column
-
-```typescript
-// In src/database/client.ts
-function runMigrations(db: Database) {
-  // ... existing migrations ...
-
-  // Check if column exists
-  const tableInfo = db.prepare(`PRAGMA table_info(sent_messages)`).all();
-  const hasNewColumn = tableInfo.some((col: any) => col.name === 'new_column');
-
-  if (!hasNewColumn) {
-    db.exec("ALTER TABLE sent_messages ADD COLUMN new_column TEXT");
-  }
-}
-```
-
-### Add New API Endpoint
-
-```typescript
-// In src/web/server.ts
-import { Request, Response } from 'express';
-
-server.app.get('/api/new-endpoint', async (req: Request, res: Response) => {
-  try {
-    const result = await someService.doSomething();
-    res.json({ success: true, data: result });
-  } catch (err) {
-    res.status(500).json({ error: (err as Error).message });
-  }
-});
-```
-
----
-
-## Known Issues
-
-### Hardcoded Username in ChatService
-
-`ChatService` has `myUsername = 'Upset_Marsupial1006'` hardcoded in JavaScript evaluation scripts. This should be parameterized from config.
-
-**Fix needed**: Pass username to `page.evaluate()` calls.
-
-### Shadow DOM Fragility
-
-Reddit frequently updates their `faceplate-*` components. Shadow DOM traversal code may break without warning.
-
-**Mitigation**: Use `scripts/inspect-chat-dom.ts` to debug when selectors change.
-
-### No Test Coverage
-
-The project has no automated tests. Any changes should be manually tested.
-
-**Recommendation**: Add tests for critical paths:
-- StrategySelector algorithm
-- ChatService shadow DOM parsing
-- OpenRouterService model fallback
-
-### Single-File Dashboard
-
-The entire dashboard is in `public/index.html` (~2000+ lines). Making changes requires editing a single large file.
-
-**Recommendation**: Consider migrating to a proper frontend framework for maintainability.
+Define the shared schema first, add a typed query/mutation, keep route/filter state in the URL where useful, invalidate snapshots from relevant SSE events, and verify loading/error/stale/accessibility states.

docs/frontend-migration.md

@@ -1,102 +0,0 @@
-# React Dashboard Migration
-
-## Outcome
-
-Replace the inline dashboard in `public/index.html` with a typed, accessible React
-application without disrupting the bot worker or its Express API. Express remains
-the authenticated API, SSE, private-media, and static-asset host.
-
-The migration is complete only when the legacy dashboard can be removed without
-losing a documented capability and the full test, type-check, production-build,
-browser-acceptance, authentication, private-media, and reconnect gates pass.
-
-## Architecture
-
-- `apps/dashboard`: React, TypeScript, Vite, React Router, and TanStack Query.
-- `packages/api-contracts`: shared Zod schemas for HTTP and realtime transport.
-- `src/web`: existing Express host, gradually adapted to the shared contracts.
-- Backend service and database types stay private to the backend. Transport
-  contracts must not expose database rows as an accidental public API.
-- Server state lives in TanStack Query. Route, filter, and selection state lives
-  in URLs. Local component state is reserved for ephemeral presentation state.
-- Do not add a global client-state library until a demonstrated cross-feature
-  state requirement cannot be met by those boundaries.
-
-## Navigation
-
-The application shell provides a responsive sidebar or drawer with these routes:
-
-| Route | Responsibility |
-| --- | --- |
-| `/` | Health, metrics, timers, limits, and important recent activity |
-| `/conversations` | Searchable conversation inbox |
-| `/conversations/:id` | Conversation history, context, suggestions, and sending |
-| `/media` | Private blurred-by-default gallery and sync controls |
-| `/performance` | Trends, strategies, subreddits, and successful examples |
-| `/operations` | Domain activity, background jobs, and diagnostics |
-| `/operations/logs` | Filterable bounded realtime technical console |
-| `/settings/*` | Monitoring, limits, behaviour, AI, and access settings |
-
-The shell always surfaces bot state, dry-run state, Reddit session state,
-realtime connection state, cooldowns, active sync progress, notifications, and
-the guarded start/stop control.
-
-## Realtime model
-
-HTTP snapshots are authoritative. A typed SSE event stream updates or invalidates
-the relevant query cache. Every event has an ID, type, occurrence timestamp, and
-validated payload. The stream supports bounded replay and `Last-Event-ID` resume.
-After reconnection the client refetches authoritative snapshots to repair gaps.
-
-Required event families are bot status, message sent or failed, conversation
-updated, reply received, sync lifecycle and progress, rate-limit state, Reddit
-session state, and technical logs.
-
-Important domain events appear in a readable activity timeline. Raw logs remain
-in Operations. Toasts are reserved for user-triggered outcomes requiring timely
-feedback. Realtime disconnection never blanks cached content; it marks it stale
-and falls back to visibility-aware polling where necessary.
-
-## Feature slices
-
-1. Capture and validate existing HTTP contracts and critical legacy journeys.
-2. Add the frontend build, application shell, authentication handling, routing,
-   error boundaries, design tokens, query client, and test harness.
-3. Deliver Overview as the first production vertical slice.
-4. Add the typed realtime event core, SSE transport, reconnection, and query
-   invalidation.
-5. Migrate Conversations, including explicit suggestion and send mutations.
-6. Migrate Media, preserving authentication and blur-by-default privacy.
-7. Migrate Performance with sample sizes and low-confidence warnings.
-8. Migrate Operations, access/login, and route-backed validated Settings.
-9. Run feature parity and security audits, switch Express to the Vite output,
-   remove the legacy HTML, and update operator and deployment documentation.
-
-Each slice must be usable independently and must not require a flag-day rewrite.
-The legacy dashboard remains available until replacement behavior is proven.
-
-## Engineering gates
-
-- New behavior follows red-green-refactor with Vitest.
-- Component tests use Testing Library and test observable behavior.
-- HTTP tests use a controlled boundary such as MSW rather than mocking `fetch`
-  throughout feature tests.
-- Contract tests prove representative current responses parse and malformed
-  payloads fail.
-- Realtime tests cover ordering, replay, duplicate handling, reconnection, and
-  cache repair.
-- Browser tests cover authentication, start/stop, conversation inspection,
-  sending confirmation, sync, settings persistence, and private media.
-- Interactive controls are keyboard accessible and restore focus after dialogs.
-- No production frontend or backend code uses `any` or `console.log`.
-- Mutations display the confirmed server outcome and do not rely on optimistic
-  success for operational controls.
-- Production builds are deterministic and the Docker image serves only generated
-  frontend assets plus authenticated private content.
-
-## Cutover evidence
-
-Before deleting `public/index.html`, record evidence for every legacy capability,
-all API and SSE authentication paths, private media access, container restart and
-SSE recovery, responsive navigation, frontend type-check/build, backend build,
-the complete Vitest suite, and the critical Playwright journeys.

docs/frontend.md

@@ -0,0 +1,110 @@
+# Dashboard architecture
+
+## Stack and boundary
+
+The operator console is a React 19 + TypeScript + Vite application under `apps/dashboard`. Express serves its production build, private media, API, authentication endpoints, and SSE streams from the same origin. TanStack Query owns server state; React Router owns navigation and route-addressable state.
+
+Shared HTTP/SSE schemas live in `packages/api-contracts`. The server and client should not duplicate transport interfaces by hand.
+
+## Routes
+
+| Route | Responsibility |
+| --- | --- |
+| `/` | Health, per-account delivery/cooldown state, timers, workload, and recent activity. |
+| `/attention` | Human handoffs, delivery failures, account risks, and other actionable items. |
+| `/outreach` | Durable candidate funnel and active candidate detail. |
+| `/conversations` | Searchable account-aware conversation inbox. |
+| `/conversations/:conversationId` | Conversation history, context, suggestions, and guarded sending. |
+| `/media` | Authenticated, privacy-conscious media gallery and sync controls. |
+| `/media-library` | Upload, classify, correct, enable, preview, and delete shared exchange images. |
+| `/performance` | Mature outcome trends, strategy/subreddit results, and model usage. |
+| `/operations` | Background jobs, sync state, events, rate limits, and technical logs. |
+| `/settings` | Validated runtime configuration and account/session management. |
+
+Navigation is declared in `app/navigation.ts`; route elements are composed in `app/router.tsx`.
+
+## State model
+
+- Remote state: TanStack Query snapshots parsed by shared Zod schemas.
+- Route/filter/selection state: URL/search params when it should survive navigation or be shareable.
+- Ephemeral UI state: component/provider state, such as dialogs and notification presentation.
+- Persistent presentation state: guarded browser storage only when explicitly useful (for example notification history).
+
+Do not introduce a general global state store unless a demonstrated cross-feature need cannot fit these boundaries.
+
+## HTTP and contracts
+
+`api/request.ts` owns authenticated request mechanics and failure conversion. `api/client.ts`/`api/queries.ts` expose typed calls and query keys. Parse every response at the boundary. Strict schemas are deliberate: when the server adds a field, update the shared contract and its consumers in the same change.
+
+Mutations should display the confirmed server result. Start/stop, config, sync, import, and send actions must not use optimistic success for operational state.
+
+Account delivery state is reported per runtime (`ready`, stopped/failed/login-required, Matrix cooldown, replies prioritized, or pacing). Preserve account attribution when presenting cooldowns and failures; a blocked account does not imply every account is blocked.
+
+## Realtime model
+
+`RealtimeProvider` connects to `/api/events/stream`. Event IDs support bounded replay/resume. Each event family either updates a narrowly safe cache value or invalidates the relevant HTTP snapshot. Reconnect and stale detection live in the app layer, not individual feature pages.
+
+Rules:
+
+- HTTP remains authoritative.
+- Duplicate/replayed events must be harmless.
+- A disconnected stream marks data stale but does not blank useful cached content.
+- Invalid event payloads are contained and repaired with a snapshot refresh.
+- User-triggered outcomes may create toasts; durable/history-worthy events also appear in the notification center/activity views.
+- Raw technical logs belong in Operations, not as general user notifications.
+
+## Authentication and privacy
+
+The login form exchanges the administrator token for an HttpOnly, SameSite=Strict cookie. API clients may use Bearer tokens. Express applies auth before static dashboard assets, APIs, SSE, and `/media`; `/healthz` is the intentional public exception.
+
+Media may be private conversation content. Preserve authenticated URLs, blur/privacy defaults, explicit reveal behavior, safe new-tab links, and no token leakage into query strings or local storage. A conversation's source-post thumbnail becomes a keyboard-accessible full-screen preview only after the operator reveals it; the preview closes by button, backdrop, or Escape and restores focus to its trigger.
+
+Exchange-library uploads require an explicit consent checkbox before the raw image request is enabled. Previews remain blurred by default. The management card exposes AI tags, safety level, confidence/review state, enablement, and a two-step delete action. Its progression rail mirrors the actual nonspecific-request selection tiers rather than implying that explicit anatomy requests follow the same sequence.
+
+Conversation reply composers include a collapsed saved-image picker. It lists only server-approved assets for the latest inbound request, keeps thumbnails blurred until revealed, and requires selection plus a dedicated confirmation dialog before sending. The server remains authoritative and may reject a choice if the conversation changes before the rate-limited send executes.
+
+## Feature structure
+
+Each route is a slice under `features/<name>/` with page/route components, local styles, and feature-specific helpers. Cross-feature visual/domain components live under `components/`; application lifecycle belongs under `app/`; transport belongs under `api/`.
+
+Keep feature components focused:
+
+- pages compose queries and sections;
+- presentational components render typed props;
+- mutation hooks own cache invalidation;
+- parsing/formatting lives in small pure helpers;
+- destructive or external-message actions require explicit confirmation and accessible focus restoration.
+
+## Accessibility and presentation
+
+- All actions must be keyboard accessible and have visible focus.
+- Dialogs label purpose, trap/restore focus, and distinguish cancel from destructive confirmation.
+- Status must not rely on color alone.
+- Relative times include an exact timestamp where operationally useful.
+- Lists are explicitly sorted after filters rather than relying on backend/incidental order.
+- Loading, empty, stale, partial, and error states are distinct.
+- Show sample sizes and low-confidence context for performance metrics.
+
+## Testing
+
+Dashboard behavior is tested with Vitest, jsdom, Testing Library, and controlled HTTP boundaries. Focus on observable behavior:
+
+- representative payloads parse and malformed payloads fail;
+- route/search state and navigation;
+- loading/error/empty/stale views;
+- mutation confirmation and server read-back;
+- SSE ordering, replay, reconnect, duplicate handling, and snapshot repair;
+- authentication/private media boundaries;
+- keyboard/focus behavior for dialogs and controls.
+
+Run focused `npx vitest run tests/dashboard/<file>`, then `npm run dashboard:typecheck`, `npm run dashboard:build`, and the full suite before publishing a frontend change.
+
+## Adding a dashboard capability
+
+1. Define/extend the shared Zod contract.
+2. Make the server route return that contract and add a route test.
+3. Add a typed client/query key.
+4. Build the feature slice and observable UI states.
+5. Map relevant realtime events to cache updates/invalidations.
+6. Add component/realtime/contract coverage.
+7. Update `api.md` when the operation catalog changed and update this or the relevant product/flow document.

docs/product-and-safety.md

@@ -0,0 +1,92 @@
+# Product goals and safety boundaries
+
+## Product purpose
+
+RedditBot helps an operator discover suitable adult Reddit users who have explicitly posted in configured communities, start relevant conversations, prioritize existing replies, and learn which outreach approaches lead to genuine engagement. It is an operator-controlled system, not an unconstrained bulk messenger.
+
+The product has five connected goals:
+
+1. Find candidates from explicitly configured subreddits.
+2. Reject unsuitable candidates before expensive AI work or any send.
+3. Coordinate multiple accounts without contacting the same person repeatedly.
+4. Continue conversations only within configured, bounded automation policies.
+5. Make every material decision and outcome visible to the operator.
+
+## What good behavior looks like
+
+- Eligibility is completed before selecting a recipient: already-processed posts, recipient history, self-declared age/gender for chat posts, seller signals, content suitability, and AI safety all have explicit outcomes.
+- Existing replies take priority over new outreach. An account with actionable inbound messages is not available for a new candidate.
+- Candidate inventory follows near-term outbound capacity and the recent-post window; discovery pauses instead of accumulating an ever-older backlog when accounts cannot keep pace.
+- Discovery is global while authentication, rate limits, conversations, and content remain account-owned.
+- Recipient deduplication is case-insensitive, durable across restarts, and protected by a live reservation during sends.
+- Remote side effects are fail-closed: a send is recorded only after the chat service confirms it; interrupted reply claims reconcile against Matrix history before retrying. A queued reply refreshes Matrix immediately before sending and becomes an auditable superseded claim if a newer inbound event or terminal state appeared while it waited.
+- Dry-run prepares and records decisions but never sends.
+- Operators can see funnel stages, account state, rate limits, failures, handoffs, and recent activity rather than inferring success from a process-health check.
+
+## Candidate policy
+
+Configured subreddits have a source type:
+
+- `image`: image-led posts are downloaded and analyzed before an opener is generated.
+- `chat`: text-led posts require a parseable self-declared gender and adult age, then use the chat-opener prompt.
+
+Seller filtering combines the candidate post with Reddit profile/about and recent activity evidence. The default policy treats Telegram names and links as seller signals alongside paid-content platforms and payment prompts. The configured keyword/domain lists are policy inputs, not a substitute for the surrounding screening flow. A profile lookup failure is not itself proof that a person is a seller; network and rate-limit failures must remain distinguishable from a rejection.
+
+The system must not manufacture personal facts. Generated messages must not claim shared location or proximity, invite an in-person meeting, invent identity/history, or ignore a conversation boundary. The final outbound safety check is intentionally separate from prompt wording.
+
+## Conversation policy modes
+
+Each subreddit snapshots a policy into a conversation when automation first handles it:
+
+| Mode | Meaning |
+| --- | --- |
+| `manual` | Never auto-reply; surface a human handoff. |
+| `legacy` | At most one optional autonomous media request, counting a request already present in the opener, followed by human handoff. |
+| `r4r` | Bounded rapport-style replies with autonomous safety checks. |
+| `r4r-media` | Rapport first, one bounded media ask, then a handoff/terminal boundary. |
+
+The snapshot matters: changing configuration later must not silently rewrite the rules for an active conversation. Automation stops for seller/upsell evidence, an image received, a detected boundary, unsafe content, an exhausted turn budget, a repeated media request, or a manual policy. Short refusals are interpreted in sequence: phrases such as “I’m good” become media boundaries only when they answer a media request.
+
+## Operator exchange media
+
+The exchange library contains only operator-uploaded images. Upload requires confirmation that every depicted adult consented to storage and bot delivery. Received conversation media is account-owned evidence and can never be promoted into this shared library.
+
+The bot may continue to ask another person for an optional photo under the configured conversation policy, but it must never mention, advertise, or offer an exchange-library image proactively. A library send requires a direct or indirect inbound image request. Exact anatomy requests match the operator-reviewed tags `penis`, `chest`, `selfie`, `topless`, or `feet`; the bot does not substitute a different anatomy when a match is unavailable.
+
+Nonspecific requests broaden progressively within one conversation. The first selects a random unused SFW asset, a later request may include topless/NSFW assets, and further requests may select from the full library. An asset is never selected twice in the same conversation, including after an uncertain send. After Matrix confirms the image event, the bot asks the other person to reciprocate without pressure. Missing inventory, failed delivery, changed conversation state, or an unconfirmed reciprocal message becomes an operator handoff.
+
+Reddit candidate eligibility remains the product's adult-entry assumption; this feature adds no separate verification workflow. Existing deterministic underage disclosures and conversation boundaries still stop automation before a library send.
+
+The conversation dashboard may let an operator choose the specific library asset, but it does not waive these rules. The picker exposes only enabled, unused assets that match the latest inbound request and its current safety tier. A manual choice is revalidated after rate-limit waiting, requires explicit send confirmation, and moves the conversation to operator-owned state after a confirmed delivery.
+
+## Success and analytics
+
+Do not collapse all progress into “messages sent.” Useful states include:
+
+- candidates discovered, screened, ready, leased, retrying, rejected, expired, and sent;
+- sends awaiting a mature response window versus mature sends;
+- replies, declined/boundary/upsell outcomes, and images received;
+- model usage, fallback behavior, strategy/sample size, and account ownership.
+
+Learning examples mature only after the conversation policy is no longer active. Full recipient history is reclassified on sync; a later decline or boundary overrides earlier reciprocal activity and removes any previously promoted example.
+
+Fetched listing size is not an eligibility count. Logs and UI should quantify rejection and deferral reasons so a dry funnel can be diagnosed without guessing.
+
+## Operational authority
+
+The following require explicit user authorization because they can affect real accounts or production state:
+
+- starting or resuming bot processing;
+- sending a message or triggering a send-capable workflow;
+- importing/replacing account sessions;
+- restarting or deploying the production service;
+- changing live configuration;
+- deleting/resetting databases, volumes, media, or account state.
+
+Read-only inspection, builds, tests, and documentation work do not grant any of those permissions. If a request is only diagnostic, inspect and explain before editing or operating.
+
+## Privacy and secrets
+
+Treat these as sensitive: `.env`, Reddit cookies, exported session JSON, Matrix access tokens, dashboard/agent tokens, the SQLite database, browser profiles, conversation text, usernames, received private media, operator exchange media, and logs that may contain request metadata.
+
+Never commit or reproduce them in documentation, fixtures, logs, issue text, or tool output. Prefer redacted structural evidence. Production backups contain account and private conversation data and need the same protection as the live volume.

docs/services.md

@@ -1,854 +1,99 @@
-# Service Catalog
-
-Detailed documentation for each service in the RedditBot codebase.
-
----
-
-## Table of Contents
-
-1. [MonitorService](#monitorservice)
-2. [ProcessorService](#processorservice)
-3. [StrategySelector](#strategypicker)
-4. [ResponseChecker](#responsechecker)
-5. [ChatService](#chatservice)
-6. [MediaService](#mediaservice)
-7. [MediaSyncService](#mediasyncservice)
-8. [AutoReplyService](#autoreplyservice)
-9. [RedditApi](#redditapi)
-10. [OpenRouterService](#openrouterservice)
-11. [BrowserClient](#browserclient)
-12. [MessagePage](#messagepage)
-13. [RateLimiter](#ratelimiter)
-
----
-
-## MonitorService
-
-**File**: `src/services/monitor.ts`  
-**Lines**: 72  
-**Responsibility**: Discover new image posts across configured subreddits
-
-### Purpose
-
-Polls configured subreddits at regular intervals, discovers new image posts, filters out already-processed posts and previously-messaged users, and returns the single newest valid post for processing.
-
-### Public Methods
-
-```typescript
-class MonitorService {
-  constructor(
-    private redditApi: RedditApi,
-    private postsRepo: PostsRepository,
-    private messagesRepo: MessagesRepository,
-    private config: Config
-  )
-
-  /**
-   * Discover the next post to process.
-   * Returns null if no valid posts are available.
-   */
-  discoverNextPost(): Promise<Post | null>
-}
-```
-
-### Algorithm
-
-1. Shuffle subreddit order (randomize polling order each cycle)
-2. For each subreddit:
-   - Fetch new posts via `RedditApi.fetchPosts()`
-   - Filter: image posts only
-   - Filter: author not deleted
-   - Filter: post not already in `processed_posts`
-   - Filter: author not previously messaged (or meets re-message criteria)
-3. Return the newest valid post across all subreddits
-4. If no valid posts found, return `null`
-
-### Dependencies
-
-- `RedditApi` - Fetch posts from Reddit
-- `PostsRepository` - Check for already-processed posts
-- `MessagesRepository` - Check for previously-messaged users
-- `Config` - Subreddit list, poll interval, target gender
-
-### Error Handling
-
-- Skips subreddits that return errors (continues to next)
-- Logs errors at `warn` level
-- Returns `null` on any unrecoverable error
-
----
-
-## ProcessorService
-
-**File**: `src/services/processor.ts`  
-**Lines**: 132  
-**Responsibility**: Core processing pipeline for discovered posts
-
-### Purpose
-
-Orchestrates the full processing pipeline for a single discovered post: image download, gender detection, AI analysis, strategy selection, message generation, and DM sending.
-
-### Public Methods
-
-```typescript
-class ProcessorService {
-  constructor(
-    private config: Config,
-    private redditApi: RedditApi,
-    private openrouter: OpenRouterService,
-    private strategySelector: StrategySelector,
-    private messageSender: MessagePage,
-    private postsRepo: PostsRepository,
-    private messagesRepo: MessagesRepository,
-    private successfulRepo: SuccessfulMessagesRepository,
-    private logger: Logger
-  )
-
-  /**
-   * Process a single discovered post through the full pipeline.
-   */
-  processPost(post: Post): Promise<void>
-}
-```
-
-### Pipeline Steps
-
-```
-1. Download image
-   └─► ImageService.downloadImage(url)
-   └─► Validate MIME type (image/jpeg, image/png, image/webp)
-   └─► Validate file size
-   └─► Convert to base64
-
-2. Quick gender detection (cost-saving pre-filter)
-   └─► OpenRouter.detectGenderOnly(image)
-   └─► Skip if gender doesn't match targetGender
-
-3. Select A/B strategy variant
-   └─► StrategySelector.selectStrategy(subreddit, author)
-
-4. Full AI analysis
-   └─► OpenRouter.analyzeImage(image)
-   └─► Detect gender, describe image
-   └─► Handle refusal (mark post, try next)
-
-5. Generate message
-   └─► OpenRouter.generateMessage(analysis, title, examples, strategy)
-   └─► Few-shot examples from SuccessfulMessagesRepository
-
-6. Send DM
-   └─► MessagePage.sendDM(author, "Stunning", message)
-   └─► Handle failure (log, don't mark as sent)
-
-7. Record in database
-   └─► Mark post as processed
-   └─► Mark message_sent = 1 if successful
-   └─► Store generated_message for reference
-```
-
-### Error Handling
-
-- AI refusal: Post is marked as processed with error, skipped
-- Image download failure: Post is marked with error, skipped
-- DM send failure: Post is marked as not sent, logged
-- All errors logged with context (post ID, subreddit, author)
-
-### Cost Optimization
-
-- Quick gender detection costs less than full analysis
-- Non-matching genders are skipped before expensive analysis
-- AI refusal detection prevents wasted tokens on rejected prompts
-
----
-
-## StrategySelector
-
-**File**: `src/services/strategy-selector.ts`  
-**Lines**: 101  
-**Responsibility**: A/B testing with explore/exploit algorithm
-
-### Purpose
-
-Selects message variants (strategies) for each post using an explore/exploit algorithm based on historical response rates. Optimizes for maximum response rate over time while continuing to explore under-tested variants.
-
-### Public Methods
-
-```typescript
-class StrategySelector {
-  constructor(
-    private config: Config,
-    private messagesRepo: MessagesRepository
-  )
-
-  /**
-   * Select the best strategy variant for a given subreddit/author.
-   */
-  selectStrategy(subreddit: string, author: string): string
-}
-```
-
-### Algorithm
-
-1. **Get strategy stats** from `MessagesRepository`:
-   - Response count per variant
-   - Sent count per variant
-   - Response rate per variant
-
-2. **Apply minimum sample threshold**:
-   - If a variant has fewer than `minSamples` sends, treat it as untested
-   - Untested variants are excluded from exploitation
-
-3. **Explore vs Exploit decision**:
-   - With probability `explorationRate`, select a random variant (explore)
-   - Otherwise, select the variant with the highest response rate (exploit)
-
-4. **Fallback**:
-   - If no variants have enough data, select randomly from enabled variants
-
-### Configuration
-
-```yaml
-strategyVariants:
-  - name: "variant_a"
-    prompt: "Compliment-based message..."
-    enabled: true
-  - name: "variant_b"
-    prompt: "Question-based message..."
-    enabled: true
-```
-
-### Dependencies
-
-- `Config` - Strategy variants, exploration rate, min samples
-- `MessagesRepository` - Response rate statistics
-
----
-
-## ResponseChecker
-
-**File**: `src/services/response-checker.ts`  
-**Lines**: 179  
-**Responsibility**: Monitor inbox for user replies
-
-### Purpose
-
-Background service that navigates the Reddit inbox via Playwright, identifies responses to bot-sent messages, updates the database, and stores successful message/response pairs for few-shot learning.
-
-### Public Methods
-
-```typescript
-class ResponseCheckerService {
-  constructor(
-    private browser: BrowserClient,
-    private messagesRepo: MessagesRepository,
-    private successfulRepo: SuccessfulMessagesRepository,
-    private logger: Logger
-  )
-
-  /**
-   * Check inbox for responses to sent messages.
-   */
-  checkResponses(): Promise<void>
-}
-```
-
-### Algorithm
-
-1. Navigate to `/message/inbox` via Playwright
-2. Parse inbox items (messages, conversations)
-3. For each response item:
-   - Extract recipient username and message text
-   - Match to `sent_messages` by recipient + timestamp proximity
-   - Update `got_response = 1` and `response_checked_at`
-   - Store the message/response pair in `successful_messages`
-4. Update strategy statistics (response rates)
-
-### Dependencies
-
-- `BrowserClient` - Playwright browser context
-- `MessagesRepository` - Update response flags
-- `SuccessfulMessagesRepository` - Store learning pairs
-- `Logger` - Activity logging
-
----
-
-## ChatService
-
-**File**: `src/services/chat.ts`  
-**Lines**: 1123+  
-**Responsibility**: Reddit chat scraping, messaging, and conversation management
-
-### Purpose
-
-The most complex service in the codebase. Manages Reddit chat interactions including scraping active conversations, loading conversation history, sending messages with human-like delays, detecting upsell/spam, and managing conversation caches.
-
-### Public Methods
-
-```typescript
-class ChatService {
-  constructor(
-    private browser: BrowserClient,
-    private config: Config,
-    private logger: Logger
-  )
-
-  /** Fetch active conversations from Reddit */
-  fetchChats(): Promise<ChatSummary[]>
-
-  /** Load full conversation history */
-  loadConversation(chatId: string): Promise<Conversation>
-
-  /** Send a message in a conversation */
-  sendMessage(chatId: string, text: string): Promise<boolean>
-
-  /** Get cached conversations */
-  getCachedConversations(): Conversation[]
-
-  /** Check for new messages in conversations */
-  checkForUpdates(): Promise<Conversation[]>
-
-  /** Detect upsell/spam in a message */
-  detectUpsell(message: string): boolean
-}
-```
-
-### Shadow DOM Handling
-
-Reddit uses custom `faceplate-*` web components with shadow DOM. Standard CSS selectors cannot pierce these boundaries. The service uses JavaScript injection via `page.evaluate()`:
-
-```javascript
-// Traverse shadow roots to find chat elements
-function traverseShadowRoots(root) {
-  const elements = root.querySelectorAll('.some-class');
-  const shadowChildren = root.querySelectorAll('*::shadow, ::deep');
-  // ... recursive traversal
-}
-```
-
-### Conversation Cache
-
-Conversations are cached in two layers:
-
-1. **In-memory**: Fast access for active conversations
-2. **Disk JSON**: Persistence across restarts at `data/chats/`
-
-Cache structure:
-```json
-{
-  "chatId": "abc123",
-  "participants": ["user1", "bot"],
-  "messages": [
-    { "author": "user1", "text": "Hey!", "timestamp": 1234567890 }
-  ],
-  "lastUpdated": 1234567890,
-  "hasNewMessages": false
-}
-```
-
-### Human-Like Messaging
-
-Messages are sent with:
-- Typing delay simulation (random delay before "typing" starts)
-- Variable typing speed
-- Random delays between messages
-- Delivery verification
-
-### Known Issues
-
-- **Hardcoded username**: `myUsername = 'Upset_Marsupial1006'` is hardcoded in JS evaluation scripts. Should be parameterized from `Config`.
-- **Size**: 1123+ lines suggests this should be split into smaller services.
-
-### Dependencies
-
-- `BrowserClient` - Playwright browser context
-- `Config` - Rate limits, username (should be), check intervals
-- `Logger` - Activity logging
-
----
-
-## MediaService
-
-**File**: `src/services/media.ts`  
-**Lines**: 254  
-**Responsibility**: Media download, caching, and indexing
-
-### Purpose
-
-Downloads images from chat conversations, resolves Matrix blurred thumbnails to full resolution, stores files locally, and maintains a deduplicated index.
-
-### Public Methods
-
-```typescript
-class MediaService {
-  constructor(
-    private config: Config,
-    private browser: BrowserClient,
-    private logger: Logger
-  )
-
-  /** Download media from a conversation */
-  downloadMedia(chatId: string): Promise<string[]>
-
-  /** Get media index */
-  getIndex(): MediaIndex
-
-  /** Get a specific media file path */
-  getPath(hash: string): string | null
-}
-```
-
-### Deduplication
-
-Files are deduplicated using SHA-1 hashing:
-
-```
-SHA-1(image_bytes) → data/media/{hash}.{ext}
-```
-
-The index maps hashes to file paths:
-```json
-{
-  "abc123def456": "abc123def456.jpg",
-  "789xyz012abc": "789xyz012abc.png"
-}
-```
-
-### Matrix Thumbnail Resolution
-
-Reddit's Matrix system uses blurred placeholder thumbnails. The service resolves these to full resolution by:
-
-1. Detecting Matrix thumbnail URLs
-2. Extracting the full-resolution URL from the response
-3. Downloading the full-resolution image
-
-### Dependencies
-
-- `Config` - Media directory path
-- `BrowserClient` - Playwright for Matrix resolution
-- `Logger` - Download activity
-
----
-
-## MediaSyncService
-
-**File**: `src/services/media-sync.ts`  
-**Lines**: 119  
-**Responsibility**: Periodic background media synchronization
-
-### Purpose
-
-Runs periodic background syncs to download media from chat conversations. Supports both incremental (top 10 chats) and full (all conversations) sync modes.
-
-### Public Methods
-
-```typescript
-class MediaSyncService {
-  constructor(
-    private config: Config,
-    private mediaService: MediaService,
-    private chatService: ChatService,
-    private logger: Logger
-  )
-
-  /** Start periodic sync */
-  start(): void
-
-  /** Stop periodic sync */
-  stop(): void
-
-  /** Trigger incremental sync */
-  syncIncremental(): Promise<void>
-
-  /** Trigger full sync */
-  syncFull(): Promise<void>
-
-  /** Get sync status */
-  getStatus(): SyncStatus
-}
-```
-
-### Sync Modes
-
-| Mode | Description | Use Case |
-|---|---|---|
-| Incremental | Top 10 most recent conversations | Regular background sync |
-| Full | All conversations | Initial setup, catch-up |
-
-### Dependencies
-
-- `Config` - Sync interval, enabled flag
-- `MediaService` - Actual download logic
-- `ChatService` - Conversation list
-- `Logger` - Sync progress
-
----
-
-## AutoReplyService
-
-**File**: `src/services/auto-reply.ts`  
-**Lines**: 199  
-**Responsibility**: Automated reply to chat conversations
-
-### Purpose
-
-Monitors cached conversations for unread messages, detects upsell/spam, generates AI reply suggestions, and either auto-sends or marks as pending for manual approval.
-
-### Public Methods
-
-```typescript
-class AutoReplyService {
-  constructor(
-    private config: Config,
-    private chatService: ChatService,
-    private openrouter: OpenRouterService,
-    private logger: Logger
-  )
-
-  /** Start auto-reply checking */
-  start(): void
-
-  /** Stop auto-reply checking */
-  stop(): void
-
-  /** Check for unread messages and generate replies */
-  checkAndReply(): Promise<void>
-}
-```
-
-### Workflow
-
-```
-1. Check cached conversations for unread messages
-   │
-   ├─► Skip if no new messages
-   │
-   ├─► Detect upsell/spam keywords
-   │   └─► Flag conversation, skip reply
-   │
-   ├─► Generate AI reply suggestion
-   │   └─► OpenRouter.generateReply(conversation history)
-   │
-   ├─► If autoSend: send reply immediately
-   │   └─► ChatService.sendMessage()
-   │
-   └─► If !autoSend: mark as pending
-       └─► Dashboard shows pending replies for approval
-```
-
-### Dependencies
-
-- `Config` - Enabled flag, autoSend flag, check interval
-- `ChatService` - Conversation access, message sending
-- `OpenRouterService` - Reply generation
-- `Logger` - Activity logging
-
----
-
-## RedditApi
-
-**File**: `src/reddit/api.ts`  
-**Lines**: 233  
-**Responsibility**: Reddit API client
-
-### Purpose
-
-Axios-based client for interacting with Reddit's public API. Handles post fetching, user profile checking, and authenticated requests using Playwright browser cookies.
-
-### Public Methods
-
-```typescript
-class RedditApi {
-  constructor(
-    private browser: BrowserClient,
-    private logger: Logger
-  )
-
-  /** Fetch new posts from a subreddit */
-  fetchPosts(subreddit: string, limit?: number): Promise<Post[]>
-
-  /** Check if a user is a seller/spam */
-  checkUserProfile(username: string): Promise<UserProfile>
-
-  /** Make authenticated request using browser cookies */
-  authenticatedRequest(url: string): Promise<any>
-}
-```
-
-### Image URL Resolution
-
-Fallback chain for extracting image URLs from post data:
-
-```
-1. post.preview.reddits[0].url (Reddit CDN preview)
-2. post.url (i.redd.it direct)
-3. post.thumbnail (if not self/spam)
-4. Scan post.selftext for imgur/image links
-```
-
-### Seller/Spam Detection
-
-Checks user profile for keywords:
-- "seller"
-- "onlyfans"
-- "link in bio"
-- Other configured `sellerKeywords`
-
-### Dependencies
-
-- `BrowserClient` - Browser cookies for authentication
-- `Logger` - Request logging
-
----
-
-## OpenRouterService
-
-**File**: `src/ai/openrouter.ts`  
-**Lines**: 307  
-**Responsibility**: OpenRouter AI client
-
-### Purpose
-
-Client for the OpenRouter API (OpenAI-compatible SDK). Provides image analysis, message generation, reply suggestions, and upsell detection.
-
-### Public Methods
-
-```typescript
-class OpenRouterService {
-  constructor(private config: Config, private logger: Logger)
-
-  /** Full image analysis with model fallback */
-  analyzeImage(imageBase64: string): Promise<ImageAnalysis>
-
-  /** Quick gender detection (cost-saving) */
-  detectGenderOnly(imageBase64: string): Promise<string>
-
-  /** Generate DM message */
-  generateMessage(
-    imageAnalysis: ImageAnalysis,
-    postTitle: string,
-    strategy: string
-  ): Promise<string>
-
-  /** Generate chat reply */
-  generateReply(conversationHistory: Message[]): Promise<string>
-
-  /** Detect upsell/spam keywords */
-  detectUpsell(message: string): boolean
-}
-```
-
-### Model Fallback Chain
-
-```
-Primary model (config.openrouter.model)
-  │
-  └─► If refusal detected:
-       │
-       └─► Try each fallback model (config.openrouter.fallbackModels)
-            │
-            └─► If all fail: throw error
-```
-
-### Refusal Detection
-
-Heuristic patterns to detect when AI models refuse to process prompts:
-
-```typescript
-const refusalPatterns = [
-  /cannot.*analyze/i,
-  /unable.*process/i,
-  /against.*policy/i,
-  /cannot.*view/i,
-  // ...
-];
-```
-
-### Few-Shot Learning
-
-`generateMessage()` retrieves successful message/response pairs from the database and includes them as examples in the prompt:
-
-```
-"Here are examples of messages that got responses:
- - Example 1: {original_message} → {response_snippet}
- - Example 2: ...
- 
-Generate a similar message for this image..."
-```
-
-### Dependencies
-
-- `Config` - API key, model selection, prompts
-- `MessagesRepository` - Successful examples for few-shot learning
-
----
-
-## BrowserClient
-
-**File**: `src/browser/client.ts`  
-**Lines**: 302  
-**Responsibility**: Playwright persistent context manager
-
-### Purpose
-
-Manages the Playwright browser session with persistent cookies/storage. Handles automated login, session verification, and 2FA/captcha detection.
-
-### Public Methods
-
-```typescript
-class BrowserClient {
-  constructor(private config: Config, private logger: Logger)
-
-  /** Initialize browser context */
-  initialize(): Promise<void>
-
-  /** Verify browser session is active */
-  verifySession(): Promise<boolean>
-
-  /** Perform automated login */
-  login(): Promise<void>
-
-  /** Get page context for operations */
-  getPage(): Promise<Page>
-
-  /** Close browser */
-  close(): Promise<void>
-}
-```
-
-### Login Flow
-
-```
-1. Navigate to Reddit login page
-2. Fill username and password
-3. Submit form
-4. Check for 2FA prompt
-   └─► If present: wait for manual input (with timeout)
-5. Check for captcha
-   └─► If present: log warning, wait
-6. Verify login success:
-   └─► Check for user menu indicator
-   └─► Check for profile avatar
-   └─► Fallback: API request to /api/me
-7. Save cookies to persistent directory
-8. On failure: capture debug screenshot
-```
-
-### Session Persistence
-
-- Cookies and storage are saved to `config.browser.userDataDir`
-- Subsequent launches restore the session automatically
-- Session expires when Reddit cookies expire (requires re-login)
-
-### Dependencies
-
-- `Config` - Credentials, headless mode, user data dir
-- `Logger` - Login progress, errors
-
----
-
-## MessagePage
-
-**File**: `src/browser/message-page.ts`  
-**Lines**: 560  
-**Responsibility**: Reddit DM compose page automation
-
-### Purpose
-
-Automates the Reddit DM compose page: filling recipient/subject/body fields, handling shadow DOM components, submitting messages, and verifying success.
-
-### Public Methods
-
-```typescript
-class MessagePage {
-  constructor(
-    private browser: BrowserClient,
-    private config: Config,
-    private logger: Logger
-  )
-
-  /** Send a DM to a recipient */
-  sendDM(recipient: string, subject: string, body: string): Promise<boolean>
-
-  /** Check if recipient field shows an error */
-  hasRecipientError(page: Page): Promise<boolean>
-}
-```
-
-### Shadow DOM Handling
-
-Reddit's compose form uses `faceplate-*` web components:
-
-```javascript
-// Fill shadow DOM input fields
-page.evaluate(({ selector, value }) => {
-  const shadowInput = document.querySelector(`${selector} input`);
-  if (shadowInput) {
-    shadowInput.value = value;
-    shadowInput.dispatchEvent(new Event('input', { bubbles: true }));
-  }
-}, { selector: 'faceplate-textarea[name="body"]', value: body });
-```
-
-### Dry Run Mode
-
-When `config.dryRun` is enabled:
-- All fields are filled as normal
-- Submit button is NOT clicked
-- Message is logged but not sent
-- Returns `true` (simulates success)
-
-### Dependencies
-
-- `BrowserClient` - Playwright page access
-- `Config` - Dry run mode
-- `Logger` - Send activity
-
----
-
-## RateLimiter
-
-**File**: `src/utils/rate-limiter.ts`  
-**Lines**: 114  
-**Responsibility**: Token-bucket rate limiting
-
-### Purpose
-
-Enforces rate limits on bot actions (primarily message sending) to avoid detection and bans. Uses a combination of minimum delay, random jitter, and hourly caps.
-
-### Public Methods
-
-```typescript
-class RateLimiter {
-  constructor(config: RateLimitConfig)
-
-  /** Wait until a slot is available */
-  waitForSlot(): Promise<void>
-
-  /** Get remaining time until next slot */
-  getTimeUntilSlot(): number
-
-  /** Get current hourly count */
-  getHourlyCount(): number
-
-  /** Reset hourly counter */
-  resetHourlyCounter(): void
-}
-```
-
-### Rate Limiting Strategy
-
-```
-1. Check hourly cap:
-   └─► If maxMessagesPerHour reached: wait until hour rolls over
-
-2. Enforce minimum delay:
-   └─► lastActionTime + minDelayMs + random(0, jitterMs)
-
-3. Track action timestamp
-4. Increment hourly counter
-```
-
-### Dependencies
-
-- `Config` - Rate limit settings
-- `p-queue` - Concurrency control
+# Service and module map
+
+This is an ownership map, not an API dump. Read the owning implementation and tests before changing behavior.
+
+## Lifecycle and account ownership
+
+| Module | Owns | Important constraints |
+| --- | --- | --- |
+| `src/bootstrap.ts` | Dependency composition and startup wiring | Keep business policy in services; preserve initialization order and test seams. |
+| `src/main-loop.ts` | Shared discovery/screening/dispatch workers and legacy loop | Loops are abortable; queue transitions and shutdown must remain recoverable. |
+| `services/reddit-account-runtime.ts` | Immutable account runtime/factory/manager lifecycle | Same-account operations serialize; session refresh replaces one runtime. |
+| `services/reddit-account-runtime-builder.ts` | Concrete account dependency graph and account loop | Account-specific browser, Matrix, repos, limiter, automation, chat, and media live here. |
+| `services/reddit-accounts.ts` | Account import/activation orchestration | Verification must bind Reddit cookies and Matrix identity before activation. |
+| `services/account-auth-context.ts` | Current verified identity snapshot | Account work pauses unless both sides authenticate. |
+| `services/session-bound-runtime.ts` | Legacy auth-bound background lifecycle | Prevents background work while logged out. |
+
+## Discovery, preparation, and delivery
+
+| Module | Owns | Important constraints |
+| --- | --- | --- |
+| `services/monitor.ts` | Subreddit ordering, candidate fetching, age/gender/seller screening, rejection summaries | Cheap checks first; preserve exact rejection/deferred counts; listing 404 disables the subreddit. |
+| `reddit/api.ts` | Reddit JSON calls, post parsing, seller/profile evidence, username resolution, error types | All reads must use the coordinator; redact error metadata. |
+| `reddit/request-coordinator.ts` | Process-wide Reddit request spacing and cooldown | Space failed requests too; 429 cooldown is global. |
+| `services/processor.ts` | Source-specific AI preparation and outbound safety | Returns prepared or explicit skip; performs no remote chat send. |
+| `services/strategy-selector.ts` | Weighted explore/exploit selection and experiment metadata | Separate image/chat strategy sections; respect mature response window and sample floor. |
+| `services/recipient-deduplicator.ts` | Global recipient history plus live reservation | Case-insensitive; release failures, commit successes, recover stale claims. |
+| `utils/rate-limiter.ts` | Per-account send spacing/hour limits/jitter | Increment only for confirmed sends; reply priority may use the same limiter. |
+| `database/candidate-queue-repository.ts` | Durable candidate state machine, leases, retries, counts | Mutations require the expected worker lease; recover expired/interrupted work. |
+
+## Conversation, chat, and media
+
+| Module | Owns | Important constraints |
+| --- | --- | --- |
+| `services/chat/service.ts` | Matrix conversation sync, cache updates, starts/replies, scoped cooldowns | Room-creation limits pause new outreach without blocking existing-room replies; Matrix acceptance and UI visibility are distinct. |
+| `services/chat/matrix/client.ts` | Matrix HTTP protocol and error classification | Authentication/rate-limit errors need typed handling. |
+| `services/chat/cache.ts` | Account-scoped cached conversations and sync state | SQLite is durable; do not share caches across accounts. |
+| `services/chat/matrix/username-resolver.ts` | Matrix/Reddit identity mapping | Preserve unresolved internal IDs without leaking them in operator text. |
+| `services/chat/matrix/token-refresher.ts` | Explicit refresh-unavailable behavior | New credentials come from verified extension dumps, not token sniffing. |
+| `services/conversation-automation.ts` | Reply-first policy, claims, retries, send-time refresh, handoffs, turn budgets | Snapshot policy; claim before send; supersede stale queued work; reconcile pending claims; fail closed. |
+| `services/conversation-state.ts` | Pure conversation parsing/state/safety helpers | Conversation text is untrusted data; keep prompt boundaries explicit. |
+| `services/conversation-boundaries.ts` | Sequence-aware media requests, refusals, and full-stop detection | Short ambiguous replies become boundaries only in the matching request context. |
+| `services/outbound-message-safety.ts` | Final no-proximity/no-meeting rule | This is defense in depth beyond prompts. |
+| `services/conversation-outcome*.ts` | Response outcome classification/recording | Keep analytics attribution account/message scoped. |
+| `services/response-checker.ts` | Inbox/performance response checks and successful examples | Non-overlapping; do not confuse chat sync with outcome maturity. |
+| `services/media.ts` | Download, deduplicate, index, and list private media | Preserve account ownership and authenticated serving. |
+| `services/media-sync.ts` | Periodic authenticated media sync | Stop while auth is unavailable and on runtime shutdown. |
+| `services/media-library.ts` | Shared operator uploads, image validation/re-encoding, classification state, and private files | Require consent confirmation; received media never enters this store. |
+| `services/media-library-exchange.ts` | Inbound request detection, progressive selection, reservation, and image-first exchange | Never offer proactively; exact tags do not substitute; no asset reuse per conversation. |
+| `database/media-library-repository.ts` | Shared asset metadata and durable account/conversation send audit | Reserve before remote send; uncertain sends stay consumed. |
+
+## Persistence
+
+| Module | Owns |
+| --- | --- |
+| `database/client.ts` | Database open settings and ordered migrations. |
+| `database/repositories.ts` | Posts, messages, successes, activity, outbox, states, claims, outcomes, users, recipient history. |
+| `database/account-repositories.ts` | Verified account records, conversations, sync cursors, and media content. |
+| `database/ai-usage-repository.ts` | Model request/cost/reliability records. |
+| `database/legacy-content-import.ts` | One-time ownership of legacy file-backed chat/media data. |
+| `config/persistence.ts` | Secret-free application configuration in SQLite. |
+
+Repositories should expose domain operations rather than raw SQL to callers. Multi-step state transitions belong in SQLite transactions when partial completion would break invariants.
+
+## Web and agent surfaces
+
+| Module | Owns |
+| --- | --- |
+| `web/server.ts` | Express lifecycle, middleware order, route registration, static dashboard/media. |
+| `web/auth.ts` | Dashboard session and bearer-token authorization. |
+| `web/context.ts` | Narrow route dependency container. |
+| `web/routes/*.ts` | Focused endpoint families. |
+| `web/api-catalog.ts` | Operation metadata, OpenAPI, and capability discovery. |
+| `web/agent-job-manager.ts` | Bounded async sync jobs and job status. |
+| `web/events/*` | Typed event publication, replay, subscriptions, and Express SSE. |
+| `web/log-broadcaster.ts` | Recent logs plus legacy/typed stream adapters. |
+| `mcp/api-client.ts`, `mcp/server.ts` | HTTP-backed stdio MCP tools. |
+
+Authorization is semantic, not just authentication: read and control agent tokens intentionally cannot import sessions, send messages, activate accounts, mutate legacy config, or use debug routes.
+
+## Frontend
+
+| Area | Owns |
+| --- | --- |
+| `apps/dashboard/src/app/` | Shell, routing, providers, auth status, notifications, realtime repair. |
+| `apps/dashboard/src/api/` | HTTP client, schema parsing, query keys/hooks. |
+| `apps/dashboard/src/features/` | Route-level feature slices. |
+| `apps/dashboard/src/components/` | Reusable domain-aware UI elements. |
+| `packages/api-contracts/` | Shared strict transport schemas and inferred types. |
+
+## Utility boundaries
+
+- `utils/logger.ts`: Winston creation, child context, and attachable sinks. No production `console.log`.
+- `utils/retry.ts`: bounded retry behavior for operations that are safe to repeat.
+- `utils/image.ts`: download/MIME/size helpers.
+- `utils/gender-tag.ts`: deterministic self-declared tag parsing.
+- `utils/fetch-with-timeout.ts`: abortable HTTP timeout wrapper.
+- `utils/json-safe.ts`: safe serialization for log/event data.
+
+When a module starts owning two independent reasons to change, extract a narrow collaborator and inject it. Do not solve size alone by moving methods into a generic utility file.

extensions/reddit-session-exporter/README.md

@@ -0,0 +1,17 @@
+# RedditBot Session Exporter
+
+This local Chrome extension exports `reddit.com` cookies and the current Reddit Chat Matrix credential into one JSON file for the self-hosted dashboard's **Import Reddit session** control. The file is equivalent to a login credential: do not share it, commit it, or send it to anyone.
+
+## Install and use
+
+1. In Chrome, open `chrome://extensions`, enable **Developer mode**, then choose **Load unpacked** and select this folder.
+   If it was already loaded, click its **Reload** button after updating these files so Chrome starts the new service worker.
+2. Sign in to Reddit in the same Chrome profile.
+3. Open [Reddit Chat](https://chat.reddit.com/) and wait for it to finish loading. Do not use `www.reddit.com/chat/`: its Matrix bridge can return HTTP 405. The extension badge changes to `OK` when it captures the Matrix credential. If no credential has been captured yet, clicking the extension opens the correct Chat host automatically.
+4. Click the **RedditBot Session Exporter** toolbar icon and save `redditbot-session.json`.
+5. In RedditBot Dashboard > Settings > Access, choose **Import Reddit session** and select the exported file.
+6. Delete the downloaded JSON file once the dashboard confirms that the session is authenticated.
+
+The extension observes only requests to Reddit's Matrix homeservers, verifies the captured token with Matrix `whoami`, reads Reddit cookies, and saves the combined export locally. It does not send the dump to any server; you upload it directly to your RedditBot dashboard.
+
+Before downloading, the extension independently resolves the current identity through the open `www.reddit.com` tab and refuses the export unless its `t2` account ID matches Matrix `whoami`. If you switch accounts, reload Reddit Chat so the extension captures that account's current Matrix token.

extensions/reddit-session-exporter/manifest.json

@@ -0,0 +1,15 @@
+{
+  "manifest_version": 3,
+  "name": "RedditBot Session Exporter",
+  "version": "1.1.1",
+  "description": "Exports Reddit cookies and Reddit Chat credentials for a self-hosted RedditBot dashboard.",
+  "permissions": ["cookies", "downloads", "scripting", "storage", "webRequest"],
+  "host_permissions": [
+    "https://reddit.com/*",
+    "https://*.reddit.com/*",
+    "https://matrix.redditspace.com/*",
+    "https://matrix.reddit.com/*"
+  ],
+  "action": { "default_title": "Export RedditBot session" },
+  "background": { "service_worker": "service-worker.js", "type": "module" }
+}

extensions/reddit-session-exporter/service-worker.js

@@ -0,0 +1,114 @@
+import {
+  assertMatchingSessionIdentity,
+  createSessionExportDownload,
+  REDDIT_CHAT_URL,
+} from './session-export.js';
+
+const MATRIX_URLS = [
+  'https://matrix.redditspace.com/*',
+  'https://matrix.reddit.com/*',
+];
+
+chrome.webRequest.onBeforeSendHeaders.addListener(
+  async (details) => {
+    const authorization = details.requestHeaders?.find(
+      (header) => header.name.toLowerCase() === 'authorization',
+    )?.value;
+    if (!authorization?.toLowerCase().startsWith('bearer ')) return;
+
+    const url = new URL(details.url);
+    await chrome.storage.local.set({
+      matrixCapture: {
+        homeserver: `${url.protocol}//${url.host}`,
+        accessToken: authorization.slice('bearer '.length).trim(),
+        capturedAt: Date.now(),
+      },
+    });
+    await chrome.action.setBadgeText({ text: 'OK' });
+    await chrome.action.setBadgeBackgroundColor({ color: '#198754' });
+    await chrome.action.setTitle({ title: 'Reddit Chat token captured. Click to export.' });
+  },
+  { urls: MATRIX_URLS },
+  ['requestHeaders', 'extraHeaders'],
+);
+
+async function getRedditIdentity() {
+  const tabs = await chrome.tabs.query({
+    url: ['https://reddit.com/*', 'https://www.reddit.com/*'],
+  });
+  const tab = tabs.find((candidate) => candidate.active) ?? tabs[0];
+  if (tab?.id === undefined) {
+    throw new Error('Keep a signed-in www.reddit.com tab open while exporting.');
+  }
+
+  const [{ result } = {}] = await chrome.scripting.executeScript({
+    target: { tabId: tab.id },
+    world: 'MAIN',
+    func: async () => {
+      try {
+        const response = await fetch('https://www.reddit.com/api/me.json', {
+          credentials: 'include',
+          cache: 'no-store',
+        });
+        if (!response.ok) return { error: 'Reddit cookies did not authenticate. Sign in and try again.' };
+        return { payload: await response.json() };
+      } catch {
+        return { error: 'Could not read the current Reddit account. Reload Reddit and try again.' };
+      }
+    },
+  });
+
+  if (result?.error) throw new Error(result.error);
+  const payload = result?.payload;
+  const account = payload?.data ?? payload;
+  if (!account?.name || !account?.id) {
+    throw new Error('Reddit did not return an authenticated account identity.');
+  }
+  return { username: account.name, accountId: account.id };
+}
+
+async function showError(message) {
+  await chrome.action.setBadgeText({ text: 'ERR' });
+  await chrome.action.setBadgeBackgroundColor({ color: '#dc3545' });
+  await chrome.action.setTitle({ title: `RedditBot export not ready: ${message}` });
+}
+
+chrome.action.onClicked.addListener(async () => {
+  try {
+    const cookies = await chrome.cookies.getAll({ domain: 'reddit.com' });
+    const { matrixCapture } = await chrome.storage.local.get('matrixCapture');
+    if (!matrixCapture) {
+      await chrome.tabs.create({ url: REDDIT_CHAT_URL });
+      await chrome.action.setBadgeText({ text: '...' });
+      await chrome.action.setBadgeBackgroundColor({ color: '#6c757d' });
+      await chrome.action.setTitle({
+        title: 'Reddit Chat opened. Wait for the badge to show OK, then click again.',
+      });
+      return;
+    }
+
+    const whoami = await fetch(`${matrixCapture.homeserver}/_matrix/client/v3/account/whoami`, {
+      headers: { Authorization: `Bearer ${matrixCapture.accessToken}` },
+    });
+    if (!whoami.ok) throw new Error('The captured Reddit Chat token has expired. Reload Reddit Chat and try again.');
+    const identity = await whoami.json();
+    if (!identity?.user_id) throw new Error('Reddit Chat did not return an account identity.');
+
+    const redditIdentity = await getRedditIdentity();
+    try {
+      assertMatchingSessionIdentity(redditIdentity, identity.user_id);
+    } catch (error) {
+      await chrome.storage.local.remove('matrixCapture');
+      throw error;
+    }
+
+    await chrome.downloads.download({
+      ...createSessionExportDownload(cookies, { ...matrixCapture, userId: identity.user_id }),
+      saveAs: true,
+    });
+    await chrome.action.setBadgeText({ text: 'OK' });
+    await chrome.action.setTitle({ title: 'RedditBot session export created.' });
+  } catch (error) {
+    await showError(error instanceof Error ? error.message : 'Could not create the session dump.');
+  }
+});

extensions/reddit-session-exporter/session-export.js

@@ -0,0 +1,56 @@
+const REDDITBOT_SESSION_FILENAME = 'redditbot-session.json';
+export const REDDIT_CHAT_URL = 'https://chat.reddit.com/';
+
+export function normalizeRedditAccountId(accountId) {
+  const trimmed = String(accountId ?? '').trim();
+  const normalized = trimmed.startsWith('t2_') ? trimmed : `t2_${trimmed}`;
+  if (!/^t2_[a-z0-9]+$/i.test(normalized)) {
+    throw new Error('Reddit returned an invalid account ID.');
+  }
+  return normalized;
+}
+
+export function assertMatchingSessionIdentity(redditIdentity, matrixUserId) {
+  const accountId = normalizeRedditAccountId(redditIdentity?.accountId);
+  const username = String(redditIdentity?.username ?? '').trim();
+  if (!username) throw new Error('Reddit did not return an authenticated username.');
+  const expectedMatrixUserId = `@${accountId}:reddit.com`;
+  if (matrixUserId !== expectedMatrixUserId) {
+    throw new Error(
+      `Reddit is logged in as u/${username} (${accountId}), but Chat is authenticated as ${matrixUserId}. Reload Reddit Chat after switching accounts, then export again.`,
+    );
+  }
+}
+
+function isRedditDomain(domain) {
+  const normalised = domain.toLowerCase().replace(/^\./, '');
+  return normalised === 'reddit.com' || normalised.endsWith('.reddit.com');
+}
+
+function toExportCookie(cookie) {
+  return {
+    name: cookie.name,
+    value: cookie.value,
+    domain: cookie.domain,
+    path: cookie.path,
+    expires: cookie.expirationDate,
+    httpOnly: cookie.httpOnly,
+    secure: cookie.secure,
+    sameSite: cookie.sameSite,
+  };
+}
+
+export function createSessionExportDownload(cookies, matrix) {
+  if (!matrix?.homeserver || !matrix?.accessToken || !matrix?.userId) {
+    throw new Error('Open Reddit Chat before exporting so Matrix credentials can be captured.');
+  }
+  const exportFile = {
+    cookies: cookies.filter((cookie) => isRedditDomain(cookie.domain)).map(toExportCookie),
+    matrix,
+  };
+
+  return {
+    filename: REDDITBOT_SESSION_FILENAME,
+    url: `data:application/json;charset=utf-8,${encodeURIComponent(JSON.stringify(exportFile))}`,
+  };
+}

package.json

@@ -11,8 +11,10 @@
     "dashboard:dev": "vite --config apps/dashboard/vite.config.ts",
     "dashboard:typecheck": "tsc -p apps/dashboard/tsconfig.json --noEmit",
     "start": "tsx src/index.ts",
-    "login": "tsx scripts/login.ts",
     "dev": "tsx watch src/index.ts",
+    "mcp": "tsx src/mcp/server.ts",
+    "docs:api": "tsx scripts/generate-api-docs.ts",
+    "docs:api:check": "tsx scripts/generate-api-docs.ts --check",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
@@ -25,9 +27,10 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@tanstack/react-query": "^5.90.20",
     "axios": "^1.13.2",
-    "better-sqlite3": "^12.5.0",
+    "better-sqlite3": "^13.0.3",
     "dotenv": "^17.2.3",
     "express": "^5.2.1",
     "openai": "^6.15.0",
@@ -37,6 +40,7 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router-dom": "^7.13.1",
+    "sharp": "^0.35.3",
     "winston": "^3.19.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.5"