From b9faeac009044fd7ebee30c797ea5ccfc75f65ad Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 21 Jul 2026 18:26:49 -0700
Subject: [PATCH 1/3] refactor: route inline /api fetch calls through client
 service layer (#2838)

---
 .changelog/NEXT.md                            |   1 +
 client/src/components/apps/tabs/GsdTab.jsx    |  19 +--
 .../components/settings/LocalSetupPanel.jsx   |  28 ++---
 .../writers-room/StagePromptModelPicker.jsx   |  19 +--
 client/src/pages/ImageGen.jsx                 |  17 +--
 client/src/pages/PromptManager.jsx            | 112 +++++++-----------
 client/src/services/README.md                 |   1 +
 client/src/services/api.js                    |   1 +
 client/src/services/apiApps.js                |   2 +-
 client/src/services/apiGSD.js                 |   2 +-
 client/src/services/apiImageVideo.js          |  44 ++++++-
 client/src/services/apiPrompts.js             |  58 +++++++++
 12 files changed, 177 insertions(+), 127 deletions(-)
 create mode 100644 client/src/services/apiPrompts.js

diff --git a/.changelog/NEXT.md b/.changelog/NEXT.md
index 766bc5e51..a5c577191 100644
--- a/.changelog/NEXT.md
+++ b/.changelog/NEXT.md
@@ -37,4 +37,5 @@
 
 - **[issue-2832] Split the boot-schema DDL into per-domain modules** — the ~1265-line inline `CREATE TABLE`/`CREATE INDEX`/trigger block in `ensureSchemaImpl()` (`server/lib/db.js`) is extracted into per-domain modules under `server/lib/db/schema/` (catalog, media, universes, writers-room, pipeline, privacy, tribe, audit, …), each exporting a statement array; `ensureSchemaImpl` is now a thin composer. Statement text and order are byte-identical, so the composed schema is unchanged.
 - **[issue-2834] Split the ~1990-line `VideoGen.jsx` into hooks + subcomponents** — the client-side batch-queue orchestration moves into `useVideoGenQueue`, the pure model-memory / FFLF frame-budget / mode-compat helpers into `lib/videoGenParams.js`, and four presentational blocks into `components/videoGen/` (`RuntimeFingerprint`, `ModelRepairBanner`, `VideoPreviewPanel`, `VideoGenGallery`). The inline runtime-status `fetch()` now routes through a `getVideoGenRuntimeStatus` service wrapper, and the Seed input gains a proper `<label htmlFor>`/`id` pairing. Behavior and deep-link routing are unchanged.
+- **[issue-2838] Route inline `fetch('/api/...')` calls through the client service layer** — the Prompt Manager's 13+ raw prompt/provider calls move into a new `services/apiPrompts.js` (stages, variables, job-skills), and the stray inline `/api/` fetches in `ImageGen`, `LocalSetupPanel`, `StagePromptModelPicker`, and `GsdTab` route through existing/new `apiX.js` wrappers. Behavior-preserving; VideoGen's remaining site is deferred to its own split issue to avoid double-touching that file.
 - **[issue-2835] Split the ~2875-line `ArcCanvas.jsx` into per-component files** — each of the 32 subcomponents/helpers (ArcHeader, EditorialRoadmapPanel, SeasonRow, IssueRow, VolumeCoversPanel, …) now lives in its own file under `client/src/components/pipeline/arcCanvas/`, with the shared severity-color map in `arcCanvas/shared.js`. `ArcCanvas.jsx` (default export) is now a thin 122-line composer and still re-exports `ArcRoadmapChart` so its public import path is unchanged. Pure mechanical, behavior-preserving refactor — no rendered-output change.
diff --git a/client/src/components/apps/tabs/GsdTab.jsx b/client/src/components/apps/tabs/GsdTab.jsx
index 5535bad5a..bd2825e97 100644
--- a/client/src/components/apps/tabs/GsdTab.jsx
+++ b/client/src/components/apps/tabs/GsdTab.jsx
@@ -253,25 +253,18 @@ export default function GsdTab({ appId, repoPath }) {
     setLoading(true);
 
     // Fetch GSD status from documents endpoint (silent, no toast)
-    const docsResp = await fetch(`/api/apps/${appId}/documents`).catch(() => null);
-    const docsData = docsResp?.ok ? await docsResp.json().catch(() => null) : null;
+    const docsData = await api.getAppDocuments(appId, { silent: true }).catch(() => null);
     const gsd = docsData?.gsd || {};
     setGsdStatus(gsd);
 
     // Only fetch project data if we have a roadmap + state (full project)
     if (gsd.hasRoadmap && gsd.hasState) {
-      const [projectResp, phasesResp] = await Promise.all([
-        fetch(`/api/cos/gsd/projects/${appId}`).catch(() => null),
-        fetch(`/api/cos/gsd/projects/${appId}/phases`).catch(() => null),
+      const [projectData, phasesData] = await Promise.all([
+        api.getGsdProject(appId, { silent: true }).catch(() => null),
+        api.getGsdPhases(appId, { silent: true }).catch(() => null),
       ]);
-      if (projectResp?.ok) {
-        const data = await projectResp.json().catch(() => null);
-        setProject(data);
-      }
-      if (phasesResp?.ok) {
-        const data = await phasesResp.json().catch(() => null);
-        setPendingActions(data?.pendingActions || []);
-      }
+      if (projectData) setProject(projectData);
+      if (phasesData) setPendingActions(phasesData.pendingActions || []);
     } else {
       setProject(null);
       setPendingActions([]);
diff --git a/client/src/components/settings/LocalSetupPanel.jsx b/client/src/components/settings/LocalSetupPanel.jsx
index 8e37b07d6..474b6df49 100644
--- a/client/src/components/settings/LocalSetupPanel.jsx
+++ b/client/src/components/settings/LocalSetupPanel.jsx
@@ -6,6 +6,7 @@ import BrailleSpinner from '../BrailleSpinner';
 import { usePrevious } from '../../hooks/usePrevious.js';
 import { useInstallStream } from '../../hooks/useInstallStream.js';
 import useMounted from '../../hooks/useMounted.js';
+import { checkImageGenSetup, detectImageGenPython, createImageGenVenv } from '../../services/api';
 
 export default function LocalSetupPanel({ pythonPath, onPythonPathChange, onPackagesChanged }) {
   const [detecting, setDetecting] = useState(false);
@@ -54,10 +55,9 @@ export default function LocalSetupPanel({ pythonPath, onPythonPathChange, onPack
     checkAbortRef.current = controller;
     setChecking(true);
     try {
-      const res = await fetch(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(path)}`, { signal: controller.signal });
+      const data = await checkImageGenSetup({ pythonPath: path, signal: controller.signal });
       if (!mountedRef.current) return;
-      if (!res.ok) { setCheck(null); return; }
-      setCheck(await res.json());
+      setCheck(data);
     } catch (err) {
       // Aborted (unmount or superseded) — leave state alone.
       if (err?.name === 'AbortError') return;
@@ -120,9 +120,9 @@ export default function LocalSetupPanel({ pythonPath, onPythonPathChange, onPack
   const handleDetect = async () => {
     setDetecting(true);
     try {
-      const res = await fetch('/api/image-gen/setup/python');
-      if (!res.ok) { toast.error('Detection failed'); return; }
-      const { path } = await res.json();
+      const result = await detectImageGenPython();
+      if (!result) { toast.error('Detection failed'); return; }
+      const { path } = result;
       if (path) {
         onPythonPathChange(path);
         toast.success(`Detected ${path}`);
@@ -147,21 +147,11 @@ export default function LocalSetupPanel({ pythonPath, onPythonPathChange, onPack
   const handleCreateVenv = async () => {
     setCreatingVenv(true);
     try {
-      const res = await fetch('/api/image-gen/setup/create-venv', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-      });
-      if (!res.ok) {
-        const json = await res.json().catch(() => ({}));
-        toast.error(json.error || 'Venv creation failed');
-        return;
-      }
-      const { pythonPath: venvPython } = await res.json();
+      const { pythonPath: venvPython } = await createImageGenVenv();
       onPythonPathChange(venvPython);
       toast.success(`Created venv at ${venvPython}`);
-    } catch {
-      toast.error('Failed to create venv');
+    } catch (err) {
+      toast.error(err.message || 'Failed to create venv');
     } finally {
       // Always clear so a fetch reject doesn't leave the button disabled.
       setCreatingVenv(false);
diff --git a/client/src/components/writers-room/StagePromptModelPicker.jsx b/client/src/components/writers-room/StagePromptModelPicker.jsx
index 54269723b..f43c54f36 100644
--- a/client/src/components/writers-room/StagePromptModelPicker.jsx
+++ b/client/src/components/writers-room/StagePromptModelPicker.jsx
@@ -11,6 +11,8 @@ import {
   TIMEOUT_INPUT_MAX_MS,
   TIMEOUT_INPUT_STEP_MS,
 } from '../../utils/formatters';
+import { getPrompt, savePrompt } from '../../services/apiPrompts';
+import { getProviders } from '../../services/apiProviders';
 
 /**
  * Inline picker for a prompt stage's provider+model. Mirrors the Tier/Specific
@@ -30,8 +32,8 @@ export default function StagePromptModelPicker({ stageName, label = 'Stage LLM',
     const controller = new AbortController();
     const { signal } = controller;
     Promise.all([
-      fetch(`/api/prompts/${encodeURIComponent(stageName)}`, { signal }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
-      fetch('/api/providers', { signal }).then((r) => (r.ok ? r.json() : null)).catch(() => null),
+      getPrompt(stageName, { signal, silent: true }).catch(() => null),
+      getProviders({ signal, silent: true }).catch(() => null),
     ]).then(([s, p]) => {
       if (cancelled) return;
       // Normalize stage.timeout through parseTimeoutMs so a legacy on-disk
@@ -65,17 +67,16 @@ export default function StagePromptModelPicker({ stageName, label = 'Stage LLM',
     if ('provider' in next) body.provider = next.provider ?? null;
     if ('model' in next) body.model = next.model;
     if ('timeout' in next) body.timeout = next.timeout;
-    const res = await fetch(`/api/prompts/${encodeURIComponent(stageName)}`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-    });
+    let errMsg = null;
+    const ok = await savePrompt(stageName, body, { silent: true })
+      .then(() => true)
+      .catch((err) => { errMsg = err.message; return false; });
     setSaving(false);
-    if (!res.ok) {
+    if (!ok) {
       // Roll back the optimistic update so the picker UI doesn't show a
       // provider/model that wasn't actually persisted server-side.
       setStage(prevStage);
-      toast.error(`Failed to save ${label}: ${await res.text().catch(() => res.statusText)}`);
+      toast.error(`Failed to save ${label}: ${errMsg}`);
     }
   };
 
diff --git a/client/src/pages/ImageGen.jsx b/client/src/pages/ImageGen.jsx
index 3a2db58b5..d776d669a 100644
--- a/client/src/pages/ImageGen.jsx
+++ b/client/src/pages/ImageGen.jsx
@@ -47,9 +47,10 @@ import { useImageGenProgress } from '../hooks/useImageGenProgress';
 import { useMediaJobSse } from '../hooks/useMediaJobSse';
 import { useModelDownloadStatus } from '../hooks/useModelDownloadStatus';
 import {
-  getImageGenStatus, generateImage, listImageModels, listLorasFull, listImageGallery,
+  getImageGenStatus, generateImage, generateImageMultipart, listImageModels, listLorasFull, listImageGallery,
   cancelImageGen, deleteImage, setImageHidden, cleanGalleryImage, getActiveImageJob, getSettings,
   buildFormData, listMediaJobs, regenerateGalleryImage, getRegenAvailability, removeImageWatermark,
+  getFlux2Status, getHfTokenStatus,
 } from '../services/api';
 
 // Multi-reference editing (FLUX.2 only) — 4 fixed slots, each carrying an
@@ -617,16 +618,13 @@ export default function ImageGen() {
   const currentCompatKey = loraCompatKey(currentModel);
 
   const refreshFlux2Status = useCallback((signal) => {
-    const qs = modelId ? `?modelId=${encodeURIComponent(modelId)}` : '';
-    return fetch(`/api/image-gen/setup/flux2-status${qs}`, { signal })
-      .then((r) => r.ok ? r.json() : null)
+    return getFlux2Status({ modelId, signal })
       .then((s) => { if (s) setFlux2Status(s); })
       .catch(() => {});
   }, [modelId]);
 
   const refreshHfTokenStatus = useCallback((signal) => {
-    return fetch('/api/image-gen/setup/hf-token-status', { signal })
-      .then((r) => r.ok ? r.json() : null)
+    return getHfTokenStatus({ signal })
       .then((s) => { if (s) setHfTokenPresent(!!s.hfTokenPresent); })
       .catch(() => {});
   }, []);
@@ -763,12 +761,7 @@ export default function ImageGen() {
         referenceStrengths: populatedRefs.map((s) => s.strength),
       } : {};
       const fd = buildFormData({ ...payload, ...initFields, ...refFields });
-      const res = await fetch('/api/image-gen/generate', { method: 'POST', body: fd });
-      if (!res.ok) {
-        const body = await res.json().catch(() => ({ error: `HTTP ${res.status}` }));
-        throw new Error(body.error || `HTTP ${res.status}`);
-      }
-      return { payload, data: await res.json() };
+      return { payload, data: await generateImageMultipart(fd, { silent: true }) };
     }
     return { payload, data: await generateImage(payload, { silent: true }) };
   };
diff --git a/client/src/pages/PromptManager.jsx b/client/src/pages/PromptManager.jsx
index da82d4cd6..80cc5def4 100644
--- a/client/src/pages/PromptManager.jsx
+++ b/client/src/pages/PromptManager.jsx
@@ -16,6 +16,12 @@ import useFieldDraft from '../hooks/useFieldDraft';
 import SettingsTabsHeader from '../components/settings/SettingsTabsHeader';
 import { FormField } from '../components/ui/FormField';
 import Modal from '../components/ui/Modal';
+import {
+  getPrompts, getPrompt, createPrompt, savePrompt, deletePrompt, previewPrompt, getPromptUsage,
+  getPromptVariables, createPromptVariable, savePromptVariable, deletePromptVariable,
+  getJobSkills, getJobSkill, saveJobSkill as apiSaveJobSkill, previewJobSkill as apiPreviewJobSkill,
+} from '../services/apiPrompts';
+import { getProviders } from '../services/apiProviders';
 
 const VALID_PROMPT_TABS = ['stages', 'variables', 'job-skills'];
 
@@ -93,10 +99,10 @@ export default function PromptManager() {
   const loadData = async () => {
     setLoading(true);
     const [stagesRes, varsRes, jobSkillsRes, providersRes] = await Promise.all([
-      fetch('/api/prompts').then(r => r.json()),
-      fetch('/api/prompts/variables').then(r => r.json()),
-      fetch('/api/prompts/skills/jobs').then(r => r.json()).catch(() => ({ skills: [] })),
-      fetch('/api/providers').then(r => r.json()).catch(() => ({ providers: [] }))
+      getPrompts({ silent: true }).catch(() => ({ stages: {} })),
+      getPromptVariables({ silent: true }).catch(() => ({ variables: {} })),
+      getJobSkills({ silent: true }).catch(() => ({ skills: [] })),
+      getProviders({ silent: true }).catch(() => ({ providers: [] }))
     ]);
     setStages(stagesRes.stages || {});
     setVariables(varsRes.variables || {});
@@ -111,8 +117,7 @@ export default function PromptManager() {
   useEffect(() => {
     if (!selectedStage) { setStageTemplate(''); setStageConfig({}); setPreview(''); return; }
     let cancelled = false;
-    fetch(`/api/prompts/${selectedStage}`)
-      .then(r => (r.ok ? r.json() : null))
+    getPrompt(selectedStage, { silent: true })
       .then(res => {
         if (cancelled || !res) return;
         setStageTemplate(res.template || '');
@@ -140,24 +145,18 @@ export default function PromptManager() {
     const payload = { template: stageTemplate, ...stageConfig };
     // Explicitly null provider when in tier mode so server clears any previous value
     if (!payload.provider) payload.provider = null;
-    const res = await fetch(`/api/prompts/${selectedStage}`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload)
-    });
-    if (!res.ok) { toast.error('Failed to save stage: ' + await res.text()); setSaving(false); return; }
+    const ok = await savePrompt(selectedStage, payload, { silent: true })
+      .then(() => true)
+      .catch((err) => { toast.error('Failed to save stage: ' + err.message); return false; });
+    if (!ok) { setSaving(false); return; }
     setSaving(false);
     await loadData();
   };
 
   const previewStage = async () => {
-    const res = await fetch(`/api/prompts/${selectedStage}/preview`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ testData: {} })
-    });
-    if (!res.ok) { toast.error('Failed to preview: ' + await res.text()); return; }
-    const data = await res.json();
+    const data = await previewPrompt(selectedStage, {}, { silent: true })
+      .catch((err) => { toast.error('Failed to preview: ' + err.message); return null; });
+    if (!data) return;
     setPreview(data.preview);
   };
 
@@ -183,14 +182,12 @@ export default function PromptManager() {
 
   const saveVariable = async () => {
     setSaving(true);
-    const url = selectedVar ? `/api/prompts/variables/${selectedVar}` : '/api/prompts/variables';
-    const method = selectedVar ? 'PUT' : 'POST';
-    const res = await fetch(url, {
-      method,
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(varForm)
-    });
-    if (!res.ok) { toast.error('Failed to save variable: ' + await res.text()); setSaving(false); return; }
+    const ok = await (selectedVar
+      ? savePromptVariable(selectedVar, varForm, { silent: true })
+      : createPromptVariable(varForm, { silent: true }))
+      .then(() => true)
+      .catch((err) => { toast.error('Failed to save variable: ' + err.message); return false; });
+    if (!ok) { setSaving(false); return; }
     setSaving(false);
     setSelectedVar(null);
     setVarForm({ key: '', name: '', category: '', content: '' });
@@ -198,8 +195,10 @@ export default function PromptManager() {
   };
 
   const deleteVariable = async (key) => {
-    const res = await fetch(`/api/prompts/variables/${key}`, { method: 'DELETE' });
-    if (!res.ok) { toast.error('Failed to delete variable: ' + await res.text()); return; }
+    const ok = await deletePromptVariable(key, { silent: true })
+      .then(() => true)
+      .catch((err) => { toast.error('Failed to delete variable: ' + err.message); return false; });
+    if (!ok) return;
     if (selectedVar === key) setSelectedVar(null);
     await loadData();
   };
@@ -214,22 +213,10 @@ export default function PromptManager() {
     const payload = { ...newStageForm };
     // Strip provider field when in tier mode
     if (!payload.provider) delete payload.provider;
-    const res = await fetch('/api/prompts', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload)
-    });
-
-    if (!res.ok) {
-      let message = 'Failed to create stage';
-      const errorBody = await res.json().catch(() => null);
-      if (errorBody?.error || errorBody?.message) {
-        message = errorBody.error || errorBody.message;
-      }
-      setSaving(false);
-      toast.error(message);
-      return;
-    }
+    const ok = await createPrompt(payload, { silent: true })
+      .then(() => true)
+      .catch((err) => { setSaving(false); toast.error(err.message || 'Failed to create stage'); return false; });
+    if (!ok) return;
 
     setSaving(false);
     setCreatingStage(false);
@@ -247,10 +234,8 @@ export default function PromptManager() {
 
   const requestDeleteStage = async (stageName) => {
     // Check if stage is in use
-    const usageResponse = await fetch(`/api/prompts/${stageName}/usage`).catch(() => null);
-    const usageRes = (!usageResponse || !usageResponse.ok)
-      ? { isSystemStage: false, usedBy: [] }
-      : await usageResponse.json().catch(() => ({ isSystemStage: false, usedBy: [] }));
+    const usageRes = await getPromptUsage(stageName, { silent: true })
+      .catch(() => ({ isSystemStage: false, usedBy: [] }));
 
     setDeleteConfirm({ stageName, ...usageRes });
   };
@@ -259,22 +244,11 @@ export default function PromptManager() {
     const { stageName, isSystemStage } = deleteConfirm;
     setDeleteConfirm(null);
 
-    const url = isSystemStage
-      ? `/api/prompts/${stageName}?force=true`
-      : `/api/prompts/${stageName}`;
-
-    const res = await fetch(url, { method: 'DELETE' }).catch(err => {
-      toast.error(`Failed to delete: ${err.message}`);
-      return null;
-    });
+    const ok = await deletePrompt(stageName, { force: isSystemStage }, { silent: true })
+      .then(() => true)
+      .catch((err) => { toast.error(`Failed to delete: ${err.message || 'Unknown error'}`); return false; });
 
-    if (!res) return;
-
-    if (!res.ok) {
-      const error = await res.json().catch(() => ({}));
-      toast.error(`Failed to delete: ${error.error || 'Unknown error'}`);
-      return;
-    }
+    if (!ok) return;
 
     if (selectedStage === stageName) {
       setSelectedStage(null);
@@ -286,23 +260,19 @@ export default function PromptManager() {
   const loadJobSkill = async (name) => {
     setSelectedJobSkill(name);
     setJobSkillPreview('');
-    const res = await fetch(`/api/prompts/skills/jobs/${name}`).then(r => r.json());
+    const res = await getJobSkill(name, { silent: true });
     setJobSkillContent(res.content || '');
     setJobSkillMeta({ jobName: res.jobName, jobId: res.jobId, category: res.category, interval: res.interval });
   };
 
   const saveJobSkill = async () => {
     setSaving(true);
-    await fetch(`/api/prompts/skills/jobs/${selectedJobSkill}`, {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ content: jobSkillContent })
-    });
+    await apiSaveJobSkill(selectedJobSkill, jobSkillContent, { silent: true });
     setSaving(false);
   };
 
   const previewJobSkill = async () => {
-    const res = await fetch(`/api/prompts/skills/jobs/${selectedJobSkill}/preview`).then(r => r.json());
+    const res = await apiPreviewJobSkill(selectedJobSkill, { silent: true });
     setJobSkillPreview(res.preview || '');
   };
 
diff --git a/client/src/services/README.md b/client/src/services/README.md
index 956e098e3..9164e8b7d 100644
--- a/client/src/services/README.md
+++ b/client/src/services/README.md
@@ -50,6 +50,7 @@ toasts on throw). **Custom catch ⇒ `silent: true`** — otherwise toasts fire
 | `apiLogs.js` | PM2 system logs: fetch a process's recent log tail (process list comes from `apiCommands.getProcessesList`). |
 | `apiPorts.js` | Port forwarding / allocation. |
 | `apiProviders.js` | AI provider config. |
+| `apiPrompts.js` | Prompt Manager: stage templates, variables, and job-skill templates (providers list reuses `apiProviders.getProviders`). |
 | `apiReferenceRepos.js` | Per-app reference-repo registry. |
 | `apiReview.js` | Review hub. |
 | `apiCodeReview.js` | Code Review Defaults (Review Loop reviewer chain + per-backend local-LLM model). |
diff --git a/client/src/services/api.js b/client/src/services/api.js
index 592594db7..3d28f9daf 100644
--- a/client/src/services/api.js
+++ b/client/src/services/api.js
@@ -10,6 +10,7 @@ export * from './apiReferenceRepos.js';
 export * from './apiPorts.js';
 export * from './apiScaffold.js';
 export * from './apiProviders.js';
+export * from './apiPrompts.js';
 export * from './apiRuns.js';
 export * from './apiHistory.js';
 export * from './apiLogs.js';
diff --git a/client/src/services/apiApps.js b/client/src/services/apiApps.js
index 1dc9022ec..f446192fc 100644
--- a/client/src/services/apiApps.js
+++ b/client/src/services/apiApps.js
@@ -112,7 +112,7 @@ export const installXcodeScripts = (id, scripts) => request(`/apps/${id}/xcode-s
   method: 'POST',
   body: JSON.stringify({ scripts })
 });
-export const getAppDocuments = (id) => request(`/apps/${id}/documents`);
+export const getAppDocuments = (id, options) => request(`/apps/${id}/documents`, options);
 export const getAppDocument = (id, filename) => request(`/apps/${id}/documents/${filename}`);
 export const saveAppDocument = (id, filename, content, commitMessage) =>
   request(`/apps/${id}/documents/${filename}`, {
diff --git a/client/src/services/apiGSD.js b/client/src/services/apiGSD.js
index 14205af21..a2d9349ea 100644
--- a/client/src/services/apiGSD.js
+++ b/client/src/services/apiGSD.js
@@ -4,7 +4,7 @@ import { request } from './apiCore.js';
 export const getGsdProjects = () => request('/cos/gsd/projects');
 export const getGsdProject = (appId, options = {}) => request(`/cos/gsd/projects/${appId}`, options);
 export const getGsdConcerns = (appId) => request(`/cos/gsd/projects/${appId}/concerns`);
-export const getGsdPhases = (appId) => request(`/cos/gsd/projects/${appId}/phases`);
+export const getGsdPhases = (appId, options) => request(`/cos/gsd/projects/${appId}/phases`, options);
 export const getGsdPhase = (appId, phaseId) => request(`/cos/gsd/projects/${appId}/phases/${phaseId}`);
 export const createGsdConcernTasks = (appId, data, options = {}) => request(`/cos/gsd/projects/${appId}/concerns/tasks`, {
   method: 'POST',
diff --git a/client/src/services/apiImageVideo.js b/client/src/services/apiImageVideo.js
index 126709559..62a0f32ff 100644
--- a/client/src/services/apiImageVideo.js
+++ b/client/src/services/apiImageVideo.js
@@ -101,13 +101,55 @@ export const rerenderWithAnnotations = (filename, { strength, steps, prompt } =
 
 // HuggingFace token (gated local Flux models). Stored in settings.imageGen.hfToken;
 // reads fall back to HF_TOKEN env var and then ~/.cache/huggingface/token.
-export const getHfTokenStatus = () => request('/image-gen/setup/hf-token-status', { silent: true });
+// Silent — callers own their own error UI. `signal` lets a page cancel a stale
+// probe on unmount / model switch.
+export const getHfTokenStatus = ({ signal } = {}) => request('/image-gen/setup/hf-token-status', { silent: true, signal });
 export const saveHfToken = (token) => request('/image-gen/setup/hf-token', {
   method: 'POST',
   body: JSON.stringify({ token }),
 });
 export const clearHfToken = () => request('/image-gen/setup/hf-token', { method: 'DELETE' });
 
+// FLUX.2 setup probe (weights/deps present for the selected model?). Silent so a
+// stale poll doesn't toast; `signal` cancels it on model switch / unmount.
+export const getFlux2Status = ({ modelId, signal } = {}) =>
+  request(`/image-gen/setup/flux2-status${modelId ? `?modelId=${encodeURIComponent(modelId)}` : ''}`, { silent: true, signal });
+
+// External/local image generation with an init or reference image attached —
+// multipart because the payload carries File uploads. request() detects the
+// FormData body and lets the browser set the multipart boundary itself.
+export const generateImageMultipart = (formData, options = {}) => request('/image-gen/generate', {
+  method: 'POST',
+  body: formData,
+  ...options,
+});
+
+// Local Python-runtime setup probes (LocalSetupPanel). These use fetch() rather
+// than request() because the caller distinguishes intentional AbortError (a
+// superseded/unmounted probe) from a real failure — request()'s catch collapses
+// abort into a generic error. Return the parsed body on 2xx, null on a non-OK
+// response; abort/network rejections propagate so the caller can inspect them.
+export async function checkImageGenSetup({ pythonPath, signal } = {}) {
+  const res = await fetch(`/api/image-gen/setup/check?pythonPath=${encodeURIComponent(pythonPath)}`, { signal });
+  return res.ok ? res.json() : null;
+}
+
+export async function detectImageGenPython() {
+  const res = await fetch('/api/image-gen/setup/python');
+  return res.ok ? res.json() : null;
+}
+
+export async function createImageGenVenv() {
+  const res = await fetch('/api/image-gen/setup/create-venv', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({}),
+  });
+  if (res.ok) return res.json();
+  const json = await res.json().catch(() => ({}));
+  throw new Error(json.error || 'Venv creation failed');
+}
+
 // Video gen
 export const getVideoGenStatus = () => request('/video-gen/status');
 export const listVideoModels = (options) => request('/video-gen/models', options);
diff --git a/client/src/services/apiPrompts.js b/client/src/services/apiPrompts.js
new file mode 100644
index 000000000..3a6d83f98
--- /dev/null
+++ b/client/src/services/apiPrompts.js
@@ -0,0 +1,58 @@
+import { request } from './apiCore.js';
+
+// Prompt stages, variables, and job skills for the Prompt Manager and the
+// inline StagePromptModelPicker. The `/api/providers` list these surfaces also
+// need lives in apiProviders.js (`getProviders`) — reuse it rather than
+// re-wrapping the same endpoint here.
+//
+// `options` (e.g. { silent: true }) lets callers that own their own error UI
+// (custom catch + toast) suppress the request() helper's default toast.
+
+// Stages
+export const getPrompts = (options) => request('/prompts', options);
+export const getPrompt = (stage, options) => request(`/prompts/${encodeURIComponent(stage)}`, options);
+export const createPrompt = (data, options = {}) => request('/prompts', {
+  method: 'POST',
+  body: JSON.stringify(data),
+  ...options,
+});
+export const savePrompt = (stage, data, options = {}) => request(`/prompts/${encodeURIComponent(stage)}`, {
+  method: 'PUT',
+  body: JSON.stringify(data),
+  ...options,
+});
+export const deletePrompt = (stage, { force = false } = {}, options = {}) =>
+  request(`/prompts/${encodeURIComponent(stage)}${force ? '?force=true' : ''}`, { method: 'DELETE', ...options });
+export const previewPrompt = (stage, testData = {}, options = {}) => request(`/prompts/${encodeURIComponent(stage)}/preview`, {
+  method: 'POST',
+  body: JSON.stringify({ testData }),
+  ...options,
+});
+export const getPromptUsage = (stage, options) => request(`/prompts/${encodeURIComponent(stage)}/usage`, options);
+
+// Variables
+export const getPromptVariables = (options) => request('/prompts/variables', options);
+export const createPromptVariable = (data, options = {}) => request('/prompts/variables', {
+  method: 'POST',
+  body: JSON.stringify(data),
+  ...options,
+});
+export const savePromptVariable = (key, data, options = {}) => request(`/prompts/variables/${encodeURIComponent(key)}`, {
+  method: 'PUT',
+  body: JSON.stringify(data),
+  ...options,
+});
+export const deletePromptVariable = (key, options = {}) => request(`/prompts/variables/${encodeURIComponent(key)}`, {
+  method: 'DELETE',
+  ...options,
+});
+
+// Autonomous job-skill prompt templates
+export const getJobSkills = (options) => request('/prompts/skills/jobs', options);
+export const getJobSkill = (name, options) => request(`/prompts/skills/jobs/${encodeURIComponent(name)}`, options);
+export const saveJobSkill = (name, content, options = {}) => request(`/prompts/skills/jobs/${encodeURIComponent(name)}`, {
+  method: 'PUT',
+  body: JSON.stringify({ content }),
+  ...options,
+});
+export const previewJobSkill = (name, options) => request(`/prompts/skills/jobs/${encodeURIComponent(name)}/preview`, options);

From 9ac3929bceb73b74b607dcf2da6ceeb839452832 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 21 Jul 2026 18:29:15 -0700
Subject: [PATCH 2/3] preserve graceful degradation in job-skill
 load/save/preview

---
 client/src/pages/PromptManager.jsx | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/client/src/pages/PromptManager.jsx b/client/src/pages/PromptManager.jsx
index 80cc5def4..055d59c1a 100644
--- a/client/src/pages/PromptManager.jsx
+++ b/client/src/pages/PromptManager.jsx
@@ -260,19 +260,21 @@ export default function PromptManager() {
   const loadJobSkill = async (name) => {
     setSelectedJobSkill(name);
     setJobSkillPreview('');
-    const res = await getJobSkill(name, { silent: true });
+    const res = await getJobSkill(name, { silent: true }).catch(() => ({}));
     setJobSkillContent(res.content || '');
     setJobSkillMeta({ jobName: res.jobName, jobId: res.jobId, category: res.category, interval: res.interval });
   };
 
   const saveJobSkill = async () => {
     setSaving(true);
-    await apiSaveJobSkill(selectedJobSkill, jobSkillContent, { silent: true });
+    // Swallow errors (matches the prior fire-and-forget PUT) but always clear
+    // the saving flag so a failure can't leave the Save button stuck disabled.
+    await apiSaveJobSkill(selectedJobSkill, jobSkillContent, { silent: true }).catch(() => {});
     setSaving(false);
   };
 
   const previewJobSkill = async () => {
-    const res = await apiPreviewJobSkill(selectedJobSkill, { silent: true });
+    const res = await apiPreviewJobSkill(selectedJobSkill, { silent: true }).catch(() => ({}));
     setJobSkillPreview(res.preview || '');
   };
 

From 66823ea905e74822f886afda7462066facc4292e Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Wed, 22 Jul 2026 07:37:40 -0700
Subject: [PATCH 3/3] route useTheme's settings read/write through apiSystem
 instead of inline fetch

Completes the #2838 sweep: useTheme was the last inline fetch('/api/...')
outside client/src/services. Both calls pass { silent: true } since the hook
already degrades to the localStorage theme and warns on its own, and the
GET's abort guard now also checks controller.signal.aborted because request()
collapses an aborted fetch into a generic error.
---
 .changelog/NEXT.md           |  2 +-
 client/src/hooks/useTheme.js | 19 +++++++++++--------
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/.changelog/NEXT.md b/.changelog/NEXT.md
index a5c577191..1e64ceca6 100644
--- a/.changelog/NEXT.md
+++ b/.changelog/NEXT.md
@@ -37,5 +37,5 @@
 
 - **[issue-2832] Split the boot-schema DDL into per-domain modules** — the ~1265-line inline `CREATE TABLE`/`CREATE INDEX`/trigger block in `ensureSchemaImpl()` (`server/lib/db.js`) is extracted into per-domain modules under `server/lib/db/schema/` (catalog, media, universes, writers-room, pipeline, privacy, tribe, audit, …), each exporting a statement array; `ensureSchemaImpl` is now a thin composer. Statement text and order are byte-identical, so the composed schema is unchanged.
 - **[issue-2834] Split the ~1990-line `VideoGen.jsx` into hooks + subcomponents** — the client-side batch-queue orchestration moves into `useVideoGenQueue`, the pure model-memory / FFLF frame-budget / mode-compat helpers into `lib/videoGenParams.js`, and four presentational blocks into `components/videoGen/` (`RuntimeFingerprint`, `ModelRepairBanner`, `VideoPreviewPanel`, `VideoGenGallery`). The inline runtime-status `fetch()` now routes through a `getVideoGenRuntimeStatus` service wrapper, and the Seed input gains a proper `<label htmlFor>`/`id` pairing. Behavior and deep-link routing are unchanged.
-- **[issue-2838] Route inline `fetch('/api/...')` calls through the client service layer** — the Prompt Manager's 13+ raw prompt/provider calls move into a new `services/apiPrompts.js` (stages, variables, job-skills), and the stray inline `/api/` fetches in `ImageGen`, `LocalSetupPanel`, `StagePromptModelPicker`, and `GsdTab` route through existing/new `apiX.js` wrappers. Behavior-preserving; VideoGen's remaining site is deferred to its own split issue to avoid double-touching that file.
+- **[issue-2838] Route inline `fetch('/api/...')` calls through the client service layer** — the Prompt Manager's 13+ raw prompt/provider calls move into a new `services/apiPrompts.js` (stages, variables, job-skills), and the stray inline `/api/` fetches in `ImageGen`, `LocalSetupPanel`, `StagePromptModelPicker`, and `GsdTab` route through existing/new `apiX.js` wrappers. `useTheme`'s settings read/write now go through `apiSystem.getSettings`/`updateSettings` (silent, so the local-storage fallback stays the only error surface), which clears the last inline `/api/` fetch outside `services/`. Behavior-preserving; VideoGen's site was already routed through a service wrapper by the VideoGen split (#2834).
 - **[issue-2835] Split the ~2875-line `ArcCanvas.jsx` into per-component files** — each of the 32 subcomponents/helpers (ArcHeader, EditorialRoadmapPanel, SeasonRow, IssueRow, VolumeCoversPanel, …) now lives in its own file under `client/src/components/pipeline/arcCanvas/`, with the shared severity-color map in `arcCanvas/shared.js`. `ArcCanvas.jsx` (default export) is now a thin 122-line composer and still re-exports `ArcRoadmapChart` so its public import path is unchanged. Pure mechanical, behavior-preserving refactor — no rendered-output change.
diff --git a/client/src/hooks/useTheme.js b/client/src/hooks/useTheme.js
index a8d3dbcb2..41bbc17fe 100644
--- a/client/src/hooks/useTheme.js
+++ b/client/src/hooks/useTheme.js
@@ -11,6 +11,7 @@ import {
   TIME_OF_DAY_AUTO_EVENT as CITY_TIME_OF_DAY_AUTO_EVENT,
 } from './useCitySettings';
 import { safeReadStorage, safeWriteStorage } from '../lib/safeStorage.js';
+import { getSettings, updateSettings } from '../services/apiSystem.js';
 
 const STORAGE_KEY = 'portos-theme';
 
@@ -61,8 +62,9 @@ export default function useTheme() {
 
   useEffect(() => {
     const controller = new AbortController();
-    fetch('/api/settings', { signal: controller.signal })
-      .then(r => r.ok ? r.json() : null)
+    // Silent — a failed read just falls back to localStorage (handled below),
+    // so the request() helper must not toast on top of our own warn.
+    getSettings({ silent: true, signal: controller.signal })
       .then(settings => {
         if (userPickedRef.current) return;
         const serverTheme = settings?.theme ? normalizeThemeId(settings.theme) : null;
@@ -77,7 +79,9 @@ export default function useTheme() {
         }
       })
       .catch((err) => {
-        if (err.name === 'AbortError') return;
+        // request() collapses an aborted fetch into a generic error, so check
+        // the controller too — an unmount/StrictMode remount isn't a failure.
+        if (controller.signal.aborted || err.name === 'AbortError') return;
         console.warn(`⚠️ Theme fetch failed, using localStorage fallback: ${err.message}`);
       });
     return () => controller.abort();
@@ -92,11 +96,10 @@ export default function useTheme() {
     setThemeId(normalized);
     safeWriteStorage(STORAGE_KEY, normalized);
     resetCityTimeOfDayOverride();
-    fetch('/api/settings', {
-      method: 'PUT',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ theme: normalized }),
-    }).catch(() => console.warn('Theme sync to server failed'));
+    // Silent — the theme is already applied locally; a failed sync only warrants
+    // a console warning, not a toast on every theme switch.
+    updateSettings({ theme: normalized }, { silent: true })
+      .catch(() => console.warn('⚠️ Theme sync to server failed'));
   }, []);
 
   const toggleMode = useCallback(() => {