From a00f4ba1fad8310b08b3a9614e83fd4ddef067b2 Mon Sep 17 00:00:00 2001
From: SNPAU <SNPAU@users.noreply.github.com>
Date: Mon, 10 Aug 2026 15:16:00 +1000
Subject: [PATCH 1/7] Add image prompt instructions to connections

---
 CHANGELOG.md                                  |  1 +
 .../connections/ConnectionEditor.tsx          | 24 +++++++++++++++++++
 packages/client/src/hooks/use-connections.ts  |  1 +
 .../client/src/lib/connection-transfer.ts     |  4 ++++
 .../client/src/localization/locales/en.json   |  3 +++
 packages/server/src/db/schema/connections.ts  |  2 ++
 packages/server/src/routes/gallery.routes.ts  |  8 +++++--
 packages/server/src/routes/generate.routes.ts | 14 +++++++++++
 .../src/routes/generate/retry-agents-route.ts | 24 +++++++++++++++++++
 .../src/services/agents/agent-executor.ts     | 14 ++++++++++-
 .../conversation-selfie-command-runtime.ts    |  6 ++++-
 .../illustrator-manual-prompt-generation.ts   |  6 +++++
 .../generation/illustrator-prompt-runtime.ts  |  1 +
 .../services/storage/connections.storage.ts   |  5 ++++
 .../shared/src/schemas/connection.schema.ts   |  1 +
 packages/shared/src/types/connection.ts       |  2 ++
 16 files changed, 112 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 703c3572c1..3e193f8ed8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@ This file is the release-notes source of truth for Marinara Engine. Reuse these
 
 ### Added
 
