From d41cabccf56ed508454e35a6bcb9e1df0df76b64 Mon Sep 17 00:00:00 2001
From: ProPR Codex Bot <codex-bot@propr.dev>
Date: Thu, 3 Sep 2026 09:49:53 +0000
Subject: [PATCH 01/18] feat(previews): add repository visual preview settings

---
 packages/api/routes/configRepoValidation.ts   | 95 ++++++++++++++++++-
 packages/api/routes/configRoutes.ts           | 12 ++-
 packages/api/test/configRepoRoutes.test.ts    | 47 ++++++++-
 .../api/test/configRepoValidation.test.ts     | 43 +++++++++
 packages/core/src/config/configManager.ts     | 58 +++++++++++
 .../core/test/visualPreviewConfig.test.ts     | 51 ++++++++++
 propr-ui/src/api/proprTypes.ts                |  6 ++
 .../src/components/RepositoryListContent.tsx  |  3 +
 .../src/components/RepositoryListItem.tsx     | 94 +++++++++++++++++-
 propr-ui/src/hooks/useRepositoryManagement.ts | 56 +++++++++--
 propr-ui/src/pages/RepositoriesPage.tsx       |  4 +-
 11 files changed, 455 insertions(+), 14 deletions(-)
 create mode 100644 packages/core/test/visualPreviewConfig.test.ts

diff --git a/packages/api/routes/configRepoValidation.ts b/packages/api/routes/configRepoValidation.ts
index bb19561c2..c5c3a762d 100644
--- a/packages/api/routes/configRepoValidation.ts
+++ b/packages/api/routes/configRepoValidation.ts
@@ -1,7 +1,27 @@
 import { randomUUID } from 'crypto';
-import type { RepoToMonitor } from '@propr/core';
+import type { RepoToMonitor, VisualPreviewSettings, VisualPreviewType } from '@propr/core';
 import { normalizeOptionalBranchName } from './branchNameValidation.js';
 
+const MAX_VISUAL_PREVIEW_INSTRUCTIONS_LENGTH = 4000;
+
+function normalizeStoredVisualPreviewSettings(value: unknown): VisualPreviewSettings {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { enabled: false, types: ['image'] };
+  }
+  const candidate = value as Partial<VisualPreviewSettings>;
+  const types = Array.isArray(candidate.types)
+    ? [...new Set(candidate.types.filter((type): type is VisualPreviewType => type === 'image' || type === 'video'))]
+    : [];
+  const instructions = typeof candidate.instructions === 'string' && candidate.instructions.trim()
+    ? candidate.instructions.trim()
+    : undefined;
+  return {
+    enabled: candidate.enabled === true,
+    types: types.length > 0 ? types : ['image'],
+    ...(instructions ? { instructions } : {})
+  };
+}
+
 type ValidationResult<T> = { ok: true; value: T } | { ok: false; error: string };
 
 function success<T>(value: T): ValidationResult<T> {
@@ -45,6 +65,13 @@ export function withDefaultRepoAutoFollowup(repo: RepoToMonitor): RepoToMonitor
   return { ...repo, autoFollowupOnFailedCi: repo.autoFollowupOnFailedCi === true };
 }
 
+export function withDefaultRepoOptions(repo: RepoToMonitor): RepoToMonitor {
+  return {
+    ...withDefaultRepoAutoFollowup(repo),
+    visualPreview: normalizeStoredVisualPreviewSettings(repo.visualPreview)
+  };
+}
+
 export function preserveRepoAutoFollowup(
   previousRepos: RepoToMonitor[],
   normalizedRepos: RepoToMonitor[],
@@ -58,6 +85,69 @@ export function preserveRepoAutoFollowup(
   });
 }
 
+export function preserveRepoVisualPreview(
+  previousRepos: RepoToMonitor[],
+  normalizedRepos: RepoToMonitor[],
+  incomingRepos: unknown[]
+): RepoToMonitor[] {
+  const explicitByRepository = new Map<string, VisualPreviewSettings>();
+  normalizedRepos.forEach((repo, index) => {
+    const incoming = incomingRepos[index] as Partial<RepoToMonitor>;
+    if (incoming.visualPreview !== undefined) {
+      explicitByRepository.set(repo.name.trim().toLowerCase(), normalizeStoredVisualPreviewSettings(repo.visualPreview));
+    }
+  });
+
+  return normalizedRepos.map(repo => {
+    const repositoryKey = repo.name.trim().toLowerCase();
+    const explicit = explicitByRepository.get(repositoryKey);
+    if (explicit) return { ...repo, visualPreview: explicit };
+
+    const previous = previousRepos.find(candidate => candidate.name.trim().toLowerCase() === repositoryKey);
+    return { ...repo, visualPreview: normalizeStoredVisualPreviewSettings(previous?.visualPreview) };
+  });
+}
+
+function normalizeVisualPreviewTypes(value: unknown, repoName: string): ValidationResult<VisualPreviewType[]> {
+  if (!Array.isArray(value)) {
+    return failure(`Invalid visualPreview.types format for ${repoName}: must be an array`);
+  }
+  if (value.some(type => type !== 'image' && type !== 'video')) {
+    return failure(`Invalid visualPreview.types format for ${repoName}: supported values are image and video`);
+  }
+  return success([...new Set(value as VisualPreviewType[])]);
+}
+
+function normalizeVisualPreview(value: unknown, repoName: string): ValidationResult<VisualPreviewSettings> {
+  if (value === undefined) return success({ enabled: false, types: ['image'] });
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return failure(`Invalid visualPreview format for ${repoName}: must be an object`);
+  }
+
+  const candidate = value as Partial<VisualPreviewSettings>;
+  if (typeof candidate.enabled !== 'boolean') {
+    return failure(`Invalid visualPreview.enabled format for ${repoName}: must be a boolean`);
+  }
+  const types = normalizeVisualPreviewTypes(candidate.types, repoName);
+  if (!types.ok) return types;
+  if (candidate.enabled && types.value.length === 0) {
+    return failure(`Invalid visualPreview.types format for ${repoName}: select at least one type when previews are enabled`);
+  }
+  if (candidate.instructions !== undefined && typeof candidate.instructions !== 'string') {
+    return failure(`Invalid visualPreview.instructions format for ${repoName}: must be a string`);
+  }
+  const instructions = candidate.instructions?.trim();
+  if (instructions && instructions.length > MAX_VISUAL_PREVIEW_INSTRUCTIONS_LENGTH) {
+    return failure(`Invalid visualPreview.instructions format for ${repoName}: must be ${MAX_VISUAL_PREVIEW_INSTRUCTIONS_LENGTH} characters or fewer`);
+  }
+
+  return success({
+    enabled: candidate.enabled,
+    types: types.value.length > 0 ? types.value : ['image'],
+    ...(instructions ? { instructions } : {})
+  });
+}
+
 export function normalizeRepoConfig(repo: unknown): ValidationResult<RepoToMonitor> {
   const candidateResult = parseRepoObject(repo);
   if (!candidateResult.ok) return candidateResult;
@@ -78,12 +168,15 @@ export function normalizeRepoConfig(repo: unknown): ValidationResult<RepoToMonit
   if (candidate.autoFollowupOnFailedCi !== undefined && typeof candidate.autoFollowupOnFailedCi !== 'boolean') {
     return failure(`Invalid autoFollowupOnFailedCi format for ${name}: must be a boolean`);
   }
+  const visualPreview = normalizeVisualPreview(candidate.visualPreview, name);
+  if (!visualPreview.ok) return visualPreview;
 
   return success({
     id: candidate.id?.trim() || randomUUID(),
     name,
     enabled,
     autoFollowupOnFailedCi: candidate.autoFollowupOnFailedCi ?? false,
+    visualPreview: visualPreview.value,
     alias: alias.value,
     baseBranch: baseBranch.value,
     defaultBranch: defaultBranch.value
diff --git a/packages/api/routes/configRoutes.ts b/packages/api/routes/configRoutes.ts
index 0eba1047c..2f32282e7 100644
--- a/packages/api/routes/configRoutes.ts
+++ b/packages/api/routes/configRoutes.ts
@@ -11,7 +11,12 @@ import { saveSettingsWithRollback } from './configRoutesSettings.js';
 import { saveThenPublishConfigUpdate } from './configRoutesPersistence.js';
 import type { AgentPreparationDeps } from './configRoutesAgentsTypes.js';
 import type { Knex } from 'knex';
-import { normalizeRepoConfig, preserveRepoAutoFollowup, withDefaultRepoAutoFollowup } from './configRepoValidation.js';
+import {
+  normalizeRepoConfig,
+  preserveRepoAutoFollowup,
+  preserveRepoVisualPreview,
+  withDefaultRepoOptions
+} from './configRepoValidation.js';
 
 interface ConfigRoutesDeps {
   redisClient: RedisClientType;
@@ -184,7 +189,7 @@ export function createConfigRoutes(deps: ConfigRoutesDeps) {
   const postFollowupIgnoreKeywords = createJsonPostHandler({ lockKey: 'config:ignore-keywords:lock', pickValue: body => body.followup_ignore_keywords, validate: followup_ignore_keywords => parseNormalizedStringArrayResult(followup_ignore_keywords, 'followup_ignore_keywords'), save: followup_ignore_keywords => configStore.saveFollowupIgnoreKeywords(followup_ignore_keywords), subtype: 'followup_ignore_keywords_update', body: followup_ignore_keywords => ({ followup_ignore_keywords }), committedErrorMessage: 'Follow-up ignore keywords were saved, but publishing the config update notification failed. Persisted config may require a follow-up check.' });
 
   const getRepos = createJsonGetHandler(
-    async () => (await configStore.loadMonitoredReposRaw()).map(withDefaultRepoAutoFollowup),
+    async () => (await configStore.loadMonitoredReposRaw()).map(withDefaultRepoOptions),
     repos_to_monitor => ({ repos_to_monitor }),
     'Failed to load repository configuration',
     '/api/config/repos GET'
@@ -214,7 +219,8 @@ export function createConfigRoutes(deps: ConfigRoutesDeps) {
     }
     const result = await withConfigLock(redisClient, 'config:repos:lock', async lock => {
       const previousRepos = await configStore.loadMonitoredReposRaw();
-      const processedRepos = preserveRepoAutoFollowup(previousRepos, validatedRepos, repos_to_monitor);
+      const withPreservedAutoFollowup = preserveRepoAutoFollowup(previousRepos, validatedRepos, repos_to_monitor);
+      const processedRepos = preserveRepoVisualPreview(previousRepos, withPreservedAutoFollowup, repos_to_monitor);
       return saveThenPublishConfigUpdate({
         save: async () => {
           await database.transaction(async trx => {
diff --git a/packages/api/test/configRepoRoutes.test.ts b/packages/api/test/configRepoRoutes.test.ts
index 96ca416e9..630381b6c 100644
--- a/packages/api/test/configRepoRoutes.test.ts
+++ b/packages/api/test/configRepoRoutes.test.ts
@@ -43,7 +43,8 @@ test('GET repository config returns false for legacy entries with a missing opti
       id: 'repo-1',
       name: 'integry/propr',
       enabled: true,
-      autoFollowupOnFailedCi: false
+      autoFollowupOnFailedCi: false,
+      visualPreview: { enabled: false, types: ['image'] }
     }]
   });
 });
@@ -86,6 +87,7 @@ test('POST repository config persists an enabled option without enabling other r
       name: 'integry/propr',
       enabled: true,
       autoFollowupOnFailedCi: true,
+      visualPreview: { enabled: false, types: ['image'] },
       alias: undefined,
       baseBranch: undefined,
       defaultBranch: undefined
@@ -95,6 +97,7 @@ test('POST repository config persists an enabled option without enabling other r
       name: 'integry/other',
       enabled: true,
       autoFollowupOnFailedCi: false,
+      visualPreview: { enabled: false, types: ['image'] },
       alias: undefined,
       baseBranch: undefined,
       defaultBranch: undefined
@@ -102,6 +105,48 @@ test('POST repository config persists an enabled option without enabling other r
   ]);
 });
 
+test('POST repository config synchronizes visual previews across branch entries', async () => {
+  const saveMonitoredRepos = mock.fn(async () => true);
+  const routes = createConfigRoutes({
+    redisClient: {
+      set: mock.fn(async () => 'OK'),
+      eval: mock.fn(async () => 1),
+      publish: mock.fn(async () => 1),
+      lPush: mock.fn(async () => 1),
+      lTrim: mock.fn(async () => 'OK')
+    } as never,
+    configStore: {
+      loadMonitoredReposRaw: async () => [],
+      saveMonitoredRepos,
+      clearRemovedRepositoryIndexData: async () => {}
+    },
+    database: {
+      transaction: async (callback: (transaction: never) => Promise<unknown>) => callback({} as never)
+    } as never
+  });
+  const response = createResponse();
+  const visualPreview = {
+    enabled: true,
+    types: ['image', 'video'],
+    instructions: 'Show desktop and mobile.'
+  };
+
+  await routes.postRepos({
+    body: {
+      repos_to_monitor: [
+        { id: 'repo-main', name: 'integry/propr', enabled: true, baseBranch: 'main', visualPreview },
+        { id: 'repo-release', name: 'integry/propr', enabled: true, baseBranch: 'release' }
+      ]
+    }
+  } as never, response as never);
+
+  assert.equal(response.statusCode, 200);
+  assert.deepEqual(
+    saveMonitoredRepos.mock.calls[0]?.arguments[0].map(repo => repo.visualPreview),
+    [visualPreview, visualPreview]
+  );
+});
+
 test('POST repository config preserves an omitted option for existing repositories', async () => {
   const saveMonitoredRepos = mock.fn(async () => true);
   const routes = createConfigRoutes({
diff --git a/packages/api/test/configRepoValidation.test.ts b/packages/api/test/configRepoValidation.test.ts
index 19dc67e89..c6b4c8280 100644
--- a/packages/api/test/configRepoValidation.test.ts
+++ b/packages/api/test/configRepoValidation.test.ts
@@ -12,6 +12,49 @@ test('repository config defaults missing automatic failed-CI follow-up to false'
   assert.equal(normalized.ok, true);
   if (normalized.ok) {
     assert.equal(normalized.value.autoFollowupOnFailedCi, false);
+    assert.deepEqual(normalized.value.visualPreview, { enabled: false, types: ['image'] });
+  }
+});
+
+test('repository config accepts visual preview types and trims instructions', () => {
+  const normalized = normalizeRepoConfig({
+    id: 'repo-1',
+    name: 'integry/propr',
+    enabled: true,
+    visualPreview: {
+      enabled: true,
+      types: ['video', 'image', 'video'],
+      instructions: '  Capture desktop and mobile views.  '
+    }
+  });
+
+  assert.equal(normalized.ok, true);
+  if (normalized.ok) {
+    assert.deepEqual(normalized.value.visualPreview, {
+      enabled: true,
+      types: ['video', 'image'],
+      instructions: 'Capture desktop and mobile views.'
+    });
+  }
+});
+
+test('repository config rejects invalid visual preview settings', () => {
+  const invalidValues = [
+    { enabled: 'true', types: ['image'] },
+    { enabled: true, types: [] },
+    { enabled: true, types: ['animation'] },
+    { enabled: true, types: ['image'], instructions: 42 }
+  ];
+
+  for (const visualPreview of invalidValues) {
+    const normalized = normalizeRepoConfig({
+      id: 'repo-1',
+      name: 'integry/propr',
+      enabled: true,
+      visualPreview
+    });
+    assert.equal(normalized.ok, false);
+    if (!normalized.ok) assert.match(normalized.error, /visualPreview/);
   }
 });
 
diff --git a/packages/core/src/config/configManager.ts b/packages/core/src/config/configManager.ts
index d246724fb..cf7fe45a9 100644
--- a/packages/core/src/config/configManager.ts
+++ b/packages/core/src/config/configManager.ts
@@ -18,11 +18,40 @@ export interface RepoToMonitor {
     name: string;            // owner/repo
     enabled: boolean;
     autoFollowupOnFailedCi?: boolean; // Defaults to false for legacy configurations
+    visualPreview?: VisualPreviewSettings; // Defaults to disabled for legacy configurations
     alias?: string;          // Optional display name
     baseBranch?: string;     // Optional specific branch to monitor
     defaultBranch?: string;  // Optional repository default branch for demo metadata
 }
 
+export type VisualPreviewType = 'image' | 'video';
+
+export interface VisualPreviewSettings {
+    enabled: boolean;
+    types: VisualPreviewType[];
+    instructions?: string;
+}
+
+export function normalizeStoredVisualPreviewSettings(value: unknown): VisualPreviewSettings {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { enabled: false, types: ['image'] };
+    }
+
+    const candidate = value as Partial<VisualPreviewSettings>;
+    const types = Array.isArray(candidate.types)
+        ? [...new Set(candidate.types.filter((type): type is VisualPreviewType => type === 'image' || type === 'video'))]
+        : [];
+    const instructions = typeof candidate.instructions === 'string' && candidate.instructions.trim()
+        ? candidate.instructions.trim()
+        : undefined;
+
+    return {
+        enabled: candidate.enabled === true,
+        types: types.length > 0 ? types : ['image'],
+        ...(instructions ? { instructions } : {})
+    };
+}
+
 interface ConfigSettings {
     worker_concurrency?: number;
     analysis_model_fast?: string;
@@ -120,6 +149,35 @@ export async function loadMonitoredReposRaw(): Promise<RepoToMonitor[]> {
     return rawRepos;
 }
 
+/**
+ * Resolve the branch-independent visual-preview policy for a repository.
+ * Multiple branch entries may exist for one repository; an explicitly enabled
+ * entry wins over disabled or legacy entries until the next synchronized save.
+ */
+export function resolveRepositoryVisualPreviewSettings(
+    repos: readonly RepoToMonitor[],
+    repository: string
+): VisualPreviewSettings {
+    const normalizedRepository = repository.trim().toLowerCase();
+    if (!normalizedRepository) return { enabled: false, types: ['image'] };
+
+    const matching = repos.filter(repo => repo.name.trim().toLowerCase() === normalizedRepository);
+    const configured = matching.find(repo => normalizeStoredVisualPreviewSettings(repo.visualPreview).enabled)
+        ?? matching.find(repo => repo.visualPreview !== undefined);
+    return normalizeStoredVisualPreviewSettings(configured?.visualPreview);
+}
+
+export async function loadRepositoryVisualPreviewSettings(repository: string): Promise<VisualPreviewSettings> {
+    try {
+        const settings = resolveRepositoryVisualPreviewSettings(await loadMonitoredReposRaw(), repository);
+        logger.info({ repository, enabled: settings.enabled, types: settings.types }, 'Loaded repository visual-preview settings');
+        return settings;
+    } catch (error) {
+        logger.warn({ repository, error: (error as Error).message }, 'Failed to load visual-preview settings; treating previews as disabled');
+        return { enabled: false, types: ['image'] };
+    }
+}
+
 export async function saveMonitoredRepos(repos: RepoToMonitor[], client?: Knex | Knex.Transaction): Promise<boolean> {
     await saveConfig('repos_to_monitor', repos, client);
     logger.info({ repos }, 'Successfully saved monitored repositories');
diff --git a/packages/core/test/visualPreviewConfig.test.ts b/packages/core/test/visualPreviewConfig.test.ts
new file mode 100644
index 000000000..96255bc16
--- /dev/null
+++ b/packages/core/test/visualPreviewConfig.test.ts
@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import { after, test } from 'node:test';
+import {
+  normalizeStoredVisualPreviewSettings,
+  resolveRepositoryVisualPreviewSettings,
+  type RepoToMonitor
+} from '../src/config/configManager.js';
+import { db } from '../src/db/connection.js';
+
+after(async () => {
+  await db.destroy();
+});
+
+test('stored visual preview settings are backward compatible and sanitized', () => {
+  assert.deepEqual(normalizeStoredVisualPreviewSettings(undefined), {
+    enabled: false,
+    types: ['image']
+  });
+  assert.deepEqual(normalizeStoredVisualPreviewSettings({
+    enabled: true,
+    types: ['video', 'invalid', 'video'],
+    instructions: '  Focus the changed dialog.  '
+  }), {
+    enabled: true,
+    types: ['video'],
+    instructions: 'Focus the changed dialog.'
+  });
+});
+
+test('repository visual preview settings are branch independent', () => {
+  const repos: RepoToMonitor[] = [
+    { id: 'main', name: 'integry/propr', enabled: true, baseBranch: 'main' },
+    {
+      id: 'release',
+      name: 'INTEGRY/PROPR',
+      enabled: true,
+      baseBranch: 'release',
+      visualPreview: { enabled: true, types: ['image', 'video'], instructions: 'Show both breakpoints.' }
+    }
+  ];
+
+  assert.deepEqual(resolveRepositoryVisualPreviewSettings(repos, 'integry/propr'), {
+    enabled: true,
+    types: ['image', 'video'],
+    instructions: 'Show both breakpoints.'
+  });
+  assert.deepEqual(resolveRepositoryVisualPreviewSettings(repos, 'integry/other'), {
+    enabled: false,
+    types: ['image']
+  });
+});
diff --git a/propr-ui/src/api/proprTypes.ts b/propr-ui/src/api/proprTypes.ts
index 07cbfb8f6..9f37c899e 100644
--- a/propr-ui/src/api/proprTypes.ts
+++ b/propr-ui/src/api/proprTypes.ts
@@ -120,6 +120,12 @@ export interface MonitoredRepo {
   enabled: boolean;
   /** Whether failed CI triggers an automatic follow-up. Missing legacy values are off. */
   autoFollowupOnFailedCi?: boolean;
+  /** Generated media to embed in PRs when a change has a visible result. */
+  visualPreview?: {
+    enabled: boolean;
+    types: Array<'image' | 'video'>;
+    instructions?: string;
+  };
   alias?: string;
   baseBranch?: string;
   starred?: boolean;
diff --git a/propr-ui/src/components/RepositoryListContent.tsx b/propr-ui/src/components/RepositoryListContent.tsx
index 500ad45b3..f4e71994b 100644
--- a/propr-ui/src/components/RepositoryListContent.tsx
+++ b/propr-ui/src/components/RepositoryListContent.tsx
@@ -33,6 +33,7 @@ interface RepositoryListContentProps {
   selectedRepoId: string | null;
   onToggle: (repoId: string) => void;
   onToggleAutoCiFollowup: (repoId: string) => void;
+  onUpdateVisualPreview: (repoId: string, settings: NonNullable<MonitoredRepo['visualPreview']>) => void;
   onRemove: (repoId: string) => void;
   onStopIndexing: (repoName: string, baseBranch?: string) => void;
   onReindex: (repoName: string, baseBranch?: string) => void;
@@ -51,6 +52,7 @@ export const RepositoryListContent: React.FC<RepositoryListContentProps> = ({
   selectedRepoId,
   onToggle,
   onToggleAutoCiFollowup,
+  onUpdateVisualPreview,
   onRemove,
   onStopIndexing,
   onReindex,
@@ -105,6 +107,7 @@ export const RepositoryListContent: React.FC<RepositoryListContentProps> = ({
       indexingStatuses={indexingStatuses}
       onToggle={onToggle}
       onToggleAutoCiFollowup={onToggleAutoCiFollowup}
+      onUpdateVisualPreview={onUpdateVisualPreview}
       onRemove={onRemove}
       onStopIndexing={onStopIndexing}
       onReindex={onReindex}
diff --git a/propr-ui/src/components/RepositoryListItem.tsx b/propr-ui/src/components/RepositoryListItem.tsx
index 38290c357..1e05a4a19 100644
--- a/propr-ui/src/components/RepositoryListItem.tsx
+++ b/propr-ui/src/components/RepositoryListItem.tsx
@@ -1,5 +1,5 @@
-import React, { useState } from 'react';
-import { Github, RefreshCw, Star, Eye, EyeOff } from 'lucide-react';
+import React, { useEffect, useState } from 'react';
+import { Github, RefreshCw, Star, Eye, EyeOff, Image, Video } from 'lucide-react';
 import { DeleteRepoDialog } from './DeleteRepoDialog';
 import { RepositoryIndexingStatus, MonitoredRepo } from '../api/proprApi';
 import { getRepoStatusKey } from '../api/repoIndexingApi';
@@ -222,11 +222,95 @@ const AutoCiFollowupControl: React.FC<{
   );
 };
 
+type VisualPreviewSettings = NonNullable<MonitoredRepo['visualPreview']>;
+
+const VisualPreviewControl: React.FC<{
+  repo: MonitoredRepo;
+  onUpdate: (repoId: string, settings: VisualPreviewSettings) => void;
+  isReadOnly: boolean;
+}> = ({ repo, onUpdate, isReadOnly }) => {
+  const settings: VisualPreviewSettings = repo.visualPreview || { enabled: false, types: ['image'] };
+  const [instructions, setInstructions] = useState(settings.instructions || '');
+
+  useEffect(() => setInstructions(settings.instructions || ''), [settings.instructions]);
+
+  if (isReadOnly) return null;
+
+  const toggleType = (type: 'image' | 'video') => {
+    const selected = settings.types.includes(type);
+    if (selected && settings.types.length === 1) return;
+    onUpdate(repo.id, {
+      ...settings,
+      types: selected ? settings.types.filter(candidate => candidate !== type) : [...settings.types, type]
+    });
+  };
+
+  return (
+    <div className="mt-2 text-[11px] text-slate-600" onClick={(event) => event.stopPropagation()}>
+      <label className="inline-flex items-center gap-2 cursor-pointer" title="Generate focused media for changes with a visible result">
+        <input
+          type="checkbox"
+          checked={settings.enabled}
+          onChange={() => onUpdate(repo.id, { ...settings, enabled: !settings.enabled })}
+          className="sr-only peer"
+          aria-label={`Visual previews for ${repo.name}`}
+        />
+        <span className="relative w-7 h-4 bg-slate-200 rounded-full peer-focus:ring-2 peer-focus:ring-teal-500/20 peer-checked:bg-teal-500 after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:h-3 after:w-3 after:rounded-full after:bg-white after:border after:border-slate-300 after:transition-all peer-checked:after:translate-x-full" />
+        <span>Visual previews</span>
+        <span className={`rounded px-1.5 py-0.5 font-medium ${settings.enabled ? 'bg-teal-50 text-teal-700' : 'bg-slate-100 text-slate-500'}`}>
+          {settings.enabled ? 'On' : 'Off'}
+        </span>
+      </label>
+
+      {settings.enabled && (
+        <div className="mt-2 ml-9 space-y-2" onClick={(event) => event.stopPropagation()}>
+          <div className="flex flex-wrap items-center gap-2">
+            <button
+              type="button"
+              onClick={() => toggleType('image')}
+              className={`inline-flex items-center gap-1 rounded border px-2 py-1 transition-colors ${settings.types.includes('image') ? 'border-teal-300 bg-teal-50 text-teal-700' : 'border-slate-200 bg-white text-slate-500'}`}
+              aria-pressed={settings.types.includes('image')}
+              title={settings.types.length === 1 && settings.types.includes('image') ? 'At least one preview type is required' : 'Include image previews'}
+            >
+              <Image className="h-3 w-3" /> Images
+            </button>
+            <button
+              type="button"
+              onClick={() => toggleType('video')}
+              className={`inline-flex items-center gap-1 rounded border px-2 py-1 transition-colors ${settings.types.includes('video') ? 'border-teal-300 bg-teal-50 text-teal-700' : 'border-slate-200 bg-white text-slate-500'}`}
+              aria-pressed={settings.types.includes('video')}
+              title={settings.types.length === 1 && settings.types.includes('video') ? 'At least one preview type is required' : 'Include video previews'}
+            >
+              <Video className="h-3 w-3" /> Videos
+            </button>
+          </div>
+          <textarea
+            value={instructions}
+            onChange={(event) => setInstructions(event.target.value)}
+            onBlur={() => {
+              const normalized = instructions.trim();
+              if (normalized !== (settings.instructions || '')) {
+                onUpdate(repo.id, { ...settings, instructions: normalized || undefined });
+              }
+            }}
+            maxLength={4000}
+            rows={2}
+            className="w-full max-w-sm resize-y rounded border border-slate-200 bg-white px-2 py-1.5 text-[11px] text-slate-700 placeholder:text-slate-400 focus:border-teal-400 focus:outline-none focus:ring-1 focus:ring-teal-400"
+            placeholder="Optional: capture separate desktop and mobile views…"
+            aria-label={`Visual preview instructions for ${repo.name}`}
+          />
+        </div>
+      )}
+    </div>
+  );
+};
+
 interface RepositoryListItemProps {
   repo: MonitoredRepo;
   indexingStatuses: Record<string, RepositoryIndexingStatus>;
   onToggle: (repoId: string) => void;
   onToggleAutoCiFollowup: (repoId: string) => void;
+  onUpdateVisualPreview: (repoId: string, settings: VisualPreviewSettings) => void;
   onRemove: (repoId: string) => void | Promise<void>;
   onStopIndexing: (repoName: string, baseBranch?: string) => void;
   onReindex: (repoName: string, baseBranch?: string) => void;
@@ -242,6 +326,7 @@ export const RepositoryListItem: React.FC<RepositoryListItemProps> = ({
   indexingStatuses,
   onToggle,
   onToggleAutoCiFollowup,
+  onUpdateVisualPreview,
   onRemove,
   onStopIndexing,
   onReindex,
@@ -360,6 +445,11 @@ export const RepositoryListItem: React.FC<RepositoryListItemProps> = ({
             onToggle={onToggleAutoCiFollowup}
             isReadOnly={isReadOnly}
           />
+          <VisualPreviewControl
+            repo={repo}
+            onUpdate={onUpdateVisualPreview}
+            isReadOnly={isReadOnly}
+          />
         </div>
 
         {/* Right Action Gutter: Fixed-width area for maintenance tools */}
diff --git a/propr-ui/src/hooks/useRepositoryManagement.ts b/propr-ui/src/hooks/useRepositoryManagement.ts
index 806ad956f..4449a1550 100644
--- a/propr-ui/src/hooks/useRepositoryManagement.ts
+++ b/propr-ui/src/hooks/useRepositoryManagement.ts
@@ -39,10 +39,31 @@ function shouldIgnoreStaleProgressUpdate(
   return currentStatus ? hasSeenTerminalSocketUpdate && TERMINAL_INDEXING_STATUSES.has(currentStatus.indexing_status) : false;
 }
 
-export type Repo = Omit<MonitoredRepo, 'autoFollowupOnFailedCi'> & {
+export type VisualPreviewSettings = NonNullable<MonitoredRepo['visualPreview']>;
+
+export type Repo = Omit<MonitoredRepo, 'autoFollowupOnFailedCi' | 'visualPreview'> & {
   autoFollowupOnFailedCi: boolean;
+  visualPreview: VisualPreviewSettings;
 };
 
+const defaultVisualPreview = (): VisualPreviewSettings => ({ enabled: false, types: ['image'] });
+
+function parseVisualPreview(value: unknown): VisualPreviewSettings {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return defaultVisualPreview();
+  const candidate = value as Record<string, unknown>;
+  const types = Array.isArray(candidate.types)
+    ? [...new Set(candidate.types.filter((type): type is 'image' | 'video' => type === 'image' || type === 'video'))]
+    : [];
+  const instructions = typeof candidate.instructions === 'string' && candidate.instructions.trim()
+    ? candidate.instructions.trim()
+    : undefined;
+  return {
+    enabled: candidate.enabled === true,
+    types: types.length > 0 ? types : ['image'],
+    ...(instructions ? { instructions } : {})
+  };
+}
+
 export interface UseRepositoryManagementResult {
   repos: Repo[];
   loading: boolean;
@@ -60,6 +81,7 @@ export interface UseRepositoryManagementResult {
   handleRemoveRepo: (repoId: string) => void;
   handleToggleRepo: (repoId: string) => void;
   handleToggleAutoCiFollowup: (repoId: string) => void;
+  handleUpdateVisualPreview: (repoId: string, settings: VisualPreviewSettings) => void;
   handleToggleStar: (repoId: string) => Promise<void>;
   handleToggleHidden: (repoId: string) => Promise<void>;
   handleToggleShowHidden: () => void;
@@ -104,18 +126,19 @@ export function useRepositoryManagement(): UseRepositoryManagementResult {
         .map((repo: unknown): Repo | null => {
           if (typeof repo === 'string') {
             const userPref = prefs[repo] || {};
-            return { id: generateId(), name: repo, enabled: true, autoFollowupOnFailedCi: false, starred: userPref.starred, hidden: userPref.hidden };
+            return { id: generateId(), name: repo, enabled: true, autoFollowupOnFailedCi: false, visualPreview: defaultVisualPreview(), starred: userPref.starred, hidden: userPref.hidden };
           } else if (repo && typeof repo === 'object') {
             const repoObj = repo as Record<string, unknown>;
             const name = (repoObj.name as string) || (repoObj.full_name as string);
             const enabled = typeof repoObj.enabled === 'boolean' ? repoObj.enabled : true;
             const autoFollowupOnFailedCi = repoObj.autoFollowupOnFailedCi === true;
+            const visualPreview = parseVisualPreview(repoObj.visualPreview);
             const id = (repoObj.id as string) || generateId();
             const alias = repoObj.alias as string | undefined;
             const baseBranch = repoObj.baseBranch as string | undefined;
             const userPref = name ? (prefs[name] || {}) : {};
             if (name) {
-              return { id, name, enabled, autoFollowupOnFailedCi, alias, baseBranch, starred: userPref.starred, hidden: userPref.hidden };
+              return { id, name, enabled, autoFollowupOnFailedCi, visualPreview, alias, baseBranch, starred: userPref.starred, hidden: userPref.hidden };
             }
           }
           return null;
@@ -305,15 +328,17 @@ export function useRepositoryManagement(): UseRepositoryManagementResult {
       alert(`Repository "${newRepo}"${branchInfo} has already been added to the list.`);
       return false;
     }
+    const repositoryKey = getRepositoryConfigKey(newRepo);
+    const existingVisualPreview = repos.find(repo => getRepositoryConfigKey(repo.name) === repositoryKey)?.visualPreview;
     const newEntry: Repo = {
       id: generateId(),
       name: newRepo,
       enabled: true,
       autoFollowupOnFailedCi,
+      visualPreview: existingVisualPreview || defaultVisualPreview(),
       alias: newAlias.trim() || undefined,
       baseBranch: newBaseBranch.trim() || undefined
     };
-    const repositoryKey = getRepositoryConfigKey(newRepo);
     const newRepos = [
       ...repos.map(repo => getRepositoryConfigKey(repo.name) === repositoryKey
         ? { ...repo, autoFollowupOnFailedCi: repo.autoFollowupOnFailedCi || autoFollowupOnFailedCi }
@@ -354,6 +379,19 @@ export function useRepositoryManagement(): UseRepositoryManagementResult {
     performAutoSave(newRepos);
   };
 
+  const handleUpdateVisualPreview = (repoId: string, settings: VisualPreviewSettings) => {
+    if (!canManageRepositories) return;
+    const targetRepo = repos.find(repo => repo.id === repoId);
+    if (!targetRepo) return;
+    const repositoryKey = getRepositoryConfigKey(targetRepo.name);
+    const normalizedSettings = parseVisualPreview(settings);
+    const newRepos = repos.map(repo => getRepositoryConfigKey(repo.name) === repositoryKey
+      ? { ...repo, visualPreview: normalizedSettings }
+      : repo);
+    setRepos(newRepos);
+    performAutoSave(newRepos);
+  };
+
   const handleToggleStar = async (repoId: string) => {
     const repo = repos.find(r => r.id === repoId);
     if (!repo) return;
@@ -389,20 +427,26 @@ export function useRepositoryManagement(): UseRepositoryManagementResult {
 
   const hiddenCount = repos.filter(r => r.hidden).length;
   const autoCiFollowupByRepository = new Map<string, boolean>();
+  const visualPreviewByRepository = new Map<string, VisualPreviewSettings>();
   for (const repo of repos) {
     const key = getRepositoryConfigKey(repo.name);
     autoCiFollowupByRepository.set(key, autoCiFollowupByRepository.get(key) === true || repo.autoFollowupOnFailedCi);
+    const previousPreview = visualPreviewByRepository.get(key);
+    if (!previousPreview || (!previousPreview.enabled && repo.visualPreview.enabled)) {
+      visualPreviewByRepository.set(key, repo.visualPreview);
+    }
   }
   const reposForDisplay = repos.map(repo => ({
     ...repo,
-    autoFollowupOnFailedCi: autoCiFollowupByRepository.get(getRepositoryConfigKey(repo.name)) === true
+    autoFollowupOnFailedCi: autoCiFollowupByRepository.get(getRepositoryConfigKey(repo.name)) === true,
+    visualPreview: visualPreviewByRepository.get(getRepositoryConfigKey(repo.name)) || defaultVisualPreview()
   }));
   const filteredRepos = showHiddenRepos ? reposForDisplay : reposForDisplay.filter(r => !r.hidden);
 
   return {
     repos, loading, error, availableRepos, indexingStatuses, saveStatus, showHiddenRepos,
     filteredRepos, hiddenCount, loadRepos, handleStopIndexing, handleReindexRepo, handleAddRepo,
-    handleRemoveRepo, handleToggleRepo, handleToggleAutoCiFollowup, handleToggleStar, handleToggleHidden, handleToggleShowHidden,
+    handleRemoveRepo, handleToggleRepo, handleToggleAutoCiFollowup, handleUpdateVisualPreview, handleToggleStar, handleToggleHidden, handleToggleShowHidden,
     handleRetry, setError
   };
 }
diff --git a/propr-ui/src/pages/RepositoriesPage.tsx b/propr-ui/src/pages/RepositoriesPage.tsx
index cb317b889..d50e671db 100644
--- a/propr-ui/src/pages/RepositoriesPage.tsx
+++ b/propr-ui/src/pages/RepositoriesPage.tsx
@@ -23,7 +23,7 @@ const RepositoriesPage: React.FC = () => {
     repos, loading, error, availableRepos, indexingStatuses, saveStatus, showHiddenRepos,
     filteredRepos, hiddenCount, handleStopIndexing, handleReindexRepo, handleAddRepo,
     handleRemoveRepo, handleToggleRepo, handleToggleStar, handleToggleHidden,
-    handleToggleAutoCiFollowup,
+    handleToggleAutoCiFollowup, handleUpdateVisualPreview,
     handleToggleShowHidden, handleRetry
   } = useRepositoryManagement();
 
@@ -127,6 +127,7 @@ const RepositoriesPage: React.FC = () => {
                 selectedRepoId={selectedRepoId}
                 onToggle={handleToggleRepo}
                 onToggleAutoCiFollowup={handleToggleAutoCiFollowup}
+                onUpdateVisualPreview={handleUpdateVisualPreview}
                 onRemove={handleRemoveRepo}
                 onStopIndexing={handleStopIndexing}
                 onReindex={handleReindexRepo}
@@ -156,6 +157,7 @@ const RepositoriesPage: React.FC = () => {
                   selectedRepoId={selectedRepoId}
                   onToggle={handleToggleRepo}
                   onToggleAutoCiFollowup={handleToggleAutoCiFollowup}
+                  onUpdateVisualPreview={handleUpdateVisualPreview}
                   onRemove={handleRemoveRepo}
                   onStopIndexing={handleStopIndexing}
                   onReindex={handleReindexRepo}

From b29eff162dfc4fd7f862c0d8ee88333935d5033f Mon Sep 17 00:00:00 2001
From: ProPR Codex Bot <codex-bot@propr.dev>
Date: Thu, 3 Sep 2026 10:32:53 +0000
Subject: [PATCH 02/18] feat(previews): publish generated visual evidence

---
 Dockerfile.agent                              |   2 +-
 docker/Dockerfile.app.prod                    |  13 +
 docs/docs/features/overview.md                |   1 +
 docs/docs/features/pr-followup.md             |   1 +
 docs/docs/features/propr-cli.md               |   4 +
 docs/docs/features/visual-previews.md         |  47 +++
 docs/docs/features/web-ui.md                  |   2 +-
 docs/sidebars.ts                              |   1 +
 packages/api/routes/configRepoValidation.ts   |  15 +-
 packages/api/routes/configRoutes.ts           |   7 +-
 packages/api/test/configRepoRoutes.test.ts    |  27 +-
 .../api/test/configRepoValidation.test.ts     |  14 +
 packages/cli/src/api/index.ts                 |   1 +
 packages/cli/src/api/repos.test.ts            |  31 +-
 packages/cli/src/api/repos.ts                 |  28 ++
 .../cli/src/commands/repoCommands.test.ts     |  22 ++
 packages/cli/src/commands/repoCommands.ts     |  67 ++++-
 .../src/claude/prompts/promptGenerator.ts     |   8 +-
 packages/core/src/index.ts                    |   1 +
 .../core/src/services/visualPreviewService.ts | 269 ++++++++++++++++++
 .../core/test/visualPreviewService.test.ts    | 141 +++++++++
 .../src/components/RepositoryListItem.tsx     |  92 +-----
 .../RepositoryVisualPreviewControl.test.tsx   |  38 +++
 .../RepositoryVisualPreviewControl.tsx        |  96 +++++++
 propr-ui/src/hooks/repositoryVisualPreview.ts |  61 ++++
 .../hooks/useRepositoryManagement.test.tsx    |  35 +++
 propr-ui/src/hooks/useRepositoryManagement.ts |  61 +---
 src/github/visualPreviewAttachments.ts        | 168 +++++++++++
 src/jobs/issueJob/agent.ts                    |   6 +-
 src/jobs/issueJobHelpers.ts                   |  51 +++-
 src/jobs/issueJobPostProcessing.ts            |  30 +-
 src/jobs/prCommentJobUtils.ts                 |   9 +-
 src/jobs/prCommentPostExecution.ts            |  84 +++++-
 src/jobs/prCompletionComment.ts               |   7 +-
 src/jobs/processPullRequestCommentJob.ts      |   5 +-
 test/issueJobUnpublishableFailure.test.ts     |   2 +
 test/visualPreviewAttachments.test.ts         | 112 ++++++++
 37 files changed, 1385 insertions(+), 174 deletions(-)
 create mode 100644 docs/docs/features/visual-previews.md
 create mode 100644 packages/core/src/services/visualPreviewService.ts
 create mode 100644 packages/core/test/visualPreviewService.test.ts
 create mode 100644 propr-ui/src/components/RepositoryVisualPreviewControl.test.tsx
 create mode 100644 propr-ui/src/components/RepositoryVisualPreviewControl.tsx
 create mode 100644 propr-ui/src/hooks/repositoryVisualPreview.ts
 create mode 100644 src/github/visualPreviewAttachments.ts
 create mode 100644 test/visualPreviewAttachments.test.ts

diff --git a/Dockerfile.agent b/Dockerfile.agent
index 72bf495b8..ed01830f8 100644
--- a/Dockerfile.agent
+++ b/Dockerfile.agent
@@ -24,7 +24,7 @@ ARG CURL_VERSION_PREFIX=7.88.1-10+deb12u
 # install falls back to the latest available version when this prefix no longer
 # matches. That trades strict reproducibility for not breaking every build on a
 # gh release; the fallback logs a note to stderr when it triggers.
-ARG GH_VERSION_PREFIX=2.96.
+ARG GH_VERSION_PREFIX=2.99.
 ARG GIT_VERSION_PREFIX=1:2.39.5-0+deb12u
 ARG GOSU_VERSION_PREFIX=1.14-1
 ARG IPTABLES_VERSION_PREFIX=1.8.9-2
diff --git a/docker/Dockerfile.app.prod b/docker/Dockerfile.app.prod
index db3766a42..29c22d511 100644
--- a/docker/Dockerfile.app.prod
+++ b/docker/Dockerfile.app.prod
@@ -48,6 +48,9 @@ FROM node:22-alpine AS runtime
 
 WORKDIR /usr/src/app
 
+ARG GH_VERSION=2.99.0
+ARG TARGETARCH
+
 # Runtime-only packages. No python/make/g++ — native modules were built in stage 1.
 #   git      — simple-git operations
 #   sudo     — worktree ownership changes
@@ -55,6 +58,16 @@ WORKDIR /usr/src/app
 #   curl/jq  — deploy-pr.sh script
 #   util-linux-misc — script(1), the PTY bridge for browser agent logins
 RUN apk add --no-cache git sudo docker-cli curl jq tini util-linux-misc \
+    && gh_arch="${TARGETARCH:-amd64}" \
+    && case "$gh_arch" in amd64|arm64) ;; *) echo "Unsupported GitHub CLI architecture: $gh_arch" >&2; exit 1 ;; esac \
+    && gh_archive="gh_${GH_VERSION}_linux_${gh_arch}.tar.gz" \
+    && curl -fsSLO "https://github.com/cli/cli/releases/download/v${GH_VERSION}/${gh_archive}" \
+    && curl -fsSLO "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_checksums.txt" \
+    && grep "  ${gh_archive}$" "gh_${GH_VERSION}_checksums.txt" | sha256sum -c - \
+    && tar -xzf "$gh_archive" \
+    && install -m 0755 "gh_${GH_VERSION}_linux_${gh_arch}/bin/gh" /usr/local/bin/gh \
+    && rm -rf "$gh_archive" "gh_${GH_VERSION}_checksums.txt" "gh_${GH_VERSION}_linux_${gh_arch}" \
+    && gh --version \
     && mkdir -p /tmp/git-processor \
     && git config --system --add safe.directory /usr/src/app/repos \
     && git config --system --add safe.directory /tmp/pr-worktrees \
diff --git a/docs/docs/features/overview.md b/docs/docs/features/overview.md
index feb17ba0b..5ddd207b6 100644
--- a/docs/docs/features/overview.md
+++ b/docs/docs/features/overview.md
@@ -41,6 +41,7 @@ Use different coding agents without changing the rest of the workflow.
 ProPR keeps follow-up work where the review already happens: the pull request.
 
 - [PR automation and fine-tuning](./pr-followup.md): create pull requests automatically, then refine them through natural GitHub comments or slash-command workflows.
+- [Visual previews](./visual-previews.md): attach focused image or video evidence when an implementation changes something users can see.
 - [PR slash commands](./pr-commands.md): the command reference for `/review`, `/fix`, `/merge`, `/switch`, `/use`, and `/ultrafix`.
 - [Branch configuration](./branch-config.md): repository-specific branch defaults and resolution rules.
 
diff --git a/docs/docs/features/pr-followup.md b/docs/docs/features/pr-followup.md
index b2bc01a5d..aed0dabe0 100644
--- a/docs/docs/features/pr-followup.md
+++ b/docs/docs/features/pr-followup.md
@@ -16,6 +16,7 @@ When ProPR finishes an implementation task, it handles the GitHub plumbing aroun
 - Pushes to GitHub
 - Opens a pull request linked to the source issue
 - Posts status back to GitHub
+- Attaches focused [visual previews](./visual-previews.md) when the repository enables them and the change has a visible result
 - Updates task and label state (`<trigger>-processing` → `<trigger>-done`, or `<trigger>-failed-*` on failure)
 
 This keeps the agent focused on code while ProPR handles the repeatable workflow around the code.
diff --git a/docs/docs/features/propr-cli.md b/docs/docs/features/propr-cli.md
index 5ccb54d7f..f16973ddc 100644
--- a/docs/docs/features/propr-cli.md
+++ b/docs/docs/features/propr-cli.md
@@ -254,6 +254,8 @@ propr repo remove owner/repo
 propr repo toggle owner/repo --enable        # Enable/disable monitoring
 propr repo toggle owner/repo --auto-ci-followup     # Enable failed-CI follow-up
 propr repo toggle owner/repo --no-auto-ci-followup  # Disable failed-CI follow-up
+propr repo toggle owner/repo --visual-previews --preview-types image,video
+propr repo toggle owner/repo --no-visual-previews
 propr repo index owner/repo                  # Full reindex
 propr repo index owner/repo --incremental    # Incremental reindex
 propr repo status                            # Indexing status for all repos
@@ -261,6 +263,8 @@ propr repo status                            # Indexing status for all repos
 
 Automatic CI follow-up is configured per repository and is **off by default**. Enable it only for repositories whose CI failures are high-quality, trusted signals; noisy or flaky checks can otherwise create unnecessary follow-up work. `propr repo list` shows the current setting for every monitored repository.
 
+Visual previews are also per-repository and **off by default**. `--preview-types` accepts `image`, `video`, or `image,video`; use `--preview-instructions` to add project-specific capture details. See [Visual Previews](./visual-previews.md) for generation and publication behavior.
+
 ## Agents
 
 ```bash
diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
new file mode 100644
index 000000000..d7f4f9565
--- /dev/null
+++ b/docs/docs/features/visual-previews.md
@@ -0,0 +1,47 @@
+---
+title: Visual Previews
+---
+
+# Visual Previews
+
+Visual previews let a ProPR implementation show its user-visible result directly in the generated pull request. The same policy applies to later follow-up commits, whose completion comments can include fresh media focused on that follow-up.
+
+The feature is opt-in per repository. Existing repository configurations remain disabled after an upgrade.
+
+## Configure A Repository
+
+On **Repositories**, turn on **Visual previews** beneath the repository entry. Choose **Images**, **Videos**, or both, then optionally add capture instructions such as:
+
+```text
+Capture separate desktop and mobile views. Open the new settings dialog and focus the changed controls.
+```
+
+The setting is repository-wide. If the same repository has entries for multiple base branches, ProPR keeps their preview policy synchronized.
+
+The CLI exposes the same policy:
+
+```bash
+propr repo add owner/repo --visual-previews --preview-types image,video \
+  --preview-instructions "Capture desktop and mobile views."
+propr repo toggle owner/repo --visual-previews --preview-types image
+propr repo toggle owner/repo --no-visual-previews
+```
+
+## What The Agent Captures
+
+When enabled, the implementation agent evaluates the completed change:
+
+- If the result is perceptible visually, it captures the changed state with relevant project tooling such as Playwright, Storybook, a browser, an emulator, or a project-native renderer.
+- If the change has no visible result, it does not create placeholder media.
+- Captures focus on the change rather than generic application screens and must not contain credentials, personal data, or unrelated content.
+- If capture is blocked, the agent can recommend the concrete browser, emulator, or media tool that should be added to the agent image.
+
+Generated files live under `.propr/previews/`. Optional titles, descriptions, and tool recommendations are recorded in `.propr/previews/manifest.json`. Only preview files changed by the current implementation commit are published, which prevents an old capture from being presented as evidence for a later change.
+
+Supported image formats are PNG, JPEG, GIF, SVG, and WebP. Supported video formats are MP4, MOV, and WebM; H.264 MP4 is the most broadly compatible choice. Each attachment must be smaller than 10 MB.
+
+## Publication And Fallbacks
+
+ProPR first adds commit-pinned repository links, then attempts to replace them with [GitHub attachments](https://cli.github.com/manual/gh_pr_edit) so images render inline and videos use GitHub's media presentation. When attachment upload is unavailable, images remain embedded from the implementation commit and videos remain explicit links to the committed recording. This keeps the evidence reachable without relying on mutable branch URLs.
+
+Preview generation is evidence, not a replacement for automated tests. A preview failure does not discard an otherwise valid implementation; the PR explains missing tool support when the agent can identify it.
diff --git a/docs/docs/features/web-ui.md b/docs/docs/features/web-ui.md
index 831a1333b..f05c506bb 100644
--- a/docs/docs/features/web-ui.md
+++ b/docs/docs/features/web-ui.md
@@ -45,7 +45,7 @@ These records are the heart of ProPR's observability — see [Observability And
 
 ## Repositories
 
-**Repositories** (`/repositories`) manages the repos ProPR monitors — add, alias, set a base branch, enable/disable, reindex, hide, or delete. The selected repository opens a panel with four tabs:
+**Repositories** (`/repositories`) manages the repos ProPR monitors — add, alias, set a base branch, enable/disable, configure [visual previews](./visual-previews.md), reindex, hide, or delete. Visual preview controls select image/video evidence and optional capture instructions for each repository. The selected repository opens a panel with four tabs:
 
 - **Chat** — converse with the indexed repository;
 - **Improve** — generate categorized improvement suggestions;
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
index b8bde75e4..d379737bf 100644
--- a/docs/sidebars.ts
+++ b/docs/sidebars.ts
@@ -67,6 +67,7 @@ const sidebars: SidebarsConfig = {
       items: [
         'features/pr-followup',
         'features/pr-commands',
+        'features/visual-previews',
       ],
     },
     {
diff --git a/packages/api/routes/configRepoValidation.ts b/packages/api/routes/configRepoValidation.ts
index c5c3a762d..8a335ff96 100644
--- a/packages/api/routes/configRepoValidation.ts
+++ b/packages/api/routes/configRepoValidation.ts
@@ -4,6 +4,9 @@ import { normalizeOptionalBranchName } from './branchNameValidation.js';
 
 const MAX_VISUAL_PREVIEW_INSTRUCTIONS_LENGTH = 4000;
 
+// Keep API input normalization side-effect-free. Importing the core package at
+// runtime initializes GitHub authentication, while this validator is also used
+// by standalone tooling and unit tests.
 function normalizeStoredVisualPreviewSettings(value: unknown): VisualPreviewSettings {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     return { enabled: false, types: ['image'] };
@@ -91,16 +94,23 @@ export function preserveRepoVisualPreview(
   incomingRepos: unknown[]
 ): RepoToMonitor[] {
   const explicitByRepository = new Map<string, VisualPreviewSettings>();
+  const changedByRepository = new Map<string, VisualPreviewSettings>();
   normalizedRepos.forEach((repo, index) => {
     const incoming = incomingRepos[index] as Partial<RepoToMonitor>;
     if (incoming.visualPreview !== undefined) {
-      explicitByRepository.set(repo.name.trim().toLowerCase(), normalizeStoredVisualPreviewSettings(repo.visualPreview));
+      const repositoryKey = repo.name.trim().toLowerCase();
+      const normalized = normalizeStoredVisualPreviewSettings(repo.visualPreview);
+      if (!explicitByRepository.has(repositoryKey)) explicitByRepository.set(repositoryKey, normalized);
+      const previous = previousRepos.find(candidate => candidate.id === repo.id);
+      if (JSON.stringify(normalized) !== JSON.stringify(normalizeStoredVisualPreviewSettings(previous?.visualPreview))) {
+        changedByRepository.set(repositoryKey, normalized);
+      }
     }
   });
 
   return normalizedRepos.map(repo => {
     const repositoryKey = repo.name.trim().toLowerCase();
-    const explicit = explicitByRepository.get(repositoryKey);
+    const explicit = changedByRepository.get(repositoryKey) || explicitByRepository.get(repositoryKey);
     if (explicit) return { ...repo, visualPreview: explicit };
 
     const previous = previousRepos.find(candidate => candidate.name.trim().toLowerCase() === repositoryKey);
@@ -109,6 +119,7 @@ export function preserveRepoVisualPreview(
 }
 
 function normalizeVisualPreviewTypes(value: unknown, repoName: string): ValidationResult<VisualPreviewType[]> {
+  if (value === undefined) return success(['image']);
   if (!Array.isArray(value)) {
     return failure(`Invalid visualPreview.types format for ${repoName}: must be an array`);
   }
diff --git a/packages/api/routes/configRoutes.ts b/packages/api/routes/configRoutes.ts
index 2f32282e7..a0827df6c 100644
--- a/packages/api/routes/configRoutes.ts
+++ b/packages/api/routes/configRoutes.ts
@@ -11,12 +11,7 @@ import { saveSettingsWithRollback } from './configRoutesSettings.js';
 import { saveThenPublishConfigUpdate } from './configRoutesPersistence.js';
 import type { AgentPreparationDeps } from './configRoutesAgentsTypes.js';
 import type { Knex } from 'knex';
-import {
-  normalizeRepoConfig,
-  preserveRepoAutoFollowup,
-  preserveRepoVisualPreview,
-  withDefaultRepoOptions
-} from './configRepoValidation.js';
+import { normalizeRepoConfig, preserveRepoAutoFollowup, preserveRepoVisualPreview, withDefaultRepoOptions } from './configRepoValidation.js';
 
 interface ConfigRoutesDeps {
   redisClient: RedisClientType;
diff --git a/packages/api/test/configRepoRoutes.test.ts b/packages/api/test/configRepoRoutes.test.ts
index 630381b6c..8cf5e5559 100644
--- a/packages/api/test/configRepoRoutes.test.ts
+++ b/packages/api/test/configRepoRoutes.test.ts
@@ -105,7 +105,7 @@ test('POST repository config persists an enabled option without enabling other r
   ]);
 });
 
-test('POST repository config synchronizes visual previews across branch entries', async () => {
+test('POST repository config synchronizes changed visual previews across branch entries', async () => {
   const saveMonitoredRepos = mock.fn(async () => true);
   const routes = createConfigRoutes({
     redisClient: {
@@ -116,7 +116,22 @@ test('POST repository config synchronizes visual previews across branch entries'
       lTrim: mock.fn(async () => 'OK')
     } as never,
     configStore: {
-      loadMonitoredReposRaw: async () => [],
+      loadMonitoredReposRaw: async () => [
+        {
+          id: 'repo-main',
+          name: 'integry/propr',
+          enabled: true,
+          baseBranch: 'main',
+          visualPreview: { enabled: false, types: ['image'] }
+        },
+        {
+          id: 'repo-release',
+          name: 'integry/propr',
+          enabled: true,
+          baseBranch: 'release',
+          visualPreview: { enabled: false, types: ['image'] }
+        }
+      ],
       saveMonitoredRepos,
       clearRemovedRepositoryIndexData: async () => {}
     },
@@ -135,7 +150,13 @@ test('POST repository config synchronizes visual previews across branch entries'
     body: {
       repos_to_monitor: [
         { id: 'repo-main', name: 'integry/propr', enabled: true, baseBranch: 'main', visualPreview },
-        { id: 'repo-release', name: 'integry/propr', enabled: true, baseBranch: 'release' }
+        {
+          id: 'repo-release',
+          name: 'integry/propr',
+          enabled: true,
+          baseBranch: 'release',
+          visualPreview: { enabled: false, types: ['image'] }
+        }
       ]
     }
   } as never, response as never);
diff --git a/packages/api/test/configRepoValidation.test.ts b/packages/api/test/configRepoValidation.test.ts
index c6b4c8280..7b000c453 100644
--- a/packages/api/test/configRepoValidation.test.ts
+++ b/packages/api/test/configRepoValidation.test.ts
@@ -38,6 +38,20 @@ test('repository config accepts visual preview types and trims instructions', ()
   }
 });
 
+test('repository config defaults omitted visual preview types', () => {
+  const normalized = normalizeRepoConfig({
+    id: 'repo-1',
+    name: 'integry/propr',
+    enabled: true,
+    visualPreview: { enabled: false }
+  });
+
+  assert.equal(normalized.ok, true);
+  if (normalized.ok) {
+    assert.deepEqual(normalized.value.visualPreview, { enabled: false, types: ['image'] });
+  }
+});
+
 test('repository config rejects invalid visual preview settings', () => {
   const invalidValues = [
     { enabled: 'true', types: ['image'] },
diff --git a/packages/cli/src/api/index.ts b/packages/cli/src/api/index.ts
index 050dd105e..dd4d116e7 100644
--- a/packages/cli/src/api/index.ts
+++ b/packages/cli/src/api/index.ts
@@ -132,6 +132,7 @@ export {
 
 export type {
   MonitoredRepo,
+  VisualPreviewSettings,
   GetReposResponse,
   AddRepoOptions,
   UpdateRepoOptions,
diff --git a/packages/cli/src/api/repos.test.ts b/packages/cli/src/api/repos.test.ts
index 84f39dd78..7e7f95e83 100644
--- a/packages/cli/src/api/repos.test.ts
+++ b/packages/cli/src/api/repos.test.ts
@@ -4,9 +4,9 @@ import type { ApiClient } from './client.js';
 import { addRepo, updateRepo, type MonitoredRepo } from './repos.js';
 
 function createClient(repos: MonitoredRepo[]): { client: ApiClient; postedRepos: () => MonitoredRepo[] } {
-  let savedRepos: MonitoredRepo[] = [];
+  let savedRepos = repos;
   const client = {
-    get: async () => ({ data: { repos_to_monitor: repos } }),
+    get: async () => ({ data: { repos_to_monitor: savedRepos } }),
     post: async (_path: string, options: { body: { repos_to_monitor: MonitoredRepo[] } }) => {
       savedRepos = options.body.repos_to_monitor;
       return { data: { success: true, repos_to_monitor: savedRepos } };
@@ -28,6 +28,33 @@ test('addRepo preserves existing failed-CI options and defaults the new reposito
 
   assert.equal(postedRepos()[0]?.autoFollowupOnFailedCi, true);
   assert.equal(postedRepos()[1]?.autoFollowupOnFailedCi, false);
+  assert.deepEqual(postedRepos()[1]?.visualPreview, { enabled: false, types: ['image'] });
+});
+
+test('updateRepo merges visual preview fields without dropping existing instructions', async () => {
+  const { client, postedRepos } = createClient([{
+    id: 'repo-1',
+    name: 'integry/propr',
+    enabled: true,
+    autoFollowupOnFailedCi: false,
+    visualPreview: { enabled: false, types: ['image'], instructions: 'Show mobile.' }
+  }]);
+
+  await updateRepo('integry/propr', {
+    visualPreview: { enabled: true, types: ['image', 'video'] }
+  }, client);
+
+  assert.deepEqual(postedRepos()[0]?.visualPreview, {
+    enabled: true,
+    types: ['image', 'video'],
+    instructions: 'Show mobile.'
+  });
+
+  await updateRepo('integry/propr', { visualPreview: { instructions: null } }, client);
+  assert.deepEqual(postedRepos()[0]?.visualPreview, {
+    enabled: true,
+    types: ['image', 'video']
+  });
 });
 
 test('updateRepo writes the failed-CI option without changing other repositories', async () => {
diff --git a/packages/cli/src/api/repos.ts b/packages/cli/src/api/repos.ts
index 149f07750..d1a34c52a 100644
--- a/packages/cli/src/api/repos.ts
+++ b/packages/cli/src/api/repos.ts
@@ -171,6 +171,11 @@ export interface MonitoredRepo {
    */
   autoFollowupOnFailedCi: boolean;
 
+  /**
+   * Visual evidence generated for changes with a user-visible result.
+   */
+  visualPreview?: VisualPreviewSettings;
+
   /**
    * Optional display alias for the repository.
    */
@@ -182,6 +187,12 @@ export interface MonitoredRepo {
   baseBranch?: string;
 }
 
+export interface VisualPreviewSettings {
+  enabled: boolean;
+  types: Array<'image' | 'video'>;
+  instructions?: string;
+}
+
 /**
  * Response from the get repos endpoint.
  */
@@ -215,6 +226,9 @@ export interface AddRepoOptions {
    * Whether failed CI should trigger automatic follow-up work. Defaults to false.
    */
   autoFollowupOnFailedCi?: boolean;
+
+  /** Visual preview policy. Defaults to disabled with image capture selected. */
+  visualPreview?: VisualPreviewSettings;
 }
 
 /**
@@ -240,6 +254,9 @@ export interface UpdateRepoOptions {
    * Optional new automatic failed-CI follow-up state.
    */
   autoFollowupOnFailedCi?: boolean;
+
+  /** Optional visual preview policy update. */
+  visualPreview?: Omit<Partial<VisualPreviewSettings>, 'instructions'> & { instructions?: string | null };
 }
 
 /**
@@ -324,6 +341,7 @@ export async function addRepo(
     name: fullName,
     enabled: options.enabled ?? true,
     autoFollowupOnFailedCi: options.autoFollowupOnFailedCi ?? false,
+    visualPreview: options.visualPreview ?? { enabled: false, types: ['image'] },
     alias: options.alias?.trim() || undefined,
     baseBranch: options.baseBranch?.trim() || undefined,
   };
@@ -379,10 +397,20 @@ export async function updateRepo(
 
   // Apply updates
   const existingRepo = currentRepos.repos_to_monitor[repoIndex];
+  const updatedInstructions = updates.visualPreview?.instructions === undefined
+    ? existingRepo.visualPreview?.instructions
+    : updates.visualPreview.instructions?.trim() || undefined;
   const updatedRepo: MonitoredRepo = {
     ...existingRepo,
     ...(updates.enabled !== undefined && { enabled: updates.enabled }),
     ...(updates.autoFollowupOnFailedCi !== undefined && { autoFollowupOnFailedCi: updates.autoFollowupOnFailedCi }),
+    ...(updates.visualPreview !== undefined && {
+      visualPreview: {
+        enabled: updates.visualPreview.enabled ?? existingRepo.visualPreview?.enabled ?? false,
+        types: updates.visualPreview.types ?? existingRepo.visualPreview?.types ?? ['image'],
+        ...(updatedInstructions ? { instructions: updatedInstructions } : {})
+      }
+    }),
     ...(updates.alias !== undefined && { alias: updates.alias?.trim() || undefined }),
     ...(updates.baseBranch !== undefined && { baseBranch: updates.baseBranch?.trim() || undefined }),
   };
diff --git a/packages/cli/src/commands/repoCommands.test.ts b/packages/cli/src/commands/repoCommands.test.ts
index 9297c8297..2a51c10e4 100644
--- a/packages/cli/src/commands/repoCommands.test.ts
+++ b/packages/cli/src/commands/repoCommands.test.ts
@@ -89,3 +89,25 @@ test("repo toggle accepts positive and negative automatic CI follow-up flags", a
   assert.equal(disabled[0]?.enabled, false);
   assert.equal(disabled[1]?.autoFollowupOnFailedCi, true);
 });
+
+test("repo add and toggle configure visual preview policy", async () => {
+  const added = await runRepoWrite(
+    ["add", "integry/previewed", "--visual-previews", "--preview-types", "image,video", "--preview-instructions", "Show desktop and mobile."],
+    []
+  );
+  assert.deepEqual(added[0]?.visualPreview, {
+    enabled: true,
+    types: ["image", "video"],
+    instructions: "Show desktop and mobile."
+  });
+
+  const disabled = await runRepoWrite(
+    ["toggle", "integry/previewed", "--no-visual-previews"],
+    added
+  );
+  assert.deepEqual(disabled[0]?.visualPreview, {
+    enabled: false,
+    types: ["image", "video"],
+    instructions: "Show desktop and mobile."
+  });
+});
diff --git a/packages/cli/src/commands/repoCommands.ts b/packages/cli/src/commands/repoCommands.ts
index a8b1efff0..8b617a742 100644
--- a/packages/cli/src/commands/repoCommands.ts
+++ b/packages/cli/src/commands/repoCommands.ts
@@ -15,6 +15,7 @@ import {
   getIndexingStatus,
   MonitoredRepo,
   RepositoryIndexingStatus,
+  VisualPreviewSettings,
 } from "../api/index.js";
 import { printOutput } from "../utils/index.js";
 import { classifyApiError, presentApiError } from "../utils/apiErrorPresentation.js";
@@ -26,6 +27,19 @@ function formatEnabled(enabled: boolean): string {
   return enabled ? "Enabled" : "Disabled";
 }
 
+function parseVisualPreviewTypes(value: string | undefined): VisualPreviewSettings['types'] {
+  if (!value) return ['image'];
+  const values = [...new Set(value.split(',').map(type => type.trim().toLowerCase()).filter(Boolean))];
+  if (values.length === 0 || values.some(type => type !== 'image' && type !== 'video')) {
+    throw new Error('Preview types must be a comma-separated list containing image and/or video');
+  }
+  return values as VisualPreviewSettings['types'];
+}
+
+function formatVisualPreview(settings: VisualPreviewSettings | undefined): string {
+  return settings?.enabled ? settings.types.join('+') : 'Disabled';
+}
+
 /**
  * Truncates a string to a maximum length.
  */
@@ -158,6 +172,10 @@ function displayReposTable(repos: MonitoredRepo[]): void {
     "Auto CI follow-up".length,
     ...repos.map((r) => formatEnabled(r.autoFollowupOnFailedCi).length)
   );
+  const visualPreviewWidth = Math.max(
+    "Visual previews".length,
+    ...repos.map((r) => formatVisualPreview(r.visualPreview).length)
+  );
 
   const header = [
     "Repository".padEnd(nameWidth),
@@ -165,6 +183,7 @@ function displayReposTable(repos: MonitoredRepo[]): void {
     "Branch".padEnd(branchWidth),
     "Status".padEnd(statusWidth),
     "Auto CI follow-up".padEnd(autoCiFollowupWidth),
+    "Visual previews".padEnd(visualPreviewWidth),
   ].join("  ");
 
   console.log(header);
@@ -177,6 +196,7 @@ function displayReposTable(repos: MonitoredRepo[]): void {
       (truncate(repo.baseBranch, 20) || "-").padEnd(branchWidth),
       formatEnabled(repo.enabled).padEnd(statusWidth),
       formatEnabled(repo.autoFollowupOnFailedCi).padEnd(autoCiFollowupWidth),
+      formatVisualPreview(repo.visualPreview).padEnd(visualPreviewWidth),
     ].join("  ");
 
     console.log(row);
@@ -249,6 +269,9 @@ Examples:
     .option("-a, --alias <alias>", "Display alias for the repository")
     .option("-b, --branch <branch>", "Base branch name (default: main/master)")
     .option("--auto-ci-followup", "Enable automatic follow-up when CI fails (default: off)")
+    .option("--visual-previews", "Enable visual previews for user-visible changes")
+    .option("--preview-types <types>", "Comma-separated preview types: image,video")
+    .option("--preview-instructions <text>", "Additional visual capture instructions")
     .addHelpText("after", `
 Argument:
   fullName    Repository in owner/repo format
@@ -257,11 +280,12 @@ Examples:
   $ propr repo add myorg/myrepo
   $ propr repo add myorg/myrepo -a "My Project" -b develop
   $ propr repo add myorg/myrepo --auto-ci-followup
+  $ propr repo add myorg/myrepo --visual-previews --preview-types image,video
 `)
     .action(
       async (
         fullName: string,
-        options: { alias?: string; branch?: string; autoCiFollowup?: boolean }
+        options: { alias?: string; branch?: string; autoCiFollowup?: boolean; visualPreviews?: boolean; previewTypes?: string; previewInstructions?: string }
       ) => {
         try {
           if (!fullName.includes("/")) {
@@ -283,11 +307,18 @@ Examples:
 
           console.log(`Adding repository: ${fullName}...`);
 
+          const previewRequested = options.visualPreviews === true || options.previewTypes !== undefined || options.previewInstructions !== undefined;
+
           const result = await addRepo(fullName, {
             alias: options.alias,
             baseBranch: options.branch,
             enabled: true,
             autoFollowupOnFailedCi: options.autoCiFollowup ?? false,
+            visualPreview: {
+              enabled: previewRequested,
+              types: parseVisualPreviewTypes(options.previewTypes),
+              ...(options.previewInstructions?.trim() ? { instructions: options.previewInstructions.trim() } : {})
+            },
           });
 
           if (result.success) {
@@ -302,6 +333,10 @@ Examples:
             console.log(
               `  Automatic CI follow-up: ${formatEnabled(options.autoCiFollowup ?? false)}`
             );
+            console.log(`  Visual previews: ${formatVisualPreview({
+              enabled: previewRequested,
+              types: parseVisualPreviewTypes(options.previewTypes)
+            })}`);
             console.log("");
             console.log(
               `Total monitored repositories: ${result.repos_to_monitor.length}`
@@ -409,28 +444,33 @@ Example:
   // repo toggle
   repo
     .command("toggle <fullName>")
-    .description("Update monitoring or automatic CI follow-up for a repository")
+    .description("Update monitoring, automatic CI follow-up, or visual previews for a repository")
     .option("--enable", "Enable monitoring for the repository")
     .option("--disable", "Disable monitoring for the repository")
     .option("--auto-ci-followup", "Enable automatic follow-up when CI fails")
     .option("--no-auto-ci-followup", "Disable automatic follow-up when CI fails")
+    .option("--visual-previews", "Enable visual previews")
+    .option("--no-visual-previews", "Disable visual previews")
+    .option("--preview-types <types>", "Comma-separated preview types: image,video")
+    .option("--preview-instructions <text>", "Replace visual capture instructions")
     .addHelpText("after", `
 Argument:
   fullName    Repository in owner/repo format
 
 Note:
-  Specify at least one monitoring or automatic CI follow-up option.
+  Specify at least one monitoring, automatic CI follow-up, or visual preview option.
 
 Examples:
   $ propr repo toggle myorg/myrepo --enable
   $ propr repo toggle myorg/myrepo --disable
   $ propr repo toggle myorg/myrepo --auto-ci-followup
   $ propr repo toggle myorg/myrepo --no-auto-ci-followup
+  $ propr repo toggle myorg/myrepo --visual-previews --preview-types image,video
 `)
     .action(
       async (
         fullName: string,
-        options: { enable?: boolean; disable?: boolean; autoCiFollowup?: boolean }
+        options: { enable?: boolean; disable?: boolean; autoCiFollowup?: boolean; visualPreviews?: boolean; previewTypes?: string; previewInstructions?: string }
       ) => {
         try {
           if (options.enable && options.disable) {
@@ -440,9 +480,9 @@ Examples:
             process.exit(1);
           }
 
-          if (!options.enable && !options.disable && options.autoCiFollowup === undefined) {
+          if (!options.enable && !options.disable && options.autoCiFollowup === undefined && options.visualPreviews === undefined && options.previewTypes === undefined && options.previewInstructions === undefined) {
             console.error(
-              "Error: Must specify --enable, --disable, --auto-ci-followup, or --no-auto-ci-followup."
+              "Error: Must specify a monitoring, automatic CI follow-up, or visual preview option."
             );
             console.log("");
             console.log("Usage:");
@@ -450,6 +490,7 @@ Examples:
             console.log(`  propr repo toggle ${fullName} --disable`);
             console.log(`  propr repo toggle ${fullName} --auto-ci-followup`);
             console.log(`  propr repo toggle ${fullName} --no-auto-ci-followup`);
+            console.log(`  propr repo toggle ${fullName} --visual-previews --preview-types image,video`);
             process.exit(1);
           }
 
@@ -463,6 +504,13 @@ Examples:
           }
 
           const enabled = options.enable ? true : options.disable ? false : undefined;
+          const visualPreviewUpdate = options.visualPreviews !== undefined || options.previewTypes !== undefined || options.previewInstructions !== undefined
+            ? {
+                ...(options.visualPreviews !== undefined && { enabled: options.visualPreviews }),
+                ...(options.previewTypes !== undefined && { types: parseVisualPreviewTypes(options.previewTypes) }),
+                ...(options.previewInstructions !== undefined && { instructions: options.previewInstructions.trim() })
+              }
+            : undefined;
           console.log(`Updating repository settings: ${fullName}...`);
 
           const result = await updateRepo(fullName, {
@@ -470,6 +518,7 @@ Examples:
             ...(options.autoCiFollowup !== undefined && {
               autoFollowupOnFailedCi: options.autoCiFollowup,
             }),
+            ...(visualPreviewUpdate && { visualPreview: visualPreviewUpdate }),
           });
 
           if (result.success) {
@@ -483,6 +532,12 @@ Examples:
                 `  Automatic CI follow-up: ${formatEnabled(options.autoCiFollowup)}`
               );
             }
+            if (visualPreviewUpdate) {
+              const previewState = options.visualPreviews === false
+                ? 'Disabled'
+                : options.previewTypes ? parseVisualPreviewTypes(options.previewTypes).join('+') : 'Updated';
+              console.log(`  Visual previews: ${previewState}`);
+            }
           } else {
             console.error("Failed to update repository.");
             process.exit(1);
diff --git a/packages/core/src/claude/prompts/promptGenerator.ts b/packages/core/src/claude/prompts/promptGenerator.ts
index 3666ffa53..e79ad4e00 100644
--- a/packages/core/src/claude/prompts/promptGenerator.ts
+++ b/packages/core/src/claude/prompts/promptGenerator.ts
@@ -1,3 +1,6 @@
+import { buildVisualPreviewPrompt } from '../../services/visualPreviewService.js';
+import type { VisualPreviewSettings } from '../../config/configManager.js';
+
 export interface IssueLabel {
     name: string;
 }
@@ -57,6 +60,7 @@ export interface GenerateClaudePromptOptions {
     modelName?: string | null;
     issueDetails?: IssueDetails | null;
     baseBranch?: string | null;
+    visualPreviewSettings?: VisualPreviewSettings;
 }
 
 function buildIssueDetailsSection(issueRef: IssueRef, issueDetails: IssueDetails): string {
@@ -92,12 +96,13 @@ function buildCommentsSection(comments: IssueComment[] | undefined): string {
 }
 
 export function generateClaudePrompt(options: GenerateClaudePromptOptions): string {
-    const { issueRef, branchName = null, modelName = null, issueDetails = null, baseBranch = null } = options;
+    const { issueRef, branchName = null, modelName = null, issueDetails = null, baseBranch = null, visualPreviewSettings } = options;
 
     const branchInfo = branchName ? `\n- **BRANCH**: You are working on branch \`${branchName}\`.` : '';
     const baseBranchInfo = baseBranch ? `\n- **BASE BRANCH**: \`${baseBranch}\` (PRs must target this branch, not main)` : '';
     const modelInfo = modelName ? `\n- **MODEL**: This task is being processed by the \`${modelName}\` model.` : '';
     const issueDetailsSection = issueDetails ? buildIssueDetailsSection(issueRef, issueDetails) : '';
+    const visualPreviewInstructions = visualPreviewSettings ? buildVisualPreviewPrompt(visualPreviewSettings) : '';
 
     return `Please analyze and implement a solution for GitHub issue #${issueRef.number}.
 
@@ -119,6 +124,7 @@ Follow these steps systematically:
 6. Implement the necessary changes to solve the issue
 7. Test your implementation (if applicable and possible)
 8. Ensure code follows existing patterns and conventions
+${visualPreviewInstructions}
 
 **IMPORTANT NOTES:**
 - **DO NOT** worry about git operations (add, commit, push, PR creation)
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 7846d92c0..6f280b3ac 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -174,6 +174,7 @@ export type { IssueLink, ExecutionResult, EpicPRResult, EnsureEpicPROptions } fr
 export { validateAttachmentBaseUrlConfig } from './services/taskExecutionHelpers.js';
 export { AttachmentService } from './services/attachmentService.js';
 export type { Attachment, MulterFile } from './services/attachmentService.js';
+export * from './services/visualPreviewService.js';
 export { PLANNER_SYSTEM_PROMPT, GRANULARITY_INSTRUCTIONS, getPlannerPrompt, REFINER_SYSTEM_PROMPT } from './claude/prompts/plannerPrompts.js';
 export type { Plan, PlanItem, RefinementResponse } from './claude/prompts/plannerPrompts.js';
 export { parseLlmJson, JsonParseError } from './utils/jsonUtils.js';
diff --git a/packages/core/src/services/visualPreviewService.ts b/packages/core/src/services/visualPreviewService.ts
new file mode 100644
index 000000000..6f41988c8
--- /dev/null
+++ b/packages/core/src/services/visualPreviewService.ts
@@ -0,0 +1,269 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { VisualPreviewSettings, VisualPreviewType } from '../config/configManager.js';
+
+export const VISUAL_PREVIEW_DIRECTORY = '.propr/previews';
+export const VISUAL_PREVIEW_MANIFEST = `${VISUAL_PREVIEW_DIRECTORY}/manifest.json`;
+export const VISUAL_PREVIEW_MARKER = '<!-- propr-visual-preview -->';
+export const VISUAL_PREVIEW_SLOT = '<!-- propr-visual-preview-slot -->';
+
+const MAX_MANIFEST_BYTES = 64 * 1024;
+const MAX_GITHUB_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+const MAX_PREVIEW_ASSETS = 8;
+const IMAGE_EXTENSIONS = new Set(['.gif', '.jpeg', '.jpg', '.png', '.svg', '.webp']);
+const VIDEO_EXTENSIONS = new Set(['.mov', '.mp4', '.webm']);
+
+export interface VisualPreviewAsset {
+  relativePath: string;
+  absolutePath: string;
+  type: VisualPreviewType;
+  title: string;
+  description?: string;
+}
+
+export interface VisualPreviewToolSuggestion {
+  name: string;
+  reason: string;
+}
+
+export interface VisualPreviewEvidence {
+  assets: VisualPreviewAsset[];
+  toolSuggestions: VisualPreviewToolSuggestion[];
+}
+
+interface VisualPreviewManifestEntry {
+  path?: unknown;
+  title?: unknown;
+  description?: unknown;
+}
+
+interface VisualPreviewManifestData {
+  previews?: unknown;
+  toolSuggestions?: unknown;
+}
+
+export interface CollectVisualPreviewEvidenceOptions {
+  worktreePath: string;
+  changedFiles: readonly string[];
+  settings: VisualPreviewSettings;
+}
+
+export interface RenderVisualPreviewOptions {
+  owner: string;
+  repo: string;
+  commitHash: string;
+  useLocalPaths?: boolean;
+}
+
+function previewTypeForPath(filePath: string): VisualPreviewType | null {
+  const extension = path.posix.extname(filePath).toLowerCase();
+  if (IMAGE_EXTENSIONS.has(extension)) return 'image';
+  if (VIDEO_EXTENSIONS.has(extension)) return 'video';
+  return null;
+}
+
+function normalizeRepositoryPath(filePath: string): string | null {
+  const normalized = path.posix.normalize(filePath.replaceAll('\\', '/')).replace(/^\.\//, '');
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+    return null;
+  }
+  return normalized;
+}
+
+function normalizeManifestPath(value: unknown): string | null {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const candidate = value.trim().replaceAll('\\', '/');
+  return normalizeRepositoryPath(candidate.startsWith(`${VISUAL_PREVIEW_DIRECTORY}/`)
+    ? candidate
+    : `${VISUAL_PREVIEW_DIRECTORY}/${candidate}`);
+}
+
+function plainText(value: unknown, maximumLength: number): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value.replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim();
+  return normalized ? normalized.slice(0, maximumLength) : undefined;
+}
+
+function inferredTitle(filePath: string): string {
+  const stem = path.posix.basename(filePath, path.posix.extname(filePath));
+  const title = stem.replace(/[-_]+/g, ' ').replace(/\s{2,}/g, ' ').trim();
+  return title ? title.replace(/^./, character => character.toUpperCase()) : 'Visual preview';
+}
+
+async function readManifest(worktreePath: string, changedFiles: Set<string>): Promise<VisualPreviewManifestData | null> {
+  if (!changedFiles.has(VISUAL_PREVIEW_MANIFEST)) return null;
+  const manifestPath = path.resolve(worktreePath, VISUAL_PREVIEW_MANIFEST);
+  try {
+    const stats = await lstat(manifestPath);
+    if (!stats.isFile() || stats.isSymbolicLink() || stats.size > MAX_MANIFEST_BYTES) return null;
+    const parsed = JSON.parse(await readFile(manifestPath, 'utf8')) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as VisualPreviewManifestData
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function manifestEntriesByPath(manifest: VisualPreviewManifestData | null): Map<string, VisualPreviewManifestEntry> {
+  const entries = new Map<string, VisualPreviewManifestEntry>();
+  if (!Array.isArray(manifest?.previews)) return entries;
+  for (const value of manifest.previews) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
+    const entry = value as VisualPreviewManifestEntry;
+    const normalizedPath = normalizeManifestPath(entry.path);
+    if (normalizedPath) entries.set(normalizedPath, entry);
+  }
+  return entries;
+}
+
+function manifestToolSuggestions(manifest: VisualPreviewManifestData | null): VisualPreviewToolSuggestion[] {
+  if (!Array.isArray(manifest?.toolSuggestions)) return [];
+  return manifest.toolSuggestions.flatMap(value => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return [];
+    const candidate = value as { name?: unknown; reason?: unknown };
+    const name = plainText(candidate.name, 80);
+    const reason = plainText(candidate.reason, 300);
+    return name && reason ? [{ name, reason }] : [];
+  }).slice(0, 5);
+}
+
+async function collectAsset(
+  worktreePath: string,
+  relativePath: string,
+  type: VisualPreviewType,
+  manifestEntry: VisualPreviewManifestEntry | undefined
+): Promise<{ asset?: VisualPreviewAsset; oversized?: boolean }> {
+  const absolutePath = path.resolve(worktreePath, relativePath);
+  const root = path.resolve(worktreePath);
+  if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`)) return {};
+
+  try {
+    const stats = await lstat(absolutePath);
+    if (!stats.isFile() || stats.isSymbolicLink()) return {};
+    if (stats.size === 0) return {};
+    if (stats.size > MAX_GITHUB_ATTACHMENT_BYTES) return { oversized: true };
+  } catch {
+    return {};
+  }
+
+  return {
+    asset: {
+      relativePath,
+      absolutePath,
+      type,
+      title: plainText(manifestEntry?.title, 120) || inferredTitle(relativePath),
+      ...(plainText(manifestEntry?.description, 300)
+        ? { description: plainText(manifestEntry?.description, 300) }
+        : {})
+    }
+  };
+}
+
+export async function collectVisualPreviewEvidence({
+  worktreePath,
+  changedFiles,
+  settings
+}: CollectVisualPreviewEvidenceOptions): Promise<VisualPreviewEvidence> {
+  if (!settings.enabled) return { assets: [], toolSuggestions: [] };
+
+  const normalizedChangedFiles = new Set(changedFiles
+    .map(normalizeRepositoryPath)
+    .filter((filePath): filePath is string => Boolean(filePath)));
+  const manifest = await readManifest(worktreePath, normalizedChangedFiles);
+  const manifestEntries = manifestEntriesByPath(manifest);
+  const toolSuggestions = manifestToolSuggestions(manifest);
+  const candidates = [...normalizedChangedFiles]
+    .filter(filePath => filePath.startsWith(`${VISUAL_PREVIEW_DIRECTORY}/`))
+    .map(filePath => ({ filePath, type: previewTypeForPath(filePath) }))
+    .filter((candidate): candidate is { filePath: string; type: VisualPreviewType } => candidate.type !== null)
+    .filter(candidate => settings.types.includes(candidate.type))
+    .sort((left, right) => left.filePath.localeCompare(right.filePath))
+    .slice(0, MAX_PREVIEW_ASSETS);
+
+  const assets: VisualPreviewAsset[] = [];
+  let oversized = false;
+  for (const candidate of candidates) {
+    const collected = await collectAsset(worktreePath, candidate.filePath, candidate.type, manifestEntries.get(candidate.filePath));
+    if (collected.asset) assets.push(collected.asset);
+    oversized ||= collected.oversized === true;
+  }
+
+  if (oversized) {
+    toolSuggestions.push({
+      name: 'Media compression tooling',
+      reason: 'At least one generated preview exceeded GitHub’s universal 10 MB attachment limit; install or use an image optimizer or ffmpeg to shrink it.'
+    });
+  }
+
+  return { assets, toolSuggestions: toolSuggestions.slice(0, 5) };
+}
+
+function markdownText(value: string): string {
+  return value.replace(/([\\`*_[\]{}()<>#+.!|])/g, '\\$1');
+}
+
+function encodedRepositoryAssetUrl(owner: string, repo: string, commitHash: string, relativePath: string): string {
+  const encodedPath = relativePath.split('/').map(segment => encodeURIComponent(segment)).join('/');
+  return `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/blob/${encodeURIComponent(commitHash)}/${encodedPath}?raw=true`;
+}
+
+function markdownTarget(target: string): string {
+  return /[\s()]/.test(target) ? `<${target.replaceAll('>', '%3E')}>` : target;
+}
+
+export function renderVisualPreviewSection(
+  evidence: VisualPreviewEvidence,
+  options: RenderVisualPreviewOptions
+): string {
+  if (evidence.assets.length === 0 && evidence.toolSuggestions.length === 0) return '';
+  const parts = [VISUAL_PREVIEW_MARKER, '## Visual preview'];
+
+  for (const asset of evidence.assets) {
+    const target = options.useLocalPaths
+      ? asset.absolutePath
+      : encodedRepositoryAssetUrl(options.owner, options.repo, options.commitHash, asset.relativePath);
+    parts.push(`### ${markdownText(asset.title)}`);
+    if (asset.type === 'video' && !options.useLocalPaths) {
+      parts.push(`[Watch ${markdownText(asset.title)}](${markdownTarget(target)})`);
+    } else {
+      parts.push(`![${asset.type === 'image' ? markdownText(asset.title) : ''}](${markdownTarget(target)})`);
+    }
+    if (asset.description) parts.push(markdownText(asset.description));
+  }
+
+  if (evidence.toolSuggestions.length > 0) {
+    parts.push('### Suggested agent tools');
+    parts.push(evidence.toolSuggestions
+      .map(suggestion => `- **${markdownText(suggestion.name)}:** ${markdownText(suggestion.reason)}`)
+      .join('\n'));
+  }
+
+  return parts.join('\n\n');
+}
+
+export function appendVisualPreviewSection(body: string, section: string): string {
+  if (!section) return body.replace(VISUAL_PREVIEW_SLOT, '').replace(/\n{3,}/g, '\n\n').trim();
+  if (body.includes(VISUAL_PREVIEW_SLOT)) return body.replace(VISUAL_PREVIEW_SLOT, section);
+  return `${body.trim()}\n\n---\n\n${section}`;
+}
+
+export function buildVisualPreviewPrompt(settings: VisualPreviewSettings): string {
+  if (!settings.enabled) return '';
+  const requestedTypes = settings.types.join(' and ');
+  const additionalInstructions = settings.instructions
+    ? `\nRepository-specific capture instructions (apply only to preview generation):\n${settings.instructions}\n`
+    : '';
+
+  return `
+**VISUAL PREVIEW REQUIREMENT:**
+Visual previews are enabled for this repository. After implementing and testing, decide whether the result is perceptible visually to a user. If it is not visually perceptible, do not create preview files. If it is visually perceptible:
+- Treat previews as evidence only: never expand the implementation scope, and do not create or update preview files when the current request produces no implementation changes.
+- Generate focused ${requestedTypes} preview evidence of the current change using the project’s existing, relevant tooling (for example a headless browser, Storybook, an Android/iOS emulator, or a project-native renderer).
+- Capture the changed state itself, not generic application screens. Use realistic viewport/device states and follow the repository-specific instructions below when present.
+- Store each preview under \`${VISUAL_PREVIEW_DIRECTORY}/\` using portable filenames and only these formats: PNG/JPEG/GIF/SVG/WebP for images; MP4/MOV/WebM for videos. Keep every file below 10 MB. For video, prefer H.264 in MP4 for browser compatibility.
+- Write \`${VISUAL_PREVIEW_MANIFEST}\` with this shape: \`{"previews":[{"path":".propr/previews/desktop.png","title":"Desktop dialog","description":"The changed dialog at desktop width"}],"toolSuggestions":[{"name":"Playwright Chromium","reason":"Needed to capture the running web UI"}]}\`. The manifest may contain an empty previews array when capture is blocked.
+- Do not fabricate a preview or hand-draw a substitute. If the project cannot be run or the needed capture tool is unavailable, record concise, actionable \`toolSuggestions\` in the manifest describing what should be installed in the agent image and why.
+- Never include credentials, tokens, personal data, or unrelated screens in preview media.
+${additionalInstructions}`;
+}
diff --git a/packages/core/test/visualPreviewService.test.ts b/packages/core/test/visualPreviewService.test.ts
new file mode 100644
index 000000000..8feb05d71
--- /dev/null
+++ b/packages/core/test/visualPreviewService.test.ts
@@ -0,0 +1,141 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, test } from 'node:test';
+import {
+  appendVisualPreviewSection,
+  buildVisualPreviewPrompt,
+  collectVisualPreviewEvidence,
+  renderVisualPreviewSection,
+  VISUAL_PREVIEW_MARKER,
+  VISUAL_PREVIEW_SLOT
+} from '../src/services/visualPreviewService.js';
+
+const temporaryDirectories: string[] = [];
+
+async function createWorktree(): Promise<string> {
+  const worktree = await mkdtemp(path.join(tmpdir(), 'propr-visual-preview-'));
+  temporaryDirectories.push(worktree);
+  await mkdir(path.join(worktree, '.propr/previews'), { recursive: true });
+  return worktree;
+}
+
+afterEach(async () => {
+  await Promise.all(temporaryDirectories.splice(0).map(directory => rm(directory, { recursive: true, force: true })));
+});
+
+test('visual preview prompt is conditional and carries repository instructions', () => {
+  assert.equal(buildVisualPreviewPrompt({ enabled: false, types: ['image'] }), '');
+  const prompt = buildVisualPreviewPrompt({
+    enabled: true,
+    types: ['image', 'video'],
+    instructions: 'Capture separate desktop and mobile views.'
+  });
+
+  assert.match(prompt, /perceptible visually/);
+  assert.match(prompt, /never expand the implementation scope/);
+  assert.match(prompt, /\.propr\/previews\/manifest\.json/);
+  assert.match(prompt, /image and video/);
+  assert.match(prompt, /Capture separate desktop and mobile views\./);
+  assert.match(prompt, /toolSuggestions/);
+});
+
+test('collects only changed, selected, regular preview files and applies manifest metadata', async () => {
+  const worktree = await createWorktree();
+  await writeFile(path.join(worktree, '.propr/previews/desktop.png'), 'png');
+  await writeFile(path.join(worktree, '.propr/previews/empty.png'), '');
+  await writeFile(path.join(worktree, '.propr/previews/walkthrough.mp4'), 'video');
+  await writeFile(path.join(worktree, 'outside.png'), 'outside');
+  await symlink(path.join(worktree, 'outside.png'), path.join(worktree, '.propr/previews/symlink.png'));
+  await writeFile(path.join(worktree, '.propr/previews/manifest.json'), JSON.stringify({
+    previews: [{
+      path: 'desktop.png',
+      title: 'Changed settings [desktop]',
+      description: 'The new preview controls.'
+    }],
+    toolSuggestions: [{ name: 'Android emulator', reason: 'Capture the native mobile layout.' }]
+  }));
+
+  const evidence = await collectVisualPreviewEvidence({
+    worktreePath: worktree,
+    changedFiles: [
+      '.propr/previews/desktop.png',
+      '.propr/previews/empty.png',
+      '.propr/previews/walkthrough.mp4',
+      '.propr/previews/symlink.png',
+      '.propr/previews/manifest.json',
+      'outside.png'
+    ],
+    settings: { enabled: true, types: ['image'] }
+  });
+
+  assert.deepEqual(evidence.assets.map(asset => ({
+    relativePath: asset.relativePath,
+    type: asset.type,
+    title: asset.title,
+    description: asset.description
+  })), [{
+    relativePath: '.propr/previews/desktop.png',
+    type: 'image',
+    title: 'Changed settings [desktop]',
+    description: 'The new preview controls.'
+  }]);
+  assert.deepEqual(evidence.toolSuggestions, [{
+    name: 'Android emulator',
+    reason: 'Capture the native mobile layout.'
+  }]);
+});
+
+test('renders upload-ready local media and stable committed-file fallbacks', async () => {
+  const worktree = await createWorktree();
+  const relativePath = '.propr/previews/desktop view.png';
+  const absolutePath = path.join(worktree, relativePath);
+  await writeFile(absolutePath, 'png');
+  const evidence = {
+    assets: [{
+      relativePath,
+      absolutePath,
+      type: 'image' as const,
+      title: 'Settings [desktop]',
+      description: 'Focused on the changed controls.'
+    }],
+    toolSuggestions: []
+  };
+
+  const local = renderVisualPreviewSection(evidence, {
+    owner: 'integry', repo: 'propr', commitHash: 'abc123', useLocalPaths: true
+  });
+  assert.match(local, new RegExp(VISUAL_PREVIEW_MARKER));
+  assert.match(local, /Settings \\\[desktop\\\]/);
+  assert.match(local, /\(<.*desktop view\.png>\)/);
+
+  const fallback = renderVisualPreviewSection(evidence, {
+    owner: 'integry', repo: 'propr', commitHash: 'abc123'
+  });
+  assert.match(fallback, /github\.com\/integry\/propr\/blob\/abc123\/\.propr\/previews\/desktop%20view\.png\?raw=true/);
+  assert.equal(appendVisualPreviewSection(`Before\n\n${VISUAL_PREVIEW_SLOT}\n\nAfter`, fallback), `Before\n\n${fallback}\n\nAfter`);
+});
+
+test('renders committed videos as playable links and local videos as upload references', () => {
+  const evidence = {
+    assets: [{
+      relativePath: '.propr/previews/walkthrough.mp4',
+      absolutePath: '/worktree/.propr/previews/walkthrough.mp4',
+      type: 'video' as const,
+      title: 'Settings walkthrough'
+    }],
+    toolSuggestions: []
+  };
+
+  const local = renderVisualPreviewSection(evidence, {
+    owner: 'integry', repo: 'propr', commitHash: 'abc123', useLocalPaths: true
+  });
+  assert.match(local, /!\[\]\(\/worktree\/\.propr\/previews\/walkthrough\.mp4\)/);
+
+  const fallback = renderVisualPreviewSection(evidence, {
+    owner: 'integry', repo: 'propr', commitHash: 'abc123'
+  });
+  assert.match(fallback, /\[Watch Settings walkthrough\]\(https:\/\/github\.com\/integry\/propr\/blob\/abc123\/\.propr\/previews\/walkthrough\.mp4\?raw=true\)/);
+  assert.doesNotMatch(fallback, /!\[\]/);
+});
diff --git a/propr-ui/src/components/RepositoryListItem.tsx b/propr-ui/src/components/RepositoryListItem.tsx
index 1e05a4a19..c6bde3f95 100644
--- a/propr-ui/src/components/RepositoryListItem.tsx
+++ b/propr-ui/src/components/RepositoryListItem.tsx
@@ -1,8 +1,9 @@
-import React, { useEffect, useState } from 'react';
-import { Github, RefreshCw, Star, Eye, EyeOff, Image, Video } from 'lucide-react';
+import React, { useState } from 'react';
+import { Github, RefreshCw, Star, Eye, EyeOff } from 'lucide-react';
 import { DeleteRepoDialog } from './DeleteRepoDialog';
 import { RepositoryIndexingStatus, MonitoredRepo } from '../api/proprApi';
 import { getRepoStatusKey } from '../api/repoIndexingApi';
+import { RepositoryVisualPreviewControl, type RepositoryVisualPreviewSettings } from './RepositoryVisualPreviewControl';
 
 type RepoStatusType = 'indexed' | 'indexing' | 'failed' | 'idle';
 
@@ -222,95 +223,12 @@ const AutoCiFollowupControl: React.FC<{
   );
 };
 
-type VisualPreviewSettings = NonNullable<MonitoredRepo['visualPreview']>;
-
-const VisualPreviewControl: React.FC<{
-  repo: MonitoredRepo;
-  onUpdate: (repoId: string, settings: VisualPreviewSettings) => void;
-  isReadOnly: boolean;
-}> = ({ repo, onUpdate, isReadOnly }) => {
-  const settings: VisualPreviewSettings = repo.visualPreview || { enabled: false, types: ['image'] };
-  const [instructions, setInstructions] = useState(settings.instructions || '');
-
-  useEffect(() => setInstructions(settings.instructions || ''), [settings.instructions]);
-
-  if (isReadOnly) return null;
-
-  const toggleType = (type: 'image' | 'video') => {
-    const selected = settings.types.includes(type);
-    if (selected && settings.types.length === 1) return;
-    onUpdate(repo.id, {
-      ...settings,
-      types: selected ? settings.types.filter(candidate => candidate !== type) : [...settings.types, type]
-    });
-  };
-
-  return (
-    <div className="mt-2 text-[11px] text-slate-600" onClick={(event) => event.stopPropagation()}>
-      <label className="inline-flex items-center gap-2 cursor-pointer" title="Generate focused media for changes with a visible result">
-        <input
-          type="checkbox"
-          checked={settings.enabled}
-          onChange={() => onUpdate(repo.id, { ...settings, enabled: !settings.enabled })}
-          className="sr-only peer"
-          aria-label={`Visual previews for ${repo.name}`}
-        />
-        <span className="relative w-7 h-4 bg-slate-200 rounded-full peer-focus:ring-2 peer-focus:ring-teal-500/20 peer-checked:bg-teal-500 after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:h-3 after:w-3 after:rounded-full after:bg-white after:border after:border-slate-300 after:transition-all peer-checked:after:translate-x-full" />
-        <span>Visual previews</span>
-        <span className={`rounded px-1.5 py-0.5 font-medium ${settings.enabled ? 'bg-teal-50 text-teal-700' : 'bg-slate-100 text-slate-500'}`}>
-          {settings.enabled ? 'On' : 'Off'}
-        </span>
-      </label>
-
-      {settings.enabled && (
-        <div className="mt-2 ml-9 space-y-2" onClick={(event) => event.stopPropagation()}>
-          <div className="flex flex-wrap items-center gap-2">
-            <button
-              type="button"
-              onClick={() => toggleType('image')}
-              className={`inline-flex items-center gap-1 rounded border px-2 py-1 transition-colors ${settings.types.includes('image') ? 'border-teal-300 bg-teal-50 text-teal-700' : 'border-slate-200 bg-white text-slate-500'}`}
-              aria-pressed={settings.types.includes('image')}
-              title={settings.types.length === 1 && settings.types.includes('image') ? 'At least one preview type is required' : 'Include image previews'}
-            >
-              <Image className="h-3 w-3" /> Images
-            </button>
-            <button
-              type="button"
-              onClick={() => toggleType('video')}
-              className={`inline-flex items-center gap-1 rounded border px-2 py-1 transition-colors ${settings.types.includes('video') ? 'border-teal-300 bg-teal-50 text-teal-700' : 'border-slate-200 bg-white text-slate-500'}`}
-              aria-pressed={settings.types.includes('video')}
-              title={settings.types.length === 1 && settings.types.includes('video') ? 'At least one preview type is required' : 'Include video previews'}
-            >
-              <Video className="h-3 w-3" /> Videos
-            </button>
-          </div>
-          <textarea
-            value={instructions}
-            onChange={(event) => setInstructions(event.target.value)}
-            onBlur={() => {
-              const normalized = instructions.trim();
-              if (normalized !== (settings.instructions || '')) {
-                onUpdate(repo.id, { ...settings, instructions: normalized || undefined });
-              }
-            }}
-            maxLength={4000}
-            rows={2}
-            className="w-full max-w-sm resize-y rounded border border-slate-200 bg-white px-2 py-1.5 text-[11px] text-slate-700 placeholder:text-slate-400 focus:border-teal-400 focus:outline-none focus:ring-1 focus:ring-teal-400"
-            placeholder="Optional: capture separate desktop and mobile views…"
-            aria-label={`Visual preview instructions for ${repo.name}`}
-          />
-        </div>
-      )}
-    </div>
-  );
-};
-
 interface RepositoryListItemProps {
   repo: MonitoredRepo;
   indexingStatuses: Record<string, RepositoryIndexingStatus>;
   onToggle: (repoId: string) => void;
   onToggleAutoCiFollowup: (repoId: string) => void;
-  onUpdateVisualPreview: (repoId: string, settings: VisualPreviewSettings) => void;
+  onUpdateVisualPreview: (repoId: string, settings: RepositoryVisualPreviewSettings) => void;
   onRemove: (repoId: string) => void | Promise<void>;
   onStopIndexing: (repoName: string, baseBranch?: string) => void;
   onReindex: (repoName: string, baseBranch?: string) => void;
@@ -445,7 +363,7 @@ export const RepositoryListItem: React.FC<RepositoryListItemProps> = ({
             onToggle={onToggleAutoCiFollowup}
             isReadOnly={isReadOnly}
           />
-          <VisualPreviewControl
+          <RepositoryVisualPreviewControl
             repo={repo}
             onUpdate={onUpdateVisualPreview}
             isReadOnly={isReadOnly}
diff --git a/propr-ui/src/components/RepositoryVisualPreviewControl.test.tsx b/propr-ui/src/components/RepositoryVisualPreviewControl.test.tsx
new file mode 100644
index 000000000..7fde9edcd
--- /dev/null
+++ b/propr-ui/src/components/RepositoryVisualPreviewControl.test.tsx
@@ -0,0 +1,38 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { MonitoredRepo } from '../api/proprApi';
+import { RepositoryVisualPreviewControl } from './RepositoryVisualPreviewControl';
+
+const repo: MonitoredRepo = {
+  id: 'repo-1',
+  name: 'integry/propr',
+  enabled: true,
+  visualPreview: { enabled: true, types: ['image'] }
+};
+
+describe('RepositoryVisualPreviewControl', () => {
+  it('updates preview types and preserves edited instructions', () => {
+    const onUpdate = vi.fn();
+    render(<RepositoryVisualPreviewControl repo={repo} onUpdate={onUpdate} isReadOnly={false} />);
+
+    fireEvent.change(screen.getByRole('textbox', { name: 'Visual preview instructions for integry/propr' }), {
+      target: { value: '  Capture the responsive menu.  ' }
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Videos' }));
+
+    expect(onUpdate).toHaveBeenLastCalledWith('repo-1', {
+      enabled: true,
+      types: ['image', 'video'],
+      instructions: 'Capture the responsive menu.'
+    });
+  });
+
+  it('keeps at least one preview type selected', () => {
+    const onUpdate = vi.fn();
+    render(<RepositoryVisualPreviewControl repo={repo} onUpdate={onUpdate} isReadOnly={false} />);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Images' }));
+
+    expect(onUpdate).not.toHaveBeenCalled();
+  });
+});
diff --git a/propr-ui/src/components/RepositoryVisualPreviewControl.tsx b/propr-ui/src/components/RepositoryVisualPreviewControl.tsx
new file mode 100644
index 000000000..cac3bc44b
--- /dev/null
+++ b/propr-ui/src/components/RepositoryVisualPreviewControl.tsx
@@ -0,0 +1,96 @@
+import React, { useEffect, useState } from 'react';
+import { Image, Video } from 'lucide-react';
+import type { MonitoredRepo } from '../api/proprApi';
+
+export type RepositoryVisualPreviewSettings = NonNullable<MonitoredRepo['visualPreview']>;
+
+interface RepositoryVisualPreviewControlProps {
+  repo: MonitoredRepo;
+  onUpdate: (repoId: string, settings: RepositoryVisualPreviewSettings) => void;
+  isReadOnly: boolean;
+}
+
+export const RepositoryVisualPreviewControl: React.FC<RepositoryVisualPreviewControlProps> = ({ repo, onUpdate, isReadOnly }) => {
+  const settings: RepositoryVisualPreviewSettings = repo.visualPreview || { enabled: false, types: ['image'] };
+  const [instructions, setInstructions] = useState(settings.instructions || '');
+
+  useEffect(() => setInstructions(settings.instructions || ''), [settings.instructions]);
+
+  if (isReadOnly) return null;
+
+  const settingsWithCurrentInstructions = (): RepositoryVisualPreviewSettings => {
+    const normalizedInstructions = instructions.trim();
+    return {
+      ...settings,
+      ...(normalizedInstructions ? { instructions: normalizedInstructions } : { instructions: undefined })
+    };
+  };
+
+  const toggleType = (type: 'image' | 'video') => {
+    const selected = settings.types.includes(type);
+    if (selected && settings.types.length === 1) return;
+    onUpdate(repo.id, {
+      ...settingsWithCurrentInstructions(),
+      types: selected ? settings.types.filter(candidate => candidate !== type) : [...settings.types, type]
+    });
+  };
+
+  return (
+    <div className="mt-2 text-[11px] text-slate-600" onClick={(event) => event.stopPropagation()}>
+      <label className="inline-flex items-center gap-2 cursor-pointer" title="Generate focused media for changes with a visible result">
+        <input
+          type="checkbox"
+          checked={settings.enabled}
+          onChange={() => onUpdate(repo.id, { ...settingsWithCurrentInstructions(), enabled: !settings.enabled })}
+          className="sr-only peer"
+          aria-label={`Visual previews for ${repo.name}`}
+        />
+        <span className="relative w-7 h-4 bg-slate-200 rounded-full peer-focus:ring-2 peer-focus:ring-teal-500/20 peer-checked:bg-teal-500 after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:h-3 after:w-3 after:rounded-full after:bg-white after:border after:border-slate-300 after:transition-all peer-checked:after:translate-x-full" />
+        <span>Visual previews</span>
+        <span className={`rounded px-1.5 py-0.5 font-medium ${settings.enabled ? 'bg-teal-50 text-teal-700' : 'bg-slate-100 text-slate-500'}`}>
+          {settings.enabled ? 'On' : 'Off'}
+        </span>
+      </label>
+
+      {settings.enabled && (
+        <div className="mt-2 ml-9 space-y-2" onClick={(event) => event.stopPropagation()}>
+          <div className="flex flex-wrap items-center gap-2">
+            <button
+              type="button"
+              onClick={() => toggleType('image')}
+              className={`inline-flex items-center gap-1 rounded border px-2 py-1 transition-colors ${settings.types.includes('image') ? 'border-teal-300 bg-teal-50 text-teal-700' : 'border-slate-200 bg-white text-slate-500'}`}
+              aria-pressed={settings.types.includes('image')}
+              title={settings.types.length === 1 && settings.types.includes('image') ? 'At least one preview type is required' : 'Include image previews'}
+            >
+              <Image className="h-3 w-3" /> Images
+            </button>
+            <button
+              type="button"
+              onClick={() => toggleType('video')}
+              className={`inline-flex items-center gap-1 rounded border px-2 py-1 transition-colors ${settings.types.includes('video') ? 'border-teal-300 bg-teal-50 text-teal-700' : 'border-slate-200 bg-white text-slate-500'}`}
+              aria-pressed={settings.types.includes('video')}
+              title={settings.types.length === 1 && settings.types.includes('video') ? 'At least one preview type is required' : 'Include video previews'}
+            >
+              <Video className="h-3 w-3" /> Videos
+            </button>
+          </div>
+          <textarea
+            value={instructions}
+            onChange={(event) => setInstructions(event.target.value)}
+            onBlur={() => {
+              const normalized = instructions.trim();
+              if (normalized !== (settings.instructions || '')) {
+                onUpdate(repo.id, settingsWithCurrentInstructions());
+              }
+            }}
+            maxLength={4000}
+            rows={2}
+            className="w-full max-w-sm resize-y rounded border border-slate-200 bg-white px-2 py-1.5 text-[11px] text-slate-700 placeholder:text-slate-400 focus:border-teal-400 focus:outline-none focus:ring-1 focus:ring-teal-400"
+            placeholder="Optional: capture separate desktop and mobile views…"
+            aria-label={`Visual preview instructions for ${repo.name}`}
+          />
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/propr-ui/src/hooks/repositoryVisualPreview.ts b/propr-ui/src/hooks/repositoryVisualPreview.ts
new file mode 100644
index 000000000..50a7811f0
--- /dev/null
+++ b/propr-ui/src/hooks/repositoryVisualPreview.ts
@@ -0,0 +1,61 @@
+import type { MonitoredRepo } from '../api/proprApi';
+
+export type VisualPreviewSettings = NonNullable<MonitoredRepo['visualPreview']>;
+
+export type ManagedRepo = Omit<MonitoredRepo, 'autoFollowupOnFailedCi' | 'visualPreview'> & {
+  autoFollowupOnFailedCi: boolean;
+  visualPreview: VisualPreviewSettings;
+};
+
+export const getRepositoryConfigKey = (name: string): string => name.trim().toLowerCase();
+
+export const defaultVisualPreview = (): VisualPreviewSettings => ({ enabled: false, types: ['image'] });
+
+export function parseVisualPreview(value: unknown): VisualPreviewSettings {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return defaultVisualPreview();
+  const candidate = value as Record<string, unknown>;
+  const types = Array.isArray(candidate.types)
+    ? [...new Set(candidate.types.filter((type): type is 'image' | 'video' => type === 'image' || type === 'video'))]
+    : [];
+  const instructions = typeof candidate.instructions === 'string' && candidate.instructions.trim()
+    ? candidate.instructions.trim()
+    : undefined;
+  return {
+    enabled: candidate.enabled === true,
+    types: types.length > 0 ? types : ['image'],
+    ...(instructions ? { instructions } : {})
+  };
+}
+
+export function updateRepositoryVisualPreview(
+  repos: ManagedRepo[],
+  repoId: string,
+  settings: VisualPreviewSettings
+): ManagedRepo[] {
+  const targetRepo = repos.find(repo => repo.id === repoId);
+  if (!targetRepo) return repos;
+  const repositoryKey = getRepositoryConfigKey(targetRepo.name);
+  const normalizedSettings = parseVisualPreview(settings);
+  return repos.map(repo => getRepositoryConfigKey(repo.name) === repositoryKey
+    ? { ...repo, visualPreview: normalizedSettings }
+    : repo);
+}
+
+export function buildRepositoriesForDisplay(repos: ManagedRepo[]): ManagedRepo[] {
+  const autoCiFollowupByRepository = new Map<string, boolean>();
+  const visualPreviewByRepository = new Map<string, VisualPreviewSettings>();
+  for (const repo of repos) {
+    const key = getRepositoryConfigKey(repo.name);
+    autoCiFollowupByRepository.set(key, autoCiFollowupByRepository.get(key) === true || repo.autoFollowupOnFailedCi);
+    const previousPreview = visualPreviewByRepository.get(key);
+    if (!previousPreview || (!previousPreview.enabled && repo.visualPreview.enabled)) {
+      visualPreviewByRepository.set(key, repo.visualPreview);
+    }
+  }
+
+  return repos.map(repo => ({
+    ...repo,
+    autoFollowupOnFailedCi: autoCiFollowupByRepository.get(getRepositoryConfigKey(repo.name)) === true,
+    visualPreview: visualPreviewByRepository.get(getRepositoryConfigKey(repo.name)) || defaultVisualPreview()
+  }));
+}
diff --git a/propr-ui/src/hooks/useRepositoryManagement.test.tsx b/propr-ui/src/hooks/useRepositoryManagement.test.tsx
index 90b0d9f43..8d1d1a9df 100644
--- a/propr-ui/src/hooks/useRepositoryManagement.test.tsx
+++ b/propr-ui/src/hooks/useRepositoryManagement.test.tsx
@@ -174,11 +174,13 @@ describe('useRepositoryManagement', () => {
       name: 'integry/propr',
       enabled: true,
       autoFollowupOnFailedCi: false,
+      visualPreview: { enabled: false, types: ['image'] },
       baseBranch: 'release/2026'
     });
 
     act(() => result.current.handleToggleRepo(result.current.repos[0].id));
     act(() => result.current.handleToggleAutoCiFollowup(result.current.repos[0].id));
+    act(() => result.current.handleUpdateVisualPreview(result.current.repos[0].id, { enabled: true, types: ['video'] }));
 
     expect(result.current.repos[0].enabled).toBe(true);
     expect(result.current.repos[0].autoFollowupOnFailedCi).toBe(false);
@@ -197,6 +199,39 @@ describe('useRepositoryManagement', () => {
     await waitFor(() => expect(result.current.loading).toBe(false));
 
     expect(result.current.repos.map(repo => repo.autoFollowupOnFailedCi)).toEqual([true, false]);
+    expect(result.current.repos.map(repo => repo.visualPreview)).toEqual([
+      { enabled: false, types: ['image'] },
+      { enabled: false, types: ['image'] }
+    ]);
+  });
+
+  it('synchronizes visual preview settings across repository branch entries', async () => {
+    mockGetRepoConfig.mockResolvedValue({
+      repos_to_monitor: [
+        { id: 'repo-main', name: 'integry/propr', enabled: true, baseBranch: 'main' },
+        { id: 'repo-release', name: 'INTEGRY/PROPR', enabled: true, baseBranch: 'release' },
+        { id: 'repo-other', name: 'integry/other', enabled: true }
+      ]
+    });
+
+    const { result } = renderHook(() => useRepositoryManagement());
+    await waitFor(() => expect(result.current.loading).toBe(false));
+
+    act(() => result.current.handleUpdateVisualPreview('repo-main', {
+      enabled: true,
+      types: ['image', 'video'],
+      instructions: 'Capture desktop and mobile.'
+    }));
+    await waitFor(() => expect(mockUpdateRepoConfig).toHaveBeenCalledTimes(1));
+
+    const savedRepos = mockUpdateRepoConfig.mock.calls[0][0];
+    expect(savedRepos[0].visualPreview).toEqual(savedRepos[1].visualPreview);
+    expect(savedRepos[0].visualPreview).toEqual({
+      enabled: true,
+      types: ['image', 'video'],
+      instructions: 'Capture desktop and mobile.'
+    });
+    expect(savedRepos[2].visualPreview).toEqual({ enabled: false, types: ['image'] });
   });
 
   it('adds the selected automatic CI setting without changing existing repositories', async () => {
diff --git a/propr-ui/src/hooks/useRepositoryManagement.ts b/propr-ui/src/hooks/useRepositoryManagement.ts
index 4449a1550..573f87be4 100644
--- a/propr-ui/src/hooks/useRepositoryManagement.ts
+++ b/propr-ui/src/hooks/useRepositoryManagement.ts
@@ -7,7 +7,6 @@ import {
   getRepositoriesIndexingStatus,
   stopRepositoryIndexing,
   RepositoryIndexingStatus,
-  MonitoredRepo,
   getUserRepoPreferences,
   updateUserRepoPreferences,
   UserRepoPreferences
@@ -18,10 +17,18 @@ import { IndexingUpdatePayload } from '@propr/shared';
 import { buildUpdatedStatus } from '../utils/indexingStatusHelpers';
 import { useCurrentUser, userHasPermission } from '../contexts/AuthContext';
 import { isCommittedConfigWriteError } from '../api/apiClient';
+import {
+  buildRepositoriesForDisplay,
+  defaultVisualPreview,
+  getRepositoryConfigKey,
+  parseVisualPreview,
+  updateRepositoryVisualPreview,
+  type ManagedRepo,
+  type VisualPreviewSettings
+} from './repositoryVisualPreview';
 
 const generateId = (): string => crypto.randomUUID();
 const TERMINAL_INDEXING_STATUSES = new Set<RepositoryIndexingStatus['indexing_status']>(['idle', 'completed', 'failed']);
-const getRepositoryConfigKey = (name: string): string => name.trim().toLowerCase();
 
 function shouldIgnoreStaleProgressUpdate(
   payload: IndexingUpdatePayload,
@@ -39,30 +46,7 @@ function shouldIgnoreStaleProgressUpdate(
   return currentStatus ? hasSeenTerminalSocketUpdate && TERMINAL_INDEXING_STATUSES.has(currentStatus.indexing_status) : false;
 }
 
-export type VisualPreviewSettings = NonNullable<MonitoredRepo['visualPreview']>;
-
-export type Repo = Omit<MonitoredRepo, 'autoFollowupOnFailedCi' | 'visualPreview'> & {
-  autoFollowupOnFailedCi: boolean;
-  visualPreview: VisualPreviewSettings;
-};
-
-const defaultVisualPreview = (): VisualPreviewSettings => ({ enabled: false, types: ['image'] });
-
-function parseVisualPreview(value: unknown): VisualPreviewSettings {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return defaultVisualPreview();
-  const candidate = value as Record<string, unknown>;
-  const types = Array.isArray(candidate.types)
-    ? [...new Set(candidate.types.filter((type): type is 'image' | 'video' => type === 'image' || type === 'video'))]
-    : [];
-  const instructions = typeof candidate.instructions === 'string' && candidate.instructions.trim()
-    ? candidate.instructions.trim()
-    : undefined;
-  return {
-    enabled: candidate.enabled === true,
-    types: types.length > 0 ? types : ['image'],
-    ...(instructions ? { instructions } : {})
-  };
-}
+export type Repo = ManagedRepo;
 
 export interface UseRepositoryManagementResult {
   repos: Repo[];
@@ -381,13 +365,8 @@ export function useRepositoryManagement(): UseRepositoryManagementResult {
 
   const handleUpdateVisualPreview = (repoId: string, settings: VisualPreviewSettings) => {
     if (!canManageRepositories) return;
-    const targetRepo = repos.find(repo => repo.id === repoId);
-    if (!targetRepo) return;
-    const repositoryKey = getRepositoryConfigKey(targetRepo.name);
-    const normalizedSettings = parseVisualPreview(settings);
-    const newRepos = repos.map(repo => getRepositoryConfigKey(repo.name) === repositoryKey
-      ? { ...repo, visualPreview: normalizedSettings }
-      : repo);
+    const newRepos = updateRepositoryVisualPreview(repos, repoId, settings);
+    if (newRepos === repos) return;
     setRepos(newRepos);
     performAutoSave(newRepos);
   };
@@ -426,21 +405,7 @@ export function useRepositoryManagement(): UseRepositoryManagementResult {
   const handleRetry = () => { setError(null); void loadRepos().catch(() => undefined); };
 
   const hiddenCount = repos.filter(r => r.hidden).length;
-  const autoCiFollowupByRepository = new Map<string, boolean>();
-  const visualPreviewByRepository = new Map<string, VisualPreviewSettings>();
-  for (const repo of repos) {
-    const key = getRepositoryConfigKey(repo.name);
-    autoCiFollowupByRepository.set(key, autoCiFollowupByRepository.get(key) === true || repo.autoFollowupOnFailedCi);
-    const previousPreview = visualPreviewByRepository.get(key);
-    if (!previousPreview || (!previousPreview.enabled && repo.visualPreview.enabled)) {
-      visualPreviewByRepository.set(key, repo.visualPreview);
-    }
-  }
-  const reposForDisplay = repos.map(repo => ({
-    ...repo,
-    autoFollowupOnFailedCi: autoCiFollowupByRepository.get(getRepositoryConfigKey(repo.name)) === true,
-    visualPreview: visualPreviewByRepository.get(getRepositoryConfigKey(repo.name)) || defaultVisualPreview()
-  }));
+  const reposForDisplay = buildRepositoriesForDisplay(repos);
   const filteredRepos = showHiddenRepos ? reposForDisplay : reposForDisplay.filter(r => !r.hidden);
 
   return {
diff --git a/src/github/visualPreviewAttachments.ts b/src/github/visualPreviewAttachments.ts
new file mode 100644
index 000000000..9fb516d37
--- /dev/null
+++ b/src/github/visualPreviewAttachments.ts
@@ -0,0 +1,168 @@
+import { execa } from 'execa';
+import {
+  appendVisualPreviewSection,
+  renderVisualPreviewSection,
+  type VisualPreviewEvidence
+} from '@propr/core';
+
+interface AttachmentCommandOptions {
+  args: string[];
+  authToken: string;
+  cwd: string;
+}
+
+export type AttachmentCommandRunner = (options: AttachmentCommandOptions) => Promise<{ stdout: string }>;
+
+const runAttachmentCommand: AttachmentCommandRunner = async ({ args, authToken, cwd }) => {
+  try {
+    const result = await execa('gh', args, {
+      cwd,
+      env: {
+        ...process.env,
+        GH_TOKEN: authToken,
+        GH_PROMPT_DISABLED: '1',
+        NO_COLOR: '1'
+      },
+      reject: true,
+      timeout: 60_000
+    });
+    return { stdout: result.stdout };
+  } catch (error) {
+    const wrappedError = new Error('GitHub CLI could not upload visual preview attachments') as Error & { stdout?: string };
+    const stdout = (error as { stdout?: unknown })?.stdout;
+    if (typeof stdout === 'string') wrappedError.stdout = stdout;
+    throw wrappedError;
+  }
+};
+
+interface BaseVisualPreviewPublicationOptions {
+  owner: string;
+  repo: string;
+  commitHash: string;
+  body: string;
+  evidence: VisualPreviewEvidence;
+  authToken: string;
+  worktreePath: string;
+  runCommand?: AttachmentCommandRunner;
+}
+
+function attachmentArguments(evidence: VisualPreviewEvidence): string[] {
+  return evidence.assets.flatMap(asset => ['--attach', asset.absolutePath]);
+}
+
+function bodyWithLocalPreviews(options: BaseVisualPreviewPublicationOptions): string {
+  const section = renderVisualPreviewSection(options.evidence, {
+    owner: options.owner,
+    repo: options.repo,
+    commitHash: options.commitHash,
+    useLocalPaths: true
+  });
+  return appendVisualPreviewSection(options.body, section);
+}
+
+export interface PublishPullRequestVisualPreviewOptions extends BaseVisualPreviewPublicationOptions {
+  pullRequestNumber: number;
+}
+
+export async function publishPullRequestVisualPreviews(options: PublishPullRequestVisualPreviewOptions): Promise<void> {
+  if (options.evidence.assets.length === 0) return;
+  const runner = options.runCommand || runAttachmentCommand;
+  await runner({
+    args: [
+      'pr', 'edit', String(options.pullRequestNumber),
+      '--repo', `${options.owner}/${options.repo}`,
+      '--body', bodyWithLocalPreviews(options),
+      ...attachmentArguments(options.evidence)
+    ],
+    authToken: options.authToken,
+    cwd: options.worktreePath
+  });
+}
+
+export interface PublishPullRequestCommentVisualPreviewOptions extends BaseVisualPreviewPublicationOptions {
+  pullRequestNumber: number;
+  octokit: {
+    request: <T = unknown>(endpoint: string, options: Record<string, unknown>) => Promise<T>;
+  };
+  startingCommentId: number;
+}
+
+export interface PublishedVisualPreviewComment {
+  html_url: string;
+  body: string;
+}
+
+function parseCommentId(url: string): number | null {
+  const match = url.match(/#issuecomment-(\d+)\b/);
+  return match ? Number(match[1]) : null;
+}
+
+export async function publishPullRequestCommentVisualPreviews(
+  options: PublishPullRequestCommentVisualPreviewOptions
+): Promise<PublishedVisualPreviewComment> {
+  if (options.evidence.assets.length === 0) {
+    throw new Error('Cannot publish an attachment comment without preview assets');
+  }
+  const runner = options.runCommand || runAttachmentCommand;
+  let result: { stdout: string };
+  try {
+    result = await runner({
+      args: [
+        'pr', 'comment', String(options.pullRequestNumber),
+        '--repo', `${options.owner}/${options.repo}`,
+        '--body', bodyWithLocalPreviews(options),
+        ...attachmentArguments(options.evidence)
+      ],
+      authToken: options.authToken,
+      cwd: options.worktreePath
+    });
+  } catch (error) {
+    const partialCommentId = parseCommentId(typeof (error as { stdout?: unknown })?.stdout === 'string'
+      ? (error as { stdout: string }).stdout
+      : '');
+    if (partialCommentId) {
+      try {
+        await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+          owner: options.owner,
+          repo: options.repo,
+          comment_id: partialCommentId
+        });
+      } catch {
+        // Best-effort cleanup; the caller still publishes the complete fallback.
+      }
+    }
+    throw error;
+  }
+
+  const commentUrl = result.stdout.trim().split('\n').find(line => line.includes('#issuecomment-')) || result.stdout.trim();
+  if (!commentUrl) throw new Error('GitHub CLI uploaded previews but did not return a comment URL');
+
+  let publishedBody = options.body;
+  const commentId = parseCommentId(commentUrl);
+  if (commentId) {
+    try {
+      const response = await options.octokit.request<{ data: { body?: string } }>('GET /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+        owner: options.owner,
+        repo: options.repo,
+        comment_id: commentId
+      });
+      publishedBody = response.data.body || publishedBody;
+    } catch {
+      // The attachment comment itself is authoritative; body retrieval is only
+      // used to enrich task history with GitHub's rewritten attachment URLs.
+    }
+  }
+
+  try {
+    await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+      owner: options.owner,
+      repo: options.repo,
+      comment_id: options.startingCommentId
+    });
+  } catch {
+    // The attached completion comment is already published. Leaving the
+    // transient work comment is preferable to posting the completion twice.
+  }
+
+  return { html_url: commentUrl, body: publishedBody };
+}
diff --git a/src/jobs/issueJob/agent.ts b/src/jobs/issueJob/agent.ts
index f2e7719bc..3c1a155bf 100644
--- a/src/jobs/issueJob/agent.ts
+++ b/src/jobs/issueJob/agent.ts
@@ -4,7 +4,7 @@
 
 import {
   TaskStates, AgentRegistry, generateClaudePrompt, updateFileChangesFromWorktree, recordLLMMetrics,
-  resolveAgentTerminationReason
+  resolveAgentTerminationReason, loadRepositoryVisualPreviewSettings
 } from '@propr/core';
 import type { AgentExecutionResult, ClaudeCodeResponse, ClaudeResult } from '@propr/core';
 import type { ExecutionParams, JobContext } from './types.js';
@@ -82,6 +82,7 @@ export async function executeAgentAndRecordMetrics(executionParams: ExecutionPar
     repoOwner: issueRef.repoOwner,
     repoName: issueRef.repoName
   };
+  const visualPreviewSettingsPromise = loadRepositoryVisualPreviewSettings(`${issueRef.repoOwner}/${issueRef.repoName}`);
 
   // Localize remote images in issue body and comments
   const issueBodyHtml = (currentIssueData.data as { body_html?: string }).body_html;
@@ -109,7 +110,8 @@ export async function executeAgentAndRecordMetrics(executionParams: ExecutionPar
       created_at: currentIssueData.data.created_at,
       user: currentIssueData.data.user
     },
-    baseBranch: issueRef.baseBranch || null
+    baseBranch: issueRef.baseBranch || null,
+    visualPreviewSettings: await visualPreviewSettingsPromise
   });
 
   // Start periodic file changes updates during agent execution
diff --git a/src/jobs/issueJobHelpers.ts b/src/jobs/issueJobHelpers.ts
index 404a0d456..0f5fffec4 100644
--- a/src/jobs/issueJobHelpers.ts
+++ b/src/jobs/issueJobHelpers.ts
@@ -9,7 +9,10 @@ import {
     buildAgentModelLlmLabel,
     getAgentTypeFromModel,
     isEpicBranch,
-    resolveAgentTerminationReason
+    appendVisualPreviewSection,
+    renderVisualPreviewSection,
+    resolveAgentTerminationReason,
+    type VisualPreviewEvidence
 } from '@propr/core';
 export { localizeContentImages, cleanupIssueAssets, type LocalizeContentImagesOptions } from './contentUtils.js';
 export {
@@ -21,6 +24,7 @@ export {
     type GenericErrorOptions
 } from './errorHandlers.js';
 import type { ClaudeCodeResponse, IssueJobData, JobResult, WorkerStateManager, WorktreeInfo, CommitResult, RepoValidationResult } from '@propr/core';
+import { publishPullRequestVisualPreviews } from '../github/visualPreviewAttachments.js';
 
 export type RepoValidation = RepoValidationResult;
 
@@ -53,6 +57,11 @@ interface CreatePROptions {
     PR_LABEL: string;
     correlatedLogger: Logger;
     issueTitle: string;
+    visualPreview?: {
+        evidence: VisualPreviewEvidence;
+        authToken: string;
+        worktreePath: string;
+    };
 }
 
 export function buildIssueReference(
@@ -171,14 +180,14 @@ export async function createPullRequest(
     worktreeInfo: WorktreeInfo,
     options: CreatePROptions
 ): Promise<PostProcessingResult> {
-    const { commitResult, claudeResult, modelName, repoValidation, PR_LABEL, correlatedLogger, issueTitle } = options;
+    const { commitResult, claudeResult, modelName, repoValidation, PR_LABEL, correlatedLogger, issueTitle, visualPreview } = options;
     const jobId = `${issueRef.repoOwner}-${issueRef.repoName}-${issueRef.number}`;
 
     const modelShortName = getModelShortName(modelName);
     const prTitle = '[' + issueRef.number + ' by ' + modelShortName + '] ' + issueTitle;
 
     const completionComment = await generateCompletionComment(claudeResult, { number: issueRef.number, repoOwner: issueRef.repoOwner, repoName: issueRef.repoName });
-    const prBody = `## AI Implementation Summary
+    const basePrBody = `## AI Implementation Summary
 
 ${buildIssueReference(issueRef.number, commitResult !== null, claudeResult)}
 
@@ -194,6 +203,14 @@ ${completionComment}
 ### 💡 Need changes?
 
 Comment on this PR to request refinements — the AI agent monitors comments and will update the implementation based on your feedback. Keep iterating until you're satisfied!`;
+    const visualPreviewSection = visualPreview && commitResult
+        ? renderVisualPreviewSection(visualPreview.evidence, {
+            owner: issueRef.repoOwner,
+            repo: issueRef.repoName,
+            commitHash: commitResult.commitHash
+        })
+        : '';
+    const prBody = appendVisualPreviewSection(basePrBody, visualPreviewSection);
 
     try {
         const prResponse = await octokit.request<{ data: { number: number; html_url: string; title: string } }>('POST /repos/{owner}/{repo}/pulls', {
@@ -232,6 +249,34 @@ Comment on this PR to request refinements — the AI agent monitors comments and
             correlatedLogger.warn({ prNumber: prResponse.data.number, labels: labelsToAdd, error: (labelError as Error).message }, 'Failed to add PR labels to new PR after retries');
         }
 
+        if (visualPreview && commitResult && visualPreview.evidence.assets.length > 0) {
+            try {
+                await publishPullRequestVisualPreviews({
+                    owner: issueRef.repoOwner,
+                    repo: issueRef.repoName,
+                    pullRequestNumber: prResponse.data.number,
+                    commitHash: commitResult.commitHash,
+                    body: basePrBody,
+                    evidence: visualPreview.evidence,
+                    authToken: visualPreview.authToken,
+                    worktreePath: visualPreview.worktreePath
+                });
+                correlatedLogger.info({ prNumber: prResponse.data.number, previewCount: visualPreview.evidence.assets.length }, 'Uploaded visual previews to pull request');
+            } catch (previewError) {
+                correlatedLogger.warn({ prNumber: prResponse.data.number, error: (previewError as Error).message }, 'Could not upload visual previews; committed-file links remain in the pull request body');
+                try {
+                    await octokit.request('PATCH /repos/{owner}/{repo}/pulls/{pull_number}', {
+                        owner: issueRef.repoOwner,
+                        repo: issueRef.repoName,
+                        pull_number: prResponse.data.number,
+                        body: prBody
+                    });
+                } catch (fallbackError) {
+                    correlatedLogger.warn({ prNumber: prResponse.data.number, error: (fallbackError as Error).message }, 'Could not restore committed-file visual preview links after a partial attachment upload');
+                }
+            }
+        }
+
         return {
             success: true,
             pr: {
diff --git a/src/jobs/issueJobPostProcessing.ts b/src/jobs/issueJobPostProcessing.ts
index 86718f733..8878647e7 100644
--- a/src/jobs/issueJobPostProcessing.ts
+++ b/src/jobs/issueJobPostProcessing.ts
@@ -2,7 +2,16 @@ import type { Logger } from 'pino';
 import { setTimeout } from 'timers/promises';
 import type { ClaudeCodeResponse } from '@propr/core';
 import type { WorktreeInfo, CommitResult, WorkerStateManager } from '@propr/core';
-import { cleanupWorktree, commitChanges, pushBranch, TaskStates, describeAgentTermination, resolveAgentTerminationReason } from '@propr/core';
+import {
+    cleanupWorktree,
+    collectVisualPreviewEvidence,
+    commitChanges,
+    loadRepositoryVisualPreviewSettings,
+    pushBranch,
+    TaskStates,
+    describeAgentTermination,
+    resolveAgentTerminationReason
+} from '@propr/core';
 import { getAuthenticatedOctokit, linkPRToPlanIssue } from '@propr/core';
 import { safeUpdateLabels } from '@propr/core';
 import { generateCompletionComment } from '@propr/core';
@@ -241,7 +250,24 @@ export async function performPostProcessing(options: PostProcessOptions): Promis
 
         postProcessingResult = await createPullRequest(
             octokit, issueRef, worktreeInfo,
-            { commitResult, claudeResult, modelName, repoValidation, PR_LABEL, correlatedLogger, issueTitle: currentIssueData.data.title }
+            {
+                commitResult,
+                claudeResult,
+                modelName,
+                repoValidation,
+                PR_LABEL,
+                correlatedLogger,
+                issueTitle: currentIssueData.data.title,
+                visualPreview: {
+                    evidence: await collectVisualPreviewEvidence({
+                        worktreePath: worktreeInfo.worktreePath,
+                        changedFiles: commitResult.filesChanged || [],
+                        settings: await loadRepositoryVisualPreviewSettings(`${issueRef.repoOwner}/${issueRef.repoName}`)
+                    }),
+                    authToken: githubToken.token,
+                    worktreePath: worktreeInfo.worktreePath
+                }
+            }
         );
 
         // Update plan issue status to 'under_review' if PR was created successfully
diff --git a/src/jobs/prCommentJobUtils.ts b/src/jobs/prCommentJobUtils.ts
index ccd76e874..7ca516c34 100644
--- a/src/jobs/prCommentJobUtils.ts
+++ b/src/jobs/prCommentJobUtils.ts
@@ -5,9 +5,9 @@ import {
     generateCorrelationId, handleError, getAuthenticatedOctokit, cleanupWorktree,
     formatResetTime, recordLLMMetrics, issueQueue, TaskStates, getDefaultModel,
     resolveModelAlias, getPendingPrCommentsKey,
-    describeAgentTermination, resolveAgentTerminationReason,
+    buildVisualPreviewPrompt, describeAgentTermination, resolveAgentTerminationReason,
     type WorktreeInfo, type ClaudeCodeResponse, type ClaudeResult,
-    type CommentJobData, type UnprocessedComment, type WorkerStateManager,
+    type CommentJobData, type UnprocessedComment, type WorkerStateManager, type VisualPreviewSettings,
 } from '@propr/core';
 import { sanitizeErrorMessage } from './errorSanitizer.js';
 import { getFixEnvironmentRepairInstructions } from './environmentRepairPrompt.js';
@@ -131,11 +131,13 @@ export interface PromptOptions {
     commandMode?: string;
     /** Formatted section of AI review comments gathered for /fix */
     reviewCommentsSection?: string;
+    visualPreviewSettings?: VisualPreviewSettings;
 }
 
 export function buildPrompt(options: PromptOptions): string {
-    const { pullRequestNumber, combinedCommentBody, commentHistory, originalTaskSpec, worktreeInfo, repoOwner, repoName, commentCount, commandMode, reviewCommentsSection } = options;
+    const { pullRequestNumber, combinedCommentBody, commentHistory, originalTaskSpec, worktreeInfo, repoOwner, repoName, commentCount, commandMode, reviewCommentsSection, visualPreviewSettings } = options;
     const environmentRepairInstructions = getFixEnvironmentRepairInstructions(commandMode);
+    const visualPreviewInstructions = visualPreviewSettings ? buildVisualPreviewPrompt(visualPreviewSettings) : '';
     return `You are working on pull request #${pullRequestNumber} to apply follow-up changes.
 
 **New Request${commentCount > 1 ? 's' : ''}:**
@@ -154,6 +156,7 @@ ${reviewCommentsSection
 - DO NOT create a new pull request
 - The repository is ${repoOwner}/${repoName}
 ${environmentRepairInstructions}
+${visualPreviewInstructions}
 
 **Context:**
 - This is a follow-up to an existing pull request #${pullRequestNumber}.
diff --git a/src/jobs/prCommentPostExecution.ts b/src/jobs/prCommentPostExecution.ts
index fb07f16e3..80873141c 100644
--- a/src/jobs/prCommentPostExecution.ts
+++ b/src/jobs/prCommentPostExecution.ts
@@ -3,12 +3,17 @@ import type { Logger } from 'pino';
 import type { Redis } from 'ioredis';
 import {
     commitChanges,
+    collectVisualPreviewEvidence,
     db,
     getRepoUrl,
     getAuthenticatedOctokit,
+    loadRepositoryVisualPreviewSettings,
     pushBranch,
+    appendVisualPreviewSection,
+    renderVisualPreviewSection,
     resolveAgentTerminationReason,
     TaskStates,
+    VISUAL_PREVIEW_SLOT,
 } from '@propr/core';
 import type {
     ClaudeCodeResponse,
@@ -24,6 +29,7 @@ import { markReviewFindingsProcessed } from './reviewCommentGatherer.js';
 import type { AIReviewComment } from './reviewCommentGatherer.js';
 import { resolveUltrafixHistoryMeta } from './ultrafixJobHelpers.js';
 import type { GitHubToken } from './githubTypes.js';
+import { publishPullRequestCommentVisualPreviews } from '../github/visualPreviewAttachments.js';
 
 interface PostExecutionState {
     octokit: Awaited<ReturnType<typeof getAuthenticatedOctokit>> | null;
@@ -126,6 +132,79 @@ export function getPostExecutionDisposition(result: ClaudeCodeResponse): 'comple
     return resolveAgentTerminationReason(result) ? 'partial' : 'failed';
 }
 
+interface CompletionCommentPublicationOptions {
+    state: ReadyPostExecutionState;
+    context: PostExecutionContext;
+    commitResult: Awaited<ReturnType<typeof commitChanges>>;
+    changesSummary: string;
+    commitMessage: string;
+    llm: string | null | undefined;
+    taskUrl: string;
+    unprocessedReviewComments: AIReviewComment[];
+}
+
+async function publishCompletionComment(options: CompletionCommentPublicationOptions): Promise<{ data: { html_url: string; body?: string } }> {
+    const { state, context, commitResult, changesSummary, commitMessage, llm, taskUrl, unprocessedReviewComments } = options;
+    const { repoOwner, repoName, pullRequestNumber, correlatedLogger } = context;
+    const visualPreviewSettings = await loadRepositoryVisualPreviewSettings(`${repoOwner}/${repoName}`);
+    const visualPreviewEvidence = await collectVisualPreviewEvidence({
+        worktreePath: state.worktreeInfo.worktreePath,
+        changedFiles: commitResult?.filesChanged || [],
+        settings: visualPreviewSettings
+    });
+    const hasVisualPreviewContent = visualPreviewEvidence.assets.length > 0 || visualPreviewEvidence.toolSuggestions.length > 0;
+    const visualPreviewSection = commitResult && hasVisualPreviewContent
+        ? renderVisualPreviewSection(visualPreviewEvidence, { owner: repoOwner, repo: repoName, commitHash: commitResult.commitHash })
+        : '';
+    const undoContext = buildUndoContext({ commitResult, unprocessedComments: state.unprocessedComments, repoOwner, repoName, pullRequestNumber, branchName: state.worktreeInfo.branchName });
+    const consumedReviewCommentIds = unprocessedReviewComments.length > 0 ? unprocessedReviewComments.map(comment => comment.id) : undefined;
+    const prCommentTemplate = await buildCompletionComment(commitResult, state.unprocessedComments, {
+        changesSummary,
+        commitMessage,
+        llm,
+        authorsText: state.authorsText,
+        undoContext,
+        taskUrl,
+        consumedReviewCommentIds,
+        visualPreviewSection: hasVisualPreviewContent ? VISUAL_PREVIEW_SLOT : undefined
+    }, state.claudeResult);
+    const prCommentBody = appendVisualPreviewSection(prCommentTemplate, visualPreviewSection);
+
+    if (!commitResult || visualPreviewEvidence.assets.length === 0) {
+        return state.octokit.request('PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+            owner: repoOwner,
+            repo: repoName,
+            comment_id: state.startingWorkComment.data.id,
+            body: prCommentBody
+        }) as Promise<{ data: { html_url: string; body?: string } }>;
+    }
+
+    try {
+        const githubToken = await state.octokit.auth({ type: 'installation' }) as GitHubToken;
+        const published = await publishPullRequestCommentVisualPreviews({
+            owner: repoOwner,
+            repo: repoName,
+            pullRequestNumber,
+            commitHash: commitResult.commitHash,
+            body: prCommentTemplate,
+            evidence: visualPreviewEvidence,
+            authToken: githubToken.token,
+            worktreePath: state.worktreeInfo.worktreePath,
+            octokit: state.octokit,
+            startingCommentId: state.startingWorkComment.data.id
+        });
+        return { data: published };
+    } catch (previewError) {
+        correlatedLogger.warn({ pullRequestNumber, error: (previewError as Error).message }, 'Could not upload visual previews; publishing committed-file links in the completion comment');
+        return state.octokit.request('PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+            owner: repoOwner,
+            repo: repoName,
+            comment_id: state.startingWorkComment.data.id,
+            body: prCommentBody
+        }) as Promise<{ data: { html_url: string; body?: string } }>;
+    }
+}
+
 export async function handlePostExecution(params: PostExecutionParams, taskUrl: string): Promise<{ commitHash?: string; partial: boolean }> {
     const {
         state,
@@ -155,10 +234,7 @@ export async function handlePostExecution(params: PostExecutionParams, taskUrl:
     }
     if (commitResult?.filesChanged?.length) state.claudeResult.modifiedFiles = commitResult.filesChanged;
 
-    const undoContext = buildUndoContext({ commitResult, unprocessedComments: state.unprocessedComments, repoOwner, repoName, pullRequestNumber, branchName: state.worktreeInfo.branchName });
-    const consumedReviewCommentIds = unprocessedReviewComments.length > 0 ? unprocessedReviewComments.map(c => c.id) : undefined;
-    const prCommentBody = await buildCompletionComment(commitResult, state.unprocessedComments, { changesSummary, commitMessage, llm, authorsText: state.authorsText, undoContext, taskUrl, consumedReviewCommentIds }, state.claudeResult);
-    const completionComment = await state.octokit.request('PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}', { owner: repoOwner, repo: repoName, comment_id: state.startingWorkComment.data.id, body: prCommentBody }) as { data: { html_url: string; body?: string } };
+    const completionComment = await publishCompletionComment({ state, context, commitResult, changesSummary, commitMessage, llm, taskUrl, unprocessedReviewComments });
     correlatedLogger.info({ pullRequestNumber, commitHash: commitResult?.commitHash, commentUrl: completionComment.data.html_url, partial, terminationReason }, partial ? 'Published partial follow-up changes after interrupted execution' : 'Successfully applied follow-up changes');
 
     if (unprocessedReviewComments.length > 0) {
diff --git a/src/jobs/prCompletionComment.ts b/src/jobs/prCompletionComment.ts
index 0d332e776..f87c99ad7 100644
--- a/src/jobs/prCompletionComment.ts
+++ b/src/jobs/prCompletionComment.ts
@@ -26,6 +26,7 @@ export interface CommentContext {
     undoContext?: UndoLinkContext;
     taskUrl?: string;
     consumedReviewCommentIds?: number[];
+    visualPreviewSection?: string;
 }
 
 export interface UndoLinkContext {
@@ -142,7 +143,7 @@ export async function buildCompletionComment(
     commentContext: CommentContext,
     claudeResult: ClaudeCodeResponse
 ): Promise<string> {
-    const { changesSummary, commitMessage, llm, authorsText, undoContext, taskUrl, consumedReviewCommentIds } = commentContext;
+    const { changesSummary, commitMessage, llm, authorsText, undoContext, taskUrl, consumedReviewCommentIds, visualPreviewSection } = commentContext;
     const terminationReason = resolveAgentTerminationReason(claudeResult);
     const partial = !claudeResult.success && terminationReason !== undefined;
 
@@ -181,6 +182,10 @@ export async function buildCompletionComment(
             prCommentBody += '## Remaining Work\n\nThe agent stopped before validating every request. Review this partial commit against the follow-up instructions and complete any unaddressed implementation, tests, or documentation.\n\n';
         }
 
+        if (visualPreviewSection) {
+            prCommentBody += `${visualPreviewSection}\n\n`;
+        }
+
         prCommentBody += await buildMetricsSection(claudeResult, llm, authorsText, false);
 
         if (undoContext) {
diff --git a/src/jobs/processPullRequestCommentJob.ts b/src/jobs/processPullRequestCommentJob.ts
index 9b8bdb26d..edca8f40d 100644
--- a/src/jobs/processPullRequestCommentJob.ts
+++ b/src/jobs/processPullRequestCommentJob.ts
@@ -12,7 +12,7 @@ import type { ClaudeCodeResponse } from '@propr/core';
 import { recordLLMMetrics } from '@propr/core';
 import { issueQueue, type CommentJobData, type UnprocessedComment, type JobResult } from '@propr/core';
 import { Redis } from 'ioredis';
-import { loadPrimaryProcessingLabels } from '@propr/core';
+import { loadPrimaryProcessingLabels, loadRepositoryVisualPreviewSettings } from '@propr/core';
 import {
     validateAndFilterComments, filterUnprocessedComments, fetchLinkedIssueContext,
     buildCommentHistory, updateTaskTitleForPR, resolvePrReasoningLevelOverride
@@ -355,7 +355,8 @@ async function executeProcessing(params: ExecuteProcessingParams): Promise<JobRe
         titleContext: buildPrTaskTitleContextHistoryMetadata(titleContext),
     });
 
-    const prompt = buildPrompt({ pullRequestNumber, combinedCommentBody: localizedCombinedCommentBody, commentHistory, originalTaskSpec: localizedOriginalTaskSpec, worktreeInfo: state.worktreeInfo, repoOwner, repoName, commentCount: state.unprocessedComments.length, commandMode: job.data.commandMode || 'default', reviewCommentsSection });
+    const visualPreviewSettings = await loadRepositoryVisualPreviewSettings(`${repoOwner}/${repoName}`);
+    const prompt = buildPrompt({ pullRequestNumber, combinedCommentBody: localizedCombinedCommentBody, commentHistory, originalTaskSpec: localizedOriginalTaskSpec, worktreeInfo: state.worktreeInfo, repoOwner, repoName, commentCount: state.unprocessedComments.length, commandMode: job.data.commandMode || 'default', reviewCommentsSection, visualPreviewSettings });
 
     const { claudeResult, agentType } = await resolveAndExecuteAgent({
         llm, worktreePath: state.worktreeInfo.worktreePath, branchName: state.worktreeInfo.branchName, prompt,
diff --git a/test/issueJobUnpublishableFailure.test.ts b/test/issueJobUnpublishableFailure.test.ts
index f8f556fd2..574de5280 100644
--- a/test/issueJobUnpublishableFailure.test.ts
+++ b/test/issueJobUnpublishableFailure.test.ts
@@ -11,7 +11,9 @@ const resolveAgentTerminationReason = mock.fn((result: { terminationReason?: 'ti
 await mock.module('@propr/core', {
     namedExports: {
         cleanupWorktree: mock.fn(async () => undefined),
+        collectVisualPreviewEvidence: mock.fn(async () => ({ assets: [], toolSuggestions: [] })),
         commitChanges,
+        loadRepositoryVisualPreviewSettings: mock.fn(async () => ({ enabled: false, types: ['image'] })),
         pushBranch,
         AI_COMMIT_AUTHOR: { name: 'ProPR AI', email: 'ai@propr.dev' },
         TaskStates: { CANCELLED: 'cancelled' },
diff --git a/test/visualPreviewAttachments.test.ts b/test/visualPreviewAttachments.test.ts
new file mode 100644
index 000000000..358f8f596
--- /dev/null
+++ b/test/visualPreviewAttachments.test.ts
@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict';
+import { after, test } from 'node:test';
+
+process.env.PROPR_DEMO_MODE = 'true';
+
+const [{ db }, {
+  publishPullRequestCommentVisualPreviews,
+  publishPullRequestVisualPreviews
+}] = await Promise.all([
+  import('@propr/core'),
+  import('../src/github/visualPreviewAttachments.js')
+]);
+
+after(async () => {
+  await db.destroy();
+});
+
+const evidence = {
+  assets: [{
+    relativePath: '.propr/previews/desktop.png',
+    absolutePath: '/worktree/.propr/previews/desktop.png',
+    type: 'image' as const,
+    title: 'Desktop settings'
+  }],
+  toolSuggestions: []
+};
+
+test('edits a pull request with uploaded visual preview attachments', async () => {
+  let invocation: { args: string[]; authToken: string; cwd: string } | undefined;
+
+  await publishPullRequestVisualPreviews({
+    owner: 'integry',
+    repo: 'propr',
+    pullRequestNumber: 42,
+    commitHash: 'abc123',
+    body: 'Implementation summary',
+    evidence,
+    authToken: 'installation-token',
+    worktreePath: '/worktree',
+    runCommand: async options => {
+      invocation = options;
+      return { stdout: '' };
+    }
+  });
+
+  assert.ok(invocation);
+  assert.deepEqual(invocation.args.slice(0, 6), ['pr', 'edit', '42', '--repo', 'integry/propr', '--body']);
+  assert.match(invocation.args[6], /!\[Desktop settings\]\(\/worktree\/\.propr\/previews\/desktop\.png\)/);
+  assert.deepEqual(invocation.args.slice(-2), ['--attach', '/worktree/.propr/previews/desktop.png']);
+  assert.equal(invocation.authToken, 'installation-token');
+  assert.equal(invocation.args.includes('installation-token'), false);
+});
+
+test('publishes an attached completion comment before removing the transient work comment', async () => {
+  const requests: Array<{ endpoint: string; options: Record<string, unknown> }> = [];
+  const published = await publishPullRequestCommentVisualPreviews({
+    owner: 'integry',
+    repo: 'propr',
+    pullRequestNumber: 42,
+    commitHash: 'abc123',
+    body: 'Follow-up complete',
+    evidence,
+    authToken: 'installation-token',
+    worktreePath: '/worktree',
+    startingCommentId: 100,
+    octokit: {
+      request: async <T>(endpoint: string, options: Record<string, unknown>) => {
+        requests.push({ endpoint, options });
+        return { data: { body: 'Follow-up complete with uploaded URL' } } as T;
+      }
+    },
+    runCommand: async () => ({ stdout: 'https://github.com/integry/propr/pull/42#issuecomment-200' })
+  });
+
+  assert.deepEqual(published, {
+    html_url: 'https://github.com/integry/propr/pull/42#issuecomment-200',
+    body: 'Follow-up complete with uploaded URL'
+  });
+  assert.deepEqual(requests.map(request => request.endpoint), [
+    'GET /repos/{owner}/{repo}/issues/comments/{comment_id}',
+    'DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}'
+  ]);
+  assert.equal(requests[1].options.comment_id, 100);
+});
+
+test('removes a partially published attachment comment before surfacing upload failure', async () => {
+  const deletedCommentIds: unknown[] = [];
+  await assert.rejects(() => publishPullRequestCommentVisualPreviews({
+    owner: 'integry',
+    repo: 'propr',
+    pullRequestNumber: 42,
+    commitHash: 'abc123',
+    body: 'Follow-up complete',
+    evidence,
+    authToken: 'installation-token',
+    worktreePath: '/worktree',
+    startingCommentId: 100,
+    octokit: {
+      request: async <T>(_endpoint: string, options: Record<string, unknown>) => {
+        deletedCommentIds.push(options.comment_id);
+        return {} as T;
+      }
+    },
+    runCommand: async () => {
+      throw Object.assign(new Error('one attachment failed'), {
+        stdout: 'https://github.com/integry/propr/pull/42#issuecomment-201'
+      });
+    }
+  }), /one attachment failed/);
+
+  assert.deepEqual(deletedCommentIds, [201]);
+});

From 95e0e053842eae06d1acb4c9f5c227d90cb19e10 Mon Sep 17 00:00:00 2001
From: "propr-dev[bot]" <1316198+propr-dev[bot]@users.noreply.github.com>
Date: Thu, 3 Sep 2026 11:52:37 +0000
Subject: [PATCH 03/18] feat(ai): Implemented the PR #2102 follow-up without
 committing changes.

Implemented the PR #2102 follow-up without committing changes.

Key changes:

- Preview evidence is collected before commit, copied to `/tmp/propr-previews/<task-id>-*/`, and removed/reset from the worktree.
- `.propr/previews` is excluded defensively from `commitChanges()`.
- Temporary files are always cleaned up after publication.
- PR and comment uploads fetch the resulting GitHub body and reject leaked local paths.
- Upload failures now publish text-only explanations; commit-pinned fallbacks were removed.
- Fixed `appendVisualPreviewSection()` so empty previews no longer normalize unrelated whitespace.
- Updated tests and [visual preview documentation](/tmp/git-processor/worktrees/integry/propr/pr-2102-followup-2026-09-03T11-36-55/docs/docs/features/visual-previews.md).

Validation passed:

- 26 focused/lifecycle tests
- Root and core typechecks
- Root and core lint
- Root and core builds
- `git diff --check`
- 146 related helper/git-hook tests

A live GitHub App upload was not performed: the environment has GitHub CLI 2.96.0, not 2.99, and directly modifying PR #2102 is outside the allowed actions.

PR: #2102
Comment by: @integry (ID: 5525114134)
Model: gpt-5.6-sol
---
 docs/docs/features/visual-previews.md         |   6 +-
 packages/core/src/git/commitOperations.ts     |   2 +-
 .../core/src/services/visualPreviewService.ts | 156 +++++++++++++++---
 .../core/test/visualPreviewService.test.ts    |  99 +++++++++--
 src/github/visualPreviewAttachments.ts        |  93 ++++++-----
 src/jobs/issueJobHelpers.ts                   |  20 +--
 src/jobs/issueJobPostProcessing.ts            |  26 +--
 src/jobs/prCommentPostExecution.ts            | 113 +++++++------
 test/issueJobUnpublishableFailure.test.ts     |   3 +-
 test/visualPreviewAttachments.test.ts         |  53 +++++-
 10 files changed, 420 insertions(+), 151 deletions(-)

diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
index d7f4f9565..624f11c5e 100644
--- a/docs/docs/features/visual-previews.md
+++ b/docs/docs/features/visual-previews.md
@@ -36,12 +36,12 @@ When enabled, the implementation agent evaluates the completed change:
 - Captures focus on the change rather than generic application screens and must not contain credentials, personal data, or unrelated content.
 - If capture is blocked, the agent can recommend the concrete browser, emulator, or media tool that should be added to the agent image.
 
-Generated files live under `.propr/previews/`. Optional titles, descriptions, and tool recommendations are recorded in `.propr/previews/manifest.json`. Only preview files changed by the current implementation commit are published, which prevents an old capture from being presented as evidence for a later change.
+Agents generate files under the transient `.propr/previews/` runtime directory. Optional titles, descriptions, and tool recommendations are recorded in `.propr/previews/manifest.json`. Before committing, ProPR copies accepted files to worker-owned temporary storage and removes the runtime directory from the worktree. Preview files are therefore never included in the implementation commit.
 
 Supported image formats are PNG, JPEG, GIF, SVG, and WebP. Supported video formats are MP4, MOV, and WebM; H.264 MP4 is the most broadly compatible choice. Each attachment must be smaller than 10 MB.
 
-## Publication And Fallbacks
+## Publication And Upload Failures
 
-ProPR first adds commit-pinned repository links, then attempts to replace them with [GitHub attachments](https://cli.github.com/manual/gh_pr_edit) so images render inline and videos use GitHub's media presentation. When attachment upload is unavailable, images remain embedded from the implementation commit and videos remain explicit links to the committed recording. This keeps the evidence reachable without relying on mutable branch URLs.
+ProPR publishes previews as [GitHub attachments](https://cli.github.com/manual/gh_pr_edit) so images render inline and videos use GitHub's media presentation. It then fetches the published PR or comment body and verifies that GitHub replaced every temporary local path with a hosted attachment URL. Temporary files are deleted after publication. If upload or verification fails, ProPR publishes a text-only explanation; preview media is not added to Git as a fallback.
 
 Preview generation is evidence, not a replacement for automated tests. A preview failure does not discard an otherwise valid implementation; the PR explains missing tool support when the agent can identify it.
diff --git a/packages/core/src/git/commitOperations.ts b/packages/core/src/git/commitOperations.ts
index 5e12cf281..0f58fce2a 100644
--- a/packages/core/src/git/commitOperations.ts
+++ b/packages/core/src/git/commitOperations.ts
@@ -119,7 +119,7 @@ export async function commitChanges(worktreePath: string, commitMessage: string
         await git.add('.');
         // Unstage generated ProPR runtime directories. Repo-authored files such
         // as .propr/setup.sh and .propr/package.json should remain committable.
-        for (const generatedPath of ['.propr/assets', '.propr/cache', '.propr/.cache', '.propr/node_modules']) {
+        for (const generatedPath of ['.propr/assets', '.propr/cache', '.propr/.cache', '.propr/node_modules', '.propr/previews']) {
             try {
                 await git.raw(['reset', 'HEAD', '--', generatedPath]);
             } catch {
diff --git a/packages/core/src/services/visualPreviewService.ts b/packages/core/src/services/visualPreviewService.ts
index 6f41988c8..3eaf823a2 100644
--- a/packages/core/src/services/visualPreviewService.ts
+++ b/packages/core/src/services/visualPreviewService.ts
@@ -1,6 +1,8 @@
-import { lstat, readFile } from 'node:fs/promises';
+import { copyFile, lstat, mkdir, mkdtemp, readFile, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import type { VisualPreviewSettings, VisualPreviewType } from '../config/configManager.js';
+import { createHooklessGit } from '../git/hooklessGit.js';
 
 export const VISUAL_PREVIEW_DIRECTORY = '.propr/previews';
 export const VISUAL_PREVIEW_MANIFEST = `${VISUAL_PREVIEW_DIRECTORY}/manifest.json`;
@@ -49,12 +51,21 @@ export interface CollectVisualPreviewEvidenceOptions {
 }
 
 export interface RenderVisualPreviewOptions {
-  owner: string;
-  repo: string;
-  commitHash: string;
   useLocalPaths?: boolean;
 }
 
+export interface PrepareVisualPreviewEvidenceOptions {
+  worktreePath: string;
+  settings: VisualPreviewSettings;
+  taskId: string;
+  changedFiles?: readonly string[];
+}
+
+export interface PreparedVisualPreviewEvidence {
+  evidence: VisualPreviewEvidence;
+  temporaryDirectory?: string;
+}
+
 function previewTypeForPath(filePath: string): VisualPreviewType | null {
   const extension = path.posix.extname(filePath).toLowerCase();
   if (IMAGE_EXTENSIONS.has(extension)) return 'image';
@@ -96,6 +107,8 @@ async function readManifest(worktreePath: string, changedFiles: Set<string>): Pr
   try {
     const stats = await lstat(manifestPath);
     if (!stats.isFile() || stats.isSymbolicLink() || stats.size > MAX_MANIFEST_BYTES) return null;
+    const [realRoot, realManifest] = await Promise.all([realpath(worktreePath), realpath(manifestPath)]);
+    if (realManifest !== realRoot && !realManifest.startsWith(`${realRoot}${path.sep}`)) return null;
     const parsed = JSON.parse(await readFile(manifestPath, 'utf8')) as unknown;
     return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
       ? parsed as VisualPreviewManifestData
@@ -141,6 +154,8 @@ async function collectAsset(
   try {
     const stats = await lstat(absolutePath);
     if (!stats.isFile() || stats.isSymbolicLink()) return {};
+    const [realRoot, realAsset] = await Promise.all([realpath(root), realpath(absolutePath)]);
+    if (realAsset !== realRoot && !realAsset.startsWith(`${realRoot}${path.sep}`)) return {};
     if (stats.size === 0) return {};
     if (stats.size > MAX_GITHUB_ATTACHMENT_BYTES) return { oversized: true };
   } catch {
@@ -199,13 +214,102 @@ export async function collectVisualPreviewEvidence({
   return { assets, toolSuggestions: toolSuggestions.slice(0, 5) };
 }
 
-function markdownText(value: string): string {
-  return value.replace(/([\\`*_[\]{}()<>#+.!|])/g, '\\$1');
+function safeTemporaryName(taskId: string): string {
+  const normalized = taskId.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
+  return normalized || 'task';
 }
 
-function encodedRepositoryAssetUrl(owner: string, repo: string, commitHash: string, relativePath: string): string {
-  const encodedPath = relativePath.split('/').map(segment => encodeURIComponent(segment)).join('/');
-  return `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/blob/${encodeURIComponent(commitHash)}/${encodedPath}?raw=true`;
+async function copyEvidenceToTemporaryDirectory(
+  evidence: VisualPreviewEvidence,
+  taskId: string
+): Promise<PreparedVisualPreviewEvidence> {
+  if (evidence.assets.length === 0) return { evidence };
+
+  const temporaryRoot = path.join(tmpdir(), 'propr-previews');
+  await mkdir(temporaryRoot, { recursive: true });
+  const temporaryDirectory = await mkdtemp(path.join(temporaryRoot, `${safeTemporaryName(taskId)}-`));
+
+  try {
+    const assets: VisualPreviewAsset[] = [];
+    for (const asset of evidence.assets) {
+      const previewRelativePath = asset.relativePath.slice(`${VISUAL_PREVIEW_DIRECTORY}/`.length);
+      const destination = path.resolve(temporaryDirectory, previewRelativePath);
+      if (!destination.startsWith(`${temporaryDirectory}${path.sep}`)) {
+        throw new Error(`Invalid visual preview path: ${asset.relativePath}`);
+      }
+      await mkdir(path.dirname(destination), { recursive: true });
+      await copyFile(asset.absolutePath, destination);
+      assets.push({ ...asset, absolutePath: destination });
+    }
+    return { evidence: { ...evidence, assets }, temporaryDirectory };
+  } catch (error) {
+    await rm(temporaryDirectory, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function scrubVisualPreviewDirectory(worktreePath: string): Promise<void> {
+  const previewDirectory = path.resolve(worktreePath, VISUAL_PREVIEW_DIRECTORY);
+  await rm(previewDirectory, { recursive: true, force: true });
+
+  const git = createHooklessGit(worktreePath);
+  const indexedPreviews = (await git.raw(['ls-files', '--', VISUAL_PREVIEW_DIRECTORY])).trim();
+  if (indexedPreviews) {
+    await git.raw(['restore', '--source=HEAD', '--staged', '--worktree', '--', VISUAL_PREVIEW_DIRECTORY]);
+  }
+}
+
+async function currentPreviewChangePaths(worktreePath: string): Promise<string[]> {
+  const git = createHooklessGit(worktreePath);
+  const statusPaths = (await git.status()).files.map(file => file.path);
+  const ignoredPreviewPaths = (await git.raw([
+    'ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--', VISUAL_PREVIEW_DIRECTORY
+  ])).split('\0').filter(Boolean);
+  return [...new Set([...statusPaths, ...ignoredPreviewPaths])];
+}
+
+/**
+ * Captures current preview evidence outside the repository, then restores the
+ * preview directory to HEAD so a later `git add .` cannot commit runtime media.
+ */
+export async function prepareVisualPreviewEvidence({
+  worktreePath,
+  settings,
+  taskId,
+  changedFiles
+}: PrepareVisualPreviewEvidenceOptions): Promise<PreparedVisualPreviewEvidence> {
+  let prepared: PreparedVisualPreviewEvidence | undefined;
+  let preparationFailed = false;
+  let preparationError: unknown;
+  try {
+    const files = changedFiles ?? await currentPreviewChangePaths(worktreePath);
+    const evidence = await collectVisualPreviewEvidence({ worktreePath, changedFiles: files, settings });
+    prepared = await copyEvidenceToTemporaryDirectory(evidence, taskId);
+  } catch (error) {
+    preparationFailed = true;
+    preparationError = error;
+  }
+
+  try {
+    await scrubVisualPreviewDirectory(worktreePath);
+  } catch (error) {
+    await cleanupPreparedVisualPreviewEvidence(prepared);
+    throw error;
+  }
+
+  if (preparationFailed) throw preparationError;
+  return prepared!;
+}
+
+export async function cleanupPreparedVisualPreviewEvidence(
+  prepared: PreparedVisualPreviewEvidence | undefined
+): Promise<void> {
+  if (!prepared?.temporaryDirectory) return;
+  await rm(prepared.temporaryDirectory, { recursive: true, force: true });
+}
+
+function markdownText(value: string): string {
+  return value.replace(/([\\`*_[\]{}()<>#+.!|])/g, '\\$1');
 }
 
 function markdownTarget(target: string): string {
@@ -216,19 +320,14 @@ export function renderVisualPreviewSection(
   evidence: VisualPreviewEvidence,
   options: RenderVisualPreviewOptions
 ): string {
-  if (evidence.assets.length === 0 && evidence.toolSuggestions.length === 0) return '';
+  const assets = options.useLocalPaths ? evidence.assets : [];
+  if (assets.length === 0 && evidence.toolSuggestions.length === 0) return '';
   const parts = [VISUAL_PREVIEW_MARKER, '## Visual preview'];
 
-  for (const asset of evidence.assets) {
-    const target = options.useLocalPaths
-      ? asset.absolutePath
-      : encodedRepositoryAssetUrl(options.owner, options.repo, options.commitHash, asset.relativePath);
+  for (const asset of assets) {
+    const target = asset.absolutePath;
     parts.push(`### ${markdownText(asset.title)}`);
-    if (asset.type === 'video' && !options.useLocalPaths) {
-      parts.push(`[Watch ${markdownText(asset.title)}](${markdownTarget(target)})`);
-    } else {
-      parts.push(`![${asset.type === 'image' ? markdownText(asset.title) : ''}](${markdownTarget(target)})`);
-    }
+    parts.push(`![${asset.type === 'image' ? markdownText(asset.title) : ''}](${markdownTarget(target)})`);
     if (asset.description) parts.push(markdownText(asset.description));
   }
 
@@ -242,8 +341,23 @@ export function renderVisualPreviewSection(
   return parts.join('\n\n');
 }
 
+export function renderVisualPreviewUploadFailureSection(evidence: VisualPreviewEvidence): string {
+  const parts = [
+    VISUAL_PREVIEW_MARKER,
+    '## Visual preview',
+    'Preview media was generated but could not be uploaded to GitHub. No preview files were committed.'
+  ];
+  if (evidence.toolSuggestions.length > 0) {
+    parts.push('### Suggested agent tools');
+    parts.push(evidence.toolSuggestions
+      .map(suggestion => `- **${markdownText(suggestion.name)}:** ${markdownText(suggestion.reason)}`)
+      .join('\n'));
+  }
+  return parts.join('\n\n');
+}
+
 export function appendVisualPreviewSection(body: string, section: string): string {
-  if (!section) return body.replace(VISUAL_PREVIEW_SLOT, '').replace(/\n{3,}/g, '\n\n').trim();
+  if (!section) return body.replace(VISUAL_PREVIEW_SLOT, '');
   if (body.includes(VISUAL_PREVIEW_SLOT)) return body.replace(VISUAL_PREVIEW_SLOT, section);
   return `${body.trim()}\n\n---\n\n${section}`;
 }
@@ -261,7 +375,7 @@ Visual previews are enabled for this repository. After implementing and testing,
 - Treat previews as evidence only: never expand the implementation scope, and do not create or update preview files when the current request produces no implementation changes.
 - Generate focused ${requestedTypes} preview evidence of the current change using the project’s existing, relevant tooling (for example a headless browser, Storybook, an Android/iOS emulator, or a project-native renderer).
 - Capture the changed state itself, not generic application screens. Use realistic viewport/device states and follow the repository-specific instructions below when present.
-- Store each preview under \`${VISUAL_PREVIEW_DIRECTORY}/\` using portable filenames and only these formats: PNG/JPEG/GIF/SVG/WebP for images; MP4/MOV/WebM for videos. Keep every file below 10 MB. For video, prefer H.264 in MP4 for browser compatibility.
+- Store each preview under the transient runtime directory \`${VISUAL_PREVIEW_DIRECTORY}/\`; never commit that directory yourself. Use portable filenames and only these formats: PNG/JPEG/GIF/SVG/WebP for images; MP4/MOV/WebM for videos. Keep every file below 10 MB. For video, prefer H.264 in MP4 for browser compatibility.
 - Write \`${VISUAL_PREVIEW_MANIFEST}\` with this shape: \`{"previews":[{"path":".propr/previews/desktop.png","title":"Desktop dialog","description":"The changed dialog at desktop width"}],"toolSuggestions":[{"name":"Playwright Chromium","reason":"Needed to capture the running web UI"}]}\`. The manifest may contain an empty previews array when capture is blocked.
 - Do not fabricate a preview or hand-draw a substitute. If the project cannot be run or the needed capture tool is unavailable, record concise, actionable \`toolSuggestions\` in the manifest describing what should be installed in the agent image and why.
 - Never include credentials, tokens, personal data, or unrelated screens in preview media.
diff --git a/packages/core/test/visualPreviewService.test.ts b/packages/core/test/visualPreviewService.test.ts
index 8feb05d71..dae1af496 100644
--- a/packages/core/test/visualPreviewService.test.ts
+++ b/packages/core/test/visualPreviewService.test.ts
@@ -1,13 +1,17 @@
 import assert from 'node:assert/strict';
-import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises';
+import { access, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { afterEach, test } from 'node:test';
+import { simpleGit } from 'simple-git';
 import {
   appendVisualPreviewSection,
   buildVisualPreviewPrompt,
+  cleanupPreparedVisualPreviewEvidence,
   collectVisualPreviewEvidence,
+  prepareVisualPreviewEvidence,
   renderVisualPreviewSection,
+  renderVisualPreviewUploadFailureSection,
   VISUAL_PREVIEW_MARKER,
   VISUAL_PREVIEW_SLOT
 } from '../src/services/visualPreviewService.js';
@@ -87,7 +91,7 @@ test('collects only changed, selected, regular preview files and applies manifes
   }]);
 });
 
-test('renders upload-ready local media and stable committed-file fallbacks', async () => {
+test('renders upload-ready local media without committed-file fallbacks', async () => {
   const worktree = await createWorktree();
   const relativePath = '.propr/previews/desktop view.png';
   const absolutePath = path.join(worktree, relativePath);
@@ -104,20 +108,21 @@ test('renders upload-ready local media and stable committed-file fallbacks', asy
   };
 
   const local = renderVisualPreviewSection(evidence, {
-    owner: 'integry', repo: 'propr', commitHash: 'abc123', useLocalPaths: true
+    useLocalPaths: true
   });
   assert.match(local, new RegExp(VISUAL_PREVIEW_MARKER));
   assert.match(local, /Settings \\\[desktop\\\]/);
   assert.match(local, /\(<.*desktop view\.png>\)/);
 
-  const fallback = renderVisualPreviewSection(evidence, {
-    owner: 'integry', repo: 'propr', commitHash: 'abc123'
-  });
-  assert.match(fallback, /github\.com\/integry\/propr\/blob\/abc123\/\.propr\/previews\/desktop%20view\.png\?raw=true/);
-  assert.equal(appendVisualPreviewSection(`Before\n\n${VISUAL_PREVIEW_SLOT}\n\nAfter`, fallback), `Before\n\n${fallback}\n\nAfter`);
+  assert.equal(renderVisualPreviewSection(evidence, {}), '');
+  const failure = renderVisualPreviewUploadFailureSection(evidence);
+  assert.match(failure, /could not be uploaded to GitHub/);
+  assert.match(failure, /No preview files were committed/);
+  assert.doesNotMatch(failure, /desktop view\.png/);
+  assert.equal(appendVisualPreviewSection(`Before\n\n${VISUAL_PREVIEW_SLOT}\n\nAfter`, failure), `Before\n\n${failure}\n\nAfter`);
 });
 
-test('renders committed videos as playable links and local videos as upload references', () => {
+test('renders videos only as local upload references', () => {
   const evidence = {
     assets: [{
       relativePath: '.propr/previews/walkthrough.mp4',
@@ -129,13 +134,79 @@ test('renders committed videos as playable links and local videos as upload refe
   };
 
   const local = renderVisualPreviewSection(evidence, {
-    owner: 'integry', repo: 'propr', commitHash: 'abc123', useLocalPaths: true
+    useLocalPaths: true
   });
   assert.match(local, /!\[\]\(\/worktree\/\.propr\/previews\/walkthrough\.mp4\)/);
+  assert.equal(renderVisualPreviewSection(evidence, {}), '');
+});
+
+test('removing an empty preview slot preserves unrelated body whitespace', () => {
+  const body = `  Before\n\n\nUnrelated spacing\n\n${VISUAL_PREVIEW_SLOT}\n\nAfter  `;
+  assert.equal(
+    appendVisualPreviewSection(body, ''),
+    '  Before\n\n\nUnrelated spacing\n\n\n\nAfter  '
+  );
+});
+
+test('stages changed previews outside the repository and restores the preview directory to HEAD', async () => {
+  const worktree = await createWorktree();
+  const git = simpleGit(worktree);
+  await git.init();
+  await git.addConfig('user.name', 'ProPR Test');
+  await git.addConfig('user.email', 'test@propr.dev');
+  await writeFile(path.join(worktree, '.propr/previews/tracked.png'), 'original');
+  await git.add('.');
+  await git.commit('initial preview');
+
+  await writeFile(path.join(worktree, '.propr/previews/tracked.png'), 'updated');
+  await writeFile(path.join(worktree, '.propr/previews/desktop.png'), 'desktop');
+  await writeFile(path.join(worktree, '.propr/previews/manifest.json'), JSON.stringify({
+    previews: [{ path: 'desktop.png', title: 'Desktop settings' }]
+  }));
+  await git.add('.propr/previews');
+
+  const prepared = await prepareVisualPreviewEvidence({
+    worktreePath: worktree,
+    settings: { enabled: true, types: ['image'] },
+    taskId: 'task/42'
+  });
+
+  assert.ok(prepared.temporaryDirectory?.startsWith(path.join(tmpdir(), 'propr-previews', 'task-42-')));
+  assert.deepEqual(prepared.evidence.assets.map(asset => asset.title), ['Desktop settings', 'Tracked']);
+  assert.equal(await readFile(prepared.evidence.assets[0].absolutePath, 'utf8'), 'desktop');
+  assert.equal(await readFile(path.join(worktree, '.propr/previews/tracked.png'), 'utf8'), 'original');
+  await assert.rejects(access(path.join(worktree, '.propr/previews/desktop.png')));
+  await assert.rejects(access(path.join(worktree, '.propr/previews/manifest.json')));
+  assert.equal((await git.status()).files.length, 0);
+
+  const stagedDirectory = prepared.temporaryDirectory;
+  await cleanupPreparedVisualPreviewEvidence(prepared);
+  await assert.rejects(access(stagedDirectory!));
+});
+
+test('stages previews even when the repository ignores the transient directory', async () => {
+  const worktree = await createWorktree();
+  const git = simpleGit(worktree);
+  await git.init();
+  await git.addConfig('user.name', 'ProPR Test');
+  await git.addConfig('user.email', 'test@propr.dev');
+  await writeFile(path.join(worktree, '.gitignore'), '.propr/previews/\n');
+  await git.add('.gitignore');
+  await git.commit('ignore runtime previews');
 
-  const fallback = renderVisualPreviewSection(evidence, {
-    owner: 'integry', repo: 'propr', commitHash: 'abc123'
+  await writeFile(path.join(worktree, '.propr/previews/mobile.png'), 'mobile');
+  await writeFile(path.join(worktree, '.propr/previews/manifest.json'), JSON.stringify({
+    previews: [{ path: 'mobile.png', title: 'Mobile settings' }]
+  }));
+
+  const prepared = await prepareVisualPreviewEvidence({
+    worktreePath: worktree,
+    settings: { enabled: true, types: ['image'] },
+    taskId: 'ignored-preview'
   });
-  assert.match(fallback, /\[Watch Settings walkthrough\]\(https:\/\/github\.com\/integry\/propr\/blob\/abc123\/\.propr\/previews\/walkthrough\.mp4\?raw=true\)/);
-  assert.doesNotMatch(fallback, /!\[\]/);
+
+  assert.deepEqual(prepared.evidence.assets.map(asset => asset.title), ['Mobile settings']);
+  assert.equal(await readFile(prepared.evidence.assets[0].absolutePath, 'utf8'), 'mobile');
+  await assert.rejects(access(path.join(worktree, '.propr/previews')));
+  await cleanupPreparedVisualPreviewEvidence(prepared);
 });
diff --git a/src/github/visualPreviewAttachments.ts b/src/github/visualPreviewAttachments.ts
index 9fb516d37..84f5db45e 100644
--- a/src/github/visualPreviewAttachments.ts
+++ b/src/github/visualPreviewAttachments.ts
@@ -38,7 +38,6 @@ const runAttachmentCommand: AttachmentCommandRunner = async ({ args, authToken,
 interface BaseVisualPreviewPublicationOptions {
   owner: string;
   repo: string;
-  commitHash: string;
   body: string;
   evidence: VisualPreviewEvidence;
   authToken: string;
@@ -52,16 +51,27 @@ function attachmentArguments(evidence: VisualPreviewEvidence): string[] {
 
 function bodyWithLocalPreviews(options: BaseVisualPreviewPublicationOptions): string {
   const section = renderVisualPreviewSection(options.evidence, {
-    owner: options.owner,
-    repo: options.repo,
-    commitHash: options.commitHash,
     useLocalPaths: true
   });
   return appendVisualPreviewSection(options.body, section);
 }
 
+function assertUploadedBodyHasNoLocalPaths(body: unknown, evidence: VisualPreviewEvidence): asserts body is string {
+  if (typeof body !== 'string') {
+    throw new Error('GitHub uploaded visual previews but did not return the published body');
+  }
+  const leakedPath = evidence.assets.find(asset => body.includes(asset.absolutePath)
+    || body.includes(asset.absolutePath.replaceAll(' ', '%20')));
+  if (leakedPath) {
+    throw new Error('GitHub did not replace a local visual preview path with an uploaded attachment URL');
+  }
+}
+
 export interface PublishPullRequestVisualPreviewOptions extends BaseVisualPreviewPublicationOptions {
   pullRequestNumber: number;
+  octokit: {
+    request: <T = unknown>(endpoint: string, options: Record<string, unknown>) => Promise<T>;
+  };
 }
 
 export async function publishPullRequestVisualPreviews(options: PublishPullRequestVisualPreviewOptions): Promise<void> {
@@ -77,6 +87,12 @@ export async function publishPullRequestVisualPreviews(options: PublishPullReque
     authToken: options.authToken,
     cwd: options.worktreePath
   });
+  const response = await options.octokit.request<{ data: { body?: string } }>('GET /repos/{owner}/{repo}/pulls/{pull_number}', {
+    owner: options.owner,
+    repo: options.repo,
+    pull_number: options.pullRequestNumber
+  });
+  assertUploadedBodyHasNoLocalPaths(response.data.body, options.evidence);
 }
 
 export interface PublishPullRequestCommentVisualPreviewOptions extends BaseVisualPreviewPublicationOptions {
@@ -104,9 +120,9 @@ export async function publishPullRequestCommentVisualPreviews(
     throw new Error('Cannot publish an attachment comment without preview assets');
   }
   const runner = options.runCommand || runAttachmentCommand;
-  let result: { stdout: string };
+  let publishedCommentId: number | null = null;
   try {
-    result = await runner({
+    const result = await runner({
       args: [
         'pr', 'comment', String(options.pullRequestNumber),
         '--repo', `${options.owner}/${options.repo}`,
@@ -116,53 +132,46 @@ export async function publishPullRequestCommentVisualPreviews(
       authToken: options.authToken,
       cwd: options.worktreePath
     });
+    const commentUrl = result.stdout.trim().split('\n').find(line => line.includes('#issuecomment-')) || result.stdout.trim();
+    if (!commentUrl) throw new Error('GitHub CLI uploaded previews but did not return a comment URL');
+    publishedCommentId = parseCommentId(commentUrl);
+    if (!publishedCommentId) throw new Error('GitHub CLI uploaded previews but did not return a comment ID');
+
+    const response = await options.octokit.request<{ data: { body?: string } }>('GET /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+      owner: options.owner,
+      repo: options.repo,
+      comment_id: publishedCommentId
+    });
+    assertUploadedBodyHasNoLocalPaths(response.data.body, options.evidence);
+
+    try {
+      await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+        owner: options.owner,
+        repo: options.repo,
+        comment_id: options.startingCommentId
+      });
+    } catch {
+      // The attached completion comment is already published. Leaving the
+      // transient work comment is preferable to posting the completion twice.
+    }
+
+    return { html_url: commentUrl, body: response.data.body };
   } catch (error) {
-    const partialCommentId = parseCommentId(typeof (error as { stdout?: unknown })?.stdout === 'string'
+    publishedCommentId ||= parseCommentId(typeof (error as { stdout?: unknown })?.stdout === 'string'
       ? (error as { stdout: string }).stdout
       : '');
-    if (partialCommentId) {
+    if (publishedCommentId) {
       try {
         await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
           owner: options.owner,
           repo: options.repo,
-          comment_id: partialCommentId
+          comment_id: publishedCommentId
         });
       } catch {
-        // Best-effort cleanup; the caller still publishes the complete fallback.
+        // Best-effort cleanup; the caller replaces the work comment with a
+        // text-only explanation that contains no local filesystem paths.
       }
     }
     throw error;
   }
-
-  const commentUrl = result.stdout.trim().split('\n').find(line => line.includes('#issuecomment-')) || result.stdout.trim();
-  if (!commentUrl) throw new Error('GitHub CLI uploaded previews but did not return a comment URL');
-
-  let publishedBody = options.body;
-  const commentId = parseCommentId(commentUrl);
-  if (commentId) {
-    try {
-      const response = await options.octokit.request<{ data: { body?: string } }>('GET /repos/{owner}/{repo}/issues/comments/{comment_id}', {
-        owner: options.owner,
-        repo: options.repo,
-        comment_id: commentId
-      });
-      publishedBody = response.data.body || publishedBody;
-    } catch {
-      // The attachment comment itself is authoritative; body retrieval is only
-      // used to enrich task history with GitHub's rewritten attachment URLs.
-    }
-  }
-
-  try {
-    await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
-      owner: options.owner,
-      repo: options.repo,
-      comment_id: options.startingCommentId
-    });
-  } catch {
-    // The attached completion comment is already published. Leaving the
-    // transient work comment is preferable to posting the completion twice.
-  }
-
-  return { html_url: commentUrl, body: publishedBody };
 }
diff --git a/src/jobs/issueJobHelpers.ts b/src/jobs/issueJobHelpers.ts
index 0f5fffec4..dfb4eee44 100644
--- a/src/jobs/issueJobHelpers.ts
+++ b/src/jobs/issueJobHelpers.ts
@@ -11,6 +11,7 @@ import {
     isEpicBranch,
     appendVisualPreviewSection,
     renderVisualPreviewSection,
+    renderVisualPreviewUploadFailureSection,
     resolveAgentTerminationReason,
     type VisualPreviewEvidence
 } from '@propr/core';
@@ -204,11 +205,10 @@ ${completionComment}
 
 Comment on this PR to request refinements — the AI agent monitors comments and will update the implementation based on your feedback. Keep iterating until you're satisfied!`;
     const visualPreviewSection = visualPreview && commitResult
-        ? renderVisualPreviewSection(visualPreview.evidence, {
-            owner: issueRef.repoOwner,
-            repo: issueRef.repoName,
-            commitHash: commitResult.commitHash
-        })
+        ? renderVisualPreviewSection({
+            assets: [],
+            toolSuggestions: visualPreview.evidence.toolSuggestions
+        }, {})
         : '';
     const prBody = appendVisualPreviewSection(basePrBody, visualPreviewSection);
 
@@ -255,24 +255,24 @@ Comment on this PR to request refinements — the AI agent monitors comments and
                     owner: issueRef.repoOwner,
                     repo: issueRef.repoName,
                     pullRequestNumber: prResponse.data.number,
-                    commitHash: commitResult.commitHash,
                     body: basePrBody,
                     evidence: visualPreview.evidence,
                     authToken: visualPreview.authToken,
-                    worktreePath: visualPreview.worktreePath
+                    worktreePath: visualPreview.worktreePath,
+                    octokit
                 });
                 correlatedLogger.info({ prNumber: prResponse.data.number, previewCount: visualPreview.evidence.assets.length }, 'Uploaded visual previews to pull request');
             } catch (previewError) {
-                correlatedLogger.warn({ prNumber: prResponse.data.number, error: (previewError as Error).message }, 'Could not upload visual previews; committed-file links remain in the pull request body');
+                correlatedLogger.warn({ prNumber: prResponse.data.number, error: (previewError as Error).message }, 'Could not upload visual previews; publishing a text-only explanation');
                 try {
                     await octokit.request('PATCH /repos/{owner}/{repo}/pulls/{pull_number}', {
                         owner: issueRef.repoOwner,
                         repo: issueRef.repoName,
                         pull_number: prResponse.data.number,
-                        body: prBody
+                        body: appendVisualPreviewSection(basePrBody, renderVisualPreviewUploadFailureSection(visualPreview.evidence))
                     });
                 } catch (fallbackError) {
-                    correlatedLogger.warn({ prNumber: prResponse.data.number, error: (fallbackError as Error).message }, 'Could not restore committed-file visual preview links after a partial attachment upload');
+                    correlatedLogger.warn({ prNumber: prResponse.data.number, error: (fallbackError as Error).message }, 'Could not publish the text-only visual preview upload explanation');
                 }
             }
         }
diff --git a/src/jobs/issueJobPostProcessing.ts b/src/jobs/issueJobPostProcessing.ts
index 8878647e7..0da17fa4e 100644
--- a/src/jobs/issueJobPostProcessing.ts
+++ b/src/jobs/issueJobPostProcessing.ts
@@ -3,11 +3,8 @@ import { setTimeout } from 'timers/promises';
 import type { ClaudeCodeResponse } from '@propr/core';
 import type { WorktreeInfo, CommitResult, WorkerStateManager } from '@propr/core';
 import {
-    cleanupWorktree,
-    collectVisualPreviewEvidence,
-    commitChanges,
-    loadRepositoryVisualPreviewSettings,
-    pushBranch,
+    cleanupWorktree, cleanupPreparedVisualPreviewEvidence, commitChanges,
+    loadRepositoryVisualPreviewSettings, prepareVisualPreviewEvidence, pushBranch,
     TaskStates,
     describeAgentTermination,
     resolveAgentTerminationReason
@@ -187,6 +184,7 @@ export async function performPostProcessing(options: PostProcessOptions): Promis
     const { octokit, issueRef, worktreeInfo, currentIssueData, claudeResult, modelName, repoValidation, repoUrl, githubToken, PR_LABEL, AI_PROCESSING_TAG, AI_DONE_TAG, correlatedLogger, taskId, stateManager } = options;
     let commitResult: CommitResult | null = null;
     let postProcessingResult: PostProcessingResult | null = null;
+    let preparedVisualPreview: Awaited<ReturnType<typeof prepareVisualPreviewEvidence>> | undefined;
 
     try {
         if (!hasPublishableAgentWork(claudeResult)) {
@@ -207,6 +205,12 @@ export async function performPostProcessing(options: PostProcessOptions): Promis
             commitMessage = claudeResult.commitMessage;
         }
 
+        preparedVisualPreview = await prepareVisualPreviewEvidence({
+            worktreePath: worktreeInfo.worktreePath,
+            settings: await loadRepositoryVisualPreviewSettings(`${issueRef.repoOwner}/${issueRef.repoName}`),
+            taskId: taskId || `${issueRef.repoOwner}-${issueRef.repoName}-${issueRef.number}`
+        });
+
         commitResult = await commitChanges(
             worktreeInfo.worktreePath, commitMessage,
             AI_COMMIT_AUTHOR,
@@ -259,11 +263,7 @@ export async function performPostProcessing(options: PostProcessOptions): Promis
                 correlatedLogger,
                 issueTitle: currentIssueData.data.title,
                 visualPreview: {
-                    evidence: await collectVisualPreviewEvidence({
-                        worktreePath: worktreeInfo.worktreePath,
-                        changedFiles: commitResult.filesChanged || [],
-                        settings: await loadRepositoryVisualPreviewSettings(`${issueRef.repoOwner}/${issueRef.repoName}`)
-                    }),
+                    evidence: preparedVisualPreview.evidence,
                     authToken: githubToken.token,
                     worktreePath: worktreeInfo.worktreePath
                 }
@@ -290,6 +290,12 @@ export async function performPostProcessing(options: PostProcessOptions): Promis
         // fallback. A failed/interrupted run with no commit must remain retryable.
         const canMarkDone = claudeResult.success || commitResult !== null;
         postProcessingResult = await handlePostProcessingFailure(options, postProcessingError, canMarkDone);
+    } finally {
+        try {
+            await cleanupPreparedVisualPreviewEvidence(preparedVisualPreview);
+        } catch (cleanupError) {
+            correlatedLogger.warn({ error: getErrorMessage(cleanupError) }, 'Could not clean up staged visual previews');
+        }
     }
 
     return { commitResult, postProcessingResult };
diff --git a/src/jobs/prCommentPostExecution.ts b/src/jobs/prCommentPostExecution.ts
index 80873141c..7948a441c 100644
--- a/src/jobs/prCommentPostExecution.ts
+++ b/src/jobs/prCommentPostExecution.ts
@@ -3,14 +3,16 @@ import type { Logger } from 'pino';
 import type { Redis } from 'ioredis';
 import {
     commitChanges,
-    collectVisualPreviewEvidence,
+    cleanupPreparedVisualPreviewEvidence,
     db,
     getRepoUrl,
     getAuthenticatedOctokit,
     loadRepositoryVisualPreviewSettings,
+    prepareVisualPreviewEvidence,
     pushBranch,
     appendVisualPreviewSection,
     renderVisualPreviewSection,
+    renderVisualPreviewUploadFailureSection,
     resolveAgentTerminationReason,
     TaskStates,
     VISUAL_PREVIEW_SLOT,
@@ -141,20 +143,16 @@ interface CompletionCommentPublicationOptions {
     llm: string | null | undefined;
     taskUrl: string;
     unprocessedReviewComments: AIReviewComment[];
+    visualPreviewEvidence: Awaited<ReturnType<typeof prepareVisualPreviewEvidence>>['evidence'];
 }
 
 async function publishCompletionComment(options: CompletionCommentPublicationOptions): Promise<{ data: { html_url: string; body?: string } }> {
-    const { state, context, commitResult, changesSummary, commitMessage, llm, taskUrl, unprocessedReviewComments } = options;
+    const { state, context, commitResult, changesSummary, commitMessage, llm, taskUrl, unprocessedReviewComments, visualPreviewEvidence } = options;
     const { repoOwner, repoName, pullRequestNumber, correlatedLogger } = context;
-    const visualPreviewSettings = await loadRepositoryVisualPreviewSettings(`${repoOwner}/${repoName}`);
-    const visualPreviewEvidence = await collectVisualPreviewEvidence({
-        worktreePath: state.worktreeInfo.worktreePath,
-        changedFiles: commitResult?.filesChanged || [],
-        settings: visualPreviewSettings
-    });
-    const hasVisualPreviewContent = visualPreviewEvidence.assets.length > 0 || visualPreviewEvidence.toolSuggestions.length > 0;
-    const visualPreviewSection = commitResult && hasVisualPreviewContent
-        ? renderVisualPreviewSection(visualPreviewEvidence, { owner: repoOwner, repo: repoName, commitHash: commitResult.commitHash })
+    const hasVisualPreviewContent = Boolean(commitResult)
+        && (visualPreviewEvidence.assets.length > 0 || visualPreviewEvidence.toolSuggestions.length > 0);
+    const visualPreviewSection = hasVisualPreviewContent
+        ? renderVisualPreviewSection({ assets: [], toolSuggestions: visualPreviewEvidence.toolSuggestions }, {})
         : '';
     const undoContext = buildUndoContext({ commitResult, unprocessedComments: state.unprocessedComments, repoOwner, repoName, pullRequestNumber, branchName: state.worktreeInfo.branchName });
     const consumedReviewCommentIds = unprocessedReviewComments.length > 0 ? unprocessedReviewComments.map(comment => comment.id) : undefined;
@@ -185,7 +183,6 @@ async function publishCompletionComment(options: CompletionCommentPublicationOpt
             owner: repoOwner,
             repo: repoName,
             pullRequestNumber,
-            commitHash: commitResult.commitHash,
             body: prCommentTemplate,
             evidence: visualPreviewEvidence,
             authToken: githubToken.token,
@@ -195,12 +192,12 @@ async function publishCompletionComment(options: CompletionCommentPublicationOpt
         });
         return { data: published };
     } catch (previewError) {
-        correlatedLogger.warn({ pullRequestNumber, error: (previewError as Error).message }, 'Could not upload visual previews; publishing committed-file links in the completion comment');
+        correlatedLogger.warn({ pullRequestNumber, error: (previewError as Error).message }, 'Could not upload visual previews; publishing a text-only explanation');
         return state.octokit.request('PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}', {
             owner: repoOwner,
             repo: repoName,
             comment_id: state.startingWorkComment.data.id,
-            body: prCommentBody
+            body: appendVisualPreviewSection(prCommentTemplate, renderVisualPreviewUploadFailureSection(visualPreviewEvidence))
         }) as Promise<{ data: { html_url: string; body?: string } }>;
     }
 }
@@ -228,41 +225,65 @@ export async function handlePostExecution(params: PostExecutionParams, taskUrl:
         throw new Error(`Agent execution failed: ${state.claudeResult.error || 'Unknown error'}`);
     }
 
-    const { commitResult, changesSummary, commitMessage } = await commitAndPush(state, { repoOwner, repoName, pullRequestNumber }, llm);
-    if (partial && !commitResult) {
-        throw new Error(`Agent execution ${terminationReason === 'timeout' ? 'timed out' : 'reached the maximum turn limit'} before producing changes to publish`);
-    }
-    if (commitResult?.filesChanged?.length) state.claudeResult.modifiedFiles = commitResult.filesChanged;
-
-    const completionComment = await publishCompletionComment({ state, context, commitResult, changesSummary, commitMessage, llm, taskUrl, unprocessedReviewComments });
-    correlatedLogger.info({ pullRequestNumber, commitHash: commitResult?.commitHash, commentUrl: completionComment.data.html_url, partial, terminationReason }, partial ? 'Published partial follow-up changes after interrupted execution' : 'Successfully applied follow-up changes');
-
-    if (unprocessedReviewComments.length > 0) {
-        await markReviewFindingsProcessed(unprocessedReviewComments, {
-            repoOwner,
-            repoName,
-            pullRequestNumber,
-            redisClient,
-            correlatedLogger,
-            prProcessingLockKey,
-            prProcessingLockToken,
+    let preparedVisualPreview: Awaited<ReturnType<typeof prepareVisualPreviewEvidence>> | undefined;
+    try {
+        preparedVisualPreview = await prepareVisualPreviewEvidence({
+            worktreePath: state.worktreeInfo.worktreePath,
+            settings: await loadRepositoryVisualPreviewSettings(`${repoOwner}/${repoName}`),
+            taskId
         });
-    }
+        const { commitResult, changesSummary, commitMessage } = await commitAndPush(state, { repoOwner, repoName, pullRequestNumber }, llm);
+        if (partial && !commitResult) {
+            throw new Error(`Agent execution ${terminationReason === 'timeout' ? 'timed out' : 'reached the maximum turn limit'} before producing changes to publish`);
+        }
+        if (commitResult?.filesChanged?.length) state.claudeResult.modifiedFiles = commitResult.filesChanged;
 
-    const ultrafixHistoryMeta = await resolveUltrafixHistoryMeta(job, { repoOwner, repoName, pullRequestNumber }, redisClient);
+        const completionComment = await publishCompletionComment({
+            state,
+            context,
+            commitResult,
+            changesSummary,
+            commitMessage,
+            llm,
+            taskUrl,
+            unprocessedReviewComments,
+            visualPreviewEvidence: preparedVisualPreview.evidence
+        });
+        correlatedLogger.info({ pullRequestNumber, commitHash: commitResult?.commitHash, commentUrl: completionComment.data.html_url, partial, terminationReason }, partial ? 'Published partial follow-up changes after interrupted execution' : 'Successfully applied follow-up changes');
 
-    await stateManager.updateTaskState(taskId, TaskStates.COMPLETED, {
-        reason: partial ? 'PR comment processing published partial work after interrupted execution' : 'PR comment processing completed successfully',
-        commitHash: commitResult?.commitHash,
-        historyMetadata: {
-            commandMode: job.data.commandMode || 'default',
-            githubComment: { url: completionComment.data.html_url, body: completionComment.data.body },
-            ...(unprocessedReviewComments.length > 0 && { consumedReviewCommentIds: unprocessedReviewComments.map(c => c.id) }),
-            ...(partial && { incompleteExecution: { reason: terminationReason } }),
-            ...ultrafixHistoryMeta,
+        if (unprocessedReviewComments.length > 0) {
+            await markReviewFindingsProcessed(unprocessedReviewComments, {
+                repoOwner,
+                repoName,
+                pullRequestNumber,
+                redisClient,
+                correlatedLogger,
+                prProcessingLockKey,
+                prProcessingLockToken,
+            });
         }
-    });
 
-    await persistCommitHash(taskId, commitResult?.commitHash, correlatedLogger);
-    return { commitHash: commitResult?.commitHash, partial };
+        const ultrafixHistoryMeta = await resolveUltrafixHistoryMeta(job, { repoOwner, repoName, pullRequestNumber }, redisClient);
+
+        await stateManager.updateTaskState(taskId, TaskStates.COMPLETED, {
+            reason: partial ? 'PR comment processing published partial work after interrupted execution' : 'PR comment processing completed successfully',
+            commitHash: commitResult?.commitHash,
+            historyMetadata: {
+                commandMode: job.data.commandMode || 'default',
+                githubComment: { url: completionComment.data.html_url, body: completionComment.data.body },
+                ...(unprocessedReviewComments.length > 0 && { consumedReviewCommentIds: unprocessedReviewComments.map(c => c.id) }),
+                ...(partial && { incompleteExecution: { reason: terminationReason } }),
+                ...ultrafixHistoryMeta,
+            }
+        });
+
+        await persistCommitHash(taskId, commitResult?.commitHash, correlatedLogger);
+        return { commitHash: commitResult?.commitHash, partial };
+    } finally {
+        try {
+            await cleanupPreparedVisualPreviewEvidence(preparedVisualPreview);
+        } catch (cleanupError) {
+            correlatedLogger.warn({ error: (cleanupError as Error).message }, 'Could not clean up staged visual previews');
+        }
+    }
 }
diff --git a/test/issueJobUnpublishableFailure.test.ts b/test/issueJobUnpublishableFailure.test.ts
index 574de5280..5d512cb89 100644
--- a/test/issueJobUnpublishableFailure.test.ts
+++ b/test/issueJobUnpublishableFailure.test.ts
@@ -11,9 +11,10 @@ const resolveAgentTerminationReason = mock.fn((result: { terminationReason?: 'ti
 await mock.module('@propr/core', {
     namedExports: {
         cleanupWorktree: mock.fn(async () => undefined),
-        collectVisualPreviewEvidence: mock.fn(async () => ({ assets: [], toolSuggestions: [] })),
+        cleanupPreparedVisualPreviewEvidence: mock.fn(async () => undefined),
         commitChanges,
         loadRepositoryVisualPreviewSettings: mock.fn(async () => ({ enabled: false, types: ['image'] })),
+        prepareVisualPreviewEvidence: mock.fn(async () => ({ evidence: { assets: [], toolSuggestions: [] } })),
         pushBranch,
         AI_COMMIT_AUTHOR: { name: 'ProPR AI', email: 'ai@propr.dev' },
         TaskStates: { CANCELLED: 'cancelled' },
diff --git a/test/visualPreviewAttachments.test.ts b/test/visualPreviewAttachments.test.ts
index 358f8f596..5f088280e 100644
--- a/test/visualPreviewAttachments.test.ts
+++ b/test/visualPreviewAttachments.test.ts
@@ -27,16 +27,22 @@ const evidence = {
 
 test('edits a pull request with uploaded visual preview attachments', async () => {
   let invocation: { args: string[]; authToken: string; cwd: string } | undefined;
+  const requests: Array<{ endpoint: string; options: Record<string, unknown> }> = [];
 
   await publishPullRequestVisualPreviews({
     owner: 'integry',
     repo: 'propr',
     pullRequestNumber: 42,
-    commitHash: 'abc123',
     body: 'Implementation summary',
     evidence,
     authToken: 'installation-token',
     worktreePath: '/worktree',
+    octokit: {
+      request: async <T>(endpoint: string, options: Record<string, unknown>) => {
+        requests.push({ endpoint, options });
+        return { data: { body: '![Desktop settings](https://github.com/user-attachments/assets/asset-id)' } } as T;
+      }
+    },
     runCommand: async options => {
       invocation = options;
       return { stdout: '' };
@@ -49,6 +55,23 @@ test('edits a pull request with uploaded visual preview attachments', async () =
   assert.deepEqual(invocation.args.slice(-2), ['--attach', '/worktree/.propr/previews/desktop.png']);
   assert.equal(invocation.authToken, 'installation-token');
   assert.equal(invocation.args.includes('installation-token'), false);
+  assert.deepEqual(requests.map(request => request.endpoint), ['GET /repos/{owner}/{repo}/pulls/{pull_number}']);
+});
+
+test('rejects a pull request upload when GitHub leaves a local path in the body', async () => {
+  await assert.rejects(() => publishPullRequestVisualPreviews({
+    owner: 'integry',
+    repo: 'propr',
+    pullRequestNumber: 42,
+    body: 'Implementation summary',
+    evidence,
+    authToken: 'installation-token',
+    worktreePath: '/worktree',
+    octokit: {
+      request: async <T>() => ({ data: { body: '![Desktop settings](/worktree/.propr/previews/desktop.png)' } }) as T
+    },
+    runCommand: async () => ({ stdout: '' })
+  }), /did not replace a local visual preview path/);
 });
 
 test('publishes an attached completion comment before removing the transient work comment', async () => {
@@ -57,7 +80,6 @@ test('publishes an attached completion comment before removing the transient wor
     owner: 'integry',
     repo: 'propr',
     pullRequestNumber: 42,
-    commitHash: 'abc123',
     body: 'Follow-up complete',
     evidence,
     authToken: 'installation-token',
@@ -89,7 +111,6 @@ test('removes a partially published attachment comment before surfacing upload f
     owner: 'integry',
     repo: 'propr',
     pullRequestNumber: 42,
-    commitHash: 'abc123',
     body: 'Follow-up complete',
     evidence,
     authToken: 'installation-token',
@@ -110,3 +131,29 @@ test('removes a partially published attachment comment before surfacing upload f
 
   assert.deepEqual(deletedCommentIds, [201]);
 });
+
+test('deletes an uploaded comment whose fetched body still contains a local path', async () => {
+  const deletedCommentIds: unknown[] = [];
+  await assert.rejects(() => publishPullRequestCommentVisualPreviews({
+    owner: 'integry',
+    repo: 'propr',
+    pullRequestNumber: 42,
+    body: 'Follow-up complete',
+    evidence,
+    authToken: 'installation-token',
+    worktreePath: '/worktree',
+    startingCommentId: 100,
+    octokit: {
+      request: async <T>(endpoint: string, options: Record<string, unknown>) => {
+        if (endpoint.startsWith('GET ')) {
+          return { data: { body: '![Desktop settings](/worktree/.propr/previews/desktop.png)' } } as T;
+        }
+        deletedCommentIds.push(options.comment_id);
+        return {} as T;
+      }
+    },
+    runCommand: async () => ({ stdout: 'https://github.com/integry/propr/pull/42#issuecomment-202' })
+  }), /did not replace a local visual preview path/);
+
+  assert.deepEqual(deletedCommentIds, [202]);
+});

From 37113e76b1d8005b1a3225a385d6ca2e9c5d674b Mon Sep 17 00:00:00 2001
From: "propr-dev[bot]" <1316198+propr-dev[bot]@users.noreply.github.com>
Date: Thu, 3 Sep 2026 12:31:04 +0000
Subject: [PATCH 04/18] feat(ai): Updated
 [visualPreviewService.ts](/tmp/git-processor/worktrees/integry/propr/pr-2102-followup-2026-09-03T12-28-37/packages/core/src/services/visualPreviewService.ts:217).

Updated [visualPreviewService.ts](/tmp/git-processor/worktrees/integry/propr/pr-2102-followup-2026-09-03T12-28-37/packages/core/src/services/visualPreviewService.ts:217).

Replaced the CodeQL-flagged trimming regex with linear index scans while preserving normalization behavior and the 80-character limit.

Validation passed:

- 7 focused visual-preview tests
- Core typecheck
- Core lint
- `git diff --check`

No commit created.

PR: #2102
Comment by: @integry (ID: 5525753130)
Model: gpt-5.6-sol
---
 packages/core/src/services/visualPreviewService.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/core/src/services/visualPreviewService.ts b/packages/core/src/services/visualPreviewService.ts
index 3eaf823a2..8728a919d 100644
--- a/packages/core/src/services/visualPreviewService.ts
+++ b/packages/core/src/services/visualPreviewService.ts
@@ -215,7 +215,12 @@ export async function collectVisualPreviewEvidence({
 }
 
 function safeTemporaryName(taskId: string): string {
-  const normalized = taskId.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
+  const sanitized = taskId.replace(/[^a-zA-Z0-9_-]+/g, '-');
+  let start = 0;
+  let end = sanitized.length;
+  while (sanitized[start] === '-') start += 1;
+  while (end > start && sanitized[end - 1] === '-') end -= 1;
+  const normalized = sanitized.slice(start, Math.min(end, start + 80));
   return normalized || 'task';
 }
 

From b186f354b86adf95ef80a0f152290c27afe75c2d Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 17:35:24 +0200
Subject: [PATCH 05/18] fix(agents): prepare runtime images once per lifecycle

---
 package.json                                  |   2 +-
 packages/core/src/agents/AgentRegistry.ts     | 202 +++++++++---------
 .../core/src/agents/agentImagePreparation.ts  | 108 ++++++++++
 .../core/src/claude/docker/dockerExecutor.ts  |   2 +-
 .../src/claude/docker/dockerImageBuilder.ts   |  61 ++++--
 src/worker.ts                                 |  72 ++++---
 test/agentImagePreparation.test.ts            |  49 +++++
 test/agentRegistryOpenCode.test.ts            |  55 +++++
 8 files changed, 401 insertions(+), 150 deletions(-)
 create mode 100644 packages/core/src/agents/agentImagePreparation.ts
 create mode 100644 test/agentImagePreparation.test.ts

diff --git a/package.json b/package.json
index 77f220b14..367bb996d 100644
--- a/package.json
+++ b/package.json
@@ -24,7 +24,7 @@
     "test:notifications:server": "node scripts/run-test-suite.mjs test/notificationSchema.test.ts test/notificationPreferenceMigration.test.ts packages/core/test/notificationService.test.ts packages/core/test/planNotificationActionsMigration.test.ts packages/core/test/pushSubscriptionExpiration.test.ts packages/api/test/notificationRoutes.test.ts packages/api/test/notificationManagementRoutes.test.ts packages/api/test/notificationProjectionService.test.ts packages/api/test/webPushDispatcher.test.ts",
     "test:notifications:ui": "npm --workspace propr-ui test -- src/api/notificationApi.test.ts src/serviceWorker.test.ts src/serviceWorkerRegistration.test.ts src/hooks/useBrowserPush.test.tsx src/pages/SettingsPage/NotificationSettingsSection.test.tsx src/pages/InboxPage.test.tsx src/pages/inboxUtils.test.ts src/components/Inbox/NotificationActions.test.tsx src/components/MobileBottomNavigation.test.tsx src/contexts/NotificationCenterContext.test.tsx src/utils/notificationIntents.test.ts src/pages/PlanStudioPage.notificationIntent.test.tsx src/components/TaskPlanner/PlanEditor.notificationIntent.test.tsx src/components/TaskPlanner/PlanIssuesManager.notificationIntent.test.tsx src/components/TaskPlanner/PlanEditor.responsive.test.tsx",
     "test:notifications": "npm run build -w @propr/shared && npm run build -w @propr/core && npm run test:notifications:server && npm run test:notifications:ui",
-    "test:unit": "NODE_ENV=test npx tsx --experimental-test-module-mocks --test test/minimal.test.ts test/modelName.test.ts test/agentContainerResources.test.ts test/agentDockerfileSupplyChain.test.ts test/daemonEventIntake.test.ts test/databaseMigrationGate.test.ts test/deployPrPreview.test.mjs test/generateContext.test.ts test/githubEventIntakeMode.test.ts test/intakeModePrerequisites.test.ts test/orchestratorMigrationPhase.test.mjs test/validateRoutingUrl.test.ts test/routingWebSocketProtocol.test.ts test/routingWebSocketIntakeService.test.ts test/routingStatusPublisher.test.ts test/releaseValidation.test.mjs test/sessionSecret.test.ts test/testSuiteRunner.test.mjs packages/api/test/connectAuth.test.ts packages/api/test/attachmentUploadCleanup.test.ts packages/api/test/configReloadSubscription.test.ts packages/api/test/dockerCommandSafety.test.ts packages/api/test/listenAddress.test.ts packages/api/test/oauthState.test.ts packages/api/test/requestRateLimits.test.ts packages/api/test/statusRoutes.test.ts packages/api/test/agentRuntimeRoutes.test.ts packages/api/test/instanceAuthorization.test.ts packages/api/test/routeAuthorization.test.ts",
+    "test:unit": "NODE_ENV=test npx tsx --experimental-test-module-mocks --test test/minimal.test.ts test/modelName.test.ts test/agentContainerResources.test.ts test/agentDockerfileSupplyChain.test.ts test/agentImagePreparation.test.ts test/daemonEventIntake.test.ts test/databaseMigrationGate.test.ts test/deployPrPreview.test.mjs test/generateContext.test.ts test/githubEventIntakeMode.test.ts test/intakeModePrerequisites.test.ts test/orchestratorMigrationPhase.test.mjs test/validateRoutingUrl.test.ts test/routingWebSocketProtocol.test.ts test/routingWebSocketIntakeService.test.ts test/routingStatusPublisher.test.ts test/releaseValidation.test.mjs test/sessionSecret.test.ts test/testSuiteRunner.test.mjs packages/api/test/connectAuth.test.ts packages/api/test/attachmentUploadCleanup.test.ts packages/api/test/configReloadSubscription.test.ts packages/api/test/dockerCommandSafety.test.ts packages/api/test/listenAddress.test.ts packages/api/test/oauthState.test.ts packages/api/test/requestRateLimits.test.ts packages/api/test/statusRoutes.test.ts packages/api/test/agentRuntimeRoutes.test.ts packages/api/test/instanceAuthorization.test.ts packages/api/test/routeAuthorization.test.ts",
     "test:e2e": "npx tsx --test test/e2e.test.ts",
     "test:docker": "docker-compose run --rm -e REDIS_HOST=redis -e NODE_ENV=test worker npx tsx --test test/*.test.ts",
     "test:docker:single": "docker-compose run --rm -e REDIS_HOST=redis -e NODE_ENV=test worker npx tsx --test",
diff --git a/packages/core/src/agents/AgentRegistry.ts b/packages/core/src/agents/AgentRegistry.ts
index c5322f9c7..2cb7fc2c8 100644
--- a/packages/core/src/agents/AgentRegistry.ts
+++ b/packages/core/src/agents/AgentRegistry.ts
@@ -1,19 +1,14 @@
-import path from 'path';
-import os from 'os';
 import logger from '../utils/logger.js';
 import { Agent, AgentConfig } from './types.js';
 import { ClaudeAgent } from './impl/ClaudeAgent.js';
 import * as configManager from '../config/configManager.js';
-import { ensureAgentBundleImage, ensureAgentDockerImage, executeDockerCommand } from '../claude/docker/dockerExecutor.js';
+import { executeDockerCommand } from '../claude/docker/dockerExecutor.js';
 import { closeConnection } from '../db/connection.js';
 import { shutdownQueue } from '../queue/taskQueue.js';
-import { computeContentHash, getAgentCliVersionMatrix, getDefaultAgentCliVersionMatrix } from './version/versionService.js';
-import { AGENT_DEFAULT_VERSIONS } from './version/types.js';
-import { DEFAULT_AGENT_DOCKER_IMAGES } from './constants.js';
-import { loadAgentRuntimePackageState, resolveAgentRuntimeImage } from './runtime/agentRuntimePackages.js';
-import { AGENT_DEFAULTS } from '../config/modelDefinitions.js';
+import { loadAgentRuntimePackageState } from './runtime/agentRuntimePackages.js';
 import { SyntheticAgentRegistry, type BeginSyntheticRoutingOptions, type SyntheticRoutingSession } from './SyntheticAgentRegistry.js';
 import { createAgentFromConfig } from './createAgentFromConfig.js';
+import { resolveDefaultAgentConfig, resolveUnifiedAgentImage } from './agentImagePreparation.js';
 
 export interface AgentRegistryOperationalStatus {
     unifiedAgentImage: {
@@ -41,6 +36,8 @@ export class AgentRegistry {
     private runtimePackagesUpdatedAt: string | undefined;
     private runtimePackageStateCheckAfter = 0;
     private runtimePackageStateUnavailable = false;
+    private pendingRefresh: Promise<void> | null = null;
+    private pendingRefreshPreparesImages = false;
     private pendingBackgroundRefresh: Promise<void> | null = null;
     private unavailableUnifiedAgentImage: { imageTag?: string; error: string; recordedAt: string } | null = null;
     private unifiedAgentImageRetryTimer: NodeJS.Timeout | null = null;
@@ -62,9 +59,40 @@ export class AgentRegistry {
 
     /**
      * Reloads configuration from configManager and instantiates agents.
-     * This should be called at startup and whenever configuration changes.
+     * This is deliberately read-only with respect to Docker images. Request and
+     * task paths may refresh the registry, but image preparation belongs to the
+     * worker's startup/configuration lifecycle.
      */
-    async refresh(): Promise<void> {
+    refresh(): Promise<void> {
+        return this.requestRefresh(false);
+    }
+
+    /**
+     * Prepares missing base and runtime-package images, then refreshes the
+     * registry. The main worker calls this at startup and when agent version
+     * configuration changes; ordinary registry consumers must use refresh().
+     */
+    prepareImagesAndRefresh(): Promise<void> {
+        return this.requestRefresh(true);
+    }
+
+    private requestRefresh(prepareImages: boolean): Promise<void> {
+        if (this.pendingRefresh) {
+            if (!prepareImages || this.pendingRefreshPreparesImages) return this.pendingRefresh;
+            return this.pendingRefresh.then(() => this.requestRefresh(true));
+        }
+
+        this.pendingRefreshPreparesImages = prepareImages;
+        const refresh = this.refreshRegistry(prepareImages)
+            .finally(() => {
+                this.pendingRefresh = null;
+                this.pendingRefreshPreparesImages = false;
+            });
+        this.pendingRefresh = refresh;
+        return refresh;
+    }
+
+    private async refreshRegistry(prepareImages: boolean): Promise<void> {
         logger.info('Refreshing agent registry...');
 
         try {
@@ -81,27 +109,32 @@ export class AgentRegistry {
                 this.defaultAgentAlias = null;
             }
 
-            // Clear existing maps
-            this.agents.clear();
-            this.agentsByAlias.clear();
-
             if (configs.length === 0) {
                 // Fallback: Create default Claude agent from ENV vars if no config exists
                 logger.info('No agents configured, creating default Claude agent from environment');
-                await this.registerDefaultAgent();
+                await this.registerDefaultAgent(prepareImages);
                 await this.captureRuntimePackageStateVersion();
                 this.initialized = true;
                 return;
             }
 
-            const bundleImage = await this.ensureUnifiedAgentImage(configs);
+            const bundleImage = await this.ensureUnifiedAgentImage(configs, prepareImages);
             if (!bundleImage) {
                 await this.captureRuntimePackageStateVersion();
                 this.initialized = true;
-                logger.warn('Agent registry initialized without agents because the unified agent image is unavailable');
+                logger.warn(
+                    this.agents.size > 0
+                        ? 'Keeping existing agents because the newly configured unified image is unavailable'
+                        : 'Agent registry initialized without agents because the unified agent image is unavailable',
+                );
                 return;
             }
 
+            // Resolve potentially slow image work before replacing the live
+            // registry, so a package/version rebuild does not interrupt tasks
+            // that can still use the previous image.
+            this.agents.clear();
+            this.agentsByAlias.clear();
             for (const config of configs) {
                 if (!config.enabled) {
                     logger.debug({ agentAlias: config.alias }, 'Skipping disabled agent');
@@ -154,10 +187,9 @@ export class AgentRegistry {
             const err = error as Error;
             logger.error({ error: err.message }, 'Failed to refresh agent registry, using default agent');
 
-            // Fallback to default agent on error
-            this.agents.clear();
-            this.agentsByAlias.clear();
-            await this.registerDefaultAgent();
+            // Fallback to the default agent only after its image resolves; a
+            // failed fallback leaves any previously working registry intact.
+            await this.registerDefaultAgent(prepareImages);
             await this.captureRuntimePackageStateVersion();
             this.initialized = true;
         }
@@ -264,9 +296,9 @@ export class AgentRegistry {
      * Ensures the registry is initialized, refreshing if necessary.
      *
      * When a runtime package state change is detected on an already-initialized
-     * registry, the refresh runs in the background: a refresh may pull or build
-     * the bundle image (minutes), and callers sit on request-serving paths, so
-     * they keep using the current agents until the refresh completes.
+     * registry, the inspect-only refresh runs in the background. The dedicated
+     * runtime build worker prepares changed package images before publishing the
+     * new state, so request-serving paths never start Docker builds themselves.
      */
     async ensureInitialized(): Promise<void> {
         if (!this.initialized) {
@@ -285,10 +317,9 @@ export class AgentRegistry {
             return;
         }
 
-        // Managed bundle cleanup and development content-hash changes can
-        // remove an image after registry initialization. Verify the cached
-        // image immediately before callers resolve an agent, and synchronously
-        // refresh so execution never reaches Docker with a missing local tag.
+        // If an image disappears after initialization, synchronously reload the
+        // inspect-only registry state so execution never reaches Docker with a
+        // missing local tag. Rebuilding remains the startup/config owner's job.
         if (!(await this.registeredAgentImagesAvailable())) {
             if (!this.pendingBackgroundRefresh) {
                 logger.warn('Refreshing agent registry because a registered agent image is no longer available locally');
@@ -364,41 +395,23 @@ export class AgentRegistry {
         }
     }
 
-    private async ensureUnifiedAgentImage(configs: AgentConfig[]): Promise<string | null> {
-        try {
-            const versions = getAgentCliVersionMatrix(configs);
-            const result = await ensureAgentBundleImage(versions, computeContentHash());
-            if (!result.success) {
-                logger.error({ error: result.error, imageTag: result.imageTag }, 'Failed to ensure unified agent image');
-                this.unavailableUnifiedAgentImage = {
-                    imageTag: result.imageTag,
-                    error: result.error || 'Unified agent image is unavailable',
-                    recordedAt: new Date().toISOString()
-                };
-                this.scheduleUnifiedAgentImageRetry();
-                return null;
-            }
-            const image = await resolveAgentRuntimeImage(result.imageTag, { buildMissing: false });
-            this.clearUnifiedAgentImageRetry();
-            this.unavailableUnifiedAgentImage = null;
-            return image;
-        } catch (error) {
-            const message = (error as Error).message;
-            logger.error({ error: message }, 'Failed to resolve unified agent image');
-            this.unavailableUnifiedAgentImage = {
-                error: message,
-                recordedAt: new Date().toISOString()
-            };
-            this.scheduleUnifiedAgentImageRetry();
+    private async ensureUnifiedAgentImage(configs: AgentConfig[], prepareImages: boolean): Promise<string | null> {
+        const result = await resolveUnifiedAgentImage(configs, prepareImages);
+        if (!result.image) {
+            const error = result.error || 'Unified agent image is unavailable';
+            logger.error({ error, imageTag: result.imageTag }, 'Failed to resolve unified agent image');
+            this.recordUnavailableUnifiedAgentImage(result.imageTag, error);
             return null;
         }
+        this.clearUnifiedAgentImageRetry();
+        this.unavailableUnifiedAgentImage = null;
+        return result.image;
     }
 
     /**
-     * A transient registry pull or artifact download must not leave an initialized
-     * but empty registry wedged until an operator edits configuration or restarts
-     * the service. Retry in the background with one shared timer; refresh already
-     * serializes the actual pull/build through the registry's normal path.
+     * A consumer can initialize while the worker is still preparing the image.
+     * Poll the local image state with one shared timer so it becomes ready after
+     * startup completes; refresh() is inspect-only and cannot launch a build.
      */
     private scheduleUnifiedAgentImageRetry(): void {
         if (this.unifiedAgentImageRetryTimer) return;
@@ -440,62 +453,41 @@ export class AgentRegistry {
      * Registers a default Claude agent using environment variables.
      * This is the fallback when no agents are configured.
      */
-    private async registerDefaultAgent(): Promise<void> {
-        const defaultConfig: AgentConfig = {
-            id: 'default-claude-agent',
-            type: 'claude',
-            alias: 'default',
-            enabled: true,
-            dockerImage: process.env.AGENT_DOCKER_IMAGE || DEFAULT_AGENT_DOCKER_IMAGES.claude,
-            configPath: process.env.CLAUDE_CONFIG_PATH || path.join(os.homedir(), '.claude'),
-            supportedModels: [...AGENT_DEFAULTS.claude.defaultModels],
-            defaultModel: process.env.CLAUDE_MODEL || undefined,
-            cliVersionType: 'default',
-            cliVersionResolved: AGENT_DEFAULT_VERSIONS.claude
-        };
-
-        if (process.env.AGENT_DOCKER_IMAGE) {
-            try {
-                const available = await ensureAgentDockerImage(defaultConfig.type, process.env.AGENT_DOCKER_IMAGE);
-                if (!available) {
-                    logger.warn({ dockerImage: process.env.AGENT_DOCKER_IMAGE }, 'Configured default agent image is not available locally and could not be pulled or built');
-                }
-                defaultConfig.dockerImage = await resolveAgentRuntimeImage(process.env.AGENT_DOCKER_IMAGE, { buildMissing: false });
-            } catch (error) {
-                logger.error(
-                    { dockerImage: defaultConfig.dockerImage, error: (error as Error).message },
-                    'Failed to resolve default Claude agent runtime image; registering the configured image for degraded-mode health checks',
-                );
-            }
-        } else {
-            try {
-                const result = await ensureAgentBundleImage(getDefaultAgentCliVersionMatrix(), computeContentHash());
-                if (!result.success) {
-                    logger.error({ error: result.error, imageTag: result.imageTag }, 'Failed to ensure default agent image; registering fallback image for degraded-mode health checks');
-                } else {
-                    defaultConfig.dockerImage = await resolveAgentRuntimeImage(result.imageTag, { buildMissing: false });
-                }
-            } catch (error) {
-                logger.error(
-                    { dockerImage: defaultConfig.dockerImage, error: (error as Error).message },
-                    'Failed to resolve default Claude agent image; registering fallback image for degraded-mode health checks',
-                );
-            }
+    private async registerDefaultAgent(prepareImages: boolean): Promise<void> {
+        const result = await resolveDefaultAgentConfig(prepareImages);
+        if (!result.config) {
+            const error = result.error || 'Default agent image is unavailable';
+            this.recordUnavailableUnifiedAgentImage(result.imageTag, error);
+            logger.error({ dockerImage: result.imageTag, error }, 'Failed to resolve default Claude agent image');
+            return;
         }
 
-        const agent = new ClaudeAgent(defaultConfig);
-        this.agents.set(defaultConfig.id, agent);
-        this.agentsByAlias.set(defaultConfig.alias, agent);
+        this.clearUnifiedAgentImageRetry();
+        this.unavailableUnifiedAgentImage = null;
+        this.agents.clear();
+        this.agentsByAlias.clear();
+        const agent = new ClaudeAgent(result.config);
+        this.agents.set(result.config.id, agent);
+        this.agentsByAlias.set(result.config.alias, agent);
 
         await this.syntheticAgents.register();
 
         logger.info({
-            agentId: defaultConfig.id,
-            agentAlias: defaultConfig.alias,
-            dockerImage: defaultConfig.dockerImage
+            agentId: result.config.id,
+            agentAlias: result.config.alias,
+            dockerImage: result.config.dockerImage
         }, 'Default Claude agent registered');
     }
 
+    private recordUnavailableUnifiedAgentImage(imageTag: string | undefined, error: string): void {
+        this.unavailableUnifiedAgentImage = {
+            imageTag,
+            error,
+            recordedAt: new Date().toISOString(),
+        };
+        this.scheduleUnifiedAgentImageRetry();
+    }
+
     /**
      * Clean up resources and connections.
      * Should be called during shutdown or test cleanup.
diff --git a/packages/core/src/agents/agentImagePreparation.ts b/packages/core/src/agents/agentImagePreparation.ts
new file mode 100644
index 000000000..cbae90014
--- /dev/null
+++ b/packages/core/src/agents/agentImagePreparation.ts
@@ -0,0 +1,108 @@
+import os from 'node:os';
+import path from 'node:path';
+import { AGENT_DEFAULTS } from '../config/modelDefinitions.js';
+import {
+    agentDockerImageExists,
+    ensureAgentBundleImage,
+    ensureAgentDockerImage,
+} from '../claude/docker/dockerExecutor.js';
+import { resolveAgentRuntimeImage } from './runtime/agentRuntimePackages.js';
+import type { AgentConfig } from './types.js';
+import { AGENT_DEFAULT_VERSIONS } from './version/types.js';
+import {
+    computeContentHash,
+    generateAgentBundleImageTag,
+    getAgentCliVersionMatrix,
+} from './version/versionService.js';
+
+export interface AgentImageResolution {
+    image?: string;
+    imageTag?: string;
+    error?: string;
+}
+
+async function resolveBundleBaseImage(
+    configs: AgentConfig[],
+    prepareImages: boolean,
+): Promise<AgentImageResolution> {
+    const versions = getAgentCliVersionMatrix(configs);
+    const contentHash = computeContentHash();
+    const imageTag = generateAgentBundleImageTag(versions, contentHash);
+    if (prepareImages) {
+        const result = await ensureAgentBundleImage(versions, contentHash);
+        return result.success
+            ? { image: result.imageTag, imageTag: result.imageTag }
+            : { imageTag: result.imageTag, error: result.error || 'Unified agent image is unavailable' };
+    }
+    return await agentDockerImageExists(imageTag)
+        ? { image: imageTag, imageTag }
+        : { imageTag, error: `Unified agent image ${imageTag} has not been prepared by the worker` };
+}
+
+export async function resolveUnifiedAgentImage(
+    configs: AgentConfig[],
+    prepareImages: boolean,
+): Promise<AgentImageResolution> {
+    try {
+        const base = await resolveBundleBaseImage(configs, prepareImages);
+        if (!base.image) return base;
+        return {
+            image: await resolveAgentRuntimeImage(base.image, { buildMissing: prepareImages }),
+            imageTag: base.imageTag,
+        };
+    } catch (error) {
+        return { error: (error as Error).message };
+    }
+}
+
+async function resolveConfiguredDefaultImage(
+    dockerImage: string,
+    prepareImages: boolean,
+): Promise<AgentImageResolution> {
+    const available = prepareImages
+        ? await ensureAgentDockerImage('claude', dockerImage)
+        : await agentDockerImageExists(dockerImage);
+    if (!available) {
+        return {
+            imageTag: dockerImage,
+            error: prepareImages
+                ? 'Configured default agent image could not be pulled or built'
+                : 'Configured default agent image has not been prepared by the worker',
+        };
+    }
+    return {
+        image: await resolveAgentRuntimeImage(dockerImage, { buildMissing: prepareImages }),
+        imageTag: dockerImage,
+    };
+}
+
+export async function resolveDefaultAgentConfig(
+    prepareImages: boolean,
+): Promise<{ config?: AgentConfig; imageTag?: string; error?: string }> {
+    const configuredImage = process.env.AGENT_DOCKER_IMAGE;
+    let resolution: AgentImageResolution;
+    try {
+        resolution = configuredImage
+            ? await resolveConfiguredDefaultImage(configuredImage, prepareImages)
+            : await resolveUnifiedAgentImage([], prepareImages);
+    } catch (error) {
+        return { imageTag: configuredImage, error: (error as Error).message };
+    }
+    if (!resolution.image) return resolution;
+
+    return {
+        config: {
+            id: 'default-claude-agent',
+            type: 'claude',
+            alias: 'default',
+            enabled: true,
+            dockerImage: resolution.image,
+            configPath: process.env.CLAUDE_CONFIG_PATH || path.join(os.homedir(), '.claude'),
+            supportedModels: [...AGENT_DEFAULTS.claude.defaultModels],
+            defaultModel: process.env.CLAUDE_MODEL || undefined,
+            cliVersionType: 'default',
+            cliVersionResolved: AGENT_DEFAULT_VERSIONS.claude,
+        },
+        imageTag: resolution.imageTag,
+    };
+}
diff --git a/packages/core/src/claude/docker/dockerExecutor.ts b/packages/core/src/claude/docker/dockerExecutor.ts
index 41698d18a..cbf306bd0 100644
--- a/packages/core/src/claude/docker/dockerExecutor.ts
+++ b/packages/core/src/claude/docker/dockerExecutor.ts
@@ -366,5 +366,5 @@ function detectContainerId(
 }
 
 // Re-export image builder functions for backward compatibility
-export { buildClaudeDockerImage, ensureAgentBundleImage, ensureAgentDockerImage } from './dockerImageBuilder.js';
+export { agentDockerImageExists, buildClaudeDockerImage, ensureAgentBundleImage, ensureAgentDockerImage } from './dockerImageBuilder.js';
 export type { VersionedImageBuildResult } from './dockerImageBuilder.js';
diff --git a/packages/core/src/claude/docker/dockerImageBuilder.ts b/packages/core/src/claude/docker/dockerImageBuilder.ts
index f2efaa74d..e384ab9b1 100644
--- a/packages/core/src/claude/docker/dockerImageBuilder.ts
+++ b/packages/core/src/claude/docker/dockerImageBuilder.ts
@@ -15,6 +15,7 @@ const PROJECT_ROOT = process.env.PROPR_ROOT
     || (fs.existsSync(path.join(process.cwd(), 'Dockerfile.agent')) ? process.cwd() : '/usr/src/app');
 const AGENT_DOCKERFILE = 'Dockerfile.agent';
 const SAFE_BUILD_VERSION = /^[0-9A-Za-z][0-9A-Za-z.!+_-]*$/;
+const pendingImagePreparations = new Map<string, Promise<VersionedImageBuildResult>>();
 
 export interface VersionedImageBuildResult {
     success: boolean;
@@ -48,7 +49,7 @@ function bundleBuildArgs(versions: AgentCliVersionMatrix): string[] {
     ];
 }
 
-async function imageExists(image: string): Promise<boolean> {
+export async function agentDockerImageExists(image: string): Promise<boolean> {
     const result = await executeDockerCommand('docker', ['images', '-q', image]);
     return result.exitCode === 0 && Boolean(result.stdout.trim());
 }
@@ -120,16 +121,16 @@ function scheduleBundleImageCleanup(imageTag: string): void {
     });
 }
 
-export async function ensureAgentBundleImage(
+async function prepareAgentBundleImage(
     versions: AgentCliVersionMatrix,
     contentHash: string,
-    basePath: string = PROJECT_ROOT
+    basePath: string,
+    imageTag: string,
 ): Promise<VersionedImageBuildResult> {
-    const imageTag = generateAgentBundleImageTag(versions, contentHash);
     logger.info({ imageTag, versions, contentHash }, 'Ensuring unified agent Docker image exists...');
 
     try {
-        if (await imageExists(imageTag)) return { success: true, imageTag };
+        if (await agentDockerImageExists(imageTag)) return { success: true, imageTag };
         if (await pullImage(imageTag)) return { success: true, imageTag };
         const built = await buildBundle(imageTag, versions, basePath);
         if (built.success) scheduleBundleImageCleanup(imageTag);
@@ -141,18 +142,48 @@ export async function ensureAgentBundleImage(
     }
 }
 
+/**
+ * Pulls or builds one bundle tag at most once per process at a time. Registry
+ * refreshes can arrive concurrently (HTTP requests, config notifications, and
+ * startup), but they must all await the same Docker operation.
+ */
+export function ensureAgentBundleImage(
+    versions: AgentCliVersionMatrix,
+    contentHash: string,
+    basePath: string = PROJECT_ROOT
+): Promise<VersionedImageBuildResult> {
+    const imageTag = generateAgentBundleImageTag(versions, contentHash);
+    const pending = pendingImagePreparations.get(imageTag);
+    if (pending) return pending;
+
+    const preparation = prepareAgentBundleImage(versions, contentHash, basePath, imageTag)
+        .finally(() => {
+            pendingImagePreparations.delete(imageTag);
+        });
+    pendingImagePreparations.set(imageTag, preparation);
+    return preparation;
+}
+
 /** Ensures a directly configured image such as propr/agent:latest is available. */
 export async function ensureAgentDockerImage(_agentType: string, dockerImage: string): Promise<boolean> {
-    try {
-        if (await imageExists(dockerImage)) return true;
-        if (await pullImage(dockerImage)) return true;
-        const versions = getDefaultAgentCliVersionMatrix();
-        const built = await buildBundle(dockerImage, versions, PROJECT_ROOT);
-        return built.success;
-    } catch (error) {
-        logger.error({ dockerImage, error: (error as Error).message }, 'Error ensuring agent Docker image');
-        return false;
-    }
+    const pending = pendingImagePreparations.get(dockerImage);
+    if (pending) return (await pending).success;
+
+    const preparation = (async (): Promise<VersionedImageBuildResult> => {
+        try {
+            if (await agentDockerImageExists(dockerImage)) return { success: true, imageTag: dockerImage };
+            if (await pullImage(dockerImage)) return { success: true, imageTag: dockerImage };
+            const versions = getDefaultAgentCliVersionMatrix();
+            return buildBundle(dockerImage, versions, PROJECT_ROOT);
+        } catch (error) {
+            logger.error({ dockerImage, error: (error as Error).message }, 'Error ensuring agent Docker image');
+            return { success: false, imageTag: dockerImage, error: (error as Error).message };
+        }
+    })().finally(() => {
+        pendingImagePreparations.delete(dockerImage);
+    });
+    pendingImagePreparations.set(dockerImage, preparation);
+    return (await preparation).success;
 }
 
 export async function buildClaudeDockerImage(): Promise<boolean> {
diff --git a/src/worker.ts b/src/worker.ts
index 7dba46edf..909349f1c 100644
--- a/src/worker.ts
+++ b/src/worker.ts
@@ -143,6 +143,33 @@ Examples:
 `);
 }
 
+async function refreshAgentRegistryForConfigUpdate(subtype: string): Promise<void> {
+    logger.info({ subtype }, 'Refreshing AgentRegistry due to agent configuration update...');
+    try {
+        const registry = AgentRegistry.getInstance();
+        if (subtype === 'agents_update') {
+            await registry.prepareImagesAndRefresh();
+        } else {
+            await registry.refresh();
+        }
+        const imageStatus = registry.getOperationalStatus().unifiedAgentImage;
+        if (imageStatus.status !== 'ready') {
+            throw new Error(imageStatus.error || `Agent image ${imageStatus.imageTag || 'unknown'} is unavailable`);
+        }
+        const agents = registry.getAllAgents();
+        logger.info({
+            agentCount: agents.length,
+            agents: agents.map(agent => ({
+                alias: agent.config.alias,
+                type: agent.config.type,
+                enabled: agent.config.enabled,
+            })),
+        }, 'AgentRegistry refreshed successfully');
+    } catch (error) {
+        logger.error({ error: (error as Error).message }, 'Failed to refresh AgentRegistry');
+    }
+}
+
 export interface StartedWorker {
     worker: MainWorker;
     runtimeBuildWorker: Worker<AgentRuntimeBuildJobData>;
@@ -193,6 +220,22 @@ async function startWorker(options: WorkerOptions = {}): Promise<StartedWorker>
         resetPerformed: options.reset || false
     }, 'Starting GitHub Issue Worker...');
 
+    // The main worker is the single owner of base/runtime agent image
+    // preparation. Do this before heartbeats and BullMQ workers so the stack
+    // cannot advertise or claim task capacity while an image is still building.
+    logger.info('Preparing agent Docker images and initializing agent registry...');
+    const registry = AgentRegistry.getInstance();
+    await registry.prepareImagesAndRefresh();
+    const imageStatus = registry.getOperationalStatus().unifiedAgentImage;
+    if (imageStatus.status !== 'ready') {
+        throw new Error(imageStatus.error || `Agent image ${imageStatus.imageTag || 'unknown'} is unavailable`);
+    }
+    const agents = registry.getAllAgents();
+    logger.info({
+        agentCount: agents.length,
+        agents: agents.map(a => ({ alias: a.config.alias, type: a.config.type, dockerImage: a.config.dockerImage }))
+    }, 'Agent images prepared and registry initialized successfully');
+
     const heartbeatRedis = new Redis({
         host: process.env.REDIS_HOST || 'localhost',
         port: parseInt(process.env.REDIS_PORT || '6379', 10),
@@ -214,21 +257,6 @@ async function startWorker(options: WorkerOptions = {}): Promise<StartedWorker>
 
     const heartbeatInterval = setInterval(sendHeartbeat, 30000);
 
-    // Initialize the AgentRegistry which will ensure all configured agent Docker images exist
-    logger.info('Initializing agent registry and ensuring Docker images...');
-    try {
-        const registry = AgentRegistry.getInstance();
-        await registry.refresh();
-        const agents = registry.getAllAgents();
-        logger.info({
-            agentCount: agents.length,
-            agents: agents.map(a => ({ alias: a.config.alias, type: a.config.type, dockerImage: a.config.dockerImage }))
-        }, 'Agent registry initialized successfully');
-    } catch (error) {
-        const err = error as Error;
-        logger.error({ error: err.message }, 'Failed to initialize agent registry. Worker may not function properly.');
-    }
-
     setUltrafixDeps(createUltrafixDeps());
     logger.info('Ultrafix dependencies initialized for worker');
 
@@ -266,19 +294,7 @@ async function startWorker(options: WorkerOptions = {}): Promise<StartedWorker>
 
                 // Handle agent config updates by refreshing the registry
                 if (event.subtype === 'agents_update' || event.subtype === 'synthetic_agents_update') {
-                    logger.info({ subtype: event.subtype }, 'Refreshing AgentRegistry due to agent configuration update...');
-                    try {
-                        const registry = AgentRegistry.getInstance();
-                        await registry.refresh();
-                        const agents = registry.getAllAgents();
-                        logger.info({
-                            agentCount: agents.length,
-                            agents: agents.map(a => ({ alias: a.config.alias, type: a.config.type, enabled: a.config.enabled }))
-                        }, 'AgentRegistry refreshed successfully');
-                    } catch (agentError) {
-                        const err = agentError as Error;
-                        logger.error({ error: err.message }, 'Failed to refresh AgentRegistry');
-                    }
+                    await refreshAgentRegistryForConfigUpdate(event.subtype);
                 }
 
                 if (event.subtype === 'settings_update') {
diff --git a/test/agentImagePreparation.test.ts b/test/agentImagePreparation.test.ts
new file mode 100644
index 000000000..a65c7a1aa
--- /dev/null
+++ b/test/agentImagePreparation.test.ts
@@ -0,0 +1,49 @@
+import { mock, test } from 'node:test';
+import assert from 'node:assert/strict';
+import type { AgentCliVersionMatrix } from '../packages/core/src/agents/version/versionService.js';
+
+let imageChecks = 0;
+let pulls = 0;
+let releasePull: (() => void) | undefined;
+const pullGate = new Promise<void>(resolve => {
+    releasePull = resolve;
+});
+
+await mock.module('../packages/core/src/claude/docker/dockerExecutor.js', {
+    exports: {
+        executeDockerCommand: mock.fn(async (_command: string, args: string[]) => {
+            if (args[0] === 'images') {
+                imageChecks += 1;
+                return { exitCode: 0, stdout: '', stderr: '', messageTimestamps: new Map() };
+            }
+            if (args[0] === 'pull') {
+                pulls += 1;
+                await pullGate;
+                return { exitCode: 0, stdout: 'pulled', stderr: '', messageTimestamps: new Map() };
+            }
+            throw new Error(`Unexpected Docker command: ${args.join(' ')}`);
+        }),
+    },
+});
+
+const { ensureAgentBundleImage } = await import('../packages/core/src/claude/docker/dockerImageBuilder.js');
+
+test('concurrent preparation of the same bundle shares one Docker operation', async () => {
+    const versions: AgentCliVersionMatrix = {
+        claude: '1.0.0',
+        codex: '1.0.0',
+        antigravity: '1.0.0',
+        opencode: '1.0.0',
+        vibe: '1.0.0',
+    };
+
+    const preparations = Array.from({ length: 8 }, () => ensureAgentBundleImage(versions, 'content'));
+    await new Promise<void>(resolve => setImmediate(resolve));
+    assert.strictEqual(imageChecks, 1);
+    assert.strictEqual(pulls, 1);
+
+    releasePull?.();
+    const results = await Promise.all(preparations);
+    assert.ok(results.every(result => result.success));
+    assert.strictEqual(new Set(results.map(result => result.imageTag)).size, 1);
+});
diff --git a/test/agentRegistryOpenCode.test.ts b/test/agentRegistryOpenCode.test.ts
index 2a639823a..961d84e8b 100644
--- a/test/agentRegistryOpenCode.test.ts
+++ b/test/agentRegistryOpenCode.test.ts
@@ -98,6 +98,46 @@ test('AgentRegistry registers enabled OpenCode configs by alias', async () => {
     );
 });
 
+test('AgentRegistry only prepares images through the explicit worker lifecycle', async () => {
+    const registry = AgentRegistry.getInstance();
+    const preparationModes: boolean[] = [];
+    (registry as unknown as {
+        ensureUnifiedAgentImage: (_configs: AgentConfig[], prepareImages: boolean) => Promise<string>;
+        registeredAgentImagesAvailable: () => Promise<boolean>;
+    }).ensureUnifiedAgentImage = async (_configs, prepareImages) => {
+        preparationModes.push(prepareImages);
+        return 'propr/agent:prepared';
+    };
+    (registry as unknown as {
+        registeredAgentImagesAvailable: () => Promise<boolean>;
+    }).registeredAgentImagesAvailable = async () => true;
+
+    await registry.refresh();
+    await registry.prepareImagesAndRefresh();
+
+    assert.deepStrictEqual(preparationModes, [false, true]);
+});
+
+test('AgentRegistry coalesces concurrent refreshes in one process', async () => {
+    const registry = AgentRegistry.getInstance();
+    let refreshes = 0;
+    (registry as unknown as {
+        ensureUnifiedAgentImage: () => Promise<string>;
+    }).ensureUnifiedAgentImage = async () => {
+        refreshes += 1;
+        await new Promise<void>(resolve => setImmediate(resolve));
+        return 'propr/agent:prepared';
+    };
+
+    await Promise.all([
+        registry.refresh(),
+        registry.refresh(),
+        registry.refresh(),
+    ]);
+
+    assert.strictEqual(refreshes, 1);
+});
+
 test('AgentRegistry degrades without throwing when unified image is unavailable', async () => {
     const registry = AgentRegistry.getInstance();
     failImageChecks(registry);
@@ -108,6 +148,21 @@ test('AgentRegistry degrades without throwing when unified image is unavailable'
     assert.deepStrictEqual(registry.getAllAgents(), []);
 });
 
+test('AgentRegistry keeps working agents while a replacement image is unavailable', async () => {
+    const registry = AgentRegistry.getInstance();
+    (registry as unknown as {
+        ensureUnifiedAgentImage: () => Promise<string | null>;
+    }).ensureUnifiedAgentImage = async () => 'propr/agent:working';
+
+    await registry.refresh();
+    (registry as unknown as {
+        ensureUnifiedAgentImage: () => Promise<string | null>;
+    }).ensureUnifiedAgentImage = async () => null;
+    await registry.prepareImagesAndRefresh();
+
+    assert.strictEqual(registry.getAgentByAlias('opencode')?.config.dockerImage, 'propr/agent:working');
+});
+
 test('AgentRegistry exposes unified image degraded status', async () => {
     const registry = AgentRegistry.getInstance();
     (registry as unknown as { ensureUnifiedAgentImage: () => Promise<string | null> }).ensureUnifiedAgentImage = async function fail(this: {

From 8351f550c77c65a60247882ac1750ceda649417c Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 17:35:41 +0200
Subject: [PATCH 06/18] fix(previews): publish preview-only follow-ups

---
 .../core/src/services/visualPreviewService.ts |  3 +-
 .../core/test/visualPreviewService.test.ts    |  2 +
 src/jobs/prCommentPostExecution.ts            |  6 +--
 src/jobs/prCompletionComment.ts               |  9 +++-
 test/prCompletionCommentVisualPreview.test.ts | 51 +++++++++++++++++++
 5 files changed, 65 insertions(+), 6 deletions(-)
 create mode 100644 test/prCompletionCommentVisualPreview.test.ts

diff --git a/packages/core/src/services/visualPreviewService.ts b/packages/core/src/services/visualPreviewService.ts
index 8728a919d..2000c90b6 100644
--- a/packages/core/src/services/visualPreviewService.ts
+++ b/packages/core/src/services/visualPreviewService.ts
@@ -377,11 +377,12 @@ export function buildVisualPreviewPrompt(settings: VisualPreviewSettings): strin
   return `
 **VISUAL PREVIEW REQUIREMENT:**
 Visual previews are enabled for this repository. After implementing and testing, decide whether the result is perceptible visually to a user. If it is not visually perceptible, do not create preview files. If it is visually perceptible:
-- Treat previews as evidence only: never expand the implementation scope, and do not create or update preview files when the current request produces no implementation changes.
+- Treat previews as evidence only: never expand the implementation scope. Do not create or update preview files when the current request produces no implementation changes, unless the user explicitly asks to generate or refresh previews for changes already present on the branch.
 - Generate focused ${requestedTypes} preview evidence of the current change using the project’s existing, relevant tooling (for example a headless browser, Storybook, an Android/iOS emulator, or a project-native renderer).
 - Capture the changed state itself, not generic application screens. Use realistic viewport/device states and follow the repository-specific instructions below when present.
 - Store each preview under the transient runtime directory \`${VISUAL_PREVIEW_DIRECTORY}/\`; never commit that directory yourself. Use portable filenames and only these formats: PNG/JPEG/GIF/SVG/WebP for images; MP4/MOV/WebM for videos. Keep every file below 10 MB. For video, prefer H.264 in MP4 for browser compatibility.
 - Write \`${VISUAL_PREVIEW_MANIFEST}\` with this shape: \`{"previews":[{"path":".propr/previews/desktop.png","title":"Desktop dialog","description":"The changed dialog at desktop width"}],"toolSuggestions":[{"name":"Playwright Chromium","reason":"Needed to capture the running web UI"}]}\`. The manifest may contain an empty previews array when capture is blocked.
+- Do not link to local preview or manifest paths in your final response. ProPR reads the manifest and publishes the preview attachments separately.
 - Do not fabricate a preview or hand-draw a substitute. If the project cannot be run or the needed capture tool is unavailable, record concise, actionable \`toolSuggestions\` in the manifest describing what should be installed in the agent image and why.
 - Never include credentials, tokens, personal data, or unrelated screens in preview media.
 ${additionalInstructions}`;
diff --git a/packages/core/test/visualPreviewService.test.ts b/packages/core/test/visualPreviewService.test.ts
index dae1af496..1dc39e952 100644
--- a/packages/core/test/visualPreviewService.test.ts
+++ b/packages/core/test/visualPreviewService.test.ts
@@ -39,7 +39,9 @@ test('visual preview prompt is conditional and carries repository instructions',
 
   assert.match(prompt, /perceptible visually/);
   assert.match(prompt, /never expand the implementation scope/);
+  assert.match(prompt, /explicitly asks to generate or refresh previews/);
   assert.match(prompt, /\.propr\/previews\/manifest\.json/);
+  assert.match(prompt, /Do not link to local preview or manifest paths/);
   assert.match(prompt, /image and video/);
   assert.match(prompt, /Capture separate desktop and mobile views\./);
   assert.match(prompt, /toolSuggestions/);
diff --git a/src/jobs/prCommentPostExecution.ts b/src/jobs/prCommentPostExecution.ts
index 7948a441c..a2a49b3a4 100644
--- a/src/jobs/prCommentPostExecution.ts
+++ b/src/jobs/prCommentPostExecution.ts
@@ -149,8 +149,8 @@ interface CompletionCommentPublicationOptions {
 async function publishCompletionComment(options: CompletionCommentPublicationOptions): Promise<{ data: { html_url: string; body?: string } }> {
     const { state, context, commitResult, changesSummary, commitMessage, llm, taskUrl, unprocessedReviewComments, visualPreviewEvidence } = options;
     const { repoOwner, repoName, pullRequestNumber, correlatedLogger } = context;
-    const hasVisualPreviewContent = Boolean(commitResult)
-        && (visualPreviewEvidence.assets.length > 0 || visualPreviewEvidence.toolSuggestions.length > 0);
+    const hasVisualPreviewContent = visualPreviewEvidence.assets.length > 0
+        || visualPreviewEvidence.toolSuggestions.length > 0;
     const visualPreviewSection = hasVisualPreviewContent
         ? renderVisualPreviewSection({ assets: [], toolSuggestions: visualPreviewEvidence.toolSuggestions }, {})
         : '';
@@ -168,7 +168,7 @@ async function publishCompletionComment(options: CompletionCommentPublicationOpt
     }, state.claudeResult);
     const prCommentBody = appendVisualPreviewSection(prCommentTemplate, visualPreviewSection);
 
-    if (!commitResult || visualPreviewEvidence.assets.length === 0) {
+    if (visualPreviewEvidence.assets.length === 0) {
         return state.octokit.request('PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}', {
             owner: repoOwner,
             repo: repoName,
diff --git a/src/jobs/prCompletionComment.ts b/src/jobs/prCompletionComment.ts
index f87c99ad7..ed4c53778 100644
--- a/src/jobs/prCompletionComment.ts
+++ b/src/jobs/prCompletionComment.ts
@@ -3,7 +3,7 @@ import type { UnprocessedComment } from '@propr/core';
 import { buildMetricsSection } from './prCommentJobUtils.js';
 import { buildAttributionLine, buildSlashCommandsBlock } from '../shared/slashCommandsBlock.js';
 import { buildWorkEvidenceMarker, filterRealComments } from '../shared/workEvidenceMarker.js';
-import { describeAgentTermination, resolveAgentTerminationReason } from '@propr/core';
+import { describeAgentTermination, resolveAgentTerminationReason, VISUAL_PREVIEW_DIRECTORY } from '@propr/core';
 
 /** Build the processing comment IDs suffix, or empty string if no real comments */
 function buildCommentIdsSuffix(comments: UnprocessedComment[]): string {
@@ -150,6 +150,9 @@ export async function buildCompletionComment(
     const cleanBody = (text: string) => {
         return text
             .replace(/^(PR|Comment by|Model):.*/gm, '')
+            .split('\n')
+            .filter(line => !line.replaceAll('\\', '/').includes(`${VISUAL_PREVIEW_DIRECTORY}/`))
+            .join('\n')
             .replace(/\n{3,}/g, '\n\n')
             .trim();
     };
@@ -211,7 +214,9 @@ export async function buildCompletionComment(
             noChangesBody += `## Analysis Summary\n\n${cleanBody(changesSummary)}\n\n`;
         }
 
-        noChangesBody += `No code changes were necessary based on the current state of the branch.\n\n`;
+        noChangesBody += visualPreviewSection
+            ? `No code changes were necessary based on the current state of the branch. Visual preview results are included below.\n\n${visualPreviewSection}\n\n`
+            : `No code changes were necessary based on the current state of the branch.\n\n`;
         noChangesBody += await buildMetricsSection(claudeResult, llm, authorsText, true);
 
         if (taskUrl) {
diff --git a/test/prCompletionCommentVisualPreview.test.ts b/test/prCompletionCommentVisualPreview.test.ts
new file mode 100644
index 000000000..7484ca93c
--- /dev/null
+++ b/test/prCompletionCommentVisualPreview.test.ts
@@ -0,0 +1,51 @@
+import assert from 'node:assert/strict';
+import { after, test } from 'node:test';
+import { closeConnection, VISUAL_PREVIEW_SLOT } from '@propr/core';
+import type { ClaudeCodeResponse, UnprocessedComment } from '@propr/core';
+import { buildCompletionComment } from '../src/jobs/prCompletionComment.js';
+
+after(async () => {
+    await closeConnection();
+});
+
+test('keeps the visual preview slot in a preview-only follow-up without a commit', async () => {
+    const comments: UnprocessedComment[] = [{
+        id: 5527365804,
+        body: 'Try showing the preview again',
+        author: 'integry',
+        createdAt: new Date().toISOString(),
+    }];
+    const localPreviewPath = '/tmp/git-processor/worktrees/integry/propr/pr-2091/.propr/previews/goal-details-delete-desktop.png';
+    const localManifestPath = '/tmp/git-processor/worktrees/integry/propr/pr-2091/.propr/previews/manifest.json';
+    const summary = [
+        'Preview capture succeeded using Chromium.',
+        `- [View goal details preview](<${localPreviewPath}>)`,
+        `- [Preview manifest](<${localManifestPath}>)`,
+        '- UI production build passed.',
+    ].join('\n');
+    const result: ClaudeCodeResponse = {
+        success: true,
+        executionTime: 1000,
+        output: null,
+        logs: '',
+        exitCode: 0,
+        finalResult: null,
+        modifiedFiles: [],
+        commitMessage: null,
+        summary,
+    };
+
+    const comment = await buildCompletionComment(null, comments, {
+        changesSummary: summary,
+        commitMessage: '',
+        llm: 'gpt-5.6-sol',
+        authorsText: '@integry',
+        visualPreviewSection: VISUAL_PREVIEW_SLOT,
+    }, result);
+
+    assert.match(comment, /Preview capture succeeded using Chromium/);
+    assert.match(comment, /UI production build passed/);
+    assert.match(comment, /Visual preview results are included below/);
+    assert.match(comment, new RegExp(VISUAL_PREVIEW_SLOT));
+    assert.doesNotMatch(comment, /\.propr\/previews\//);
+});

From 8d50d3f02060c13f022bd2315ede926ba5076355 Mon Sep 17 00:00:00 2001
From: "propr-dev[bot]" <1316198+propr-dev[bot]@users.noreply.github.com>
Date: Thu, 3 Sep 2026 15:42:19 +0000
Subject: [PATCH 07/18] =?UTF-8?q?feat(ai):=20Fixed=20the=20failed=20CI=20c?=
 =?UTF-8?q?heck=20in=20[test/agentImagePreparation.test.ts](/tmp/git-proce?=
 =?UTF-8?q?ssor/worktrees/integry/propr/pr-2102-followup-2026-09-03T15-37-?=
 =?UTF-8?q?17/test/agentImagePreparation.test.ts:12)=20by=20using=20Node?=
 =?UTF-8?q?=E2=80=99s=20correct=20`namedExports`=20module-mocking=20option?=
 =?UTF-8?q?.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixed the failed CI check in [test/agentImagePreparation.test.ts](/tmp/git-processor/worktrees/integry/propr/pr-2102-followup-2026-09-03T15-37-17/test/agentImagePreparation.test.ts:12) by using Node’s correct `namedExports` module-mocking option.

Validation:

- Fast unit suite: 284 passed, 0 failed
- Root TypeScript check passed
- `git diff --check` passed
- No visual preview generated because this test-only change is not user-visible
- No commit created, as requested

PR: #2102
Comment by: @github-actions[bot] (ID: 5528151996)
Model: gpt-5.6-sol
---
 test/agentImagePreparation.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/agentImagePreparation.test.ts b/test/agentImagePreparation.test.ts
index a65c7a1aa..c41fd0c9f 100644
--- a/test/agentImagePreparation.test.ts
+++ b/test/agentImagePreparation.test.ts
@@ -10,7 +10,7 @@ const pullGate = new Promise<void>(resolve => {
 });
 
 await mock.module('../packages/core/src/claude/docker/dockerExecutor.js', {
-    exports: {
+    namedExports: {
         executeDockerCommand: mock.fn(async (_command: string, args: string[]) => {
             if (args[0] === 'images') {
                 imageChecks += 1;

From 6ea1534a6a309dac215f590ede3f2a3466277263 Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 20:50:52 +0200
Subject: [PATCH 08/18] fix(previews): install uploader CLI in worker images

---
 Dockerfile                              | 14 ++++++++++++++
 Dockerfile.node                         | 15 ++++++++++++++-
 src/github/visualPreviewAttachments.ts  | 13 +++++++++++--
 test/agentDockerfileSupplyChain.test.ts | 17 +++++++++++++++++
 4 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 461cf64af..569793640 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -2,6 +2,9 @@ FROM node:22-slim
 
 WORKDIR /usr/src/app
 
+ARG GH_VERSION=2.99.0
+ARG TARGETARCH
+
 # Install git, sudo, Docker tooling, and build tools for native modules
 # (better-sqlite3). Debian's essential bsdutils package already provides
 # script(1), used as the browser agent-login PTY bridge.
@@ -12,9 +15,20 @@ RUN apt-get update && apt-get install -y \
     git \
     sudo \
     docker.io \
+    curl \
     python3 \
     make \
     g++ \
+    && gh_arch="${TARGETARCH:-amd64}" \
+    && case "$gh_arch" in amd64|arm64) ;; *) echo "Unsupported GitHub CLI architecture: $gh_arch" >&2; exit 1 ;; esac \
+    && gh_archive="gh_${GH_VERSION}_linux_${gh_arch}.tar.gz" \
+    && curl -fsSLO "https://github.com/cli/cli/releases/download/v${GH_VERSION}/${gh_archive}" \
+    && curl -fsSLO "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_checksums.txt" \
+    && grep "  ${gh_archive}$" "gh_${GH_VERSION}_checksums.txt" | sha256sum -c - \
+    && tar -xzf "$gh_archive" \
+    && install -m 0755 "gh_${GH_VERSION}_linux_${gh_arch}/bin/gh" /usr/local/bin/gh \
+    && rm -rf "$gh_archive" "gh_${GH_VERSION}_checksums.txt" "gh_${GH_VERSION}_linux_${gh_arch}" \
+    && gh --version \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy package files (including workspace packages)
diff --git a/Dockerfile.node b/Dockerfile.node
index 19fc0c783..f56adf480 100644
--- a/Dockerfile.node
+++ b/Dockerfile.node
@@ -1,10 +1,23 @@
 FROM node:22-alpine
 
+ARG GH_VERSION=2.99.0
+ARG TARGETARCH
+
 # Install git, sudo, Docker tooling, script(1) for browser agent-login PTYs,
 # curl, jq, and build tools for native modules (better-sqlite3)
 # curl and jq are required for deploy-pr.sh script execution
 # docker-cli-compose provides 'docker compose' (v2) command
-RUN apk add --no-cache git sudo docker-cli docker-cli-compose curl jq util-linux-misc python3 make g++
+RUN apk add --no-cache git sudo docker-cli docker-cli-compose curl jq util-linux-misc python3 make g++ \
+    && gh_arch="${TARGETARCH:-amd64}" \
+    && case "$gh_arch" in amd64|arm64) ;; *) echo "Unsupported GitHub CLI architecture: $gh_arch" >&2; exit 1 ;; esac \
+    && gh_archive="gh_${GH_VERSION}_linux_${gh_arch}.tar.gz" \
+    && curl -fsSLO "https://github.com/cli/cli/releases/download/v${GH_VERSION}/${gh_archive}" \
+    && curl -fsSLO "https://github.com/cli/cli/releases/download/v${GH_VERSION}/gh_${GH_VERSION}_checksums.txt" \
+    && grep "  ${gh_archive}$" "gh_${GH_VERSION}_checksums.txt" | sha256sum -c - \
+    && tar -xzf "$gh_archive" \
+    && install -m 0755 "gh_${GH_VERSION}_linux_${gh_arch}/bin/gh" /usr/local/bin/gh \
+    && rm -rf "$gh_archive" "gh_${GH_VERSION}_checksums.txt" "gh_${GH_VERSION}_linux_${gh_arch}" \
+    && gh --version
 
 WORKDIR /usr/src/app
 
diff --git a/src/github/visualPreviewAttachments.ts b/src/github/visualPreviewAttachments.ts
index 84f5db45e..b2e0e6b0c 100644
--- a/src/github/visualPreviewAttachments.ts
+++ b/src/github/visualPreviewAttachments.ts
@@ -1,6 +1,7 @@
 import { execa } from 'execa';
 import {
   appendVisualPreviewSection,
+  redactSecrets,
   renderVisualPreviewSection,
   type VisualPreviewEvidence
 } from '@propr/core';
@@ -28,8 +29,16 @@ const runAttachmentCommand: AttachmentCommandRunner = async ({ args, authToken,
     });
     return { stdout: result.stdout };
   } catch (error) {
-    const wrappedError = new Error('GitHub CLI could not upload visual preview attachments') as Error & { stdout?: string };
-    const stdout = (error as { stdout?: unknown })?.stdout;
+    const commandError = error as { code?: unknown; stderr?: unknown; stdout?: unknown };
+    const detail = commandError.code === 'ENOENT'
+      ? 'gh executable was not found in PATH'
+      : typeof commandError.stderr === 'string' && commandError.stderr.trim()
+        ? redactSecrets(commandError.stderr.trim()).replace(/\s+/g, ' ').slice(0, 1000)
+        : '';
+    const wrappedError = new Error(
+      `GitHub CLI could not upload visual preview attachments${detail ? `: ${detail}` : ''}`
+    ) as Error & { stdout?: string };
+    const stdout = commandError.stdout;
     if (typeof stdout === 'string') wrappedError.stdout = stdout;
     throw wrappedError;
   }
diff --git a/test/agentDockerfileSupplyChain.test.ts b/test/agentDockerfileSupplyChain.test.ts
index 9b299733c..d0adc2907 100644
--- a/test/agentDockerfileSupplyChain.test.ts
+++ b/test/agentDockerfileSupplyChain.test.ts
@@ -4,6 +4,23 @@ import test from 'node:test';
 
 const dockerfile = readFileSync(new URL('../Dockerfile.agent', import.meta.url), 'utf8');
 const buildScript = readFileSync(new URL('../scripts/build-images.sh', import.meta.url), 'utf8');
+const appDockerfiles = [
+  'Dockerfile',
+  'Dockerfile.node',
+  'docker/Dockerfile.app.prod',
+];
+
+for (const dockerfilePath of appDockerfiles) {
+  test(`${dockerfilePath} installs the pinned GitHub CLI used for preview attachments`, () => {
+    const appDockerfile = readFileSync(new URL(`../${dockerfilePath}`, import.meta.url), 'utf8');
+
+    assert.match(appDockerfile, /ARG GH_VERSION=2\.99\.0/);
+    assert.match(appDockerfile, /cli\/cli\/releases\/download\/v\$\{GH_VERSION\}/);
+    assert.match(appDockerfile, /sha256sum -c -/);
+    assert.match(appDockerfile, /\/usr\/local\/bin\/gh/);
+    assert.match(appDockerfile, /gh --version/);
+  });
+}
 
 test('Antigravity agent build uses a versioned artifact with a pinned checksum', () => {
   assert.match(dockerfile, /ARG ANTIGRAVITY_CLI_VERSION=\d+\.\d+\.\d+/);

From a47a8324c6a83cd24b7403f7b87a1dd7bc57e3d0 Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 21:42:44 +0200
Subject: [PATCH 09/18] fix(previews): use user token for GitHub attachments

---
 .env.example                                  |  8 ++++++
 docs/docs/features/visual-previews.md         |  7 +++++
 .../operations/configuration-reference.md     |  1 +
 src/github/visualPreviewAttachments.ts        | 27 ++++++++++++++++---
 src/jobs/issueJobHelpers.ts                   |  2 --
 src/jobs/issueJobPostProcessing.ts            |  1 -
 src/jobs/prCommentPostExecution.ts            |  2 --
 test/visualPreviewAttachments.test.ts         | 16 ++++++++++-
 8 files changed, 55 insertions(+), 9 deletions(-)

diff --git a/.env.example b/.env.example
index a778e1c69..af2a87685 100644
--- a/.env.example
+++ b/.env.example
@@ -46,6 +46,14 @@ GITHUB_EVENT_INTAKE_MODE=routing_websocket
 # are set, so you normally do not need this.
 # GH_AUTH_MODE=relay
 
+# GitHub user credential used only for visual-preview attachment uploads.
+# GitHub's attachment endpoint rejects App installation tokens, so visual
+# previews require an OAuth token, classic PAT, or fine-grained PAT belonging
+# to a user with write access to each target repository. Keep this secret out
+# of source control. Other GitHub API and git operations continue to use the
+# short-lived App installation token configured above.
+# GITHUB_VISUAL_PREVIEW_TOKEN=your_oauth_or_personal_access_token
+
 # --- Hosted UI tunnel (v1, optional) -----------------------------------------
 # Expose this local stack's API to the hosted control plane at
 # https://app.propr.dev through a Cloudflare Tunnel, so you can drive a
diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
index 624f11c5e..3f98f4457 100644
--- a/docs/docs/features/visual-previews.md
+++ b/docs/docs/features/visual-previews.md
@@ -8,6 +8,13 @@ Visual previews let a ProPR implementation show its user-visible result directly
 
 The feature is opt-in per repository. Existing repository configurations remain disabled after an upgrade.
 
+GitHub attachment uploads also require `GITHUB_VISUAL_PREVIEW_TOKEN` in the
+stack `.env`. Use an OAuth token, classic personal access token, or fine-grained
+personal access token for a user with write access to every repository where
+previews are enabled. GitHub App installation tokens cannot upload user
+attachments, so ProPR keeps this credential separate from its normal App
+authentication.
+
 ## Configure A Repository
 
 On **Repositories**, turn on **Visual previews** beneath the repository entry. Choose **Images**, **Videos**, or both, then optionally add capture instructions such as:
diff --git a/docs/docs/operations/configuration-reference.md b/docs/docs/operations/configuration-reference.md
index 945363188..1150d8254 100644
--- a/docs/docs/operations/configuration-reference.md
+++ b/docs/docs/operations/configuration-reference.md
@@ -22,6 +22,7 @@ The backend authenticates to GitHub in one of three modes — `demo`, `relay`, o
 | `HOST_GH_PRIVATE_KEY` | Unset | Absolute host path to the `.pem`. The CLI/launcher bind-mounts it read-only into the app containers and overrides `GH_PRIVATE_KEY_PATH`, so the key can live anywhere on the host. No `~`. | App mode via the `propr` CLI or launcher. |
 | `GH_OAUTH_CLIENT_ID` / `GH_OAUTH_CLIENT_SECRET` | Placeholders | GitHub OAuth App credentials for Web UI login. | Always, for UI login. |
 | `GH_OAUTH_CALLBACK_URL` | Derived: `<API host>/api/auth/github/callback` | OAuth callback served by the API. Leave commented so tunnel-mode derivation wins; an active localhost value is used as-is even in tunnel mode. Register the URL — derived or explicit — in your GitHub OAuth App. | Override only. |
+| `GITHUB_VISUAL_PREVIEW_TOKEN` | Unset | OAuth token, classic PAT, or fine-grained PAT used only to upload visual-preview attachments. GitHub's user-attachment endpoint rejects App installation tokens; the token's user must have write access to each target repository. | Repositories with visual previews enabled. |
 | `SESSION_SECRET` | Placeholder | Signs browser session cookies. | Always. |
 | `ENABLE_BEARER_AUTH` | `true` (any value except `false` enables it) | Bearer token auth for the CLI. Set `false` to allow session login only. | Optional. |
 | `PROPR_DEMO_MODE` | `false` | `true`/`1` allows read-only access without GitHub OAuth and blocks all mutating API requests. Use a curated config/database for public demos. | Demo deployments. |
diff --git a/src/github/visualPreviewAttachments.ts b/src/github/visualPreviewAttachments.ts
index b2e0e6b0c..ea65ed95b 100644
--- a/src/github/visualPreviewAttachments.ts
+++ b/src/github/visualPreviewAttachments.ts
@@ -14,6 +14,26 @@ interface AttachmentCommandOptions {
 
 export type AttachmentCommandRunner = (options: AttachmentCommandOptions) => Promise<{ stdout: string }>;
 
+export const VISUAL_PREVIEW_UPLOAD_TOKEN_ENV = 'GITHUB_VISUAL_PREVIEW_TOKEN';
+
+/**
+ * GitHub's user-attachment endpoint does not accept GitHub App installation
+ * tokens. Keep this credential separate from the installation token used for
+ * normal API requests and git operations.
+ */
+export function resolveVisualPreviewUploadToken(
+  environment: NodeJS.ProcessEnv = process.env
+): string {
+  const token = environment[VISUAL_PREVIEW_UPLOAD_TOKEN_ENV]?.trim();
+  if (token) return token;
+
+  throw new Error(
+    `${VISUAL_PREVIEW_UPLOAD_TOKEN_ENV} is not configured; GitHub attachment uploads require `
+    + 'an OAuth token, classic personal access token, or fine-grained personal access token '
+    + 'for a user with write access to the repository. GitHub App installation tokens cannot upload attachments.'
+  );
+}
+
 const runAttachmentCommand: AttachmentCommandRunner = async ({ args, authToken, cwd }) => {
   try {
     const result = await execa('gh', args, {
@@ -49,7 +69,8 @@ interface BaseVisualPreviewPublicationOptions {
   repo: string;
   body: string;
   evidence: VisualPreviewEvidence;
-  authToken: string;
+  /** Optional injection used by callers with an already-resolved upload credential. */
+  authToken?: string;
   worktreePath: string;
   runCommand?: AttachmentCommandRunner;
 }
@@ -93,7 +114,7 @@ export async function publishPullRequestVisualPreviews(options: PublishPullReque
       '--body', bodyWithLocalPreviews(options),
       ...attachmentArguments(options.evidence)
     ],
-    authToken: options.authToken,
+    authToken: options.authToken ?? resolveVisualPreviewUploadToken(),
     cwd: options.worktreePath
   });
   const response = await options.octokit.request<{ data: { body?: string } }>('GET /repos/{owner}/{repo}/pulls/{pull_number}', {
@@ -138,7 +159,7 @@ export async function publishPullRequestCommentVisualPreviews(
         '--body', bodyWithLocalPreviews(options),
         ...attachmentArguments(options.evidence)
       ],
-      authToken: options.authToken,
+      authToken: options.authToken ?? resolveVisualPreviewUploadToken(),
       cwd: options.worktreePath
     });
     const commentUrl = result.stdout.trim().split('\n').find(line => line.includes('#issuecomment-')) || result.stdout.trim();
diff --git a/src/jobs/issueJobHelpers.ts b/src/jobs/issueJobHelpers.ts
index dfb4eee44..2c60883d8 100644
--- a/src/jobs/issueJobHelpers.ts
+++ b/src/jobs/issueJobHelpers.ts
@@ -60,7 +60,6 @@ interface CreatePROptions {
     issueTitle: string;
     visualPreview?: {
         evidence: VisualPreviewEvidence;
-        authToken: string;
         worktreePath: string;
     };
 }
@@ -257,7 +256,6 @@ Comment on this PR to request refinements — the AI agent monitors comments and
                     pullRequestNumber: prResponse.data.number,
                     body: basePrBody,
                     evidence: visualPreview.evidence,
-                    authToken: visualPreview.authToken,
                     worktreePath: visualPreview.worktreePath,
                     octokit
                 });
diff --git a/src/jobs/issueJobPostProcessing.ts b/src/jobs/issueJobPostProcessing.ts
index 0da17fa4e..fa7fe4d11 100644
--- a/src/jobs/issueJobPostProcessing.ts
+++ b/src/jobs/issueJobPostProcessing.ts
@@ -264,7 +264,6 @@ export async function performPostProcessing(options: PostProcessOptions): Promis
                 issueTitle: currentIssueData.data.title,
                 visualPreview: {
                     evidence: preparedVisualPreview.evidence,
-                    authToken: githubToken.token,
                     worktreePath: worktreeInfo.worktreePath
                 }
             }
diff --git a/src/jobs/prCommentPostExecution.ts b/src/jobs/prCommentPostExecution.ts
index a2a49b3a4..bcb4cfe4d 100644
--- a/src/jobs/prCommentPostExecution.ts
+++ b/src/jobs/prCommentPostExecution.ts
@@ -178,14 +178,12 @@ async function publishCompletionComment(options: CompletionCommentPublicationOpt
     }
 
     try {
-        const githubToken = await state.octokit.auth({ type: 'installation' }) as GitHubToken;
         const published = await publishPullRequestCommentVisualPreviews({
             owner: repoOwner,
             repo: repoName,
             pullRequestNumber,
             body: prCommentTemplate,
             evidence: visualPreviewEvidence,
-            authToken: githubToken.token,
             worktreePath: state.worktreeInfo.worktreePath,
             octokit: state.octokit,
             startingCommentId: state.startingWorkComment.data.id
diff --git a/test/visualPreviewAttachments.test.ts b/test/visualPreviewAttachments.test.ts
index 5f088280e..6b0e56dc4 100644
--- a/test/visualPreviewAttachments.test.ts
+++ b/test/visualPreviewAttachments.test.ts
@@ -5,7 +5,8 @@ process.env.PROPR_DEMO_MODE = 'true';
 
 const [{ db }, {
   publishPullRequestCommentVisualPreviews,
-  publishPullRequestVisualPreviews
+  publishPullRequestVisualPreviews,
+  resolveVisualPreviewUploadToken
 }] = await Promise.all([
   import('@propr/core'),
   import('../src/github/visualPreviewAttachments.js')
@@ -25,6 +26,19 @@ const evidence = {
   toolSuggestions: []
 };
 
+test('resolves the dedicated visual preview upload credential', () => {
+  assert.equal(resolveVisualPreviewUploadToken({
+    GITHUB_VISUAL_PREVIEW_TOKEN: '  gho_preview-token  '
+  }), 'gho_preview-token');
+});
+
+test('explains why the GitHub App credential cannot be used for attachments', () => {
+  assert.throws(
+    () => resolveVisualPreviewUploadToken({}),
+    /GitHub App installation tokens cannot upload attachments/
+  );
+});
+
 test('edits a pull request with uploaded visual preview attachments', async () => {
   let invocation: { args: string[]; authToken: string; cwd: string } | undefined;
   const requests: Array<{ endpoint: string; options: Record<string, unknown> }> = [];

From 6bafa3d81a20aa37e6b95d9eb9b686dfa9fd2d46 Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 21:43:28 +0200
Subject: [PATCH 10/18] chore(previews): pass upload token to worker

---
 docker-compose.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docker-compose.yml b/docker-compose.yml
index 908b2caf6..5a3fc8998 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -109,6 +109,9 @@ services:
       - OPENCODE_CONFIG_PATH=${HOME:?HOME must be set}/.config/opencode
       - VIBE_CONFIG_PATH=${HOME:?HOME must be set}/.vibe
       - PROPR_MANAGED_CREDENTIALS_DIR=${HOME:?HOME must be set}/.propr/agent-credentials
+      # Dedicated user credential for GitHub's attachment endpoint. This is
+      # separate from the App installation token used for normal GitHub work.
+      - GITHUB_VISUAL_PREVIEW_TOKEN=${GITHUB_VISUAL_PREVIEW_TOKEN:-}
       - PROPR_CONTAINERIZED=1
     depends_on:
       redis:

From aad4b14106ce7d887dea6fe6414da7468772544f Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 22:43:31 +0200
Subject: [PATCH 11/18] feat(previews): persist and refresh upload OAuth

---
 .env.example                                  |  16 +-
 docker-compose.yml                            |   4 +-
 docs/docs/features/visual-previews.md         |  24 +-
 .../operations/configuration-reference.md     |   3 +-
 packages/api/auth.ts                          |  49 +-
 packages/api/authGithubTokens.ts              | 105 +++-
 packages/api/authTypes.ts                     |   2 +
 packages/api/connectAuth.ts                   |  15 +-
 packages/api/routeRegistry.ts                 |   6 +
 packages/api/routes/index.ts                  |   1 +
 .../api/routes/visualPreviewAuthRoutes.ts     |  71 +++
 packages/api/server.ts                        |  10 +
 packages/api/services/visualPreviewOAuth.ts   |  76 +++
 packages/api/test/authGithubTokens.test.ts    |  34 ++
 packages/api/test/connectAuth.test.ts         |  27 +
 packages/api/test/routeAuthorization.test.ts  |   4 +
 .../api/test/visualPreviewAuthRoutes.test.ts  | 100 ++++
 ...create_visual_preview_oauth_credentials.js |  27 +
 packages/core/src/index.ts                    |   2 +
 .../visualPreviewOAuthCredentialService.ts    | 468 ++++++++++++++++++
 .../core/src/services/visualPreviewService.ts |  18 +-
 ...isualPreviewOAuthCredentialService.test.ts | 142 ++++++
 .../core/test/visualPreviewService.test.ts    |   3 +
 propr-ui/src/api/visualPreviewAuthApi.ts      |  41 ++
 .../VisualPreviewAuthSection.test.tsx         |  77 +++
 .../SettingsPage/VisualPreviewAuthSection.tsx | 134 +++++
 propr-ui/src/pages/SettingsPage/index.tsx     |   3 +
 src/github/visualPreviewAttachments.ts        |  85 +++-
 src/jobs/issueJobHelpers.ts                   |  10 +-
 src/jobs/prCommentPostExecution.ts            |  10 +-
 test/visualPreviewAttachments.test.ts         |  33 +-
 31 files changed, 1534 insertions(+), 66 deletions(-)
 create mode 100644 packages/api/routes/visualPreviewAuthRoutes.ts
 create mode 100644 packages/api/services/visualPreviewOAuth.ts
 create mode 100644 packages/api/test/visualPreviewAuthRoutes.test.ts
 create mode 100644 packages/core/src/db/migrations/20260903000000_create_visual_preview_oauth_credentials.js
 create mode 100644 packages/core/src/services/visualPreviewOAuthCredentialService.ts
 create mode 100644 packages/core/test/visualPreviewOAuthCredentialService.test.ts
 create mode 100644 propr-ui/src/api/visualPreviewAuthApi.ts
 create mode 100644 propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
 create mode 100644 propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx

diff --git a/.env.example b/.env.example
index af2a87685..85c151e7d 100644
--- a/.env.example
+++ b/.env.example
@@ -46,13 +46,17 @@ GITHUB_EVENT_INTAKE_MODE=routing_websocket
 # are set, so you normally do not need this.
 # GH_AUTH_MODE=relay
 
-# GitHub user credential used only for visual-preview attachment uploads.
-# GitHub's attachment endpoint rejects App installation tokens, so visual
-# previews require an OAuth token, classic PAT, or fine-grained PAT belonging
-# to a user with write access to each target repository. Keep this secret out
-# of source control. Other GitHub API and git operations continue to use the
-# short-lived App installation token configured above.
+# Advanced override for the GitHub user credential used only for visual-preview
+# attachment uploads. Normally an instance administrator's Web UI login is
+# captured, encrypted in SQLite, and refreshed automatically. Set this only to
+# override that flow with an OAuth token, classic PAT, or fine-grained PAT for a
+# user with write access to each target repository. GitHub App installation
+# tokens are not supported by the attachment endpoint.
 # GITHUB_VISUAL_PREVIEW_TOKEN=your_oauth_or_personal_access_token
+# Optional dedicated encryption secret for the persisted OAuth grant. The
+# default is SYSTEM_TASK_SECRET, falling back to SESSION_SECRET. Keep the value
+# stable and identical for the API and worker.
+# PROPR_CREDENTIAL_ENCRYPTION_KEY=generate-a-strong-secret-here
 
 # --- Hosted UI tunnel (v1, optional) -----------------------------------------
 # Expose this local stack's API to the hosted control plane at
diff --git a/docker-compose.yml b/docker-compose.yml
index 5a3fc8998..fa7229c9e 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -109,8 +109,8 @@ services:
       - OPENCODE_CONFIG_PATH=${HOME:?HOME must be set}/.config/opencode
       - VIBE_CONFIG_PATH=${HOME:?HOME must be set}/.vibe
       - PROPR_MANAGED_CREDENTIALS_DIR=${HOME:?HOME must be set}/.propr/agent-credentials
-      # Dedicated user credential for GitHub's attachment endpoint. This is
-      # separate from the App installation token used for normal GitHub work.
+      # Optional override for the encrypted OAuth credential collected through
+      # the Web UI. App installation tokens cannot upload GitHub attachments.
       - GITHUB_VISUAL_PREVIEW_TOKEN=${GITHUB_VISUAL_PREVIEW_TOKEN:-}
       - PROPR_CONTAINERIZED=1
     depends_on:
diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
index 3f98f4457..b613897b7 100644
--- a/docs/docs/features/visual-previews.md
+++ b/docs/docs/features/visual-previews.md
@@ -8,12 +8,22 @@ Visual previews let a ProPR implementation show its user-visible result directly
 
 The feature is opt-in per repository. Existing repository configurations remain disabled after an upgrade.
 
-GitHub attachment uploads also require `GITHUB_VISUAL_PREVIEW_TOKEN` in the
-stack `.env`. Use an OAuth token, classic personal access token, or fine-grained
-personal access token for a user with write access to every repository where
-previews are enabled. GitHub App installation tokens cannot upload user
-attachments, so ProPR keeps this credential separate from its normal App
-authentication.
+GitHub attachment uploads require a user OAuth credential because GitHub App
+installation tokens cannot upload user attachments. When an instance
+administrator signs in to the Web UI, ProPR automatically stores their compatible
+OAuth credential, encrypted in the shared database. Open **Settings → Visual
+preview uploads** to see which account is connected or explicitly replace it
+with the current administrator login. Normal GitHub API, commit, and pull-request
+operations continue to use the GitHub App installation token.
+
+Expiring OAuth credentials are refreshed on API startup and every 30 minutes
+while the stack is running. Each successful refresh rotates the access and
+refresh tokens, so an administrator does not need to sign in every six months
+while the stack can keep refreshing them. A revoked grant, an expired unused
+refresh token, or a changed encryption secret requires a fresh administrator
+login. `GITHUB_VISUAL_PREVIEW_TOKEN` remains available as an advanced environment
+override for an OAuth token, classic PAT, or fine-grained PAT belonging to a user
+with write access to every preview-enabled repository.
 
 ## Configure A Repository
 
@@ -49,6 +59,6 @@ Supported image formats are PNG, JPEG, GIF, SVG, and WebP. Supported video forma
 
 ## Publication And Upload Failures
 
-ProPR publishes previews as [GitHub attachments](https://cli.github.com/manual/gh_pr_edit) so images render inline and videos use GitHub's media presentation. It then fetches the published PR or comment body and verifies that GitHub replaced every temporary local path with a hosted attachment URL. Temporary files are deleted after publication. If upload or verification fails, ProPR publishes a text-only explanation; preview media is not added to Git as a fallback.
+ProPR publishes previews as [GitHub attachments](https://cli.github.com/manual/gh_pr_edit) so images render inline and videos use GitHub's media presentation. It then fetches the published PR or comment body and verifies that GitHub replaced every temporary local path with a hosted attachment URL. Temporary files are deleted after publication. If upload or verification fails, ProPR publishes a text-only explanation; preview media is not added to Git as a fallback. When the failure is a missing, unsupported, expired, or rejected user credential, that explanation includes the exact Settings reconnection steps in the affected pull request.
 
 Preview generation is evidence, not a replacement for automated tests. A preview failure does not discard an otherwise valid implementation; the PR explains missing tool support when the agent can identify it.
diff --git a/docs/docs/operations/configuration-reference.md b/docs/docs/operations/configuration-reference.md
index 1150d8254..5d988b86a 100644
--- a/docs/docs/operations/configuration-reference.md
+++ b/docs/docs/operations/configuration-reference.md
@@ -22,7 +22,8 @@ The backend authenticates to GitHub in one of three modes — `demo`, `relay`, o
 | `HOST_GH_PRIVATE_KEY` | Unset | Absolute host path to the `.pem`. The CLI/launcher bind-mounts it read-only into the app containers and overrides `GH_PRIVATE_KEY_PATH`, so the key can live anywhere on the host. No `~`. | App mode via the `propr` CLI or launcher. |
 | `GH_OAUTH_CLIENT_ID` / `GH_OAUTH_CLIENT_SECRET` | Placeholders | GitHub OAuth App credentials for Web UI login. | Always, for UI login. |
 | `GH_OAUTH_CALLBACK_URL` | Derived: `<API host>/api/auth/github/callback` | OAuth callback served by the API. Leave commented so tunnel-mode derivation wins; an active localhost value is used as-is even in tunnel mode. Register the URL — derived or explicit — in your GitHub OAuth App. | Override only. |
-| `GITHUB_VISUAL_PREVIEW_TOKEN` | Unset | OAuth token, classic PAT, or fine-grained PAT used only to upload visual-preview attachments. GitHub's user-attachment endpoint rejects App installation tokens; the token's user must have write access to each target repository. | Repositories with visual previews enabled. |
+| `GITHUB_VISUAL_PREVIEW_TOKEN` | Unset | Advanced override for the OAuth token, classic PAT, or fine-grained PAT used only to upload visual-preview attachments. Normally an administrator login supplies an encrypted, automatically refreshed OAuth credential through **Settings → Visual preview uploads**. GitHub's user-attachment endpoint rejects App installation tokens. | Optional override. |
+| `PROPR_CREDENTIAL_ENCRYPTION_KEY` | `SYSTEM_TASK_SECRET`, then `SESSION_SECRET` | Optional dedicated secret used to encrypt the persisted visual-preview OAuth grant. It must be identical in the API and worker containers and remain stable across restarts; changing it requires reconnecting the GitHub login. | Optional security isolation. |
 | `SESSION_SECRET` | Placeholder | Signs browser session cookies. | Always. |
 | `ENABLE_BEARER_AUTH` | `true` (any value except `false` enables it) | Bearer token auth for the CLI. Set `false` to allow session login only. | Optional. |
 | `PROPR_DEMO_MODE` | `false` | `true`/`1` allows read-only access without GitHub OAuth and blocks all mutating API requests. Use a curated config/database for public demos. | Demo deployments. |
diff --git a/packages/api/auth.ts b/packages/api/auth.ts
index 8cc796ec7..e7e21ed8a 100644
--- a/packages/api/auth.ts
+++ b/packages/api/auth.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- browser, bearer, and socket authentication share session state */
 import passport from 'passport';
 import { Strategy as GitHubStrategy, Profile } from 'passport-github2';
 import session from 'express-session';
@@ -8,7 +9,7 @@ import type { Express, Request, Response, NextFunction, RequestHandler } from 'e
 import { validateSessionSecret } from '@propr/shared';
 import { validateGitHubToken } from './authBearer.js';
 import { configureDemoMode, getDemoUser, isDemoMode } from './demoMode.js';
-import { clearSessionForReauth, isGitHubTokenExpired, refreshGitHubTokenIfNeeded, refreshGitHubTokenWithResult } from './authGithubTokens.js';
+import { clearSessionForReauth, isGitHubTokenExpired, refreshGitHubTokenWithResult } from './authGithubTokens.js';
 import { getValidatedRedirectTo, getDefaultRedirectUrl } from './authRedirect.js';
 import { isUserWhitelisted } from './userWhitelist.js';
 import type { GitHubUser } from './authTypes.js';
@@ -32,6 +33,7 @@ import {
     resolveInstanceAuthorization,
     type InstanceAuthorization,
 } from './authorization.js';
+import { captureVisualPreviewCredentialFromAdminLogin } from './services/visualPreviewOAuth.js';
 import './authTypes.js';
 
 export { refreshGitHubTokenIfNeeded } from './authGithubTokens.js';
@@ -87,7 +89,7 @@ export function createGitHubOAuthStrategy(config: GitHubOAuthStrategyConfig): Gi
         state: true as unknown as string,
     },
     // eslint-disable-next-line max-params
-    function verifyCallback(accessToken: string, refreshToken: string, params: { expires_in?: number }, profile: Profile, done: (error: Error | null, user?: GitHubUser) => void) {
+    function verifyCallback(accessToken: string, refreshToken: string, params: { expires_in?: number; refresh_token_expires_in?: number }, profile: Profile, done: (error: Error | null, user?: GitHubUser) => void) {
         console.log('User authenticated:', profile.username);
 
         const tokenExpiresAt = params.expires_in ? Date.now() + (params.expires_in * 1000) : undefined;
@@ -101,6 +103,10 @@ export function createGitHubOAuthStrategy(config: GitHubOAuthStrategyConfig): Gi
             accessToken,
             refreshToken: refreshToken || undefined,
             tokenExpiresAt,
+            refreshTokenExpiresAt: params.refresh_token_expires_in
+                ? Date.now() + (params.refresh_token_expires_in * 1000)
+                : undefined,
+            oauthSource: 'github',
         };
         return done(null, user);
     });
@@ -136,7 +142,7 @@ export function createConnectCallbackHandler(
                     redirectAuthError(res, 'session_unavailable');
                     return;
                 }
-                completeAuthenticatedSession(req, res);
+                void completeAuthenticatedSessionWithPreviewCredential(req, res);
             });
         } catch (error) {
             console.error('Connect instance login failed:', error);
@@ -145,6 +151,20 @@ export function createConnectCallbackHandler(
     };
 }
 
+async function completeAuthenticatedSessionWithPreviewCredential(req: Request, res: Response): Promise<void> {
+    if (req.user && isUserWhitelisted(req.user.username)) {
+        try {
+            const captured = await captureVisualPreviewCredentialFromAdminLogin(req.user);
+            if (captured) console.log(`[visual-preview] Captured OAuth upload credential for administrator ${req.user.username}`);
+        } catch (error) {
+            // Preview uploads are optional; a storage or encryption issue must not
+            // prevent an otherwise valid administrator from logging in.
+            console.warn('[visual-preview] Could not capture OAuth upload credential during login:', (error as Error).message);
+        }
+    }
+    completeAuthenticatedSession(req, res);
+}
+
 export function setupAuth(app: Express, demoModeAtStartup = isDemoMode()): SocketAuthMiddlewareBundle {
     configureDemoMode(demoModeAtStartup);
     const browserAuthMode = demoModeAtStartup ? 'disabled' : resolveBrowserAuthMode();
@@ -263,7 +283,7 @@ export function setupAuth(app: Express, demoModeAtStartup = isDemoMode()): Socke
             redirectAuthError(res, 'web_auth_not_configured');
             return;
         }
-        passport.authenticate('github', { scope: ['user:email', 'read:org', 'repo'] })(req, res, next);
+        passport.authenticate('github', { scope: ['user:email', 'read:org', 'repo', 'offline_access'] })(req, res, next);
     });
 
     if (demoModeAtStartup) {
@@ -274,7 +294,7 @@ export function setupAuth(app: Express, demoModeAtStartup = isDemoMode()): Socke
     } else if (browserAuthMode === 'github') {
         app.get('/api/auth/github/callback',
             passport.authenticate('github', { failureRedirect: '/login' }),
-            completeAuthenticatedSession
+            completeAuthenticatedSessionWithPreviewCredential
         );
     } else if (browserAuthMode === 'connect') {
         app.get('/api/auth/github/callback', createConnectCallbackHandler());
@@ -380,6 +400,8 @@ export async function authenticateSocketRequest(
     throw new SocketAuthenticationError('AUTHENTICATION_REQUIRED', 'Authentication required');
 }
 
+// Session, bearer, demo, and refresh outcomes are intentionally centralized.
+// eslint-disable-next-line complexity
 export async function ensureAuthenticated(req: Request, res: Response, next: NextFunction): Promise<void> {
     if (isDemoMode()) {
         res.set('X-ProPR-Demo-Mode', 'true');
@@ -419,10 +441,19 @@ export async function ensureAuthenticated(req: Request, res: Response, next: Nex
                 return;
             }
         } else {
-            // Proactively refresh token in background if needed.
-            refreshGitHubTokenIfNeeded(req).catch((err) => {
-                console.error('Background token refresh failed:', err);
-            });
+            // Await synchronization with the durable upload grant before a
+            // downstream route can use an access token invalidated by rotation.
+            // Temporary proactive-refresh failures do not invalidate a token
+            // whose recorded expiry is still in the future.
+            const refreshResult = await refreshGitHubTokenWithResult(req);
+            if (refreshResult.status === 'reauth-required' || req.user?.githubAuthInvalid) {
+                if (req.user?.githubAuthInvalid) await clearSessionForReauth(req);
+                res.status(401).json({ error: 'GitHub authentication expired', code: 'GITHUB_REAUTH_REQUIRED', message: 'Your GitHub session has expired. Please log in again.' });
+                return;
+            }
+            if (refreshResult.status === 'temporarily-unavailable') {
+                console.warn('Proactive GitHub token refresh was temporarily unavailable; continuing with the unexpired session token');
+            }
         }
         return next();
     }
diff --git a/packages/api/authGithubTokens.ts b/packages/api/authGithubTokens.ts
index 8b6063d2e..079acd502 100644
--- a/packages/api/authGithubTokens.ts
+++ b/packages/api/authGithubTokens.ts
@@ -1,4 +1,9 @@
 import type { Request } from 'express';
+import { isSupportedVisualPreviewUploadToken } from '@propr/core';
+import {
+    updateVisualPreviewCredentialForCurrentOwner,
+    visualPreviewOAuthCredentialService,
+} from './services/visualPreviewOAuth.js';
 
 const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000;
 
@@ -6,6 +11,7 @@ interface GitHubTokenRefreshResponse {
     access_token?: string;
     refresh_token?: string;
     expires_in?: number;
+    refresh_token_expires_in?: number;
     error?: string;
     error_description?: string;
 }
@@ -17,6 +23,7 @@ export interface GitHubTokenRefreshResult {
     accessToken?: string;
     refreshToken?: string;
     tokenExpiresAt?: number;
+    refreshTokenExpiresAt?: number;
 }
 
 const sessionRefreshes = new Map<string, Promise<GitHubTokenRefreshResult>>();
@@ -38,6 +45,7 @@ async function markGitHubSessionReauthRequired(req: Request, reason: string): Pr
     user.accessToken = '';
     delete user.refreshToken;
     delete user.tokenExpiresAt;
+    delete user.refreshTokenExpiresAt;
 
     await new Promise<void>(resolve => {
         req.session.save(err => {
@@ -72,6 +80,7 @@ function applyRefreshResultToRequest(req: Request, result: GitHubTokenRefreshRes
     user.accessToken = result.accessToken;
     if (result.refreshToken) user.refreshToken = result.refreshToken;
     if (result.tokenExpiresAt) user.tokenExpiresAt = result.tokenExpiresAt;
+    if (result.refreshTokenExpiresAt) user.refreshTokenExpiresAt = result.refreshTokenExpiresAt;
 }
 
 async function saveSession(req: Request, successMessage: string): Promise<void> {
@@ -88,9 +97,82 @@ async function saveSession(req: Request, successMessage: string): Promise<void>
     });
 }
 
+function buildTokenRefreshRequest(user: NonNullable<Request['user']>): { endpoint: string; init: RequestInit } {
+    if (user.oauthSource === 'connect') {
+        const relayUrl = process.env.PROPR_GH_RELAY_URL?.trim().replace(/\/+$/, '');
+        const relayToken = process.env.PROPR_GH_RELAY_TOKEN?.trim();
+        if (!relayUrl || !relayToken) throw new Error('ProPR Connect credentials are unavailable for token refresh');
+        const endpoint = new URL(`${relayUrl}/auth/instance-grants/refresh`);
+        if (endpoint.protocol !== 'https:' && endpoint.hostname !== 'localhost' && endpoint.hostname !== '127.0.0.1') {
+            throw new Error('PROPR_GH_RELAY_URL must use HTTPS');
+        }
+        return {
+            endpoint: endpoint.toString(),
+            init: {
+                method: 'POST',
+                headers: {
+                    'Accept': 'application/json',
+                    'Authorization': `Bearer ${relayToken}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({ refresh_token: user.refreshToken }),
+            },
+        };
+    }
+    return {
+        endpoint: 'https://github.com/login/oauth/access_token',
+        init: {
+            method: 'POST',
+            headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_id: process.env.GH_OAUTH_CLIENT_ID,
+                client_secret: process.env.GH_OAUTH_CLIENT_SECRET,
+                grant_type: 'refresh_token',
+                refresh_token: user.refreshToken,
+            }),
+        },
+    };
+}
+
+// Session fallback and the shared background credential deliberately converge here.
+// eslint-disable-next-line complexity
 async function performGitHubTokenRefresh(req: Request, force: boolean): Promise<GitHubTokenRefreshResult> {
     const user = req.user;
     if (!user || user.githubAuthInvalid) return { status: 'reauth-required' };
+    const supportsVisualPreviewUploads = isSupportedVisualPreviewUploadToken(user.accessToken || '');
+
+    if (supportsVisualPreviewUploads) {
+        try {
+            const sharedGrant = await visualPreviewOAuthCredentialService.refreshAndGetForOwner(user.id, force);
+            if (sharedGrant?.status === 'reauth_required') {
+                await markGitHubSessionReauthRequired(req, 'shared_visual_preview_grant_invalid');
+                return { status: 'reauth-required' };
+            }
+            if (sharedGrant?.accessToken) {
+                const changed = user.accessToken !== sharedGrant.accessToken
+                    || user.refreshToken !== sharedGrant.refreshToken
+                    || user.tokenExpiresAt !== sharedGrant.accessTokenExpiresAt;
+                user.accessToken = sharedGrant.accessToken;
+                user.refreshToken = sharedGrant.refreshToken;
+                user.tokenExpiresAt = sharedGrant.accessTokenExpiresAt;
+                user.refreshTokenExpiresAt = sharedGrant.refreshTokenExpiresAt;
+                if (changed) {
+                    await saveSession(req, `Synchronized refreshed GitHub token for user ${user.username}`);
+                }
+                return {
+                    status: changed ? 'refreshed' : 'not-needed',
+                    accessToken: user.accessToken,
+                    refreshToken: user.refreshToken,
+                    tokenExpiresAt: user.tokenExpiresAt,
+                    refreshTokenExpiresAt: user.refreshTokenExpiresAt,
+                };
+            }
+        } catch (error) {
+            console.error('Error refreshing shared GitHub OAuth credential:', error);
+            return { status: 'temporarily-unavailable' };
+        }
+    }
+
     if (!user.refreshToken) return { status: 'reauth-required' };
 
     const now = Date.now();
@@ -100,16 +182,8 @@ async function performGitHubTokenRefresh(req: Request, force: boolean): Promise<
     console.log(`Refreshing GitHub token for user ${user.username} (force=${force})`);
 
     try {
-        const response = await fetch('https://github.com/login/oauth/access_token', {
-            method: 'POST',
-            headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                client_id: process.env.GH_OAUTH_CLIENT_ID,
-                client_secret: process.env.GH_OAUTH_CLIENT_SECRET,
-                grant_type: 'refresh_token',
-                refresh_token: user.refreshToken,
-            }),
-        });
+        const refreshRequest = buildTokenRefreshRequest(user);
+        const response = await fetch(refreshRequest.endpoint, refreshRequest.init);
         if (!response.ok) {
             console.error(`GitHub token refresh failed with status ${response.status}`);
             return { status: 'temporarily-unavailable' };
@@ -129,14 +203,25 @@ async function performGitHubTokenRefresh(req: Request, force: boolean): Promise<
         user.accessToken = data.access_token;
         if (data.refresh_token) user.refreshToken = data.refresh_token;
         if (data.expires_in) user.tokenExpiresAt = Date.now() + (data.expires_in * 1000);
+        if (data.refresh_token_expires_in) {
+            user.refreshTokenExpiresAt = Date.now() + (data.refresh_token_expires_in * 1000);
+        }
 
         await saveSession(req, `Successfully refreshed GitHub token for user ${user.username}`);
+        if (supportsVisualPreviewUploads) {
+            try {
+                await updateVisualPreviewCredentialForCurrentOwner(user);
+            } catch (error) {
+                console.warn('[visual-preview] Could not persist the refreshed OAuth upload credential:', (error as Error).message);
+            }
+        }
 
         return {
             status: 'refreshed',
             accessToken: user.accessToken,
             refreshToken: user.refreshToken,
             tokenExpiresAt: user.tokenExpiresAt,
+            refreshTokenExpiresAt: user.refreshTokenExpiresAt,
         };
     } catch (error) {
         console.error('Error refreshing GitHub token:', error);
diff --git a/packages/api/authTypes.ts b/packages/api/authTypes.ts
index afbbdaf57..fc895b9b9 100644
--- a/packages/api/authTypes.ts
+++ b/packages/api/authTypes.ts
@@ -8,6 +8,8 @@ export interface GitHubUser {
     accessToken?: string;
     refreshToken?: string;
     tokenExpiresAt?: number;
+    refreshTokenExpiresAt?: number;
+    oauthSource?: 'github' | 'connect';
     githubAuthInvalid?: boolean;
 }
 
diff --git a/packages/api/connectAuth.ts b/packages/api/connectAuth.ts
index f810c61ee..720e2d837 100644
--- a/packages/api/connectAuth.ts
+++ b/packages/api/connectAuth.ts
@@ -103,6 +103,12 @@ export async function redeemConnectAuthorizationCode(options: {
         email: null,
         avatarUrl: body.avatar_url,
         accessToken: body.access_token,
+        refreshToken: body.refresh_token,
+        tokenExpiresAt: body.expires_in ? Date.now() + body.expires_in * 1000 : undefined,
+        refreshTokenExpiresAt: body.refresh_token_expires_in
+            ? Date.now() + body.refresh_token_expires_in * 1000
+            : undefined,
+        oauthSource: 'connect',
     };
 }
 
@@ -169,6 +175,9 @@ function isRedeemedIdentity(value: unknown): value is {
     username: string;
     avatar_url: string | null;
     access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    refresh_token_expires_in?: number;
 } {
     if (typeof value !== 'object' || value === null) return false;
     const candidate = value as Record<string, unknown>;
@@ -176,6 +185,10 @@ function isRedeemedIdentity(value: unknown): value is {
         isGitHubLogin(candidate.username) &&
         (candidate.avatar_url === null || typeof candidate.avatar_url === 'string') &&
         typeof candidate.access_token === 'string' &&
-        candidate.access_token.length > 0
+        candidate.access_token.length > 0 &&
+        (candidate.refresh_token === undefined || typeof candidate.refresh_token === 'string') &&
+        (candidate.expires_in === undefined || (typeof candidate.expires_in === 'number' && candidate.expires_in > 0)) &&
+        (candidate.refresh_token_expires_in === undefined
+            || (typeof candidate.refresh_token_expires_in === 'number' && candidate.refresh_token_expires_in > 0))
     );
 }
diff --git a/packages/api/routeRegistry.ts b/packages/api/routeRegistry.ts
index a9c52b05b..f3e79bfa1 100644
--- a/packages/api/routeRegistry.ts
+++ b/packages/api/routeRegistry.ts
@@ -6,6 +6,7 @@ import type {
   createAgentVersionRoutes,
   createConfigRoutes,
   createInstanceCatalogRoutes,
+  createVisualPreviewAuthRoutes,
 } from './routes/index.js';
 import {
   requireAgentTankUsageAccess,
@@ -26,6 +27,7 @@ interface ManagementRouteDeps {
   agentRuntimeRoutes: ReturnType<typeof createAgentRuntimeRoutes>;
   agentVersionRoutes: ReturnType<typeof createAgentVersionRoutes>;
   configRoutes: ReturnType<typeof createConfigRoutes>;
+  visualPreviewAuthRoutes: ReturnType<typeof createVisualPreviewAuthRoutes>;
 }
 
 interface MemberCatalogRouteDeps {
@@ -38,6 +40,7 @@ export function createManagementRouteEntries({
   agentRuntimeRoutes,
   agentVersionRoutes,
   configRoutes,
+  visualPreviewAuthRoutes,
 }: ManagementRouteDeps): RouteEntry[] {
   return [
     ['get', '/api/config/followup-keywords', requireManageSettings, configRoutes.getFollowupKeywords],
@@ -70,6 +73,9 @@ export function createManagementRouteEntries({
     ['get', '/api/config/agent-tank/usage', requireAgentTankUsageAccess, configRoutes.getAgentTankUsage],
     ['post', '/api/config/agent-tank/refresh', requireManageAgents, configRoutes.postAgentTankRefresh],
     ['get', '/api/config/agent-tank/detect', requireManageAgents, configRoutes.getAgentTankDetect],
+    ['get', '/api/config/visual-preview-auth', requireManageSettings, visualPreviewAuthRoutes.getStatus],
+    ['post', '/api/config/visual-preview-auth', requireManageSettings, visualPreviewAuthRoutes.useCurrentLogin],
+    ['delete', '/api/config/visual-preview-auth', requireManageSettings, visualPreviewAuthRoutes.disconnect],
 
     ['get', '/api/admin/members', requireManageMembers, adminRoutes.listMembers],
     ['get', '/api/admin/role-audit', requireManageMembers, adminRoutes.listRoleAudit],
diff --git a/packages/api/routes/index.ts b/packages/api/routes/index.ts
index 8c018e944..3d0ddfbcf 100644
--- a/packages/api/routes/index.ts
+++ b/packages/api/routes/index.ts
@@ -29,3 +29,4 @@ export { createUserRepoPreferencesRoutes } from './userRepoPreferencesRoutes.js'
 export { createAgentRuntimeRoutes } from './agentRuntimeRoutes.js';
 export { createNotificationRoutes } from './notificationRoutes.js';
 export { createAdminRoutes } from './adminRoutes.js';
+export { createVisualPreviewAuthRoutes } from './visualPreviewAuthRoutes.js';
diff --git a/packages/api/routes/visualPreviewAuthRoutes.ts b/packages/api/routes/visualPreviewAuthRoutes.ts
new file mode 100644
index 000000000..67b5e8c46
--- /dev/null
+++ b/packages/api/routes/visualPreviewAuthRoutes.ts
@@ -0,0 +1,71 @@
+import type { Request, Response } from 'express';
+import {
+  VisualPreviewOAuthCredentialService,
+  isSupportedVisualPreviewUploadToken,
+} from '@propr/core';
+import {
+  visualPreviewCredentialFromUser,
+  visualPreviewOAuthCredentialService,
+} from '../services/visualPreviewOAuth.js';
+
+interface VisualPreviewAuthRoutesDeps {
+  service?: VisualPreviewOAuthCredentialService;
+}
+
+function sendFailure(error: unknown, res: Response): void {
+  console.error('[visual-preview] Credential administration failed:', error);
+  res.status(500).json({
+    error: 'Visual-preview upload credential administration failed',
+    code: 'VISUAL_PREVIEW_AUTH_ADMINISTRATION_FAILED',
+  });
+}
+
+export function createVisualPreviewAuthRoutes({
+  service = visualPreviewOAuthCredentialService,
+}: VisualPreviewAuthRoutesDeps = {}) {
+  async function getStatus(req: Request, res: Response): Promise<void> {
+    try {
+      res.json({
+        ...await service.getStatus(),
+        currentUsername: req.user?.username,
+        canUseCurrentLogin: Boolean(
+          req.user?.accessToken && isSupportedVisualPreviewUploadToken(req.user.accessToken),
+        ),
+      });
+    } catch (error) {
+      sendFailure(error, res);
+    }
+  }
+
+  async function useCurrentLogin(req: Request, res: Response): Promise<void> {
+    const credential = req.user ? visualPreviewCredentialFromUser(req.user) : null;
+    if (!credential) {
+      res.status(409).json({
+        error: 'The current GitHub login did not provide an OAuth token supported by GitHub media uploads. Log out and sign in again.',
+        code: 'VISUAL_PREVIEW_LOGIN_TOKEN_UNSUPPORTED',
+      });
+      return;
+    }
+    try {
+      await service.replace(credential);
+      res.json({
+        ...await service.getStatus(),
+        currentUsername: req.user?.username,
+        canUseCurrentLogin: true,
+      });
+    } catch (error) {
+      sendFailure(error, res);
+    }
+  }
+
+  async function disconnect(_req: Request, res: Response): Promise<void> {
+    try {
+      await service.disconnect();
+      res.status(204).end();
+    } catch (error) {
+      sendFailure(error, res);
+    }
+  }
+
+  return { getStatus, useCurrentLogin, disconnect };
+}
diff --git a/packages/api/server.ts b/packages/api/server.ts
index 14a958ba0..5840f9df1 100644
--- a/packages/api/server.ts
+++ b/packages/api/server.ts
@@ -31,6 +31,7 @@ import {
   createUserRepoPreferencesRoutes,
   createAgentRuntimeRoutes, createNotificationRoutes,
   createAdminRoutes,
+  createVisualPreviewAuthRoutes,
   createInstanceCatalogRoutes,
   attachmentUpload
 } from './routes/index.js';
@@ -72,6 +73,10 @@ import {
   type RouteEntry
 } from './routeRegistry.js';
 import { createTaskDeleteRouteEntries } from './taskDeleteRouteRegistry.js';
+import {
+  startVisualPreviewOAuthRefreshScheduler,
+  type VisualPreviewOAuthRefreshScheduler,
+} from './services/visualPreviewOAuth.js';
 
 type ShutdownTask = { name: string; close: () => Promise<unknown> };
 
@@ -190,6 +195,7 @@ let configReloadSubscription: ConfigReloadSubscription | undefined;
 let notificationProjection: NotificationProjectionService | undefined;
 let webPushDispatcher: WebPushDispatcher | undefined;
 let webPushDispatcherConfigured = false;
+let visualPreviewOAuthRefreshScheduler: VisualPreviewOAuthRefreshScheduler | undefined;
 
 function createDemoTaskQueue(): Queue {
   return {
@@ -275,6 +281,7 @@ function setupRoutes(): void {
   const agentRuntimeRoutes = createAgentRuntimeRoutes({ getRuntimeBuildQueue: () => runtimeBuildQueue });
   const notificationRoutes = createNotificationRoutes({ webPushDispatcherConfigured });
   const adminRoutes = createAdminRoutes();
+  const visualPreviewAuthRoutes = createVisualPreviewAuthRoutes();
   const instanceCatalogRoutes = createInstanceCatalogRoutes();
   const agentVersionRoutes = createAgentVersionRoutes();
 
@@ -311,6 +318,7 @@ function setupRoutes(): void {
       agentRuntimeRoutes,
       agentVersionRoutes,
       configRoutes,
+      visualPreviewAuthRoutes,
     }),
   ];
   assertNoDuplicateRoutes(routes);
@@ -425,6 +433,7 @@ async function start(): Promise<void> {
       // chain so no settings update can race with the startup snapshot.
       await configReloadSubscription.reload();
       await initializePushSubscriptionMaintenance();
+      visualPreviewOAuthRefreshScheduler = await startVisualPreviewOAuthRefreshScheduler();
       try {
         const removed = await agentLoginSessionManager.cleanupOrphanedContainers();
         if (removed > 0) console.log(`Removed ${removed} orphaned agent login container(s)`);
@@ -488,6 +497,7 @@ async function start(): Promise<void> {
       if (!demoMode) {
         shutdownTasks.push(
           { name: 'Web Push dispatcher', close: () => webPushDispatcher?.close() ?? Promise.resolve() },
+          { name: 'visual-preview OAuth refresh scheduler', close: () => visualPreviewOAuthRefreshScheduler?.close() ?? Promise.resolve() },
           { name: 'config reload subscriber', close: () => configReloadSubscription?.close() ?? Promise.resolve() },
           { name: 'ultrafix state redis', close: () => closeUltrafixStateRedis() },
           { name: 'socket service', close: () => closeSocketService() },
diff --git a/packages/api/services/visualPreviewOAuth.ts b/packages/api/services/visualPreviewOAuth.ts
new file mode 100644
index 000000000..814c8a5e1
--- /dev/null
+++ b/packages/api/services/visualPreviewOAuth.ts
@@ -0,0 +1,76 @@
+import {
+  VisualPreviewOAuthCredentialService,
+  isSupportedVisualPreviewUploadToken,
+  type VisualPreviewOAuthCredentialInput,
+} from '@propr/core';
+import type { GitHubUser } from '../authTypes.js';
+import { resolveInstanceAuthorization } from '../authorization.js';
+import { isUserWhitelisted } from '../userWhitelist.js';
+
+const REFRESH_INTERVAL_MS = 30 * 60 * 1000;
+
+export const visualPreviewOAuthCredentialService = new VisualPreviewOAuthCredentialService();
+
+export function visualPreviewCredentialFromUser(user: GitHubUser): VisualPreviewOAuthCredentialInput | null {
+  const accessToken = user.accessToken?.trim();
+  if (!accessToken || !isSupportedVisualPreviewUploadToken(accessToken)) return null;
+  return {
+    githubUserId: user.id,
+    githubUsername: user.username,
+    source: user.oauthSource || 'github',
+    accessToken,
+    refreshToken: user.refreshToken,
+    accessTokenExpiresAt: user.tokenExpiresAt,
+    refreshTokenExpiresAt: user.refreshTokenExpiresAt,
+  };
+}
+
+export async function captureVisualPreviewCredentialFromAdminLogin(user: GitHubUser): Promise<boolean> {
+  if (!isUserWhitelisted(user.username)) return false;
+  const credential = visualPreviewCredentialFromUser(user);
+  if (!credential) return false;
+  const authorization = await resolveInstanceAuthorization(user);
+  if (authorization.role !== 'admin') return false;
+  return visualPreviewOAuthCredentialService.captureFromLogin(credential);
+}
+
+export async function updateVisualPreviewCredentialForCurrentOwner(user: GitHubUser): Promise<boolean> {
+  const credential = visualPreviewCredentialFromUser(user);
+  if (!credential) return false;
+  return visualPreviewOAuthCredentialService.updateIfOwner(credential);
+}
+
+export interface VisualPreviewOAuthRefreshScheduler {
+  close: () => Promise<void>;
+}
+
+export async function startVisualPreviewOAuthRefreshScheduler(
+  service = visualPreviewOAuthCredentialService,
+): Promise<VisualPreviewOAuthRefreshScheduler> {
+  let closed = false;
+  let activeRefresh: Promise<void> | undefined;
+  const refresh = (): Promise<void> => {
+    if (activeRefresh) return activeRefresh;
+    activeRefresh = service.refreshIfNeeded()
+      .then(result => {
+        if (result === 'refreshed') console.log('[visual-preview] Refreshed the GitHub OAuth upload credential');
+        if (result === 'reauth-required') console.warn('[visual-preview] GitHub OAuth upload credential requires reconnection');
+      })
+      .catch(error => {
+        console.warn('[visual-preview] Could not refresh the GitHub OAuth upload credential:', (error as Error).message);
+      })
+      .finally(() => { activeRefresh = undefined; });
+    return activeRefresh;
+  };
+
+  await refresh();
+  const timer = setInterval(() => { if (!closed) void refresh(); }, REFRESH_INTERVAL_MS);
+  timer.unref();
+  return {
+    close: async () => {
+      closed = true;
+      clearInterval(timer);
+      await activeRefresh;
+    },
+  };
+}
diff --git a/packages/api/test/authGithubTokens.test.ts b/packages/api/test/authGithubTokens.test.ts
index 499f69343..42120fa7d 100644
--- a/packages/api/test/authGithubTokens.test.ts
+++ b/packages/api/test/authGithubTokens.test.ts
@@ -145,6 +145,40 @@ test('ensureAuthenticated reports a temporary error when refresh fails recoverab
   assert.equal(req.destroyCalls, 0);
 });
 
+test('refreshes a Connect-issued session through the relay', async () => {
+  configureDemoMode(false);
+  const previousRelayUrl = process.env.PROPR_GH_RELAY_URL;
+  const previousRelayToken = process.env.PROPR_GH_RELAY_TOKEN;
+  process.env.PROPR_GH_RELAY_URL = 'https://relay.example.test/v1';
+  process.env.PROPR_GH_RELAY_TOKEN = 'prt_relay';
+  const req = createRequest(createUser({
+    accessToken: 'connect-access-token',
+    oauthSource: 'connect',
+  }));
+  const { response } = createJsonResponse();
+  let refreshRequest: Request | undefined;
+  globalThis.fetch = async (input, init) => {
+    refreshRequest = new Request(input, init);
+    return Response.json({
+      access_token: 'gho_fresh-connect-token',
+      refresh_token: 'ghr_fresh-connect-refresh',
+      expires_in: 3600,
+    });
+  };
+
+  try {
+    assert.equal(await runEnsureAuthenticated(req, response), true);
+    assert.equal(refreshRequest?.url, 'https://relay.example.test/v1/auth/instance-grants/refresh');
+    assert.equal(refreshRequest?.headers.get('authorization'), 'Bearer prt_relay');
+    assert.deepEqual(JSON.parse(await refreshRequest!.text()), { refresh_token: 'refresh-token' });
+  } finally {
+    if (previousRelayUrl === undefined) delete process.env.PROPR_GH_RELAY_URL;
+    else process.env.PROPR_GH_RELAY_URL = previousRelayUrl;
+    if (previousRelayToken === undefined) delete process.env.PROPR_GH_RELAY_TOKEN;
+    else process.env.PROPR_GH_RELAY_TOKEN = previousRelayToken;
+  }
+});
+
 test('ensureAuthenticated coalesces concurrent expired-token refreshes for one session', async () => {
   configureDemoMode(false);
   const req1 = createRequest(createUser({ accessToken: 'expired-token-1' }));
diff --git a/packages/api/test/connectAuth.test.ts b/packages/api/test/connectAuth.test.ts
index a27be828c..a7c7fd44a 100644
--- a/packages/api/test/connectAuth.test.ts
+++ b/packages/api/test/connectAuth.test.ts
@@ -145,3 +145,30 @@ test('binds the Connect identity username to the validated token owner', async (
   assert.equal(user.username, 'verified-owner');
   assert.equal(user.displayName, 'verified-owner');
 });
+
+test('preserves expiring OAuth grant fields returned by Connect', async () => {
+  const before = Date.now();
+  const user = await redeemConnectAuthorizationCode({
+    code: 'pia_code',
+    relayUrl: 'https://webhook.propr.dev/v1',
+    relayToken: 'prt_relay_secret',
+    fetchImpl: (async (input) => {
+      if (String(input) === 'https://api.github.com/user') {
+        return Response.json({ id: 583231, login: 'octocat' });
+      }
+      return Response.json({
+        username: 'octocat',
+        avatar_url: null,
+        access_token: 'gho_user_secret',
+        refresh_token: 'ghr_refresh_secret',
+        expires_in: 28_800,
+        refresh_token_expires_in: 15_897_600,
+      });
+    }) as typeof fetch,
+  });
+
+  assert.equal(user.oauthSource, 'connect');
+  assert.equal(user.refreshToken, 'ghr_refresh_secret');
+  assert.ok((user.tokenExpiresAt || 0) >= before + 28_800_000);
+  assert.ok((user.refreshTokenExpiresAt || 0) >= before + 15_897_600_000);
+});
diff --git a/packages/api/test/routeAuthorization.test.ts b/packages/api/test/routeAuthorization.test.ts
index 6c314ac3c..2badfbf85 100644
--- a/packages/api/test/routeAuthorization.test.ts
+++ b/packages/api/test/routeAuthorization.test.ts
@@ -52,6 +52,7 @@ function createAuthorizationTestApp() {
       agentRuntimeRoutes: handlerCollection(),
       agentVersionRoutes: handlerCollection(),
       configRoutes: handlerCollection(),
+      visualPreviewAuthRoutes: handlerCollection(),
     }),
   ];
   assertNoDuplicateRoutes(routes);
@@ -82,6 +83,9 @@ const managementRequests = [
   ['POST', '/api/config/synthetic-agents'],
   ['GET', '/api/config/agent-tank/usage'],
   ['GET', '/api/admin/members'],
+  ['GET', '/api/config/visual-preview-auth'],
+  ['POST', '/api/config/visual-preview-auth'],
+  ['DELETE', '/api/config/visual-preview-auth'],
   ['GET', '/api/agent-runtime/packages'],
   ['POST', '/api/agent-runtime/packages/verify'],
   ['GET', '/api/agents/codex/images'],
diff --git a/packages/api/test/visualPreviewAuthRoutes.test.ts b/packages/api/test/visualPreviewAuthRoutes.test.ts
new file mode 100644
index 000000000..ea2450f23
--- /dev/null
+++ b/packages/api/test/visualPreviewAuthRoutes.test.ts
@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import { after, test } from 'node:test';
+import type { Request, Response } from 'express';
+import { closeConnection } from '@propr/core';
+import type {
+  VisualPreviewOAuthCredentialInput,
+  VisualPreviewOAuthCredentialService,
+} from '@propr/core';
+import { createVisualPreviewAuthRoutes } from '../routes/visualPreviewAuthRoutes.js';
+import type { GitHubUser } from '../authTypes.js';
+
+after(async () => closeConnection());
+
+function user(overrides: Partial<GitHubUser> = {}): GitHubUser {
+  return {
+    id: '123',
+    login: 'admin',
+    username: 'admin',
+    displayName: 'Admin',
+    email: null,
+    avatarUrl: null,
+    accessToken: 'gho_browser-secret',
+    refreshToken: 'ghr_browser-secret',
+    oauthSource: 'github',
+    ...overrides,
+  };
+}
+
+function responseRecorder() {
+  let statusCode = 200;
+  let body: unknown;
+  const response = {
+    status(code: number) {
+      statusCode = code;
+      return response;
+    },
+    json(value: unknown) {
+      body = value;
+      return response;
+    },
+    end() { return response; },
+  } as unknown as Response;
+  return { response, getStatus: () => statusCode, getBody: () => body };
+}
+
+test('returns visual-preview auth status without exposing stored token material', async () => {
+  const service = {
+    getStatus: async () => ({
+      configured: true,
+      source: 'github' as const,
+      status: 'active' as const,
+      githubUsername: 'admin',
+    }),
+  } as unknown as VisualPreviewOAuthCredentialService;
+  const routes = createVisualPreviewAuthRoutes({ service });
+  const recorder = responseRecorder();
+
+  await routes.getStatus({ user: user() } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 200);
+  assert.deepEqual(recorder.getBody(), {
+    configured: true,
+    source: 'github',
+    status: 'active',
+    githubUsername: 'admin',
+    currentUsername: 'admin',
+    canUseCurrentLogin: true,
+  });
+  assert.doesNotMatch(JSON.stringify(recorder.getBody()), /browser-secret/);
+});
+
+test('explicitly replaces the uploader grant with the current administrator login', async () => {
+  let replaced: VisualPreviewOAuthCredentialInput | undefined;
+  const service = {
+    replace: async (credential: VisualPreviewOAuthCredentialInput) => { replaced = credential; },
+    getStatus: async () => ({ configured: true, source: 'github' as const, status: 'active' as const }),
+  } as unknown as VisualPreviewOAuthCredentialService;
+  const routes = createVisualPreviewAuthRoutes({ service });
+  const recorder = responseRecorder();
+
+  await routes.useCurrentLogin({ user: user() } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 200);
+  assert.equal(replaced?.githubUserId, '123');
+  assert.equal(replaced?.accessToken, 'gho_browser-secret');
+  assert.doesNotMatch(JSON.stringify(recorder.getBody()), /browser-secret/);
+});
+
+test('rejects a current login whose GitHub token cannot upload attachments', async () => {
+  const routes = createVisualPreviewAuthRoutes({ service: {} as VisualPreviewOAuthCredentialService });
+  const recorder = responseRecorder();
+
+  await routes.useCurrentLogin({ user: user({ accessToken: 'ghs_installation-token' }) } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 409);
+  assert.deepEqual(recorder.getBody(), {
+    error: 'The current GitHub login did not provide an OAuth token supported by GitHub media uploads. Log out and sign in again.',
+    code: 'VISUAL_PREVIEW_LOGIN_TOKEN_UNSUPPORTED',
+  });
+});
diff --git a/packages/core/src/db/migrations/20260903000000_create_visual_preview_oauth_credentials.js b/packages/core/src/db/migrations/20260903000000_create_visual_preview_oauth_credentials.js
new file mode 100644
index 000000000..a521c0625
--- /dev/null
+++ b/packages/core/src/db/migrations/20260903000000_create_visual_preview_oauth_credentials.js
@@ -0,0 +1,27 @@
+/**
+ * Stores the single GitHub user credential used for visual-preview uploads.
+ * Token material is encrypted by the application before it reaches SQLite.
+ */
+export async function up(knex) {
+  await knex.schema.createTable('visual_preview_oauth_credentials', table => {
+    table.integer('id').primary();
+    table.string('github_user_id', 255).notNullable();
+    table.string('github_username', 255).notNullable();
+    table.string('source', 32).notNullable();
+    table.text('access_token_encrypted').notNullable();
+    table.text('refresh_token_encrypted').nullable();
+    table.bigInteger('access_token_expires_at_ms').nullable();
+    table.bigInteger('refresh_token_expires_at_ms').nullable();
+    table.string('status', 32).notNullable().defaultTo('active');
+    table.string('last_error_code', 64).nullable();
+    table.bigInteger('refresh_lease_until_ms').nullable();
+    table.string('refresh_lease_owner', 64).nullable();
+    table.timestamp('last_refreshed_at').nullable();
+    table.timestamp('created_at').defaultTo(knex.fn.now()).notNullable();
+    table.timestamp('updated_at').defaultTo(knex.fn.now()).notNullable();
+  });
+}
+
+export async function down(knex) {
+  await knex.schema.dropTableIfExists('visual_preview_oauth_credentials');
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 6f280b3ac..35e9bb9e6 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- public package exports are intentionally centralized */
 export { default as logger, generateCorrelationId, createCorrelatedLogger } from './utils/logger.js';
 export { handleError, withErrorHandling, safeAsync, makeIdempotent, categorizeError, ErrorCategories } from './utils/errorHandler.js';
 export type { ErrorCategory, ErrorDetails, ErrorHandlerOptions, IssueRef as ErrorIssueRef } from './utils/errorHandler.js';
@@ -175,6 +176,7 @@ export { validateAttachmentBaseUrlConfig } from './services/taskExecutionHelpers
 export { AttachmentService } from './services/attachmentService.js';
 export type { Attachment, MulterFile } from './services/attachmentService.js';
 export * from './services/visualPreviewService.js';
+export * from './services/visualPreviewOAuthCredentialService.js';
 export { PLANNER_SYSTEM_PROMPT, GRANULARITY_INSTRUCTIONS, getPlannerPrompt, REFINER_SYSTEM_PROMPT } from './claude/prompts/plannerPrompts.js';
 export type { Plan, PlanItem, RefinementResponse } from './claude/prompts/plannerPrompts.js';
 export { parseLlmJson, JsonParseError } from './utils/jsonUtils.js';
diff --git a/packages/core/src/services/visualPreviewOAuthCredentialService.ts b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
new file mode 100644
index 000000000..10392ceb4
--- /dev/null
+++ b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
@@ -0,0 +1,468 @@
+/* eslint-disable max-lines -- storage, encryption, leasing, and provider refresh form one credential boundary */
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+} from 'node:crypto';
+import type { Knex } from 'knex';
+import { db } from '../db/connection.js';
+
+const CREDENTIAL_ID = 1;
+const ACCESS_TOKEN_REFRESH_BUFFER_MS = 60 * 60 * 1000;
+const TOKEN_REFRESH_TIMEOUT_MS = 20_000;
+const REFRESH_LEASE_MS = TOKEN_REFRESH_TIMEOUT_MS + 5_000;
+const REFRESH_LEASE_POLL_MS = 100;
+const ENCRYPTION_CONTEXT = 'propr:visual-preview-oauth:v1';
+const SUPPORTED_TOKEN_PATTERN = /^(?:gho_|ghp_|github_pat_)/;
+
+export const VISUAL_PREVIEW_UPLOAD_TOKEN_ENV = 'GITHUB_VISUAL_PREVIEW_TOKEN';
+export const VISUAL_PREVIEW_CREDENTIAL_KEY_ENV = 'PROPR_CREDENTIAL_ENCRYPTION_KEY';
+
+export type VisualPreviewOAuthSource = 'github' | 'connect';
+export type VisualPreviewOAuthStatus = 'active' | 'reauth_required';
+
+export interface VisualPreviewOAuthCredentialInput {
+  githubUserId: string;
+  githubUsername: string;
+  source: VisualPreviewOAuthSource;
+  accessToken: string;
+  refreshToken?: string;
+  accessTokenExpiresAt?: number;
+  refreshTokenExpiresAt?: number;
+}
+
+export interface VisualPreviewOAuthCredentialStatus {
+  configured: boolean;
+  source?: VisualPreviewOAuthSource | 'environment';
+  status: VisualPreviewOAuthStatus | 'missing';
+  githubUsername?: string;
+  accessTokenExpiresAt?: number;
+  refreshTokenExpiresAt?: number;
+  lastErrorCode?: string;
+  updatedAt?: string;
+}
+
+export interface VisualPreviewOAuthCredentialGrant {
+  status: 'active' | 'reauth_required';
+  accessToken?: string;
+  refreshToken?: string;
+  accessTokenExpiresAt?: number;
+  refreshTokenExpiresAt?: number;
+}
+
+interface CredentialRow {
+  id: number;
+  github_user_id: string;
+  github_username: string;
+  source: VisualPreviewOAuthSource;
+  access_token_encrypted: string;
+  refresh_token_encrypted: string | null;
+  access_token_expires_at_ms: number | string | null;
+  refresh_token_expires_at_ms: number | string | null;
+  status: VisualPreviewOAuthStatus;
+  last_error_code: string | null;
+  refresh_lease_until_ms: number | string | null;
+  refresh_lease_owner: string | null;
+  last_refreshed_at: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+interface TokenRefreshResponse {
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  refresh_token_expires_in?: number;
+  error?: string;
+  error_description?: string;
+}
+
+export type VisualPreviewCredentialErrorCode =
+  | 'VISUAL_PREVIEW_AUTH_MISSING'
+  | 'VISUAL_PREVIEW_AUTH_UNSUPPORTED'
+  | 'VISUAL_PREVIEW_AUTH_EXPIRED'
+  | 'VISUAL_PREVIEW_AUTH_REAUTH_REQUIRED'
+  | 'VISUAL_PREVIEW_AUTH_DECRYPTION_FAILED';
+
+export class VisualPreviewCredentialError extends Error {
+  constructor(
+    public readonly code: VisualPreviewCredentialErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'VisualPreviewCredentialError';
+  }
+}
+
+export function isVisualPreviewCredentialError(error: unknown): error is VisualPreviewCredentialError {
+  return error instanceof VisualPreviewCredentialError || (
+    error instanceof Error
+    && 'code' in error
+    && typeof (error as { code?: unknown }).code === 'string'
+    && (error as { code: string }).code.startsWith('VISUAL_PREVIEW_AUTH_')
+  );
+}
+
+export function isSupportedVisualPreviewUploadToken(token: string): boolean {
+  return SUPPORTED_TOKEN_PATTERN.test(token.trim());
+}
+
+function optionalTimestamp(value: number | string | null): number | undefined {
+  if (value === null) return undefined;
+  const timestamp = Number(value);
+  return Number.isFinite(timestamp) ? timestamp : undefined;
+}
+
+function encryptionSecret(environment: NodeJS.ProcessEnv): string | undefined {
+  return environment[VISUAL_PREVIEW_CREDENTIAL_KEY_ENV]?.trim()
+    || environment.SYSTEM_TASK_SECRET?.trim()
+    || environment.SESSION_SECRET?.trim();
+}
+
+function encryptionKey(environment: NodeJS.ProcessEnv): Buffer {
+  const secret = encryptionSecret(environment);
+  if (!secret) {
+    throw new Error(
+      `${VISUAL_PREVIEW_CREDENTIAL_KEY_ENV}, SYSTEM_TASK_SECRET, or SESSION_SECRET must be configured `
+      + 'to store the visual-preview OAuth credential securely.',
+    );
+  }
+  return createHash('sha256').update(ENCRYPTION_CONTEXT).update('\0').update(secret).digest();
+}
+
+function encryptToken(token: string, environment: NodeJS.ProcessEnv): string {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', encryptionKey(environment), iv);
+  const ciphertext = Buffer.concat([cipher.update(token, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return ['v1', iv.toString('base64url'), tag.toString('base64url'), ciphertext.toString('base64url')].join('.');
+}
+
+function decryptToken(value: string, environment: NodeJS.ProcessEnv): string {
+  try {
+    const [version, encodedIv, encodedTag, encodedCiphertext] = value.split('.');
+    if (version !== 'v1' || !encodedIv || !encodedTag || !encodedCiphertext) throw new Error('invalid envelope');
+    const decipher = createDecipheriv('aes-256-gcm', encryptionKey(environment), Buffer.from(encodedIv, 'base64url'));
+    decipher.setAuthTag(Buffer.from(encodedTag, 'base64url'));
+    return Buffer.concat([
+      decipher.update(Buffer.from(encodedCiphertext, 'base64url')),
+      decipher.final(),
+    ]).toString('utf8');
+  } catch {
+    throw new VisualPreviewCredentialError(
+      'VISUAL_PREVIEW_AUTH_DECRYPTION_FAILED',
+      'The stored visual-preview OAuth credential could not be decrypted. Verify the shared credential encryption secret.',
+    );
+  }
+}
+
+function assertSupportedToken(token: string): string {
+  const normalized = token.trim();
+  if (!isSupportedVisualPreviewUploadToken(normalized)) {
+    throw new VisualPreviewCredentialError(
+      'VISUAL_PREVIEW_AUTH_UNSUPPORTED',
+      'GitHub visual-preview uploads require an OAuth token or personal access token; GitHub App tokens are not supported.',
+    );
+  }
+  return normalized;
+}
+
+function resolveEnvironmentToken(environment: NodeJS.ProcessEnv): string | undefined {
+  const token = environment[VISUAL_PREVIEW_UPLOAD_TOKEN_ENV]?.trim();
+  return token ? assertSupportedToken(token) : undefined;
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+function statusFromRow(row: CredentialRow): VisualPreviewOAuthCredentialStatus {
+  return {
+    configured: true,
+    source: row.source,
+    status: row.status,
+    githubUsername: row.github_username,
+    accessTokenExpiresAt: optionalTimestamp(row.access_token_expires_at_ms),
+    refreshTokenExpiresAt: optionalTimestamp(row.refresh_token_expires_at_ms),
+    lastErrorCode: row.last_error_code || undefined,
+    updatedAt: row.updated_at,
+  };
+}
+
+function isUnrecoverableRefreshError(error?: string): boolean {
+  return error === 'bad_refresh_token' || error === 'invalid_grant';
+}
+
+export class VisualPreviewOAuthCredentialService {
+  constructor(
+    private readonly database: Knex = db,
+    private readonly environment: NodeJS.ProcessEnv = process.env,
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  private credentialQuery() {
+    return this.database<CredentialRow>('visual_preview_oauth_credentials').where({ id: CREDENTIAL_ID });
+  }
+
+  async getStatus(): Promise<VisualPreviewOAuthCredentialStatus> {
+    const rawEnvironmentToken = this.environment[VISUAL_PREVIEW_UPLOAD_TOKEN_ENV]?.trim();
+    if (rawEnvironmentToken) {
+      return isSupportedVisualPreviewUploadToken(rawEnvironmentToken)
+        ? { configured: true, source: 'environment', status: 'active' }
+        : {
+            configured: true,
+            source: 'environment',
+            status: 'reauth_required',
+            lastErrorCode: 'unsupported_environment_token',
+          };
+    }
+    const row = await this.credentialQuery().first();
+    return row ? statusFromRow(row) : { configured: false, status: 'missing' };
+  }
+
+  async captureFromLogin(input: VisualPreviewOAuthCredentialInput): Promise<boolean> {
+    assertSupportedToken(input.accessToken);
+    const existing = await this.credentialQuery().first();
+    if (existing && existing.github_user_id !== input.githubUserId && existing.status === 'active') return false;
+    await this.store(input);
+    return true;
+  }
+
+  async replace(input: VisualPreviewOAuthCredentialInput): Promise<void> {
+    assertSupportedToken(input.accessToken);
+    await this.store(input);
+  }
+
+  async updateIfOwner(input: VisualPreviewOAuthCredentialInput): Promise<boolean> {
+    assertSupportedToken(input.accessToken);
+    const existing = await this.credentialQuery().first();
+    if (!existing || existing.github_user_id !== input.githubUserId) return false;
+    await this.store(input);
+    return true;
+  }
+
+  private async store(input: VisualPreviewOAuthCredentialInput): Promise<void> {
+    const now = this.database.fn.now();
+    const values = {
+      id: CREDENTIAL_ID,
+      github_user_id: input.githubUserId,
+      github_username: input.githubUsername,
+      source: input.source,
+      access_token_encrypted: encryptToken(input.accessToken.trim(), this.environment),
+      refresh_token_encrypted: input.refreshToken
+        ? encryptToken(input.refreshToken.trim(), this.environment)
+        : null,
+      access_token_expires_at_ms: input.accessTokenExpiresAt ?? null,
+      refresh_token_expires_at_ms: input.refreshTokenExpiresAt ?? null,
+      status: 'active' as const,
+      last_error_code: null,
+      refresh_lease_until_ms: null,
+      refresh_lease_owner: null,
+      updated_at: now,
+    };
+    await this.database('visual_preview_oauth_credentials')
+      .insert({ ...values, created_at: now })
+      .onConflict('id')
+      .merge(values);
+  }
+
+  async disconnect(): Promise<void> {
+    await this.credentialQuery().delete();
+  }
+
+  async resolveUploadToken(): Promise<string> {
+    const environmentToken = resolveEnvironmentToken(this.environment);
+    if (environmentToken) return environmentToken;
+
+    const row = await this.credentialQuery().first();
+    if (!row) {
+      throw new VisualPreviewCredentialError(
+        'VISUAL_PREVIEW_AUTH_MISSING',
+        'No GitHub user credential is configured for visual-preview uploads.',
+      );
+    }
+    if (row.status !== 'active') {
+      throw new VisualPreviewCredentialError(
+        'VISUAL_PREVIEW_AUTH_REAUTH_REQUIRED',
+        'The GitHub user credential for visual-preview uploads must be reconnected.',
+      );
+    }
+    const expiresAt = optionalTimestamp(row.access_token_expires_at_ms);
+    if (expiresAt !== undefined && expiresAt <= Date.now()) {
+      throw new VisualPreviewCredentialError(
+        'VISUAL_PREVIEW_AUTH_EXPIRED',
+        'The GitHub user credential for visual-preview uploads has expired.',
+      );
+    }
+    return assertSupportedToken(decryptToken(row.access_token_encrypted, this.environment));
+  }
+
+  async markReauthRequired(errorCode: string): Promise<void> {
+    if (this.environment[VISUAL_PREVIEW_UPLOAD_TOKEN_ENV]?.trim()) return;
+    await this.credentialQuery().update({
+      status: 'reauth_required',
+      last_error_code: errorCode.slice(0, 64),
+      refresh_lease_until_ms: null,
+      refresh_lease_owner: null,
+      updated_at: this.database.fn.now(),
+    });
+  }
+
+  async refreshIfNeeded(force = false): Promise<'missing' | 'not-needed' | 'refreshed' | 'reauth-required'> {
+    if (resolveEnvironmentToken(this.environment)) return 'not-needed';
+    const row = await this.credentialQuery().first();
+    if (!row) return 'missing';
+    if (row.status !== 'active') return 'reauth-required';
+
+    const expiresAt = optionalTimestamp(row.access_token_expires_at_ms);
+    const needsRefresh = force || (expiresAt !== undefined && expiresAt - Date.now() < ACCESS_TOKEN_REFRESH_BUFFER_MS);
+    if (!needsRefresh) return 'not-needed';
+    if (!row.refresh_token_encrypted) {
+      await this.markReauthRequired('missing_refresh_token');
+      return 'reauth-required';
+    }
+
+    const leaseOwner = randomBytes(16).toString('hex');
+    const leaseAcquired = await this.database<CredentialRow>('visual_preview_oauth_credentials')
+      .where({ id: CREDENTIAL_ID, status: 'active' })
+      .andWhere(builder => builder
+        .whereNull('refresh_lease_until_ms')
+        .orWhere('refresh_lease_until_ms', '<', Date.now()))
+      .update({
+        refresh_lease_owner: leaseOwner,
+        refresh_lease_until_ms: Date.now() + REFRESH_LEASE_MS,
+      });
+    if (leaseAcquired === 0) {
+      await this.waitForRefreshLease();
+      const refreshedRow = await this.credentialQuery().first();
+      if (!refreshedRow) return 'missing';
+      if (refreshedRow.status !== 'active') return 'reauth-required';
+      const refreshedExpiry = optionalTimestamp(refreshedRow.access_token_expires_at_ms);
+      if (refreshedExpiry !== undefined && refreshedExpiry - Date.now() < ACCESS_TOKEN_REFRESH_BUFFER_MS) {
+        throw new Error('Concurrent GitHub OAuth refresh did not produce a usable access token');
+      }
+      return 'not-needed';
+    }
+
+    try {
+      const refreshToken = decryptToken(row.refresh_token_encrypted, this.environment);
+      const response = await this.requestRefresh(row.source, refreshToken);
+      if (response.error) {
+        if (isUnrecoverableRefreshError(response.error)) {
+          await this.markReauthRequired(response.error);
+          return 'reauth-required';
+        }
+        throw new Error(`GitHub OAuth refresh was temporarily unavailable (${response.error})`);
+      }
+      if (!response.access_token) throw new Error('GitHub OAuth refresh response did not include an access token');
+
+      const now = Date.now();
+      await this.store({
+        githubUserId: row.github_user_id,
+        githubUsername: row.github_username,
+        source: row.source,
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token || refreshToken,
+        accessTokenExpiresAt: response.expires_in ? now + response.expires_in * 1000 : undefined,
+        refreshTokenExpiresAt: response.refresh_token_expires_in
+          ? now + response.refresh_token_expires_in * 1000
+          : optionalTimestamp(row.refresh_token_expires_at_ms),
+      });
+      await this.credentialQuery().update({ last_refreshed_at: this.database.fn.now() });
+      return 'refreshed';
+    } finally {
+      await this.database<CredentialRow>('visual_preview_oauth_credentials')
+        .where({ id: CREDENTIAL_ID, refresh_lease_owner: leaseOwner })
+        .update({ refresh_lease_owner: null, refresh_lease_until_ms: null });
+    }
+  }
+
+  async refreshAndGetForOwner(
+    githubUserId: string,
+    force = false,
+  ): Promise<VisualPreviewOAuthCredentialGrant | null> {
+    const current = await this.credentialQuery().first();
+    if (!current || current.github_user_id !== githubUserId) return null;
+    const refreshStatus = await this.refreshIfNeeded(force);
+    if (refreshStatus === 'reauth-required') return { status: 'reauth_required' };
+    const row = await this.credentialQuery().first();
+    if (!row || row.github_user_id !== githubUserId) return null;
+    if (row.status !== 'active') return { status: 'reauth_required' };
+    return {
+      status: 'active',
+      accessToken: decryptToken(row.access_token_encrypted, this.environment),
+      refreshToken: row.refresh_token_encrypted
+        ? decryptToken(row.refresh_token_encrypted, this.environment)
+        : undefined,
+      accessTokenExpiresAt: optionalTimestamp(row.access_token_expires_at_ms),
+      refreshTokenExpiresAt: optionalTimestamp(row.refresh_token_expires_at_ms),
+    };
+  }
+
+  private async waitForRefreshLease(): Promise<void> {
+    const deadline = Date.now() + REFRESH_LEASE_MS;
+    while (Date.now() < deadline) {
+      const row = await this.credentialQuery().first();
+      if (!row?.refresh_lease_owner || (optionalTimestamp(row.refresh_lease_until_ms) || 0) <= Date.now()) return;
+      await delay(REFRESH_LEASE_POLL_MS);
+    }
+  }
+
+  private async requestRefresh(source: VisualPreviewOAuthSource, refreshToken: string): Promise<TokenRefreshResponse> {
+    if (source === 'connect') return this.requestConnectRefresh(refreshToken);
+    const clientId = this.environment.GH_OAUTH_CLIENT_ID?.trim();
+    const clientSecret = this.environment.GH_OAUTH_CLIENT_SECRET?.trim();
+    if (!clientId || !clientSecret) throw new Error('GitHub OAuth client credentials are unavailable for token refresh');
+    return this.postRefresh('https://github.com/login/oauth/access_token', {
+      client_id: clientId,
+      client_secret: clientSecret,
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+    });
+  }
+
+  private async requestConnectRefresh(refreshToken: string): Promise<TokenRefreshResponse> {
+    const relayUrl = this.environment.PROPR_GH_RELAY_URL?.trim().replace(/\/+$/, '');
+    const relayToken = this.environment.PROPR_GH_RELAY_TOKEN?.trim();
+    if (!relayUrl || !relayToken) throw new Error('ProPR Connect credentials are unavailable for token refresh');
+    const endpoint = new URL(`${relayUrl}/auth/instance-grants/refresh`);
+    if (endpoint.protocol !== 'https:' && endpoint.hostname !== 'localhost' && endpoint.hostname !== '127.0.0.1') {
+      throw new Error('PROPR_GH_RELAY_URL must use HTTPS');
+    }
+    return this.postRefresh(endpoint, { refresh_token: refreshToken }, relayToken);
+  }
+
+  private async postRefresh(
+    endpoint: string | URL,
+    body: Record<string, string>,
+    bearerToken?: string,
+  ): Promise<TokenRefreshResponse> {
+    const response = await this.fetchImpl(endpoint, {
+      method: 'POST',
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        ...(bearerToken ? { authorization: `Bearer ${bearerToken}` } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TOKEN_REFRESH_TIMEOUT_MS),
+    });
+    if (!response.ok) throw new Error(`GitHub OAuth refresh failed with HTTP ${response.status}`);
+    return response.json() as Promise<TokenRefreshResponse>;
+  }
+}
+
+const defaultService = new VisualPreviewOAuthCredentialService();
+
+export function resolveVisualPreviewUploadToken(): Promise<string> {
+  return defaultService.resolveUploadToken();
+}
+
+export function refreshVisualPreviewOAuthCredential(force = false) {
+  return defaultService.refreshIfNeeded(force);
+}
+
+export function markVisualPreviewOAuthCredentialReauthRequired(errorCode: string): Promise<void> {
+  return defaultService.markReauthRequired(errorCode);
+}
diff --git a/packages/core/src/services/visualPreviewService.ts b/packages/core/src/services/visualPreviewService.ts
index 2000c90b6..183efa77e 100644
--- a/packages/core/src/services/visualPreviewService.ts
+++ b/packages/core/src/services/visualPreviewService.ts
@@ -346,12 +346,28 @@ export function renderVisualPreviewSection(
   return parts.join('\n\n');
 }
 
-export function renderVisualPreviewUploadFailureSection(evidence: VisualPreviewEvidence): string {
+export interface RenderVisualPreviewUploadFailureOptions {
+  authenticationFailure?: boolean;
+}
+
+export function renderVisualPreviewUploadFailureSection(
+  evidence: VisualPreviewEvidence,
+  options: RenderVisualPreviewUploadFailureOptions = {},
+): string {
   const parts = [
     VISUAL_PREVIEW_MARKER,
     '## Visual preview',
     'Preview media was generated but could not be uploaded to GitHub. No preview files were committed.'
   ];
+  if (options.authenticationFailure) {
+    parts.push('### Restore preview uploads');
+    parts.push(
+      'An instance administrator must open the ProPR Web UI, go to **Settings → Visual preview uploads**, '
+      + 'and select **Use my GitHub login**. If the current login is expired or ineligible, log out and sign in '
+      + 'with GitHub again first. If `GITHUB_VISUAL_PREVIEW_TOKEN` is set, remove or replace that override because '
+      + 'it takes precedence over the Web UI credential. Then request the visual preview again.',
+    );
+  }
   if (evidence.toolSuggestions.length > 0) {
     parts.push('### Suggested agent tools');
     parts.push(evidence.toolSuggestions
diff --git a/packages/core/test/visualPreviewOAuthCredentialService.test.ts b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
new file mode 100644
index 000000000..617d0e79a
--- /dev/null
+++ b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
@@ -0,0 +1,142 @@
+import assert from 'node:assert/strict';
+import { after, afterEach, beforeEach, test } from 'node:test';
+import knex, { type Knex } from 'knex';
+import { db as defaultDatabase } from '../src/db/connection.js';
+import { up as createVisualPreviewOAuthCredentials } from '../src/db/migrations/20260903000000_create_visual_preview_oauth_credentials.js';
+import {
+  VisualPreviewCredentialError,
+  VisualPreviewOAuthCredentialService,
+} from '../src/services/visualPreviewOAuthCredentialService.js';
+
+let database: Knex;
+
+beforeEach(async () => {
+  database = knex({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true });
+  await createVisualPreviewOAuthCredentials(database);
+});
+
+afterEach(async () => database.destroy());
+after(async () => defaultDatabase.destroy());
+
+function createService(fetchImpl: typeof fetch = fetch) {
+  return new VisualPreviewOAuthCredentialService(database, {
+    SYSTEM_TASK_SECRET: 'test-only-shared-encryption-secret',
+    GH_OAUTH_CLIENT_ID: 'client-id',
+    GH_OAUTH_CLIENT_SECRET: 'client-secret',
+  }, fetchImpl);
+}
+
+test('encrypts a captured administrator credential and resolves it for a worker', async () => {
+  const service = createService();
+  assert.equal(await service.captureFromLogin({
+    githubUserId: '1',
+    githubUsername: 'admin',
+    source: 'github',
+    accessToken: 'gho_access-secret',
+    refreshToken: 'ghr_refresh-secret',
+  }), true);
+
+  const row = await database('visual_preview_oauth_credentials').first();
+  assert.equal(String(row.access_token_encrypted).includes('gho_access-secret'), false);
+  assert.equal(String(row.refresh_token_encrypted).includes('ghr_refresh-secret'), false);
+  assert.equal(await service.resolveUploadToken(), 'gho_access-secret');
+});
+
+test('does not silently replace a healthy credential when another admin logs in', async () => {
+  const service = createService();
+  await service.captureFromLogin({
+    githubUserId: '1', githubUsername: 'first', source: 'github', accessToken: 'gho_first',
+  });
+  assert.equal(await service.captureFromLogin({
+    githubUserId: '2', githubUsername: 'second', source: 'github', accessToken: 'gho_second',
+  }), false);
+  assert.equal(await service.resolveUploadToken(), 'gho_first');
+
+  await service.replace({
+    githubUserId: '2', githubUsername: 'second', source: 'github', accessToken: 'gho_second',
+  });
+  assert.equal(await service.resolveUploadToken(), 'gho_second');
+});
+
+test('refreshes an expiring OAuth grant and rotates both persisted tokens', async () => {
+  let refreshBody: Record<string, string> | undefined;
+  const service = createService((async (_input, init) => {
+    refreshBody = JSON.parse(String(init?.body)) as Record<string, string>;
+    return Response.json({
+      access_token: 'gho_rotated-access',
+      refresh_token: 'ghr_rotated-refresh',
+      expires_in: 28_800,
+      refresh_token_expires_in: 15_897_600,
+    });
+  }) as typeof fetch);
+  await service.replace({
+    githubUserId: '1',
+    githubUsername: 'admin',
+    source: 'github',
+    accessToken: 'gho_old-access',
+    refreshToken: 'ghr_old-refresh',
+    accessTokenExpiresAt: Date.now() + 30_000,
+  });
+
+  assert.equal(await service.refreshIfNeeded(), 'refreshed');
+  assert.equal(refreshBody?.refresh_token, 'ghr_old-refresh');
+  assert.equal(await service.resolveUploadToken(), 'gho_rotated-access');
+  const row = await database('visual_preview_oauth_credentials').first();
+  assert.equal(String(row.refresh_token_encrypted).includes('ghr_rotated-refresh'), false);
+  assert.ok(row.last_refreshed_at);
+});
+
+test('marks an unrecoverable refresh failure for administrator reconnection', async () => {
+  const service = createService((async () => Response.json({ error: 'bad_refresh_token' })) as typeof fetch);
+  await service.replace({
+    githubUserId: '1',
+    githubUsername: 'admin',
+    source: 'github',
+    accessToken: 'gho_old-access',
+    refreshToken: 'ghr_old-refresh',
+    accessTokenExpiresAt: Date.now() - 1,
+  });
+
+  assert.equal(await service.refreshIfNeeded(), 'reauth-required');
+  await assert.rejects(
+    service.resolveUploadToken(),
+    (error: unknown) => error instanceof VisualPreviewCredentialError
+      && error.code === 'VISUAL_PREVIEW_AUTH_REAUTH_REQUIRED',
+  );
+});
+
+test('serializes refreshes across service instances sharing SQLite', async () => {
+  let refreshRequests = 0;
+  const fetchImpl = (async () => {
+    refreshRequests += 1;
+    await new Promise(resolve => setTimeout(resolve, 50));
+    return Response.json({
+      access_token: 'gho_once-access',
+      refresh_token: 'ghr_once-refresh',
+      expires_in: 28_800,
+      refresh_token_expires_in: 15_897_600,
+    });
+  }) as typeof fetch;
+  const first = createService(fetchImpl);
+  const second = createService(fetchImpl);
+  await first.replace({
+    githubUserId: '1',
+    githubUsername: 'admin',
+    source: 'github',
+    accessToken: 'gho_old-access',
+    refreshToken: 'ghr_old-refresh',
+    accessTokenExpiresAt: Date.now() + 30_000,
+  });
+
+  await Promise.all([first.refreshIfNeeded(), second.refreshIfNeeded()]);
+  assert.equal(refreshRequests, 1);
+  assert.equal(await second.resolveUploadToken(), 'gho_once-access');
+});
+
+test('rejects GitHub App tokens before storing them', async () => {
+  const service = createService();
+  await assert.rejects(service.replace({
+    githubUserId: '1', githubUsername: 'admin', source: 'github', accessToken: 'ghs_installation',
+  }), /GitHub App tokens are not supported/);
+  assert.equal((await service.getStatus()).status, 'missing');
+});
diff --git a/packages/core/test/visualPreviewService.test.ts b/packages/core/test/visualPreviewService.test.ts
index 1dc39e952..c95d01de7 100644
--- a/packages/core/test/visualPreviewService.test.ts
+++ b/packages/core/test/visualPreviewService.test.ts
@@ -121,6 +121,9 @@ test('renders upload-ready local media without committed-file fallbacks', async
   assert.match(failure, /could not be uploaded to GitHub/);
   assert.match(failure, /No preview files were committed/);
   assert.doesNotMatch(failure, /desktop view\.png/);
+  const authenticationFailure = renderVisualPreviewUploadFailureSection(evidence, { authenticationFailure: true });
+  assert.match(authenticationFailure, /Settings → Visual preview uploads/);
+  assert.match(authenticationFailure, /Use my GitHub login/);
   assert.equal(appendVisualPreviewSection(`Before\n\n${VISUAL_PREVIEW_SLOT}\n\nAfter`, failure), `Before\n\n${failure}\n\nAfter`);
 });
 
diff --git a/propr-ui/src/api/visualPreviewAuthApi.ts b/propr-ui/src/api/visualPreviewAuthApi.ts
new file mode 100644
index 000000000..4f11887f3
--- /dev/null
+++ b/propr-ui/src/api/visualPreviewAuthApi.ts
@@ -0,0 +1,41 @@
+import { API_BASE_URL, apiFetch, handleApiResponse } from './apiClient';
+
+export type VisualPreviewAuthStatusValue = 'active' | 'reauth_required' | 'missing';
+
+export interface VisualPreviewAuthStatus {
+  configured: boolean;
+  source?: 'github' | 'connect' | 'environment';
+  status: VisualPreviewAuthStatusValue;
+  githubUsername?: string;
+  currentUsername?: string;
+  canUseCurrentLogin: boolean;
+  accessTokenExpiresAt?: number;
+  refreshTokenExpiresAt?: number;
+  lastErrorCode?: string;
+  updatedAt?: string;
+}
+
+export async function getVisualPreviewAuthStatus(): Promise<VisualPreviewAuthStatus> {
+  const response = await apiFetch(`${API_BASE_URL}/api/config/visual-preview-auth`, {
+    credentials: 'include',
+  });
+  await handleApiResponse(response);
+  return response.json();
+}
+
+export async function connectCurrentGitHubLoginForVisualPreviews(): Promise<VisualPreviewAuthStatus> {
+  const response = await apiFetch(`${API_BASE_URL}/api/config/visual-preview-auth`, {
+    method: 'POST',
+    credentials: 'include',
+  }, { replayMutationAfterTokenRefresh: true });
+  await handleApiResponse(response);
+  return response.json();
+}
+
+export async function disconnectVisualPreviewAuth(): Promise<void> {
+  const response = await apiFetch(`${API_BASE_URL}/api/config/visual-preview-auth`, {
+    method: 'DELETE',
+    credentials: 'include',
+  }, { replayMutationAfterTokenRefresh: true });
+  await handleApiResponse(response);
+}
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
new file mode 100644
index 000000000..53fcc57cf
--- /dev/null
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
@@ -0,0 +1,77 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import VisualPreviewAuthSection from './VisualPreviewAuthSection';
+import {
+  disconnectVisualPreviewAuth,
+  getVisualPreviewAuthStatus,
+  connectCurrentGitHubLoginForVisualPreviews,
+} from '../../api/visualPreviewAuthApi';
+import { logout } from '../../api/proprApi';
+
+vi.mock('../../api/visualPreviewAuthApi', () => ({
+  disconnectVisualPreviewAuth: vi.fn(),
+  getVisualPreviewAuthStatus: vi.fn(),
+  connectCurrentGitHubLoginForVisualPreviews: vi.fn(),
+}));
+vi.mock('../../api/proprApi', () => ({ logout: vi.fn() }));
+
+const getStatus = vi.mocked(getVisualPreviewAuthStatus);
+const useCurrentLogin = vi.mocked(connectCurrentGitHubLoginForVisualPreviews);
+
+describe('VisualPreviewAuthSection', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    getStatus.mockResolvedValue({
+      configured: false,
+      status: 'missing',
+      currentUsername: 'admin',
+      canUseCurrentLogin: true,
+    });
+  });
+
+  it('connects the current administrator GitHub login', async () => {
+    useCurrentLogin.mockResolvedValue({
+      configured: true,
+      source: 'github',
+      status: 'active',
+      githubUsername: 'admin',
+      currentUsername: 'admin',
+      canUseCurrentLogin: true,
+    });
+    render(<VisualPreviewAuthSection />);
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Use my GitHub login' }));
+    await waitFor(() => expect(useCurrentLogin).toHaveBeenCalledOnce());
+    expect(await screen.findByText(/Uploads use the GitHub login for @admin/)).toBeInTheDocument();
+  });
+
+  it('offers a fresh GitHub sign-in when the session token is incompatible', async () => {
+    getStatus.mockResolvedValue({
+      configured: true,
+      source: 'github',
+      status: 'reauth_required',
+      githubUsername: 'admin',
+      currentUsername: 'admin',
+      canUseCurrentLogin: true,
+    });
+    render(<VisualPreviewAuthSection />);
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Sign in with GitHub again' }));
+    expect(logout).toHaveBeenCalledOnce();
+  });
+
+  it('shows environment-managed credentials without replacement controls', async () => {
+    getStatus.mockResolvedValue({
+      configured: true,
+      source: 'environment',
+      status: 'active',
+      currentUsername: 'admin',
+      canUseCurrentLogin: true,
+    });
+    render(<VisualPreviewAuthSection />);
+
+    expect(await screen.findByText(/server-managed credential/)).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Use my GitHub login' })).not.toBeInTheDocument();
+    expect(disconnectVisualPreviewAuth).not.toHaveBeenCalled();
+  });
+});
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
new file mode 100644
index 000000000..0c710f399
--- /dev/null
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
@@ -0,0 +1,134 @@
+import React, { useCallback, useEffect, useState } from 'react';
+import { Check, LoaderCircle, LogIn, Unplug } from 'lucide-react';
+import { logout } from '../../api/proprApi';
+import {
+  disconnectVisualPreviewAuth,
+  getVisualPreviewAuthStatus,
+  connectCurrentGitHubLoginForVisualPreviews,
+  type VisualPreviewAuthStatus,
+} from '../../api/visualPreviewAuthApi';
+
+function statusDescription(status: VisualPreviewAuthStatus | null): string {
+  if (status?.source === 'environment') {
+    return status.status === 'active'
+      ? 'A server-managed credential is configured through GITHUB_VISUAL_PREVIEW_TOKEN.'
+      : 'GITHUB_VISUAL_PREVIEW_TOKEN is set but is not a supported upload credential. Remove or replace it and restart the worker.';
+  }
+  if (status?.status === 'active' && status.githubUsername) {
+    return `Uploads use the GitHub login for @${status.githubUsername}. Expiring OAuth credentials are refreshed automatically.`;
+  }
+  return 'Connect an administrator GitHub login so background workers can attach generated screenshots and videos to pull requests.';
+}
+
+const VisualPreviewAuthSection: React.FC = () => {
+  const [status, setStatus] = useState<VisualPreviewAuthStatus | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const load = useCallback(async () => {
+    try {
+      setStatus(await getVisualPreviewAuthStatus());
+      setError(null);
+    } catch (requestError) {
+      setError((requestError as Error).message);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => { void load(); }, [load]);
+
+  const connect = async () => {
+    setSaving(true);
+    setError(null);
+    try {
+      setStatus(await connectCurrentGitHubLoginForVisualPreviews());
+    } catch (requestError) {
+      setError((requestError as Error).message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const disconnect = async () => {
+    setSaving(true);
+    setError(null);
+    try {
+      await disconnectVisualPreviewAuth();
+      await load();
+    } catch (requestError) {
+      setError((requestError as Error).message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="border-t border-gray-200 pt-6 text-xs text-gray-500">
+        Loading visual preview upload status...
+      </div>
+    );
+  }
+
+  const active = status?.status === 'active';
+  const environmentManaged = status?.source === 'environment';
+
+  return (
+    <div className="border-t border-gray-200 pt-6">
+      <div className="mb-2 flex items-center justify-between gap-3">
+        <h4 className="text-[10px] font-bold uppercase tracking-wider text-gray-500">Visual preview uploads</h4>
+        <span className={`flex items-center gap-1.5 text-[11px] ${active ? 'text-green-700' : 'text-amber-700'}`}>
+          <span className={`h-1.5 w-1.5 rounded-full ${active ? 'bg-green-500' : 'bg-amber-500'}`} />
+          {active ? 'Connected' : status?.status === 'reauth_required' ? 'Reconnect required' : 'Not connected'}
+        </span>
+      </div>
+
+      <p className="text-xs leading-5 text-gray-600">
+        {statusDescription(status)}
+      </p>
+
+      {!environmentManaged && (
+        <div className="mt-3 flex flex-wrap items-center gap-2">
+          {status?.canUseCurrentLogin && status.status !== 'reauth_required' ? (
+            <button
+              type="button"
+              onClick={() => void connect()}
+              disabled={saving}
+              className="inline-flex items-center gap-1.5 rounded bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800 disabled:opacity-50"
+            >
+              {saving ? <LoaderCircle size={13} className="animate-spin" /> : <Check size={13} />}
+              Use my GitHub login
+            </button>
+          ) : (
+            <button
+              type="button"
+              onClick={() => { void logout(); }}
+              disabled={saving}
+              className="inline-flex items-center gap-1.5 rounded bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800 disabled:opacity-50"
+            >
+              <LogIn size={13} />
+              Sign in with GitHub again
+            </button>
+          )}
+          {status?.configured && (
+            <button
+              type="button"
+              onClick={() => void disconnect()}
+              disabled={saving}
+              className="inline-flex items-center gap-1.5 rounded border border-gray-300 px-3 py-1.5 text-xs font-medium text-gray-600 hover:bg-gray-50 disabled:opacity-50"
+            >
+              <Unplug size={13} />
+              Disconnect
+            </button>
+          )}
+        </div>
+      )}
+
+      {error && <p className="mt-2 text-xs text-red-600">{error}</p>}
+    </div>
+  );
+};
+
+export default VisualPreviewAuthSection;
diff --git a/propr-ui/src/pages/SettingsPage/index.tsx b/propr-ui/src/pages/SettingsPage/index.tsx
index 526c6e478..8b92b0d49 100644
--- a/propr-ui/src/pages/SettingsPage/index.tsx
+++ b/propr-ui/src/pages/SettingsPage/index.tsx
@@ -11,6 +11,7 @@ import { useSettingsState } from './useSettingsState';
 import { useDemoMode } from '../../contexts/DemoModeContext';
 import { useCurrentUser, userHasPermission } from '../../contexts/AuthContext';
 import NotificationSettingsSection from './NotificationSettingsSection';
+import VisualPreviewAuthSection from './VisualPreviewAuthSection';
 
 const AdminSettingsPage: React.FC = () => {
   const { isDemoMode } = useDemoMode();
@@ -145,6 +146,8 @@ const AdminSettingsPage: React.FC = () => {
           <div className="space-y-6">
             <NotificationSettingsSection />
 
+            <VisualPreviewAuthSection />
+
             <div className="border-t border-gray-200" />
 
             <TagListSection
diff --git a/src/github/visualPreviewAttachments.ts b/src/github/visualPreviewAttachments.ts
index ea65ed95b..8ed35da23 100644
--- a/src/github/visualPreviewAttachments.ts
+++ b/src/github/visualPreviewAttachments.ts
@@ -1,8 +1,14 @@
 import { execa } from 'execa';
 import {
   appendVisualPreviewSection,
+  isSupportedVisualPreviewUploadToken,
+  isVisualPreviewCredentialError,
+  markVisualPreviewOAuthCredentialReauthRequired,
   redactSecrets,
   renderVisualPreviewSection,
+  resolveVisualPreviewUploadToken as resolveStoredVisualPreviewUploadToken,
+  VisualPreviewCredentialError,
+  VISUAL_PREVIEW_UPLOAD_TOKEN_ENV,
   type VisualPreviewEvidence
 } from '@propr/core';
 
@@ -14,20 +20,46 @@ interface AttachmentCommandOptions {
 
 export type AttachmentCommandRunner = (options: AttachmentCommandOptions) => Promise<{ stdout: string }>;
 
-export const VISUAL_PREVIEW_UPLOAD_TOKEN_ENV = 'GITHUB_VISUAL_PREVIEW_TOKEN';
+export { VISUAL_PREVIEW_UPLOAD_TOKEN_ENV };
+
+export class VisualPreviewUploadAuthenticationError extends Error {
+  readonly code = 'VISUAL_PREVIEW_AUTH_REJECTED';
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'VisualPreviewUploadAuthenticationError';
+  }
+}
+
+export function isVisualPreviewUploadAuthenticationError(error: unknown): boolean {
+  return isVisualPreviewCredentialError(error) || error instanceof VisualPreviewUploadAuthenticationError || (
+    error instanceof Error
+    && 'code' in error
+    && typeof (error as { code?: unknown }).code === 'string'
+    && (error as { code: string }).code.startsWith('VISUAL_PREVIEW_AUTH_')
+  );
+}
 
 /**
  * GitHub's user-attachment endpoint does not accept GitHub App installation
  * tokens. Keep this credential separate from the installation token used for
  * normal API requests and git operations.
  */
-export function resolveVisualPreviewUploadToken(
-  environment: NodeJS.ProcessEnv = process.env
-): string {
+export async function resolveVisualPreviewUploadToken(
+  environment?: NodeJS.ProcessEnv
+): Promise<string> {
+  if (!environment) return resolveStoredVisualPreviewUploadToken();
   const token = environment[VISUAL_PREVIEW_UPLOAD_TOKEN_ENV]?.trim();
-  if (token) return token;
+  if (token && isSupportedVisualPreviewUploadToken(token)) return token;
+  if (token) {
+    throw new VisualPreviewCredentialError(
+      'VISUAL_PREVIEW_AUTH_UNSUPPORTED',
+      `${VISUAL_PREVIEW_UPLOAD_TOKEN_ENV} is not a GitHub OAuth or personal access token supported by attachment uploads.`,
+    );
+  }
 
-  throw new Error(
+  throw new VisualPreviewCredentialError(
+    'VISUAL_PREVIEW_AUTH_MISSING',
     `${VISUAL_PREVIEW_UPLOAD_TOKEN_ENV} is not configured; GitHub attachment uploads require `
     + 'an OAuth token, classic personal access token, or fine-grained personal access token '
     + 'for a user with write access to the repository. GitHub App installation tokens cannot upload attachments.'
@@ -55,9 +87,19 @@ const runAttachmentCommand: AttachmentCommandRunner = async ({ args, authToken,
       : typeof commandError.stderr === 'string' && commandError.stderr.trim()
         ? redactSecrets(commandError.stderr.trim()).replace(/\s+/g, ' ').slice(0, 1000)
         : '';
-    const wrappedError = new Error(
-      `GitHub CLI could not upload visual preview attachments${detail ? `: ${detail}` : ''}`
-    ) as Error & { stdout?: string };
+    const message = `GitHub CLI could not upload visual preview attachments${detail ? `: ${detail}` : ''}`;
+    const authFailure = /unsupported authentication type|bad credentials|authentication failed|http 401|requires authentication|not logged in/i.test(detail);
+    if (authFailure) {
+      try {
+        await markVisualPreviewOAuthCredentialReauthRequired('github_rejected_token');
+      } catch {
+        // Preserve the original upload error. The Settings status can recover
+        // once database access is restored.
+      }
+    }
+    const wrappedError = (authFailure
+      ? new VisualPreviewUploadAuthenticationError(message)
+      : new Error(message)) as Error & { stdout?: string };
     const stdout = commandError.stdout;
     if (typeof stdout === 'string') wrappedError.stdout = stdout;
     throw wrappedError;
@@ -114,7 +156,7 @@ export async function publishPullRequestVisualPreviews(options: PublishPullReque
       '--body', bodyWithLocalPreviews(options),
       ...attachmentArguments(options.evidence)
     ],
-    authToken: options.authToken ?? resolveVisualPreviewUploadToken(),
+    authToken: options.authToken ?? await resolveVisualPreviewUploadToken(),
     cwd: options.worktreePath
   });
   const response = await options.octokit.request<{ data: { body?: string } }>('GET /repos/{owner}/{repo}/pulls/{pull_number}', {
@@ -159,7 +201,7 @@ export async function publishPullRequestCommentVisualPreviews(
         '--body', bodyWithLocalPreviews(options),
         ...attachmentArguments(options.evidence)
       ],
-      authToken: options.authToken ?? resolveVisualPreviewUploadToken(),
+      authToken: options.authToken ?? await resolveVisualPreviewUploadToken(),
       cwd: options.worktreePath
     });
     const commentUrl = result.stdout.trim().split('\n').find(line => line.includes('#issuecomment-')) || result.stdout.trim();
@@ -174,18 +216,31 @@ export async function publishPullRequestCommentVisualPreviews(
     });
     assertUploadedBodyHasNoLocalPaths(response.data.body, options.evidence);
 
+    const updatedStartingComment = await options.octokit.request<{ data: { html_url: string; body?: string } }>(
+      'PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}',
+      {
+        owner: options.owner,
+        repo: options.repo,
+        comment_id: options.startingCommentId,
+        body: response.data.body
+      }
+    );
+
     try {
       await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
         owner: options.owner,
         repo: options.repo,
-        comment_id: options.startingCommentId
+        comment_id: publishedCommentId
       });
     } catch {
-      // The attached completion comment is already published. Leaving the
-      // transient work comment is preferable to posting the completion twice.
+      // The bot-owned completion comment is already updated. Leaving the
+      // temporary uploader comment is preferable to losing the preview.
     }
 
-    return { html_url: commentUrl, body: response.data.body };
+    return {
+      html_url: updatedStartingComment.data.html_url,
+      body: updatedStartingComment.data.body || response.data.body
+    };
   } catch (error) {
     publishedCommentId ||= parseCommentId(typeof (error as { stdout?: unknown })?.stdout === 'string'
       ? (error as { stdout: string }).stdout
diff --git a/src/jobs/issueJobHelpers.ts b/src/jobs/issueJobHelpers.ts
index 2c60883d8..b94e5d915 100644
--- a/src/jobs/issueJobHelpers.ts
+++ b/src/jobs/issueJobHelpers.ts
@@ -25,7 +25,10 @@ export {
     type GenericErrorOptions
 } from './errorHandlers.js';
 import type { ClaudeCodeResponse, IssueJobData, JobResult, WorkerStateManager, WorktreeInfo, CommitResult, RepoValidationResult } from '@propr/core';
-import { publishPullRequestVisualPreviews } from '../github/visualPreviewAttachments.js';
+import {
+    isVisualPreviewUploadAuthenticationError,
+    publishPullRequestVisualPreviews,
+} from '../github/visualPreviewAttachments.js';
 
 export type RepoValidation = RepoValidationResult;
 
@@ -267,7 +270,10 @@ Comment on this PR to request refinements — the AI agent monitors comments and
                         owner: issueRef.repoOwner,
                         repo: issueRef.repoName,
                         pull_number: prResponse.data.number,
-                        body: appendVisualPreviewSection(basePrBody, renderVisualPreviewUploadFailureSection(visualPreview.evidence))
+                        body: appendVisualPreviewSection(basePrBody, renderVisualPreviewUploadFailureSection(
+                            visualPreview.evidence,
+                            { authenticationFailure: isVisualPreviewUploadAuthenticationError(previewError) }
+                        ))
                     });
                 } catch (fallbackError) {
                     correlatedLogger.warn({ prNumber: prResponse.data.number, error: (fallbackError as Error).message }, 'Could not publish the text-only visual preview upload explanation');
diff --git a/src/jobs/prCommentPostExecution.ts b/src/jobs/prCommentPostExecution.ts
index bcb4cfe4d..cb3732a6a 100644
--- a/src/jobs/prCommentPostExecution.ts
+++ b/src/jobs/prCommentPostExecution.ts
@@ -31,7 +31,10 @@ import { markReviewFindingsProcessed } from './reviewCommentGatherer.js';
 import type { AIReviewComment } from './reviewCommentGatherer.js';
 import { resolveUltrafixHistoryMeta } from './ultrafixJobHelpers.js';
 import type { GitHubToken } from './githubTypes.js';
-import { publishPullRequestCommentVisualPreviews } from '../github/visualPreviewAttachments.js';
+import {
+    isVisualPreviewUploadAuthenticationError,
+    publishPullRequestCommentVisualPreviews,
+} from '../github/visualPreviewAttachments.js';
 
 interface PostExecutionState {
     octokit: Awaited<ReturnType<typeof getAuthenticatedOctokit>> | null;
@@ -195,7 +198,10 @@ async function publishCompletionComment(options: CompletionCommentPublicationOpt
             owner: repoOwner,
             repo: repoName,
             comment_id: state.startingWorkComment.data.id,
-            body: appendVisualPreviewSection(prCommentTemplate, renderVisualPreviewUploadFailureSection(visualPreviewEvidence))
+            body: appendVisualPreviewSection(prCommentTemplate, renderVisualPreviewUploadFailureSection(
+                visualPreviewEvidence,
+                { authenticationFailure: isVisualPreviewUploadAuthenticationError(previewError) }
+            ))
         }) as Promise<{ data: { html_url: string; body?: string } }>;
     }
 }
diff --git a/test/visualPreviewAttachments.test.ts b/test/visualPreviewAttachments.test.ts
index 6b0e56dc4..cf4183d34 100644
--- a/test/visualPreviewAttachments.test.ts
+++ b/test/visualPreviewAttachments.test.ts
@@ -6,7 +6,8 @@ process.env.PROPR_DEMO_MODE = 'true';
 const [{ db }, {
   publishPullRequestCommentVisualPreviews,
   publishPullRequestVisualPreviews,
-  resolveVisualPreviewUploadToken
+  resolveVisualPreviewUploadToken,
+  isVisualPreviewUploadAuthenticationError
 }] = await Promise.all([
   import('@propr/core'),
   import('../src/github/visualPreviewAttachments.js')
@@ -26,17 +27,21 @@ const evidence = {
   toolSuggestions: []
 };
 
-test('resolves the dedicated visual preview upload credential', () => {
-  assert.equal(resolveVisualPreviewUploadToken({
+test('resolves the dedicated visual preview upload credential', async () => {
+  assert.equal(await resolveVisualPreviewUploadToken({
     GITHUB_VISUAL_PREVIEW_TOKEN: '  gho_preview-token  '
   }), 'gho_preview-token');
 });
 
-test('explains why the GitHub App credential cannot be used for attachments', () => {
-  assert.throws(
-    () => resolveVisualPreviewUploadToken({}),
-    /GitHub App installation tokens cannot upload attachments/
-  );
+test('explains why the GitHub App credential cannot be used for attachments', async () => {
+  let caught: unknown;
+  try {
+    await resolveVisualPreviewUploadToken({});
+  } catch (error) {
+    caught = error;
+  }
+  assert.match((caught as Error).message, /GitHub App installation tokens cannot upload attachments/);
+  assert.equal(isVisualPreviewUploadAuthenticationError(caught), true);
 });
 
 test('edits a pull request with uploaded visual preview attachments', async () => {
@@ -88,7 +93,7 @@ test('rejects a pull request upload when GitHub leaves a local path in the body'
   }), /did not replace a local visual preview path/);
 });
 
-test('publishes an attached completion comment before removing the transient work comment', async () => {
+test('copies uploaded media into the bot-owned work comment and removes the uploader comment', async () => {
   const requests: Array<{ endpoint: string; options: Record<string, unknown> }> = [];
   const published = await publishPullRequestCommentVisualPreviews({
     owner: 'integry',
@@ -102,6 +107,12 @@ test('publishes an attached completion comment before removing the transient wor
     octokit: {
       request: async <T>(endpoint: string, options: Record<string, unknown>) => {
         requests.push({ endpoint, options });
+        if (endpoint.startsWith('PATCH ')) {
+          return { data: {
+            html_url: 'https://github.com/integry/propr/pull/42#issuecomment-100',
+            body: 'Follow-up complete with uploaded URL'
+          } } as T;
+        }
         return { data: { body: 'Follow-up complete with uploaded URL' } } as T;
       }
     },
@@ -109,14 +120,16 @@ test('publishes an attached completion comment before removing the transient wor
   });
 
   assert.deepEqual(published, {
-    html_url: 'https://github.com/integry/propr/pull/42#issuecomment-200',
+    html_url: 'https://github.com/integry/propr/pull/42#issuecomment-100',
     body: 'Follow-up complete with uploaded URL'
   });
   assert.deepEqual(requests.map(request => request.endpoint), [
     'GET /repos/{owner}/{repo}/issues/comments/{comment_id}',
+    'PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}',
     'DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}'
   ]);
   assert.equal(requests[1].options.comment_id, 100);
+  assert.equal(requests[2].options.comment_id, 200);
 });
 
 test('removes a partially published attachment comment before surfacing upload failure', async () => {

From 2c1f62e439a7c13528532e3ddcb7cf3b6dbefd01 Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 23:11:10 +0200
Subject: [PATCH 12/18] fix(previews): retain GitHub user OAuth tokens

---
 packages/api/auth.ts                          |  8 ++++--
 packages/api/test/authRedirect.test.ts        | 28 +++++++++++++++++++
 .../visualPreviewOAuthCredentialService.ts    |  7 +++--
 ...isualPreviewOAuthCredentialService.test.ts | 19 +++++++++++--
 4 files changed, 55 insertions(+), 7 deletions(-)

diff --git a/packages/api/auth.ts b/packages/api/auth.ts
index e7e21ed8a..ed58cba95 100644
--- a/packages/api/auth.ts
+++ b/packages/api/auth.ts
@@ -185,9 +185,11 @@ export function setupAuth(app: Express, demoModeAtStartup = isDemoMode()): Socke
     }
     const engineMiddleware: RequestHandler[] = [];
 
-    // Keep unauthenticated OAuth/session endpoints bounded independently from
-    // the general API quota. Register this before session and Passport work.
-    app.use('/api/auth', createAuthRequestRateLimiter());
+    // Keep OAuth starts and callbacks bounded independently from the general
+    // API quota. Session checks, logout, and auth metadata remain covered by
+    // the general API limiter and must not exhaust the much smaller OAuth
+    // bucket during normal UI use.
+    app.use('/api/auth/github', createAuthRequestRateLimiter());
 
     if (!demoModeAtStartup) {
         // Create Redis client for session store
diff --git a/packages/api/test/authRedirect.test.ts b/packages/api/test/authRedirect.test.ts
index 900b3e446..6d4dc12a4 100644
--- a/packages/api/test/authRedirect.test.ts
+++ b/packages/api/test/authRedirect.test.ts
@@ -10,6 +10,8 @@ const originalFrontendUrl = process.env.FRONTEND_URL;
 const originalCookieDomain = process.env.COOKIE_DOMAIN;
 const originalApiPublicUrl = process.env.API_PUBLIC_URL;
 const originalRedirectAllowedHosts = process.env.AUTH_REDIRECT_ALLOWED_HOSTS;
+const originalAuthRateLimitMax = process.env.PROPR_AUTH_RATE_LIMIT_MAX;
+const originalAuthRateLimitWindowMs = process.env.PROPR_AUTH_RATE_LIMIT_WINDOW_MS;
 
 async function fetchFromApp(app: express.Express, path: string): Promise<globalThis.Response> {
   const server = app.listen(0, '127.0.0.1');
@@ -35,12 +37,38 @@ afterEach(() => {
   else process.env.API_PUBLIC_URL = originalApiPublicUrl;
   if (originalRedirectAllowedHosts === undefined) delete process.env.AUTH_REDIRECT_ALLOWED_HOSTS;
   else process.env.AUTH_REDIRECT_ALLOWED_HOSTS = originalRedirectAllowedHosts;
+  if (originalAuthRateLimitMax === undefined) delete process.env.PROPR_AUTH_RATE_LIMIT_MAX;
+  else process.env.PROPR_AUTH_RATE_LIMIT_MAX = originalAuthRateLimitMax;
+  if (originalAuthRateLimitWindowMs === undefined) delete process.env.PROPR_AUTH_RATE_LIMIT_WINDOW_MS;
+  else process.env.PROPR_AUTH_RATE_LIMIT_WINDOW_MS = originalAuthRateLimitWindowMs;
 });
 
 after(async () => {
   await closeConnection();
 });
 
+test('ordinary auth metadata requests do not consume the OAuth attempt quota', async () => {
+  process.env.PROPR_DEMO_MODE = 'true';
+  process.env.FRONTEND_URL = 'https://app.example.com';
+  process.env.PROPR_AUTH_RATE_LIMIT_MAX = '2';
+  process.env.PROPR_AUTH_RATE_LIMIT_WINDOW_MS = '60000';
+  const app = express();
+  setupAuth(app);
+
+  for (let index = 0; index < 5; index += 1) {
+    assert.equal((await fetchFromApp(app, '/api/auth/demo-mode')).status, 200);
+  }
+
+  assert.equal((await fetchFromApp(app, '/api/auth/github')).status, 302);
+  assert.equal((await fetchFromApp(app, '/api/auth/github/callback')).status, 302);
+  const limited = await fetchFromApp(app, '/api/auth/github');
+  assert.equal(limited.status, 429);
+  assert.deepEqual(await limited.json(), {
+    code: 'RATE_LIMIT_EXCEEDED',
+    error: 'Too many requests. Please try again later.',
+  });
+});
+
 test('auth redirect allowlist treats FRONTEND_URL as exact host only', async () => {
   process.env.PROPR_DEMO_MODE = 'true';
   process.env.FRONTEND_URL = 'https://app.example.com';
diff --git a/packages/core/src/services/visualPreviewOAuthCredentialService.ts b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
index 10392ceb4..5d6782dcb 100644
--- a/packages/core/src/services/visualPreviewOAuthCredentialService.ts
+++ b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
@@ -14,7 +14,10 @@ const TOKEN_REFRESH_TIMEOUT_MS = 20_000;
 const REFRESH_LEASE_MS = TOKEN_REFRESH_TIMEOUT_MS + 5_000;
 const REFRESH_LEASE_POLL_MS = 100;
 const ENCRYPTION_CONTEXT = 'propr:visual-preview-oauth:v1';
-const SUPPORTED_TOKEN_PATTERN = /^(?:gho_|ghp_|github_pat_)/;
+// GitHub App user access tokens (`ghu_`) act on behalf of the signed-in user
+// and are distinct from installation tokens (`ghs_`). Hosted/Connect login
+// commonly returns the former, including a refresh token when expiry is on.
+const SUPPORTED_TOKEN_PATTERN = /^(?:gho_|ghu_|ghp_|github_pat_)/;
 
 export const VISUAL_PREVIEW_UPLOAD_TOKEN_ENV = 'GITHUB_VISUAL_PREVIEW_TOKEN';
 export const VISUAL_PREVIEW_CREDENTIAL_KEY_ENV = 'PROPR_CREDENTIAL_ENCRYPTION_KEY';
@@ -162,7 +165,7 @@ function assertSupportedToken(token: string): string {
   if (!isSupportedVisualPreviewUploadToken(normalized)) {
     throw new VisualPreviewCredentialError(
       'VISUAL_PREVIEW_AUTH_UNSUPPORTED',
-      'GitHub visual-preview uploads require an OAuth token or personal access token; GitHub App tokens are not supported.',
+      'GitHub visual-preview uploads require a user OAuth token or personal access token; GitHub App installation tokens are not supported.',
     );
   }
   return normalized;
diff --git a/packages/core/test/visualPreviewOAuthCredentialService.test.ts b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
index 617d0e79a..4e4409cb5 100644
--- a/packages/core/test/visualPreviewOAuthCredentialService.test.ts
+++ b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
@@ -42,6 +42,21 @@ test('encrypts a captured administrator credential and resolves it for a worker'
   assert.equal(await service.resolveUploadToken(), 'gho_access-secret');
 });
 
+test('accepts an expiring GitHub App user access token from browser login', async () => {
+  const service = createService();
+  assert.equal(await service.captureFromLogin({
+    githubUserId: '1',
+    githubUsername: 'admin',
+    source: 'github',
+    accessToken: 'ghu_user-access-secret',
+    refreshToken: 'ghr_refresh-secret',
+    accessTokenExpiresAt: Date.now() + 28_800_000,
+  }), true);
+
+  assert.equal(await service.resolveUploadToken(), 'ghu_user-access-secret');
+  assert.equal((await service.getStatus()).status, 'active');
+});
+
 test('does not silently replace a healthy credential when another admin logs in', async () => {
   const service = createService();
   await service.captureFromLogin({
@@ -133,10 +148,10 @@ test('serializes refreshes across service instances sharing SQLite', async () =>
   assert.equal(await second.resolveUploadToken(), 'gho_once-access');
 });
 
-test('rejects GitHub App tokens before storing them', async () => {
+test('rejects GitHub App installation tokens before storing them', async () => {
   const service = createService();
   await assert.rejects(service.replace({
     githubUserId: '1', githubUsername: 'admin', source: 'github', accessToken: 'ghs_installation',
-  }), /GitHub App tokens are not supported/);
+  }), /GitHub App installation tokens are not supported/);
   assert.equal((await service.getStatus()).status, 'missing');
 });

From 7912ae67845357751b8c910108b0441d5b4fa8af Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 23:39:52 +0200
Subject: [PATCH 13/18] fix(previews): reject GitHub App upload tokens

---
 .env.example                                  | 12 +++----
 docs/docs/features/visual-previews.md         | 23 ++++++------
 .../operations/configuration-reference.md     |  4 +--
 .../api/routes/visualPreviewAuthRoutes.ts     | 22 +++++++++---
 .../api/test/visualPreviewAuthRoutes.test.ts  | 35 ++++++++++++++++++-
 .../visualPreviewOAuthCredentialService.ts    | 10 +++---
 .../core/src/services/visualPreviewService.ts |  8 +++--
 ...isualPreviewOAuthCredentialService.test.ts | 27 ++++----------
 .../core/test/visualPreviewService.test.ts    |  2 ++
 propr-ui/src/api/visualPreviewAuthApi.ts      |  1 +
 .../VisualPreviewAuthSection.test.tsx         | 35 +++++++++++++++++--
 .../SettingsPage/VisualPreviewAuthSection.tsx | 11 ++++--
 12 files changed, 133 insertions(+), 57 deletions(-)

diff --git a/.env.example b/.env.example
index 85c151e7d..75dd8f9be 100644
--- a/.env.example
+++ b/.env.example
@@ -47,11 +47,11 @@ GITHUB_EVENT_INTAKE_MODE=routing_websocket
 # GH_AUTH_MODE=relay
 
 # Advanced override for the GitHub user credential used only for visual-preview
-# attachment uploads. Normally an instance administrator's Web UI login is
-# captured, encrypted in SQLite, and refreshed automatically. Set this only to
-# override that flow with an OAuth token, classic PAT, or fine-grained PAT for a
-# user with write access to each target repository. GitHub App installation
-# tokens are not supported by the attachment endpoint.
+# attachment uploads. An administrator's Web UI login can be captured when it
+# uses a GitHub OAuth App token (`gho_`); GitHub's uploader rejects GitHub App
+# user (`ghu_`) and installation (`ghs_`) tokens. Set this to override the Web
+# UI flow with an OAuth App token, classic PAT, or fine-grained PAT for a user
+# with write access to each target repository.
 # GITHUB_VISUAL_PREVIEW_TOKEN=your_oauth_or_personal_access_token
 # Optional dedicated encryption secret for the persisted OAuth grant. The
 # default is SYSTEM_TASK_SECRET, falling back to SESSION_SECRET. Keep the value
@@ -373,7 +373,7 @@ DASHBOARD_API_PORT=4000
 # PROPR_ALLOW_INSECURE_LOCAL_WEB_PUSH=false
 
 # Per-client request quotas. Defaults protect the general API (600/minute),
-# OAuth/session endpoints (30/15 minutes), and direct webhooks (300/minute).
+# OAuth initiation/callback endpoints (30/15 minutes), and direct webhooks (300/minute).
 # Values must be positive integers; raise them only for measured trusted traffic.
 # PROPR_API_RATE_LIMIT_MAX=600
 # PROPR_API_RATE_LIMIT_WINDOW_MS=60000
diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
index b613897b7..5ec96c940 100644
--- a/docs/docs/features/visual-previews.md
+++ b/docs/docs/features/visual-previews.md
@@ -8,22 +8,25 @@ Visual previews let a ProPR implementation show its user-visible result directly
 
 The feature is opt-in per repository. Existing repository configurations remain disabled after an upgrade.
 
-GitHub attachment uploads require a user OAuth credential because GitHub App
-installation tokens cannot upload user attachments. When an instance
-administrator signs in to the Web UI, ProPR automatically stores their compatible
-OAuth credential, encrypted in the shared database. Open **Settings → Visual
-preview uploads** to see which account is connected or explicitly replace it
-with the current administrator login. Normal GitHub API, commit, and pull-request
-operations continue to use the GitHub App installation token.
+GitHub attachment uploads require a GitHub OAuth App token (`gho_`) or personal
+access token. GitHub's uploader rejects both GitHub App user (`ghu_`) and
+installation (`ghs_`) tokens even though those tokens work for normal GitHub API
+operations. When an instance administrator's Web UI login is backed by a GitHub
+OAuth App, ProPR automatically stores its compatible credential, encrypted in
+the shared database. Open **Settings → Visual preview uploads** to see which
+account is connected or explicitly replace it with the current administrator
+login. Normal GitHub API, commit, and pull-request operations continue to use
+the GitHub App installation token.
 
 Expiring OAuth credentials are refreshed on API startup and every 30 minutes
 while the stack is running. Each successful refresh rotates the access and
 refresh tokens, so an administrator does not need to sign in every six months
 while the stack can keep refreshing them. A revoked grant, an expired unused
 refresh token, or a changed encryption secret requires a fresh administrator
-login. `GITHUB_VISUAL_PREVIEW_TOKEN` remains available as an advanced environment
-override for an OAuth token, classic PAT, or fine-grained PAT belonging to a user
-with write access to every preview-enabled repository.
+login. If Web UI login uses a GitHub App rather than an OAuth App, configure
+`GITHUB_VISUAL_PREVIEW_TOKEN` with an OAuth App token, classic PAT, or
+fine-grained PAT belonging to a user with write access to every preview-enabled
+repository.
 
 ## Configure A Repository
 
diff --git a/docs/docs/operations/configuration-reference.md b/docs/docs/operations/configuration-reference.md
index 5d988b86a..21b98fcdf 100644
--- a/docs/docs/operations/configuration-reference.md
+++ b/docs/docs/operations/configuration-reference.md
@@ -22,7 +22,7 @@ The backend authenticates to GitHub in one of three modes — `demo`, `relay`, o
 | `HOST_GH_PRIVATE_KEY` | Unset | Absolute host path to the `.pem`. The CLI/launcher bind-mounts it read-only into the app containers and overrides `GH_PRIVATE_KEY_PATH`, so the key can live anywhere on the host. No `~`. | App mode via the `propr` CLI or launcher. |
 | `GH_OAUTH_CLIENT_ID` / `GH_OAUTH_CLIENT_SECRET` | Placeholders | GitHub OAuth App credentials for Web UI login. | Always, for UI login. |
 | `GH_OAUTH_CALLBACK_URL` | Derived: `<API host>/api/auth/github/callback` | OAuth callback served by the API. Leave commented so tunnel-mode derivation wins; an active localhost value is used as-is even in tunnel mode. Register the URL — derived or explicit — in your GitHub OAuth App. | Override only. |
-| `GITHUB_VISUAL_PREVIEW_TOKEN` | Unset | Advanced override for the OAuth token, classic PAT, or fine-grained PAT used only to upload visual-preview attachments. Normally an administrator login supplies an encrypted, automatically refreshed OAuth credential through **Settings → Visual preview uploads**. GitHub's user-attachment endpoint rejects App installation tokens. | Optional override. |
+| `GITHUB_VISUAL_PREVIEW_TOKEN` | Unset | Advanced override for the OAuth App token (`gho_`), classic PAT, or fine-grained PAT used only to upload visual-preview attachments. An administrator login can supply the encrypted credential when Web UI login uses a GitHub OAuth App. GitHub's uploader rejects GitHub App user (`ghu_`) and installation (`ghs_`) tokens. | Optional override. |
 | `PROPR_CREDENTIAL_ENCRYPTION_KEY` | `SYSTEM_TASK_SECRET`, then `SESSION_SECRET` | Optional dedicated secret used to encrypt the persisted visual-preview OAuth grant. It must be identical in the API and worker containers and remain stable across restarts; changing it requires reconnecting the GitHub login. | Optional security isolation. |
 | `SESSION_SECRET` | Placeholder | Signs browser session cookies. | Always. |
 | `ENABLE_BEARER_AUTH` | `true` (any value except `false` enables it) | Bearer token auth for the CLI. Set `false` to allow session login only. | Optional. |
@@ -46,7 +46,7 @@ The backend authenticates to GitHub in one of three modes — `demo`, `relay`, o
 | `WEB_PUSH_RETRY_BASE_MS` / `WEB_PUSH_RETRY_CAP_MS` | `30000` / `900000` | Base and cap for exponential retry scheduling after throttling, provider errors, or network failures. | Optional Web Push tuning. |
 | `PROPR_ALLOW_INSECURE_LOCAL_WEB_PUSH` | `false` | Requests loopback HTTP Push enrollment for isolated local development. It is honored only outside production when `API_PUBLIC_URL` is unset/local or has a loopback host, and can be changed without migrating the stable schema. | Local browser development only. |
 | `PROPR_API_RATE_LIMIT_MAX` / `PROPR_API_RATE_LIMIT_WINDOW_MS` | `600` / `60000` | Per-client quota and window (milliseconds) for all `/api` requests. | Optional tuning. |
-| `PROPR_AUTH_RATE_LIMIT_MAX` / `PROPR_AUTH_RATE_LIMIT_WINDOW_MS` | `30` / `900000` | Additional, tighter per-client quota for OAuth and session endpoints. | Optional tuning. |
+| `PROPR_AUTH_RATE_LIMIT_MAX` / `PROPR_AUTH_RATE_LIMIT_WINDOW_MS` | `30` / `900000` | Additional, tighter per-client quota for OAuth initiation and callback endpoints. | Optional tuning. |
 | `PROPR_WEBHOOK_RATE_LIMIT_MAX` / `PROPR_WEBHOOK_RATE_LIMIT_WINDOW_MS` | `300` / `60000` | Per-client quota for direct webhook requests, applied before body parsing and signature verification. | Optional tuning in direct-webhook mode. |
 | `PROPR_TRUSTED_PROXY_PEERS` | Unset; launcher-managed tunnel: reserved `self` mode | Comma-separated immediate proxy IPs, CIDRs, or `proxy-addr` names whose forwarded client IP and protocol are trusted. Unset ignores forwarding headers. The launcher injects `self` only for its managed sidecar sharing the API network namespace. Its broad `uniquelocal` name is accepted only when `API_PORT` is explicitly loopback-bound. | Reverse-proxy deployments; injected automatically for the managed tunnel. |
 | `LOG_LEVEL` | `info` | Log verbosity across services. | Optional. |
diff --git a/packages/api/routes/visualPreviewAuthRoutes.ts b/packages/api/routes/visualPreviewAuthRoutes.ts
index 67b5e8c46..d225a0f10 100644
--- a/packages/api/routes/visualPreviewAuthRoutes.ts
+++ b/packages/api/routes/visualPreviewAuthRoutes.ts
@@ -12,6 +12,16 @@ interface VisualPreviewAuthRoutesDeps {
   service?: VisualPreviewOAuthCredentialService;
 }
 
+type CurrentLoginTokenType = 'supported' | 'github_app_user' | 'unsupported' | 'missing';
+
+function currentLoginTokenType(accessToken?: string): CurrentLoginTokenType {
+  const token = accessToken?.trim();
+  if (!token) return 'missing';
+  if (isSupportedVisualPreviewUploadToken(token)) return 'supported';
+  if (token.startsWith('ghu_')) return 'github_app_user';
+  return 'unsupported';
+}
+
 function sendFailure(error: unknown, res: Response): void {
   console.error('[visual-preview] Credential administration failed:', error);
   res.status(500).json({
@@ -25,12 +35,12 @@ export function createVisualPreviewAuthRoutes({
 }: VisualPreviewAuthRoutesDeps = {}) {
   async function getStatus(req: Request, res: Response): Promise<void> {
     try {
+      const loginTokenType = currentLoginTokenType(req.user?.accessToken);
       res.json({
         ...await service.getStatus(),
         currentUsername: req.user?.username,
-        canUseCurrentLogin: Boolean(
-          req.user?.accessToken && isSupportedVisualPreviewUploadToken(req.user.accessToken),
-        ),
+        currentLoginTokenType: loginTokenType,
+        canUseCurrentLogin: loginTokenType === 'supported',
       });
     } catch (error) {
       sendFailure(error, res);
@@ -40,8 +50,11 @@ export function createVisualPreviewAuthRoutes({
   async function useCurrentLogin(req: Request, res: Response): Promise<void> {
     const credential = req.user ? visualPreviewCredentialFromUser(req.user) : null;
     if (!credential) {
+      const githubAppUserToken = currentLoginTokenType(req.user?.accessToken) === 'github_app_user';
       res.status(409).json({
-        error: 'The current GitHub login did not provide an OAuth token supported by GitHub media uploads. Log out and sign in again.',
+        error: githubAppUserToken
+          ? 'The current login uses a GitHub App user token, which GitHub attachment uploads reject. Configure Web UI login with a GitHub OAuth App or use GITHUB_VISUAL_PREVIEW_TOKEN with an OAuth App token or PAT.'
+          : 'The current GitHub login did not provide an OAuth App token or personal access token supported by GitHub attachment uploads.',
         code: 'VISUAL_PREVIEW_LOGIN_TOKEN_UNSUPPORTED',
       });
       return;
@@ -51,6 +64,7 @@ export function createVisualPreviewAuthRoutes({
       res.json({
         ...await service.getStatus(),
         currentUsername: req.user?.username,
+        currentLoginTokenType: 'supported',
         canUseCurrentLogin: true,
       });
     } catch (error) {
diff --git a/packages/api/test/visualPreviewAuthRoutes.test.ts b/packages/api/test/visualPreviewAuthRoutes.test.ts
index ea2450f23..771120add 100644
--- a/packages/api/test/visualPreviewAuthRoutes.test.ts
+++ b/packages/api/test/visualPreviewAuthRoutes.test.ts
@@ -64,6 +64,7 @@ test('returns visual-preview auth status without exposing stored token material'
     status: 'active',
     githubUsername: 'admin',
     currentUsername: 'admin',
+    currentLoginTokenType: 'supported',
     canUseCurrentLogin: true,
   });
   assert.doesNotMatch(JSON.stringify(recorder.getBody()), /browser-secret/);
@@ -94,7 +95,39 @@ test('rejects a current login whose GitHub token cannot upload attachments', asy
 
   assert.equal(recorder.getStatus(), 409);
   assert.deepEqual(recorder.getBody(), {
-    error: 'The current GitHub login did not provide an OAuth token supported by GitHub media uploads. Log out and sign in again.',
+    error: 'The current GitHub login did not provide an OAuth App token or personal access token supported by GitHub attachment uploads.',
+    code: 'VISUAL_PREVIEW_LOGIN_TOKEN_UNSUPPORTED',
+  });
+});
+
+test('identifies a GitHub App user login without exposing its token', async () => {
+  const service = {
+    getStatus: async () => ({ configured: false, status: 'missing' as const }),
+  } as unknown as VisualPreviewOAuthCredentialService;
+  const routes = createVisualPreviewAuthRoutes({ service });
+  const recorder = responseRecorder();
+
+  await routes.getStatus({ user: user({ accessToken: 'ghu_browser-secret' }) } as Request, recorder.response);
+
+  assert.deepEqual(recorder.getBody(), {
+    configured: false,
+    status: 'missing',
+    currentUsername: 'admin',
+    currentLoginTokenType: 'github_app_user',
+    canUseCurrentLogin: false,
+  });
+  assert.doesNotMatch(JSON.stringify(recorder.getBody()), /browser-secret/);
+});
+
+test('explains why a GitHub App user login cannot be selected', async () => {
+  const routes = createVisualPreviewAuthRoutes({ service: {} as VisualPreviewOAuthCredentialService });
+  const recorder = responseRecorder();
+
+  await routes.useCurrentLogin({ user: user({ accessToken: 'ghu_browser-secret' }) } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 409);
+  assert.deepEqual(recorder.getBody(), {
+    error: 'The current login uses a GitHub App user token, which GitHub attachment uploads reject. Configure Web UI login with a GitHub OAuth App or use GITHUB_VISUAL_PREVIEW_TOKEN with an OAuth App token or PAT.',
     code: 'VISUAL_PREVIEW_LOGIN_TOKEN_UNSUPPORTED',
   });
 });
diff --git a/packages/core/src/services/visualPreviewOAuthCredentialService.ts b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
index 5d6782dcb..11593b62c 100644
--- a/packages/core/src/services/visualPreviewOAuthCredentialService.ts
+++ b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
@@ -14,10 +14,10 @@ const TOKEN_REFRESH_TIMEOUT_MS = 20_000;
 const REFRESH_LEASE_MS = TOKEN_REFRESH_TIMEOUT_MS + 5_000;
 const REFRESH_LEASE_POLL_MS = 100;
 const ENCRYPTION_CONTEXT = 'propr:visual-preview-oauth:v1';
-// GitHub App user access tokens (`ghu_`) act on behalf of the signed-in user
-// and are distinct from installation tokens (`ghs_`). Hosted/Connect login
-// commonly returns the former, including a refresh token when expiry is on.
-const SUPPORTED_TOKEN_PATTERN = /^(?:gho_|ghu_|ghp_|github_pat_)/;
+// GitHub CLI's attachment uploader accepts OAuth App and personal-access
+// tokens. It deliberately rejects both GitHub App user (`ghu_`) and
+// installation (`ghs_`) tokens before making an upload request.
+const SUPPORTED_TOKEN_PATTERN = /^(?:gho_|ghp_|github_pat_)/;
 
 export const VISUAL_PREVIEW_UPLOAD_TOKEN_ENV = 'GITHUB_VISUAL_PREVIEW_TOKEN';
 export const VISUAL_PREVIEW_CREDENTIAL_KEY_ENV = 'PROPR_CREDENTIAL_ENCRYPTION_KEY';
@@ -165,7 +165,7 @@ function assertSupportedToken(token: string): string {
   if (!isSupportedVisualPreviewUploadToken(normalized)) {
     throw new VisualPreviewCredentialError(
       'VISUAL_PREVIEW_AUTH_UNSUPPORTED',
-      'GitHub visual-preview uploads require a user OAuth token or personal access token; GitHub App installation tokens are not supported.',
+      'GitHub visual-preview uploads require an OAuth App token or personal access token; GitHub App user and installation tokens are not supported.',
     );
   }
   return normalized;
diff --git a/packages/core/src/services/visualPreviewService.ts b/packages/core/src/services/visualPreviewService.ts
index 183efa77e..0fdef7abe 100644
--- a/packages/core/src/services/visualPreviewService.ts
+++ b/packages/core/src/services/visualPreviewService.ts
@@ -363,9 +363,11 @@ export function renderVisualPreviewUploadFailureSection(
     parts.push('### Restore preview uploads');
     parts.push(
       'An instance administrator must open the ProPR Web UI, go to **Settings → Visual preview uploads**, '
-      + 'and select **Use my GitHub login**. If the current login is expired or ineligible, log out and sign in '
-      + 'with GitHub again first. If `GITHUB_VISUAL_PREVIEW_TOKEN` is set, remove or replace that override because '
-      + 'it takes precedence over the Web UI credential. Then request the visual preview again.',
+      + 'and select **Use my GitHub login** when that login is backed by a GitHub OAuth App token (`gho_`). '
+      + 'GitHub rejects GitHub App user (`ghu_`) and installation (`ghs_`) tokens for attachments. If the current '
+      + 'login is ineligible, configure Web UI login with a GitHub OAuth App, or set `GITHUB_VISUAL_PREVIEW_TOKEN` '
+      + 'to an OAuth App token, classic PAT, or fine-grained PAT with repository write access. The environment '
+      + 'override takes precedence over the Web UI credential. Then request the visual preview again.',
     );
   }
   if (evidence.toolSuggestions.length > 0) {
diff --git a/packages/core/test/visualPreviewOAuthCredentialService.test.ts b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
index 4e4409cb5..493fcf57d 100644
--- a/packages/core/test/visualPreviewOAuthCredentialService.test.ts
+++ b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
@@ -42,19 +42,14 @@ test('encrypts a captured administrator credential and resolves it for a worker'
   assert.equal(await service.resolveUploadToken(), 'gho_access-secret');
 });
 
-test('accepts an expiring GitHub App user access token from browser login', async () => {
+test('rejects GitHub App user and installation tokens before storing them', async () => {
   const service = createService();
-  assert.equal(await service.captureFromLogin({
-    githubUserId: '1',
-    githubUsername: 'admin',
-    source: 'github',
-    accessToken: 'ghu_user-access-secret',
-    refreshToken: 'ghr_refresh-secret',
-    accessTokenExpiresAt: Date.now() + 28_800_000,
-  }), true);
-
-  assert.equal(await service.resolveUploadToken(), 'ghu_user-access-secret');
-  assert.equal((await service.getStatus()).status, 'active');
+  for (const accessToken of ['ghu_user-access', 'ghs_installation']) {
+    await assert.rejects(service.replace({
+      githubUserId: '1', githubUsername: 'admin', source: 'github', accessToken,
+    }), /GitHub App user and installation tokens are not supported/);
+  }
+  assert.equal((await service.getStatus()).status, 'missing');
 });
 
 test('does not silently replace a healthy credential when another admin logs in', async () => {
@@ -147,11 +142,3 @@ test('serializes refreshes across service instances sharing SQLite', async () =>
   assert.equal(refreshRequests, 1);
   assert.equal(await second.resolveUploadToken(), 'gho_once-access');
 });
-
-test('rejects GitHub App installation tokens before storing them', async () => {
-  const service = createService();
-  await assert.rejects(service.replace({
-    githubUserId: '1', githubUsername: 'admin', source: 'github', accessToken: 'ghs_installation',
-  }), /GitHub App installation tokens are not supported/);
-  assert.equal((await service.getStatus()).status, 'missing');
-});
diff --git a/packages/core/test/visualPreviewService.test.ts b/packages/core/test/visualPreviewService.test.ts
index c95d01de7..b77da9bfe 100644
--- a/packages/core/test/visualPreviewService.test.ts
+++ b/packages/core/test/visualPreviewService.test.ts
@@ -124,6 +124,8 @@ test('renders upload-ready local media without committed-file fallbacks', async
   const authenticationFailure = renderVisualPreviewUploadFailureSection(evidence, { authenticationFailure: true });
   assert.match(authenticationFailure, /Settings → Visual preview uploads/);
   assert.match(authenticationFailure, /Use my GitHub login/);
+  assert.match(authenticationFailure, /GitHub App user \(`ghu_`\)/);
+  assert.match(authenticationFailure, /GitHub OAuth App token \(`gho_`\)/);
   assert.equal(appendVisualPreviewSection(`Before\n\n${VISUAL_PREVIEW_SLOT}\n\nAfter`, failure), `Before\n\n${failure}\n\nAfter`);
 });
 
diff --git a/propr-ui/src/api/visualPreviewAuthApi.ts b/propr-ui/src/api/visualPreviewAuthApi.ts
index 4f11887f3..eba1a4e5e 100644
--- a/propr-ui/src/api/visualPreviewAuthApi.ts
+++ b/propr-ui/src/api/visualPreviewAuthApi.ts
@@ -8,6 +8,7 @@ export interface VisualPreviewAuthStatus {
   status: VisualPreviewAuthStatusValue;
   githubUsername?: string;
   currentUsername?: string;
+  currentLoginTokenType?: 'supported' | 'github_app_user' | 'unsupported' | 'missing';
   canUseCurrentLogin: boolean;
   accessTokenExpiresAt?: number;
   refreshTokenExpiresAt?: number;
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
index 53fcc57cf..47b85eb95 100644
--- a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
@@ -25,6 +25,7 @@ describe('VisualPreviewAuthSection', () => {
       configured: false,
       status: 'missing',
       currentUsername: 'admin',
+      currentLoginTokenType: 'supported',
       canUseCurrentLogin: true,
     });
   });
@@ -36,6 +37,7 @@ describe('VisualPreviewAuthSection', () => {
       status: 'active',
       githubUsername: 'admin',
       currentUsername: 'admin',
+      currentLoginTokenType: 'supported',
       canUseCurrentLogin: true,
     });
     render(<VisualPreviewAuthSection />);
@@ -45,19 +47,45 @@ describe('VisualPreviewAuthSection', () => {
     expect(await screen.findByText(/Uploads use the GitHub login for @admin/)).toBeInTheDocument();
   });
 
-  it('offers a fresh GitHub sign-in when the session token is incompatible', async () => {
+  it('replaces an expired stored credential when the current login is supported', async () => {
     getStatus.mockResolvedValue({
       configured: true,
       source: 'github',
       status: 'reauth_required',
       githubUsername: 'admin',
       currentUsername: 'admin',
+      currentLoginTokenType: 'supported',
       canUseCurrentLogin: true,
     });
+    useCurrentLogin.mockResolvedValue({
+      configured: true,
+      source: 'github',
+      status: 'active',
+      githubUsername: 'admin',
+      currentUsername: 'admin',
+      currentLoginTokenType: 'supported',
+      canUseCurrentLogin: true,
+    });
+    render(<VisualPreviewAuthSection />);
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Use my GitHub login' }));
+    await waitFor(() => expect(useCurrentLogin).toHaveBeenCalledOnce());
+    expect(logout).not.toHaveBeenCalled();
+  });
+
+  it('explains that repeating a GitHub App login cannot enable uploads', async () => {
+    getStatus.mockResolvedValue({
+      configured: false,
+      status: 'missing',
+      currentUsername: 'admin',
+      currentLoginTokenType: 'github_app_user',
+      canUseCurrentLogin: false,
+    });
     render(<VisualPreviewAuthSection />);
 
-    fireEvent.click(await screen.findByRole('button', { name: 'Sign in with GitHub again' }));
-    expect(logout).toHaveBeenCalledOnce();
+    expect(await screen.findByText(/GitHub App user token/)).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Use my GitHub login' })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Sign in with GitHub again' })).not.toBeInTheDocument();
   });
 
   it('shows environment-managed credentials without replacement controls', async () => {
@@ -66,6 +94,7 @@ describe('VisualPreviewAuthSection', () => {
       source: 'environment',
       status: 'active',
       currentUsername: 'admin',
+      currentLoginTokenType: 'github_app_user',
       canUseCurrentLogin: true,
     });
     render(<VisualPreviewAuthSection />);
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
index 0c710f399..fd7dfd248 100644
--- a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
@@ -17,6 +17,9 @@ function statusDescription(status: VisualPreviewAuthStatus | null): string {
   if (status?.status === 'active' && status.githubUsername) {
     return `Uploads use the GitHub login for @${status.githubUsername}. Expiring OAuth credentials are refreshed automatically.`;
   }
+  if (status?.currentLoginTokenType === 'github_app_user') {
+    return 'Your current login uses a GitHub App user token, which GitHub attachment uploads reject. Configure Web UI login with a GitHub OAuth App, or set GITHUB_VISUAL_PREVIEW_TOKEN to an OAuth App token or PAT.';
+  }
   return 'Connect an administrator GitHub login so background workers can attach generated screenshots and videos to pull requests.';
 }
 
@@ -74,6 +77,8 @@ const VisualPreviewAuthSection: React.FC = () => {
 
   const active = status?.status === 'active';
   const environmentManaged = status?.source === 'environment';
+  const canConnectCurrentLogin = !active && status?.canUseCurrentLogin;
+  const canRetryLogin = !active && status?.currentLoginTokenType !== 'github_app_user';
 
   return (
     <div className="border-t border-gray-200 pt-6">
@@ -91,7 +96,7 @@ const VisualPreviewAuthSection: React.FC = () => {
 
       {!environmentManaged && (
         <div className="mt-3 flex flex-wrap items-center gap-2">
-          {status?.canUseCurrentLogin && status.status !== 'reauth_required' ? (
+          {canConnectCurrentLogin ? (
             <button
               type="button"
               onClick={() => void connect()}
@@ -101,7 +106,7 @@ const VisualPreviewAuthSection: React.FC = () => {
               {saving ? <LoaderCircle size={13} className="animate-spin" /> : <Check size={13} />}
               Use my GitHub login
             </button>
-          ) : (
+          ) : canRetryLogin ? (
             <button
               type="button"
               onClick={() => { void logout(); }}
@@ -111,7 +116,7 @@ const VisualPreviewAuthSection: React.FC = () => {
               <LogIn size={13} />
               Sign in with GitHub again
             </button>
-          )}
+          ) : null}
           {status?.configured && (
             <button
               type="button"

From ec69434ba71eae8fa1b58a66db5827672cf8721d Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Thu, 3 Sep 2026 23:58:47 +0200
Subject: [PATCH 14/18] feat(previews): configure upload tokens without OAuth
 callbacks

---
 docs/docs/features/visual-previews.md         |  20 +-
 .../operations/configuration-reference.md     |   2 +-
 packages/api/routeRegistry.ts                 |   1 +
 .../api/routes/visualPreviewAuthRoutes.ts     | 115 +++++++++--
 packages/api/test/routeAuthorization.test.ts  |   1 +
 .../api/test/visualPreviewAuthRoutes.test.ts  |  86 ++++++++-
 packages/cli/src/api/index.ts                 |   6 +
 packages/cli/src/api/visualPreviewAuth.ts     |  21 +++
 .../cli/src/commands/setup/engine.test.ts     |  20 ++
 packages/cli/src/commands/setup/engine.ts     |  43 +++++
 .../cli/src/commands/setup/sequential.test.ts |   1 +
 .../visualPreviewOAuthCredentialService.ts    |   6 +-
 .../core/src/services/visualPreviewService.ts |   9 +-
 ...isualPreviewOAuthCredentialService.test.ts |  14 ++
 .../core/test/visualPreviewService.test.ts    |   4 +-
 propr-ui/src/api/visualPreviewAuthApi.ts      |  13 +-
 .../VisualPreviewAuthSection.test.tsx         |  32 +++-
 .../SettingsPage/VisualPreviewAuthSection.tsx | 178 ++++++++++++++----
 18 files changed, 498 insertions(+), 74 deletions(-)
 create mode 100644 packages/cli/src/api/visualPreviewAuth.ts

diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
index 5ec96c940..22d1c6b08 100644
--- a/docs/docs/features/visual-previews.md
+++ b/docs/docs/features/visual-previews.md
@@ -18,15 +18,27 @@ account is connected or explicitly replace it with the current administrator
 login. Normal GitHub API, commit, and pull-request operations continue to use
 the GitHub App installation token.
 
+When normal Web UI login uses a GitHub App, an administrator can instead paste
+a personal access token in **Settings → Visual preview uploads**. ProPR validates
+the token with GitHub and encrypts it before storing it. No CLI, callback URL, or
+service restart is required. The token must have access to every repository where
+preview media will be attached.
+
 Expiring OAuth credentials are refreshed on API startup and every 30 minutes
 while the stack is running. Each successful refresh rotates the access and
 refresh tokens, so an administrator does not need to sign in every six months
 while the stack can keep refreshing them. A revoked grant, an expired unused
 refresh token, or a changed encryption secret requires a fresh administrator
-login. If Web UI login uses a GitHub App rather than an OAuth App, configure
-`GITHUB_VISUAL_PREVIEW_TOKEN` with an OAuth App token, classic PAT, or
-fine-grained PAT belonging to a user with write access to every preview-enabled
-repository.
+login. Personal access tokens are not refreshable OAuth grants; replace a
+revoked or expired PAT in **Settings → Visual preview uploads**. As an advanced
+server-managed alternative, configure `GITHUB_VISUAL_PREVIEW_TOKEN` with an
+OAuth App token, classic PAT, or fine-grained PAT belonging to a user with write
+access to every preview-enabled repository.
+
+`propr setup` also reuses an upload-compatible token from an existing `gh` CLI
+session when no working preview credential is already configured. GitHub CLI
+does not expose a refresh token to ProPR, so an expired or revoked imported token
+must be replaced in Settings or re-imported by running setup again.
 
 ## Configure A Repository
 
diff --git a/docs/docs/operations/configuration-reference.md b/docs/docs/operations/configuration-reference.md
index 21b98fcdf..e5674d91a 100644
--- a/docs/docs/operations/configuration-reference.md
+++ b/docs/docs/operations/configuration-reference.md
@@ -22,7 +22,7 @@ The backend authenticates to GitHub in one of three modes — `demo`, `relay`, o
 | `HOST_GH_PRIVATE_KEY` | Unset | Absolute host path to the `.pem`. The CLI/launcher bind-mounts it read-only into the app containers and overrides `GH_PRIVATE_KEY_PATH`, so the key can live anywhere on the host. No `~`. | App mode via the `propr` CLI or launcher. |
 | `GH_OAUTH_CLIENT_ID` / `GH_OAUTH_CLIENT_SECRET` | Placeholders | GitHub OAuth App credentials for Web UI login. | Always, for UI login. |
 | `GH_OAUTH_CALLBACK_URL` | Derived: `<API host>/api/auth/github/callback` | OAuth callback served by the API. Leave commented so tunnel-mode derivation wins; an active localhost value is used as-is even in tunnel mode. Register the URL — derived or explicit — in your GitHub OAuth App. | Override only. |
-| `GITHUB_VISUAL_PREVIEW_TOKEN` | Unset | Advanced override for the OAuth App token (`gho_`), classic PAT, or fine-grained PAT used only to upload visual-preview attachments. An administrator login can supply the encrypted credential when Web UI login uses a GitHub OAuth App. GitHub's uploader rejects GitHub App user (`ghu_`) and installation (`ghs_`) tokens. | Optional override. |
+| `GITHUB_VISUAL_PREVIEW_TOKEN` | Unset | Advanced override for the OAuth App token (`gho_`), classic PAT, or fine-grained PAT used only to upload visual-preview attachments. Administrators can normally paste a PAT in Settings instead, and `propr setup` imports a compatible `gh` CLI token when available. GitHub's uploader rejects GitHub App user (`ghu_`) and installation (`ghs_`) tokens. | Optional override. |
 | `PROPR_CREDENTIAL_ENCRYPTION_KEY` | `SYSTEM_TASK_SECRET`, then `SESSION_SECRET` | Optional dedicated secret used to encrypt the persisted visual-preview OAuth grant. It must be identical in the API and worker containers and remain stable across restarts; changing it requires reconnecting the GitHub login. | Optional security isolation. |
 | `SESSION_SECRET` | Placeholder | Signs browser session cookies. | Always. |
 | `ENABLE_BEARER_AUTH` | `true` (any value except `false` enables it) | Bearer token auth for the CLI. Set `false` to allow session login only. | Optional. |
diff --git a/packages/api/routeRegistry.ts b/packages/api/routeRegistry.ts
index f3e79bfa1..89986b7c9 100644
--- a/packages/api/routeRegistry.ts
+++ b/packages/api/routeRegistry.ts
@@ -75,6 +75,7 @@ export function createManagementRouteEntries({
     ['get', '/api/config/agent-tank/detect', requireManageAgents, configRoutes.getAgentTankDetect],
     ['get', '/api/config/visual-preview-auth', requireManageSettings, visualPreviewAuthRoutes.getStatus],
     ['post', '/api/config/visual-preview-auth', requireManageSettings, visualPreviewAuthRoutes.useCurrentLogin],
+    ['put', '/api/config/visual-preview-auth/token', requireManageSettings, visualPreviewAuthRoutes.usePersonalAccessToken],
     ['delete', '/api/config/visual-preview-auth', requireManageSettings, visualPreviewAuthRoutes.disconnect],
 
     ['get', '/api/admin/members', requireManageMembers, adminRoutes.listMembers],
diff --git a/packages/api/routes/visualPreviewAuthRoutes.ts b/packages/api/routes/visualPreviewAuthRoutes.ts
index d225a0f10..8b0c47bdb 100644
--- a/packages/api/routes/visualPreviewAuthRoutes.ts
+++ b/packages/api/routes/visualPreviewAuthRoutes.ts
@@ -2,14 +2,20 @@ import type { Request, Response } from 'express';
 import {
   VisualPreviewOAuthCredentialService,
   isSupportedVisualPreviewUploadToken,
+  type VisualPreviewOAuthCredentialStatus,
 } from '@propr/core';
 import {
   visualPreviewCredentialFromUser,
   visualPreviewOAuthCredentialService,
 } from '../services/visualPreviewOAuth.js';
 
+const GITHUB_USER_URL = 'https://api.github.com/user';
+const GITHUB_REQUEST_TIMEOUT_MS = 20_000;
+const MAX_TOKEN_LENGTH = 512;
+
 interface VisualPreviewAuthRoutesDeps {
   service?: VisualPreviewOAuthCredentialService;
+  fetchImpl?: typeof fetch;
 }
 
 type CurrentLoginTokenType = 'supported' | 'github_app_user' | 'unsupported' | 'missing';
@@ -22,6 +28,16 @@ function currentLoginTokenType(accessToken?: string): CurrentLoginTokenType {
   return 'unsupported';
 }
 
+function statusResponse(req: Request, status: VisualPreviewOAuthCredentialStatus) {
+  const loginTokenType = currentLoginTokenType(req.user?.accessToken);
+  return {
+    ...status,
+    currentUsername: req.user?.username,
+    currentLoginTokenType: loginTokenType,
+    canUseCurrentLogin: loginTokenType === 'supported',
+  };
+}
+
 function sendFailure(error: unknown, res: Response): void {
   console.error('[visual-preview] Credential administration failed:', error);
   res.status(500).json({
@@ -30,18 +46,39 @@ function sendFailure(error: unknown, res: Response): void {
   });
 }
 
+function readSubmittedToken(req: Request): string | null {
+  const token = typeof req.body?.token === 'string' ? req.body.token.trim() : '';
+  if (!token || token.length > MAX_TOKEN_LENGTH || !isSupportedVisualPreviewUploadToken(token)) return null;
+  return token;
+}
+
+async function fetchGitHubIdentity(token: string, fetchImpl: typeof fetch): Promise<{
+  status: number;
+  id?: string;
+  username?: string;
+}> {
+  const response = await fetchImpl(GITHUB_USER_URL, {
+    headers: {
+      accept: 'application/vnd.github+json',
+      authorization: `Bearer ${token}`,
+      'user-agent': 'ProPR',
+      'x-github-api-version': '2022-11-28',
+    },
+    signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),
+  });
+  if (!response.ok) return { status: response.status };
+  const identity = await response.json() as { id?: number; login?: string };
+  if (!Number.isSafeInteger(identity.id) || !identity.login) return { status: 502 };
+  return { status: 200, id: String(identity.id), username: identity.login };
+}
+
 export function createVisualPreviewAuthRoutes({
   service = visualPreviewOAuthCredentialService,
+  fetchImpl = fetch,
 }: VisualPreviewAuthRoutesDeps = {}) {
   async function getStatus(req: Request, res: Response): Promise<void> {
     try {
-      const loginTokenType = currentLoginTokenType(req.user?.accessToken);
-      res.json({
-        ...await service.getStatus(),
-        currentUsername: req.user?.username,
-        currentLoginTokenType: loginTokenType,
-        canUseCurrentLogin: loginTokenType === 'supported',
-      });
+      res.json(statusResponse(req, await service.getStatus()));
     } catch (error) {
       sendFailure(error, res);
     }
@@ -53,7 +90,7 @@ export function createVisualPreviewAuthRoutes({
       const githubAppUserToken = currentLoginTokenType(req.user?.accessToken) === 'github_app_user';
       res.status(409).json({
         error: githubAppUserToken
-          ? 'The current login uses a GitHub App user token, which GitHub attachment uploads reject. Configure Web UI login with a GitHub OAuth App or use GITHUB_VISUAL_PREVIEW_TOKEN with an OAuth App token or PAT.'
+          ? 'The current login uses a GitHub App user token, which GitHub attachment uploads reject. Add a personal access token in Visual preview uploads instead.'
           : 'The current GitHub login did not provide an OAuth App token or personal access token supported by GitHub attachment uploads.',
         code: 'VISUAL_PREVIEW_LOGIN_TOKEN_UNSUPPORTED',
       });
@@ -61,13 +98,63 @@ export function createVisualPreviewAuthRoutes({
     }
     try {
       await service.replace(credential);
-      res.json({
-        ...await service.getStatus(),
-        currentUsername: req.user?.username,
-        currentLoginTokenType: 'supported',
-        canUseCurrentLogin: true,
+      res.json(statusResponse(req, await service.getStatus()));
+    } catch (error) {
+      sendFailure(error, res);
+    }
+  }
+
+  async function usePersonalAccessToken(req: Request, res: Response): Promise<void> {
+    const token = readSubmittedToken(req);
+    if (!token) {
+      res.status(400).json({
+        error: 'Enter a GitHub OAuth App token or personal access token (gho_, ghp_, or github_pat_). GitHub App tokens are not supported for attachment uploads.',
+        code: 'VISUAL_PREVIEW_TOKEN_UNSUPPORTED',
+      });
+      return;
+    }
+
+    try {
+      const currentStatus = await service.getStatus();
+      if (currentStatus.source === 'environment') {
+        res.status(409).json({
+          error: 'GITHUB_VISUAL_PREVIEW_TOKEN manages this credential. Remove the environment override and restart the stack before saving a token in Settings.',
+          code: 'VISUAL_PREVIEW_TOKEN_ENVIRONMENT_MANAGED',
+        });
+        return;
+      }
+
+      const identity = await fetchGitHubIdentity(token, fetchImpl);
+      if (identity.status === 401 || identity.status === 403) {
+        res.status(400).json({
+          error: 'GitHub rejected this token. Check that it is active and has access to the repositories where previews are uploaded.',
+          code: 'VISUAL_PREVIEW_TOKEN_INVALID',
+        });
+        return;
+      }
+      if (identity.status !== 200 || !identity.id || !identity.username) {
+        res.status(502).json({
+          error: 'GitHub could not validate this token. Please try again.',
+          code: 'VISUAL_PREVIEW_TOKEN_VALIDATION_FAILED',
+        });
+        return;
+      }
+
+      await service.replace({
+        githubUserId: identity.id,
+        githubUsername: identity.username,
+        source: 'static_token',
+        accessToken: token,
       });
+      res.json(statusResponse(req, await service.getStatus()));
     } catch (error) {
+      if (error instanceof TypeError || (error instanceof Error && error.name === 'TimeoutError')) {
+        res.status(502).json({
+          error: 'GitHub could not validate this token. Please try again.',
+          code: 'VISUAL_PREVIEW_TOKEN_VALIDATION_FAILED',
+        });
+        return;
+      }
       sendFailure(error, res);
     }
   }
@@ -81,5 +168,5 @@ export function createVisualPreviewAuthRoutes({
     }
   }
 
-  return { getStatus, useCurrentLogin, disconnect };
+  return { getStatus, useCurrentLogin, usePersonalAccessToken, disconnect };
 }
diff --git a/packages/api/test/routeAuthorization.test.ts b/packages/api/test/routeAuthorization.test.ts
index 2badfbf85..5da652019 100644
--- a/packages/api/test/routeAuthorization.test.ts
+++ b/packages/api/test/routeAuthorization.test.ts
@@ -85,6 +85,7 @@ const managementRequests = [
   ['GET', '/api/admin/members'],
   ['GET', '/api/config/visual-preview-auth'],
   ['POST', '/api/config/visual-preview-auth'],
+  ['PUT', '/api/config/visual-preview-auth/token'],
   ['DELETE', '/api/config/visual-preview-auth'],
   ['GET', '/api/agent-runtime/packages'],
   ['POST', '/api/agent-runtime/packages/verify'],
diff --git a/packages/api/test/visualPreviewAuthRoutes.test.ts b/packages/api/test/visualPreviewAuthRoutes.test.ts
index 771120add..3afbc6700 100644
--- a/packages/api/test/visualPreviewAuthRoutes.test.ts
+++ b/packages/api/test/visualPreviewAuthRoutes.test.ts
@@ -127,7 +127,91 @@ test('explains why a GitHub App user login cannot be selected', async () => {
 
   assert.equal(recorder.getStatus(), 409);
   assert.deepEqual(recorder.getBody(), {
-    error: 'The current login uses a GitHub App user token, which GitHub attachment uploads reject. Configure Web UI login with a GitHub OAuth App or use GITHUB_VISUAL_PREVIEW_TOKEN with an OAuth App token or PAT.',
+    error: 'The current login uses a GitHub App user token, which GitHub attachment uploads reject. Add a personal access token in Visual preview uploads instead.',
     code: 'VISUAL_PREVIEW_LOGIN_TOKEN_UNSUPPORTED',
   });
 });
+
+test('validates and stores a submitted personal access token without returning it', async () => {
+  let replaced: VisualPreviewOAuthCredentialInput | undefined;
+  let authorization = '';
+  const service = {
+    getStatus: async () => replaced
+      ? { configured: true, source: 'static_token' as const, status: 'active' as const, githubUsername: 'preview-bot' }
+      : { configured: false, status: 'missing' as const },
+    replace: async (credential: VisualPreviewOAuthCredentialInput) => { replaced = credential; },
+  } as unknown as VisualPreviewOAuthCredentialService;
+  const fetchImpl = (async (_input, init) => {
+    authorization = new Headers(init?.headers).get('authorization') || '';
+    return Response.json({ id: 456, login: 'preview-bot' });
+  }) as typeof fetch;
+  const routes = createVisualPreviewAuthRoutes({ service, fetchImpl });
+  const recorder = responseRecorder();
+
+  await routes.usePersonalAccessToken({
+    user: user({ accessToken: 'ghu_browser-secret' }),
+    body: { token: 'github_pat_preview-secret' },
+  } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 200);
+  assert.equal(authorization, 'Bearer github_pat_preview-secret');
+  assert.deepEqual(replaced, {
+    githubUserId: '456',
+    githubUsername: 'preview-bot',
+    source: 'static_token',
+    accessToken: 'github_pat_preview-secret',
+  });
+  assert.doesNotMatch(JSON.stringify(recorder.getBody()), /preview-secret/);
+});
+
+test('rejects unsupported submitted tokens before contacting GitHub', async () => {
+  let fetched = false;
+  const routes = createVisualPreviewAuthRoutes({
+    service: {} as VisualPreviewOAuthCredentialService,
+    fetchImpl: (async () => { fetched = true; return Response.json({}); }) as typeof fetch,
+  });
+  const recorder = responseRecorder();
+
+  await routes.usePersonalAccessToken({ body: { token: 'ghu_app-user-token' } } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 400);
+  assert.equal((recorder.getBody() as { code: string }).code, 'VISUAL_PREVIEW_TOKEN_UNSUPPORTED');
+  assert.equal(fetched, false);
+});
+
+test('does not replace an environment-managed preview token', async () => {
+  let fetched = false;
+  const service = {
+    getStatus: async () => ({ configured: true, source: 'environment' as const, status: 'active' as const }),
+  } as unknown as VisualPreviewOAuthCredentialService;
+  const routes = createVisualPreviewAuthRoutes({
+    service,
+    fetchImpl: (async () => { fetched = true; return Response.json({}); }) as typeof fetch,
+  });
+  const recorder = responseRecorder();
+
+  await routes.usePersonalAccessToken({ body: { token: 'ghp_preview-secret' } } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 409);
+  assert.equal((recorder.getBody() as { code: string }).code, 'VISUAL_PREVIEW_TOKEN_ENVIRONMENT_MANAGED');
+  assert.equal(fetched, false);
+});
+
+test('reports a token rejected by GitHub without storing it', async () => {
+  let replaced = false;
+  const service = {
+    getStatus: async () => ({ configured: false, status: 'missing' as const }),
+    replace: async () => { replaced = true; },
+  } as unknown as VisualPreviewOAuthCredentialService;
+  const routes = createVisualPreviewAuthRoutes({
+    service,
+    fetchImpl: (async () => new Response(null, { status: 401 })) as typeof fetch,
+  });
+  const recorder = responseRecorder();
+
+  await routes.usePersonalAccessToken({ body: { token: 'ghp_preview-secret' } } as Request, recorder.response);
+
+  assert.equal(recorder.getStatus(), 400);
+  assert.equal((recorder.getBody() as { code: string }).code, 'VISUAL_PREVIEW_TOKEN_INVALID');
+  assert.equal(replaced, false);
+});
diff --git a/packages/cli/src/api/index.ts b/packages/cli/src/api/index.ts
index dd4d116e7..3975e0a53 100644
--- a/packages/cli/src/api/index.ts
+++ b/packages/cli/src/api/index.ts
@@ -38,6 +38,12 @@ export {
   updateAgentRuntimePackages,
   verifyAgentRuntimePackages,
 } from './agentRuntime.js';
+
+export {
+  getVisualPreviewAuthStatus,
+  saveVisualPreviewUploadToken,
+} from './visualPreviewAuth.js';
+export type { VisualPreviewAuthStatus } from './visualPreviewAuth.js';
 export type {
   AgentRuntimeBuildStatus,
   AgentRuntimeImageVerification,
diff --git a/packages/cli/src/api/visualPreviewAuth.ts b/packages/cli/src/api/visualPreviewAuth.ts
new file mode 100644
index 000000000..2254d13d6
--- /dev/null
+++ b/packages/cli/src/api/visualPreviewAuth.ts
@@ -0,0 +1,21 @@
+import type { ApiClient } from './client.js';
+
+export interface VisualPreviewAuthStatus {
+  configured: boolean;
+  source?: 'github' | 'connect' | 'static_token' | 'environment';
+  status: 'active' | 'reauth_required' | 'missing';
+  githubUsername?: string;
+}
+
+export async function getVisualPreviewAuthStatus(client: ApiClient): Promise<VisualPreviewAuthStatus> {
+  return (await client.get<VisualPreviewAuthStatus>('/api/config/visual-preview-auth')).data;
+}
+
+export async function saveVisualPreviewUploadToken(
+  token: string,
+  client: ApiClient,
+): Promise<VisualPreviewAuthStatus> {
+  return (await client.put<VisualPreviewAuthStatus>('/api/config/visual-preview-auth/token', {
+    body: { token },
+  })).data;
+}
diff --git a/packages/cli/src/commands/setup/engine.test.ts b/packages/cli/src/commands/setup/engine.test.ts
index 014cc21ae..7e4998d6d 100644
--- a/packages/cli/src/commands/setup/engine.test.ts
+++ b/packages/cli/src/commands/setup/engine.test.ts
@@ -57,6 +57,7 @@ function mockActions(overrides: Partial<SetupActions> = {}): SetupActions {
     isStackRunning: async () => false,
     startStack: async () => undefined,
     checkBackendHealth: async () => ({ healthy: true, detail: "API healthy" }),
+    configureVisualPreviewCredential: async () => ({ status: 'already-configured' }),
     addRepository: async () => undefined,
     resolveUiUrl: async () => "http://localhost:3000",
     openUrl: async () => undefined,
@@ -98,6 +99,25 @@ test("re-running on an initialized stack leaves it intact and completes", async
   assert.equal(result.completed, true);
 });
 
+test("imports an upload-compatible gh token after the backend becomes healthy", async () => {
+  let configuredRoot: string | undefined;
+  const log: string[] = [];
+  const result = await runSetup({
+    root: "/stack",
+    reporter: { onLog: (line) => log.push(line) },
+    actions: mockActions({
+      configureVisualPreviewCredential: async (rootDir) => {
+        configuredRoot = rootDir;
+        return { status: 'configured', githubUsername: 'octocat' };
+      },
+    }),
+  });
+
+  assert.equal(result.completed, true);
+  assert.equal(configuredRoot, '/stack');
+  assert.ok(log.includes('visual previews: configured from the gh CLI session (@octocat)'));
+});
+
 test("an incomplete stack root (missing dirs) is re-scaffolded even when .env exists", async () => {
   let scaffolded = false;
   const result = await runSetup({
diff --git a/packages/cli/src/commands/setup/engine.ts b/packages/cli/src/commands/setup/engine.ts
index 15700eda6..0e5289566 100644
--- a/packages/cli/src/commands/setup/engine.ts
+++ b/packages/cli/src/commands/setup/engine.ts
@@ -335,6 +335,11 @@ export interface BackendHealth {
   accessFailure?: "unauthorized" | "forbidden";
 }
 
+export interface VisualPreviewCredentialSetupResult {
+  status: 'configured' | 'already-configured' | 'environment-managed' | 'missing' | 'unsupported';
+  githubUsername?: string;
+}
+
 /** Classify an HTTP access failure from the protected backend status route. */
 export function classifyBackendAccessError(error: unknown): BackendHealth | undefined {
   const httpStatus = (error as { status?: unknown } | null)?.status;
@@ -379,6 +384,8 @@ export interface SetupActions extends AgentSetupActions {
   isStackRunning(rootDir: string): Promise<boolean>;
   startStack(params: StartStackParams): Promise<void>;
   checkBackendHealth(params: BackendHealthParams): Promise<BackendHealth>;
+  /** Seed preview uploads from the authenticated gh CLI session when possible. */
+  configureVisualPreviewCredential(rootDir: string): Promise<VisualPreviewCredentialSetupResult>;
   addRepository(selection: RepoSelection, rootDir: string): Promise<void>;
   resolveUiUrl(rootDir: string): Promise<string>;
   /** Open `url` in the host's default browser (best-effort; may reject). */
@@ -573,6 +580,21 @@ export function createDefaultActions(configManager?: ConfigManager): SetupAction
       } while (Date.now() < deadline);
       return { healthy: false, detail: `backend not healthy within ${Math.round(timeoutMs / 1000)}s (${lastError})` };
     },
+    async configureVisualPreviewCredential(rootDir) {
+      const token = configManager?.getGithubToken()?.trim();
+      if (!token) return { status: 'missing' };
+      if (!/^(?:gho_|ghp_|github_pat_)/.test(token)) return { status: 'unsupported' };
+
+      const { getVisualPreviewAuthStatus, saveVisualPreviewUploadToken } = await import('../../api/visualPreviewAuth.js');
+      const client = await localApiClient(rootDir);
+      const current = await getVisualPreviewAuthStatus(client);
+      if (current.status === 'active') {
+        return { status: 'already-configured', githubUsername: current.githubUsername };
+      }
+      if (current.source === 'environment') return { status: 'environment-managed' };
+      const configured = await saveVisualPreviewUploadToken(token, client);
+      return { status: 'configured', githubUsername: configured.githubUsername };
+    },
     async addRepository({ fullName, alias, baseBranch }, rootDir) {
       const { addRepo } = await import("../../api/repos.js");
       // Point the client at this stack's API port rather than the saved remote.
@@ -1349,6 +1371,27 @@ export async function runSetup(options: RunSetupOptions = {}): Promise<SetupRunR
     return finish();
   }
 
+  // Reuse an upload-compatible token from `gh auth token` when setup already
+  // authenticated the operator through the CLI. This is best-effort and does
+  // not make an otherwise healthy setup fail; the same credential can always
+  // be added later in Settings without restarting the stack.
+  if (backendReady && resolvedAuth.mode !== 'demo') {
+    try {
+      const previewCredential = await actions.configureVisualPreviewCredential(rootDir);
+      if (previewCredential.status === 'configured') {
+        log(`visual previews: configured from the gh CLI session${previewCredential.githubUsername ? ` (@${previewCredential.githubUsername})` : ''}`);
+      } else if (previewCredential.status === 'already-configured') {
+        log('visual previews: upload credential already configured');
+      } else if (previewCredential.status === 'unsupported') {
+        log('visual previews: the gh CLI token type cannot upload attachments; add a PAT in Settings');
+      } else if (previewCredential.status === 'environment-managed') {
+        log('visual previews: GITHUB_VISUAL_PREVIEW_TOKEN is invalid; replace or remove that environment override');
+      }
+    } catch (error) {
+      log(`visual previews: could not import the gh CLI token (${(error as Error).message}); add a PAT in Settings`);
+    }
+  }
+
   // 7. Enable agents in the running backend — add the selected agents that are
   //    missing (existing ones are never disabled or deleted) and, on
   //    confirmation, authenticate the ones that support an image login. This
diff --git a/packages/cli/src/commands/setup/sequential.test.ts b/packages/cli/src/commands/setup/sequential.test.ts
index 151e1a288..017842a2f 100644
--- a/packages/cli/src/commands/setup/sequential.test.ts
+++ b/packages/cli/src/commands/setup/sequential.test.ts
@@ -321,6 +321,7 @@ function mockActions(overrides: Partial<SetupActions> = {}): SetupActions {
     isStackRunning: async () => false,
     startStack: async () => undefined,
     checkBackendHealth: async () => ({ healthy: true, detail: "API healthy" }),
+    configureVisualPreviewCredential: async () => ({ status: 'already-configured' }),
     addRepository: async () => undefined,
     resolveUiUrl: async () => "http://localhost:3000",
     openUrl: async () => undefined,
diff --git a/packages/core/src/services/visualPreviewOAuthCredentialService.ts b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
index 11593b62c..dfe6cdb45 100644
--- a/packages/core/src/services/visualPreviewOAuthCredentialService.ts
+++ b/packages/core/src/services/visualPreviewOAuthCredentialService.ts
@@ -22,7 +22,7 @@ const SUPPORTED_TOKEN_PATTERN = /^(?:gho_|ghp_|github_pat_)/;
 export const VISUAL_PREVIEW_UPLOAD_TOKEN_ENV = 'GITHUB_VISUAL_PREVIEW_TOKEN';
 export const VISUAL_PREVIEW_CREDENTIAL_KEY_ENV = 'PROPR_CREDENTIAL_ENCRYPTION_KEY';
 
-export type VisualPreviewOAuthSource = 'github' | 'connect';
+export type VisualPreviewOAuthSource = 'github' | 'connect' | 'static_token';
 export type VisualPreviewOAuthStatus = 'active' | 'reauth_required';
 
 export interface VisualPreviewOAuthCredentialInput {
@@ -387,6 +387,10 @@ export class VisualPreviewOAuthCredentialService {
   ): Promise<VisualPreviewOAuthCredentialGrant | null> {
     const current = await this.credentialQuery().first();
     if (!current || current.github_user_id !== githubUserId) return null;
+    // A manually supplied or CLI-imported token is dedicated to background
+    // preview uploads. Never copy it into the administrator's browser session
+    // or try to refresh it as an OAuth grant.
+    if (current.source === 'static_token') return null;
     const refreshStatus = await this.refreshIfNeeded(force);
     if (refreshStatus === 'reauth-required') return { status: 'reauth_required' };
     const row = await this.credentialQuery().first();
diff --git a/packages/core/src/services/visualPreviewService.ts b/packages/core/src/services/visualPreviewService.ts
index 0fdef7abe..32a1c9f56 100644
--- a/packages/core/src/services/visualPreviewService.ts
+++ b/packages/core/src/services/visualPreviewService.ts
@@ -363,11 +363,10 @@ export function renderVisualPreviewUploadFailureSection(
     parts.push('### Restore preview uploads');
     parts.push(
       'An instance administrator must open the ProPR Web UI, go to **Settings → Visual preview uploads**, '
-      + 'and select **Use my GitHub login** when that login is backed by a GitHub OAuth App token (`gho_`). '
-      + 'GitHub rejects GitHub App user (`ghu_`) and installation (`ghs_`) tokens for attachments. If the current '
-      + 'login is ineligible, configure Web UI login with a GitHub OAuth App, or set `GITHUB_VISUAL_PREVIEW_TOKEN` '
-      + 'to an OAuth App token, classic PAT, or fine-grained PAT with repository write access. The environment '
-      + 'override takes precedence over the Web UI credential. Then request the visual preview again.',
+      + 'and add or replace the personal access token. The token must have access to this repository. GitHub '
+      + 'rejects GitHub App user (`ghu_`) and installation (`ghs_`) tokens for attachments. A server operator can '
+      + 'alternatively set `GITHUB_VISUAL_PREVIEW_TOKEN`; that environment override takes precedence over the Web '
+      + 'UI credential. Then request the visual preview again.',
     );
   }
   if (evidence.toolSuggestions.length > 0) {
diff --git a/packages/core/test/visualPreviewOAuthCredentialService.test.ts b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
index 493fcf57d..8d2012a42 100644
--- a/packages/core/test/visualPreviewOAuthCredentialService.test.ts
+++ b/packages/core/test/visualPreviewOAuthCredentialService.test.ts
@@ -68,6 +68,20 @@ test('does not silently replace a healthy credential when another admin logs in'
   assert.equal(await service.resolveUploadToken(), 'gho_second');
 });
 
+test('keeps a personal access token dedicated to uploads instead of copying it into a browser session', async () => {
+  const service = createService();
+  await service.replace({
+    githubUserId: '1',
+    githubUsername: 'preview-bot',
+    source: 'static_token',
+    accessToken: 'github_pat_preview-secret',
+  });
+
+  assert.equal(await service.resolveUploadToken(), 'github_pat_preview-secret');
+  assert.equal(await service.refreshAndGetForOwner('1', true), null);
+  assert.equal((await service.getStatus()).status, 'active');
+});
+
 test('refreshes an expiring OAuth grant and rotates both persisted tokens', async () => {
   let refreshBody: Record<string, string> | undefined;
   const service = createService((async (_input, init) => {
diff --git a/packages/core/test/visualPreviewService.test.ts b/packages/core/test/visualPreviewService.test.ts
index b77da9bfe..631a4eb27 100644
--- a/packages/core/test/visualPreviewService.test.ts
+++ b/packages/core/test/visualPreviewService.test.ts
@@ -123,9 +123,9 @@ test('renders upload-ready local media without committed-file fallbacks', async
   assert.doesNotMatch(failure, /desktop view\.png/);
   const authenticationFailure = renderVisualPreviewUploadFailureSection(evidence, { authenticationFailure: true });
   assert.match(authenticationFailure, /Settings → Visual preview uploads/);
-  assert.match(authenticationFailure, /Use my GitHub login/);
+  assert.match(authenticationFailure, /add or replace the personal access token/);
   assert.match(authenticationFailure, /GitHub App user \(`ghu_`\)/);
-  assert.match(authenticationFailure, /GitHub OAuth App token \(`gho_`\)/);
+  assert.match(authenticationFailure, /GITHUB_VISUAL_PREVIEW_TOKEN/);
   assert.equal(appendVisualPreviewSection(`Before\n\n${VISUAL_PREVIEW_SLOT}\n\nAfter`, failure), `Before\n\n${failure}\n\nAfter`);
 });
 
diff --git a/propr-ui/src/api/visualPreviewAuthApi.ts b/propr-ui/src/api/visualPreviewAuthApi.ts
index eba1a4e5e..76f5c46e1 100644
--- a/propr-ui/src/api/visualPreviewAuthApi.ts
+++ b/propr-ui/src/api/visualPreviewAuthApi.ts
@@ -4,7 +4,7 @@ export type VisualPreviewAuthStatusValue = 'active' | 'reauth_required' | 'missi
 
 export interface VisualPreviewAuthStatus {
   configured: boolean;
-  source?: 'github' | 'connect' | 'environment';
+  source?: 'github' | 'connect' | 'static_token' | 'environment';
   status: VisualPreviewAuthStatusValue;
   githubUsername?: string;
   currentUsername?: string;
@@ -24,6 +24,17 @@ export async function getVisualPreviewAuthStatus(): Promise<VisualPreviewAuthSta
   return response.json();
 }
 
+export async function connectVisualPreviewPersonalAccessToken(token: string): Promise<VisualPreviewAuthStatus> {
+  const response = await apiFetch(`${API_BASE_URL}/api/config/visual-preview-auth/token`, {
+    method: 'PUT',
+    credentials: 'include',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ token }),
+  });
+  await handleApiResponse(response);
+  return response.json();
+}
+
 export async function connectCurrentGitHubLoginForVisualPreviews(): Promise<VisualPreviewAuthStatus> {
   const response = await apiFetch(`${API_BASE_URL}/api/config/visual-preview-auth`, {
     method: 'POST',
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
index 47b85eb95..abb051ccd 100644
--- a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
@@ -5,18 +5,19 @@ import {
   disconnectVisualPreviewAuth,
   getVisualPreviewAuthStatus,
   connectCurrentGitHubLoginForVisualPreviews,
+  connectVisualPreviewPersonalAccessToken,
 } from '../../api/visualPreviewAuthApi';
-import { logout } from '../../api/proprApi';
 
 vi.mock('../../api/visualPreviewAuthApi', () => ({
   disconnectVisualPreviewAuth: vi.fn(),
   getVisualPreviewAuthStatus: vi.fn(),
   connectCurrentGitHubLoginForVisualPreviews: vi.fn(),
+  connectVisualPreviewPersonalAccessToken: vi.fn(),
 }));
-vi.mock('../../api/proprApi', () => ({ logout: vi.fn() }));
 
 const getStatus = vi.mocked(getVisualPreviewAuthStatus);
 const useCurrentLogin = vi.mocked(connectCurrentGitHubLoginForVisualPreviews);
+const usePersonalAccessToken = vi.mocked(connectVisualPreviewPersonalAccessToken);
 
 describe('VisualPreviewAuthSection', () => {
   beforeEach(() => {
@@ -70,7 +71,6 @@ describe('VisualPreviewAuthSection', () => {
 
     fireEvent.click(await screen.findByRole('button', { name: 'Use my GitHub login' }));
     await waitFor(() => expect(useCurrentLogin).toHaveBeenCalledOnce());
-    expect(logout).not.toHaveBeenCalled();
   });
 
   it('explains that repeating a GitHub App login cannot enable uploads', async () => {
@@ -83,9 +83,31 @@ describe('VisualPreviewAuthSection', () => {
     });
     render(<VisualPreviewAuthSection />);
 
-    expect(await screen.findByText(/GitHub App user token/)).toBeInTheDocument();
+    expect(await screen.findByText(/GitHub App token/)).toBeInTheDocument();
     expect(screen.queryByRole('button', { name: 'Use my GitHub login' })).not.toBeInTheDocument();
-    expect(screen.queryByRole('button', { name: 'Sign in with GitHub again' })).not.toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Add personal access token' })).toBeInTheDocument();
+  });
+
+  it('validates and stores a personal access token without rendering it afterward', async () => {
+    usePersonalAccessToken.mockResolvedValue({
+      configured: true,
+      source: 'static_token',
+      status: 'active',
+      githubUsername: 'preview-bot',
+      currentUsername: 'admin',
+      currentLoginTokenType: 'github_app_user',
+      canUseCurrentLogin: false,
+    });
+    render(<VisualPreviewAuthSection />);
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Add personal access token' }));
+    const input = screen.getByLabelText('GitHub personal access token');
+    fireEvent.change(input, { target: { value: 'github_pat_preview-secret' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save token' }));
+
+    await waitFor(() => expect(usePersonalAccessToken).toHaveBeenCalledWith('github_pat_preview-secret'));
+    expect(await screen.findByText(/owned by @preview-bot/)).toBeInTheDocument();
+    expect(screen.queryByDisplayValue('github_pat_preview-secret')).not.toBeInTheDocument();
   });
 
   it('shows environment-managed credentials without replacement controls', async () => {
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
index fd7dfd248..d35f5cf2b 100644
--- a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
@@ -1,10 +1,10 @@
 import React, { useCallback, useEffect, useState } from 'react';
-import { Check, LoaderCircle, LogIn, Unplug } from 'lucide-react';
-import { logout } from '../../api/proprApi';
+import { Check, KeyRound, LoaderCircle, Unplug, X } from 'lucide-react';
 import {
   disconnectVisualPreviewAuth,
   getVisualPreviewAuthStatus,
   connectCurrentGitHubLoginForVisualPreviews,
+  connectVisualPreviewPersonalAccessToken,
   type VisualPreviewAuthStatus,
 } from '../../api/visualPreviewAuthApi';
 
@@ -14,15 +14,127 @@ function statusDescription(status: VisualPreviewAuthStatus | null): string {
       ? 'A server-managed credential is configured through GITHUB_VISUAL_PREVIEW_TOKEN.'
       : 'GITHUB_VISUAL_PREVIEW_TOKEN is set but is not a supported upload credential. Remove or replace it and restart the worker.';
   }
+  if (status?.status === 'active' && status.source === 'static_token' && status.githubUsername) {
+    return `Uploads use an encrypted upload token owned by @${status.githubUsername}.`;
+  }
   if (status?.status === 'active' && status.githubUsername) {
     return `Uploads use the GitHub login for @${status.githubUsername}. Expiring OAuth credentials are refreshed automatically.`;
   }
   if (status?.currentLoginTokenType === 'github_app_user') {
-    return 'Your current login uses a GitHub App user token, which GitHub attachment uploads reject. Configure Web UI login with a GitHub OAuth App, or set GITHUB_VISUAL_PREVIEW_TOKEN to an OAuth App token or PAT.';
+    return 'Your normal login uses a GitHub App token, which GitHub attachment uploads reject. Add a personal access token once for preview uploads.';
   }
-  return 'Connect an administrator GitHub login so background workers can attach generated screenshots and videos to pull requests.';
+  return 'Add a GitHub personal access token so background workers can attach generated screenshots and videos to pull requests.';
+}
+
+interface VisualPreviewAuthControlsProps {
+  status: VisualPreviewAuthStatus | null;
+  saving: boolean;
+  onConnectCurrentLogin: () => Promise<void>;
+  onDisconnect: () => Promise<void>;
+  onSaveToken: (token: string) => Promise<boolean>;
+  onClearError: () => void;
 }
 
+const VisualPreviewAuthControls: React.FC<VisualPreviewAuthControlsProps> = ({
+  status,
+  saving,
+  onConnectCurrentLogin,
+  onDisconnect,
+  onSaveToken,
+  onClearError,
+}) => {
+  const [editingToken, setEditingToken] = useState(false);
+  const [token, setToken] = useState('');
+  const active = status?.status === 'active';
+  const canConnectCurrentLogin = !active && status?.canUseCurrentLogin;
+
+  const submit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    const submittedToken = token.trim();
+    if (!submittedToken) return;
+    setToken('');
+    if (await onSaveToken(submittedToken)) setEditingToken(false);
+  };
+
+  return (
+    <div className="mt-3">
+      <div className="flex flex-wrap items-center gap-2">
+        {canConnectCurrentLogin && (
+          <button
+            type="button"
+            onClick={() => void onConnectCurrentLogin()}
+            disabled={saving}
+            className="inline-flex items-center gap-1.5 rounded bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800 disabled:opacity-50"
+          >
+            {saving ? <LoaderCircle size={13} className="animate-spin" /> : <Check size={13} />}
+            Use my GitHub login
+          </button>
+        )}
+        <button
+          type="button"
+          onClick={() => { setEditingToken(value => !value); onClearError(); }}
+          disabled={saving}
+          className={`${canConnectCurrentLogin ? 'border border-gray-300 text-gray-600 hover:bg-gray-50' : 'bg-gray-900 text-white hover:bg-gray-800'} inline-flex items-center gap-1.5 rounded px-3 py-1.5 text-xs font-medium disabled:opacity-50`}
+        >
+          {editingToken ? <X size={13} /> : <KeyRound size={13} />}
+          {editingToken ? 'Cancel' : active || status?.configured ? 'Replace token' : 'Add personal access token'}
+        </button>
+        {status?.configured && (
+          <button
+            type="button"
+            onClick={() => void onDisconnect()}
+            disabled={saving}
+            className="inline-flex items-center gap-1.5 rounded border border-gray-300 px-3 py-1.5 text-xs font-medium text-gray-600 hover:bg-gray-50 disabled:opacity-50"
+          >
+            <Unplug size={13} />
+            Disconnect
+          </button>
+        )}
+      </div>
+
+      {editingToken && (
+        <form onSubmit={(event) => void submit(event)} className="mt-3 rounded border border-gray-200 bg-gray-50 p-3">
+          <label htmlFor="visual-preview-token" className="block text-xs font-medium text-gray-700">
+            GitHub personal access token
+          </label>
+          <div className="mt-1.5 flex flex-col gap-2 sm:flex-row">
+            <input
+              id="visual-preview-token"
+              type="password"
+              value={token}
+              onChange={(event) => setToken(event.target.value)}
+              autoComplete="off"
+              spellCheck={false}
+              maxLength={512}
+              placeholder="github_pat_… or ghp_…"
+              className="min-w-0 flex-1 rounded border border-gray-300 bg-white px-2.5 py-1.5 text-xs text-gray-900 focus:border-gray-500 focus:outline-none"
+            />
+            <button
+              type="submit"
+              disabled={saving || !token.trim()}
+              className="inline-flex items-center justify-center gap-1.5 rounded bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800 disabled:opacity-50"
+            >
+              {saving && <LoaderCircle size={13} className="animate-spin" />}
+              Save token
+            </button>
+          </div>
+          <p className="mt-2 text-[11px] leading-4 text-gray-500">
+            The token is sent once, validated with GitHub, and encrypted at rest. Give it access to every repository where previews are uploaded.{' '}
+            <a
+              href="https://github.com/settings/personal-access-tokens/new"
+              target="_blank"
+              rel="noreferrer"
+              className="font-medium text-gray-700 underline hover:text-gray-900"
+            >
+              Create a fine-grained token
+            </a>
+          </p>
+        </form>
+      )}
+    </div>
+  );
+};
+
 const VisualPreviewAuthSection: React.FC = () => {
   const [status, setStatus] = useState<VisualPreviewAuthStatus | null>(null);
   const [loading, setLoading] = useState(true);
@@ -67,6 +179,20 @@ const VisualPreviewAuthSection: React.FC = () => {
     }
   };
 
+  const saveToken = async (submittedToken: string): Promise<boolean> => {
+    setSaving(true);
+    setError(null);
+    try {
+      setStatus(await connectVisualPreviewPersonalAccessToken(submittedToken));
+      return true;
+    } catch (requestError) {
+      setError((requestError as Error).message);
+      return false;
+    } finally {
+      setSaving(false);
+    }
+  };
+
   if (loading) {
     return (
       <div className="border-t border-gray-200 pt-6 text-xs text-gray-500">
@@ -77,8 +203,6 @@ const VisualPreviewAuthSection: React.FC = () => {
 
   const active = status?.status === 'active';
   const environmentManaged = status?.source === 'environment';
-  const canConnectCurrentLogin = !active && status?.canUseCurrentLogin;
-  const canRetryLogin = !active && status?.currentLoginTokenType !== 'github_app_user';
 
   return (
     <div className="border-t border-gray-200 pt-6">
@@ -95,40 +219,14 @@ const VisualPreviewAuthSection: React.FC = () => {
       </p>
 
       {!environmentManaged && (
-        <div className="mt-3 flex flex-wrap items-center gap-2">
-          {canConnectCurrentLogin ? (
-            <button
-              type="button"
-              onClick={() => void connect()}
-              disabled={saving}
-              className="inline-flex items-center gap-1.5 rounded bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800 disabled:opacity-50"
-            >
-              {saving ? <LoaderCircle size={13} className="animate-spin" /> : <Check size={13} />}
-              Use my GitHub login
-            </button>
-          ) : canRetryLogin ? (
-            <button
-              type="button"
-              onClick={() => { void logout(); }}
-              disabled={saving}
-              className="inline-flex items-center gap-1.5 rounded bg-gray-900 px-3 py-1.5 text-xs font-medium text-white hover:bg-gray-800 disabled:opacity-50"
-            >
-              <LogIn size={13} />
-              Sign in with GitHub again
-            </button>
-          ) : null}
-          {status?.configured && (
-            <button
-              type="button"
-              onClick={() => void disconnect()}
-              disabled={saving}
-              className="inline-flex items-center gap-1.5 rounded border border-gray-300 px-3 py-1.5 text-xs font-medium text-gray-600 hover:bg-gray-50 disabled:opacity-50"
-            >
-              <Unplug size={13} />
-              Disconnect
-            </button>
-          )}
-        </div>
+        <VisualPreviewAuthControls
+          status={status}
+          saving={saving}
+          onConnectCurrentLogin={connect}
+          onDisconnect={disconnect}
+          onSaveToken={saveToken}
+          onClearError={() => setError(null)}
+        />
       )}
 
       {error && <p className="mt-2 text-xs text-red-600">{error}</p>}

From 1127d7c3a9a2ad064e839ef23af15e7a73a45541 Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Fri, 4 Sep 2026 00:14:28 +0200
Subject: [PATCH 15/18] docs(ui): clarify preview upload token permissions

---
 docs/docs/features/visual-previews.md         | 12 ++++-
 .../VisualPreviewAuthSection.test.tsx         | 17 +++++++
 .../SettingsPage/VisualPreviewAuthSection.tsx | 44 +++++++++++++++----
 3 files changed, 62 insertions(+), 11 deletions(-)

diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
index 22d1c6b08..62084b958 100644
--- a/docs/docs/features/visual-previews.md
+++ b/docs/docs/features/visual-previews.md
@@ -21,8 +21,16 @@ the GitHub App installation token.
 When normal Web UI login uses a GitHub App, an administrator can instead paste
 a personal access token in **Settings → Visual preview uploads**. ProPR validates
 the token with GitHub and encrypts it before storing it. No CLI, callback URL, or
-service restart is required. The token must have access to every repository where
-preview media will be attached.
+service restart is required. For a fine-grained token, choose the organization or
+user that owns the repositories as the resource owner, include every
+preview-enabled repository, and grant the repository permission **Pull requests:
+Read and write**. GitHub adds read-only metadata access automatically; no other
+repository permission is required. The token owner must have push access to the
+repositories and must complete any organization approval or SAML SSO authorization.
+Fine-grained tokens can target only one resource owner. If the repositories span
+multiple owners, use a classic PAT with `repo`, or `public_repo` if every repository
+is public. Settings links to GitHub's token form with the fine-grained permission
+preselected.
 
 Expiring OAuth credentials are refreshed on API startup and every 30 minutes
 while the stack is running. Each successful refresh rotates the access and
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
index abb051ccd..1ad423206 100644
--- a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.test.tsx
@@ -110,6 +110,23 @@ describe('VisualPreviewAuthSection', () => {
     expect(screen.queryByDisplayValue('github_pat_preview-secret')).not.toBeInTheDocument();
   });
 
+  it('shows the exact GitHub permissions needed for preview uploads', async () => {
+    render(<VisualPreviewAuthSection />);
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Add personal access token' }));
+
+    expect(screen.getByText('Fine-grained token requirements')).toBeInTheDocument();
+    expect(screen.getByText('Pull requests')).toBeInTheDocument();
+    expect(screen.getByText('Read and write')).toBeInTheDocument();
+    expect(screen.getByText(/Use an account with push access/)).toBeInTheDocument();
+    expect(screen.getByText(/organization approval or SAML SSO authorization/)).toBeInTheDocument();
+    expect(screen.getByText(/classic token with/)).toHaveTextContent('repo');
+    expect(screen.getByText(/classic token with/)).toHaveTextContent('public_repo');
+
+    const createTokenLink = screen.getByRole('link', { name: 'Create token on GitHub' });
+    expect(createTokenLink).toHaveAttribute('href', expect.stringContaining('pull_requests=write'));
+  });
+
   it('shows environment-managed credentials without replacement controls', async () => {
     getStatus.mockResolvedValue({
       configured: true,
diff --git a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
index d35f5cf2b..be874db8f 100644
--- a/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
+++ b/propr-ui/src/pages/SettingsPage/VisualPreviewAuthSection.tsx
@@ -8,6 +8,8 @@ import {
   type VisualPreviewAuthStatus,
 } from '../../api/visualPreviewAuthApi';
 
+const FINE_GRAINED_TOKEN_URL = 'https://github.com/settings/personal-access-tokens/new?name=ProPR%20visual%20previews&description=Uploads%20generated%20preview%20media%20to%20pull%20requests&pull_requests=write';
+
 function statusDescription(status: VisualPreviewAuthStatus | null): string {
   if (status?.source === 'environment') {
     return status.status === 'active'
@@ -118,16 +120,40 @@ const VisualPreviewAuthControls: React.FC<VisualPreviewAuthControlsProps> = ({
               Save token
             </button>
           </div>
+          <div className="mt-3 rounded border border-gray-200 bg-white p-3 text-[11px] leading-4 text-gray-600">
+            <p className="font-semibold text-gray-700">Fine-grained token requirements</p>
+            <ol className="mt-1.5 list-decimal space-y-1 pl-4">
+              <li>Choose the organization or user that owns the repositories as the resource owner.</li>
+              <li>Select every repository where ProPR will upload visual previews.</li>
+              <li>
+                Under repository permissions, set <span className="font-medium text-gray-700">Pull requests</span> to{' '}
+                <span className="font-medium text-gray-700">Read and write</span>. Metadata read access is added automatically;
+                no other repository permission is required.
+              </li>
+              <li>
+                Use an account with push access to those repositories. Complete organization approval or SAML SSO authorization,
+                if required.
+              </li>
+            </ol>
+            <p className="mt-2">
+              GitHub will prefill the token name and Pull requests permission; you still choose the owner, repositories, and expiration.{' '}
+              <a
+                href={FINE_GRAINED_TOKEN_URL}
+                target="_blank"
+                rel="noreferrer"
+                className="font-medium text-gray-700 underline hover:text-gray-900"
+              >
+                Create token on GitHub
+              </a>
+            </p>
+            <p className="mt-2 text-gray-500">
+              A fine-grained token can cover only one resource owner. If preview-enabled repositories span multiple owners, use a
+              classic token with <code className="font-mono">repo</code>, or <code className="font-mono">public_repo</code> when
+              every repository is public.
+            </p>
+          </div>
           <p className="mt-2 text-[11px] leading-4 text-gray-500">
-            The token is sent once, validated with GitHub, and encrypted at rest. Give it access to every repository where previews are uploaded.{' '}
-            <a
-              href="https://github.com/settings/personal-access-tokens/new"
-              target="_blank"
-              rel="noreferrer"
-              className="font-medium text-gray-700 underline hover:text-gray-900"
-            >
-              Create a fine-grained token
-            </a>
+            The token is sent once, validated with GitHub, and encrypted at rest. It is never displayed again after saving.
           </p>
         </form>
       )}

From 4bd81259b12bb5c860f7be9d00daeea426233439 Mon Sep 17 00:00:00 2001
From: Rinalds Uzkalns <livecart@gmail.com>
Date: Fri, 4 Sep 2026 00:50:56 +0200
Subject: [PATCH 16/18] fix(previews): avoid duplicate completion comments

---
 docs/docs/features/visual-previews.md  |   2 +-
 src/github/visualPreviewAttachments.ts | 220 +++++++++++++++++--------
 test/visualPreviewAttachments.test.ts  | 109 ++++++++----
 3 files changed, 230 insertions(+), 101 deletions(-)

diff --git a/docs/docs/features/visual-previews.md b/docs/docs/features/visual-previews.md
index 62084b958..716d4cd85 100644
--- a/docs/docs/features/visual-previews.md
+++ b/docs/docs/features/visual-previews.md
@@ -82,6 +82,6 @@ Supported image formats are PNG, JPEG, GIF, SVG, and WebP. Supported video forma
 
 ## Publication And Upload Failures
 
-ProPR publishes previews as [GitHub attachments](https://cli.github.com/manual/gh_pr_edit) so images render inline and videos use GitHub's media presentation. It then fetches the published PR or comment body and verifies that GitHub replaced every temporary local path with a hosted attachment URL. Temporary files are deleted after publication. If upload or verification fails, ProPR publishes a text-only explanation; preview media is not added to Git as a fallback. When the failure is a missing, unsupported, expired, or rejected user credential, that explanation includes the exact Settings reconnection steps in the affected pull request.
+ProPR publishes previews as [GitHub attachments](https://cli.github.com/manual/gh_pr_edit) so images render inline and videos use GitHub's media presentation. For follow-ups, it uploads the media first and then updates the existing progress comment; it does not create a temporary second comment. ProPR verifies that every temporary local path was replaced with a hosted attachment URL, then deletes the temporary files. If upload or verification fails, ProPR publishes a text-only explanation; preview media is not added to Git as a fallback. When the failure is a missing, unsupported, expired, or rejected user credential, that explanation includes the exact Settings reconnection steps in the affected pull request.
 
 Preview generation is evidence, not a replacement for automated tests. A preview failure does not discard an otherwise valid implementation; the PR explains missing tool support when the agent can identify it.
diff --git a/src/github/visualPreviewAttachments.ts b/src/github/visualPreviewAttachments.ts
index 8ed35da23..8cf026b06 100644
--- a/src/github/visualPreviewAttachments.ts
+++ b/src/github/visualPreviewAttachments.ts
@@ -1,3 +1,5 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { execa } from 'execa';
 import {
   appendVisualPreviewSection,
@@ -20,6 +22,14 @@ interface AttachmentCommandOptions {
 
 export type AttachmentCommandRunner = (options: AttachmentCommandOptions) => Promise<{ stdout: string }>;
 
+interface VisualPreviewAssetUploadOptions {
+  absolutePath: string;
+  authToken: string;
+  repositoryId: number;
+}
+
+export type VisualPreviewAssetUploader = (options: VisualPreviewAssetUploadOptions) => Promise<string>;
+
 export { VISUAL_PREVIEW_UPLOAD_TOKEN_ENV };
 
 export class VisualPreviewUploadAuthenticationError extends Error {
@@ -106,6 +116,92 @@ const runAttachmentCommand: AttachmentCommandRunner = async ({ args, authToken,
   }
 };
 
+const CONTENT_TYPE_BY_EXTENSION: Record<string, string> = {
+  '.gif': 'image/gif',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.mov': 'video/quicktime',
+  '.mp4': 'video/mp4',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.webm': 'video/webm',
+  '.webp': 'image/webp',
+};
+
+async function responseErrorDetail(response: Response): Promise<string> {
+  const rawBody = redactSecrets((await response.text()).trim()).replace(/\s+/g, ' ').slice(0, 1000);
+  if (!rawBody) return '';
+  try {
+    const parsed = JSON.parse(rawBody) as { message?: unknown; errors?: unknown };
+    const message = typeof parsed.message === 'string' ? parsed.message : '';
+    const errors = Array.isArray(parsed.errors)
+      ? parsed.errors.filter((error): error is string => typeof error === 'string').join('; ')
+      : '';
+    return [message, errors].filter(Boolean).join('; ');
+  } catch {
+    return rawBody;
+  }
+}
+
+async function markRejectedUploadCredential(): Promise<void> {
+  try {
+    await markVisualPreviewOAuthCredentialReauthRequired('github_rejected_token');
+  } catch {
+    // Preserve the original upload error. The Settings status can recover
+    // once database access is restored.
+  }
+}
+
+export const uploadVisualPreviewAsset: VisualPreviewAssetUploader = async ({
+  absolutePath,
+  authToken,
+  repositoryId,
+}) => {
+  const contentType = CONTENT_TYPE_BY_EXTENSION[path.extname(absolutePath).toLowerCase()];
+  if (!contentType) throw new Error(`Unsupported visual preview attachment type: ${path.basename(absolutePath)}`);
+
+  const body = await readFile(absolutePath);
+  const uploadUrl = new URL('https://uploads.github.com/user-attachments/assets');
+  uploadUrl.searchParams.set('name', path.basename(absolutePath));
+  uploadUrl.searchParams.set('content_type', contentType);
+  uploadUrl.searchParams.set('repository_id', String(repositoryId));
+
+  let response: Response;
+  try {
+    response = await fetch(uploadUrl, {
+      method: 'POST',
+      headers: {
+        Accept: 'application/vnd.github+json',
+        Authorization: `Bearer ${authToken}`,
+        'Content-Length': String(body.byteLength),
+        'Content-Type': 'application/octet-stream',
+        'User-Agent': 'ProPR',
+      },
+      body,
+      signal: AbortSignal.timeout(60_000),
+    });
+  } catch (error) {
+    throw new Error(`GitHub could not upload ${path.basename(absolutePath)}: ${(error as Error).message}`);
+  }
+
+  if (!response.ok) {
+    const detail = await responseErrorDetail(response);
+    const suffix = detail ? `: ${detail}` : '';
+    const message = response.status === 404
+      ? `GitHub could not upload ${path.basename(absolutePath)} because the token owner does not have write access to the repository${suffix}`
+      : `GitHub could not upload ${path.basename(absolutePath)} (HTTP ${response.status})${suffix}`;
+    if (response.status === 401) await markRejectedUploadCredential();
+    if ([401, 403, 404].includes(response.status)) throw new VisualPreviewUploadAuthenticationError(message);
+    throw new Error(message);
+  }
+
+  const payload = await response.json() as { url?: unknown };
+  if (typeof payload.url !== 'string' || !payload.url.startsWith('https://github.com/user-attachments/')) {
+    throw new Error('GitHub uploaded a visual preview but did not return a valid attachment URL');
+  }
+  return payload.url;
+};
+
 interface BaseVisualPreviewPublicationOptions {
   owner: string;
   repo: string;
@@ -115,6 +211,7 @@ interface BaseVisualPreviewPublicationOptions {
   authToken?: string;
   worktreePath: string;
   runCommand?: AttachmentCommandRunner;
+  uploadAsset?: VisualPreviewAssetUploader;
 }
 
 function attachmentArguments(evidence: VisualPreviewEvidence): string[] {
@@ -128,6 +225,20 @@ function bodyWithLocalPreviews(options: BaseVisualPreviewPublicationOptions): st
   return appendVisualPreviewSection(options.body, section);
 }
 
+function bodyWithUploadedPreviews(options: BaseVisualPreviewPublicationOptions, uploadedUrls: readonly string[]): string {
+  if (uploadedUrls.length !== options.evidence.assets.length) {
+    throw new Error('GitHub did not return an attachment URL for every visual preview');
+  }
+  const evidence = {
+    ...options.evidence,
+    assets: options.evidence.assets.map((asset, index) => ({
+      ...asset,
+      absolutePath: uploadedUrls[index],
+    })),
+  };
+  return appendVisualPreviewSection(options.body, renderVisualPreviewSection(evidence, { useLocalPaths: true }));
+}
+
 function assertUploadedBodyHasNoLocalPaths(body: unknown, evidence: VisualPreviewEvidence): asserts body is string {
   if (typeof body !== 'string') {
     throw new Error('GitHub uploaded visual previews but did not return the published body');
@@ -139,6 +250,23 @@ function assertUploadedBodyHasNoLocalPaths(body: unknown, evidence: VisualPrevie
   }
 }
 
+function assertUploadedBodyContainsUrls(body: string, uploadedUrls: readonly string[]): void {
+  const missingUrl = uploadedUrls.find(url => !body.includes(url));
+  if (missingUrl) throw new Error('GitHub published a visual preview comment without every uploaded attachment URL');
+}
+
+async function resolveRepositoryId(options: PublishPullRequestCommentVisualPreviewOptions): Promise<number> {
+  const response = await options.octokit.request<{ data: { id?: unknown } }>('GET /repos/{owner}/{repo}', {
+    owner: options.owner,
+    repo: options.repo,
+  });
+  const repositoryId = response.data.id;
+  if (typeof repositoryId !== 'number' || !Number.isSafeInteger(repositoryId) || repositoryId <= 0) {
+    throw new Error('Could not determine which GitHub repository should own the visual preview attachments');
+  }
+  return repositoryId;
+}
+
 export interface PublishPullRequestVisualPreviewOptions extends BaseVisualPreviewPublicationOptions {
   pullRequestNumber: number;
   octokit: {
@@ -180,83 +308,39 @@ export interface PublishedVisualPreviewComment {
   body: string;
 }
 
-function parseCommentId(url: string): number | null {
-  const match = url.match(/#issuecomment-(\d+)\b/);
-  return match ? Number(match[1]) : null;
-}
-
 export async function publishPullRequestCommentVisualPreviews(
   options: PublishPullRequestCommentVisualPreviewOptions
 ): Promise<PublishedVisualPreviewComment> {
   if (options.evidence.assets.length === 0) {
     throw new Error('Cannot publish an attachment comment without preview assets');
   }
-  const runner = options.runCommand || runAttachmentCommand;
-  let publishedCommentId: number | null = null;
-  try {
-    const result = await runner({
-      args: [
-        'pr', 'comment', String(options.pullRequestNumber),
-        '--repo', `${options.owner}/${options.repo}`,
-        '--body', bodyWithLocalPreviews(options),
-        ...attachmentArguments(options.evidence)
-      ],
-      authToken: options.authToken ?? await resolveVisualPreviewUploadToken(),
-      cwd: options.worktreePath
-    });
-    const commentUrl = result.stdout.trim().split('\n').find(line => line.includes('#issuecomment-')) || result.stdout.trim();
-    if (!commentUrl) throw new Error('GitHub CLI uploaded previews but did not return a comment URL');
-    publishedCommentId = parseCommentId(commentUrl);
-    if (!publishedCommentId) throw new Error('GitHub CLI uploaded previews but did not return a comment ID');
+  const authToken = options.authToken ?? await resolveVisualPreviewUploadToken();
+  const repositoryId = await resolveRepositoryId(options);
+  const uploader = options.uploadAsset ?? uploadVisualPreviewAsset;
+  const uploadedUrls: string[] = [];
+  for (const asset of options.evidence.assets) {
+    uploadedUrls.push(await uploader({
+      absolutePath: asset.absolutePath,
+      authToken,
+      repositoryId,
+    }));
+  }
 
-    const response = await options.octokit.request<{ data: { body?: string } }>('GET /repos/{owner}/{repo}/issues/comments/{comment_id}', {
+  const body = bodyWithUploadedPreviews(options, uploadedUrls);
+  const updatedStartingComment = await options.octokit.request<{ data: { html_url: string; body?: string } }>(
+    'PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}',
+    {
       owner: options.owner,
       repo: options.repo,
-      comment_id: publishedCommentId
-    });
-    assertUploadedBodyHasNoLocalPaths(response.data.body, options.evidence);
-
-    const updatedStartingComment = await options.octokit.request<{ data: { html_url: string; body?: string } }>(
-      'PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}',
-      {
-        owner: options.owner,
-        repo: options.repo,
-        comment_id: options.startingCommentId,
-        body: response.data.body
-      }
-    );
-
-    try {
-      await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
-        owner: options.owner,
-        repo: options.repo,
-        comment_id: publishedCommentId
-      });
-    } catch {
-      // The bot-owned completion comment is already updated. Leaving the
-      // temporary uploader comment is preferable to losing the preview.
+      comment_id: options.startingCommentId,
+      body,
     }
+  );
+  assertUploadedBodyHasNoLocalPaths(updatedStartingComment.data.body, options.evidence);
+  assertUploadedBodyContainsUrls(updatedStartingComment.data.body, uploadedUrls);
 
-    return {
-      html_url: updatedStartingComment.data.html_url,
-      body: updatedStartingComment.data.body || response.data.body
-    };
-  } catch (error) {
-    publishedCommentId ||= parseCommentId(typeof (error as { stdout?: unknown })?.stdout === 'string'
-      ? (error as { stdout: string }).stdout
-      : '');
-    if (publishedCommentId) {
-      try {
-        await options.octokit.request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {
-          owner: options.owner,
-          repo: options.repo,
-          comment_id: publishedCommentId
-        });
-      } catch {
-        // Best-effort cleanup; the caller replaces the work comment with a
-        // text-only explanation that contains no local filesystem paths.
-      }
-    }
-    throw error;
-  }
+  return {
+    html_url: updatedStartingComment.data.html_url,
+    body: updatedStartingComment.data.body,
+  };
 }
diff --git a/test/visualPreviewAttachments.test.ts b/test/visualPreviewAttachments.test.ts
index cf4183d34..462e528f9 100644
--- a/test/visualPreviewAttachments.test.ts
+++ b/test/visualPreviewAttachments.test.ts
@@ -1,4 +1,7 @@
 import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import { after, test } from 'node:test';
 
 process.env.PROPR_DEMO_MODE = 'true';
@@ -7,7 +10,8 @@ const [{ db }, {
   publishPullRequestCommentVisualPreviews,
   publishPullRequestVisualPreviews,
   resolveVisualPreviewUploadToken,
-  isVisualPreviewUploadAuthenticationError
+  isVisualPreviewUploadAuthenticationError,
+  uploadVisualPreviewAsset,
 }] = await Promise.all([
   import('@propr/core'),
   import('../src/github/visualPreviewAttachments.js')
@@ -93,8 +97,9 @@ test('rejects a pull request upload when GitHub leaves a local path in the body'
   }), /did not replace a local visual preview path/);
 });
 
-test('copies uploaded media into the bot-owned work comment and removes the uploader comment', async () => {
+test('uploads media before updating the existing work comment without creating another comment', async () => {
   const requests: Array<{ endpoint: string; options: Record<string, unknown> }> = [];
+  const uploads: Array<{ absolutePath: string; authToken: string; repositoryId: number }> = [];
   const published = await publishPullRequestCommentVisualPreviews({
     owner: 'integry',
     repo: 'propr',
@@ -107,33 +112,41 @@ test('copies uploaded media into the bot-owned work comment and removes the uplo
     octokit: {
       request: async <T>(endpoint: string, options: Record<string, unknown>) => {
         requests.push({ endpoint, options });
+        if (endpoint === 'GET /repos/{owner}/{repo}') {
+          return { data: { id: 987 } } as T;
+        }
         if (endpoint.startsWith('PATCH ')) {
           return { data: {
             html_url: 'https://github.com/integry/propr/pull/42#issuecomment-100',
-            body: 'Follow-up complete with uploaded URL'
+            body: options.body,
           } } as T;
         }
-        return { data: { body: 'Follow-up complete with uploaded URL' } } as T;
+        throw new Error(`Unexpected endpoint: ${endpoint}`);
       }
     },
-    runCommand: async () => ({ stdout: 'https://github.com/integry/propr/pull/42#issuecomment-200' })
+    uploadAsset: async options => {
+      uploads.push(options);
+      return 'https://github.com/user-attachments/assets/asset-id';
+    },
   });
 
-  assert.deepEqual(published, {
-    html_url: 'https://github.com/integry/propr/pull/42#issuecomment-100',
-    body: 'Follow-up complete with uploaded URL'
-  });
+  assert.equal(published.html_url, 'https://github.com/integry/propr/pull/42#issuecomment-100');
+  assert.match(published.body, /https:\/\/github\.com\/user-attachments\/assets\/asset-id/);
+  assert.doesNotMatch(published.body, /\/worktree\/\.propr\/previews/);
   assert.deepEqual(requests.map(request => request.endpoint), [
-    'GET /repos/{owner}/{repo}/issues/comments/{comment_id}',
+    'GET /repos/{owner}/{repo}',
     'PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}',
-    'DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}'
   ]);
   assert.equal(requests[1].options.comment_id, 100);
-  assert.equal(requests[2].options.comment_id, 200);
+  assert.deepEqual(uploads, [{
+    absolutePath: '/worktree/.propr/previews/desktop.png',
+    authToken: 'installation-token',
+    repositoryId: 987,
+  }]);
 });
 
-test('removes a partially published attachment comment before surfacing upload failure', async () => {
-  const deletedCommentIds: unknown[] = [];
+test('does not update the work comment when a direct attachment upload fails', async () => {
+  const requests: string[] = [];
   await assert.rejects(() => publishPullRequestCommentVisualPreviews({
     owner: 'integry',
     repo: 'propr',
@@ -144,23 +157,19 @@ test('removes a partially published attachment comment before surfacing upload f
     worktreePath: '/worktree',
     startingCommentId: 100,
     octokit: {
-      request: async <T>(_endpoint: string, options: Record<string, unknown>) => {
-        deletedCommentIds.push(options.comment_id);
-        return {} as T;
+      request: async <T>(endpoint: string) => {
+        requests.push(endpoint);
+        return { data: { id: 987 } } as T;
       }
     },
-    runCommand: async () => {
-      throw Object.assign(new Error('one attachment failed'), {
-        stdout: 'https://github.com/integry/propr/pull/42#issuecomment-201'
-      });
-    }
-  }), /one attachment failed/);
+    uploadAsset: async () => { throw new Error('attachment upload failed'); },
+  }), /attachment upload failed/);
 
-  assert.deepEqual(deletedCommentIds, [201]);
+  assert.deepEqual(requests, ['GET /repos/{owner}/{repo}']);
 });
 
-test('deletes an uploaded comment whose fetched body still contains a local path', async () => {
-  const deletedCommentIds: unknown[] = [];
+test('rejects an updated work comment whose response still contains a local path', async () => {
+  const requests: string[] = [];
   await assert.rejects(() => publishPullRequestCommentVisualPreviews({
     owner: 'integry',
     repo: 'propr',
@@ -172,15 +181,51 @@ test('deletes an uploaded comment whose fetched body still contains a local path
     startingCommentId: 100,
     octokit: {
       request: async <T>(endpoint: string, options: Record<string, unknown>) => {
-        if (endpoint.startsWith('GET ')) {
-          return { data: { body: '![Desktop settings](/worktree/.propr/previews/desktop.png)' } } as T;
+        requests.push(endpoint);
+        if (endpoint === 'GET /repos/{owner}/{repo}') {
+          return { data: { id: 987 } } as T;
         }
-        deletedCommentIds.push(options.comment_id);
-        return {} as T;
+        return { data: {
+          html_url: 'https://github.com/integry/propr/pull/42#issuecomment-100',
+          body: '![Desktop settings](/worktree/.propr/previews/desktop.png)',
+          comment_id: options.comment_id,
+        } } as T;
       }
     },
-    runCommand: async () => ({ stdout: 'https://github.com/integry/propr/pull/42#issuecomment-202' })
+    uploadAsset: async () => 'https://github.com/user-attachments/assets/asset-id',
   }), /did not replace a local visual preview path/);
 
-  assert.deepEqual(deletedCommentIds, [202]);
+  assert.deepEqual(requests, [
+    'GET /repos/{owner}/{repo}',
+    'PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}',
+  ]);
+});
+
+test('uploads an attachment directly to the repository-scoped GitHub endpoint', async t => {
+  const temporaryDirectory = await mkdtemp(path.join(tmpdir(), 'propr-upload-test-'));
+  const assetPath = path.join(temporaryDirectory, 'desktop.png');
+  const assetBody = Buffer.from('preview bytes');
+  await writeFile(assetPath, assetBody);
+  t.after(async () => rm(temporaryDirectory, { recursive: true, force: true }));
+
+  t.mock.method(globalThis, 'fetch', async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(String(input));
+    assert.equal(url.origin, 'https://uploads.github.com');
+    assert.equal(url.pathname, '/user-attachments/assets');
+    assert.equal(url.searchParams.get('name'), 'desktop.png');
+    assert.equal(url.searchParams.get('content_type'), 'image/png');
+    assert.equal(url.searchParams.get('repository_id'), '987');
+    assert.equal(init?.method, 'POST');
+    assert.equal(new Headers(init?.headers).get('Authorization'), 'Bearer preview-token');
+    assert.deepEqual(Buffer.from(init?.body as Uint8Array), assetBody);
+    return new Response(JSON.stringify({
+      url: 'https://github.com/user-attachments/assets/direct-asset-id',
+    }), { status: 201, headers: { 'Content-Type': 'application/json' } });
+  });
+
+  assert.equal(await uploadVisualPreviewAsset({
+    absolutePath: assetPath,
+    authToken: 'preview-token',
+    repositoryId: 987,
+  }), 'https://github.com/user-attachments/assets/direct-asset-id');
 });

From ea8bbf58ffecc133a7f848bc61ffaa1d160f4cd8 Mon Sep 17 00:00:00 2001
From: "propr-dev[bot]" <1316198+propr-dev[bot]@users.noreply.github.com>
Date: Thu, 3 Sep 2026 23:36:19 +0000
Subject: [PATCH 17/18] =?UTF-8?q?feat(ai):=20Implemented=20selected=20find?=
 =?UTF-8?q?ings=20F1=E2=80=93F3=20only.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implemented selected findings F1–F3 only.

- F1: Already fixed on this branch; empty sections only remove the placeholder without normalizing body whitespace.
- F2: Unexpired sessions without refresh tokens now continue normally; explicit invalidation remains fatal.
- F3: Removed invalid `offline_access` GitHub scope.

Validation passed:

- 16 focused tests
- Core and API typechecks
- Core and API lint
- `git diff --check`

No visual previews were generated because these changes have no visual UI impact. No commit was created.

PR: #2102
Comment by: @integry (ID: 5533427617)
Model: gpt-5.6-sol
---
 packages/api/auth.ts             | 4 ++--
 packages/api/authGithubTokens.ts | 4 +++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/api/auth.ts b/packages/api/auth.ts
index ed58cba95..420a52e4c 100644
--- a/packages/api/auth.ts
+++ b/packages/api/auth.ts
@@ -285,7 +285,7 @@ export function setupAuth(app: Express, demoModeAtStartup = isDemoMode()): Socke
             redirectAuthError(res, 'web_auth_not_configured');
             return;
         }
-        passport.authenticate('github', { scope: ['user:email', 'read:org', 'repo', 'offline_access'] })(req, res, next);
+        passport.authenticate('github', { scope: ['user:email', 'read:org', 'repo'] })(req, res, next);
     });
 
     if (demoModeAtStartup) {
@@ -448,7 +448,7 @@ export async function ensureAuthenticated(req: Request, res: Response, next: Nex
             // Temporary proactive-refresh failures do not invalidate a token
             // whose recorded expiry is still in the future.
             const refreshResult = await refreshGitHubTokenWithResult(req);
-            if (refreshResult.status === 'reauth-required' || req.user?.githubAuthInvalid) {
+            if (req.user?.githubAuthInvalid) {
                 if (req.user?.githubAuthInvalid) await clearSessionForReauth(req);
                 res.status(401).json({ error: 'GitHub authentication expired', code: 'GITHUB_REAUTH_REQUIRED', message: 'Your GitHub session has expired. Please log in again.' });
                 return;
diff --git a/packages/api/authGithubTokens.ts b/packages/api/authGithubTokens.ts
index 079acd502..08cc2566e 100644
--- a/packages/api/authGithubTokens.ts
+++ b/packages/api/authGithubTokens.ts
@@ -173,7 +173,9 @@ async function performGitHubTokenRefresh(req: Request, force: boolean): Promise<
         }
     }
 
-    if (!user.refreshToken) return { status: 'reauth-required' };
+    if (!user.refreshToken) {
+        return { status: force ? 'reauth-required' : 'not-needed' };
+    }
 
     const now = Date.now();
     const needsRefresh = force || (user.tokenExpiresAt && (user.tokenExpiresAt - now) < TOKEN_REFRESH_BUFFER_MS);

From a279a3c7f0f8dfad4894ee270ff264dc178e0e37 Mon Sep 17 00:00:00 2001
From: "propr-dev[bot]" <1316198+propr-dev[bot]@users.noreply.github.com>
Date: Fri, 4 Sep 2026 00:03:21 +0000
Subject: [PATCH 18/18] feat(ai): Implemented only F4 and F5.

Implemented only F4 and F5.

- F4: Preserves the prior repository-wide visual-preview policy using enabled-wins semantics when branch entries are deleted or unchanged.
- F5: Adds a 20-second timeout to GitHub/Connect token refresh requests; aborts remain `temporarily-unavailable`.

Validation passed:

- Focused config and authentication tests
- Branch-deletion regression check
- Timeout/abort regression check
- API typecheck and lint
- `git diff --check`

Only the two cited implementation files changed. No visual previews were created because the changes are backend-only.

PR: #2102
Comment by: @propr-ultrafix (ID: 0)
Model: gpt-5.6-sol
---
 packages/api/authGithubTokens.ts            |  6 +++++-
 packages/api/routes/configRepoValidation.ts | 18 ++++++++++++++----
 2 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/packages/api/authGithubTokens.ts b/packages/api/authGithubTokens.ts
index 08cc2566e..238e36cb3 100644
--- a/packages/api/authGithubTokens.ts
+++ b/packages/api/authGithubTokens.ts
@@ -6,6 +6,7 @@ import {
 } from './services/visualPreviewOAuth.js';
 
 const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+const TOKEN_REFRESH_TIMEOUT_MS = 20_000;
 
 interface GitHubTokenRefreshResponse {
     access_token?: string;
@@ -185,7 +186,10 @@ async function performGitHubTokenRefresh(req: Request, force: boolean): Promise<
 
     try {
         const refreshRequest = buildTokenRefreshRequest(user);
-        const response = await fetch(refreshRequest.endpoint, refreshRequest.init);
+        const response = await fetch(refreshRequest.endpoint, {
+            ...refreshRequest.init,
+            signal: AbortSignal.timeout(TOKEN_REFRESH_TIMEOUT_MS),
+        });
         if (!response.ok) {
             console.error(`GitHub token refresh failed with status ${response.status}`);
             return { status: 'temporarily-unavailable' };
diff --git a/packages/api/routes/configRepoValidation.ts b/packages/api/routes/configRepoValidation.ts
index 8a335ff96..7f68dd9e6 100644
--- a/packages/api/routes/configRepoValidation.ts
+++ b/packages/api/routes/configRepoValidation.ts
@@ -110,11 +110,21 @@ export function preserveRepoVisualPreview(
 
   return normalizedRepos.map(repo => {
     const repositoryKey = repo.name.trim().toLowerCase();
-    const explicit = changedByRepository.get(repositoryKey) || explicitByRepository.get(repositoryKey);
-    if (explicit) return { ...repo, visualPreview: explicit };
+    const changed = changedByRepository.get(repositoryKey);
+    if (changed) return { ...repo, visualPreview: changed };
+
+    const previousMatches = previousRepos.filter(
+      candidate => candidate.name.trim().toLowerCase() === repositoryKey
+    );
+    if (previousMatches.length > 0) {
+      const configured = previousMatches.find(
+        candidate => normalizeStoredVisualPreviewSettings(candidate.visualPreview).enabled
+      ) ?? previousMatches.find(candidate => candidate.visualPreview !== undefined);
+      return { ...repo, visualPreview: normalizeStoredVisualPreviewSettings(configured?.visualPreview) };
+    }
 
-    const previous = previousRepos.find(candidate => candidate.name.trim().toLowerCase() === repositoryKey);
-    return { ...repo, visualPreview: normalizeStoredVisualPreviewSettings(previous?.visualPreview) };
+    const explicit = explicitByRepository.get(repositoryKey);
+    return { ...repo, visualPreview: explicit ?? normalizeStoredVisualPreviewSettings(repo.visualPreview) };
   });
 }