+- Added optional image prompting instructions to image connections, applying them inside existing selfie and Illustrator prompt-writing calls before provider review or generation.
 - Added batch selection to Character and Persona image galleries so selected images can be downloaded or deleted together after confirmation (#4832).
 - Added a persisted Auto, Low, Medium, or High output-quality choice to GPT Image generation connections (#4831).
 - Added optional character and persona reference sheets under Sprites, with upload, size-bounded AI creation, safe selection cleanup, and an explicit generation-reference toggle that falls back to existing likeness art; both Galleries include the same AI creation entrypoint (#4786).
diff --git a/packages/client/src/components/connections/ConnectionEditor.tsx b/packages/client/src/components/connections/ConnectionEditor.tsx
index 961cbb18d2..f19fc063c7 100644
--- a/packages/client/src/components/connections/ConnectionEditor.tsx
+++ b/packages/client/src/components/connections/ConnectionEditor.tsx
@@ -299,6 +299,7 @@ export function ConnectionEditor() {
   const [localComfyuiWorkflow, setLocalComfyuiWorkflow] = useState("");
   const [localImageService, setLocalImageService] = useState<string | null>(null);
   const [localImageEndpointId, setLocalImageEndpointId] = useState("");
+  const [localImagePromptInstructions, setLocalImagePromptInstructions] = useState("");
   const [localImageGenerationQuality, setLocalImageGenerationQuality] = useState<ImageGenerationQuality>("auto");
   const [localVideoGenerationSource, setLocalVideoGenerationSource] = useState("");
   const [localVideoService, setLocalVideoService] = useState<string | null>(null);
@@ -418,6 +419,7 @@ export function ConnectionEditor() {
     setLocalComfyuiWorkflow((c.comfyuiWorkflow as string) ?? "");
     setLocalImageService(imageService);
     setLocalImageEndpointId((c.imageEndpointId as string) ?? "");
+    setLocalImagePromptInstructions((c.imagePromptInstructions as string) ?? "");
     setLocalImageGenerationQuality(
       c.imageGenerationQuality === "low" || c.imageGenerationQuality === "medium" || c.imageGenerationQuality === "high"
         ? c.imageGenerationQuality
@@ -719,6 +721,7 @@ export function ConnectionEditor() {
       imageService: isImageProvider ? localImageGenerationSource || localImageService || null : null,
       imageEndpointId:
         isImageProvider && selectedImageService === "runpod_comfyui" ? localImageEndpointId || null : null,
+      imagePromptInstructions: isImageProvider ? localImagePromptInstructions.trim() || null : null,
       imageGenerationQuality: isImageProvider ? localImageGenerationQuality : "auto",
       videoGenerationSource: isVideoProvider ? selectedVideoProvider || null : null,
       videoService: isVideoProvider ? selectedVideoDefaultsService : null,
@@ -818,6 +821,7 @@ export function ConnectionEditor() {
     localComfyuiWorkflow,
     localImageService,
     localImageEndpointId,
+    localImagePromptInstructions,
     localImageGenerationQuality,
     localMaxTokensOverride,
     localClaudeFastMode,
@@ -923,6 +927,7 @@ export function ConnectionEditor() {
       videoService,
       imageEndpointId:
         isImageProvider && selectedImageService === "runpod_comfyui" ? localImageEndpointId || null : null,
+      imagePromptInstructions: isImageProvider ? localImagePromptInstructions.trim() || null : null,
       imageGenerationQuality: isImageProvider ? localImageGenerationQuality : "auto",
       comfyuiWorkflow:
         isImageProvider || (isVideoProvider && videoProvider === "comfyui") ? localComfyuiWorkflow || null : null,
@@ -961,6 +966,7 @@ export function ConnectionEditor() {
     selectedVideoProvider,
     selectedImageService,
     localImageEndpointId,
+    localImagePromptInstructions,
     localImageGenerationQuality,
     localComfyuiWorkflow,
     localClaudeFastMode,
@@ -2008,6 +2014,24 @@ export function ConnectionEditor() {
             </FieldGroup>
           )}
 
+          {localProvider === "image_generation" && (
+            <FieldGroup
+              label={localizeUi("ui.connections.connectioneditor.imagePromptingInstructions")}
+              icon={<Sparkles size="0.875rem" className="text-sky-400" />}
+              help={localizeUi("ui.connections.connectioneditor.imagePromptingInstructionsHelp")}
+            >
+              <textarea
+                value={localImagePromptInstructions}
+                onChange={(event) => {
+                  setLocalImagePromptInstructions(event.target.value);
+                  markDirty();
+                }}
+                placeholder={localizeUi("ui.connections.connectioneditor.imagePromptingInstructionsPlaceholder")}
+                className="w-full min-h-[96px] resize-y rounded-xl bg-[var(--secondary)] px-3 py-2.5 text-sm outline-none ring-1 ring-[var(--border)] transition-shadow placeholder:text-[var(--muted-foreground)]/50 focus:ring-sky-400/50"
+              />
+            </FieldGroup>
+          )}
+
           {supportsGptImageQuality && (
             <FieldGroup
               label={localizeUi("ui.connections.connectioneditor.gptImageQuality")}
diff --git a/packages/client/src/hooks/use-connections.ts b/packages/client/src/hooks/use-connections.ts
index f36f0293c8..ec97b431bc 100644
--- a/packages/client/src/hooks/use-connections.ts
+++ b/packages/client/src/hooks/use-connections.ts
@@ -54,6 +54,7 @@ export type CreateConnectionPayload = {
   comfyuiWorkflow?: string | null;
   imageService?: string | null;
   imageEndpointId?: string | null;
+  imagePromptInstructions?: string | null;
   imageGenerationQuality?: ImageGenerationQuality;
   videoGenerationSource?: string | null;
   videoService?: string | null;
diff --git a/packages/client/src/lib/connection-transfer.ts b/packages/client/src/lib/connection-transfer.ts
index 8ed5678f58..a840b0a2be 100644
--- a/packages/client/src/lib/connection-transfer.ts
+++ b/packages/client/src/lib/connection-transfer.ts
@@ -29,6 +29,7 @@ export type ConnectionTransferRow = {
   videoService?: unknown;
   service?: unknown;
   imageEndpointId?: unknown;
+  imagePromptInstructions?: unknown;
   imageGenerationQuality?: unknown;
   comfyuiWorkflow?: unknown;
   treatAsLocalEndpoint?: unknown;
@@ -62,6 +63,7 @@ export type SafeConnectionExport = {
   videoGenerationSource: string | null;
   videoService: string | null;
   imageEndpointId: string | null;
+  imagePromptInstructions: string | null;
   imageGenerationQuality: ImageGenerationQuality;
   comfyuiWorkflow: string | null;
   treatAsLocalEndpoint: boolean;
@@ -133,6 +135,7 @@ export function normalizeImportedConnectionEntry(value: unknown): ConnectionImpo
       comfyuiWorkflow: asNullableString(value.comfyuiWorkflow),
       imageService,
       imageEndpointId: asNullableString(value.imageEndpointId),
+      imagePromptInstructions: asNullableString(value.imagePromptInstructions),
       imageGenerationQuality: asImageGenerationQuality(value.imageGenerationQuality),
       videoGenerationSource: provider === "video_generation" ? asNullableString(value.videoGenerationSource) : null,
       videoService,
@@ -177,6 +180,7 @@ function serializeConnectionForExport(connection: ConnectionTransferRow): SafeCo
     videoGenerationSource: isVideoProvider ? asNullableString(connection.videoGenerationSource) : null,
     videoService: isVideoProvider ? asNullableString(connection.videoService ?? connection.service) : null,
     imageEndpointId: asNullableString(connection.imageEndpointId),
+    imagePromptInstructions: asNullableString(connection.imagePromptInstructions),
     imageGenerationQuality: asImageGenerationQuality(connection.imageGenerationQuality),
     comfyuiWorkflow: asNullableString(connection.comfyuiWorkflow),
     treatAsLocalEndpoint: asBoolean(connection.treatAsLocalEndpoint),
diff --git a/packages/client/src/localization/locales/en.json b/packages/client/src/localization/locales/en.json
index 2a0da91b63..2ce2e0f0e0 100644
--- a/packages/client/src/localization/locales/en.json
+++ b/packages/client/src/localization/locales/en.json
@@ -4055,6 +4055,9 @@
   "ui.connections.connectioneditor.httpsUsCentral1AiplatformGoogleapisComV1ProjectsMy": "https://us-central1-aiplatform.googleapis.com/v1/projects/my-project/locations/us-central1",
   "ui.connections.connectioneditor.ifYourProxyOrLocalServerIsnTDetected": "If your proxy or local server isn't detected, Windows Defender Firewall may be blocking the connection. Open",
   "ui.connections.connectioneditor.imageCaptioning": "Image Captioning",
+  "ui.connections.connectioneditor.imagePromptingInstructions": "Image Prompting Instructions",
+  "ui.connections.connectioneditor.imagePromptingInstructionsHelp": "When set, Marinara makes one extra call to your default language model to apply these instructions, then sends the resulting prompt to this image backend. Useful for tags, quality tokens, negative-prompt conventions, or local/ComfyUI syntax.",
+  "ui.connections.connectioneditor.imagePromptingInstructionsPlaceholder": "Example: use comma-separated tags, add quality tokens, and keep negative terms separate.",
   "ui.connections.connectioneditor.imageQualityAuto": "Auto",
   "ui.connections.connectioneditor.imageQualityHigh": "High",
   "ui.connections.connectioneditor.imageQualityLow": "Low",
diff --git a/packages/server/src/db/schema/connections.ts b/packages/server/src/db/schema/connections.ts
index 99a9cdee40..0b11aa6167 100644
--- a/packages/server/src/db/schema/connections.ts
+++ b/packages/server/src/db/schema/connections.ts
@@ -63,6 +63,8 @@ export const apiConnections = fileTable("api_connections", {
   imageService: text("image_service"),
   /** For endpoint-based image services (e.g. RunPod Serverless ComfyUI): the endpoint ID. */
   imageEndpointId: text("image_endpoint_id"),
+  /** Instructions passed to the default language model before image generation. */
+  imagePromptInstructions: text("image_prompt_instructions"),
   /** OpenAI GPT Image quality for this connection. */
   imageGenerationQuality: text("image_generation_quality").notNull().default("auto"),
   /** Explicit video backend selection for video-generation connections. */
diff --git a/packages/server/src/routes/gallery.routes.ts b/packages/server/src/routes/gallery.routes.ts
index 501d26aa3b..1dfa07860c 100644
--- a/packages/server/src/routes/gallery.routes.ts
+++ b/packages/server/src/routes/gallery.routes.ts
@@ -1255,6 +1255,10 @@ export async function galleryRoutes(app: FastifyInstance) {
     const selfieSystemPrompt = styleGuidance
       ? `${baseSelfieSystemPrompt}${formatImageStylePromptGuidance(styleGuidance)}`
       : baseSelfieSystemPrompt;
+    const imagePromptInstructions = imageConn.imagePromptInstructions?.trim();
+    const selfieSystemPromptWithImageInstructions = imagePromptInstructions
+      ? `${selfieSystemPrompt}\n\n<image_prompting_instructions>\nApply these image-backend instructions when writing the provider-ready prompt. They are instructions, not text to copy into the prompt:\n${imagePromptInstructions}\n</image_prompting_instructions>`
+      : selfieSystemPrompt;
 
     const selfieAbortSignal = createResponseAbortSignal(reply, SCENE_VIDEO_GENERATION_TIMEOUT_MS, "Selfie generation");
     let promptRuntime;
@@ -1276,7 +1280,7 @@ export async function galleryRoutes(app: FastifyInstance) {
       : `Generate a casual selfie of ${characterName} based on the current conversation context.`;
 
     if (debugLogsEnabled) {
-      debugLog("[debug/gallery/selfie] prompt-builder system:\n%s", selfieSystemPrompt);
+      debugLog("[debug/gallery/selfie] prompt-builder system:\n%s", selfieSystemPromptWithImageInstructions);
       debugLog("[debug/gallery/selfie] prompt-builder user:\n%s", promptContext);
     }
 
@@ -1285,7 +1289,7 @@ export async function galleryRoutes(app: FastifyInstance) {
       try {
         const promptResult = await promptBuilder.chatComplete(
           [
-            { role: "system", content: selfieSystemPrompt },
+            { role: "system", content: selfieSystemPromptWithImageInstructions },
             { role: "user", content: promptContext },
           ],
           {
diff --git a/packages/server/src/routes/generate.routes.ts b/packages/server/src/routes/generate.routes.ts
index fa8af22119..b7f3542817 100644
--- a/packages/server/src/routes/generate.routes.ts
+++ b/packages/server/src/routes/generate.routes.ts
@@ -3631,6 +3631,20 @@ export async function generateRoutes(app: FastifyInstance) {
           agentContext.memory._personaAvatarPath =
             persona && typeof persona.avatarPath === "string" ? persona.avatarPath : null;
         }
+        {
+          const illustratorAgentForInstructions = resolvedAgents.find((a) => a.type === "illustrator");
+          const imageConnectionId = resolveIllustratorImageConnectionId(
+            requestChatMode,
+            chatMeta,
+            illustratorAgentForInstructions?.settings?.imageConnectionId,
+          );
+          let imageConnectionForInstructions = imageConnectionId
+            ? await connections.getById(imageConnectionId).catch(() => null)
+            : null;
+          imageConnectionForInstructions ??= await connections.getDefaultForImageGeneration().catch(() => null);
+          const imagePromptInstructions = imageConnectionForInstructions?.imagePromptInstructions?.trim() ?? "";
+          if (imagePromptInstructions) agentContext.memory._imagePromptInstructions = imagePromptInstructions;
+        }
         const getLatestUserExpressionSource = () =>
           (
             [...agentContext.recentMessages]
diff --git a/packages/server/src/routes/generate/retry-agents-route.ts b/packages/server/src/routes/generate/retry-agents-route.ts
index 5ca95ec4cb..83087ea01e 100644
--- a/packages/server/src/routes/generate/retry-agents-route.ts
+++ b/packages/server/src/routes/generate/retry-agents-route.ts
@@ -547,10 +547,18 @@ async function executeManualIllustratorPromptRequest(args: {
             conns: args.conns,
             illustratorAgent: args.illustratorEntry.resolved,
           });
+    const imageConnectionId = resolveIllustratorImageConnectionId(
+      args.chat.mode,
+      args.chatMeta,
+      args.illustratorEntry.resolved.settings.imageConnectionId,
+    );
+    let imageConnection = imageConnectionId ? await args.conns.getById(imageConnectionId).catch(() => null) : null;
+    imageConnection ??= await args.conns.getDefaultForImageGeneration().catch(() => null);
     const generated = await writeManualIllustratorPromptPlan({
       illustratorAgent: args.illustratorEntry.resolved,
       context: args.agentContext,
       styleInstruction,
+      imagePromptInstructions: imageConnection?.imagePromptInstructions?.trim() || undefined,
       signal: args.agentContext.signal,
       debugLog: (message, ...values) => logDebugOverride(args.debugMode || isDebugAgentsEnabled(), message, ...values),
     });
@@ -4181,6 +4189,22 @@ export async function registerRetryAgentsRoute(app: FastifyInstance) {
           logger.warn(error, "[retry-agents] Failed to resolve image style instruction for the prompt writer");
         }
       }
+      {
+        const imageConnectionId = resolveIllustratorImageConnectionId(
+          chatMode,
+          chatMeta,
+          retryIllustratorPromptAgent?.resolved.settings?.imageConnectionId,
+        );
+        let imageConnectionForInstructions = imageConnectionId
+          ? await conns.getById(imageConnectionId).catch(() => null)
+          : null;
+        imageConnectionForInstructions ??= await conns.getDefaultForImageGeneration().catch(() => null);
+        const imagePromptInstructions = imageConnectionForInstructions?.imagePromptInstructions?.trim() ?? "";
+        if (imagePromptInstructions) {
+          agentContext.memory._imagePromptInstructions = imagePromptInstructions;
+          if (preGenerationAgentContext) preGenerationAgentContext.memory._imagePromptInstructions = imagePromptInstructions;
+        }
+      }
       if (preGenerationAgentContext) preGenerationAgentContext.signal = abortController.signal;
       if (debugMode) {
         const emitRetryAgentDebug = (event: AgentCallDebugEvent) => {
diff --git a/packages/server/src/services/agents/agent-executor.ts b/packages/server/src/services/agents/agent-executor.ts
index 61ccff858b..94d0994d0e 100644
--- a/packages/server/src/services/agents/agent-executor.ts
+++ b/packages/server/src/services/agents/agent-executor.ts
@@ -2366,7 +2366,19 @@ function buildAgentMessages(
   // some models, so add a terminal user instruction for that agent type too.
   const outputFormatBlock = options.outputFormatBlock?.trim() ?? "";
   const requiresTerminalUserInstruction =
-    finalParts.length > 0 || contextAgentTypes.includes("echo-chamber") || !!outputFormatBlock;
+    finalParts.length > 0 ||
+    contextAgentTypes.includes("echo-chamber") ||
+    !!outputFormatBlock ||
+    (typeof context.memory._imagePromptInstructions === "string" && context.memory._imagePromptInstructions.trim().length > 0);
+
+  const lateImagePromptInstructions =
+    typeof context.memory._imagePromptInstructions === "string" ? context.memory._imagePromptInstructions.trim() : "";
+  if (lateImagePromptInstructions) {
+    finalParts.push("\n<image_prompting_instructions>");
+    finalParts.push("Apply these image-backend instructions when writing the provider-ready image prompt. Do not copy the instructions as prompt content.");
+    finalParts.push(lateImagePromptInstructions);
+    finalParts.push("</image_prompting_instructions>");
+  }
 
   if (requiresTerminalUserInstruction) {
     const instruction = "Now return the requested format(s).";
diff --git a/packages/server/src/services/generation/conversation-selfie-command-runtime.ts b/packages/server/src/services/generation/conversation-selfie-command-runtime.ts
index f3b5627484..c06b52eb6e 100644
--- a/packages/server/src/services/generation/conversation-selfie-command-runtime.ts
+++ b/packages/server/src/services/generation/conversation-selfie-command-runtime.ts
@@ -201,6 +201,10 @@ async function generateSelfie(
   const selfieSystemPrompt = styleGuidance
     ? `${baseSelfieSystemPrompt}${formatImageStylePromptGuidance(styleGuidance)}`
     : baseSelfieSystemPrompt;
+  const imagePromptInstructions = imgConnFull.imagePromptInstructions?.trim();
+  const selfieSystemPromptWithImageInstructions = imagePromptInstructions
+    ? `${selfieSystemPrompt}\n\n<image_prompting_instructions>\nApply these image-backend instructions when writing the provider-ready prompt. They are instructions, not text to copy into the prompt:\n${imagePromptInstructions}\n</image_prompting_instructions>`
+    : selfieSystemPrompt;
   const userPrompt = args.command.context
     ? `Context for the selfie: ${args.command.context}`
     : `Generate a casual selfie of ${args.charName} based on the current conversation context.`;
@@ -213,7 +217,7 @@ async function generateSelfie(
     [
       {
         role: "system",
-        content: selfieSystemPrompt,
+        content: selfieSystemPromptWithImageInstructions,
       },
       {
         role: "user",
diff --git a/packages/server/src/services/generation/illustrator-manual-prompt-generation.ts b/packages/server/src/services/generation/illustrator-manual-prompt-generation.ts
index 375172e6ea..79ebbbf7ad 100644
--- a/packages/server/src/services/generation/illustrator-manual-prompt-generation.ts
+++ b/packages/server/src/services/generation/illustrator-manual-prompt-generation.ts
@@ -238,6 +238,7 @@ export function buildManualIllustratorPromptMessages(args: {
   contextSize: unknown;
   selectedPromptTemplate?: string;
   styleInstruction?: string;
+  imagePromptInstructions?: string;
 }): ChatMessage[] {
   const promptModeInstruction = normalizeManualIllustratorPromptModeInstruction(args.selectedPromptTemplate ?? "");
   const systemPrompt = [
@@ -253,6 +254,9 @@ export function buildManualIllustratorPromptMessages(args: {
     args.styleInstruction
       ? `Additional Image Style instruction for the image prompt you write: ${args.styleInstruction}\nCombine it with the selected Illustrator prompt mode. It may refine rendering and visual treatment, but it must not replace or weaken the selected format, layout, framing, or text requirements.`
       : "No visual style profile is selected. Infer only the visual treatment supported by the scene context.",
+    args.imagePromptInstructions
+      ? `<image_prompting_instructions>\nApply these image-backend instructions when writing the provider-ready prompt. They are instructions, not text to copy into the prompt:\n${args.imagePromptInstructions}\n</image_prompting_instructions>`
+      : "",
     buildCharacterPersonaContext(args.context),
   ].join("\n\n");
   const messages: ChatMessage[] = [
@@ -295,6 +299,7 @@ export async function writeManualIllustratorPromptPlan(args: {
   illustratorAgent: ResolvedAgent;
   context: AgentContext;
   styleInstruction?: string;
+  imagePromptInstructions?: string;
   signal?: AbortSignal;
   debugLog?: (message: string, ...args: unknown[]) => void;
 }): Promise<ManualIllustratorPromptResult> {
@@ -309,6 +314,7 @@ export async function writeManualIllustratorPromptPlan(args: {
     contextSize: args.illustratorAgent.settings.contextSize,
     selectedPromptTemplate,
     styleInstruction: args.styleInstruction,
+    imagePromptInstructions: args.imagePromptInstructions,
   });
   args.debugLog?.(
     "[debug/illustrator/manual-illustration-prompt] messages:\n%s",
diff --git a/packages/server/src/services/generation/illustrator-prompt-runtime.ts b/packages/server/src/services/generation/illustrator-prompt-runtime.ts
index 59fd91a7d7..3ed5278a23 100644
--- a/packages/server/src/services/generation/illustrator-prompt-runtime.ts
+++ b/packages/server/src/services/generation/illustrator-prompt-runtime.ts
@@ -13,6 +13,7 @@ export type IllustratorPromptConnection = FallbackConnection & {
   imageGenerationSource?: string | null;
   imageService?: string | null;
   imageEndpointId?: string | null;
+  imagePromptInstructions?: string | null;
   comfyuiWorkflow?: string | null;
 };
 
diff --git a/packages/server/src/services/storage/connections.storage.ts b/packages/server/src/services/storage/connections.storage.ts
index 2741fe7ef5..4797f4a659 100644
--- a/packages/server/src/services/storage/connections.storage.ts
+++ b/packages/server/src/services/storage/connections.storage.ts
@@ -141,6 +141,7 @@ export function createConnectionsStorage(db: DB) {
         comfyuiWorkflow: input.comfyuiWorkflow ?? null,
         imageService: input.imageService ?? null,
         imageEndpointId: input.imageEndpointId ?? null,
+        imagePromptInstructions: input.imagePromptInstructions ?? null,
         imageGenerationQuality: input.imageGenerationQuality ?? "auto",
         videoGenerationSource: input.videoGenerationSource ?? null,
         videoService: input.videoService ?? null,
@@ -283,6 +284,9 @@ export function createConnectionsStorage(db: DB) {
       if (data.imageEndpointId !== undefined) {
         updateFields.imageEndpointId = data.imageEndpointId;
       }
+      if (data.imagePromptInstructions !== undefined) {
+        updateFields.imagePromptInstructions = data.imagePromptInstructions;
+      }
       if (data.imageGenerationQuality !== undefined) {
         updateFields.imageGenerationQuality = data.imageGenerationQuality;
       }
@@ -418,6 +422,7 @@ export function createConnectionsStorage(db: DB) {
         comfyuiWorkflow: source.comfyuiWorkflow,
         imageService: source.imageService,
         imageEndpointId: source.imageEndpointId,
+        imagePromptInstructions: source.imagePromptInstructions,
         imageGenerationQuality: source.imageGenerationQuality,
         videoGenerationSource: source.videoGenerationSource,
         videoService: source.videoService,
diff --git a/packages/shared/src/schemas/connection.schema.ts b/packages/shared/src/schemas/connection.schema.ts
index 16890955c8..98c887a003 100644
--- a/packages/shared/src/schemas/connection.schema.ts
+++ b/packages/shared/src/schemas/connection.schema.ts
@@ -69,6 +69,7 @@ export const createConnectionSchema = z.object({
   comfyuiWorkflow: z.string().nullable().default(null),
   imageService: z.string().nullable().default(null),
   imageEndpointId: z.string().nullable().default(null),
+  imagePromptInstructions: z.string().nullable().default(null),
   imageGenerationQuality: imageGenerationQualitySchema.default("auto"),
   videoGenerationSource: z.string().nullable().default(null),
   videoService: z.string().nullable().default(null),
diff --git a/packages/shared/src/types/connection.ts b/packages/shared/src/types/connection.ts
index eab82eb64a..1d183630d5 100644
--- a/packages/shared/src/types/connection.ts
+++ b/packages/shared/src/types/connection.ts
@@ -69,6 +69,8 @@ export interface APIConnection {
   imageService: string | null;
   /** For endpoint-based image services (e.g. RunPod Serverless): the endpoint ID sent alongside the base URL. */
   imageEndpointId: string | null;
+  /** Instructions applied by an extra default-language-model call before image generation. */
+  imagePromptInstructions: string | null;
   /** OpenAI GPT Image quality saved for this connection. */
   imageGenerationQuality: ImageGenerationQuality;
   /** Explicit video backend selection for video-generation connections (e.g. Gemini Omni). */

From ec8a8e3e98d36b82d7629a277790b08f0b098dfb Mon Sep 17 00:00:00 2001
From: SNPAU <SNPAU@users.noreply.github.com>
Date: Mon, 10 Aug 2026 15:31:12 +1000
Subject: [PATCH 2/7] Clarify

---
 packages/client/src/localization/locales/en.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/client/src/localization/locales/en.json b/packages/client/src/localization/locales/en.json
index 2ce2e0f0e0..d831215848 100644
--- a/packages/client/src/localization/locales/en.json
+++ b/packages/client/src/localization/locales/en.json
@@ -4056,7 +4056,7 @@
   "ui.connections.connectioneditor.ifYourProxyOrLocalServerIsnTDetected": "If your proxy or local server isn't detected, Windows Defender Firewall may be blocking the connection. Open",
   "ui.connections.connectioneditor.imageCaptioning": "Image Captioning",
   "ui.connections.connectioneditor.imagePromptingInstructions": "Image Prompting Instructions",
-  "ui.connections.connectioneditor.imagePromptingInstructionsHelp": "When set, Marinara makes one extra call to your default language model to apply these instructions, then sends the resulting prompt to this image backend. Useful for tags, quality tokens, negative-prompt conventions, or local/ComfyUI syntax.",
+  "ui.connections.connectioneditor.imagePromptingInstructionsHelp": "When set, Marinara makes UP TO (but not always) one extra call to your default language model to apply these instructions, then sends the resulting prompt to this image backend. Useful for tags, quality tokens, negative-prompt conventions, or local/ComfyUI syntax.",
   "ui.connections.connectioneditor.imagePromptingInstructionsPlaceholder": "Example: use comma-separated tags, add quality tokens, and keep negative terms separate.",
   "ui.connections.connectioneditor.imageQualityAuto": "Auto",
   "ui.connections.connectioneditor.imageQualityHigh": "High",

From be35ad112bac0f64ed75ade604607916c6ff4065 Mon Sep 17 00:00:00 2001
From: SNPAU <SNPAU@users.noreply.github.com>
Date: Mon, 10 Aug 2026 15:59:40 +1000
Subject: [PATCH 3/7] Address code review

---
 CHANGELOG.md                                  |  1 +
 .../connections/ConnectionEditor.tsx          |  7 +-
 .../client/src/lib/connection-transfer.ts     | 11 ++-
 .../client/src/localization/locales/en.json   |  2 +-
 packages/server/src/routes/gallery.routes.ts  |  9 +-
 packages/server/src/routes/generate.routes.ts |  7 +-
 .../src/routes/generate/retry-agents-route.ts | 92 ++++++++++++++-----
 .../src/services/agents/agent-executor.ts     | 11 ++-
 .../conversation-selfie-command-runtime.ts    |  9 +-
 .../generation/image-prompt-instructions.ts   |  8 ++
 packages/shared/src/constants/defaults.ts     |  9 ++
 .../shared/src/schemas/connection.schema.ts   |  3 +-
 12 files changed, 128 insertions(+), 41 deletions(-)
 create mode 100644 packages/server/src/services/generation/image-prompt-instructions.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3e193f8ed8..b67ba18c21 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,6 +46,7 @@ This file is the release-notes source of truth for Marinara Engine. Reuse these
 
 ### Fixed
 
+- Scoped image-connection prompt instructions to image-producing agents, bounded stored instructions to 5,000 characters, and kept each retry agent on its own configured image connection.
 - Kept Professor Mari's Home navigator enabled by default and visible with reduced effects, reset her to the default position when re-enabled, centered her drag handle, contained compact Field Notes and Community actions, and presented iPad sidebars as full-width overlays (#4826, #4827, #4829, #4830).
 - Sharpened Professor Mari's read-only guardrail so a "how do I…" question is answered or offered rather than performed, even when it names the change as its goal (for example "how do I make X have Y") — while a plainly-worded request to make that change, including a polite question form like "can you set X to Y", is still carried out — so she keys on intent rather than grammar and no longer edits without a clear instruction (#4838).
 - Reduced background autonomous-message polling to a lightweight candidate-id lookup instead of re-fetching the full chat list every 30 seconds (#4715).
diff --git a/packages/client/src/components/connections/ConnectionEditor.tsx b/packages/client/src/components/connections/ConnectionEditor.tsx
index f19fc063c7..cc89fe6732 100644
--- a/packages/client/src/components/connections/ConnectionEditor.tsx
+++ b/packages/client/src/components/connections/ConnectionEditor.tsx
@@ -95,6 +95,8 @@ import {
   sanitizeImageGenerationProfile,
   sanitizeVideoGenerationProfile,
   suggestImageStyleProfileIdForModel,
+  MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH,
+  normalizeImagePromptInstructions,
   parseConnectionImageCaptioningDefaults,
   type APIProvider,
   type ComfyUiLoraSetting,
@@ -721,7 +723,7 @@ export function ConnectionEditor() {
       imageService: isImageProvider ? localImageGenerationSource || localImageService || null : null,
       imageEndpointId:
         isImageProvider && selectedImageService === "runpod_comfyui" ? localImageEndpointId || null : null,
-      imagePromptInstructions: isImageProvider ? localImagePromptInstructions.trim() || null : null,
+      imagePromptInstructions: isImageProvider ? normalizeImagePromptInstructions(localImagePromptInstructions) : null,
       imageGenerationQuality: isImageProvider ? localImageGenerationQuality : "auto",
       videoGenerationSource: isVideoProvider ? selectedVideoProvider || null : null,
       videoService: isVideoProvider ? selectedVideoDefaultsService : null,
@@ -927,7 +929,7 @@ export function ConnectionEditor() {
       videoService,
       imageEndpointId:
         isImageProvider && selectedImageService === "runpod_comfyui" ? localImageEndpointId || null : null,
-      imagePromptInstructions: isImageProvider ? localImagePromptInstructions.trim() || null : null,
+      imagePromptInstructions: isImageProvider ? normalizeImagePromptInstructions(localImagePromptInstructions) : null,
       imageGenerationQuality: isImageProvider ? localImageGenerationQuality : "auto",
       comfyuiWorkflow:
         isImageProvider || (isVideoProvider && videoProvider === "comfyui") ? localComfyuiWorkflow || null : null,
@@ -2022,6 +2024,7 @@ export function ConnectionEditor() {
             >
               <textarea
                 value={localImagePromptInstructions}
+                maxLength={MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH}
                 onChange={(event) => {
                   setLocalImagePromptInstructions(event.target.value);
                   markDirty();
diff --git a/packages/client/src/lib/connection-transfer.ts b/packages/client/src/lib/connection-transfer.ts
index a840b0a2be..f34e7eac81 100644
--- a/packages/client/src/lib/connection-transfer.ts
+++ b/packages/client/src/lib/connection-transfer.ts
@@ -1,4 +1,9 @@
-import { PROVIDERS, type APIProvider, type ImageGenerationQuality } from "@marinara-engine/shared";
+import {
+  normalizeImagePromptInstructions,
+  PROVIDERS,
+  type APIProvider,
+  type ImageGenerationQuality,
+} from "@marinara-engine/shared";
 import type { CreateConnectionPayload } from "../hooks/use-connections";
 
 export type ConnectionTransferRow = {
@@ -135,7 +140,7 @@ export function normalizeImportedConnectionEntry(value: unknown): ConnectionImpo
       comfyuiWorkflow: asNullableString(value.comfyuiWorkflow),
       imageService,
       imageEndpointId: asNullableString(value.imageEndpointId),
-      imagePromptInstructions: asNullableString(value.imagePromptInstructions),
+      imagePromptInstructions: normalizeImagePromptInstructions(value.imagePromptInstructions),
       imageGenerationQuality: asImageGenerationQuality(value.imageGenerationQuality),
       videoGenerationSource: provider === "video_generation" ? asNullableString(value.videoGenerationSource) : null,
       videoService,
@@ -180,7 +185,7 @@ function serializeConnectionForExport(connection: ConnectionTransferRow): SafeCo
     videoGenerationSource: isVideoProvider ? asNullableString(connection.videoGenerationSource) : null,
     videoService: isVideoProvider ? asNullableString(connection.videoService ?? connection.service) : null,
     imageEndpointId: asNullableString(connection.imageEndpointId),
-    imagePromptInstructions: asNullableString(connection.imagePromptInstructions),
+    imagePromptInstructions: normalizeImagePromptInstructions(connection.imagePromptInstructions),
     imageGenerationQuality: asImageGenerationQuality(connection.imageGenerationQuality),
     comfyuiWorkflow: asNullableString(connection.comfyuiWorkflow),
     treatAsLocalEndpoint: asBoolean(connection.treatAsLocalEndpoint),
diff --git a/packages/client/src/localization/locales/en.json b/packages/client/src/localization/locales/en.json
index d831215848..0338c18eca 100644
--- a/packages/client/src/localization/locales/en.json
+++ b/packages/client/src/localization/locales/en.json
@@ -4056,7 +4056,7 @@
   "ui.connections.connectioneditor.ifYourProxyOrLocalServerIsnTDetected": "If your proxy or local server isn't detected, Windows Defender Firewall may be blocking the connection. Open",
   "ui.connections.connectioneditor.imageCaptioning": "Image Captioning",
   "ui.connections.connectioneditor.imagePromptingInstructions": "Image Prompting Instructions",
-  "ui.connections.connectioneditor.imagePromptingInstructionsHelp": "When set, Marinara makes UP TO (but not always) one extra call to your default language model to apply these instructions, then sends the resulting prompt to this image backend. Useful for tags, quality tokens, negative-prompt conventions, or local/ComfyUI syntax.",
+  "ui.connections.connectioneditor.imagePromptingInstructionsHelp": "When set, these instructions are added to the existing prompt-writer system message and processed by the configured Illustrator provider and model before the prompt is sent to this image backend. Some flows, including Noodle, use an additional prompt-writing call to apply them. Useful for tags, quality tokens, negative-prompt conventions, or local/ComfyUI syntax. An invalid-JSON retry may trigger another call.",
   "ui.connections.connectioneditor.imagePromptingInstructionsPlaceholder": "Example: use comma-separated tags, add quality tokens, and keep negative terms separate.",
   "ui.connections.connectioneditor.imageQualityAuto": "Auto",
   "ui.connections.connectioneditor.imageQualityHigh": "High",
diff --git a/packages/server/src/routes/gallery.routes.ts b/packages/server/src/routes/gallery.routes.ts
index 1dfa07860c..bc99e81cd2 100644
--- a/packages/server/src/routes/gallery.routes.ts
+++ b/packages/server/src/routes/gallery.routes.ts
@@ -66,6 +66,7 @@ import {
 import { resolveIllustratorPromptRuntime } from "../services/generation/illustrator-prompt-runtime.js";
 import { resolveIllustratorImageConnectionId } from "../services/generation/illustrator-background-generation.js";
 import { resolveConversationSelfieSystemPrompt } from "../services/conversation/selfie-prompt.js";
+import { appendImagePromptInstructions } from "../services/generation/image-prompt-instructions.js";
 import {
   suppressesReferencePromptLine,
   resolveIllustratorCharacterReferences,
@@ -1255,10 +1256,10 @@ export async function galleryRoutes(app: FastifyInstance) {
     const selfieSystemPrompt = styleGuidance
       ? `${baseSelfieSystemPrompt}${formatImageStylePromptGuidance(styleGuidance)}`
       : baseSelfieSystemPrompt;
-    const imagePromptInstructions = imageConn.imagePromptInstructions?.trim();
-    const selfieSystemPromptWithImageInstructions = imagePromptInstructions
-      ? `${selfieSystemPrompt}\n\n<image_prompting_instructions>\nApply these image-backend instructions when writing the provider-ready prompt. They are instructions, not text to copy into the prompt:\n${imagePromptInstructions}\n</image_prompting_instructions>`
-      : selfieSystemPrompt;
+    const selfieSystemPromptWithImageInstructions = appendImagePromptInstructions(
+      selfieSystemPrompt,
+      imageConn.imagePromptInstructions,
+    );
 
     const selfieAbortSignal = createResponseAbortSignal(reply, SCENE_VIDEO_GENERATION_TIMEOUT_MS, "Selfie generation");
     let promptRuntime;
diff --git a/packages/server/src/routes/generate.routes.ts b/packages/server/src/routes/generate.routes.ts
index b7f3542817..3c0d018e57 100644
--- a/packages/server/src/routes/generate.routes.ts
+++ b/packages/server/src/routes/generate.routes.ts
@@ -43,6 +43,7 @@ import {
   unwrapConversationInstructions,
   findKnownModel,
   LOCAL_SIDECAR_CONNECTION_ID,
+  normalizeImagePromptInstructions,
   normalizeTextForMatch,
   parseManagedGenerationParameterDefinitions,
   normalizeGameStoryboardKeyframeCount,
@@ -3631,7 +3632,7 @@ export async function generateRoutes(app: FastifyInstance) {
           agentContext.memory._personaAvatarPath =
             persona && typeof persona.avatarPath === "string" ? persona.avatarPath : null;
         }
-        {
+        if (resolvedAgents.some((entry) => entry.type === "illustrator")) {
           const illustratorAgentForInstructions = resolvedAgents.find((a) => a.type === "illustrator");
           const imageConnectionId = resolveIllustratorImageConnectionId(
             requestChatMode,
@@ -3642,7 +3643,9 @@ export async function generateRoutes(app: FastifyInstance) {
             ? await connections.getById(imageConnectionId).catch(() => null)
             : null;
           imageConnectionForInstructions ??= await connections.getDefaultForImageGeneration().catch(() => null);
-          const imagePromptInstructions = imageConnectionForInstructions?.imagePromptInstructions?.trim() ?? "";
+          const imagePromptInstructions = normalizeImagePromptInstructions(
+            imageConnectionForInstructions?.imagePromptInstructions,
+          );
           if (imagePromptInstructions) agentContext.memory._imagePromptInstructions = imagePromptInstructions;
         }
         const getLatestUserExpressionSource = () =>
diff --git a/packages/server/src/routes/generate/retry-agents-route.ts b/packages/server/src/routes/generate/retry-agents-route.ts
index 83087ea01e..50d0f1b606 100644
--- a/packages/server/src/routes/generate/retry-agents-route.ts
+++ b/packages/server/src/routes/generate/retry-agents-route.ts
@@ -21,6 +21,7 @@ import {
   normalizeWorldCustomFields,
   normalizeAgentPhaseValue,
   normalizeAgentPromptTemplateSelectionMap,
+  normalizeImagePromptInstructions,
   resolveMacros,
   resolveGameSetupArtStylePrompt,
   resolveAgentPromptTemplate,
@@ -558,7 +559,7 @@ async function executeManualIllustratorPromptRequest(args: {
       illustratorAgent: args.illustratorEntry.resolved,
       context: args.agentContext,
       styleInstruction,
-      imagePromptInstructions: imageConnection?.imagePromptInstructions?.trim() || undefined,
+      imagePromptInstructions: normalizeImagePromptInstructions(imageConnection?.imagePromptInstructions) ?? undefined,
       signal: args.agentContext.signal,
       debugLog: (message, ...values) => logDebugOverride(args.debugMode || isDebugAgentsEnabled(), message, ...values),
     });
@@ -2448,10 +2449,48 @@ async function validateSpotifyRetryPlayback(
   };
 }
 
+function isImagePromptRetryAgent(entry: ResolvedRetryAgent): boolean {
+  return (
+    entry.resolved.type === "illustrator" ||
+    (entry.resolved.isCustomAgent === true &&
+      customAgentHasCapability(entry.resolved.settings, "trigger_image_generation"))
+  );
+}
+
+async function resolveRetryImagePromptContext(args: {
+  entry: ResolvedRetryAgent;
+  context: AgentContext;
+  conns?: ReturnType<typeof createConnectionsStorage>;
+  chatMode?: ChatMode;
+  chatMeta?: Record<string, unknown>;
+}): Promise<AgentContext> {
+  const memory = { ...args.context.memory };
+  delete memory._imagePromptInstructions;
+
+  if (!args.conns || !args.chatMode || !args.chatMeta) {
+    return { ...args.context, memory };
+  }
+
+  const imageConnectionId =
+    args.entry.resolved.type === "illustrator"
+      ? resolveIllustratorImageConnectionId(args.chatMode, args.chatMeta, args.entry.resolved.settings.imageConnectionId)
+      : typeof args.entry.resolved.settings.imageConnectionId === "string"
+        ? args.entry.resolved.settings.imageConnectionId.trim()
+        : "";
+  let imageConnection = imageConnectionId ? await args.conns.getById(imageConnectionId).catch(() => null) : null;
+  imageConnection ??= await args.conns.getDefaultForImageGeneration().catch(() => null);
+  const imagePromptInstructions = normalizeImagePromptInstructions(imageConnection?.imagePromptInstructions);
+  if (imagePromptInstructions) memory._imagePromptInstructions = imagePromptInstructions;
+  return { ...args.context, memory };
+}
+
 async function executeRetryBatches(
   agentContext: AgentContext,
   resolvedAgents: ResolvedRetryAgent[],
   preGenerationContext?: AgentContext | null,
+  conns?: ReturnType<typeof createConnectionsStorage>,
+  chatMode?: ChatMode,
+  chatMeta?: Record<string, unknown>,
 ) {
   const retryAgents = mergeRetryPairedBuiltInRewriteAgents(resolvedAgents);
   const providerModelGroups = new Map<
@@ -2512,13 +2551,15 @@ async function executeRetryBatches(
     async (group) => {
       const toolAgents = group.agents.filter((agent) => shouldUseToolsDuringAgentExecution(agent.resolved));
       const batchAgents = group.agents.filter((agent) => !shouldUseToolsDuringAgentExecution(agent.resolved));
+      const imagePromptAgents = batchAgents.filter(isImagePromptRetryAgent);
+      const regularBatchAgents = batchAgents.filter((agent) => !isImagePromptRetryAgent(agent));
       const groupResults: AgentResult[] = [];
 
-      if (batchAgents.length > 0) {
-        const configs = batchAgents.map((agent) => agent.resolved);
+      if (regularBatchAgents.length > 0) {
+        const configs = regularBatchAgents.map((agent) => agent.resolved);
         const batchResults = await executeAgentBatch(configs, group.context, group.provider, group.model);
         for (const result of batchResults) {
-          const entry = batchAgents.find(
+          const entry = regularBatchAgents.find(
             (agent) => agent.resolved.id === result.agentId || agent.resolved.type === result.agentType,
           );
           groupResults.push(
@@ -2529,10 +2570,26 @@ async function executeRetryBatches(
         }
       }
 
+      for (const entry of imagePromptAgents) {
+        const imagePromptContext = await resolveRetryImagePromptContext({
+          entry,
+          context: group.context,
+          conns,
+          chatMode,
+          chatMeta,
+        });
+        groupResults.push(
+          await executeAgent(entry.resolved, imagePromptContext, group.provider, group.model, entry.resolved.toolContext),
+        );
+      }
+
       for (const entry of toolAgents) {
+        const toolContext = isImagePromptRetryAgent(entry)
+          ? await resolveRetryImagePromptContext({ entry, context: group.context, conns, chatMode, chatMeta })
+          : group.context;
         const result = await executeAgent(
           entry.resolved,
-          group.context,
+          toolContext,
           group.provider,
           group.model,
           entry.resolved.toolContext,
@@ -4189,22 +4246,6 @@ export async function registerRetryAgentsRoute(app: FastifyInstance) {
           logger.warn(error, "[retry-agents] Failed to resolve image style instruction for the prompt writer");
         }
       }
-      {
-        const imageConnectionId = resolveIllustratorImageConnectionId(
-          chatMode,
-          chatMeta,
-          retryIllustratorPromptAgent?.resolved.settings?.imageConnectionId,
-        );
-        let imageConnectionForInstructions = imageConnectionId
-          ? await conns.getById(imageConnectionId).catch(() => null)
-          : null;
-        imageConnectionForInstructions ??= await conns.getDefaultForImageGeneration().catch(() => null);
-        const imagePromptInstructions = imageConnectionForInstructions?.imagePromptInstructions?.trim() ?? "";
-        if (imagePromptInstructions) {
-          agentContext.memory._imagePromptInstructions = imagePromptInstructions;
-          if (preGenerationAgentContext) preGenerationAgentContext.memory._imagePromptInstructions = imagePromptInstructions;
-        }
-      }
       if (preGenerationAgentContext) preGenerationAgentContext.signal = abortController.signal;
       if (debugMode) {
         const emitRetryAgentDebug = (event: AgentCallDebugEvent) => {
@@ -4309,7 +4350,14 @@ export async function registerRetryAgentsRoute(app: FastifyInstance) {
                 }),
               ]
             : nonLorebookAgents.length > 0
-              ? await executeRetryBatches(agentContext, nonLorebookAgents, preGenerationAgentContext)
+              ? await executeRetryBatches(
+                  agentContext,
+                  nonLorebookAgents,
+                  preGenerationAgentContext,
+                  conns,
+                  chatMode,
+                  chatMeta,
+                )
               : [];
       const results = rawResults
         .map(markInvalidJsonAgentResult)
diff --git a/packages/server/src/services/agents/agent-executor.ts b/packages/server/src/services/agents/agent-executor.ts
index 94d0994d0e..37e0c7efd3 100644
--- a/packages/server/src/services/agents/agent-executor.ts
+++ b/packages/server/src/services/agents/agent-executor.ts
@@ -18,6 +18,7 @@ import type {
 import {
   characterTrackerLockKey,
   compactQuestProgressForContext,
+  customAgentHasCapability,
   DEFAULT_AGENT_CONTEXT_SIZE,
   DEFAULT_AGENT_MAX_TOKENS,
   DEFAULT_CUSTOM_AGENT_CONTEXT_SOURCES,
@@ -1627,6 +1628,7 @@ function shouldRunAgentIndividually(config: Pick<AgentExecConfig, "type" | "sett
   // must not be merged into unrelated batched agent requests.
   return (
     config.type === "illustrator" ||
+    customAgentHasCapability(config.settings, "trigger_image_generation") ||
     config.type === "lorebook-keeper" ||
     resolveAgentResultType(config) === "text_rewrite" ||
     musicDjUsesJsonOnlyProvider(config) ||
@@ -1811,6 +1813,8 @@ function buildStandardAgentMessages(config: AgentExecConfig, template: string, c
     includeTrackerData: contextSources.trackerData,
     preserveAssistantResponseMarkup: resultType === "text_rewrite",
     outputFormatBlock: buildAgentOutputFormatBlock([config], context, renderedTemplates),
+    includeImagePromptInstructions:
+      config.type === "illustrator" || customAgentHasCapability(config.settings, "trigger_image_generation"),
   });
 }
 
@@ -2280,6 +2284,7 @@ function buildAgentMessages(
     includeTrackerData?: boolean;
     preserveAssistantResponseMarkup?: boolean;
     outputFormatBlock?: string;
+    includeImagePromptInstructions?: boolean;
   } = {},
 ): ChatMessage[] {
   // ── 1. System message — already contains <role>, <lore>, <agents>, and extras ──
@@ -2369,11 +2374,13 @@ function buildAgentMessages(
     finalParts.length > 0 ||
     contextAgentTypes.includes("echo-chamber") ||
     !!outputFormatBlock ||
-    (typeof context.memory._imagePromptInstructions === "string" && context.memory._imagePromptInstructions.trim().length > 0);
+    (options.includeImagePromptInstructions === true &&
+      typeof context.memory._imagePromptInstructions === "string" &&
+      context.memory._imagePromptInstructions.trim().length > 0);
 
   const lateImagePromptInstructions =
     typeof context.memory._imagePromptInstructions === "string" ? context.memory._imagePromptInstructions.trim() : "";
-  if (lateImagePromptInstructions) {
+  if (options.includeImagePromptInstructions === true && lateImagePromptInstructions) {
     finalParts.push("\n<image_prompting_instructions>");
     finalParts.push("Apply these image-backend instructions when writing the provider-ready image prompt. Do not copy the instructions as prompt content.");
     finalParts.push(lateImagePromptInstructions);
diff --git a/packages/server/src/services/generation/conversation-selfie-command-runtime.ts b/packages/server/src/services/generation/conversation-selfie-command-runtime.ts
index c06b52eb6e..b8fabf1c68 100644
--- a/packages/server/src/services/generation/conversation-selfie-command-runtime.ts
+++ b/packages/server/src/services/generation/conversation-selfie-command-runtime.ts
@@ -16,6 +16,7 @@ import { generateImage, saveImageToDisk } from "../image/image-generation.js";
 import { loadImageGenerationUserSettings } from "../image/image-generation-settings.js";
 import { generateIllustratorImageVariants } from "../image/illustrator-image-variants.js";
 import { resolveConversationSelfieSystemPrompt } from "../conversation/selfie-prompt.js";
+import { appendImagePromptInstructions } from "./image-prompt-instructions.js";
 import type { CharacterCommand, SelfieCommand } from "../conversation/character-commands.js";
 import { createGalleryStorage } from "../storage/gallery.storage.js";
 import { createCharacterGalleryStorage } from "../storage/character-gallery.storage.js";
@@ -201,10 +202,10 @@ async function generateSelfie(
   const selfieSystemPrompt = styleGuidance
     ? `${baseSelfieSystemPrompt}${formatImageStylePromptGuidance(styleGuidance)}`
     : baseSelfieSystemPrompt;
-  const imagePromptInstructions = imgConnFull.imagePromptInstructions?.trim();
-  const selfieSystemPromptWithImageInstructions = imagePromptInstructions
-    ? `${selfieSystemPrompt}\n\n<image_prompting_instructions>\nApply these image-backend instructions when writing the provider-ready prompt. They are instructions, not text to copy into the prompt:\n${imagePromptInstructions}\n</image_prompting_instructions>`
-    : selfieSystemPrompt;
+  const selfieSystemPromptWithImageInstructions = appendImagePromptInstructions(
+    selfieSystemPrompt,
+    imgConnFull.imagePromptInstructions,
+  );
   const userPrompt = args.command.context
     ? `Context for the selfie: ${args.command.context}`
     : `Generate a casual selfie of ${args.charName} based on the current conversation context.`;
diff --git a/packages/server/src/services/generation/image-prompt-instructions.ts b/packages/server/src/services/generation/image-prompt-instructions.ts
new file mode 100644
index 0000000000..1d13d3e839
--- /dev/null
+++ b/packages/server/src/services/generation/image-prompt-instructions.ts
@@ -0,0 +1,8 @@
+import { normalizeImagePromptInstructions } from "@marinara-engine/shared";
+
+export function appendImagePromptInstructions(prompt: string, instructions: unknown): string {
+  const normalizedInstructions = normalizeImagePromptInstructions(instructions);
+  return normalizedInstructions
+    ? `${prompt}\n\n<image_prompting_instructions>\nApply these image-backend instructions when writing the provider-ready prompt. They are instructions, not text to copy into the prompt:\n${normalizedInstructions}\n</image_prompting_instructions>`
+    : prompt;
+}
\ No newline at end of file
diff --git a/packages/shared/src/constants/defaults.ts b/packages/shared/src/constants/defaults.ts
index 6efa97892b..bf82d9aca9 100644
--- a/packages/shared/src/constants/defaults.ts
+++ b/packages/shared/src/constants/defaults.ts
@@ -18,6 +18,15 @@ export const DEFAULT_CONNECTION_ID = "__default_openrouter__";
 /** Shared width for cached background thumbnails used by compact client surfaces. */
 export const BACKGROUND_THUMBNAIL_WIDTH = 320;
 
+/** Maximum length for image-backend instructions stored on an image connection. */
+export const MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH = 5_000;
+
+export function normalizeImagePromptInstructions(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH);
+  return trimmed || null;
+}
+
 /** Default system prompt for AI-backed translation. */
 export const DEFAULT_TRANSLATION_SYSTEM_PROMPT =
   "You are a translator. Translate the given text accurately into {{targetLanguage}}, preserving formatting, markdown, and any special characters like *asterisks* for actions. Output ONLY the translated text, nothing else -- no explanations, no extra commentary.";
diff --git a/packages/shared/src/schemas/connection.schema.ts b/packages/shared/src/schemas/connection.schema.ts
index 98c887a003..80ab5a12c4 100644
--- a/packages/shared/src/schemas/connection.schema.ts
+++ b/packages/shared/src/schemas/connection.schema.ts
@@ -3,6 +3,7 @@
 // ──────────────────────────────────────────────
 import { z } from "zod";
 import { IMAGE_GENERATION_QUALITIES } from "../types/connection.js";
+import { MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH } from "../constants/defaults.js";
 
 export const apiProviderSchema = z.enum([
   "openai",
@@ -69,7 +70,7 @@ export const createConnectionSchema = z.object({
   comfyuiWorkflow: z.string().nullable().default(null),
   imageService: z.string().nullable().default(null),
   imageEndpointId: z.string().nullable().default(null),
-  imagePromptInstructions: z.string().nullable().default(null),
+  imagePromptInstructions: z.string().trim().max(MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH).nullable().default(null),
   imageGenerationQuality: imageGenerationQualitySchema.default("auto"),
   videoGenerationSource: z.string().nullable().default(null),
   videoService: z.string().nullable().default(null),

From daf3a12d1eb4850219bd701270e39b1d662b11ce Mon Sep 17 00:00:00 2001
From: SNPAU <SNPAU@users.noreply.github.com>
Date: Mon, 10 Aug 2026 16:13:22 +1000
Subject: [PATCH 4/7] Address code review comments

---
 .../client/src/localization/locales/en.json   |  2 +-
 packages/server/src/routes/generate.routes.ts | 23 +++++++++++++------
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/packages/client/src/localization/locales/en.json b/packages/client/src/localization/locales/en.json
index 0338c18eca..5befd0607e 100644
--- a/packages/client/src/localization/locales/en.json
+++ b/packages/client/src/localization/locales/en.json
@@ -4056,7 +4056,7 @@
   "ui.connections.connectioneditor.ifYourProxyOrLocalServerIsnTDetected": "If your proxy or local server isn't detected, Windows Defender Firewall may be blocking the connection. Open",
   "ui.connections.connectioneditor.imageCaptioning": "Image Captioning",
   "ui.connections.connectioneditor.imagePromptingInstructions": "Image Prompting Instructions",
-  "ui.connections.connectioneditor.imagePromptingInstructionsHelp": "When set, these instructions are added to the existing prompt-writer system message and processed by the configured Illustrator provider and model before the prompt is sent to this image backend. Some flows, including Noodle, use an additional prompt-writing call to apply them. Useful for tags, quality tokens, negative-prompt conventions, or local/ComfyUI syntax. An invalid-JSON retry may trigger another call.",
+  "ui.connections.connectioneditor.imagePromptingInstructionsHelp": "When set, these instructions are added to the existing prompt-writer system message and processed by the configured Illustrator provider and model in selfie and Illustrator flows before the prompt is sent to this image backend. Useful for tags, quality tokens, negative-prompt conventions, or local/ComfyUI syntax. An invalid-JSON retry may trigger another call.",
   "ui.connections.connectioneditor.imagePromptingInstructionsPlaceholder": "Example: use comma-separated tags, add quality tokens, and keep negative terms separate.",
   "ui.connections.connectioneditor.imageQualityAuto": "Auto",
   "ui.connections.connectioneditor.imageQualityHigh": "High",
diff --git a/packages/server/src/routes/generate.routes.ts b/packages/server/src/routes/generate.routes.ts
index 3c0d018e57..939f6bc533 100644
--- a/packages/server/src/routes/generate.routes.ts
+++ b/packages/server/src/routes/generate.routes.ts
@@ -3632,13 +3632,22 @@ export async function generateRoutes(app: FastifyInstance) {
           agentContext.memory._personaAvatarPath =
             persona && typeof persona.avatarPath === "string" ? persona.avatarPath : null;
         }
-        if (resolvedAgents.some((entry) => entry.type === "illustrator")) {
-          const illustratorAgentForInstructions = resolvedAgents.find((a) => a.type === "illustrator");
-          const imageConnectionId = resolveIllustratorImageConnectionId(
-            requestChatMode,
-            chatMeta,
-            illustratorAgentForInstructions?.settings?.imageConnectionId,
-          );
+        const imagePromptAgentForInstructions = resolvedAgents.find(
+          (entry) =>
+            entry.type === "illustrator" ||
+            (entry.isCustomAgent === true && customAgentHasCapability(entry.settings, "trigger_image_generation")),
+        );
+        if (imagePromptAgentForInstructions) {
+          const imageConnectionId =
+            imagePromptAgentForInstructions.type === "illustrator"
+              ? resolveIllustratorImageConnectionId(
+                  requestChatMode,
+                  chatMeta,
+                  imagePromptAgentForInstructions.settings?.imageConnectionId,
+                )
+              : typeof imagePromptAgentForInstructions.settings?.imageConnectionId === "string"
+                ? imagePromptAgentForInstructions.settings.imageConnectionId.trim()
+                : "";
           let imageConnectionForInstructions = imageConnectionId
             ? await connections.getById(imageConnectionId).catch(() => null)
             : null;

From b8170a59a743f779507c0c70dd381feba5229906 Mon Sep 17 00:00:00 2001
From: SNPAU <SNPAU@users.noreply.github.com>
Date: Mon, 10 Aug 2026 16:33:57 +1000
Subject: [PATCH 5/7] Fix per-agent image prompt instructions

---
 packages/server/src/routes/generate.routes.ts | 59 ++++++++++---------
 .../src/services/agents/agent-executor.ts     | 16 +++--
 .../src/services/agents/agent-pipeline.ts     | 42 +++++++++----
 3 files changed, 75 insertions(+), 42 deletions(-)

diff --git a/packages/server/src/routes/generate.routes.ts b/packages/server/src/routes/generate.routes.ts
index 939f6bc533..b3335db115 100644
--- a/packages/server/src/routes/generate.routes.ts
+++ b/packages/server/src/routes/generate.routes.ts
@@ -158,7 +158,12 @@ import {
 import { executeToolCalls, formatToolExecutionResultForModel } from "../services/tools/tool-executor.js";
 import { createAgentPipeline, type ResolvedAgent, type AgentInjection } from "../services/agents/agent-pipeline.js";
 import { DATA_DIR } from "../utils/data-dir.js";
-import { executeAgent, normalizeAgentContextSize, resolveAgentResultType } from "../services/agents/agent-executor.js";
+import {
+  executeAgent,
+  normalizeAgentContextSize,
+  resolveAgentResultType,
+  type AgentExecConfig,
+} from "../services/agents/agent-executor.js";
 import { matchCustomAgentActivation } from "./generate/agent-activation.js";
 import { listCharacterSprites } from "../services/game/sprite.service.js";
 import {
@@ -3632,31 +3637,6 @@ export async function generateRoutes(app: FastifyInstance) {
           agentContext.memory._personaAvatarPath =
             persona && typeof persona.avatarPath === "string" ? persona.avatarPath : null;
         }
-        const imagePromptAgentForInstructions = resolvedAgents.find(
-          (entry) =>
-            entry.type === "illustrator" ||
-            (entry.isCustomAgent === true && customAgentHasCapability(entry.settings, "trigger_image_generation")),
-        );
-        if (imagePromptAgentForInstructions) {
-          const imageConnectionId =
-            imagePromptAgentForInstructions.type === "illustrator"
-              ? resolveIllustratorImageConnectionId(
-                  requestChatMode,
-                  chatMeta,
-                  imagePromptAgentForInstructions.settings?.imageConnectionId,
-                )
-              : typeof imagePromptAgentForInstructions.settings?.imageConnectionId === "string"
-                ? imagePromptAgentForInstructions.settings.imageConnectionId.trim()
-                : "";
-          let imageConnectionForInstructions = imageConnectionId
-            ? await connections.getById(imageConnectionId).catch(() => null)
-            : null;
-          imageConnectionForInstructions ??= await connections.getDefaultForImageGeneration().catch(() => null);
-          const imagePromptInstructions = normalizeImagePromptInstructions(
-            imageConnectionForInstructions?.imagePromptInstructions,
-          );
-          if (imagePromptInstructions) agentContext.memory._imagePromptInstructions = imagePromptInstructions;
-        }
         const getLatestUserExpressionSource = () =>
           (
             [...agentContext.recentMessages]
@@ -4362,7 +4342,32 @@ export async function generateRoutes(app: FastifyInstance) {
         // Pre-generation prompt-patch agents read the assembled prompt here; this is overwritten
         // with the fitted provider prompt before each main model call.
         agentContext.memory._mainPromptPreview = promptPreviewForAgents(finalMessages);
-        const pipeline = createAgentPipeline(pipelineAgents, agentContext, sendAgentEventAfterMainStream);
+        const resolveImagePromptAgentContext = async (agent: AgentExecConfig, context: AgentContext): Promise<AgentContext> => {
+          const isImagePromptAgent =
+            agent.type === "illustrator" ||
+            (agent.isCustomAgent === true && customAgentHasCapability(agent.settings, "trigger_image_generation"));
+          if (!isImagePromptAgent) return context;
+
+          const memory = { ...context.memory };
+          delete memory._imagePromptInstructions;
+          const imageConnectionId =
+            agent.type === "illustrator"
+              ? resolveIllustratorImageConnectionId(chatMode, chatMeta, agent.settings.imageConnectionId)
+              : typeof agent.settings.imageConnectionId === "string"
+                ? agent.settings.imageConnectionId.trim()
+                : "";
+          let imageConnection = imageConnectionId ? await connections.getWithKey(imageConnectionId) : null;
+          imageConnection ??= await connections.getDefaultForImageGeneration();
+          const imagePromptInstructions = normalizeImagePromptInstructions(imageConnection?.imagePromptInstructions);
+          if (imagePromptInstructions) memory._imagePromptInstructions = imagePromptInstructions;
+          return { ...context, memory };
+        };
+        const pipeline = createAgentPipeline(
+          pipelineAgents,
+          agentContext,
+          sendAgentEventAfterMainStream,
+          resolveImagePromptAgentContext,
+        );
         let directorSecretPlotResults: AgentResult[] = [];
         let directorSecretPlotArcForPrompt: unknown = directorSecretPlotMemory.overarchingArc;
 
diff --git a/packages/server/src/services/agents/agent-executor.ts b/packages/server/src/services/agents/agent-executor.ts
index 37e0c7efd3..855bda9929 100644
--- a/packages/server/src/services/agents/agent-executor.ts
+++ b/packages/server/src/services/agents/agent-executor.ts
@@ -1057,6 +1057,7 @@ export async function executeAgentBatch(
   context: AgentContext,
   provider: BaseLLMProvider,
   model: string,
+  resolveAgentContext?: (config: AgentExecConfig, context: AgentContext) => AgentContext | Promise<AgentContext>,
 ): Promise<AgentResult[]> {
   if (configs.length === 0) return [];
   const isolatedConfigs = configs.filter(shouldRunAgentIndividually);
@@ -1076,7 +1077,7 @@ export async function executeAgentBatch(
     const isolatedSettled = await settleAgentJobsWithConcurrencyLimit(
       isolatedConfigs,
       AGENT_BATCH_FALLBACK_MAX_CONCURRENT,
-      (config) => executeAgent(config, context, provider, model),
+      async (config) => executeAgent(config, resolveAgentContext ? await resolveAgentContext(config, context) : context, provider, model),
     );
     return isolatedSettled.map((entry, index) =>
       entry.status === "fulfilled"
@@ -1096,9 +1097,13 @@ export async function executeAgentBatch(
     );
     const batchedConfigs = configs.filter((config) => !shouldRunAgentIndividually(config));
     const [batchedResults, isolatedSettled] = await Promise.all([
-      executeAgentBatch(batchedConfigs, context, provider, model),
+      executeAgentBatch(batchedConfigs, context, provider, model, resolveAgentContext),
       settleAgentJobsWithConcurrencyLimit(isolatedConfigs, AGENT_BATCH_FALLBACK_MAX_CONCURRENT, (config) =>
-        executeAgent(config, context, provider, model),
+        resolveAgentContext
+          ? Promise.resolve(resolveAgentContext(config, context)).then((agentContext) =>
+              executeAgent(config, agentContext, provider, model),
+            )
+          : executeAgent(config, context, provider, model),
       ),
     ]);
     const isolatedResults = isolatedSettled.map((entry, index) =>
@@ -1114,7 +1119,8 @@ export async function executeAgentBatch(
   }
   if (configs.length === 1) {
     logger.info(`[agent-batch] Only 1 agent (${configs[0]!.type}), running individually`);
-    return [await executeAgent(configs[0]!, context, provider, model)];
+    const agentContext = resolveAgentContext ? await resolveAgentContext(configs[0]!, context) : context;
+    return [await executeAgent(configs[0]!, agentContext, provider, model)];
   }
 
   const requestOptionGroups = new Map<string, AgentExecConfig[]>();
@@ -1283,7 +1289,7 @@ export async function executeAgentBatch(
       const retrySettled = await settleAgentJobsWithConcurrencyLimit(
         failed,
         AGENT_BATCH_FALLBACK_MAX_CONCURRENT,
-        (config) => executeAgent(config, context, provider, model),
+        async (config) => executeAgent(config, resolveAgentContext ? await resolveAgentContext(config, context) : context, provider, model),
       );
       const retries: AgentResult[] = [];
       for (let i = 0; i < retrySettled.length; i++) {
diff --git a/packages/server/src/services/agents/agent-pipeline.ts b/packages/server/src/services/agents/agent-pipeline.ts
index c35181245e..d3fa9d5861 100644
--- a/packages/server/src/services/agents/agent-pipeline.ts
+++ b/packages/server/src/services/agents/agent-pipeline.ts
@@ -39,6 +39,11 @@ export interface AgentInjection {
   text: string;
 }
 
+export type AgentContextResolver = (
+  agent: AgentExecConfig,
+  context: AgentContext,
+) => AgentContext | Promise<AgentContext>;
+
 /** Callback fired whenever an agent produces a result. */
 export type AgentResultCallback = (result: AgentResult) => void;
 
@@ -165,8 +170,11 @@ async function executeGroup(
   group: AgentGroup,
   context: AgentContext,
   onResult?: AgentResultCallback,
+  resolveAgentContext?: AgentContextResolver,
 ): Promise<AgentResult[]> {
-  const groupContext = buildAgentContext(group.agents[0]!, context);
+  const groupContext = resolveAgentContext
+    ? await resolveAgentContext(group.agents[0]!, buildAgentContext(group.agents[0]!, context))
+    : buildAgentContext(group.agents[0]!, context);
   // Separate tool-using agents (can't be batched) from regular agents. Spotify always
   // returns one JSON intent; deterministic host-side playback runs after parsing.
   const toolAgents = group.agents.filter((a) => shouldUseToolsDuringAgentExecution(a));
@@ -189,7 +197,7 @@ async function executeGroup(
 
   const batchResultsPromise =
     batchAgents.length > 0
-      ? executeAgentBatch(batchAgents, groupContext, group.provider, group.model).then((results) => {
+      ? executeAgentBatch(batchAgents, groupContext, group.provider, group.model, resolveAgentContext).then((results) => {
           for (const result of results) {
             safeOnResult(result);
           }
@@ -207,7 +215,10 @@ async function executeGroup(
     toolAgents,
     AGENT_GROUP_MAX_CONCURRENT_TOOL_CALLS,
     (agent) =>
-      executeAgent(agent, buildAgentContext(agent, context), agent.provider, agent.model, agent.toolContext).then((result) => {
+      (resolveAgentContext
+        ? Promise.resolve(resolveAgentContext(agent, buildAgentContext(agent, context)))
+        : Promise.resolve(buildAgentContext(agent, context))
+      ).then((agentContext) => executeAgent(agent, agentContext, agent.provider, agent.model, agent.toolContext)).then((result) => {
         safeOnResult(result);
         return result;
       }),
@@ -249,6 +260,7 @@ async function executePhase(
   phase: string,
   context: AgentContext,
   onResult?: AgentResultCallback,
+  resolveAgentContext?: AgentContextResolver,
 ): Promise<AgentResult[]> {
   const phaseAgents = agents.filter((a) => a.phase === phase);
   if (phaseAgents.length === 0) return [];
@@ -275,7 +287,7 @@ async function executePhase(
   const settled = await settleAgentJobsWithConcurrencyLimit(
     groups,
     AGENT_PHASE_MAX_CONCURRENT_GROUPS,
-    (group) => executeGroup(group, context, onResult),
+    (group) => executeGroup(group, context, onResult, resolveAgentContext),
   );
 
   const results: AgentResult[] = [];
@@ -337,9 +349,10 @@ export async function runPreGenerationAgents(
   context: AgentContext,
   onResult?: AgentResultCallback,
   agentTypeFilter?: (agentType: string) => boolean,
+  resolveAgentContext?: AgentContextResolver,
 ): Promise<AgentInjection[]> {
   const filtered = agentTypeFilter ? agents.filter((a) => agentTypeFilter(a.type)) : agents;
-  const results = await executePhase(filtered, "pre_generation", context, onResult);
+  const results = await executePhase(filtered, "pre_generation", context, onResult, resolveAgentContext);
 
   const injections: AgentInjection[] = [];
   for (const result of results) {
@@ -378,8 +391,9 @@ export async function runPostProcessingAgents(
   agents: ResolvedAgent[],
   context: AgentContext,
   onResult?: AgentResultCallback,
+  resolveAgentContext?: AgentContextResolver,
 ): Promise<AgentResult[]> {
-  return executePhase(agents, "post_processing", context, onResult);
+  return executePhase(agents, "post_processing", context, onResult, resolveAgentContext);
 }
 
 /**
@@ -389,8 +403,9 @@ export async function runParallelAgents(
   agents: ResolvedAgent[],
   context: AgentContext,
   onResult?: AgentResultCallback,
+  resolveAgentContext?: AgentContextResolver,
 ): Promise<AgentResult[]> {
-  return executePhase(agents, "parallel", context, onResult);
+  return executePhase(agents, "parallel", context, onResult, resolveAgentContext);
 }
 
 // ──────────────────────────────────────────────
@@ -417,6 +432,7 @@ export function createAgentPipeline(
   agents: ResolvedAgent[],
   baseContext: AgentContext,
   onResult?: AgentResultCallback,
+  resolveAgentContext?: AgentContextResolver,
 ) {
   const allResults: AgentResult[] = [];
   const preGenerationInjections: AgentInjection[] = [];
@@ -433,7 +449,13 @@ export function createAgentPipeline(
      * Returns context injection strings to prepend to the prompt.
      */
     async preGenerate(agentTypeFilter?: (agentType: string) => boolean): Promise<AgentInjection[]> {
-      const injections = await runPreGenerationAgents(agents, baseContext, wrappedOnResult, agentTypeFilter);
+      const injections = await runPreGenerationAgents(
+        agents,
+        baseContext,
+        wrappedOnResult,
+        agentTypeFilter,
+        resolveAgentContext,
+      );
       preGenerationInjections.push(...injections);
       return injections;
     },
@@ -444,7 +466,7 @@ export function createAgentPipeline(
      * base context without mainResponse (since it doesn't exist yet).
      */
     async runParallel(): Promise<AgentResult[]> {
-      const results = await runParallelAgents(agents, baseContext, wrappedOnResult);
+      const results = await runParallelAgents(agents, baseContext, wrappedOnResult, resolveAgentContext);
       parallelPhaseResults.push(...results);
       return results;
     },
@@ -464,7 +486,7 @@ export function createAgentPipeline(
         parallelResults: options.parallelResults ?? parallelPhaseResults,
       };
 
-      return runPostProcessingAgents(agents, fullContext, wrappedOnResult);
+      return runPostProcessingAgents(agents, fullContext, wrappedOnResult, resolveAgentContext);
     },
 
     /** All results collected so far. */

From 69343ed51eb5c5dfc4c3bbda4f0bce98ca62902a Mon Sep 17 00:00:00 2001
From: SNPAU <SNPAU@users.noreply.github.com>
Date: Mon, 10 Aug 2026 16:35:16 +1000
Subject: [PATCH 6/7] Raise limit, I can't fit my 6k characters instructions in

---
 CHANGELOG.md                                             | 2 +-
 packages/server/src/routes/game.routes.ts                | 9 +++++----
 .../server/src/services/game/game-asset-generation.ts    | 5 +++--
 packages/server/src/services/sidecar/scene-analyzer.ts   | 3 ++-
 packages/shared/src/constants/defaults.ts                | 2 +-
 packages/shared/src/schemas/scene-analysis.schema.ts     | 3 ++-
 6 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b67ba18c21..2a37e78fc6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -46,7 +46,7 @@ This file is the release-notes source of truth for Marinara Engine. Reuse these
 
 ### Fixed
 
-- Scoped image-connection prompt instructions to image-producing agents, bounded stored instructions to 5,000 characters, and kept each retry agent on its own configured image connection.
+- Scoped image-connection prompt instructions to image-producing agents, bounded stored instructions to 20,000 characters, and kept each retry agent on its own configured image connection.
 - Kept Professor Mari's Home navigator enabled by default and visible with reduced effects, reset her to the default position when re-enabled, centered her drag handle, contained compact Field Notes and Community actions, and presented iPad sidebars as full-width overlays (#4826, #4827, #4829, #4830).
 - Sharpened Professor Mari's read-only guardrail so a "how do I…" question is answered or offered rather than performed, even when it names the change as its goal (for example "how do I make X have Y") — while a plainly-worded request to make that change, including a polite question form like "can you set X to Y", is still carried out — so she keys on intent rather than grammar and no longer edits without a clear instruction (#4838).
 - Reduced background autonomous-message polling to a lightweight candidate-id lookup instead of re-fetching the full chat list every 30 seconds (#4715).
diff --git a/packages/server/src/routes/game.routes.ts b/packages/server/src/routes/game.routes.ts
index 57f5ced6f3..37376ea9b6 100644
--- a/packages/server/src/routes/game.routes.ts
+++ b/packages/server/src/routes/game.routes.ts
@@ -155,6 +155,7 @@ import {
   parseTrackerHiddenFields,
   normalizeRpgStatPools,
   normalizeIllustratorImagesPerGeneration,
+  MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH,
   resolveGameSetupArtStylePrompt,
   BUILT_IN_AGENT_IDS,
   STORYBOARD_AGENT_ID,
@@ -10295,7 +10296,7 @@ export async function gameRoutes(app: FastifyInstance) {
       .catch(() => null);
     const imagePromptInstructions =
       typeof meta.gameImagePromptInstructions === "string"
-        ? meta.gameImagePromptInstructions.trim().slice(0, 5000)
+        ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
         : "";
 
     // Compute approximate turn number: count user messages + 1 (current turn)
@@ -11178,7 +11179,7 @@ export async function gameRoutes(app: FastifyInstance) {
         null;
       const imagePromptInstructions =
         ownerMode === "game" && typeof meta.gameImagePromptInstructions === "string"
-          ? meta.gameImagePromptInstructions.trim().slice(0, 5000)
+          ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
           : "";
       const useAvatarReferences = meta.storyboardAgentUseAvatarReferences !== false;
       const useStoryboardPromptTemplate =
@@ -12028,7 +12029,7 @@ export async function gameRoutes(app: FastifyInstance) {
       null;
     const imagePromptInstructions =
       typeof meta.gameImagePromptInstructions === "string"
-        ? meta.gameImagePromptInstructions.trim().slice(0, 5000)
+        ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
         : "";
     const useAvatarReferences = input.useAvatarReferences ?? meta.gameImageUseAvatarReferences !== false;
     const includeCharacterAppearance =
@@ -12441,7 +12442,7 @@ export async function gameRoutes(app: FastifyInstance) {
         null;
       const imagePromptInstructions =
         typeof meta.gameImagePromptInstructions === "string"
-          ? meta.gameImagePromptInstructions.trim().slice(0, 5000)
+          ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
           : "";
       const useAvatarReferences = input.useAvatarReferences ?? meta.gameImageUseAvatarReferences !== false;
       const includeCharacterAppearance =
diff --git a/packages/server/src/services/game/game-asset-generation.ts b/packages/server/src/services/game/game-asset-generation.ts
index 9fe95768c6..c314aee121 100644
--- a/packages/server/src/services/game/game-asset-generation.ts
+++ b/packages/server/src/services/game/game-asset-generation.ts
@@ -24,6 +24,7 @@ import {
 } from "../prompt-overrides/index.js";
 import {
   inferImageSource,
+  MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH,
   type ImageGenerationDefaultsProfile,
   type ImageGenerationQuality,
   type ImageStyleProfileSettings,
@@ -990,7 +991,7 @@ async function buildBackgroundRawPrompt(req: BackgroundGenRequest): Promise<stri
     ? await loadPrompt(req.promptOverridesStorage, GAME_BACKGROUND, backgroundVars)
     : GAME_BACKGROUND.defaultBuilder(backgroundVars);
   const imagePromptInstructionsLine = req.imagePromptInstructions?.trim()
-    ? `User image instructions: ${req.imagePromptInstructions.trim().replace(/\s+/g, " ").slice(0, 5000)}`
+    ? `User image instructions: ${req.imagePromptInstructions.trim().replace(/\s+/g, " ").slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)}`
     : "";
   return imagePromptInstructionsLine && !rawPrompt.includes(imagePromptInstructionsLine)
     ? `${rawPrompt}\n${imagePromptInstructionsLine}`
@@ -1124,7 +1125,7 @@ async function buildSceneIllustrationRawPrompt(req: SceneIllustrationGenRequest)
   const referenceImages = sceneIllustrationReferenceImagesForProvider(req);
   const characterReferenceImagesAttached = referenceImages.length > (req.locationReferenceImageAttached ? 1 : 0);
   const imagePromptInstructionsLine = req.imagePromptInstructions?.trim()
-    ? `User image instructions: ${req.imagePromptInstructions.trim().replace(/\s+/g, " ").slice(0, 5000)}`
+    ? `User image instructions: ${req.imagePromptInstructions.trim().replace(/\s+/g, " ").slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)}`
     : "";
   const useGamePromptTemplate = req.useGamePromptTemplate !== false;
   const scopedScenePrompt = req.prompt.trim();
diff --git a/packages/server/src/services/sidecar/scene-analyzer.ts b/packages/server/src/services/sidecar/scene-analyzer.ts
index e8b0fd64c9..de98d6ee26 100644
--- a/packages/server/src/services/sidecar/scene-analyzer.ts
+++ b/packages/server/src/services/sidecar/scene-analyzer.ts
@@ -11,6 +11,7 @@ import {
   LOCATION_KINDS,
   MUSIC_GENRES,
   MUSIC_INTENSITIES,
+  MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH,
   type HudWidget,
   type GameNpc,
   type GameActiveState,
@@ -116,7 +117,7 @@ function buildBackgroundOptions(ctx?: SceneAnalyzerContext): string[] {
 }
 
 function compactImagePromptInstructions(value: string | null | undefined): string {
-  return (value ?? "").trim().replace(/\s+/g, " ").slice(0, 5000);
+  return (value ?? "").trim().replace(/\s+/g, " ").slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH);
 }
 
 function compactPromptLabel(value: string | null | undefined): string {
diff --git a/packages/shared/src/constants/defaults.ts b/packages/shared/src/constants/defaults.ts
index bf82d9aca9..edb9df4086 100644
--- a/packages/shared/src/constants/defaults.ts
+++ b/packages/shared/src/constants/defaults.ts
@@ -19,7 +19,7 @@ export const DEFAULT_CONNECTION_ID = "__default_openrouter__";
 export const BACKGROUND_THUMBNAIL_WIDTH = 320;
 
 /** Maximum length for image-backend instructions stored on an image connection. */
-export const MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH = 5_000;
+export const MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH = 20_000;
 
 export function normalizeImagePromptInstructions(value: unknown): string | null {
   if (typeof value !== "string") return null;
diff --git a/packages/shared/src/schemas/scene-analysis.schema.ts b/packages/shared/src/schemas/scene-analysis.schema.ts
index 852a557e3c..5eaf9580bb 100644
--- a/packages/shared/src/schemas/scene-analysis.schema.ts
+++ b/packages/shared/src/schemas/scene-analysis.schema.ts
@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH } from "../constants/defaults.js";
 import type { GameNpc, HudWidget } from "../types/game.js";
 import type { GameActiveState } from "../types/game.js";
 import type { SceneSpotifyTrackCandidate } from "../types/sidecar.js";
@@ -44,7 +45,7 @@ export const sceneAnalysisContextSchema = z.object({
   canGenerateBackgrounds: z.boolean().optional(),
   canGenerateIllustrations: z.boolean().optional(),
   artStylePrompt: z.string().nullable().optional(),
-  imagePromptInstructions: z.string().max(5_000).nullable().optional(),
+  imagePromptInstructions: z.string().max(MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH).nullable().optional(),
 });
 
 export const sceneAnalysisRequestSchema = z.object({

From 177a6e6f06b4d6d4111d585ba128f12c2e68e3a5 Mon Sep 17 00:00:00 2001
From: SNPAU <SNPAU@users.noreply.github.com>
Date: Mon, 10 Aug 2026 16:58:26 +1000
Subject: [PATCH 7/7] Address image prompt review follow-ups

---
 packages/server/src/routes/game.routes.ts              | 10 +++++-----
 packages/server/src/routes/generate.routes.ts          |  3 ++-
 packages/server/src/services/agents/agent-executor.ts  |  2 +-
 .../server/src/services/game/game-asset-generation.ts  |  6 +++---
 packages/server/src/services/sidecar/scene-analyzer.ts |  2 +-
 5 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/packages/server/src/routes/game.routes.ts b/packages/server/src/routes/game.routes.ts
index 37376ea9b6..782fa84ceb 100644
--- a/packages/server/src/routes/game.routes.ts
+++ b/packages/server/src/routes/game.routes.ts
@@ -63,6 +63,7 @@ import { listPartySprites, readPreferredFullBodySpriteBase64 } from "../services
 import {
   buildSceneAnalyzerSystemPrompt,
   buildSceneAnalyzerUserPrompt,
+  compactImagePromptInstructions,
   type SceneAnalyzerContext,
 } from "../services/sidecar/scene-analyzer.js";
 import { postProcessSceneResult, type PostProcessContext } from "../services/sidecar/scene-postprocess.js";
@@ -155,7 +156,6 @@ import {
   parseTrackerHiddenFields,
   normalizeRpgStatPools,
   normalizeIllustratorImagesPerGeneration,
-  MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH,
   resolveGameSetupArtStylePrompt,
   BUILT_IN_AGENT_IDS,
   STORYBOARD_AGENT_ID,
@@ -10296,7 +10296,7 @@ export async function gameRoutes(app: FastifyInstance) {
       .catch(() => null);
     const imagePromptInstructions =
       typeof meta.gameImagePromptInstructions === "string"
-        ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
+        ? compactImagePromptInstructions(meta.gameImagePromptInstructions)
         : "";
 
     // Compute approximate turn number: count user messages + 1 (current turn)
@@ -11179,7 +11179,7 @@ export async function gameRoutes(app: FastifyInstance) {
         null;
       const imagePromptInstructions =
         ownerMode === "game" && typeof meta.gameImagePromptInstructions === "string"
-          ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
+          ? compactImagePromptInstructions(meta.gameImagePromptInstructions)
           : "";
       const useAvatarReferences = meta.storyboardAgentUseAvatarReferences !== false;
       const useStoryboardPromptTemplate =
@@ -12029,7 +12029,7 @@ export async function gameRoutes(app: FastifyInstance) {
       null;
     const imagePromptInstructions =
       typeof meta.gameImagePromptInstructions === "string"
-        ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
+        ? compactImagePromptInstructions(meta.gameImagePromptInstructions)
         : "";
     const useAvatarReferences = input.useAvatarReferences ?? meta.gameImageUseAvatarReferences !== false;
     const includeCharacterAppearance =
@@ -12442,7 +12442,7 @@ export async function gameRoutes(app: FastifyInstance) {
         null;
       const imagePromptInstructions =
         typeof meta.gameImagePromptInstructions === "string"
-          ? meta.gameImagePromptInstructions.trim().slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)
+          ? compactImagePromptInstructions(meta.gameImagePromptInstructions)
           : "";
       const useAvatarReferences = input.useAvatarReferences ?? meta.gameImageUseAvatarReferences !== false;
       const includeCharacterAppearance =
diff --git a/packages/server/src/routes/generate.routes.ts b/packages/server/src/routes/generate.routes.ts
index b3335db115..efcb96e9e6 100644
--- a/packages/server/src/routes/generate.routes.ts
+++ b/packages/server/src/routes/generate.routes.ts
@@ -7653,9 +7653,10 @@ export async function generateRoutes(app: FastifyInstance) {
                       historicalLorebookTarget.id,
                     ) ?? phaseRetryContext)
                   : phaseRetryContext;
+                const resolvedRetryContext = await resolveImagePromptAgentContext(agentCfg, retryCtx);
                 const retried = await executeAgent(
                   agentCfg,
-                  retryCtx,
+                  resolvedRetryContext,
                   agentCfg.provider,
                   agentCfg.model,
                   agentCfg.type === "spotify" ? undefined : agentCfg.toolContext,
diff --git a/packages/server/src/services/agents/agent-executor.ts b/packages/server/src/services/agents/agent-executor.ts
index 855bda9929..5dd35206f8 100644
--- a/packages/server/src/services/agents/agent-executor.ts
+++ b/packages/server/src/services/agents/agent-executor.ts
@@ -1138,7 +1138,7 @@ export async function executeAgentBatch(
     );
     const groupedResults: AgentResult[] = [];
     for (const group of requestOptionGroups.values()) {
-      groupedResults.push(...(await executeAgentBatch(group, context, provider, model)));
+      groupedResults.push(...(await executeAgentBatch(group, context, provider, model, resolveAgentContext)));
     }
     return groupedResults;
   }
diff --git a/packages/server/src/services/game/game-asset-generation.ts b/packages/server/src/services/game/game-asset-generation.ts
index c314aee121..edc6ea5528 100644
--- a/packages/server/src/services/game/game-asset-generation.ts
+++ b/packages/server/src/services/game/game-asset-generation.ts
@@ -24,7 +24,6 @@ import {
 } from "../prompt-overrides/index.js";
 import {
   inferImageSource,
-  MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH,
   type ImageGenerationDefaultsProfile,
   type ImageGenerationQuality,
   type ImageStyleProfileSettings,
@@ -34,6 +33,7 @@ import type { ImageGenerationSize } from "../image/image-generation-settings.js"
 import { compileImagePrompt } from "../image/image-prompt-compiler.js";
 import { loadGameStoryboardImagePrompt } from "../image/game-storyboard-image-prompt.js";
 import { SPATIAL_LOCATION_REFERENCE_PROMPT_LINE } from "../image/spatial-location-reference.js";
+import { compactImagePromptInstructions } from "../sidecar/scene-analyzer.js";
 
 const NPC_AVATAR_DIR = join(DATA_DIR, "avatars", "npc");
 const CHAT_BACKGROUND_DIR = join(DATA_DIR, "backgrounds");
@@ -991,7 +991,7 @@ async function buildBackgroundRawPrompt(req: BackgroundGenRequest): Promise<stri
     ? await loadPrompt(req.promptOverridesStorage, GAME_BACKGROUND, backgroundVars)
     : GAME_BACKGROUND.defaultBuilder(backgroundVars);
   const imagePromptInstructionsLine = req.imagePromptInstructions?.trim()
-    ? `User image instructions: ${req.imagePromptInstructions.trim().replace(/\s+/g, " ").slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)}`
+    ? `User image instructions: ${compactImagePromptInstructions(req.imagePromptInstructions)}`
     : "";
   return imagePromptInstructionsLine && !rawPrompt.includes(imagePromptInstructionsLine)
     ? `${rawPrompt}\n${imagePromptInstructionsLine}`
@@ -1125,7 +1125,7 @@ async function buildSceneIllustrationRawPrompt(req: SceneIllustrationGenRequest)
   const referenceImages = sceneIllustrationReferenceImagesForProvider(req);
   const characterReferenceImagesAttached = referenceImages.length > (req.locationReferenceImageAttached ? 1 : 0);
   const imagePromptInstructionsLine = req.imagePromptInstructions?.trim()
-    ? `User image instructions: ${req.imagePromptInstructions.trim().replace(/\s+/g, " ").slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH)}`
+    ? `User image instructions: ${compactImagePromptInstructions(req.imagePromptInstructions)}`
     : "";
   const useGamePromptTemplate = req.useGamePromptTemplate !== false;
   const scopedScenePrompt = req.prompt.trim();
diff --git a/packages/server/src/services/sidecar/scene-analyzer.ts b/packages/server/src/services/sidecar/scene-analyzer.ts
index de98d6ee26..04bb9ba0ec 100644
--- a/packages/server/src/services/sidecar/scene-analyzer.ts
+++ b/packages/server/src/services/sidecar/scene-analyzer.ts
@@ -116,7 +116,7 @@ function buildBackgroundOptions(ctx?: SceneAnalyzerContext): string[] {
   return options;
 }
 
-function compactImagePromptInstructions(value: string | null | undefined): string {
+export function compactImagePromptInstructions(value: string | null | undefined): string {
   return (value ?? "").trim().replace(/\s+/g, " ").slice(0, MAX_IMAGE_PROMPT_INSTRUCTIONS_LENGTH);
 }