diff --git a/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx b/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
new file mode 100644
index 0000000..3a36836
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx
@@ -0,0 +1,204 @@
+/**
+ * Helper sub-components extracted from ChatPanel
+ *
+ * StageIndicator, ActionsTaken, CharacterAvatar, renderMessageContent
+ */
+
+import React, { useState, useEffect, useCallback, memo, useRef } from 'react';
+import { ChevronDown, ChevronRight } from 'lucide-react';
+import type { CharacterConfig } from '@/lib/characterManager';
+import { resolveEmotionMedia } from '@/lib/characterManager';
+import type { ModManager } from '@/lib/modManager';
+import styles from './index.module.scss';
+
+// ---------------------------------------------------------------------------
+// Render message content — formats (action text) as styled spans
+// ---------------------------------------------------------------------------
+
+export function renderMessageContent(content: string): React.ReactNode {
+  const parts = content.split(/(\([^)]+\))/g);
+  return parts.map((part, i) => {
+    if (/^\([^)]+\)$/.test(part)) {
+      return (
+        <span key={i} className={styles.emotion}>
+          {part}
+        </span>
+      );
+    }
+    return part;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Stage Indicator
+// ---------------------------------------------------------------------------
+
+export const StageIndicator: React.FC<{ modManager: ModManager | null }> = ({ modManager }) => {
+  if (!modManager) return null;
+
+  const total = modManager.stageCount;
+  const current = modManager.currentStageIndex;
+  const finished = modManager.isFinished;
+
+  return (
+    <div className={styles.stageIndicator}>
+      <span className={styles.stageText}>
+        Stage {finished ? total : current + 1}/{total}
+      </span>
+      <div className={styles.stageDots}>
+        {Array.from({ length: total }, (_, i) => (
+          <div
+            key={i}
+            className={`${styles.stageDot} ${
+              i < current || finished
+                ? styles.stageDotCompleted
+                : i === current
+                  ? styles.stageDotCurrent
+                  : ''
+            }`}
+          />
+        ))}
+      </div>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Actions Taken (collapsible)
+// ---------------------------------------------------------------------------
+
+export const ActionsTaken: React.FC<{ calls: string[] }> = ({ calls }) => {
+  const [open, setOpen] = useState(false);
+  if (calls.length === 0) return null;
+
+  return (
+    <div className={styles.actionsTaken}>
+      <button className={styles.actionsTakenToggle} onClick={() => setOpen(!open)}>
+        Actions taken
+        {open ? <ChevronDown size={12} /> : <ChevronRight size={12} />}
+      </button>
+      {open && (
+        <div className={styles.actionsTakenList}>
+          {calls.map((c, i) => (
+            <div key={i}>{c}</div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// CharacterAvatar – crossfade between emotion media without flashing
+// ---------------------------------------------------------------------------
+
+interface AvatarLayer {
+  url: string;
+  type: 'video' | 'image';
+  active: boolean;
+}
+
+export const CharacterAvatar: React.FC<{
+  character: CharacterConfig;
+  emotion?: string;
+  onEmotionEnd: () => void;
+}> = memo(({ character, emotion, onEmotionEnd }) => {
+  const isIdle = !emotion;
+  const media = resolveEmotionMedia(character, emotion || 'default');
+
+  const [layers, setLayers] = useState<AvatarLayer[]>(() =>
+    media ? [{ url: media.url, type: media.type, active: true }] : [],
+  );
+  const activeUrl = layers.find((l) => l.active)?.url;
+  const cleanupRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (cleanupRef.current) clearTimeout(cleanupRef.current);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!media) {
+      setLayers([]);
+      return;
+    }
+    if (media.url === activeUrl) return;
+    setLayers((prev) => {
+      // If the URL already exists (possibly inactive), reactivate it
+      const existing = prev.find((l) => l.url === media.url);
+      if (existing) {
+        // Cancel any pending cleanup that might remove this layer
+        if (cleanupRef.current) {
+          clearTimeout(cleanupRef.current);
+          cleanupRef.current = null;
+        }
+        return prev.map((l) => ({
+          ...l,
+          active: l.url === media.url,
+        }));
+      }
+      return [...prev, { url: media.url, type: media.type, active: false }];
+    });
+  }, [media?.url, activeUrl]);
+
+  const desiredUrlRef = useRef<string | undefined>(media?.url);
+  desiredUrlRef.current = media?.url;
+
+  const handleMediaReady = useCallback((readyUrl: string) => {
+    // Ignore stale loads — if the user has since switched to a different emotion,
+    // don't activate the old layer
+    if (desiredUrlRef.current && readyUrl !== desiredUrlRef.current) return;
+    setLayers((prev) => {
+      const staleUrls = prev.filter((l) => l.url !== readyUrl).map((l) => l.url);
+      if (cleanupRef.current) clearTimeout(cleanupRef.current);
+      cleanupRef.current = setTimeout(() => {
+        setLayers((curr) => curr.filter((l) => !staleUrls.includes(l.url)));
+      }, 300);
+      return prev.map((l) => ({ ...l, active: l.url === readyUrl }));
+    });
+  }, []);
+
+  if (layers.length === 0) {
+    return <div className={styles.avatarPlaceholder}>{character.character_name.charAt(0)}</div>;
+  }
+
+  return (
+    <>
+      {layers.map((layer) => {
+        const layerStyle: React.CSSProperties = {
+          position: 'absolute',
+          inset: 0,
+          opacity: layer.active ? 1 : 0,
+          transition: 'opacity 0.25s ease-out',
+        };
+        if (layer.type === 'video') {
+          return (
+            <video
+              key={layer.url}
+              className={styles.avatarImage}
+              style={layerStyle}
+              src={layer.url}
+              autoPlay
+              loop={layer.active ? isIdle : false}
+              muted
+              playsInline
+              onCanPlay={!layer.active ? () => handleMediaReady(layer.url) : undefined}
+              onEnded={layer.active && !isIdle ? onEmotionEnd : undefined}
+            />
+          );
+        }
+        return (
+          <img
+            key={layer.url}
+            className={styles.avatarImage}
+            style={layerStyle}
+            src={layer.url}
+            alt={character.character_name}
+            onLoad={!layer.active ? () => handleMediaReady(layer.url) : undefined}
+          />
+        );
+      })}
+    </>
+  );
+});
diff --git a/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
new file mode 100644
index 0000000..a706e27
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx
@@ -0,0 +1,395 @@
+/**
+ * SettingsModal — LLM + Image Generation configuration
+ *
+ * Extracted from ChatPanel for maintainability.
+ */
+
+import React, { useState, useEffect, useRef } from 'react';
+import { Pencil, List } from 'lucide-react';
+import { PROVIDER_MODELS, getDefaultProviderConfig, type LLMProvider } from '@/lib/llmModels';
+import type { LLMConfig, LLMConfigUpdate } from '@/lib/llmModels';
+import {
+  getDefaultImageGenConfig,
+  type ImageGenConfig,
+  type ImageGenConfigUpdate,
+  type ImageGenProvider,
+} from '@/lib/imageGenClient';
+import styles from './index.module.scss';
+
+interface SettingsModalProps {
+  config: LLMConfig | null;
+  imageGenConfig: ImageGenConfig | null;
+  onSave: (
+    _config: LLMConfigUpdate,
+    _igConfig: ImageGenConfigUpdate | null,
+  ) => Promise<{ ok: boolean; error?: string }> | { ok: boolean; error?: string } | void;
+  onClose: () => void;
+}
+
+const SettingsModal: React.FC<SettingsModalProps> = ({
+  config,
+  imageGenConfig,
+  onSave,
+  onClose,
+}) => {
+  // LLM settings
+  const [provider, setProvider] = useState<LLMProvider>(config?.provider || 'minimax');
+  const [apiKey, setApiKey] = useState('');
+  const [apiKeyDirty, setApiKeyDirty] = useState(false);
+  const [baseUrl, setBaseUrl] = useState(
+    config?.baseUrl || getDefaultProviderConfig('minimax').baseUrl,
+  );
+  const [model, setModel] = useState(config?.model || getDefaultProviderConfig('minimax').model);
+  const [customHeaders, setCustomHeaders] = useState(config?.customHeaders || '');
+  const [manualModelMode, setManualModelMode] = useState(false);
+
+  const isPresetModel = PROVIDER_MODELS[provider]?.includes(model) ?? false;
+  const showDropdown = !manualModelMode && isPresetModel;
+
+  // Image gen settings
+  const [igProvider, setIgProvider] = useState<ImageGenProvider>(
+    imageGenConfig?.provider || 'gemini',
+  );
+  const [igApiKey, setIgApiKey] = useState('');
+  const [igApiKeyDirty, setIgApiKeyDirty] = useState(false);
+  const [igBaseUrl, setIgBaseUrl] = useState(
+    imageGenConfig?.baseUrl || getDefaultImageGenConfig('gemini').baseUrl,
+  );
+  const [igModel, setIgModel] = useState(
+    imageGenConfig?.model || getDefaultImageGenConfig('gemini').model,
+  );
+  const [igCustomHeaders, setIgCustomHeaders] = useState(imageGenConfig?.customHeaders || '');
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  // Track whether the user has edited any field locally — prevents useEffect from clobbering in-progress edits
+  const hasLocalEditsRef = useRef(false);
+
+  // Sync local state when parent props change — but only before first local edit
+  useEffect(() => {
+    if (!config) return;
+    if (hasLocalEditsRef.current) return;
+    setProvider(config.provider);
+    setApiKey('');
+    setApiKeyDirty(false);
+    setBaseUrl(config.baseUrl || getDefaultProviderConfig(config.provider).baseUrl);
+    setModel(config.model || getDefaultProviderConfig(config.provider).model);
+    setCustomHeaders(config.customHeaders || '');
+    setManualModelMode(false);
+  }, [config]);
+
+  useEffect(() => {
+    if (!imageGenConfig) return;
+    if (hasLocalEditsRef.current) return;
+    setIgProvider(imageGenConfig.provider);
+    setIgApiKey('');
+    setIgApiKeyDirty(false);
+    setIgBaseUrl(
+      imageGenConfig.baseUrl || getDefaultImageGenConfig(imageGenConfig.provider).baseUrl,
+    );
+    setIgModel(imageGenConfig.model || getDefaultImageGenConfig(imageGenConfig.provider).model);
+    setIgCustomHeaders(imageGenConfig.customHeaders || '');
+  }, [imageGenConfig]);
+
+  const handleProviderChange = (p: LLMProvider) => {
+    hasLocalEditsRef.current = true;
+    setProvider(p);
+    const defaults = getDefaultProviderConfig(p);
+    setBaseUrl(defaults.baseUrl);
+    setModel(defaults.model);
+    setManualModelMode(false);
+  };
+
+  const handleModelChange = (newModel: string) => {
+    hasLocalEditsRef.current = true;
+    setModel(newModel);
+    setManualModelMode(false);
+  };
+
+  const handleIgProviderChange = (p: ImageGenProvider) => {
+    hasLocalEditsRef.current = true;
+    setIgProvider(p);
+    const defaults = getDefaultImageGenConfig(p);
+    setIgBaseUrl(defaults.baseUrl);
+    setIgModel(defaults.model);
+  };
+
+  const llmApiKeyPlaceholder = config?.hasApiKey
+    ? 'Server key configured (enter to replace)'
+    : 'Optional for local servers';
+  const imageApiKeyPlaceholder = imageGenConfig?.hasApiKey
+    ? 'Server key configured (enter to replace)'
+    : 'API Key...';
+
+  const llmEndpointChanged =
+    !!config && (provider !== config.provider || baseUrl !== config.baseUrl);
+  const imageGenEndpointChanged =
+    !!imageGenConfig &&
+    (igProvider !== imageGenConfig.provider || igBaseUrl !== imageGenConfig.baseUrl);
+
+  const buildImageGenConfig = (): ImageGenConfigUpdate => ({
+    provider: igProvider,
+    baseUrl: igBaseUrl,
+    model: igModel,
+    customHeaders: igCustomHeaders,
+    ...(igApiKeyDirty ? { apiKey: igApiKey } : {}),
+    ...(!igApiKeyDirty && imageGenEndpointChanged ? { apiKey: '' } : {}),
+  });
+
+  return (
+    <div className={styles.overlay} data-testid="settings-overlay">
+      <div className={styles.settingsModal} data-testid="settings-modal">
+        <div className={styles.settingsTitle}>LLM Settings</div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Provider</label>
+          <select
+            className={styles.select}
+            value={provider}
+            onChange={(e) => handleProviderChange(e.target.value as LLMProvider)}
+          >
+            <option value="openai">OpenAI</option>
+            <option value="anthropic">Anthropic</option>
+            <option value="deepseek">DeepSeek</option>
+            <option value="llama.cpp">llama.cpp</option>
+            <option value="minimax">MiniMax</option>
+            <option value="z.ai">Z.ai</option>
+            <option value="kimi">Kimi</option>
+            <option value="openrouter">OpenRouter</option>
+          </select>
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>API Key</label>
+          <input
+            className={styles.fieldInput}
+            type="password"
+            value={apiKey}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setApiKeyDirty(true);
+              setApiKey(e.target.value);
+            }}
+            placeholder={llmApiKeyPlaceholder}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Base URL</label>
+          <input
+            className={styles.fieldInput}
+            value={baseUrl}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setBaseUrl(e.target.value);
+            }}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Model</label>
+          <div className={styles.modelSelectorWrapper}>
+            {showDropdown ? (
+              <>
+                <select
+                  className={styles.select}
+                  value={model}
+                  onChange={(e) => handleModelChange(e.target.value)}
+                >
+                  {PROVIDER_MODELS[provider]?.map((m) => (
+                    <option key={m} value={m}>
+                      {m}
+                    </option>
+                  ))}
+                </select>
+                <button
+                  type="button"
+                  onClick={() => {
+                    hasLocalEditsRef.current = true;
+                    setManualModelMode(true);
+                  }}
+                  className={styles.manualToggleBtn}
+                  title="Enter custom model name"
+                >
+                  <Pencil size={14} />
+                </button>
+              </>
+            ) : (
+              <>
+                <input
+                  className={styles.fieldInput}
+                  value={model}
+                  onChange={(e) => {
+                    hasLocalEditsRef.current = true;
+                    setModel(e.target.value);
+                  }}
+                  placeholder="e.g. gpt-4-turbo"
+                />
+                {isPresetModel && (
+                  <button
+                    type="button"
+                    onClick={() => {
+                      hasLocalEditsRef.current = true;
+                      setManualModelMode(false);
+                    }}
+                    className={styles.manualToggleBtn}
+                    title="Back to model list"
+                  >
+                    <List size={14} />
+                  </button>
+                )}
+              </>
+            )}
+          </div>
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Custom Headers (one per line, Key: Value)</label>
+          <textarea
+            className={styles.fieldInput}
+            value={customHeaders}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setCustomHeaders(e.target.value);
+            }}
+            placeholder={'X-Custom-Header: value\nAnother-Header: value'}
+            rows={3}
+            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
+          />
+        </div>
+
+        <div className={styles.settingsDivider} />
+        <div className={styles.settingsTitle}>Image Generation</div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Provider</label>
+          <select
+            className={styles.select}
+            value={igProvider}
+            onChange={(e) => handleIgProviderChange(e.target.value as ImageGenProvider)}
+          >
+            <option value="openai">OpenAI</option>
+            <option value="gemini">Gemini</option>
+          </select>
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>API Key</label>
+          <input
+            className={styles.fieldInput}
+            type="password"
+            value={igApiKey}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setIgApiKeyDirty(true);
+              setIgApiKey(e.target.value);
+            }}
+            placeholder={imageApiKeyPlaceholder}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Base URL</label>
+          <input
+            className={styles.fieldInput}
+            value={igBaseUrl}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setIgBaseUrl(e.target.value);
+            }}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Model</label>
+          <input
+            className={styles.fieldInput}
+            value={igModel}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setIgModel(e.target.value);
+            }}
+          />
+        </div>
+
+        <div className={styles.field}>
+          <label className={styles.label}>Custom Headers</label>
+          <textarea
+            className={styles.fieldInput}
+            value={igCustomHeaders}
+            onChange={(e) => {
+              hasLocalEditsRef.current = true;
+              setIgCustomHeaders(e.target.value);
+            }}
+            placeholder={'X-Custom-Header: value'}
+            rows={2}
+            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
+          />
+        </div>
+
+        <div className={styles.settingsActions}>
+          {saveError && (
+            <div style={{ color: '#ff6b6b', fontSize: '12px', marginRight: 'auto' }}>
+              {saveError}
+            </div>
+          )}
+          <button className={styles.cancelBtn} onClick={onClose}>
+            Cancel
+          </button>
+          <button
+            className={styles.saveBtn}
+            disabled={saving}
+            onClick={async () => {
+              setSaveError(null);
+              setSaving(true);
+              const llmCfg: LLMConfigUpdate = {
+                provider,
+                baseUrl: baseUrl.trim(),
+                model: model.trim(),
+                customHeaders: customHeaders.trim(),
+              };
+              if (apiKeyDirty) {
+                llmCfg.apiKey = apiKey.trim();
+              } else if (llmEndpointChanged) {
+                llmCfg.apiKey = '';
+              }
+              const nextImageGenConfig = buildImageGenConfig();
+              const igCfg: ImageGenConfigUpdate | null = imageGenConfig
+                ? {
+                    ...nextImageGenConfig,
+                    baseUrl: nextImageGenConfig.baseUrl.trim(),
+                    model: nextImageGenConfig.model.trim(),
+                    customHeaders: nextImageGenConfig.customHeaders?.trim(),
+                    ...(nextImageGenConfig.apiKey
+                      ? { apiKey: nextImageGenConfig.apiKey.trim() }
+                      : {}),
+                  }
+                : igApiKey.trim()
+                  ? {
+                      ...nextImageGenConfig,
+                      apiKey: igApiKey.trim(),
+                      baseUrl: nextImageGenConfig.baseUrl.trim(),
+                      model: nextImageGenConfig.model.trim(),
+                    }
+                  : null;
+              try {
+                const result = await onSave(llmCfg, igCfg);
+                if (result && result.ok === false) {
+                  setSaveError(result.error || 'Failed to save settings');
+                }
+              } catch (err) {
+                setSaveError(err instanceof Error ? err.message : String(err));
+              } finally {
+                setSaving(false);
+              }
+            }}
+          >
+            {saving ? 'Saving...' : 'Save'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default SettingsModal;
diff --git a/apps/webuiapps/src/components/ChatPanel/index.tsx b/apps/webuiapps/src/components/ChatPanel/index.tsx
index 740488c..b7c39e6 100644
--- a/apps/webuiapps/src/components/ChatPanel/index.tsx
+++ b/apps/webuiapps/src/components/ChatPanel/index.tsx
@@ -1,57 +1,29 @@
-import React, { useState, useRef, useEffect, useCallback, memo } from 'react';
-import {
-  Settings,
-  Trash2,
-  RotateCcw,
-  Minus,
-  Maximize2,
-  ChevronDown,
-  ChevronRight,
-  Pencil,
-  List,
-} from 'lucide-react';
-import { chat, loadConfig, loadConfigSync, saveConfig, type ChatMessage } from '@/lib/llmClient';
-import {
-  PROVIDER_MODELS,
-  getDefaultProviderConfig,
-  type LLMConfig,
-  type LLMProvider,
-} from '@/lib/llmModels';
+/**
+ * ChatPanel — main chat interface
+ *
+ * This is the "thin shell" that wires state to UI.
+ * Core logic lives in:
+ *   - toolDefinitions.ts    (tool defs, system prompt builder)
+ *   - ChatSubComponents.tsx  (CharacterAvatar, StageIndicator, ActionsTaken)
+ *   - SettingsModal.tsx      (LLM + image gen config UI)
+ *   - useConversationEngine.ts (conversation loop + tool dispatch)
+ */
+
+import React, { useState, useRef, useEffect, useLayoutEffect, useCallback } from 'react';
+import { Settings, Trash2, RotateCcw, Minus, Maximize2 } from 'lucide-react';
+import { loadConfig, loadConfigSync, saveConfig, type ChatMessage } from '@/lib/llmClient';
+import type { LLMConfig } from '@/lib/llmModels';
 import {
   loadImageGenConfig,
   loadImageGenConfigSync,
-  saveImageGenConfig,
-  getDefaultImageGenConfig,
   type ImageGenConfig,
-  type ImageGenProvider,
 } from '@/lib/imageGenClient';
-import {
-  getAppActionToolDefinition,
-  resolveAppAction,
-  getListAppsToolDefinition,
-  executeListApps,
-  APP_REGISTRY,
-  loadActionsFromMeta,
-} from '@/lib/appRegistry';
+// loadActionsFromMeta used by useConversationEngine
 import { seedMetaFiles } from '@/lib/seedMeta';
-import { dispatchAgentAction, onUserAction } from '@/lib/vibeContainerMock';
+import { onUserAction } from '@/lib/vibeContainerMock';
 import { closeAllWindows } from '@/lib/windowManager';
-import { getFileToolDefinitions, isFileTool, executeFileTool } from '@/lib/fileTools';
 import { setSessionPath } from '@/lib/sessionPath';
-import {
-  getMemoryToolDefinitions,
-  isMemoryTool,
-  executeMemoryTool,
-  loadMemories,
-  buildMemoryPrompt,
-  type MemoryEntry,
-} from '@/lib/memoryManager';
-import { logger } from '@/lib/logger';
-import {
-  getImageGenToolDefinitions,
-  isImageGenTool,
-  executeImageGenTool,
-} from '@/lib/imageGenTools';
+import { loadMemories, type MemoryEntry } from '@/lib/memoryManager';
 import {
   loadChatHistory,
   loadChatHistorySync,
@@ -61,28 +33,35 @@ import {
   type DisplayMessage,
 } from '@/lib/chatHistoryStorage';
 import {
-  type CharacterConfig,
   type CharacterCollection,
   DEFAULT_COLLECTION as DEFAULT_CHAR_COLLECTION,
   loadCharacterCollection,
   loadCharacterCollectionSync,
   saveCharacterCollection,
   getActiveCharacter,
-  getCharacterPromptContext,
-  resolveEmotionMedia,
-  clearEmotionVideoCache,
 } from '@/lib/characterManager';
 import {
-  ModManager,
   type ModCollection,
   DEFAULT_MOD_COLLECTION,
   loadModCollection,
   loadModCollectionSync,
   saveModCollection,
   getActiveModEntry,
+  ModManager,
 } from '@/lib/modManager';
+import { APP_REGISTRY } from '@/lib/appRegistry';
+import { logger } from '@/lib/logger';
 import CharacterPanel from './CharacterPanel';
 import ModPanel from './ModPanel';
+import { hasUsableLLMConfig } from './toolDefinitions';
+import {
+  CharacterAvatar,
+  StageIndicator,
+  ActionsTaken,
+  renderMessageContent,
+} from './ChatSubComponents';
+import SettingsModal from './SettingsModal';
+import { useConversationEngine, type ConversationDisplayMessage } from './useConversationEngine';
 import styles from './index.module.scss';
 
 // ---------------------------------------------------------------------------
@@ -92,293 +71,16 @@ import styles from './index.module.scss';
 interface CharacterDisplayMessage extends DisplayMessage {
   emotion?: string;
   suggestedReplies?: string[];
-  toolCalls?: string[]; // collapsed tool call summaries
-}
-
-function hasUsableLLMConfig(config: LLMConfig | null | undefined): config is LLMConfig {
-  return !!config?.baseUrl.trim() && !!config.model.trim();
-}
-
-// ---------------------------------------------------------------------------
-// Tool definitions for character system
-// ---------------------------------------------------------------------------
-
-function getRespondToUserToolDef() {
-  return {
-    type: 'function' as const,
-    function: {
-      name: 'respond_to_user',
-      description:
-        'Send a message to the user as the character. ALWAYS use this tool to respond — never output plain text.',
-      parameters: {
-        type: 'object' as const,
-        properties: {
-          character_expression: {
-            type: 'object',
-            properties: {
-              content: {
-                type: 'string',
-                description:
-                  'The message text (dialogue with optional action descriptions in parentheses)',
-              },
-              emotion: {
-                type: 'string',
-                description: 'Character emotion: happy, shy, peaceful, depressing, angry',
-              },
-            },
-            required: ['content'],
-          },
-          user_interaction: {
-            type: 'object',
-            properties: {
-              suggested_replies: {
-                type: 'array',
-                items: { type: 'string' },
-                description: 'List of 3 suggested user replies (under 25 chars each)',
-              },
-            },
-          },
-        },
-        required: ['character_expression'],
-      },
-    },
-  };
-}
-
-function getFinishTargetToolDef() {
-  return {
-    type: 'function' as const,
-    function: {
-      name: 'finish_target',
-      description:
-        'Mark story targets as completed when achieved through conversation. Do not announce this to the user.',
-      parameters: {
-        type: 'object' as const,
-        properties: {
-          target_ids: {
-            type: 'array',
-            items: { type: 'number' },
-            description: 'IDs of targets to mark as completed',
-          },
-        },
-        required: ['target_ids'],
-      },
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Build system prompt with Character + Mod context
-// ---------------------------------------------------------------------------
-
-function buildSystemPrompt(
-  character: CharacterConfig,
-  modManager: ModManager | null,
-  hasImageGen: boolean,
-  memories: MemoryEntry[] = [],
-): string {
-  let prompt = getCharacterPromptContext(character);
-
-  if (modManager) {
-    prompt += '\n' + modManager.buildStageReminder();
-  }
-
-  prompt += `
-You can interact with apps on the user's device using tools.
-
-When the user wants to interact with an app, first identify the target app from the user's intent, then follow ALL steps in order:
-1. list_apps — discover available apps
-2. file_read("apps/{appName}/meta.yaml") — learn the target app's available actions
-3. file_read("apps/{appName}/guide.md") — learn its data structure and JSON schema
-4. file_list/file_read — explore existing data in "apps/{appName}/data/"
-5. file_write/file_delete — create/modify/delete data following the JSON schema from step 3
-6. app_action — notify the app to reload (ONLY use actions defined in meta.yaml)
-
-Rules:
-- Always operate on the app the user specified. Do not redirect the operation to a different app or OS action.
-- Data mutations MUST go through file_write/file_delete. app_action only notifies the app to reload, it cannot write data.
-- After file_write, ALWAYS call app_action with the corresponding REFRESH action.
-- Do NOT skip step 5. If the user asked to save/create/add something, you must file_write the data. file_list alone does not save anything.
-- Do NOT skip steps 2-3. You MUST read guide.md before ANY file_write. The guide defines the ONLY valid directory structure and file schemas. Writing to paths not defined in guide.md will cause data loss — the app will not see the files.
-- NEVER invent or guess file paths. ALL file_write paths MUST exactly follow the directory structure in guide.md. For example, if guide.md defines entries under "/entries/{id}.json", you MUST write to "apps/{appName}/data/entries/{id}.json" — NOT to "apps/{appName}/data/{id}.json" or any other path.
-- NAS paths in guide.md like "/articles/xxx.json" map to "apps/{appName}/data/articles/xxx.json". This prefix rule applies to ALL paths — always preserve the full subdirectory structure from guide.md.
-
-When you receive "[User performed action in ... (appName: xxx)]", the appName is already provided. Read its meta.yaml to understand available actions, then respond accordingly. For games, respond with your own move — think strategically.
-
-IMPORTANT: You MUST use the respond_to_user tool to send all messages to the user. Do NOT output plain text responses. Include your emotion and 3 suggested replies.${hasImageGen ? '\n\nYou can use generate_image to create images from text prompts. The generated image will be displayed in chat.' : ''}`;
-
-  prompt += buildMemoryPrompt(memories);
-
-  return prompt;
+  toolCalls?: string[];
 }
 
-// ---------------------------------------------------------------------------
-// Helper: parse action text in parentheses as emotion markers
-// ---------------------------------------------------------------------------
-
-function renderMessageContent(content: string): React.ReactNode {
-  // Match (action text) patterns and render them as styled spans
-  const parts = content.split(/(\([^)]+\))/g);
-  return parts.map((part, i) => {
-    if (/^\([^)]+\)$/.test(part)) {
-      return (
-        <span key={i} className={styles.emotion}>
-          {part}
-        </span>
-      );
-    }
-    return part;
-  });
+interface PendingSaveSnapshot {
+  path: string;
+  messages: CharacterDisplayMessage[];
+  history: ChatMessage[];
+  replies: string[];
 }
 
-// ---------------------------------------------------------------------------
-// Stage Indicator Component
-// ---------------------------------------------------------------------------
-
-const StageIndicator: React.FC<{ modManager: ModManager | null }> = ({ modManager }) => {
-  if (!modManager) return null;
-
-  const total = modManager.stageCount;
-  const current = modManager.currentStageIndex;
-  const finished = modManager.isFinished;
-
-  return (
-    <div className={styles.stageIndicator}>
-      <span className={styles.stageText}>
-        Stage {finished ? total : current + 1}/{total}
-      </span>
-      <div className={styles.stageDots}>
-        {Array.from({ length: total }, (_, i) => (
-          <div
-            key={i}
-            className={`${styles.stageDot} ${
-              i < current || finished
-                ? styles.stageDotCompleted
-                : i === current
-                  ? styles.stageDotCurrent
-                  : ''
-            }`}
-          />
-        ))}
-      </div>
-    </div>
-  );
-};
-
-// ---------------------------------------------------------------------------
-// Actions Taken (collapsible)
-// ---------------------------------------------------------------------------
-
-const ActionsTaken: React.FC<{ calls: string[] }> = ({ calls }) => {
-  const [open, setOpen] = useState(false);
-  if (calls.length === 0) return null;
-
-  return (
-    <div className={styles.actionsTaken}>
-      <button className={styles.actionsTakenToggle} onClick={() => setOpen(!open)}>
-        Actions taken
-        {open ? <ChevronDown size={12} /> : <ChevronRight size={12} />}
-      </button>
-      {open && (
-        <div className={styles.actionsTakenList}>
-          {calls.map((c, i) => (
-            <div key={i}>{c}</div>
-          ))}
-        </div>
-      )}
-    </div>
-  );
-};
-
-// ---------------------------------------------------------------------------
-// CharacterAvatar – crossfade between emotion media without flashing
-// ---------------------------------------------------------------------------
-
-interface AvatarLayer {
-  url: string;
-  type: 'video' | 'image';
-  active: boolean;
-}
-
-const CharacterAvatar: React.FC<{
-  character: CharacterConfig;
-  emotion?: string;
-  onEmotionEnd: () => void;
-}> = memo(({ character, emotion, onEmotionEnd }) => {
-  const isIdle = !emotion;
-  const media = resolveEmotionMedia(character, emotion || 'default');
-
-  const [layers, setLayers] = useState<AvatarLayer[]>(() =>
-    media ? [{ url: media.url, type: media.type, active: true }] : [],
-  );
-  const activeUrl = layers.find((l) => l.active)?.url;
-
-  useEffect(() => {
-    if (!media) {
-      setLayers([]);
-      return;
-    }
-    if (media.url === activeUrl) return;
-    setLayers((prev) => {
-      if (prev.some((l) => l.url === media.url)) return prev;
-      return [...prev, { url: media.url, type: media.type, active: false }];
-    });
-  }, [media?.url, activeUrl]);
-
-  const handleMediaReady = useCallback((readyUrl: string) => {
-    setLayers((prev) => {
-      const staleUrls = prev.filter((l) => l.url !== readyUrl).map((l) => l.url);
-      setTimeout(() => {
-        setLayers((curr) => curr.filter((l) => !staleUrls.includes(l.url)));
-      }, 300);
-      return prev.map((l) => ({ ...l, active: l.url === readyUrl }));
-    });
-  }, []);
-
-  if (layers.length === 0) {
-    return <div className={styles.avatarPlaceholder}>{character.character_name.charAt(0)}</div>;
-  }
-
-  return (
-    <>
-      {layers.map((layer) => {
-        const layerStyle: React.CSSProperties = {
-          position: 'absolute',
-          inset: 0,
-          opacity: layer.active ? 1 : 0,
-          transition: 'opacity 0.25s ease-out',
-        };
-        if (layer.type === 'video') {
-          return (
-            <video
-              key={layer.url}
-              className={styles.avatarImage}
-              style={layerStyle}
-              src={layer.url}
-              autoPlay
-              loop={layer.active ? isIdle : false}
-              muted
-              playsInline
-              onCanPlay={!layer.active ? () => handleMediaReady(layer.url) : undefined}
-              onEnded={layer.active && !isIdle ? onEmotionEnd : undefined}
-            />
-          );
-        }
-        return (
-          <img
-            key={layer.url}
-            className={styles.avatarImage}
-            style={layerStyle}
-            src={layer.url}
-            alt={character.character_name}
-            onLoad={!layer.active ? () => handleMediaReady(layer.url) : undefined}
-          />
-        );
-      })}
-    </>
-  );
-});
-
 // ---------------------------------------------------------------------------
 // ChatPanel
 // ---------------------------------------------------------------------------
@@ -389,7 +91,7 @@ const ChatPanel: React.FC<{
   zIndex?: number;
   onFocus?: () => void;
 }> = ({ onClose, visible = true, zIndex, onFocus }) => {
-  // Character + Mod state (collection-based)
+  // Character + Mod state
   const [charCollection, setCharCollection] = useState<CharacterCollection>(
     () => loadCharacterCollectionSync() ?? DEFAULT_CHAR_COLLECTION,
   );
@@ -404,11 +106,17 @@ const ChatPanel: React.FC<{
     return new ModManager(entry.config, entry.state);
   });
 
-  // Session key for chat history isolation (character × mod)
+  // Session key for chat history isolation (derived, not state)
   const sessionPath = buildSessionPath(charCollection.activeId, modCollection.activeId);
-  setSessionPath(sessionPath);
 
-  // Chat state — initialized from session-scoped cache
+  // Keep the module-level session path in sync synchronously after DOM
+  // mutations so tool execution always reads the latest path, even within the
+  // same paint cycle as a character/mod switch.
+  useLayoutEffect(() => {
+    setSessionPath(sessionPath);
+  }, [sessionPath]);
+
+  // Chat state
   const [messages, setMessages] = useState<CharacterDisplayMessage[]>(() => {
     const cache = loadChatHistorySync(sessionPath);
     return (cache?.messages ?? []) as CharacterDisplayMessage[];
@@ -424,33 +132,14 @@ const ChatPanel: React.FC<{
   const [imageGenConfig, setImageGenConfig] = useState<ImageGenConfig | null>(
     loadImageGenConfigSync,
   );
-
-  // Suggested replies from latest assistant message
   const [suggestedReplies, setSuggestedReplies] = useState<string[]>([]);
   const [showCharacterPanel, setShowCharacterPanel] = useState(false);
   const [showModPanel, setShowModPanel] = useState(false);
   const [initialEditModId, setInitialEditModId] = useState<string | undefined>();
   const [currentEmotion, setCurrentEmotion] = useState<string | undefined>();
-
-  // Open mod editor when triggered from Shell (e.g. after card import mod generation)
-  useEffect(() => {
-    const handler = (e: Event) => {
-      const modId = (e as CustomEvent<{ modId: string }>).detail?.modId;
-      if (modId) {
-        setInitialEditModId(modId);
-        setShowModPanel(true);
-      }
-    };
-    window.addEventListener('open-mod-editor', handler);
-    return () => window.removeEventListener('open-mod-editor', handler);
-  }, []);
-
-  // Memories loaded for SP injection
   const [memories, setMemories] = useState<MemoryEntry[]>([]);
 
-  // Pending tool calls for current response (grouped per assistant turn)
-  const pendingToolCallsRef = useRef<string[]>([]);
-
+  // Refs for stable access in callbacks
   const messagesEndRef = useRef<HTMLDivElement>(null);
   const messagesRef = useRef(messages);
   messagesRef.current = messages;
@@ -459,28 +148,93 @@ const ChatPanel: React.FC<{
   const suggestedRepliesRef = useRef(suggestedReplies);
   suggestedRepliesRef.current = suggestedReplies;
 
-  // Debounced save
-  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
+  const configRef = useRef(config);
+  configRef.current = config;
+  const imageGenConfigRef = useRef(imageGenConfig);
+  imageGenConfigRef.current = imageGenConfig;
+  const modManagerRef = useRef(modManager);
+  modManagerRef.current = modManager;
+  const characterRef = useRef(character);
+  characterRef.current = character;
+  const memoriesRef = useRef(memories);
+  memoriesRef.current = memories;
   const sessionPathRef = useRef(sessionPath);
   sessionPathRef.current = sessionPath;
 
+  // Conversation engine
+  const { runConversation, abortRef } = useConversationEngine({
+    imageGenConfigRef,
+    modManagerRef,
+    characterRef,
+    memoriesRef,
+    sessionPathRef,
+    callbacks: {
+      addMessage: useCallback((msg: ConversationDisplayMessage) => {
+        setMessages((prev) => [...prev, msg]);
+      }, []),
+      setChatHistory,
+      setSuggestedReplies,
+      setCurrentEmotion,
+      setModCollection,
+      setModManager,
+      setMemories,
+    },
+  });
+
+  // Debounced save — tracks the most recent snapshot to be persisted.
+  const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const pendingSaveRef = useRef<PendingSaveSnapshot | null>(null);
+
+  // Reschedule the debounce timer on every data change.  Never flush
+  // synchronously here — flushing is handled by the session-switch effect below
+  // so that rapid updates (e.g. streaming tokens) are genuinely batched.
   useEffect(() => {
-    if (messages.length === 0 && chatHistory.length === 0) return;
+    if (messages.length === 0 && chatHistory.length === 0) {
+      pendingSaveRef.current = null;
+      return;
+    }
+    pendingSaveRef.current = {
+      path: sessionPath,
+      messages,
+      history: chatHistory,
+      replies: suggestedReplies,
+    };
     if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
     saveTimerRef.current = setTimeout(() => {
-      saveChatHistory(
-        sessionPathRef.current,
-        messagesRef.current,
-        chatHistoryRef.current,
-        suggestedRepliesRef.current,
-      );
+      if (pendingSaveRef.current) {
+        const { path, messages: m, history: h, replies: r } = pendingSaveRef.current;
+        saveChatHistory(path, m, h, r);
+        pendingSaveRef.current = null;
+      }
+      saveTimerRef.current = null;
     }, 500);
     return () => {
-      if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
+      // Cancel the timer so the next render's effect can reschedule it.
+      // Do NOT flush here — that would fire a POST on every state update,
+      // defeating the debounce.
+      if (saveTimerRef.current) {
+        clearTimeout(saveTimerRef.current);
+        saveTimerRef.current = null;
+      }
     };
   }, [messages, chatHistory, suggestedReplies]);
 
+  // Flush any pending save when the session path changes (character/mod switch)
+  // or when the component unmounts, so no data is silently lost.
+  useEffect(() => {
+    return () => {
+      if (saveTimerRef.current) {
+        clearTimeout(saveTimerRef.current);
+        saveTimerRef.current = null;
+      }
+      if (pendingSaveRef.current) {
+        const { path, messages: m, history: h, replies: r } = pendingSaveRef.current;
+        saveChatHistory(path, m, h, r);
+        pendingSaveRef.current = null;
+      }
+    };
+  }, [sessionPath]);
+
   /** Seed prologue and opening replies from active mod */
   const seedPrologue = useCallback(() => {
     const entry = getActiveModEntry(modCollection);
@@ -502,18 +256,19 @@ const ChatPanel: React.FC<{
     setCurrentEmotion(undefined);
   }, [modCollection]);
 
-  // Reload chat history when session (character × mod) changes
+  // Reload chat history when session changes
   useEffect(() => {
-    loadChatHistory(sessionPath).then((data) => {
+    let cancelled = false;
+    const load = async () => {
+      const data = await loadChatHistory(sessionPath);
+      if (cancelled) return;
       const loadedMessages = (data?.messages ?? []) as CharacterDisplayMessage[];
       const loadedHistory = data?.chatHistory ?? [];
       if (loadedMessages.length === 0 && loadedHistory.length === 0) {
-        // No history — seed prologue
         seedPrologue();
       } else {
         setMessages(loadedMessages);
         setChatHistory(loadedHistory);
-        // Restore suggested replies from saved data, or from mod config if only prologue
         if (data?.suggestedReplies?.length) {
           setSuggestedReplies(data.suggestedReplies);
         } else {
@@ -530,15 +285,25 @@ const ChatPanel: React.FC<{
         }
         setCurrentEmotion(undefined);
       }
-    });
-    // Load memories for SP injection
-    loadMemories(sessionPath).then(setMemories);
-  }, [sessionPath, modCollection, seedPrologue]);
+      if (cancelled) return;
+      loadMemories(sessionPath)
+        .then((mems) => {
+          if (!cancelled) setMemories(mems);
+        })
+        .catch(() => {
+          if (!cancelled) setMemories([]);
+        });
+    };
+    load();
+    return () => {
+      cancelled = true;
+    };
+    // sessionPath is derived from charCollection.activeId + modCollection.activeId,
+    // so it already captures session changes. seedPrologue reads modCollection via
+    // closure but we only want to trigger on session identity change.
+  }, [sessionPath]);
 
-  // Load configs from file (async override).
-  // Empty deps [] is intentional: configs (character collection, mod collection,
-  // chat config, image-gen config) are loaded inside the effect and written to
-  // state — they are not external dependencies that should trigger re-runs.
+  // Load configs from file (async override)
   useEffect(() => {
     loadConfig().then((fileConfig) => {
       if (fileConfig) setConfig(fileConfig);
@@ -558,7 +323,7 @@ const ChatPanel: React.FC<{
     });
   }, []);
 
-  // Listen for mod collection changes from Shell (e.g. after mod generation)
+  // Listen for mod collection changes from Shell
   useEffect(() => {
     const handler = (e: Event) => {
       const col = (e as CustomEvent<ModCollection>).detail;
@@ -572,32 +337,39 @@ const ChatPanel: React.FC<{
     return () => window.removeEventListener('mod-collection-changed', handler);
   }, []);
 
+  // Open mod editor when triggered from Shell
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const modId = (e as CustomEvent<{ modId: string }>).detail?.modId;
+      if (modId) {
+        setInitialEditModId(modId);
+        setShowModPanel(true);
+      }
+    };
+    window.addEventListener('open-mod-editor', handler);
+    return () => window.removeEventListener('open-mod-editor', handler);
+  }, []);
+
   const handleClearHistory = useCallback(async () => {
     await clearChatHistory(sessionPathRef.current);
     seedPrologue();
   }, [seedPrologue]);
 
-  /** Reset entire session — clears chat, memories, app data, and mod state */
   const handleResetSession = useCallback(async () => {
     const sp = sessionPathRef.current;
-    // Clear server-side session directory
     try {
       await fetch(`/api/session-reset?path=${encodeURIComponent(sp)}`, { method: 'DELETE' });
     } catch {
       // ignore
     }
-    // Clear local state
     localStorage.removeItem(`openroom_chat_${sp.replace(/\//g, '_')}`);
     setMessages([]);
     setChatHistory([]);
     setSuggestedReplies([]);
     setMemories([]);
     setCurrentEmotion(undefined);
-
-    // Close all open app windows
     closeAllWindows();
 
-    // Reset mod state
     if (modManagerRef.current) {
       modManagerRef.current.reset();
       const mm = modManagerRef.current;
@@ -616,12 +388,9 @@ const ChatPanel: React.FC<{
       });
     }
 
-    // Re-seed prologue and opening replies
     seedPrologue();
-
-    // Re-seed meta files
     await seedMetaFiles();
-  }, [modCollection, seedPrologue]);
+  }, [seedPrologue]);
 
   useEffect(() => {
     messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
@@ -631,17 +400,6 @@ const ChatPanel: React.FC<{
     setMessages((prev) => [...prev, msg]);
   }, []);
 
-  const configRef = useRef(config);
-  configRef.current = config;
-  const imageGenConfigRef = useRef(imageGenConfig);
-  imageGenConfigRef.current = imageGenConfig;
-  const modManagerRef = useRef(modManager);
-  modManagerRef.current = modManager;
-  const characterRef = useRef(character);
-  characterRef.current = character;
-  const memoriesRef = useRef(memories);
-  memoriesRef.current = memories;
-
   // User action queue
   const actionQueueRef = useRef<string[]>([]);
   const processingRef = useRef(false);
@@ -661,16 +419,25 @@ const ChatPanel: React.FC<{
       ];
       setChatHistory(newHistory);
       setLoading(true);
+
+      // Cancel any previous conversation
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
       try {
-        await runConversation(newHistory, cfg);
+        await runConversation(newHistory, cfg, controller.signal);
       } catch (err) {
-        logger.error('ChatPanel', 'User action error:', err);
+        if ((err as Error).name !== 'AbortError') {
+          logger.error('ChatPanel', 'User action error:', err);
+        }
       } finally {
+        if (abortRef.current === controller) abortRef.current = null;
         setLoading(false);
       }
     }
     processingRef.current = false;
-  }, []);
+  }, [runConversation, abortRef]);
 
   // Listen for user actions from apps
   useEffect(() => {
@@ -723,311 +490,38 @@ const ChatPanel: React.FC<{
       };
       addMessage(userDisplay);
 
-      const newHistory: ChatMessage[] = [...chatHistory, { role: 'user', content: text }];
+      // Use chatHistoryRef to avoid stale closure over chatHistory state
+      const newHistory: ChatMessage[] = [
+        ...chatHistoryRef.current,
+        { role: 'user', content: text },
+      ];
       setChatHistory(newHistory);
 
       setLoading(true);
-      try {
-        await runConversation(newHistory, config);
-      } catch (err) {
-        logger.error('ChatPanel', 'Error:', err);
-        addMessage({
-          id: String(Date.now()),
-          role: 'assistant',
-          content: `Error: ${err instanceof Error ? err.message : String(err)}`,
-        });
-      } finally {
-        setLoading(false);
-      }
-    },
-    [input, loading, config, chatHistory, addMessage],
-  );
-
-  // Core conversation loop
-  const runConversation = async (history: ChatMessage[], cfg: LLMConfig) => {
-    await seedMetaFiles();
-    await loadActionsFromMeta();
-    const hasImageGen = !!imageGenConfigRef.current?.apiKey;
-    const mm = modManagerRef.current;
-    const char = characterRef.current;
-
-    const tools = [
-      getRespondToUserToolDef(),
-      getFinishTargetToolDef(),
-      getListAppsToolDefinition(),
-      getAppActionToolDefinition(),
-      ...getFileToolDefinitions(),
-      ...getMemoryToolDefinitions(),
-      ...(hasImageGen ? getImageGenToolDefinitions() : []),
-    ];
-
-    const currentMemories = memoriesRef.current;
-    const fullMessages: ChatMessage[] = [
-      { role: 'system', content: buildSystemPrompt(char, mm, hasImageGen, currentMemories) },
-      ...history,
-    ];
-
-    let currentMessages = fullMessages;
-    let iterations = 0;
-    const maxIterations = 10;
-    pendingToolCallsRef.current = [];
-
-    while (iterations < maxIterations) {
-      iterations++;
-      const response = await chat(currentMessages, tools, cfg);
-
-      if (response.toolCalls.length === 0) {
-        // No tool calls — fallback plain text (shouldn't happen with respond_to_user requirement)
-        if (response.content) {
-          addMessage({
-            id: String(Date.now()),
-            role: 'assistant',
-            content: response.content,
-            toolCalls:
-              pendingToolCallsRef.current.length > 0 ? [...pendingToolCallsRef.current] : undefined,
-          });
-          setChatHistory((prev) => [...prev, { role: 'assistant', content: response.content }]);
-          pendingToolCallsRef.current = [];
-        }
-        break;
-      }
 
-      // Has tool calls
-      const assistantMsg: ChatMessage = {
-        role: 'assistant',
-        content: response.content,
-        tool_calls: response.toolCalls,
-      };
-      currentMessages = [...currentMessages, assistantMsg];
-
-      // Execute each tool call
-      for (const tc of response.toolCalls) {
-        let params: Record<string, unknown> = {};
-        try {
-          params = JSON.parse(tc.function.arguments);
-        } catch {
-          // ignore
-        }
-
-        // ---- respond_to_user ----
-        if (tc.function.name === 'respond_to_user') {
-          const expr =
-            (params.character_expression as { content?: string; emotion?: string }) ?? {};
-          const interaction = (params.user_interaction as { suggested_replies?: string[] }) ?? {};
-
-          const content = expr.content ?? '';
-          const emotion = expr.emotion;
-          const replies = interaction.suggested_replies ?? [];
+      // Cancel any previous conversation
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
 
+      try {
+        await runConversation(newHistory, config, controller.signal);
+      } catch (err) {
+        if ((err as Error).name !== 'AbortError') {
+          logger.error('ChatPanel', 'Error:', err);
           addMessage({
             id: String(Date.now()),
             role: 'assistant',
-            content,
-            emotion,
-            suggestedReplies: replies,
-            toolCalls:
-              pendingToolCallsRef.current.length > 0 ? [...pendingToolCallsRef.current] : undefined,
+            content: `Error: ${err instanceof Error ? err.message : String(err)}`,
           });
-          setSuggestedReplies(replies);
-          if (emotion) {
-            clearEmotionVideoCache(character.id);
-            setCurrentEmotion(emotion);
-          }
-          pendingToolCallsRef.current = [];
-
-          setChatHistory((prev) => [...prev, { role: 'assistant', content }]);
-          currentMessages = [
-            ...currentMessages,
-            { role: 'tool', content: 'Message delivered.', tool_call_id: tc.id },
-          ];
-          continue;
         }
-
-        // ---- finish_target ----
-        if (tc.function.name === 'finish_target') {
-          const targetIds = (params.target_ids as number[]) ?? [];
-          if (mm) {
-            const result = mm.finishTarget(targetIds);
-            // Persist state via collection
-            const updatedEntry = { config: mm.getConfig(), state: mm.getState() };
-            setModCollection((prev) => {
-              const updated = {
-                ...prev,
-                items: { ...prev.items, [updatedEntry.config.id]: updatedEntry },
-              };
-              saveModCollection(updated);
-              return updated;
-            });
-            setModManager(new ModManager(mm.getConfig(), mm.getState()));
-
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: JSON.stringify(result), tool_call_id: tc.id },
-            ];
-          } else {
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: 'No mod loaded.', tool_call_id: tc.id },
-            ];
-          }
-          continue;
-        }
-
-        // ---- list_apps ----
-        if (tc.function.name === 'list_apps') {
-          const result = executeListApps();
-          pendingToolCallsRef.current.push(`list_apps`);
-          currentMessages = [
-            ...currentMessages,
-            { role: 'tool', content: result, tool_call_id: tc.id },
-          ];
-          continue;
-        }
-
-        // ---- File tools ----
-        if (isFileTool(tc.function.name)) {
-          pendingToolCallsRef.current.push(
-            `${tc.function.name}(${JSON.stringify(params).slice(0, 60)})`,
-          );
-          try {
-            const result = await executeFileTool(
-              tc.function.name,
-              params as Record<string, string>,
-            );
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // ---- Image gen ----
-        if (isImageGenTool(tc.function.name)) {
-          pendingToolCallsRef.current.push('generate_image');
-          try {
-            const { result, dataUrl } = await executeImageGenTool(
-              params as Record<string, string>,
-              imageGenConfigRef.current,
-            );
-            if (dataUrl) {
-              addMessage({
-                id: String(Date.now()) + '-img',
-                role: 'assistant',
-                content: '',
-                imageUrl: dataUrl,
-              });
-            }
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // ---- Memory tools ----
-        if (isMemoryTool(tc.function.name)) {
-          pendingToolCallsRef.current.push(`save_memory`);
-          try {
-            const result = await executeMemoryTool(
-              sessionPathRef.current,
-              params as Record<string, string>,
-            );
-            // Refresh memories for next turn's SP
-            loadMemories(sessionPathRef.current).then(setMemories);
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // ---- app_action ----
-        if (tc.function.name === 'app_action') {
-          const strParams = params as Record<string, string>;
-          const resolved = resolveAppAction(strParams.app_name, strParams.action_type);
-          if (typeof resolved === 'string') {
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: resolved, tool_call_id: tc.id },
-            ];
-            continue;
-          }
-
-          pendingToolCallsRef.current.push(`${strParams.app_name}/${strParams.action_type}`);
-
-          let actionParams: Record<string, string> = {};
-          if (strParams.params) {
-            try {
-              actionParams = JSON.parse(strParams.params);
-            } catch {
-              // empty
-            }
-          }
-
-          try {
-            const result = await dispatchAgentAction({
-              app_id: resolved.appId,
-              action_type: resolved.actionType,
-              params: actionParams,
-            });
-            currentMessages = [
-              ...currentMessages,
-              { role: 'tool', content: result, tool_call_id: tc.id },
-            ];
-          } catch (err) {
-            currentMessages = [
-              ...currentMessages,
-              {
-                role: 'tool',
-                content: `error: ${err instanceof Error ? err.message : String(err)}`,
-                tool_call_id: tc.id,
-              },
-            ];
-          }
-          continue;
-        }
-
-        // Unknown tool
-        currentMessages = [
-          ...currentMessages,
-          { role: 'tool', content: 'error: unknown tool', tool_call_id: tc.id },
-        ];
+      } finally {
+        if (abortRef.current === controller) abortRef.current = null;
+        setLoading(false);
       }
-
-      // Update chat history
-      setChatHistory(currentMessages.slice(1));
-    }
-  };
+    },
+    [input, loading, config, addMessage, runConversation, abortRef],
+  );
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === 'Enter' && !e.shiftKey) {
@@ -1064,7 +558,6 @@ const ChatPanel: React.FC<{
               style={{ cursor: 'pointer' }}
             >
               <span className={styles.characterName}>{character.character_name}</span>
-              <ChevronRight size={14} style={{ color: 'rgba(255,255,255,0.4)' }} />
             </div>
             <div className={styles.headerActions}>
               <div onClick={() => setShowModPanel(true)} style={{ cursor: 'pointer' }}>
@@ -1175,12 +668,39 @@ const ChatPanel: React.FC<{
         <SettingsModal
           config={config}
           imageGenConfig={imageGenConfig}
-          onSave={(c, igc) => {
-            setConfig(c);
-            setImageGenConfig(igc);
-            saveConfig(c, igc);
-            if (igc) saveImageGenConfig(igc);
-            setShowSettings(false);
+          onSave={async (c, igc) => {
+            const saveResult = await saveConfig(c, igc);
+            if (saveResult && saveResult.ok === false) {
+              return saveResult;
+            }
+
+            const [nextConfig, nextImageGenConfig] = await Promise.all([
+              loadConfig(),
+              loadImageGenConfig(),
+            ]);
+
+            // Keep the previous in-memory state on reload failure so we do not
+            // store partial update objects or freshly typed raw API keys in state.
+            setConfig(nextConfig ?? config);
+            setImageGenConfig(nextImageGenConfig ?? imageGenConfig);
+
+            const imageGenReloadSucceeded = igc === null ? true : nextImageGenConfig !== null;
+            if (nextConfig !== null && imageGenReloadSucceeded) {
+              setShowSettings(false);
+            }
+
+            if (nextConfig === null || !imageGenReloadSucceeded) {
+              const reloadFailures = [
+                ...(nextConfig === null ? ['chat settings'] : []),
+                ...(!imageGenReloadSucceeded ? ['image generation settings'] : []),
+              ];
+              return {
+                ok: false,
+                error: `Settings were saved, but reloading ${reloadFailures.join(' and ')} failed. Please reopen settings to verify.`,
+              };
+            }
+
+            return { ok: true };
           }}
           onClose={() => setShowSettings(false)}
         />
@@ -1220,253 +740,4 @@ const ChatPanel: React.FC<{
   );
 };
 
-// ---------------------------------------------------------------------------
-// Settings Modal (extended with Character + Mod)
-// ---------------------------------------------------------------------------
-
-const SettingsModal: React.FC<{
-  config: LLMConfig | null;
-  imageGenConfig: ImageGenConfig | null;
-  onSave: (_config: LLMConfig, _igConfig: ImageGenConfig | null) => void;
-  onClose: () => void;
-}> = ({ config, imageGenConfig, onSave, onClose }) => {
-  // LLM settings
-  const [provider, setProvider] = useState<LLMProvider>(config?.provider || 'minimax');
-  const [apiKey, setApiKey] = useState(config?.apiKey || '');
-  const [baseUrl, setBaseUrl] = useState(
-    config?.baseUrl || getDefaultProviderConfig('minimax').baseUrl,
-  );
-  const [model, setModel] = useState(config?.model || getDefaultProviderConfig('minimax').model);
-  const [customHeaders, setCustomHeaders] = useState(config?.customHeaders || '');
-  const [manualModelMode, setManualModelMode] = useState(false);
-
-  const isPresetModel = PROVIDER_MODELS[provider]?.includes(model) ?? false;
-  const showDropdown = !manualModelMode && isPresetModel;
-
-  // Image gen settings
-  const [igProvider, setIgProvider] = useState<ImageGenProvider>(
-    imageGenConfig?.provider || 'gemini',
-  );
-  const [igApiKey, setIgApiKey] = useState(imageGenConfig?.apiKey || '');
-  const [igBaseUrl, setIgBaseUrl] = useState(
-    imageGenConfig?.baseUrl || getDefaultImageGenConfig('gemini').baseUrl,
-  );
-  const [igModel, setIgModel] = useState(
-    imageGenConfig?.model || getDefaultImageGenConfig('gemini').model,
-  );
-  const [igCustomHeaders, setIgCustomHeaders] = useState(imageGenConfig?.customHeaders || '');
-
-  const handleProviderChange = (p: LLMProvider) => {
-    setProvider(p);
-    const defaults = getDefaultProviderConfig(p);
-    setBaseUrl(defaults.baseUrl);
-    setModel(defaults.model);
-    setManualModelMode(false);
-  };
-
-  const handleModelChange = (newModel: string) => {
-    setModel(newModel);
-    setManualModelMode(false);
-  };
-
-  const handleIgProviderChange = (p: ImageGenProvider) => {
-    setIgProvider(p);
-    const defaults = getDefaultImageGenConfig(p);
-    setIgBaseUrl(defaults.baseUrl);
-    setIgModel(defaults.model);
-  };
-
-  return (
-    <div className={styles.overlay} data-testid="settings-overlay">
-      <div className={styles.settingsModal} data-testid="settings-modal">
-        <div className={styles.settingsTitle}>LLM Settings</div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Provider</label>
-          <select
-            className={styles.select}
-            value={provider}
-            onChange={(e) => handleProviderChange(e.target.value as LLMProvider)}
-          >
-            <option value="openai">OpenAI</option>
-            <option value="anthropic">Anthropic</option>
-            <option value="deepseek">DeepSeek</option>
-            <option value="llama.cpp">llama.cpp</option>
-            <option value="minimax">MiniMax</option>
-            <option value="z.ai">Z.ai</option>
-            <option value="kimi">Kimi</option>
-            <option value="openrouter">OpenRouter</option>
-          </select>
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>API Key</label>
-          <input
-            className={styles.fieldInput}
-            type="password"
-            value={apiKey}
-            onChange={(e) => setApiKey(e.target.value)}
-            placeholder="Optional for local servers"
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Base URL</label>
-          <input
-            className={styles.fieldInput}
-            value={baseUrl}
-            onChange={(e) => setBaseUrl(e.target.value)}
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Model</label>
-          <div className={styles.modelSelectorWrapper}>
-            {showDropdown ? (
-              <>
-                <select
-                  className={styles.select}
-                  value={model}
-                  onChange={(e) => handleModelChange(e.target.value)}
-                >
-                  {PROVIDER_MODELS[provider]?.map((m) => (
-                    <option key={m} value={m}>
-                      {m}
-                    </option>
-                  ))}
-                </select>
-                <button
-                  type="button"
-                  onClick={() => setManualModelMode(true)}
-                  className={styles.manualToggleBtn}
-                  title="Enter custom model name"
-                >
-                  <Pencil size={14} />
-                </button>
-              </>
-            ) : (
-              <>
-                <input
-                  className={styles.fieldInput}
-                  value={model}
-                  onChange={(e) => setModel(e.target.value)}
-                  placeholder="e.g. gpt-4-turbo"
-                />
-                {isPresetModel && (
-                  <button
-                    type="button"
-                    onClick={() => setManualModelMode(false)}
-                    className={styles.manualToggleBtn}
-                    title="Back to model list"
-                  >
-                    <List size={14} />
-                  </button>
-                )}
-              </>
-            )}
-          </div>
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Custom Headers (one per line, Key: Value)</label>
-          <textarea
-            className={styles.fieldInput}
-            value={customHeaders}
-            onChange={(e) => setCustomHeaders(e.target.value)}
-            placeholder={'X-Custom-Header: value\nAnother-Header: value'}
-            rows={3}
-            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
-          />
-        </div>
-
-        <div className={styles.settingsDivider} />
-        <div className={styles.settingsTitle}>Image Generation</div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Provider</label>
-          <select
-            className={styles.select}
-            value={igProvider}
-            onChange={(e) => handleIgProviderChange(e.target.value as ImageGenProvider)}
-          >
-            <option value="openai">OpenAI</option>
-            <option value="gemini">Gemini</option>
-          </select>
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>API Key</label>
-          <input
-            className={styles.fieldInput}
-            type="password"
-            value={igApiKey}
-            onChange={(e) => setIgApiKey(e.target.value)}
-            placeholder="API Key..."
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Base URL</label>
-          <input
-            className={styles.fieldInput}
-            value={igBaseUrl}
-            onChange={(e) => setIgBaseUrl(e.target.value)}
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Model</label>
-          <input
-            className={styles.fieldInput}
-            value={igModel}
-            onChange={(e) => setIgModel(e.target.value)}
-          />
-        </div>
-
-        <div className={styles.field}>
-          <label className={styles.label}>Custom Headers</label>
-          <textarea
-            className={styles.fieldInput}
-            value={igCustomHeaders}
-            onChange={(e) => setIgCustomHeaders(e.target.value)}
-            placeholder={'X-Custom-Header: value'}
-            rows={2}
-            style={{ resize: 'vertical', fontFamily: 'monospace', fontSize: '12px' }}
-          />
-        </div>
-
-        <div className={styles.settingsActions}>
-          <button className={styles.cancelBtn} onClick={onClose}>
-            Cancel
-          </button>
-          <button
-            className={styles.saveBtn}
-            onClick={() => {
-              const llmCfg: LLMConfig = {
-                provider,
-                apiKey,
-                baseUrl,
-                model,
-                ...(customHeaders.trim() ? { customHeaders } : {}),
-              };
-              const igCfg: ImageGenConfig | null = igApiKey.trim()
-                ? {
-                    provider: igProvider,
-                    apiKey: igApiKey,
-                    baseUrl: igBaseUrl,
-                    model: igModel,
-                    ...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
-                  }
-                : null;
-              onSave(llmCfg, igCfg);
-            }}
-          >
-            Save
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-};
-
 export default ChatPanel;
diff --git a/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts b/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
new file mode 100644
index 0000000..5c3e190
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts
@@ -0,0 +1,141 @@
+/**
+ * Tool Definitions & System Prompt for ChatPanel
+ *
+ * Pure functions with no React dependency — easily testable in isolation.
+ */
+
+import type { CharacterConfig } from '@/lib/characterManager';
+import { getCharacterPromptContext } from '@/lib/characterManager';
+import type { ModManager } from '@/lib/modManager';
+import type { MemoryEntry } from '@/lib/memoryManager';
+import { buildMemoryPrompt } from '@/lib/memoryManager';
+import type { LLMConfig } from '@/lib/llmModels';
+
+// ---------------------------------------------------------------------------
+// Config guard
+// ---------------------------------------------------------------------------
+
+export function hasUsableLLMConfig(config: LLMConfig | null | undefined): config is LLMConfig {
+  const baseUrl = typeof config?.baseUrl === 'string' ? config.baseUrl.trim() : '';
+  const model = typeof config?.model === 'string' ? config.model.trim() : '';
+  // Normalize the config in-place so downstream callers get trimmed values
+  if (config) {
+    config.baseUrl = baseUrl;
+    config.model = model;
+  }
+  return !!baseUrl && !!model;
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions for character system
+// ---------------------------------------------------------------------------
+
+export function getRespondToUserToolDef() {
+  return {
+    type: 'function' as const,
+    function: {
+      name: 'respond_to_user',
+      description:
+        'Send a message to the user as the character. ALWAYS use this tool to respond — never output plain text.',
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          character_expression: {
+            type: 'object',
+            properties: {
+              content: {
+                type: 'string',
+                description:
+                  'The message text (dialogue with optional action descriptions in parentheses)',
+              },
+              emotion: {
+                type: 'string',
+                description:
+                  "Character emotion — use one of the active character's defined emotion keys",
+              },
+            },
+            required: ['content'],
+          },
+          user_interaction: {
+            type: 'object',
+            properties: {
+              suggested_replies: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of 3 suggested user replies (under 25 chars each)',
+              },
+            },
+          },
+        },
+        required: ['character_expression'],
+      },
+    },
+  };
+}
+
+export function getFinishTargetToolDef() {
+  return {
+    type: 'function' as const,
+    function: {
+      name: 'finish_target',
+      description:
+        'Mark story targets as completed when achieved through conversation. Do not announce this to the user.',
+      parameters: {
+        type: 'object' as const,
+        properties: {
+          target_ids: {
+            type: 'array',
+            items: { type: 'number' },
+            description: 'IDs of targets to mark as completed',
+          },
+        },
+        required: ['target_ids'],
+      },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// System prompt builder
+// ---------------------------------------------------------------------------
+
+export function buildSystemPrompt(
+  character: CharacterConfig,
+  modManager: ModManager | null,
+  hasImageGen: boolean,
+  memories: MemoryEntry[] = [],
+): string {
+  let prompt = getCharacterPromptContext(character);
+
+  if (modManager) {
+    prompt += '\n' + modManager.buildStageReminder();
+  }
+
+  prompt += `
+You can interact with apps on the user's device using tools.
+
+When the user wants to interact with an app, first identify the target app from the user's intent, then follow ALL steps in order:
+1. list_apps — discover available apps
+2. file_read("apps/{appName}/meta.yaml") — learn the target app's available actions
+3. file_read("apps/{appName}/guide.md") — learn its data structure and JSON schema
+4. file_list/file_read — explore existing data in "apps/{appName}/data/"
+5. file_write/file_delete — create/modify/delete data following the JSON schema from step 3
+6. app_action — notify the app to reload (ONLY use actions defined in meta.yaml)
+
+Rules:
+- Always operate on the app the user specified. Do not redirect the operation to a different app or OS action.
+- Data mutations MUST go through file_write/file_delete. app_action only notifies the app to reload, it cannot write data.
+- After file_write, ALWAYS call app_action with the corresponding REFRESH action.
+- Do NOT skip step 5. If the user asked to save/create/add something, you must file_write the data. file_list alone does not save anything.
+- Do NOT skip steps 2-3. You MUST read guide.md before ANY file_write. The guide defines the ONLY valid directory structure and file schemas. Writing to paths not defined in guide.md will cause data loss — the app will not see the files.
+- NEVER invent or guess file paths. ALL file_write paths MUST exactly follow the directory structure in guide.md. For example, if guide.md defines entries under "/entries/{id}.json", you MUST write to "apps/{appName}/data/entries/{id}.json" — NOT to "apps/{appName}/data/{id}.json" or any other path.
+- NAS paths in guide.md like "/articles/xxx.json" map to "apps/{appName}/data/articles/xxx.json". This prefix rule applies to ALL paths — always preserve the full subdirectory structure from guide.md.
+
+When you receive "[User performed action in ... (appName: xxx)]", the appName is already provided. Read its meta.yaml to understand available actions, then respond accordingly. For games, respond with your own move — think strategically.
+
+IMPORTANT: You MUST use the respond_to_user tool to send all messages to the user. Do NOT output plain text responses. Include your emotion and 3 suggested replies.${hasImageGen ? '\n\nYou can use generate_image to create images from text prompts. The generated image will be displayed in chat.' : ''}`;
+
+  prompt += buildMemoryPrompt(memories);
+
+  return prompt;
+}
diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.test.tsx b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.test.tsx
new file mode 100644
index 0000000..d6d47f6
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.test.tsx
@@ -0,0 +1,277 @@
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import type { LLMConfig } from '@/lib/llmModels';
+import type { ChatMessage, ToolCall } from '@/lib/llmClient';
+
+const {
+  chatMock,
+  seedMetaFilesMock,
+  loadActionsFromMetaMock,
+  executeFileToolMock,
+  getImageGenToolDefinitionsMock,
+  buildSystemPromptMock,
+  clearEmotionVideoCacheMock,
+  loadMemoriesMock,
+} = vi.hoisted(() => ({
+  chatMock: vi.fn(),
+  seedMetaFilesMock: vi.fn().mockResolvedValue(undefined),
+  loadActionsFromMetaMock: vi.fn().mockResolvedValue(undefined),
+  executeFileToolMock: vi.fn(),
+  getImageGenToolDefinitionsMock: vi.fn(() => [
+    { type: 'function', function: { name: 'generate_image' } },
+  ]),
+  buildSystemPromptMock: vi.fn(() => 'system prompt'),
+  clearEmotionVideoCacheMock: vi.fn(),
+  loadMemoriesMock: vi.fn(),
+}));
+
+vi.mock('@/lib/llmClient', () => ({
+  chat: chatMock,
+}));
+
+vi.mock('@/lib/seedMeta', () => ({
+  seedMetaFiles: seedMetaFilesMock,
+}));
+
+vi.mock('@/lib/appRegistry', () => ({
+  getAppActionToolDefinition: () => ({ type: 'function', function: { name: 'app_action' } }),
+  resolveAppAction: vi.fn(),
+  getListAppsToolDefinition: () => ({ type: 'function', function: { name: 'list_apps' } }),
+  executeListApps: vi.fn(() => '[]'),
+  loadActionsFromMeta: loadActionsFromMetaMock,
+}));
+
+vi.mock('@/lib/fileTools', () => ({
+  getFileToolDefinitions: () => [{ type: 'function', function: { name: 'file_write' } }],
+  isFileTool: (name: string) => name.startsWith('file_'),
+  executeFileTool: executeFileToolMock,
+}));
+
+vi.mock('@/lib/imageGenTools', () => ({
+  getImageGenToolDefinitions: getImageGenToolDefinitionsMock,
+  isImageGenTool: (name: string) => name === 'generate_image',
+  executeImageGenTool: vi.fn(),
+}));
+
+vi.mock('@/lib/memoryManager', () => ({
+  getMemoryToolDefinitions: () => [],
+  isMemoryTool: () => false,
+  executeMemoryTool: vi.fn(),
+  loadMemories: loadMemoriesMock,
+}));
+
+vi.mock('@/lib/characterManager', () => ({
+  clearEmotionVideoCache: clearEmotionVideoCacheMock,
+}));
+
+vi.mock('@/lib/modManager', () => ({
+  ModManager: class ModManager {},
+  saveModCollection: vi.fn(),
+}));
+
+vi.mock('@/lib/vibeContainerMock', () => ({
+  dispatchAgentAction: vi.fn(),
+}));
+
+vi.mock('./toolDefinitions', () => ({
+  getRespondToUserToolDef: () => ({ type: 'function', function: { name: 'respond_to_user' } }),
+  getFinishTargetToolDef: () => ({ type: 'function', function: { name: 'finish_target' } }),
+  buildSystemPrompt: buildSystemPromptMock,
+}));
+
+import {
+  useConversationEngine,
+  type ConversationCallbacks,
+  type ConversationDisplayMessage,
+} from './useConversationEngine';
+
+const CFG: LLMConfig = {
+  provider: 'openai',
+  apiKey: 'sk-test',
+  baseUrl: 'https://api.openai.com/v1',
+  model: 'gpt-4.1',
+};
+
+type HookApi = ReturnType<typeof useConversationEngine>;
+
+function makeToolCall(name: string, args: Record<string, unknown>, id = `${name}-1`): ToolCall {
+  return {
+    id,
+    type: 'function',
+    function: { name, arguments: JSON.stringify(args) },
+  };
+}
+
+function renderHookWithDeps(options?: { imageApiKey?: string | null }) {
+  const addMessage = vi.fn<(msg: ConversationDisplayMessage) => void>();
+  const chatHistorySetters: ChatMessage[][] = [];
+
+  const callbacks: ConversationCallbacks = {
+    addMessage,
+    setChatHistory: vi.fn((updater) => {
+      const next = typeof updater === 'function' ? updater([]) : updater;
+      chatHistorySetters.push(next as ChatMessage[]);
+      return next;
+    }),
+    setSuggestedReplies: vi.fn(),
+    setCurrentEmotion: vi.fn(),
+    setModCollection: vi.fn(),
+    setModManager: vi.fn(),
+    setMemories: vi.fn(),
+  };
+
+  const deps = {
+    imageGenConfigRef: {
+      current: options?.imageApiKey === null ? null : { apiKey: options?.imageApiKey ?? 'img-key' },
+    },
+    modManagerRef: { current: null },
+    characterRef: { current: { id: 'char-1' } },
+    memoriesRef: { current: [] },
+    sessionPathRef: { current: 'session/a' },
+    callbacks,
+  } as Parameters<typeof useConversationEngine>[0];
+
+  const host = document.createElement('div');
+  let root: Root | null = createRoot(host);
+  const api: { current: HookApi | null } = { current: null };
+
+  function Harness() {
+    api.current = useConversationEngine(deps);
+    return null;
+  }
+
+  act(() => {
+    root!.render(<Harness />);
+  });
+
+  return {
+    api,
+    callbacks,
+    addMessage,
+    chatHistorySetters,
+    cleanup: () => {
+      if (root) {
+        act(() => {
+          root!.unmount();
+        });
+        root = null;
+      }
+    },
+  };
+}
+
+describe('useConversationEngine', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    executeFileToolMock.mockResolvedValue('ok');
+    (
+      globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+    ).IS_REACT_ACT_ENVIRONMENT = true;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('passes the provided AbortSignal through to chat()', async () => {
+    chatMock.mockResolvedValueOnce({ content: 'hello', toolCalls: [] });
+    const harness = renderHookWithDeps();
+    const controller = new AbortController();
+
+    await harness.api.current!.runConversation(
+      [{ role: 'user', content: 'hi' }],
+      CFG,
+      controller.signal,
+    );
+
+    expect(chatMock).toHaveBeenCalledTimes(1);
+    expect(chatMock.mock.calls[0][3]).toBe(controller.signal);
+    expect(seedMetaFilesMock).toHaveBeenCalledTimes(1);
+    expect(loadActionsFromMetaMock).toHaveBeenCalledTimes(1);
+
+    harness.cleanup();
+  });
+
+  it('redacts file tool summaries to tool name and file path only', async () => {
+    chatMock
+      .mockResolvedValueOnce({
+        content: '',
+        toolCalls: [
+          makeToolCall('file_write', {
+            file_path: 'notes/secret.txt',
+            content: 'TOP SECRET CONTENT',
+            password: 'hunter2',
+          }),
+        ],
+      })
+      .mockResolvedValueOnce({
+        content: '',
+        toolCalls: [
+          makeToolCall('respond_to_user', {
+            character_expression: { content: 'Saved it.', emotion: 'calm' },
+            user_interaction: { suggested_replies: ['Nice'] },
+          }),
+        ],
+      });
+
+    const harness = renderHookWithDeps();
+
+    await harness.api.current!.runConversation([{ role: 'user', content: 'save this' }], CFG);
+
+    expect(executeFileToolMock).toHaveBeenCalledWith('file_write', {
+      file_path: 'notes/secret.txt',
+      content: 'TOP SECRET CONTENT',
+      password: 'hunter2',
+    });
+    expect(harness.addMessage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        content: 'Saved it.',
+        toolCalls: ['file_write(file_path: notes/secret.txt)'],
+      }),
+    );
+    expect(JSON.stringify(harness.addMessage.mock.calls)).not.toContain('TOP SECRET CONTENT');
+    expect(JSON.stringify(harness.addMessage.mock.calls)).not.toContain('hunter2');
+
+    harness.cleanup();
+  });
+
+  it('treats whitespace-only image generation keys as disabled', async () => {
+    chatMock.mockResolvedValueOnce({ content: 'no image tools', toolCalls: [] });
+    const harness = renderHookWithDeps({ imageApiKey: '   ' });
+
+    await harness.api.current!.runConversation([{ role: 'user', content: 'hi' }], CFG);
+
+    expect(buildSystemPromptMock).toHaveBeenCalledWith(expect.anything(), null, false, []);
+    expect(getImageGenToolDefinitionsMock).not.toHaveBeenCalled();
+    const toolsArg = chatMock.mock.calls[0][1] as Array<{ function: { name: string } }>;
+    expect(toolsArg.map((tool) => tool.function.name)).not.toContain('generate_image');
+
+    harness.cleanup();
+  });
+
+  it('stops after tool execution when the signal is aborted mid-loop', async () => {
+    const controller = new AbortController();
+    executeFileToolMock.mockImplementationOnce(async () => {
+      controller.abort();
+      return 'ok';
+    });
+    chatMock.mockResolvedValueOnce({
+      content: '',
+      toolCalls: [makeToolCall('file_write', { file_path: 'notes/a.txt', content: 'a' })],
+    });
+
+    const harness = renderHookWithDeps();
+
+    await harness.api.current!.runConversation(
+      [{ role: 'user', content: 'save' }],
+      CFG,
+      controller.signal,
+    );
+
+    expect(chatMock).toHaveBeenCalledTimes(1);
+    expect(executeFileToolMock).toHaveBeenCalledTimes(1);
+
+    harness.cleanup();
+  });
+});
diff --git a/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
new file mode 100644
index 0000000..accf6ac
--- /dev/null
+++ b/apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts
@@ -0,0 +1,401 @@
+/**
+ * useConversationEngine — extracted conversation loop from ChatPanel
+ *
+ * Encapsulates the LLM tool-call loop and dispatch logic.
+ * All side effects (state updates) are expressed as callbacks, keeping
+ * the engine itself pure and testable.
+ */
+
+import {
+  useCallback,
+  useRef,
+  type Dispatch,
+  type SetStateAction,
+  type MutableRefObject,
+} from 'react';
+import { chat, type ChatMessage, type ToolCall } from '@/lib/llmClient';
+import type { LLMConfig } from '@/lib/llmModels';
+import { type ImageGenConfig } from '@/lib/imageGenClient';
+import type { CharacterConfig } from '@/lib/characterManager';
+import { clearEmotionVideoCache } from '@/lib/characterManager';
+import type { MemoryEntry } from '@/lib/memoryManager';
+import { loadMemories } from '@/lib/memoryManager';
+import {
+  getAppActionToolDefinition,
+  resolveAppAction,
+  getListAppsToolDefinition,
+  executeListApps,
+  loadActionsFromMeta,
+} from '@/lib/appRegistry';
+import { getFileToolDefinitions, isFileTool, executeFileTool } from '@/lib/fileTools';
+import { seedMetaFiles } from '@/lib/seedMeta';
+import { dispatchAgentAction } from '@/lib/vibeContainerMock';
+import {
+  getImageGenToolDefinitions,
+  isImageGenTool,
+  executeImageGenTool,
+} from '@/lib/imageGenTools';
+import { getMemoryToolDefinitions, isMemoryTool, executeMemoryTool } from '@/lib/memoryManager';
+import { ModManager, saveModCollection } from '@/lib/modManager';
+import {
+  getRespondToUserToolDef,
+  getFinishTargetToolDef,
+  buildSystemPrompt,
+} from './toolDefinitions';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ConversationCallbacks {
+  addMessage: (msg: ConversationDisplayMessage) => void;
+  setChatHistory: Dispatch<SetStateAction<ChatMessage[]>>;
+  setSuggestedReplies: Dispatch<SetStateAction<string[]>>;
+  setCurrentEmotion: Dispatch<SetStateAction<string | undefined>>;
+  setModCollection: Dispatch<SetStateAction<import('@/lib/modManager').ModCollection>>;
+  setModManager: Dispatch<SetStateAction<ModManager | null>>;
+  setMemories: Dispatch<SetStateAction<MemoryEntry[]>>;
+}
+
+export interface ConversationDisplayMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'tool';
+  content: string;
+  emotion?: string;
+  suggestedReplies?: string[];
+  toolCalls?: string[];
+  imageUrl?: string;
+}
+
+export interface ConversationEngineDeps {
+  /** Refs to current values (avoids stale closures) */
+  imageGenConfigRef: MutableRefObject<ImageGenConfig | null>;
+  modManagerRef: MutableRefObject<ModManager | null>;
+  characterRef: MutableRefObject<CharacterConfig>;
+  memoriesRef: MutableRefObject<MemoryEntry[]>;
+  sessionPathRef: MutableRefObject<string>;
+
+  /** Side-effect callbacks */
+  callbacks: ConversationCallbacks;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+export function useConversationEngine(deps: ConversationEngineDeps) {
+  const { imageGenConfigRef, modManagerRef, characterRef, memoriesRef, sessionPathRef } = deps;
+
+  // Keep callbacks in a ref so the stabilized runConversation always reads the
+  // latest versions without needing them in its dependency array.
+  const callbacksRef = useRef(deps.callbacks);
+  callbacksRef.current = deps.callbacks;
+
+  const pendingToolCallsRef = useRef<string[]>([]);
+
+  // Abort controller for the current conversation — allows cancellation when
+  // the user switches sessions or triggers a new request.
+  const abortRef = useRef<AbortController | null>(null);
+
+  /**
+   * Core conversation loop — sends messages to LLM, executes tool calls,
+   * and loops until the model responds via respond_to_user or produces plain text.
+   *
+   * Stabilized with useCallback — all inputs are refs, so this identity never
+   * changes, preventing unsubscribe/subscribe churn in the onUserAction listener.
+   *
+   * @param signal AbortSignal to cancel the conversation mid-loop
+   */
+  const runConversation = useCallback(
+    async (history: ChatMessage[], cfg: LLMConfig, signal?: AbortSignal) => {
+      await seedMetaFiles();
+      await loadActionsFromMeta();
+      const hasImageGen = (imageGenConfigRef.current?.apiKey?.trim().length ?? 0) > 0;
+      const mm = modManagerRef.current;
+      const char = characterRef.current;
+
+      const tools = [
+        getRespondToUserToolDef(),
+        getFinishTargetToolDef(),
+        getListAppsToolDefinition(),
+        getAppActionToolDefinition(),
+        ...getFileToolDefinitions(),
+        ...getMemoryToolDefinitions(),
+        ...(hasImageGen ? getImageGenToolDefinitions() : []),
+      ];
+
+      const currentMemories = memoriesRef.current;
+      const fullMessages: ChatMessage[] = [
+        { role: 'system', content: buildSystemPrompt(char, mm, hasImageGen, currentMemories) },
+        ...history,
+      ];
+
+      let currentMessages = fullMessages;
+      let iterations = 0;
+      const maxIterations = 10;
+      pendingToolCallsRef.current = [];
+
+      while (iterations < maxIterations) {
+        if (signal?.aborted) break;
+        iterations++;
+        const response = await chat(currentMessages, tools, cfg, signal);
+
+        if (response.toolCalls.length === 0) {
+          // No tool calls — fallback plain text
+          if (response.content) {
+            callbacksRef.current.addMessage({
+              id: String(Date.now()),
+              role: 'assistant',
+              content: response.content,
+              toolCalls:
+                pendingToolCallsRef.current.length > 0
+                  ? [...pendingToolCallsRef.current]
+                  : undefined,
+            });
+            callbacksRef.current.setChatHistory((prev) => [
+              ...prev,
+              { role: 'assistant', content: response.content },
+            ]);
+            pendingToolCallsRef.current = [];
+          }
+          break;
+        }
+
+        // Has tool calls — build assistant message
+        const assistantMsg: ChatMessage = {
+          role: 'assistant',
+          content: response.content,
+          tool_calls: response.toolCalls,
+        };
+        currentMessages = [...currentMessages, assistantMsg];
+
+        // Execute each tool call
+        const hasRespondToUser = response.toolCalls.some(
+          (tc) => tc.function.name === 'respond_to_user',
+        );
+        for (const tc of response.toolCalls) {
+          const result = await executeToolCall(tc, {
+            mm,
+            hasImageGen,
+            pendingToolCallsRef,
+            sessionPathRef,
+            imageGenConfigRef,
+            characterRef,
+            callbacks: callbacksRef.current,
+          });
+          currentMessages = [...currentMessages, result];
+        }
+
+        // Update chat history (skip system message)
+        callbacksRef.current.setChatHistory(currentMessages.slice(1));
+
+        // Only break when respond_to_user was the sole tool call — if other
+        // tools ran in the same batch the model may still need a follow-up
+        // round-trip (e.g. finish_target) to commit state updates.
+        if (hasRespondToUser && response.toolCalls.length === 1) break;
+        if (signal?.aborted) break;
+      }
+    },
+    [],
+  );
+
+  return { runConversation, pendingToolCallsRef, abortRef };
+}
+
+// ---------------------------------------------------------------------------
+// Tool dispatch — each branch returns a tool-result ChatMessage
+// ---------------------------------------------------------------------------
+
+async function executeToolCall(
+  tc: ToolCall,
+  ctx: {
+    mm: ModManager | null;
+    hasImageGen: boolean;
+    pendingToolCallsRef: MutableRefObject<string[]>;
+    sessionPathRef: MutableRefObject<string>;
+    imageGenConfigRef: MutableRefObject<ImageGenConfig | null>;
+    characterRef: MutableRefObject<CharacterConfig>;
+    callbacks: ConversationCallbacks;
+  },
+): Promise<ChatMessage> {
+  let params: Record<string, unknown> = {};
+  try {
+    params = JSON.parse(tc.function.arguments);
+  } catch (e) {
+    console.warn('Failed to parse tool call arguments for tool:', tc.function.name, e);
+  }
+
+  const toolResult = (content: string): ChatMessage => ({
+    role: 'tool',
+    content,
+    tool_call_id: tc.id,
+  });
+
+  // ---- respond_to_user ----
+  if (tc.function.name === 'respond_to_user') {
+    const expr = (params.character_expression as { content?: string; emotion?: string }) ?? {};
+    const interaction = (params.user_interaction as { suggested_replies?: string[] }) ?? {};
+
+    const content = expr.content ?? '';
+    const emotion = expr.emotion;
+    const replies = interaction.suggested_replies ?? [];
+
+    ctx.callbacks.addMessage({
+      id: String(Date.now()),
+      role: 'assistant',
+      content,
+      emotion,
+      suggestedReplies: replies,
+      toolCalls:
+        ctx.pendingToolCallsRef.current.length > 0
+          ? [...ctx.pendingToolCallsRef.current]
+          : undefined,
+    });
+    ctx.callbacks.setSuggestedReplies(replies);
+    if (emotion) {
+      clearEmotionVideoCache(ctx.characterRef.current.id);
+      ctx.callbacks.setCurrentEmotion(emotion);
+    }
+    ctx.pendingToolCallsRef.current = [];
+    ctx.callbacks.setChatHistory((prev) => [...prev, { role: 'assistant', content }]);
+    return toolResult('Message delivered.');
+  }
+
+  // ---- finish_target ----
+  if (tc.function.name === 'finish_target') {
+    const targetIds = (params.target_ids as number[]) ?? [];
+    if (ctx.mm) {
+      const result = ctx.mm.finishTarget(targetIds);
+      const updatedEntry = { config: ctx.mm.getConfig(), state: ctx.mm.getState() };
+      ctx.callbacks.setModCollection((prev) => {
+        const updated = {
+          ...prev,
+          items: { ...prev.items, [updatedEntry.config.id]: updatedEntry },
+        };
+        saveModCollection(updated);
+        return updated;
+      });
+      ctx.callbacks.setModManager(new ModManager(ctx.mm.getConfig(), ctx.mm.getState()));
+      return toolResult(JSON.stringify(result));
+    }
+    return toolResult('No mod loaded.');
+  }
+
+  // ---- list_apps ----
+  if (tc.function.name === 'list_apps') {
+    const result = executeListApps();
+    ctx.pendingToolCallsRef.current.push('list_apps');
+    return toolResult(result);
+  }
+
+  // ---- File tools ----
+  if (isFileTool(tc.function.name)) {
+    // Only log tool name + path to avoid persisting sensitive file contents
+    const pathKeys = [
+      'path',
+      'file_path',
+      'filePath',
+      'sourcePath',
+      'targetPath',
+      'destinationPath',
+    ] as const;
+    let summary = tc.function.name;
+    for (const key of pathKeys) {
+      const value = (params as Record<string, unknown>)[key];
+      if (typeof value === 'string' && value.length > 0) {
+        summary = `${tc.function.name}(${key}: ${value})`;
+        break;
+      }
+    }
+    ctx.pendingToolCallsRef.current.push(summary);
+    try {
+      const result = await executeFileTool(tc.function.name, params as Record<string, string>);
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // ---- Image gen ----
+  if (isImageGenTool(tc.function.name)) {
+    ctx.pendingToolCallsRef.current.push('generate_image');
+    try {
+      const { result, dataUrl } = await executeImageGenTool(
+        params as Record<string, string>,
+        ctx.imageGenConfigRef.current,
+      );
+      if (dataUrl) {
+        ctx.callbacks.addMessage({
+          id: String(Date.now()) + '-img',
+          role: 'assistant',
+          content: '',
+          imageUrl: dataUrl,
+        });
+      }
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // ---- Memory tools ----
+  if (isMemoryTool(tc.function.name)) {
+    ctx.pendingToolCallsRef.current.push('save_memory');
+    try {
+      const result = await executeMemoryTool(
+        ctx.sessionPathRef.current,
+        params as Record<string, string>,
+      );
+      const capturedSession = ctx.sessionPathRef.current;
+      loadMemories(capturedSession)
+        .then((mems) => {
+          if (ctx.sessionPathRef.current === capturedSession) {
+            ctx.callbacks.setMemories(mems);
+          }
+        })
+        .catch((err) => {
+          console.warn('Failed to reload memories after save:', err);
+          if (ctx.sessionPathRef.current === capturedSession) {
+            ctx.callbacks.setMemories([]);
+          }
+        });
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // ---- app_action ----
+  if (tc.function.name === 'app_action') {
+    const strParams = params as Record<string, string>;
+    const resolved = resolveAppAction(strParams.app_name, strParams.action_type);
+    if (typeof resolved === 'string') {
+      return toolResult(resolved);
+    }
+
+    ctx.pendingToolCallsRef.current.push(`${strParams.app_name}/${strParams.action_type}`);
+
+    let actionParams: Record<string, string> = {};
+    if (strParams.params) {
+      try {
+        actionParams = JSON.parse(strParams.params);
+      } catch {
+        // empty
+      }
+    }
+
+    try {
+      const result = await dispatchAgentAction({
+        app_id: resolved.appId,
+        action_type: resolved.actionType,
+        params: actionParams,
+      });
+      return toolResult(result);
+    } catch (err) {
+      return toolResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Unknown tool
+  return toolResult('error: unknown tool');
+}
diff --git a/apps/webuiapps/src/components/ErrorBoundary.module.scss b/apps/webuiapps/src/components/ErrorBoundary.module.scss
new file mode 100644
index 0000000..fa5f3aa
--- /dev/null
+++ b/apps/webuiapps/src/components/ErrorBoundary.module.scss
@@ -0,0 +1,50 @@
+.fallback {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  padding: 24px;
+  background: rgba(0, 0, 0, 0.85);
+  border-radius: 8px;
+  color: #fff;
+  font-family:
+    system-ui,
+    -apple-system,
+    sans-serif;
+  text-align: center;
+  gap: 8px;
+}
+
+.icon {
+  font-size: 32px;
+  margin-bottom: 4px;
+}
+
+.message {
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.detail {
+  font-size: 12px;
+  color: rgba(255, 255, 255, 0.6);
+  max-width: 280px;
+  word-break: break-word;
+}
+
+.retryBtn {
+  margin-top: 8px;
+  padding: 6px 16px;
+  background: rgba(255, 255, 255, 0.15);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 6px;
+  color: #fff;
+  font-size: 13px;
+  cursor: pointer;
+  transition: background 0.15s;
+
+  &:hover {
+    background: rgba(255, 255, 255, 0.25);
+  }
+}
diff --git a/apps/webuiapps/src/components/ErrorBoundary.tsx b/apps/webuiapps/src/components/ErrorBoundary.tsx
new file mode 100644
index 0000000..1caf6bd
--- /dev/null
+++ b/apps/webuiapps/src/components/ErrorBoundary.tsx
@@ -0,0 +1,62 @@
+/**
+ * ErrorBoundary — prevents child crashes from taking down the entire Shell.
+ *
+ * Usage: Wrap any subtree that should be isolated (AppWindow, ChatPanel, etc.)
+ * The fallback shows a compact error card with a retry button.
+ */
+
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+import styles from './ErrorBoundary.module.scss';
+
+interface Props {
+  children: ReactNode;
+  /** Optional label shown in the fallback UI (e.g. "Chess" or "Chat") */
+  name?: string;
+}
+
+interface State {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    console.error(`[ErrorBoundary${this.props.name ? `:${this.props.name}` : ''}]`, error, info);
+  }
+
+  private handleRetry = () => {
+    this.setState({ hasError: false, error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return (
+        <div
+          className={styles.fallback}
+          data-testid="error-boundary-fallback"
+          role="alert"
+          aria-live="assertive"
+        >
+          <div className={styles.icon}>⚠️</div>
+          <div className={styles.message}>
+            {this.props.name ? `${this.props.name} crashed` : 'Something went wrong'}
+          </div>
+          <div className={styles.detail}>{this.state.error?.message}</div>
+          <button type="button" className={styles.retryBtn} onClick={this.handleRetry}>
+            Retry
+          </button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
diff --git a/apps/webuiapps/src/components/Shell/index.tsx b/apps/webuiapps/src/components/Shell/index.tsx
index 2066df3..fb0d903 100644
--- a/apps/webuiapps/src/components/Shell/index.tsx
+++ b/apps/webuiapps/src/components/Shell/index.tsx
@@ -23,6 +23,7 @@ import {
 } from 'lucide-react';
 import ChatPanel from '../ChatPanel';
 import AppWindow from '../AppWindow';
+import { ErrorBoundary } from '../ErrorBoundary';
 import { getWindows, subscribe, openWindow, claimZIndex } from '@/lib/windowManager';
 import { getDesktopApps } from '@/lib/appRegistry';
 import { reportUserOsAction, onOSEvent } from '@/lib/vibeContainerMock';
@@ -350,18 +351,22 @@ const Shell: React.FC = () => {
         </div>
       </div>
 
-      {/* App windows */}
+      {/* App windows — each wrapped in ErrorBoundary so a crash doesn't kill the Shell */}
       {windows.map((win) => (
-        <AppWindow key={win.appId} win={win} />
+        <ErrorBoundary key={win.appId} name={`App ${win.appId}`}>
+          <AppWindow win={win} />
+        </ErrorBoundary>
       ))}
 
       {/* Chat Panel — always mounted to preserve chat history */}
-      <ChatPanel
-        onClose={() => setChatOpen(false)}
-        visible={chatOpen}
-        zIndex={chatZIndex}
-        onFocus={() => setChatZIndex(claimZIndex())}
-      />
+      <ErrorBoundary name="Chat">
+        <ChatPanel
+          onClose={() => setChatOpen(false)}
+          visible={chatOpen}
+          zIndex={chatZIndex}
+          onFocus={() => setChatZIndex(claimZIndex())}
+        />
+      </ErrorBoundary>
 
       {/* Upload Modal */}
       {uploadOpen && (
diff --git a/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts b/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
index 06758b0..2a0fb4d 100644
--- a/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/configPersistence.test.ts
@@ -1,30 +1,27 @@
-/**
- * Unit tests for configPersistence.ts
- *
- * Covers: loadPersistedConfig, savePersistedConfig, legacy format migration
- */
+/** Unit tests for configPersistence.ts */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
   loadPersistedConfig,
   savePersistedConfig,
   type PersistedConfig,
+  type PersistedConfigUpdate,
 } from '../configPersistence';
 import type { LLMConfig } from '../llmModels';
 import type { ImageGenConfig } from '../imageGenClient';
 
-// ─── Constants ──────────────────────────────────────────────────────────────────
-
 const MOCK_LLM_CONFIG: LLMConfig = {
   provider: 'openai',
-  apiKey: 'sk-test',
+  apiKey: '',
+  hasApiKey: true,
   baseUrl: 'https://api.openai.com',
   model: 'gpt-4',
 };
 
 const MOCK_IMAGEGEN_CONFIG: ImageGenConfig = {
   provider: 'openai',
-  apiKey: 'sk-img-test',
+  apiKey: '',
+  hasApiKey: true,
   baseUrl: 'https://api.openai.com',
   model: 'gpt-image-1.5',
 };
@@ -34,8 +31,6 @@ const MOCK_PERSISTED: PersistedConfig = {
   imageGen: MOCK_IMAGEGEN_CONFIG,
 };
 
-// ─── Setup / Teardown ───────────────────────────────────────────────────────────
-
 beforeEach(() => {
   vi.restoreAllMocks();
 });
@@ -44,115 +39,74 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-// ─── loadPersistedConfig() ──────────────────────────────────────────────────────
-
 describe('loadPersistedConfig()', () => {
-  it('returns full config when file has new { llm, imageGen } format', async () => {
+  it('returns redacted config when the API responds with the new format', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
       json: () => Promise.resolve(MOCK_PERSISTED),
     } as unknown as Response);
 
-    const result = await loadPersistedConfig();
-
-    expect(result).toEqual(MOCK_PERSISTED);
-    expect(result?.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(result?.imageGen).toEqual(MOCK_IMAGEGEN_CONFIG);
-  });
-
-  it('returns { llm } only when imageGen is absent', async () => {
-    const withoutImageGen = { llm: MOCK_LLM_CONFIG };
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve(withoutImageGen),
-    } as unknown as Response);
-
-    const result = await loadPersistedConfig();
-
-    expect(result?.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(result?.imageGen).toBeUndefined();
+    await expect(loadPersistedConfig()).resolves.toEqual(MOCK_PERSISTED);
   });
 
-  it('migrates legacy flat LLMConfig format to { llm } wrapper', async () => {
-    // Legacy format: flat LLMConfig at top level (has "provider", no "llm" key)
+  it('migrates legacy flat LLMConfig format to { llm }', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve(MOCK_LLM_CONFIG),
+      json: () => Promise.resolve({ ...MOCK_LLM_CONFIG }),
     } as unknown as Response);
 
-    const result = await loadPersistedConfig();
-
-    expect(result).toEqual({ llm: MOCK_LLM_CONFIG });
-    expect(result?.llm.provider).toBe('openai');
-    expect(result?.imageGen).toBeUndefined();
-  });
-
-  it('returns null when API returns 404', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: false,
-      status: 404,
-    } as Response);
-
-    expect(await loadPersistedConfig()).toBeNull();
+    await expect(loadPersistedConfig()).resolves.toEqual({ llm: { ...MOCK_LLM_CONFIG } });
   });
 
-  it('returns null when fetch throws (network error)', async () => {
+  it('returns null when the API request fails', async () => {
     globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
 
-    expect(await loadPersistedConfig()).toBeNull();
-  });
-
-  it('returns null when response is not a recognized format', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
-      ok: true,
-      json: () => Promise.resolve({ unrelated: 'data' }),
-    } as unknown as Response);
-
-    expect(await loadPersistedConfig()).toBeNull();
+    await expect(loadPersistedConfig()).resolves.toBeNull();
   });
 });
 
-// ─── savePersistedConfig() ──────────────────────────────────────────────────────
-
 describe('savePersistedConfig()', () => {
-  it('POSTs the full config to /api/llm-config', async () => {
+  it('POSTs the config update to /api/llm-config', async () => {
     const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
     globalThis.fetch = mockFetch;
 
-    await savePersistedConfig(MOCK_PERSISTED);
+    const update: PersistedConfigUpdate = {
+      llm: {
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com',
+        model: 'gpt-4',
+      },
+      imageGen: null,
+    };
+
+    const result = await savePersistedConfig(update);
 
+    expect(result).toEqual({ ok: true });
     expect(mockFetch).toHaveBeenCalledWith('/api/llm-config', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(MOCK_PERSISTED),
+      body: JSON.stringify(update),
     });
   });
 
-  it('includes imageGen in the persisted JSON', async () => {
-    const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
-    globalThis.fetch = mockFetch;
-
-    await savePersistedConfig(MOCK_PERSISTED);
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
-    expect(body.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(body.imageGen).toEqual(MOCK_IMAGEGEN_CONFIG);
-  });
-
-  it('omits imageGen when not provided', async () => {
-    const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
-    globalThis.fetch = mockFetch;
-
-    await savePersistedConfig({ llm: MOCK_LLM_CONFIG });
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
-    expect(body.llm).toEqual(MOCK_LLM_CONFIG);
-    expect(body.imageGen).toBeUndefined();
-  });
-
-  it('does not throw when fetch fails', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
+  it('returns an error result when the API rejects the save', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 400,
+      text: () => Promise.resolve('bad request'),
+    } as unknown as Response);
 
-    await expect(savePersistedConfig(MOCK_PERSISTED)).resolves.toBeUndefined();
+    await expect(
+      savePersistedConfig({
+        llm: {
+          provider: 'openai',
+          baseUrl: 'https://api.openai.com',
+          model: 'gpt-4',
+        },
+      }),
+    ).resolves.toEqual({
+      ok: false,
+      error: 'Failed to save config (400): bad request',
+    });
   });
 });
diff --git a/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts b/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts
index ab4ea5d..3c4ea35 100644
--- a/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/imageGenClient.test.ts
@@ -1,6 +1,4 @@
-/**
- * Unit tests for imageGenClient.ts — config loading/saving
- */
+/** Unit tests for imageGenClient.ts */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
@@ -8,11 +6,11 @@ import {
   loadImageGenConfigSync,
   saveImageGenConfig,
   getDefaultImageGenConfig,
+  hasUsableImageGenConfig,
+  generateImage,
   type ImageGenConfig,
 } from '../imageGenClient';
 
-const CONFIG_KEY = 'webuiapps-imagegen-config';
-
 const MOCK_IG_CONFIG: ImageGenConfig = {
   provider: 'openai',
   apiKey: 'sk-img-test',
@@ -20,15 +18,7 @@ const MOCK_IG_CONFIG: ImageGenConfig = {
   model: 'gpt-image-1.5',
 };
 
-const MOCK_LLM_CONFIG = {
-  provider: 'openai',
-  apiKey: 'sk-llm',
-  baseUrl: 'https://api.openai.com',
-  model: 'gpt-4',
-};
-
 beforeEach(() => {
-  localStorage.clear();
   vi.restoreAllMocks();
 });
 
@@ -51,78 +41,71 @@ describe('getDefaultImageGenConfig()', () => {
 });
 
 describe('loadImageGenConfigSync()', () => {
-  it('returns null when localStorage is empty', () => {
-    expect(loadImageGenConfigSync()).toBeNull();
-  });
-
-  it('returns parsed config from localStorage', () => {
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_IG_CONFIG));
-    expect(loadImageGenConfigSync()).toEqual(MOCK_IG_CONFIG);
-  });
-
-  it('returns null on invalid JSON', () => {
-    localStorage.setItem(CONFIG_KEY, 'bad-json');
+  it('always returns null because browser-side key caching is disabled', () => {
     expect(loadImageGenConfigSync()).toBeNull();
   });
 });
 
 describe('loadImageGenConfig()', () => {
-  it('loads imageGen from file API (new format) and syncs to localStorage', async () => {
+  it('loads redacted imageGen config from the config API', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve({ llm: MOCK_LLM_CONFIG, imageGen: MOCK_IG_CONFIG }),
+      json: () =>
+        Promise.resolve({
+          llm: { provider: 'openai', apiKey: '', hasApiKey: true, baseUrl: 'u', model: 'm' },
+          imageGen: { ...MOCK_IG_CONFIG, apiKey: '', hasApiKey: true },
+        }),
     } as unknown as Response);
 
-    const result = await loadImageGenConfig();
-
-    expect(result).toEqual(MOCK_IG_CONFIG);
-    expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_IG_CONFIG));
+    await expect(loadImageGenConfig()).resolves.toEqual({
+      ...MOCK_IG_CONFIG,
+      apiKey: '',
+      hasApiKey: true,
+    });
   });
 
-  it('returns null from file API when imageGen is absent (LLM-only config)', async () => {
+  it('returns null when the config API has no imageGen section', async () => {
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve({ llm: MOCK_LLM_CONFIG }),
+      json: () =>
+        Promise.resolve({ llm: { provider: 'openai', apiKey: '', baseUrl: 'u', model: 'm' } }),
     } as unknown as Response);
 
-    const result = await loadImageGenConfig();
-
-    // No imageGen in file → falls through to localStorage
-    expect(result).toBeNull();
+    await expect(loadImageGenConfig()).resolves.toBeNull();
   });
+});
 
-  it('falls back to localStorage when API is unavailable', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_IG_CONFIG));
-
-    const result = await loadImageGenConfig();
-
-    expect(result).toEqual(MOCK_IG_CONFIG);
+describe('saveImageGenConfig()', () => {
+  it('remains a no-op because image config is saved via llmClient.saveConfig', () => {
+    expect(() => saveImageGenConfig(MOCK_IG_CONFIG)).not.toThrow();
   });
+});
 
-  it('returns null when both API and localStorage have nothing', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({ ok: false, status: 404 } as Response);
+describe('hasUsableImageGenConfig()', () => {
+  it('accepts redacted configs when the server reports a stored key', () => {
+    expect(hasUsableImageGenConfig({ ...MOCK_IG_CONFIG, apiKey: '', hasApiKey: true })).toBe(true);
+  });
 
-    expect(await loadImageGenConfig()).toBeNull();
+  it('rejects configs without a key or server-side key flag', () => {
+    expect(hasUsableImageGenConfig({ ...MOCK_IG_CONFIG, apiKey: '', hasApiKey: false })).toBe(
+      false,
+    );
   });
+});
 
-  it('handles legacy flat LLMConfig file (no imageGen) gracefully', async () => {
-    // Legacy file has flat LLMConfig → no imageGen field
-    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+describe('generateImage()', () => {
+  it('marks image generation requests with the imageGen config scope header', async () => {
+    const mockFetch = vi.fn().mockResolvedValueOnce({
       ok: true,
-      json: () => Promise.resolve(MOCK_LLM_CONFIG),
+      json: () => Promise.resolve({ data: [{ b64_json: 'abc123' }] }),
+      text: () => Promise.resolve(''),
     } as unknown as Response);
+    globalThis.fetch = mockFetch;
 
-    const result = await loadImageGenConfig();
-
-    // Legacy format has no imageGen → should fall through to localStorage
-    expect(result).toBeNull();
-  });
-});
+    await generateImage('draw a castle', MOCK_IG_CONFIG);
 
-describe('saveImageGenConfig()', () => {
-  it('writes to localStorage', () => {
-    saveImageGenConfig(MOCK_IG_CONFIG);
-    expect(JSON.parse(localStorage.getItem(CONFIG_KEY)!)).toEqual(MOCK_IG_CONFIG);
+    const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
+    expect(headers['X-LLM-Config-Scope']).toBe('imageGen');
+    expect(headers['X-LLM-Target-URL']).toBe('https://api.openai.com/v1/images/generations');
   });
 });
diff --git a/apps/webuiapps/src/lib/__tests__/llmClient.test.ts b/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
index 1b53438..a930b7e 100644
--- a/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
+++ b/apps/webuiapps/src/lib/__tests__/llmClient.test.ts
@@ -1,11 +1,4 @@
-/**
- * Unit tests for llmClient.ts
- *
- * Environment: happy-dom (provides localStorage, fetch globals)
- * Mock strategy:
- *   - fetch: vi.fn() via globalThis.fetch per test
- *   - localStorage: happy-dom provides real implementation, cleared in beforeEach
- */
+/** Unit tests for llmClient.ts */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import {
@@ -18,10 +11,6 @@ import {
 } from '../llmClient';
 import { getDefaultProviderConfig, type LLMConfig } from '../llmModels';
 
-// ─── Constants ────────────────────────────────────────────────────────────────
-
-const CONFIG_KEY = 'webuiapps-llm-config';
-
 const MOCK_OPENAI_CONFIG: LLMConfig = {
   provider: 'openai',
   apiKey: 'sk-test-key',
@@ -90,7 +79,6 @@ function makeErrorResponse(status: number, bodyText: string) {
 // ─── Setup / Teardown ─────────────────────────────────────────────────────────
 
 beforeEach(() => {
-  localStorage.clear();
   vi.restoreAllMocks();
 });
 
@@ -163,175 +151,100 @@ describe('getDefaultProviderConfig()', () => {
   });
 });
 
-// ─── loadConfigSync() ─────────────────────────────────────────────────────────
-
 describe('loadConfigSync()', () => {
-  it('returns null when localStorage is empty', () => {
-    expect(loadConfigSync()).toBeNull();
-  });
-
-  it('returns parsed config when localStorage has valid JSON', () => {
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_OPENAI_CONFIG));
-    expect(loadConfigSync()).toEqual(MOCK_OPENAI_CONFIG);
-  });
-
-  it('returns null when localStorage contains invalid JSON', () => {
-    localStorage.setItem(CONFIG_KEY, 'not-valid-json{{{');
+  it('always returns null because browser-side key caching is disabled', () => {
     expect(loadConfigSync()).toBeNull();
   });
-
-  it('returns null when value is empty string', () => {
-    localStorage.setItem(CONFIG_KEY, '');
-    expect(loadConfigSync()).toBeNull();
-  });
-
-  it('preserves optional customHeaders field', () => {
-    const cfg: LLMConfig = { ...MOCK_OPENAI_CONFIG, customHeaders: 'X-Foo: bar\nX-Baz: qux' };
-    localStorage.setItem(CONFIG_KEY, JSON.stringify(cfg));
-    expect(loadConfigSync()?.customHeaders).toBe('X-Foo: bar\nX-Baz: qux');
-  });
 });
 
-// ─── loadConfig() ─────────────────────────────────────────────────────────────
-
 describe('loadConfig()', () => {
-  describe('Scenario A: API returns 200 with new format', () => {
-    it('returns LLM config from { llm, imageGen } format and syncs to localStorage', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({
-        ok: true,
-        json: () =>
-          Promise.resolve({
-            llm: MOCK_OPENAI_CONFIG,
-            imageGen: { provider: 'openai', apiKey: 'k', baseUrl: 'u', model: 'm' },
-          }),
-      } as unknown as Response);
-
-      const result = await loadConfig();
-
-      expect(result).toEqual(MOCK_OPENAI_CONFIG);
-      expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_OPENAI_CONFIG));
-    });
-  });
-
-  describe('Scenario A2: API returns 200 with legacy flat format', () => {
-    it('returns config from legacy flat LLMConfig format', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({
-        ok: true,
-        json: () => Promise.resolve(MOCK_OPENAI_CONFIG),
-      } as unknown as Response);
-
-      const result = await loadConfig();
-
-      expect(result).toEqual(MOCK_OPENAI_CONFIG);
-      expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_OPENAI_CONFIG));
+  it('returns redacted LLM config from the persisted payload', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: () =>
+        Promise.resolve({
+          llm: { ...MOCK_OPENAI_CONFIG, apiKey: '', hasApiKey: true },
+          imageGen: { provider: 'openai', apiKey: '', hasApiKey: true, baseUrl: 'u', model: 'm' },
+        }),
+    } as unknown as Response);
+
+    await expect(loadConfig()).resolves.toEqual({
+      ...MOCK_OPENAI_CONFIG,
+      apiKey: '',
+      hasApiKey: true,
     });
   });
 
-  describe('Scenario B: API returns 404 (no file)', () => {
-    it('falls back to localStorage when API returns 404', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({ ok: false, status: 404 } as Response);
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_OPENAI_CONFIG));
-
-      expect(await loadConfig()).toEqual(MOCK_OPENAI_CONFIG);
-    });
-
-    it('returns null when API returns 404 and localStorage is empty', async () => {
-      globalThis.fetch = vi.fn().mockResolvedValueOnce({ ok: false, status: 404 } as Response);
+  it('supports legacy flat config responses', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve(MOCK_OPENAI_CONFIG),
+    } as unknown as Response);
 
-      expect(await loadConfig()).toBeNull();
-    });
+    await expect(loadConfig()).resolves.toEqual(MOCK_OPENAI_CONFIG);
   });
 
-  describe('Scenario C: fetch throws (network error / production)', () => {
-    it('falls back to localStorage on network error', async () => {
-      globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(MOCK_ANTHROPIC_CONFIG));
-
-      expect(await loadConfig()).toEqual(MOCK_ANTHROPIC_CONFIG);
-    });
-
-    it('returns null when fetch throws and localStorage is empty', async () => {
-      globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('fetch is not defined'));
-
-      expect(await loadConfig()).toBeNull();
-    });
+  it('returns null when the config API is unavailable', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
 
-    it('resolves null when both API and localStorage fail (does not throw)', async () => {
-      globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('Network error'));
-      localStorage.setItem(CONFIG_KEY, 'corrupted-json');
-
-      await expect(loadConfig()).resolves.toBeNull();
-    });
+    await expect(loadConfig()).resolves.toBeNull();
   });
 });
 
-// ─── saveConfig() ─────────────────────────────────────────────────────────────
-
 describe('saveConfig()', () => {
-  it('always writes to localStorage even if fetch fails', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('API unavailable'));
-
-    await saveConfig(MOCK_OPENAI_CONFIG);
-
-    expect(localStorage.getItem(CONFIG_KEY)).toBe(JSON.stringify(MOCK_OPENAI_CONFIG));
-  });
-
   it('POSTs new { llm } format to /api/llm-config', async () => {
     const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
     globalThis.fetch = mockFetch;
 
-    await saveConfig(MOCK_OPENAI_CONFIG);
+    await expect(saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: undefined })).resolves.toEqual({
+      ok: true,
+    });
 
     expect(mockFetch).toHaveBeenCalledWith('/api/llm-config', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ llm: MOCK_OPENAI_CONFIG }),
+      body: JSON.stringify({
+        llm: {
+          provider: MOCK_OPENAI_CONFIG.provider,
+          baseUrl: MOCK_OPENAI_CONFIG.baseUrl,
+          model: MOCK_OPENAI_CONFIG.model,
+        },
+      }),
     });
   });
 
-  it('includes imageGen when provided', async () => {
+  it('includes imageGen updates when provided', async () => {
     const mockFetch = vi.fn().mockResolvedValueOnce({ ok: true } as Response);
     globalThis.fetch = mockFetch;
 
-    const igConfig = { provider: 'openai' as const, apiKey: 'k', baseUrl: 'u', model: 'm' };
-    await saveConfig(MOCK_OPENAI_CONFIG, igConfig);
+    const igConfig = { provider: 'openai' as const, baseUrl: 'u', model: 'm' };
+    await expect(
+      saveConfig({ ...MOCK_OPENAI_CONFIG, apiKey: 'next-key' }, igConfig),
+    ).resolves.toEqual({
+      ok: true,
+    });
 
     const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
-    expect(body.llm).toEqual(MOCK_OPENAI_CONFIG);
+    expect(body.llm).toEqual({
+      provider: MOCK_OPENAI_CONFIG.provider,
+      apiKey: 'next-key',
+      baseUrl: MOCK_OPENAI_CONFIG.baseUrl,
+      model: MOCK_OPENAI_CONFIG.model,
+    });
     expect(body.imageGen).toEqual(igConfig);
   });
 
-  it('does not throw when POST request fails silently', async () => {
-    globalThis.fetch = vi.fn().mockRejectedValueOnce(new Error('API unavailable'));
-
-    await expect(saveConfig(MOCK_OPENAI_CONFIG)).resolves.toBeUndefined();
-  });
-
-  it('overwrites previous config — latest value wins', async () => {
-    globalThis.fetch = vi.fn().mockResolvedValue({ ok: true } as Response);
-
-    await saveConfig(MOCK_OPENAI_CONFIG);
-    await saveConfig(MOCK_ANTHROPIC_CONFIG);
-
-    const stored = JSON.parse(localStorage.getItem(CONFIG_KEY) ?? 'null');
-    expect(stored?.provider).toBe('anthropic');
-  });
-
-  it('writes localStorage before awaiting fetch', async () => {
-    let localStorageWrittenBeforeFetch = false;
-    const originalSetItem = localStorage.setItem.bind(localStorage);
+  it('surfaces save failures to the caller', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      text: () => Promise.resolve('boom'),
+    } as unknown as Response);
 
-    globalThis.fetch = vi.fn().mockImplementationOnce(() => {
-      // By the time fetch is called, localStorage should already be written
-      localStorageWrittenBeforeFetch = localStorage.getItem(CONFIG_KEY) !== null;
-      return Promise.resolve({ ok: true } as Response);
+    await expect(saveConfig(MOCK_OPENAI_CONFIG)).resolves.toEqual({
+      ok: false,
+      error: 'Failed to save config (500): boom',
     });
-
-    vi.spyOn(localStorage, 'setItem').mockImplementation(originalSetItem);
-
-    await saveConfig(MOCK_OPENAI_CONFIG);
-
-    expect(localStorageWrittenBeforeFetch).toBe(true);
   });
 });
 
@@ -353,14 +266,15 @@ describe('chat()', () => {
       expect(result.toolCalls).toEqual([]);
     });
 
-    it('sets Authorization Bearer token header', async () => {
+    it('sends only proxy routing headers for OpenAI requests', async () => {
       const mockFetch = vi.fn().mockResolvedValueOnce(makeOpenAIResponse('ok'));
       globalThis.fetch = mockFetch;
 
       await chat(MOCK_MESSAGES, [], MOCK_OPENAI_CONFIG);
 
       const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
-      expect(headers['Authorization']).toBe('Bearer sk-test-key');
+      expect(headers['Authorization']).toBeUndefined();
+      expect(headers['X-LLM-Config-Scope']).toBe('llm');
     });
 
     it('uses v1/chat/completions when baseUrl has no version suffix', async () => {
@@ -446,6 +360,7 @@ describe('chat()', () => {
       expect(result.content).toBe('Local response');
       const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
       expect(headers['Authorization']).toBeUndefined();
+      expect(headers['X-LLM-Config-Scope']).toBe('llm');
       expect(headers['X-LLM-Target-URL']).toBe('http://athena:8081/v1/chat/completions');
     });
 
@@ -482,7 +397,7 @@ respond_to_user
   });
 
   describe('Anthropic provider', () => {
-    it('uses x-api-key and anthropic-version headers', async () => {
+    it('uses anthropic-version and proxy scope headers without exposing x-api-key', async () => {
       const mockFetch = vi.fn().mockResolvedValueOnce(makeAnthropicResponse('Anthropic response'));
       globalThis.fetch = mockFetch;
 
@@ -491,7 +406,8 @@ respond_to_user
       expect(result.content).toBe('Anthropic response');
       const headers = mockFetch.mock.calls[0][1].headers as Record<string, string>;
       expect(headers['anthropic-version']).toBe('2023-06-01');
-      expect(headers['x-api-key']).toBe('ant-test-key');
+      expect(headers['x-api-key']).toBeUndefined();
+      expect(headers['X-LLM-Config-Scope']).toBe('llm');
     });
 
     it('uses /messages when baseUrl already includes /v1', async () => {
diff --git a/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
new file mode 100644
index 0000000..f350576
--- /dev/null
+++ b/apps/webuiapps/src/lib/__tests__/viteConfig.test.ts
@@ -0,0 +1,209 @@
+/** Unit tests for Vite proxy/config helper functions. */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  normalizeServerConfig,
+  redactServerConfig,
+  inferProvider,
+  parseProxyTargetUrl,
+  isAllowedTarget,
+  selectServerApiKey,
+} from '../../../vite.config';
+
+const originalAllowLocalLlm = process.env.ALLOW_LOCAL_LLM;
+
+afterEach(() => {
+  if (originalAllowLocalLlm === undefined) {
+    delete process.env.ALLOW_LOCAL_LLM;
+  } else {
+    process.env.ALLOW_LOCAL_LLM = originalAllowLocalLlm;
+  }
+});
+
+describe('normalizeServerConfig()', () => {
+  it('returns null for null input', () => {
+    expect(normalizeServerConfig(null)).toBeNull();
+  });
+
+  it('returns null for undefined input', () => {
+    expect(normalizeServerConfig(undefined)).toBeNull();
+  });
+
+  it('returns null for an empty object', () => {
+    expect(normalizeServerConfig({})).toBeNull();
+  });
+
+  it('wraps legacy flat configs under llm', () => {
+    expect(
+      normalizeServerConfig({
+        provider: 'openai',
+        apiKey: 'sk-test',
+        baseUrl: 'https://api.openai.com',
+        model: 'gpt-4',
+      }),
+    ).toEqual({
+      llm: {
+        provider: 'openai',
+        apiKey: 'sk-test',
+        baseUrl: 'https://api.openai.com',
+        model: 'gpt-4',
+      },
+    });
+  });
+
+  it('keeps the structured llm/imageGen format', () => {
+    expect(
+      normalizeServerConfig({
+        llm: { provider: 'openai', apiKey: 'sk-llm', baseUrl: 'u', model: 'm' },
+        imageGen: { provider: 'openai', apiKey: 'sk-img', baseUrl: 'iu', model: 'im' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: 'sk-llm', baseUrl: 'u', model: 'm' },
+      imageGen: { provider: 'openai', apiKey: 'sk-img', baseUrl: 'iu', model: 'im' },
+    });
+  });
+});
+
+describe('redactServerConfig()', () => {
+  it('removes API key values while preserving hasApiKey flags', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', apiKey: 'sk-llm', baseUrl: 'u', model: 'm' },
+        imageGen: { provider: 'gemini', apiKey: 'sk-img', baseUrl: 'iu', model: 'im' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: true, baseUrl: 'u', model: 'm' },
+      imageGen: { provider: 'gemini', apiKey: '', hasApiKey: true, baseUrl: 'iu', model: 'im' },
+    });
+  });
+
+  it('sets hasApiKey=false when apiKey is an empty string', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', apiKey: '', baseUrl: 'u', model: 'm' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: false, baseUrl: 'u', model: 'm' },
+    });
+  });
+
+  it('sets hasApiKey=false when apiKey is missing entirely', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', baseUrl: 'u', model: 'm' } as any,
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: false, baseUrl: 'u', model: 'm' },
+    });
+  });
+
+  it('sets hasApiKey=false for whitespace-only apiKey', () => {
+    expect(
+      redactServerConfig({
+        llm: { provider: 'openai', apiKey: '   ', baseUrl: 'u', model: 'm' },
+      }),
+    ).toEqual({
+      llm: { provider: 'openai', apiKey: '', hasApiKey: false, baseUrl: 'u', model: 'm' },
+    });
+  });
+});
+
+describe('inferProvider()', () => {
+  it('honors supported manual overrides', () => {
+    expect(inferProvider('https://example.com/v1', 'openai')).toBe('openai');
+    expect(inferProvider('https://example.com/v1', 'gemini')).toBe('gemini');
+  });
+
+  it('returns unknown for unsupported manual overrides', () => {
+    expect(inferProvider('https://example.com/v1', 'custom-provider')).toBe('unknown');
+  });
+
+  it('infers providers from the target URL host', () => {
+    expect(inferProvider('https://api.anthropic.com/v1/messages')).toBe('anthropic');
+    expect(inferProvider('https://generativelanguage.googleapis.com/v1beta/models/test')).toBe(
+      'gemini',
+    );
+  });
+
+  it('returns unknown for malformed URLs', () => {
+    expect(inferProvider('not a url')).toBe('unknown');
+  });
+});
+
+describe('parseProxyTargetUrl()', () => {
+  it('parses valid HTTPS targets', () => {
+    expect(parseProxyTargetUrl('https://api.openai.com/v1')?.toString()).toBe(
+      'https://api.openai.com/v1',
+    );
+  });
+
+  it('parses valid HTTP localhost targets with explicit ports', () => {
+    expect(parseProxyTargetUrl('http://localhost:3000')?.toString()).toBe('http://localhost:3000/');
+  });
+
+  it('returns null for malformed URLs', () => {
+    expect(parseProxyTargetUrl('not a url')).toBeNull();
+  });
+
+  it('returns null for unsupported protocols', () => {
+    expect(parseProxyTargetUrl('file:///tmp/secret')).toBeNull();
+  });
+});
+
+describe('selectServerApiKey()', () => {
+  const config = {
+    llm: { apiKey: 'sk-llm' },
+    imageGen: { apiKey: 'sk-img' },
+  };
+
+  it('selects the key by explicit scope', () => {
+    expect(selectServerApiKey(config, 'llm', 'openai')).toBe('sk-llm');
+    expect(selectServerApiKey(config, 'imageGen', 'openai')).toBe('sk-img');
+  });
+
+  it('prefers the imageGen key for gemini when no scope is provided', () => {
+    expect(selectServerApiKey(config, undefined, 'gemini')).toBe('sk-img');
+  });
+});
+
+describe('isAllowedTarget()', () => {
+  it('allows known provider hosts', () => {
+    expect(isAllowedTarget(new URL('https://api.openai.com/v1/chat/completions'))).toBe(true);
+    expect(isAllowedTarget(new URL('https://api.anthropic.com/v1/messages'))).toBe(true);
+    expect(isAllowedTarget(new URL('https://api.deepseek.com/v1/chat/completions'))).toBe(true);
+    expect(isAllowedTarget(new URL('https://openrouter.ai/api/v1/chat/completions'))).toBe(true);
+    expect(
+      isAllowedTarget(new URL('https://generativelanguage.googleapis.com/v1beta/models')),
+    ).toBe(true);
+  });
+
+  it('rejects unknown hosts', () => {
+    expect(isAllowedTarget(new URL('https://evil.example.com/steal'))).toBe(false);
+    expect(isAllowedTarget(new URL('https://attacker.com/api'))).toBe(false);
+  });
+
+  it('rejects internal addresses by default', () => {
+    delete process.env.ALLOW_LOCAL_LLM;
+
+    expect(isAllowedTarget(new URL('http://localhost:8080/v1/chat/completions'))).toBe(false);
+    expect(isAllowedTarget(new URL('http://127.0.0.1:8080/v1/chat/completions'))).toBe(false);
+    expect(isAllowedTarget(new URL('http://192.168.1.1:8080/v1'))).toBe(false);
+  });
+
+  it('allows local hosts when ALLOW_LOCAL_LLM=true', () => {
+    process.env.ALLOW_LOCAL_LLM = 'true';
+
+    expect(isAllowedTarget(new URL('http://localhost:8080/v1/chat/completions'))).toBe(true);
+    expect(isAllowedTarget(new URL('http://127.0.0.1:8080/v1/chat/completions'))).toBe(true);
+  });
+
+  it('rejects private network hosts even when ALLOW_LOCAL_LLM=true', () => {
+    process.env.ALLOW_LOCAL_LLM = 'true';
+
+    expect(isAllowedTarget(new URL('http://192.168.1.1:8080/v1'))).toBe(false);
+  });
+
+  it('rejects plaintext HTTP for public provider hosts', () => {
+    expect(isAllowedTarget(new URL('http://api.openai.com/v1/chat/completions'))).toBe(false);
+  });
+});
diff --git a/apps/webuiapps/src/lib/configPersistence.ts b/apps/webuiapps/src/lib/configPersistence.ts
index fa8a0ab..67312ec 100644
--- a/apps/webuiapps/src/lib/configPersistence.ts
+++ b/apps/webuiapps/src/lib/configPersistence.ts
@@ -7,13 +7,24 @@
  */
 
 import type { LLMConfig } from './llmModels';
-import type { ImageGenConfig } from './imageGenClient';
+import type { LLMConfigUpdate } from './llmModels';
+import type { ImageGenConfig, ImageGenConfigUpdate } from './imageGenClient';
 
 export interface PersistedConfig {
   llm: LLMConfig;
   imageGen?: ImageGenConfig;
 }
 
+export interface PersistedConfigUpdate {
+  llm: LLMConfigUpdate;
+  imageGen?: ImageGenConfigUpdate | null;
+}
+
+export interface PersistedSaveResult {
+  ok: boolean;
+  error?: string;
+}
+
 const CONFIG_API = '/api/llm-config';
 
 /** Detect legacy flat LLMConfig (has "provider" at top level, no "llm" key). */
@@ -22,9 +33,9 @@ function isLegacyConfig(obj: unknown): obj is LLMConfig {
 }
 
 /**
- * Load the full persisted config from ~/.openroom/config.json via the dev-server API.
- * Handles legacy flat LLMConfig format for backward compatibility.
- * Returns null if the API is unavailable or the file doesn't exist.
+ * Load the client-safe persisted config from ~/.openroom/config.json via the
+ * dev-server API. API keys are redacted server-side and exposed only as
+ * hasApiKey booleans.
  */
 export async function loadPersistedConfig(): Promise<PersistedConfig | null> {
   try {
@@ -45,17 +56,30 @@ export async function loadPersistedConfig(): Promise<PersistedConfig | null> {
 }
 
 /**
- * Save the full config to ~/.openroom/config.json via the dev-server API.
- * Always writes the new { llm, imageGen? } format.
+ * Save config updates to ~/.openroom/config.json via the dev-server API.
+ * API keys may be omitted to preserve the existing server-side secret.
  */
-export async function savePersistedConfig(config: PersistedConfig): Promise<void> {
+export async function savePersistedConfig(
+  config: PersistedConfigUpdate,
+): Promise<PersistedSaveResult> {
   try {
-    await fetch(CONFIG_API, {
+    const res = await fetch(CONFIG_API, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(config),
     });
-  } catch {
-    // Silently ignore if API is not available
+    if (!res.ok) {
+      const detail = await res.text().catch(() => '');
+      return {
+        ok: false,
+        error: `Failed to save config (${res.status})${detail ? `: ${detail}` : ''}`,
+      };
+    }
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
   }
 }
diff --git a/apps/webuiapps/src/lib/imageGenClient.ts b/apps/webuiapps/src/lib/imageGenClient.ts
index 7ed04c5..bde06b1 100644
--- a/apps/webuiapps/src/lib/imageGenClient.ts
+++ b/apps/webuiapps/src/lib/imageGenClient.ts
@@ -8,11 +8,16 @@ export type ImageGenProvider = 'openai' | 'gemini';
 export interface ImageGenConfig {
   provider: ImageGenProvider;
   apiKey: string;
+  hasApiKey?: boolean;
   baseUrl: string;
   model: string;
   customHeaders?: string;
 }
 
+export type ImageGenConfigUpdate = Omit<ImageGenConfig, 'apiKey' | 'hasApiKey'> & {
+  apiKey?: string;
+};
+
 export interface ImageGenResult {
   base64: string;
   mimeType: string;
@@ -21,8 +26,6 @@ export interface ImageGenResult {
 import { logger } from './logger';
 import { loadPersistedConfig } from './configPersistence';
 
-const CONFIG_KEY = 'webuiapps-imagegen-config';
-
 const DEFAULT_CONFIGS: Record<ImageGenProvider, Omit<ImageGenConfig, 'apiKey'>> = {
   openai: {
     provider: 'openai',
@@ -43,37 +46,37 @@ export function getDefaultImageGenConfig(
 }
 
 /**
- * Load image gen config — priority: local file (~/.openroom/config.json) > localStorage.
- * Falls back gracefully if the dev server API is unavailable.
+ * Load image gen config — from server-side config only.
+ * Keys never touch localStorage.
  */
 export async function loadImageGenConfig(): Promise<ImageGenConfig | null> {
-  // 1. Try local file via dev-server API
   try {
     const persisted = await loadPersistedConfig();
     if (persisted?.imageGen) {
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(persisted.imageGen));
       return persisted.imageGen;
     }
   } catch {
     // API not available — fall through
   }
-
-  // 2. Fall back to localStorage
-  return loadImageGenConfigSync();
+  return null;
 }
 
-/** Synchronous read from localStorage cache. */
+/** Synchronous read — returns null since keys are server-side only. */
 export function loadImageGenConfigSync(): ImageGenConfig | null {
-  try {
-    const raw = localStorage.getItem(CONFIG_KEY);
-    return raw ? JSON.parse(raw) : null;
-  } catch {
-    return null;
-  }
+  return null;
+}
+
+export function saveImageGenConfig(_config: ImageGenConfig): void {
+  // No-op: config is saved server-side via saveConfig in llmClient.ts
 }
 
-export function saveImageGenConfig(config: ImageGenConfig): void {
-  localStorage.setItem(CONFIG_KEY, JSON.stringify(config));
+export function hasUsableImageGenConfig(
+  config: ImageGenConfig | null | undefined,
+): config is ImageGenConfig {
+  const baseUrl = typeof config?.baseUrl === 'string' ? config.baseUrl.trim() : '';
+  const model = typeof config?.model === 'string' ? config.model.trim() : '';
+  const hasApiKey = typeof config?.apiKey === 'string' ? config.apiKey.trim().length > 0 : false;
+  return !!baseUrl && !!model && (hasApiKey || !!config?.hasApiKey);
 }
 
 /** Parse custom headers, adding x-custom- prefix */
@@ -128,8 +131,9 @@ async function generateImageOpenAI(
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
-      Authorization: `Bearer ${config.apiKey}`,
+      'X-LLM-Config-Scope': 'imageGen',
       'X-LLM-Target-URL': targetUrl,
+      // API key injected server-side by the proxy
       ...parseCustomHeaders(config.customHeaders),
     },
     body: JSON.stringify(body),
@@ -163,8 +167,9 @@ async function generateImageGemini(
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
-      'x-goog-api-key': config.apiKey,
+      'X-LLM-Config-Scope': 'imageGen',
       'X-LLM-Target-URL': targetUrl,
+      // API key injected server-side by the proxy
       ...parseCustomHeaders(config.customHeaders),
     },
     body: JSON.stringify(body),
diff --git a/apps/webuiapps/src/lib/imageGenTools.ts b/apps/webuiapps/src/lib/imageGenTools.ts
index 78d06a9..719621a 100644
--- a/apps/webuiapps/src/lib/imageGenTools.ts
+++ b/apps/webuiapps/src/lib/imageGenTools.ts
@@ -5,7 +5,7 @@
 
 import * as idb from './diskStorage';
 import { getSessionPath } from './sessionPath';
-import { generateImage, type ImageGenConfig } from './imageGenClient';
+import { generateImage, hasUsableImageGenConfig, type ImageGenConfig } from './imageGenClient';
 
 const TOOL_NAME = 'generate_image';
 const IMAGES_DIR = 'generated-images';
@@ -70,7 +70,7 @@ export async function executeImageGenTool(
   params: Record<string, string>,
   config: ImageGenConfig | null,
 ): Promise<{ result: string; dataUrl?: string }> {
-  if (!config?.apiKey) {
+  if (!hasUsableImageGenConfig(config)) {
     return { result: 'error: image generation not configured, please set up in Settings' };
   }
 
diff --git a/apps/webuiapps/src/lib/llmClient.ts b/apps/webuiapps/src/lib/llmClient.ts
index 5c30e12..b385b54 100644
--- a/apps/webuiapps/src/lib/llmClient.ts
+++ b/apps/webuiapps/src/lib/llmClient.ts
@@ -3,55 +3,42 @@
  * Supports OpenAI-compatible / Anthropic-compatible formats
  */
 
-import type { LLMConfig } from './llmModels';
+import type { LLMConfig, LLMConfigUpdate } from './llmModels';
 
 import { logger } from './logger';
 import { loadPersistedConfig, savePersistedConfig } from './configPersistence';
 
-const CONFIG_KEY = 'webuiapps-llm-config';
-
 export async function loadConfig(): Promise<LLMConfig | null> {
+  // Load from server-side config only — keys never stored in localStorage
   try {
     const persisted = await loadPersistedConfig();
     if (persisted?.llm) {
-      localStorage.setItem(CONFIG_KEY, JSON.stringify(persisted.llm));
       return persisted.llm;
     }
   } catch {
     // API not available (production / network error)
   }
 
-  try {
-    const raw = localStorage.getItem(CONFIG_KEY);
-    return raw ? JSON.parse(raw) : null;
-  } catch {
-    return null;
-  }
+  return null;
 }
 
 export async function saveConfig(
-  config: LLMConfig,
-  imageGenConfig?: import('./imageGenClient').ImageGenConfig | null,
-): Promise<void> {
-  localStorage.setItem(CONFIG_KEY, JSON.stringify(config));
-
-  const persisted: import('./configPersistence').PersistedConfig = {
+  config: LLMConfigUpdate,
+  imageGenConfig?: import('./imageGenClient').ImageGenConfigUpdate | null,
+): Promise<{ ok: boolean; error?: string }> {
+  const persisted: import('./configPersistence').PersistedConfigUpdate = {
     llm: config,
   };
-  if (imageGenConfig) {
+  if (imageGenConfig !== undefined) {
     persisted.imageGen = imageGenConfig;
   }
 
-  await savePersistedConfig(persisted);
+  return savePersistedConfig(persisted);
 }
 
+/** Synchronous config read — returns null since keys are server-side only. */
 export function loadConfigSync(): LLMConfig | null {
-  try {
-    const raw = localStorage.getItem(CONFIG_KEY);
-    return raw ? JSON.parse(raw) : null;
-  } catch {
-    return null;
-  }
+  return null;
 }
 
 export interface ChatMessage {
@@ -191,6 +178,7 @@ export async function chat(
   messages: ChatMessage[],
   tools: ToolDef[],
   config: LLMConfig,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   logger.info(
     'LLM',
@@ -202,15 +190,16 @@ export async function chat(
     messages.length,
   );
   if (config.provider === 'anthropic' || config.provider === 'minimax') {
-    return chatAnthropic(messages, tools, config);
+    return chatAnthropic(messages, tools, config, signal);
   }
-  return chatOpenAI(messages, tools, config);
+  return chatOpenAI(messages, tools, config, signal);
 }
 
 async function chatOpenAI(
   messages: ChatMessage[],
   tools: ToolDef[],
   config: LLMConfig,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   const body: Record<string, unknown> = {
     model: config.model,
@@ -231,16 +220,16 @@ async function chatOpenAI(
   });
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
+    'X-LLM-Config-Scope': 'llm',
     'X-LLM-Target-URL': targetUrl,
+    // API key injected server-side by the proxy — never sent from browser
     ...parseCustomHeaders(config.customHeaders),
   };
-  if (config.apiKey.trim()) {
-    headers.Authorization = `Bearer ${config.apiKey}`;
-  }
   const res = await fetch('/api/llm-proxy', {
     method: 'POST',
     headers,
     body: JSON.stringify(body),
+    signal,
   });
 
   logger.info('LLM', 'Response status:', res.status);
@@ -277,6 +266,7 @@ async function chatAnthropic(
   messages: ChatMessage[],
   tools: ToolDef[],
   config: LLMConfig,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   const systemMsg = messages.find((m) => m.role === 'system')?.content || '';
   const nonSystemMessages = messages.filter((m) => m.role !== 'system');
@@ -343,16 +333,16 @@ async function chatAnthropic(
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     'anthropic-version': '2023-06-01',
+    'X-LLM-Config-Scope': 'llm',
     'X-LLM-Target-URL': targetUrl,
+    // API key injected server-side by the proxy — never sent from browser
     ...parseCustomHeaders(config.customHeaders),
   };
-  if (config.apiKey.trim()) {
-    headers['x-api-key'] = config.apiKey;
-  }
   const res = await fetch('/api/llm-proxy', {
     method: 'POST',
     headers,
     body: JSON.stringify(body),
+    signal,
   });
 
   logger.info('LLM', 'Anthropic Response status:', res.status);
diff --git a/apps/webuiapps/src/lib/llmModels.ts b/apps/webuiapps/src/lib/llmModels.ts
index 346907e..29bd04d 100644
--- a/apps/webuiapps/src/lib/llmModels.ts
+++ b/apps/webuiapps/src/lib/llmModels.ts
@@ -19,11 +19,16 @@ export interface ModelInfo {
 export interface LLMConfig {
   provider: LLMProvider;
   apiKey: string;
+  hasApiKey?: boolean;
   baseUrl: string;
   model: string;
   customHeaders?: string;
 }
 
+export type LLMConfigUpdate = Omit<LLMConfig, 'apiKey' | 'hasApiKey'> & {
+  apiKey?: string;
+};
+
 export interface ProviderModelConfig {
   displayName: string;
   baseUrl: string;
diff --git a/apps/webuiapps/src/pages/Album/album_cn/guide.md b/apps/webuiapps/src/pages/Album/album_cn/guide.md
index 2e469cf..42c58eb 100644
--- a/apps/webuiapps/src/pages/Album/album_cn/guide.md
+++ b/apps/webuiapps/src/pages/Album/album_cn/guide.md
@@ -21,11 +21,11 @@
 
 #### 图片文件 `{id}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 图片唯一标识，与文件名一致（不含 `.json` 后缀） |
-| src | string | 是 | 图片地址：data URL（如 `data:image/png;base64,...`）或 https URL |
-| createdAt | integer | 是 | 创建时间戳（毫秒） |
+| 字段      | 类型    | 必填 | 说明                                                             |
+| --------- | ------- | ---- | ---------------------------------------------------------------- |
+| id        | string  | 是   | 图片唯一标识，与文件名一致（不含 `.json` 后缀）                  |
+| src       | string  | 是   | 图片地址：data URL（如 `data:image/png;base64,...`）或 https URL |
+| createdAt | integer | 是   | 创建时间戳（毫秒）                                               |
 
 示例：
 
@@ -51,7 +51,8 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 在云端新增或删除图片文件后，下发 `REFRESH` Action，前端收到后重新执行 `initFromCloud()` 并刷新列表。
+Agent 在云端新增或删除图片文件后，下发 `REFRESH` Action，前端收到后重新执行 `initFromCloud()`
+并刷新列表。
 
 ### 用户操作
 
diff --git a/apps/webuiapps/src/pages/Album/album_en/guide.md b/apps/webuiapps/src/pages/Album/album_en/guide.md
index 66007bf..b5b8952 100644
--- a/apps/webuiapps/src/pages/Album/album_en/guide.md
+++ b/apps/webuiapps/src/pages/Album/album_en/guide.md
@@ -21,11 +21,11 @@ Stores metadata for all pre-stored images. Each image has a separate JSON file,
 
 #### Image File `{id}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique image identifier, matches the filename (without `.json` extension) |
-| src | string | Yes | Image URL: data URL (e.g., `data:image/png;base64,...`) or https URL |
-| createdAt | integer | Yes | Creation timestamp (milliseconds) |
+| Field     | Type    | Required | Description                                                               |
+| --------- | ------- | -------- | ------------------------------------------------------------------------- |
+| id        | string  | Yes      | Unique image identifier, matches the filename (without `.json` extension) |
+| src       | string  | Yes      | Image URL: data URL (e.g., `data:image/png;base64,...`) or https URL      |
+| createdAt | integer | Yes      | Creation timestamp (milliseconds)                                         |
 
 Example:
 
@@ -51,8 +51,10 @@ Or using an external link:
 
 ### Agent Operations (Agent → Frontend)
 
-After the Agent adds or deletes image files on the cloud, it dispatches the `REFRESH` Action. Upon receiving it, the frontend re-executes `initFromCloud()` and refreshes the list.
+After the Agent adds or deletes image files on the cloud, it dispatches the `REFRESH` Action. Upon
+receiving it, the frontend re-executes `initFromCloud()` and refreshes the list.
 
 ### User Operations
 
-The album is a read-only app. Users can only browse and click to view full-size images. No Actions are reported.
+The album is a read-only app. Users can only browse and click to view full-size images. No Actions
+are reported.
diff --git a/apps/webuiapps/src/pages/Chess/chess_cn/guide.md b/apps/webuiapps/src/pages/Chess/chess_cn/guide.md
index bf899b7..ea8c917 100644
--- a/apps/webuiapps/src/pages/Chess/chess_cn/guide.md
+++ b/apps/webuiapps/src/pages/Chess/chess_cn/guide.md
@@ -13,74 +13,126 @@
 
 存储当前棋局的完整状态，包括棋盘布局、当前回合、易位权限、过路兵目标、走法历史和游戏状态。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| board | (Piece \| null)[][] | 是 | 8x8 棋盘，索引 [0][0] 为 a8（黑方底线左上角），[7][7] 为 h1（白方底线右下角） |
-| currentTurn | string | 是 | 当前回合：`"w"` 白方 / `"b"` 黑方 |
-| castlingRights | CastlingRights | 是 | 易位权限 |
-| enPassantTarget | [number, number] \| null | 是 | 可执行过路兵的目标格（[row, col]），无则为 null |
-| halfMoveClock | number | 是 | 半步计数器（用于 50 步和棋规则） |
-| moveHistory | MoveRecord[] | 是 | 走法历史记录数组 |
-| gameStatus | string | 是 | 游戏状态：`"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"` |
-| winner | string \| null | 是 | 胜方：`"w"` / `"b"` / null |
-| gameId | string | 是 | 棋局唯一标识 |
-| lastMove | object \| null | 是 | 上一步走法，包含 `from: [row, col]` 和 `to: [row, col]`，无则为 null |
-| isAgentThinking | boolean | 是 | Agent 是否正在思考中。为 true 时前端锁定棋盘，禁止用户操作 |
+| 字段            | 类型                     | 必填 | 说明                                                                          |
+| --------------- | ------------------------ | ---- | ----------------------------------------------------------------------------- |
+| board           | (Piece \| null)[][]      | 是   | 8x8 棋盘，索引 [0][0] 为 a8（黑方底线左上角），[7][7] 为 h1（白方底线右下角） |
+| currentTurn     | string                   | 是   | 当前回合：`"w"` 白方 / `"b"` 黑方                                             |
+| castlingRights  | CastlingRights           | 是   | 易位权限                                                                      |
+| enPassantTarget | [number, number] \| null | 是   | 可执行过路兵的目标格（[row, col]），无则为 null                               |
+| halfMoveClock   | number                   | 是   | 半步计数器（用于 50 步和棋规则）                                              |
+| moveHistory     | MoveRecord[]             | 是   | 走法历史记录数组                                                              |
+| gameStatus      | string                   | 是   | 游戏状态：`"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"`  |
+| winner          | string \| null           | 是   | 胜方：`"w"` / `"b"` / null                                                    |
+| gameId          | string                   | 是   | 棋局唯一标识                                                                  |
+| lastMove        | object \| null           | 是   | 上一步走法，包含 `from: [row, col]` 和 `to: [row, col]`，无则为 null          |
+| isAgentThinking | boolean                  | 是   | Agent 是否正在思考中。为 true 时前端锁定棋盘，禁止用户操作                    |
 
 #### Piece 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| type | string | 是 | 棋子类型：`"K"` 王 / `"Q"` 后 / `"R"` 车 / `"B"` 象 / `"N"` 马 / `"P"` 兵 |
-| color | string | 是 | 棋子颜色：`"w"` 白 / `"b"` 黑 |
+| 字段  | 类型   | 必填 | 说明                                                                      |
+| ----- | ------ | ---- | ------------------------------------------------------------------------- |
+| type  | string | 是   | 棋子类型：`"K"` 王 / `"Q"` 后 / `"R"` 车 / `"B"` 象 / `"N"` 马 / `"P"` 兵 |
+| color | string | 是   | 棋子颜色：`"w"` 白 / `"b"` 黑                                             |
 
 #### CastlingRights 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| wK | boolean | 是 | 白方王翼（短）易位权限 |
-| wQ | boolean | 是 | 白方后翼（长）易位权限 |
-| bK | boolean | 是 | 黑方王翼（短）易位权限 |
-| bQ | boolean | 是 | 黑方后翼（长）易位权限 |
+| 字段 | 类型    | 必填 | 说明                   |
+| ---- | ------- | ---- | ---------------------- |
+| wK   | boolean | 是   | 白方王翼（短）易位权限 |
+| wQ   | boolean | 是   | 白方后翼（长）易位权限 |
+| bK   | boolean | 是   | 黑方王翼（短）易位权限 |
+| bQ   | boolean | 是   | 黑方后翼（长）易位权限 |
 
 #### MoveRecord 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| from | [number, number] | 是 | 起始位置 [row, col] |
-| to | [number, number] | 是 | 目标位置 [row, col] |
-| piece | Piece | 是 | 移动的棋子 |
-| captured | Piece \| null | 是 | 被吃掉的棋子（无则 null） |
-| promotion | string \| null | 是 | 升变棋子类型（如 `"Q"`），无则 null |
-| castling | string \| null | 是 | 易位类型：`"K"` 王翼 / `"Q"` 后翼 / null |
-| enPassant | boolean | 是 | 是否为过路兵吃子 |
+| 字段      | 类型             | 必填 | 说明                                     |
+| --------- | ---------------- | ---- | ---------------------------------------- |
+| from      | [number, number] | 是   | 起始位置 [row, col]                      |
+| to        | [number, number] | 是   | 目标位置 [row, col]                      |
+| piece     | Piece            | 是   | 移动的棋子                               |
+| captured  | Piece \| null    | 是   | 被吃掉的棋子（无则 null）                |
+| promotion | string \| null   | 是   | 升变棋子类型（如 `"Q"`），无则 null      |
+| castling  | string \| null   | 是   | 易位类型：`"K"` 王翼 / `"Q"` 后翼 / null |
+| enPassant | boolean          | 是   | 是否为过路兵吃子                         |
 
 示例：
 
 ```json
 {
   "board": [
-    [{"type":"R","color":"b"}, {"type":"N","color":"b"}, {"type":"B","color":"b"}, {"type":"Q","color":"b"}, {"type":"K","color":"b"}, {"type":"B","color":"b"}, {"type":"N","color":"b"}, {"type":"R","color":"b"}],
-    [{"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, null, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}],
+    [
+      { "type": "R", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "Q", "color": "b" },
+      { "type": "K", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "R", "color": "b" }
+    ],
+    [
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      null,
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" }
+    ],
     [null, null, null, null, null, null, null, null],
-    [null, null, null, null, {"type":"P","color":"b"}, null, null, null],
-    [null, null, null, null, {"type":"P","color":"w"}, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "b" }, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "w" }, null, null, null],
     [null, null, null, null, null, null, null, null],
-    [{"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, null, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}],
-    [{"type":"R","color":"w"}, {"type":"N","color":"w"}, {"type":"B","color":"w"}, {"type":"Q","color":"w"}, {"type":"K","color":"w"}, {"type":"B","color":"w"}, {"type":"N","color":"w"}, {"type":"R","color":"w"}]
+    [
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      null,
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" }
+    ],
+    [
+      { "type": "R", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "Q", "color": "w" },
+      { "type": "K", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "R", "color": "w" }
+    ]
   ],
   "currentTurn": "b",
-  "castlingRights": {"wK": true, "wQ": true, "bK": true, "bQ": true},
+  "castlingRights": { "wK": true, "wQ": true, "bK": true, "bQ": true },
   "enPassantTarget": null,
   "halfMoveClock": 0,
   "moveHistory": [
-    {"from": [6,4], "to": [4,4], "piece": {"type":"P","color":"w"}, "captured": null, "promotion": null, "castling": null, "enPassant": false},
-    {"from": [1,4], "to": [3,4], "piece": {"type":"P","color":"b"}, "captured": null, "promotion": null, "castling": null, "enPassant": false}
+    {
+      "from": [6, 4],
+      "to": [4, 4],
+      "piece": { "type": "P", "color": "w" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    },
+    {
+      "from": [1, 4],
+      "to": [3, 4],
+      "piece": { "type": "P", "color": "b" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    }
   ],
   "gameStatus": "playing",
   "winner": null,
   "gameId": "1706000000000-abc123def",
-  "lastMove": {"from": [1,4], "to": [3,4]},
+  "lastMove": { "from": [1, 4], "to": [3, 4] },
   "isAgentThinking": false
 }
 ```
@@ -90,6 +142,7 @@
 ### 回合制交互模型
 
 本应用采用**严格回合制**：
+
 - 用户执白，Agent 执黑
 - 用户走棋后，棋盘锁定（`isAgentThinking = true`），等待 Agent 响应
 - Agent 走棋后，棋盘解锁（`isAgentThinking = false`），轮到用户操作
@@ -99,22 +152,31 @@
 
 Agent 在云端直接修改 `/state.json`，将自己的走法应用到棋盘上，然后下发 Action 通知前端同步：
 
-- **AGENT_MOVE**：Agent 走了一步棋。Agent 在 state.json 中更新棋盘、将 `currentTurn` 改为 `"w"`、将 `isAgentThinking` 设为 `false`，并更新走法历史和游戏状态。前端收到后执行 `initFromCloud()` 读取最新状态并刷新 UI。
-- **SYNC_STATE**：Agent 修改了 state.json（如调整棋局状态），前端收到后执行 `initFromCloud()` 读取最新状态并刷新 UI。
-- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()` 读取并刷新 UI。
+- **AGENT_MOVE**：Agent 走了一步棋。Agent 在 state.json 中更新棋盘、将 `currentTurn` 改为 `"w"`、将
+  `isAgentThinking` 设为 `false`，并更新走法历史和游戏状态。前端收到后执行 `initFromCloud()`
+  读取最新状态并刷新 UI。
+- **SYNC_STATE**：Agent 修改了 state.json（如调整棋局状态），前端收到后执行 `initFromCloud()`
+  读取最新状态并刷新 UI。
+- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()`
+  读取并刷新 UI。
 
 ### 用户操作（前端 → Agent）
 
-- **USER_MOVE**：用户在界面上走了一步棋后，前端更新本地状态（`currentTurn` 改为 `"b"`、`isAgentThinking` 设为 `true`）并同步到云端，然后上报 `USER_MOVE` Action（附带 from、to 坐标和 gameId）。
-- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新棋局并同步到云端，然后上报 `NEW_GAME` Action（附带 gameId）。
+- **USER_MOVE**：用户在界面上走了一步棋后，前端更新本地状态（`currentTurn` 改为
+  `"b"`、`isAgentThinking` 设为 `true`）并同步到云端，然后上报 `USER_MOVE`
+  Action（附带 from、to 坐标和 gameId）。
+- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新棋局并同步到云端，然后上报 `NEW_GAME`
+  Action（附带 gameId）。
 
 ### 启动恢复
 
-前端启动时调用 `initFromCloud()` 从云端拉取 `/state.json`。若文件不存在，自动生成初始棋局并写入云端。
+前端启动时调用 `initFromCloud()` 从云端拉取
+`/state.json`。若文件不存在，自动生成初始棋局并写入云端。
 
 ### 坐标系统
 
 棋盘坐标使用 `[row, col]` 格式：
+
 - `[0, 0]` = a8（左上角，黑方底线）
 - `[0, 7]` = h8（右上角）
 - `[7, 0]` = a1（左下角，白方底线）
diff --git a/apps/webuiapps/src/pages/Chess/chess_en/guide.md b/apps/webuiapps/src/pages/Chess/chess_en/guide.md
index 04dd3ed..8f5399f 100644
--- a/apps/webuiapps/src/pages/Chess/chess_en/guide.md
+++ b/apps/webuiapps/src/pages/Chess/chess_en/guide.md
@@ -11,76 +11,129 @@
 
 ### State File `/state.json`
 
-Stores the complete state of the current game, including board layout, current turn, castling rights, en passant target, move history, and game status.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| board | (Piece \| null)[][] | Yes | 8x8 board, index [0][0] is a8 (top-left, black's back rank), [7][7] is h1 (bottom-right, white's back rank) |
-| currentTurn | string | Yes | Current turn: `"w"` white / `"b"` black |
-| castlingRights | CastlingRights | Yes | Castling rights |
-| enPassantTarget | [number, number] \| null | Yes | En passant target square ([row, col]), null if none |
-| halfMoveClock | number | Yes | Half-move counter (for 50-move draw rule) |
-| moveHistory | MoveRecord[] | Yes | Array of move history records |
-| gameStatus | string | Yes | Game status: `"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"` |
-| winner | string \| null | Yes | Winner: `"w"` / `"b"` / null |
-| gameId | string | Yes | Unique game identifier |
-| lastMove | object \| null | Yes | Last move with `from: [row, col]` and `to: [row, col]`, null if none |
-| isAgentThinking | boolean | Yes | Whether the Agent is currently thinking. When true, the frontend locks the board and prevents user interaction |
+Stores the complete state of the current game, including board layout, current turn, castling
+rights, en passant target, move history, and game status.
+
+| Field           | Type                     | Required | Description                                                                                                    |
+| --------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------- |
+| board           | (Piece \| null)[][]      | Yes      | 8x8 board, index [0][0] is a8 (top-left, black's back rank), [7][7] is h1 (bottom-right, white's back rank)    |
+| currentTurn     | string                   | Yes      | Current turn: `"w"` white / `"b"` black                                                                        |
+| castlingRights  | CastlingRights           | Yes      | Castling rights                                                                                                |
+| enPassantTarget | [number, number] \| null | Yes      | En passant target square ([row, col]), null if none                                                            |
+| halfMoveClock   | number                   | Yes      | Half-move counter (for 50-move draw rule)                                                                      |
+| moveHistory     | MoveRecord[]             | Yes      | Array of move history records                                                                                  |
+| gameStatus      | string                   | Yes      | Game status: `"playing"` / `"check"` / `"checkmate"` / `"stalemate"` / `"draw"`                                |
+| winner          | string \| null           | Yes      | Winner: `"w"` / `"b"` / null                                                                                   |
+| gameId          | string                   | Yes      | Unique game identifier                                                                                         |
+| lastMove        | object \| null           | Yes      | Last move with `from: [row, col]` and `to: [row, col]`, null if none                                           |
+| isAgentThinking | boolean                  | Yes      | Whether the Agent is currently thinking. When true, the frontend locks the board and prevents user interaction |
 
 #### Piece Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| type | string | Yes | Piece type: `"K"` King / `"Q"` Queen / `"R"` Rook / `"B"` Bishop / `"N"` Knight / `"P"` Pawn |
-| color | string | Yes | Piece color: `"w"` white / `"b"` black |
+| Field | Type   | Required | Description                                                                                  |
+| ----- | ------ | -------- | -------------------------------------------------------------------------------------------- |
+| type  | string | Yes      | Piece type: `"K"` King / `"Q"` Queen / `"R"` Rook / `"B"` Bishop / `"N"` Knight / `"P"` Pawn |
+| color | string | Yes      | Piece color: `"w"` white / `"b"` black                                                       |
 
 #### CastlingRights Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| wK | boolean | Yes | White kingside castling right |
-| wQ | boolean | Yes | White queenside castling right |
-| bK | boolean | Yes | Black kingside castling right |
-| bQ | boolean | Yes | Black queenside castling right |
+| Field | Type    | Required | Description                    |
+| ----- | ------- | -------- | ------------------------------ |
+| wK    | boolean | Yes      | White kingside castling right  |
+| wQ    | boolean | Yes      | White queenside castling right |
+| bK    | boolean | Yes      | Black kingside castling right  |
+| bQ    | boolean | Yes      | Black queenside castling right |
 
 #### MoveRecord Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| from | [number, number] | Yes | Source position [row, col] |
-| to | [number, number] | Yes | Target position [row, col] |
-| piece | Piece | Yes | The piece that moved |
-| captured | Piece \| null | Yes | The captured piece (null if none) |
-| promotion | string \| null | Yes | Promotion piece type (e.g., `"Q"`), null if none |
-| castling | string \| null | Yes | Castling type: `"K"` kingside / `"Q"` queenside / null |
-| enPassant | boolean | Yes | Whether this was an en passant capture |
+| Field     | Type             | Required | Description                                            |
+| --------- | ---------------- | -------- | ------------------------------------------------------ |
+| from      | [number, number] | Yes      | Source position [row, col]                             |
+| to        | [number, number] | Yes      | Target position [row, col]                             |
+| piece     | Piece            | Yes      | The piece that moved                                   |
+| captured  | Piece \| null    | Yes      | The captured piece (null if none)                      |
+| promotion | string \| null   | Yes      | Promotion piece type (e.g., `"Q"`), null if none       |
+| castling  | string \| null   | Yes      | Castling type: `"K"` kingside / `"Q"` queenside / null |
+| enPassant | boolean          | Yes      | Whether this was an en passant capture                 |
 
 Example:
 
 ```json
 {
   "board": [
-    [{"type":"R","color":"b"}, {"type":"N","color":"b"}, {"type":"B","color":"b"}, {"type":"Q","color":"b"}, {"type":"K","color":"b"}, {"type":"B","color":"b"}, {"type":"N","color":"b"}, {"type":"R","color":"b"}],
-    [{"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}, null, {"type":"P","color":"b"}, {"type":"P","color":"b"}, {"type":"P","color":"b"}],
+    [
+      { "type": "R", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "Q", "color": "b" },
+      { "type": "K", "color": "b" },
+      { "type": "B", "color": "b" },
+      { "type": "N", "color": "b" },
+      { "type": "R", "color": "b" }
+    ],
+    [
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      null,
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" },
+      { "type": "P", "color": "b" }
+    ],
     [null, null, null, null, null, null, null, null],
-    [null, null, null, null, {"type":"P","color":"b"}, null, null, null],
-    [null, null, null, null, {"type":"P","color":"w"}, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "b" }, null, null, null],
+    [null, null, null, null, { "type": "P", "color": "w" }, null, null, null],
     [null, null, null, null, null, null, null, null],
-    [{"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}, null, {"type":"P","color":"w"}, {"type":"P","color":"w"}, {"type":"P","color":"w"}],
-    [{"type":"R","color":"w"}, {"type":"N","color":"w"}, {"type":"B","color":"w"}, {"type":"Q","color":"w"}, {"type":"K","color":"w"}, {"type":"B","color":"w"}, {"type":"N","color":"w"}, {"type":"R","color":"w"}]
+    [
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      null,
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" },
+      { "type": "P", "color": "w" }
+    ],
+    [
+      { "type": "R", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "Q", "color": "w" },
+      { "type": "K", "color": "w" },
+      { "type": "B", "color": "w" },
+      { "type": "N", "color": "w" },
+      { "type": "R", "color": "w" }
+    ]
   ],
   "currentTurn": "b",
-  "castlingRights": {"wK": true, "wQ": true, "bK": true, "bQ": true},
+  "castlingRights": { "wK": true, "wQ": true, "bK": true, "bQ": true },
   "enPassantTarget": null,
   "halfMoveClock": 0,
   "moveHistory": [
-    {"from": [6,4], "to": [4,4], "piece": {"type":"P","color":"w"}, "captured": null, "promotion": null, "castling": null, "enPassant": false},
-    {"from": [1,4], "to": [3,4], "piece": {"type":"P","color":"b"}, "captured": null, "promotion": null, "castling": null, "enPassant": false}
+    {
+      "from": [6, 4],
+      "to": [4, 4],
+      "piece": { "type": "P", "color": "w" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    },
+    {
+      "from": [1, 4],
+      "to": [3, 4],
+      "piece": { "type": "P", "color": "b" },
+      "captured": null,
+      "promotion": null,
+      "castling": null,
+      "enPassant": false
+    }
   ],
   "gameStatus": "playing",
   "winner": null,
   "gameId": "1706000000000-abc123def",
-  "lastMove": {"from": [1,4], "to": [3,4]},
+  "lastMove": { "from": [1, 4], "to": [3, 4] },
   "isAgentThinking": false
 }
 ```
@@ -90,6 +143,7 @@ Example:
 ### Turn-Based Interaction Model
 
 This application uses a **strict turn-based** model:
+
 - The user plays white, the Agent plays black
 - After the user moves, the board locks (`isAgentThinking = true`), waiting for the Agent to respond
 - After the Agent moves, the board unlocks (`isAgentThinking = false`), and it's the user's turn
@@ -97,24 +151,34 @@ This application uses a **strict turn-based** model:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent directly modifies `/state.json` on the cloud, applying its move to the board, then dispatches an Action to notify the frontend to sync:
+The Agent directly modifies `/state.json` on the cloud, applying its move to the board, then
+dispatches an Action to notify the frontend to sync:
 
-- **AGENT_MOVE**: The Agent made a move. The Agent updates the board in state.json, sets `currentTurn` to `"w"`, sets `isAgentThinking` to `false`, and updates move history and game status. The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
-- **SYNC_STATE**: The Agent modified state.json (e.g., adjusting game state). The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
-- **NEW_GAME**: The Agent wrote a new game's state.json. The frontend executes `initFromCloud()` to read and refresh the UI.
+- **AGENT_MOVE**: The Agent made a move. The Agent updates the board in state.json, sets
+  `currentTurn` to `"w"`, sets `isAgentThinking` to `false`, and updates move history and game
+  status. The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
+- **SYNC_STATE**: The Agent modified state.json (e.g., adjusting game state). The frontend executes
+  `initFromCloud()` to read the latest state and refresh the UI.
+- **NEW_GAME**: The Agent wrote a new game's state.json. The frontend executes `initFromCloud()` to
+  read and refresh the UI.
 
 ### User Operations (Frontend → Agent)
 
-- **USER_MOVE**: After the user makes a move on the board, the frontend updates the local state (`currentTurn` to `"b"`, `isAgentThinking` to `true`) and syncs to the cloud, then reports the `USER_MOVE` Action (with from, to coordinates and gameId).
-- **NEW_GAME**: After the user clicks "New Game", the frontend generates a new game and syncs to the cloud, then reports the `NEW_GAME` Action (with gameId).
+- **USER_MOVE**: After the user makes a move on the board, the frontend updates the local state
+  (`currentTurn` to `"b"`, `isAgentThinking` to `true`) and syncs to the cloud, then reports the
+  `USER_MOVE` Action (with from, to coordinates and gameId).
+- **NEW_GAME**: After the user clicks "New Game", the frontend generates a new game and syncs to the
+  cloud, then reports the `NEW_GAME` Action (with gameId).
 
 ### Startup Recovery
 
-On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file does not exist, an initial game is automatically generated and written to the cloud.
+On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file
+does not exist, an initial game is automatically generated and written to the cloud.
 
 ### Coordinate System
 
 Board coordinates use `[row, col]` format:
+
 - `[0, 0]` = a8 (top-left, black's back rank)
 - `[0, 7]` = h8 (top-right)
 - `[7, 0]` = a1 (bottom-left, white's back rank)
diff --git a/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx b/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx
index f93b75d..3598d6f 100644
--- a/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx
+++ b/apps/webuiapps/src/pages/Chess/components/ChessBoard3D.tsx
@@ -1,4 +1,4 @@
-import React, { useEffect, useState, Suspense } from 'react';
+import React, { useEffect, useState, Suspense, useMemo } from 'react';
 import { Canvas, useThree } from '@react-three/fiber';
 import { OrbitControls, PerspectiveCamera, ContactShadows, Environment } from '@react-three/drei';
 import * as THREE from 'three';
@@ -282,6 +282,14 @@ const ChessBoard3D: React.FC<ChessBoard3DProps> = ({
   onSquareClick,
 }) => {
   const [pieces, setPieces] = useState<TrackedPiece[]>(() => extractPieces(board));
+  const [webglStatus, setWebglStatus] = useState<
+    { supported: true } | { supported: false; message: string; details: string[] } | null
+  >(null);
+
+  const statusLines = useMemo(() => {
+    if (!webglStatus || webglStatus.supported) return [] as string[];
+    return webglStatus.details;
+  }, [webglStatus]);
 
   // Full-board reconciliation piece tracking
   useEffect(() => {
@@ -369,6 +377,60 @@ const ChessBoard3D: React.FC<ChessBoard3DProps> = ({
     });
   }, [board, lastMove]);
 
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+      setWebglStatus({ supported: true });
+      return;
+    }
+
+    const canvas = document.createElement('canvas');
+    const details: string[] = [];
+
+    const tryContext = (kind: 'webgl2' | 'webgl') => {
+      try {
+        return canvas.getContext(kind, {
+          alpha: true,
+          antialias: true,
+          powerPreference: 'high-performance',
+          stencil: true,
+          depth: true,
+        } as WebGLContextAttributes);
+      } catch (error) {
+        details.push(
+          `${kind}: ${error instanceof Error ? error.message : String(error) || 'failed'}`,
+        );
+        return null;
+      }
+    };
+
+    const webgl2 = tryContext('webgl2');
+    const webgl = webgl2 ?? tryContext('webgl');
+
+    if (webgl2 || webgl) {
+      const gl = webgl2 ?? webgl;
+      try {
+        const dbg = gl?.getExtension?.('WEBGL_debug_renderer_info');
+        if (dbg) {
+          const renderer = gl.getParameter(dbg.UNMASKED_RENDERER_WEBGL);
+          const vendor = gl.getParameter(dbg.UNMASKED_VENDOR_WEBGL);
+          details.push(`renderer: ${String(renderer)}`);
+          details.push(`vendor: ${String(vendor)}`);
+        }
+      } catch {
+        // Best-effort diagnostics only.
+      }
+      setWebglStatus({ supported: true });
+      return;
+    }
+
+    details.push('No WebGL context could be created for @react-three/fiber Canvas.');
+    setWebglStatus({
+      supported: false,
+      message: '3D board unavailable in this browser/runtime',
+      details,
+    });
+  }, []);
+
   const selectedSquareKey = selectedPos ? `${selectedPos[0]}-${selectedPos[1]}` : null;
 
   const handleSquareClick = (r: number, c: number) => {
@@ -376,6 +438,52 @@ const ChessBoard3D: React.FC<ChessBoard3DProps> = ({
     onSquareClick(r, c);
   };
 
+  if (webglStatus && !webglStatus.supported) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          backgroundImage: `url(${chessBg})`,
+          backgroundSize: 'cover',
+          backgroundPosition: 'center',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: '24px',
+        }}
+      >
+        <div
+          style={{
+            maxWidth: '520px',
+            background: 'rgba(8, 8, 10, 0.82)',
+            border: '1px solid rgba(255,255,255,0.12)',
+            borderRadius: '16px',
+            padding: '20px 22px',
+            color: 'rgba(255,255,255,0.92)',
+            backdropFilter: 'blur(12px)',
+            boxShadow: '0 12px 40px rgba(0,0,0,0.45)',
+          }}
+        >
+          <div style={{ fontSize: '18px', fontWeight: 700, marginBottom: '8px' }}>
+            {webglStatus.message}
+          </div>
+          <div style={{ fontSize: '14px', lineHeight: 1.5, opacity: 0.85 }}>
+            The Chess app mounted correctly, but this environment failed WebGL initialization, so
+            the Three.js board cannot render here.
+          </div>
+          {statusLines.length > 0 && (
+            <div style={{ marginTop: '14px', fontSize: '12px', opacity: 0.72 }}>
+              {statusLines.map((line, idx) => (
+                <div key={`${idx}-${line}`}>{line}</div>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div
       style={{
diff --git a/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md b/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md
index 4444101..b02713c 100644
--- a/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md
+++ b/apps/webuiapps/src/pages/CyberNews/meta/meta_cn/guide.md
@@ -8,45 +8,45 @@
 
 ### Article（新闻文章）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | string | 唯一标识 |
-| title | string | 标题（大写） |
-| category | 'breaking' \| 'corporate' \| 'street' \| 'tech' | 分类 |
-| summary | string | 摘要 |
-| content | string | 正文 |
-| imageUrl | string | 配图URL（可为空） |
-| publishedAt | string | 发布时间 ISO 格式 |
+| 字段        | 类型                                            | 说明              |
+| ----------- | ----------------------------------------------- | ----------------- |
+| id          | string                                          | 唯一标识          |
+| title       | string                                          | 标题（大写）      |
+| category    | 'breaking' \| 'corporate' \| 'street' \| 'tech' | 分类              |
+| summary     | string                                          | 摘要              |
+| content     | string                                          | 正文              |
+| imageUrl    | string                                          | 配图URL（可为空） |
+| publishedAt | string                                          | 发布时间 ISO 格式 |
 
 ### Case（调查案件）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | string | 唯一标识 |
-| caseNumber | string | 案件编号 |
-| title | string | 案件标题 |
-| status | 'open' \| 'closed' \| 'classified' | 状态 |
-| clues | Clue[] | 线索列表 |
+| 字段       | 类型                               | 说明     |
+| ---------- | ---------------------------------- | -------- |
+| id         | string                             | 唯一标识 |
+| caseNumber | string                             | 案件编号 |
+| title      | string                             | 案件标题 |
+| status     | 'open' \| 'closed' \| 'classified' | 状态     |
+| clues      | Clue[]                             | 线索列表 |
 
 ### Clue（线索卡片）
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | string | 唯一标识 |
-| type | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | 类型 |
-| title | string | 标题 |
-| content | string | 内容 |
-| posX | number | 在调查板上的X坐标 |
-| posY | number | 在调查板上的Y坐标 |
+| 字段    | 类型                                                     | 说明              |
+| ------- | -------------------------------------------------------- | ----------------- |
+| id      | string                                                   | 唯一标识          |
+| type    | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | 类型              |
+| title   | string                                                   | 标题              |
+| content | string                                                   | 内容              |
+| posX    | number                                                   | 在调查板上的X坐标 |
+| posY    | number                                                   | 在调查板上的Y坐标 |
 
 ### AppState（应用状态）
 
-| 字段 | 类型 | 默认值 |
-|------|------|--------|
-| currentView | 'news' \| 'case-board' | 'news' |
-| selectedArticleId | string \| null | null |
-| selectedCaseId | string \| null | null |
-| newsFilter | ArticleCategory \| null | null |
+| 字段              | 类型                    | 默认值 |
+| ----------------- | ----------------------- | ------ |
+| currentView       | 'news' \| 'case-board'  | 'news' |
+| selectedArticleId | string \| null          | null   |
+| selectedCaseId    | string \| null          | null   |
+| newsFilter        | ArticleCategory \| null | null   |
 
 ## 存储结构
 
@@ -96,4 +96,5 @@
 
 ### 刷新类 Action
 
-发送 REFRESH_ARTICLES 或 REFRESH_CASES 强制 App 重新读取存储中的所有数据。可用 `navigateTo` 参数切换视图，`focusId` 参数自动选中某项。
+发送 REFRESH_ARTICLES 或 REFRESH_CASES 强制 App 重新读取存储中的所有数据。可用 `navigateTo`
+参数切换视图，`focusId` 参数自动选中某项。
diff --git a/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md b/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md
index d6b86ac..17436a0 100644
--- a/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md
+++ b/apps/webuiapps/src/pages/CyberNews/meta/meta_en/guide.md
@@ -2,42 +2,43 @@
 
 ## Overview
 
-A Cyberpunk 2077 Night City-style news terminal and investigation board app. Features news browsing, article reading, and a case investigation board with draggable clue cards.
+A Cyberpunk 2077 Night City-style news terminal and investigation board app. Features news browsing,
+article reading, and a case investigation board with draggable clue cards.
 
 ## Data Schemas
 
 ### Article
 
-| Field | Type | Description |
-|-------|------|-------------|
-| id | string | Unique identifier |
-| title | string | Title (uppercase) |
-| category | 'breaking' \| 'corporate' \| 'street' \| 'tech' | Category |
-| summary | string | Summary |
-| content | string | Full article body |
-| imageUrl | string | Cover image URL (can be empty) |
-| publishedAt | string | ISO date string |
+| Field       | Type                                            | Description                    |
+| ----------- | ----------------------------------------------- | ------------------------------ |
+| id          | string                                          | Unique identifier              |
+| title       | string                                          | Title (uppercase)              |
+| category    | 'breaking' \| 'corporate' \| 'street' \| 'tech' | Category                       |
+| summary     | string                                          | Summary                        |
+| content     | string                                          | Full article body              |
+| imageUrl    | string                                          | Cover image URL (can be empty) |
+| publishedAt | string                                          | ISO date string                |
 
 ### Case
 
-| Field | Type | Description |
-|-------|------|-------------|
-| id | string | Unique identifier |
-| caseNumber | string | Case number |
-| title | string | Case title |
-| status | 'open' \| 'closed' \| 'classified' | Status |
-| clues | Clue[] | List of clues |
+| Field      | Type                               | Description       |
+| ---------- | ---------------------------------- | ----------------- |
+| id         | string                             | Unique identifier |
+| caseNumber | string                             | Case number       |
+| title      | string                             | Case title        |
+| status     | 'open' \| 'closed' \| 'classified' | Status            |
+| clues      | Clue[]                             | List of clues     |
 
 ### Clue
 
-| Field | Type | Description |
-|-------|------|-------------|
-| id | string | Unique identifier |
-| type | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | Type |
-| title | string | Title |
-| content | string | Content |
-| posX | number | X position on board |
-| posY | number | Y position on board |
+| Field   | Type                                                     | Description         |
+| ------- | -------------------------------------------------------- | ------------------- |
+| id      | string                                                   | Unique identifier   |
+| type    | 'press' \| 'report' \| 'document' \| 'message' \| 'note' | Type                |
+| title   | string                                                   | Title               |
+| content | string                                                   | Content             |
+| posX    | number                                                   | X position on board |
+| posY    | number                                                   | Y position on board |
 
 ## Storage Structure
 
@@ -70,7 +71,10 @@ Step 2: Write full Article JSON (include imageUrl) to /articles/{articleId}.json
 Step 3: Send CREATE_ARTICLE action → App refreshes article list from storage
 ```
 
-**Creating news requires image generation**: Article's imageUrl must be set. Use whatever image-generation tool or capability is provided in the current environment to create a cyberpunk/Night City-style cover image first, then fill imageUrl with the returned URL before writing the article file.
+**Creating news requires image generation**: Article's imageUrl must be set. Use whatever
+image-generation tool or capability is provided in the current environment to create a
+cyberpunk/Night City-style cover image first, then fill imageUrl with the returned URL before
+writing the article file.
 
 Example flow for creating a case with clues:
 
@@ -79,12 +83,15 @@ Step 1: Write full Case JSON (including clues array) to /cases/{caseId}.json (pa
 Step 2: Send CREATE_CASE action → App refreshes case list from storage
 ```
 
-**Important**: The App does NOT create files from action params. It only reads existing files from storage. If you send CREATE_ARTICLE without writing the file first, the article will not appear.
+**Important**: The App does NOT create files from action params. It only reads existing files from
+storage. If you send CREATE_ARTICLE without writing the file first, the article will not appear.
 
 ### Operation Actions (VIEW / SELECT / FILTER / MOVE)
 
-Operation actions execute immediately — no file writing needed. Just send the action with the correct params.
+Operation actions execute immediately — no file writing needed. Just send the action with the
+correct params.
 
 ### Refresh Actions
 
-Send REFRESH_ARTICLES or REFRESH_CASES to force the App to re-read all data from storage. Use `navigateTo` param to switch views, `focusId` to auto-select an item.
+Send REFRESH_ARTICLES or REFRESH_CASES to force the App to re-read all data from storage. Use
+`navigateTo` param to switch views, `focusId` to auto-select an item.
diff --git a/apps/webuiapps/src/pages/Diary/diary_cn/guide.md b/apps/webuiapps/src/pages/Diary/diary_cn/guide.md
index e2def40..fe6ea9e 100644
--- a/apps/webuiapps/src/pages/Diary/diary_cn/guide.md
+++ b/apps/webuiapps/src/pages/Diary/diary_cn/guide.md
@@ -23,16 +23,16 @@
 
 #### 日记文件 `{entryId}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 日记唯一标识，与文件名一致（不含 `.json` 后缀） |
-| date | string | 是 | 日期，格式 YYYY-MM-DD（如 `2026-02-12`），每天最多一条 |
-| title | string | 是 | 日记标题，可为空字符串 |
-| content | string | 是 | 日记内容，支持 Markdown 和特殊标记语法，可为空字符串 |
-| mood | string | 否 | 心情标签：`happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
-| weather | string | 否 | 天气标签：`sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy` |
-| createdAt | integer | 是 | 创建时间戳（毫秒） |
-| updatedAt | integer | 是 | 最后更新时间戳（毫秒） |
+| 字段      | 类型    | 必填 | 说明                                                                                          |
+| --------- | ------- | ---- | --------------------------------------------------------------------------------------------- |
+| id        | string  | 是   | 日记唯一标识，与文件名一致（不含 `.json` 后缀）                                               |
+| date      | string  | 是   | 日期，格式 YYYY-MM-DD（如 `2026-02-12`），每天最多一条                                        |
+| title     | string  | 是   | 日记标题，可为空字符串                                                                        |
+| content   | string  | 是   | 日记内容，支持 Markdown 和特殊标记语法，可为空字符串                                          |
+| mood      | string  | 否   | 心情标签：`happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
+| weather   | string  | 否   | 天气标签：`sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy`                          |
+| createdAt | integer | 是   | 创建时间戳（毫秒）                                                                            |
+| updatedAt | integer | 是   | 最后更新时间戳（毫秒）                                                                        |
 
 示例：
 
@@ -53,19 +53,19 @@
 
 日记内容支持以下手绘效果标记，在预览模式下会渲染为 SVG 动画装饰：
 
-| 标记 | 效果 | 说明 |
-|------|------|------|
-| `{{strike}}文字{{/strike}}` | 手绘删除线 | 红色波浪线划过文字 |
-| `{{scribble}}文字{{/scribble}}` | 涂鸦划掉 | 双重深色删除线 |
-| `{{messy}}文字{{/messy}}` | 凌乱涂黑 | 锯齿形涂鸦遮盖文字 |
+| 标记                            | 效果       | 说明               |
+| ------------------------------- | ---------- | ------------------ |
+| `{{strike}}文字{{/strike}}`     | 手绘删除线 | 红色波浪线划过文字 |
+| `{{scribble}}文字{{/scribble}}` | 涂鸦划掉   | 双重深色删除线     |
+| `{{messy}}文字{{/messy}}`       | 凌乱涂黑   | 锯齿形涂鸦遮盖文字 |
 
 ### 状态文件 `/state.json`
 
 存储应用运行时状态，用于启动时恢复现场。前端在选中日期变更时自动保存并同步到云端。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| selectedDate | string \| null | 是 | 当前选中的日期（YYYY-MM-DD），无选中时为 null |
+| 字段         | 类型           | 必填 | 说明                                          |
+| ------------ | -------------- | ---- | --------------------------------------------- |
+| selectedDate | string \| null | 是   | 当前选中的日期（YYYY-MM-DD），无选中时为 null |
 
 示例：
 
@@ -79,8 +79,7 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。
-前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
+Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
 
 **Agent 创建日记**:
 
diff --git a/apps/webuiapps/src/pages/Diary/diary_en/guide.md b/apps/webuiapps/src/pages/Diary/diary_en/guide.md
index 432c8f5..7c12e44 100644
--- a/apps/webuiapps/src/pages/Diary/diary_en/guide.md
+++ b/apps/webuiapps/src/pages/Diary/diary_en/guide.md
@@ -16,23 +16,25 @@
 
 Stores all diary entry data. Each entry is saved as an independent JSON file, named by entry ID.
 
-- On startup, the frontend reads all files from this directory to render the calendar and diary content
+- On startup, the frontend reads all files from this directory to render the calendar and diary
+  content
 - When the Agent creates a diary entry, it writes a new file directly
-- When a user creates or edits a diary entry, the frontend creates/updates the file and syncs to the cloud
+- When a user creates or edits a diary entry, the frontend creates/updates the file and syncs to the
+  cloud
 - Each date can have at most one entry; entries are browsed by date via the calendar navigator
 
 #### Diary Entry File `{entryId}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique diary entry identifier, matches the filename (without `.json` extension) |
-| date | string | Yes | Date in YYYY-MM-DD format (e.g., `2026-02-12`), at most one entry per day |
-| title | string | Yes | Diary title, can be an empty string |
-| content | string | Yes | Diary content, supports Markdown and special markup syntax, can be an empty string |
-| mood | string | No | Mood tag: `happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
-| weather | string | No | Weather tag: `sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy` |
-| createdAt | integer | Yes | Creation timestamp (milliseconds) |
-| updatedAt | integer | Yes | Last updated timestamp (milliseconds) |
+| Field     | Type    | Required | Description                                                                                   |
+| --------- | ------- | -------- | --------------------------------------------------------------------------------------------- |
+| id        | string  | Yes      | Unique diary entry identifier, matches the filename (without `.json` extension)               |
+| date      | string  | Yes      | Date in YYYY-MM-DD format (e.g., `2026-02-12`), at most one entry per day                     |
+| title     | string  | Yes      | Diary title, can be an empty string                                                           |
+| content   | string  | Yes      | Diary content, supports Markdown and special markup syntax, can be an empty string            |
+| mood      | string  | No       | Mood tag: `happy` / `sad` / `neutral` / `excited` / `tired` / `anxious` / `hopeful` / `angry` |
+| weather   | string  | No       | Weather tag: `sunny` / `cloudy` / `rainy` / `snowy` / `windy` / `foggy`                       |
+| createdAt | integer | Yes      | Creation timestamp (milliseconds)                                                             |
+| updatedAt | integer | Yes      | Last updated timestamp (milliseconds)                                                         |
 
 Example:
 
@@ -51,21 +53,23 @@ Example:
 
 #### Special Content Markup
 
-Diary content supports the following hand-drawn effect markups. In preview mode, they render as animated SVG decorations:
+Diary content supports the following hand-drawn effect markups. In preview mode, they render as
+animated SVG decorations:
 
-| Markup | Effect | Description |
-|--------|--------|-------------|
-| `{{strike}}text{{/strike}}` | Hand-drawn strikethrough | Red wavy line through text |
-| `{{scribble}}text{{/scribble}}` | Scribble cross-out | Double dark strikethrough lines |
-| `{{messy}}text{{/messy}}` | Messy scribble | Zigzag scribble covering text |
+| Markup                          | Effect                   | Description                     |
+| ------------------------------- | ------------------------ | ------------------------------- |
+| `{{strike}}text{{/strike}}`     | Hand-drawn strikethrough | Red wavy line through text      |
+| `{{scribble}}text{{/scribble}}` | Scribble cross-out       | Double dark strikethrough lines |
+| `{{messy}}text{{/messy}}`       | Messy scribble           | Zigzag scribble covering text   |
 
 ### State File `/state.json`
 
-Stores the app's runtime state for restoring the session on startup. The frontend automatically saves and syncs to the cloud when the selected date changes.
+Stores the app's runtime state for restoring the session on startup. The frontend automatically
+saves and syncs to the cloud when the selected date changes.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| selectedDate | string \| null | Yes | Currently selected date (YYYY-MM-DD), null when nothing is selected |
+| Field        | Type           | Required | Description                                                         |
+| ------------ | -------------- | -------- | ------------------------------------------------------------------- |
+| selectedDate | string \| null | Yes      | Currently selected date (YYYY-MM-DD), null when nothing is selected |
 
 Example:
 
@@ -79,14 +83,18 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to notify the frontend to sync and refresh.
-After receiving an Action, the frontend only reads the latest data from the cloud — it does not create files locally.
+The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to
+notify the frontend to sync and refresh. After receiving an Action, the frontend only reads the
+latest data from the cloud — it does not create files locally.
 
 **Agent Creates a Diary Entry**:
 
-1. The Agent writes the file `/entries/{id}.json` on the cloud (containing the complete diary entry JSON, must include `date` field)
-2. The Agent dispatches the `CREATE_ENTRY` Action with `filePath` in params (e.g., `/entries/{id}.json`)
-3. The frontend reads the file from the cloud, updates the local file tree and calendar, and auto-navigates to that date
+1. The Agent writes the file `/entries/{id}.json` on the cloud (containing the complete diary entry
+   JSON, must include `date` field)
+2. The Agent dispatches the `CREATE_ENTRY` Action with `filePath` in params (e.g.,
+   `/entries/{id}.json`)
+3. The frontend reads the file from the cloud, updates the local file tree and calendar, and
+   auto-navigates to that date
 
 **Agent Updates a Diary Entry**:
 
@@ -112,12 +120,14 @@ After receiving an Action, the frontend only reads the latest data from the clou
 
 ### User Operations (Frontend → Cloud)
 
-User operations on the frontend are handled by the frontend code. The flow is: local operation → sync to cloud → report Action.
+User operations on the frontend are handled by the frontend code. The flow is: local operation →
+sync to cloud → report Action.
 
 **User Creates a Diary Entry**:
 
 1. User selects a date on the calendar and clicks the "Write one" button
-2. The frontend generates diary data (including `date` field) and writes it to the local file system at `/entries/{id}.json`
+2. The frontend generates diary data (including `date` field) and writes it to the local file system
+   at `/entries/{id}.json`
 3. The frontend syncs the file to the cloud
 4. The frontend reports the `CREATE_ENTRY` Action
 
@@ -136,7 +146,8 @@ User operations on the frontend are handled by the frontend code. The flow is: l
 **User Deletes a Diary Entry**:
 
 1. User clicks the delete button
-2. The frontend removes `/entries/{id}.json` from the local file system and syncs the deletion to the cloud
+2. The frontend removes `/entries/{id}.json` from the local file system and syncs the deletion to
+   the cloud
 3. The calendar marker for that date disappears
 4. The frontend reports the `DELETE_ENTRY` Action
 
@@ -144,5 +155,6 @@ User operations on the frontend are handled by the frontend code. The flow is: l
 
 1. The frontend calls `initFromCloud()` to fetch all files
 2. Reads all diary files under `/entries/`, builds a date index for each entry
-3. Reads `/state.json` to restore the previously selected date, and navigates the calendar to that month
+3. Reads `/state.json` to restore the previously selected date, and navigates the calendar to that
+   month
 4. If no saved state, defaults to today
diff --git a/apps/webuiapps/src/pages/Email/email_cn/guide.md b/apps/webuiapps/src/pages/Email/email_cn/guide.md
index 8ed3c77..77fbbb2 100644
--- a/apps/webuiapps/src/pages/Email/email_cn/guide.md
+++ b/apps/webuiapps/src/pages/Email/email_cn/guide.md
@@ -4,12 +4,14 @@
 
 本邮箱是**用户（User）的邮箱**，所有邮件的视角以用户为主。`folder` 字段的设置必须基于用户视角：
 
-- **`inbox`**：用户收到的邮件。Character 发送给用户的邮件应放在 `inbox`，因为对用户来说这是一封收到的邮件。
+- **`inbox`**：用户收到的邮件。Character 发送给用户的邮件应放在
+  `inbox`，因为对用户来说这是一封收到的邮件。
 - **`sent`**：用户发出的邮件。只有用户主动发送的邮件才应放在 `sent`。
 - **`drafts`**：用户的草稿。
 - **`trash`**：用户删除的邮件。
 
-> **常见错误**：Character 向用户发送邮件时，不应将 `folder` 设为 `sent`。虽然这封邮件是 Character "发送"的，但对于用户来说这是一封**收到的邮件**，应设为 `inbox`。
+> **常见错误**：Character 向用户发送邮件时，不应将 `folder` 设为 `sent`。虽然这封邮件是 Character
+> "发送"的，但对于用户来说这是一封**收到的邮件**，应设为 `inbox`。
 
 ## 文件夹结构
 
@@ -34,27 +36,27 @@
 
 #### 邮件文件 `{emailId}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 邮件唯一标识，与文件名一致（不含 `.json` 后缀） |
-| from | object | 是 | 发件人信息 |
-| from.name | string | 是 | 发件人姓名 |
-| from.address | string | 是 | 发件人邮箱地址 |
-| to | array | 是 | 收件人列表，每项为 EmailAddress 对象 |
-| cc | array | 是 | 抄送列表，每项为 EmailAddress 对象，可为空数组 |
-| subject | string | 是 | 邮件主题 |
-| content | string | 是 | 邮件正文内容 |
-| timestamp | integer | 是 | 发送/接收时间戳（毫秒） |
-| isRead | boolean | 是 | 是否已读 |
-| isStarred | boolean | 是 | 是否已加星标 |
-| folder | string | 是 | 所属文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
+| 字段         | 类型    | 必填 | 说明                                                   |
+| ------------ | ------- | ---- | ------------------------------------------------------ |
+| id           | string  | 是   | 邮件唯一标识，与文件名一致（不含 `.json` 后缀）        |
+| from         | object  | 是   | 发件人信息                                             |
+| from.name    | string  | 是   | 发件人姓名                                             |
+| from.address | string  | 是   | 发件人邮箱地址                                         |
+| to           | array   | 是   | 收件人列表，每项为 EmailAddress 对象                   |
+| cc           | array   | 是   | 抄送列表，每项为 EmailAddress 对象，可为空数组         |
+| subject      | string  | 是   | 邮件主题                                               |
+| content      | string  | 是   | 邮件正文内容                                           |
+| timestamp    | integer | 是   | 发送/接收时间戳（毫秒）                                |
+| isRead       | boolean | 是   | 是否已读                                               |
+| isStarred    | boolean | 是   | 是否已加星标                                           |
+| folder       | string  | 是   | 所属文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
 
 **EmailAddress 对象结构：**
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| name | string | 是 | 姓名 |
-| address | string | 是 | 邮箱地址 |
+| 字段    | 类型   | 必填 | 说明     |
+| ------- | ------ | ---- | -------- |
+| name    | string | 是   | 姓名     |
+| address | string | 是   | 邮箱地址 |
 
 示例：
 
@@ -85,10 +87,10 @@
 
 存储应用运行时状态，用于启动时恢复现场。前端在状态变更时自动保存并同步到云端。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| selectedEmailId | string\|null | 否 | 当前选中的邮件 ID，未选中时为 null |
-| currentFolder | string | 是 | 当前所在文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
+| 字段            | 类型         | 必填 | 说明                                                       |
+| --------------- | ------------ | ---- | ---------------------------------------------------------- |
+| selectedEmailId | string\|null | 否   | 当前选中的邮件 ID，未选中时为 null                         |
+| currentFolder   | string       | 是   | 当前所在文件夹，可选值：`inbox`、`sent`、`drafts`、`trash` |
 
 示例：
 
@@ -103,8 +105,7 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 负责在云端完成邮件文件的写入/删除，完成后通过下发 Action 通知前端同步刷新。
-前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
+Agent 负责在云端完成邮件文件的写入/删除，完成后通过下发 Action 通知前端同步刷新。前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
 
 **Agent 写邮件**:
 
diff --git a/apps/webuiapps/src/pages/Email/email_en/guide.md b/apps/webuiapps/src/pages/Email/email_en/guide.md
index 3d4cad4..01e177a 100644
--- a/apps/webuiapps/src/pages/Email/email_en/guide.md
+++ b/apps/webuiapps/src/pages/Email/email_en/guide.md
@@ -2,14 +2,19 @@
 
 ## Important: Mailbox Ownership
 
-This mailbox belongs to the **User**. All emails are viewed from the User's perspective. The `folder` field must be set accordingly:
+This mailbox belongs to the **User**. All emails are viewed from the User's perspective. The
+`folder` field must be set accordingly:
 
-- **`inbox`**: Emails received by the User. Emails sent by a Character to the User should be placed in `inbox`, because from the User's perspective, it is a received email.
-- **`sent`**: Emails sent by the User. Only emails actively sent by the User should be placed in `sent`.
+- **`inbox`**: Emails received by the User. Emails sent by a Character to the User should be placed
+  in `inbox`, because from the User's perspective, it is a received email.
+- **`sent`**: Emails sent by the User. Only emails actively sent by the User should be placed in
+  `sent`.
 - **`drafts`**: The User's drafts.
 - **`trash`**: Emails deleted by the User.
 
-> **Common Mistake**: When a Character sends an email to the User, do NOT set `folder` to `sent`. Although the Character "sent" the email, from the User's perspective it is a **received email** and should be set to `inbox`.
+> **Common Mistake**: When a Character sends an email to the User, do NOT set `folder` to `sent`.
+> Although the Character "sent" the email, from the User's perspective it is a **received email**
+> and should be set to `inbox`.
 
 ## Folder Structure
 
@@ -34,27 +39,27 @@ Stores all email data. Each email is saved as an independent JSON file, named by
 
 #### Email File `{emailId}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique email identifier, matches the filename (without `.json` extension) |
-| from | object | Yes | Sender information |
-| from.name | string | Yes | Sender name |
-| from.address | string | Yes | Sender email address |
-| to | array | Yes | Recipient list, each item is an EmailAddress object |
-| cc | array | Yes | CC list, each item is an EmailAddress object, can be an empty array |
-| subject | string | Yes | Email subject |
-| content | string | Yes | Email body content |
-| timestamp | integer | Yes | Send/receive timestamp (milliseconds) |
-| isRead | boolean | Yes | Whether the email has been read |
-| isStarred | boolean | Yes | Whether the email is starred |
-| folder | string | Yes | Folder name, one of: `inbox`, `sent`, `drafts`, `trash` |
+| Field        | Type    | Required | Description                                                               |
+| ------------ | ------- | -------- | ------------------------------------------------------------------------- |
+| id           | string  | Yes      | Unique email identifier, matches the filename (without `.json` extension) |
+| from         | object  | Yes      | Sender information                                                        |
+| from.name    | string  | Yes      | Sender name                                                               |
+| from.address | string  | Yes      | Sender email address                                                      |
+| to           | array   | Yes      | Recipient list, each item is an EmailAddress object                       |
+| cc           | array   | Yes      | CC list, each item is an EmailAddress object, can be an empty array       |
+| subject      | string  | Yes      | Email subject                                                             |
+| content      | string  | Yes      | Email body content                                                        |
+| timestamp    | integer | Yes      | Send/receive timestamp (milliseconds)                                     |
+| isRead       | boolean | Yes      | Whether the email has been read                                           |
+| isStarred    | boolean | Yes      | Whether the email is starred                                              |
+| folder       | string  | Yes      | Folder name, one of: `inbox`, `sent`, `drafts`, `trash`                   |
 
 **EmailAddress Object Structure:**
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| name | string | Yes | Name |
-| address | string | Yes | Email address |
+| Field   | Type   | Required | Description   |
+| ------- | ------ | -------- | ------------- |
+| name    | string | Yes      | Name          |
+| address | string | Yes      | Email address |
 
 Example:
 
@@ -83,12 +88,13 @@ Example:
 
 ### State File `/state.json`
 
-Stores the app's runtime state for restoring the session on startup. The frontend automatically saves and syncs to the cloud when state changes.
+Stores the app's runtime state for restoring the session on startup. The frontend automatically
+saves and syncs to the cloud when state changes.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| selectedEmailId | string\|null | No | Currently selected email ID, null when none is selected |
-| currentFolder | string | Yes | Current folder, one of: `inbox`, `sent`, `drafts`, `trash` |
+| Field           | Type         | Required | Description                                                |
+| --------------- | ------------ | -------- | ---------------------------------------------------------- |
+| selectedEmailId | string\|null | No       | Currently selected email ID, null when none is selected    |
+| currentFolder   | string       | Yes      | Current folder, one of: `inbox`, `sent`, `drafts`, `trash` |
 
 Example:
 
@@ -103,13 +109,16 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent completes email file writes/deletions on the cloud, then dispatches Actions to notify the frontend to sync and refresh.
-After receiving an Action, the frontend only reads the latest data from the cloud — it does not create files locally.
+The Agent completes email file writes/deletions on the cloud, then dispatches Actions to notify the
+frontend to sync and refresh. After receiving an Action, the frontend only reads the latest data
+from the cloud — it does not create files locally.
 
 **Agent Composes an Email**:
 
-1. The Agent writes the email file `/emails/{id}.json` on the cloud (containing the complete email JSON)
-2. The Agent dispatches the `COMPOSE_EMAIL` Action with `filePath` in params (e.g., `/emails/{id}.json`)
+1. The Agent writes the email file `/emails/{id}.json` on the cloud (containing the complete email
+   JSON)
+2. The Agent dispatches the `COMPOSE_EMAIL` Action with `filePath` in params (e.g.,
+   `/emails/{id}.json`)
 3. The frontend reads the file from the cloud, updates the local file tree and UI
 
 **Agent Deletes an Email**:
@@ -126,7 +135,8 @@ After receiving an Action, the frontend only reads the latest data from the clou
 
 ### User Operations (Frontend → Cloud)
 
-User operations on the frontend are in read-only mode — composing, replying, and sending emails are not available. The operations users can perform are:
+User operations on the frontend are in read-only mode — composing, replying, and sending emails are
+not available. The operations users can perform are:
 
 **User Reads an Email**:
 
diff --git a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md
index 74ce404..880be32 100644
--- a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md
+++ b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_cn/guide.md
@@ -19,22 +19,22 @@
 
 #### 档案文件 `{id}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 档案唯一标识 |
-| title | string | 是 | 档案标题 |
-| description | string | 是 | 档案描述摘要 |
-| content | string | 是 | 档案正文内容 |
-| type | string | 是 | 档案类型：`video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
-| category | string | 是 | 所属分类：`identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other` |
-| impact | string | 是 | 影响类型：`vindicate`（正面）/ `expose`（负面）/ `neutral`（中性）/ `mixed`（复合） |
-| source | string | 是 | 档案来源 |
-| timestamp | number | 是 | 档案时间戳（Unix 毫秒） |
-| credibility | number | 是 | 可信度（0-100） |
-| importance | number | 是 | 重要性（0-100） |
-| tags | string[] | 是 | 标签数组 |
-| vindicateText | string | 否 | 正面影响说明 |
-| exposeText | string | 否 | 负面影响说明 |
+| 字段          | 类型     | 必填 | 说明                                                                                                                                         |
+| ------------- | -------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| id            | string   | 是   | 档案唯一标识                                                                                                                                 |
+| title         | string   | 是   | 档案标题                                                                                                                                     |
+| description   | string   | 是   | 档案描述摘要                                                                                                                                 |
+| content       | string   | 是   | 档案正文内容                                                                                                                                 |
+| type          | string   | 是   | 档案类型：`video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
+| category      | string   | 是   | 所属分类：`identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other`                                                   |
+| impact        | string   | 是   | 影响类型：`vindicate`（正面）/ `expose`（负面）/ `neutral`（中性）/ `mixed`（复合）                                                          |
+| source        | string   | 是   | 档案来源                                                                                                                                     |
+| timestamp     | number   | 是   | 档案时间戳（Unix 毫秒）                                                                                                                      |
+| credibility   | number   | 是   | 可信度（0-100）                                                                                                                              |
+| importance    | number   | 是   | 重要性（0-100）                                                                                                                              |
+| tags          | string[] | 是   | 标签数组                                                                                                                                     |
+| vindicateText | string   | 否   | 正面影响说明                                                                                                                                 |
+| exposeText    | string   | 否   | 负面影响说明                                                                                                                                 |
 
 示例：
 
@@ -78,4 +78,5 @@
 
 ### 启动恢复
 
-前端启动时调用 `initFromCloud()` 从云端拉取 `/files/` 目录下的所有档案文件。若目录为空，则显示空状态。
+前端启动时调用 `initFromCloud()` 从云端拉取 `/files/`
+目录下的所有档案文件。若目录为空，则显示空状态。
diff --git a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md
index 9f03932..bfdc534 100644
--- a/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md
+++ b/apps/webuiapps/src/pages/EvidenceVault/evidencevault_en/guide.md
@@ -13,28 +13,29 @@
 
 ### Evidence File Collection `/files/`
 
-Stores all evidence files, each representing a single evidence/archive record. Data is static and read-only, pre-stored on the cloud.
+Stores all evidence files, each representing a single evidence/archive record. Data is static and
+read-only, pre-stored on the cloud.
 
 File naming convention: `{id}.json`, where `id` is a globally unique identifier.
 
 #### Evidence File `{id}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique evidence identifier |
-| title | string | Yes | Evidence title |
-| description | string | Yes | Evidence summary |
-| content | string | Yes | Evidence body content |
-| type | string | Yes | Evidence type: `video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
-| category | string | Yes | Category: `identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other` |
-| impact | string | Yes | Impact type: `vindicate` (positive) / `expose` (negative) / `neutral` / `mixed` |
-| source | string | Yes | Evidence source |
-| timestamp | number | Yes | Timestamp (Unix milliseconds) |
-| credibility | number | Yes | Credibility score (0-100) |
-| importance | number | Yes | Importance score (0-100) |
-| tags | string[] | Yes | Tag array |
-| vindicateText | string | No | Positive impact description |
-| exposeText | string | No | Negative impact description |
+| Field         | Type     | Required | Description                                                                                                                                       |
+| ------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id            | string   | Yes      | Unique evidence identifier                                                                                                                        |
+| title         | string   | Yes      | Evidence title                                                                                                                                    |
+| description   | string   | Yes      | Evidence summary                                                                                                                                  |
+| content       | string   | Yes      | Evidence body content                                                                                                                             |
+| type          | string   | Yes      | Evidence type: `video` / `log` / `transaction` / `document` / `image` / `audio` / `chat` / `email` / `contract` / `report` / `trace` / `relation` |
+| category      | string   | Yes      | Category: `identity` / `family` / `money` / `reputation` / `incident` / `secret` / `other`                                                        |
+| impact        | string   | Yes      | Impact type: `vindicate` (positive) / `expose` (negative) / `neutral` / `mixed`                                                                   |
+| source        | string   | Yes      | Evidence source                                                                                                                                   |
+| timestamp     | number   | Yes      | Timestamp (Unix milliseconds)                                                                                                                     |
+| credibility   | number   | Yes      | Credibility score (0-100)                                                                                                                         |
+| importance    | number   | Yes      | Importance score (0-100)                                                                                                                          |
+| tags          | string[] | Yes      | Tag array                                                                                                                                         |
+| vindicateText | string   | No       | Positive impact description                                                                                                                       |
+| exposeText    | string   | No       | Negative impact description                                                                                                                       |
 
 Example:
 
@@ -78,4 +79,5 @@ Users can only perform the following read-only operations (pure frontend, no clo
 
 ### Startup Recovery
 
-On startup, the frontend calls `initFromCloud()` to pull all evidence files from the `/files/` directory on the cloud. If the directory is empty, an empty state is displayed.
+On startup, the frontend calls `initFromCloud()` to pull all evidence files from the `/files/`
+directory on the cloud. If the directory is empty, an empty state is displayed.
diff --git a/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md b/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md
index a20e0ab..0f4911d 100644
--- a/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md
+++ b/apps/webuiapps/src/pages/FreeCell/freecell_cn/guide.md
@@ -13,21 +13,21 @@
 
 存储当前牌局的完整状态，包括 8 列牌阵、4 个可用单元格、4 个基础牌堆、步数和游戏状态。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| columns | Card[][] | 是 | 8 列牌阵，每列为 Card 数组，索引 0-7 |
-| freeCells | (Card \| null)[] | 是 | 4 个可用单元格，null 表示空位 |
-| foundations | Record<Suit, Card[]> | 是 | 4 个基础牌堆，按花色分组（hearts/diamonds/clubs/spades），从 A 到 K 顺序堆叠 |
-| moveCount | number | 是 | 当前步数 |
-| gameStatus | string | 是 | 游戏状态：`"playing"` 或 `"won"` |
-| gameId | string | 是 | 牌局唯一标识 |
+| 字段        | 类型                 | 必填 | 说明                                                                         |
+| ----------- | -------------------- | ---- | ---------------------------------------------------------------------------- |
+| columns     | Card[][]             | 是   | 8 列牌阵，每列为 Card 数组，索引 0-7                                         |
+| freeCells   | (Card \| null)[]     | 是   | 4 个可用单元格，null 表示空位                                                |
+| foundations | Record<Suit, Card[]> | 是   | 4 个基础牌堆，按花色分组（hearts/diamonds/clubs/spades），从 A 到 K 顺序堆叠 |
+| moveCount   | number               | 是   | 当前步数                                                                     |
+| gameStatus  | string               | 是   | 游戏状态：`"playing"` 或 `"won"`                                             |
+| gameId      | string               | 是   | 牌局唯一标识                                                                 |
 
 #### Card 结构
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| suit | string | 是 | 花色：`"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
-| rank | number | 是 | 点数：1=A, 2-10, 11=J, 12=Q, 13=K |
+| 字段 | 类型   | 必填 | 说明                                                     |
+| ---- | ------ | ---- | -------------------------------------------------------- |
+| suit | string | 是   | 花色：`"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
+| rank | number | 是   | 点数：1=A, 2-10, 11=J, 12=Q, 13=K                        |
 
 示例：
 
@@ -58,14 +58,19 @@
 
 Agent 可以直接写入 `/state.json` 来设置任意合法牌局状态，然后下发以下 Action 通知前端同步：
 
-- **SYNC_STATE**：Agent 修改了 state.json（如代替用户走棋），前端收到后执行 `initFromCloud()` 读取最新状态并刷新 UI。
-- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()` 读取并刷新 UI。
+- **SYNC_STATE**：Agent 修改了 state.json（如代替用户走棋），前端收到后执行 `initFromCloud()`
+  读取最新状态并刷新 UI。
+- **NEW_GAME**：Agent 写入了一局新游戏的 state.json，前端收到后执行 `initFromCloud()`
+  读取并刷新 UI。
 
 ### 用户操作（前端 -> Agent）
 
-- **MOVE_CARD**：用户在界面上移动一张或多张牌后，前端更新本地状态并同步到云端，然后上报 `MOVE_CARD` Action（附带 gameId 和 moveCount）。
-- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新牌局并同步到云端，然后上报 `NEW_GAME` Action（附带 gameId）。
+- **MOVE_CARD**：用户在界面上移动一张或多张牌后，前端更新本地状态并同步到云端，然后上报 `MOVE_CARD`
+  Action（附带 gameId 和 moveCount）。
+- **NEW_GAME**：用户点击"新游戏"按钮后，前端生成新牌局并同步到云端，然后上报 `NEW_GAME`
+  Action（附带 gameId）。
 
 ### 启动恢复
 
-前端启动时调用 `initFromCloud()` 从云端拉取 `/state.json`。若文件不存在，自动生成一局新游戏并写入云端。
+前端启动时调用 `initFromCloud()` 从云端拉取
+`/state.json`。若文件不存在，自动生成一局新游戏并写入云端。
diff --git a/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md b/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md
index 9c66ec2..b35f98c 100644
--- a/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md
+++ b/apps/webuiapps/src/pages/FreeCell/freecell_en/guide.md
@@ -11,23 +11,24 @@
 
 ### State File `/state.json`
 
-Stores the complete state of the current game, including 8 tableau columns, 4 free cells, 4 foundation piles, move count, and game status.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| columns | Card[][] | Yes | 8 tableau columns, each is a Card array, indexed 0-7 |
-| freeCells | (Card \| null)[] | Yes | 4 free cells, null indicates an empty slot |
-| foundations | Record<Suit, Card[]> | Yes | 4 foundation piles, grouped by suit (hearts/diamonds/clubs/spades), stacked in order from A to K |
-| moveCount | number | Yes | Current move count |
-| gameStatus | string | Yes | Game status: `"playing"` or `"won"` |
-| gameId | string | Yes | Unique game identifier |
+Stores the complete state of the current game, including 8 tableau columns, 4 free cells, 4
+foundation piles, move count, and game status.
+
+| Field       | Type                 | Required | Description                                                                                      |
+| ----------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| columns     | Card[][]             | Yes      | 8 tableau columns, each is a Card array, indexed 0-7                                             |
+| freeCells   | (Card \| null)[]     | Yes      | 4 free cells, null indicates an empty slot                                                       |
+| foundations | Record<Suit, Card[]> | Yes      | 4 foundation piles, grouped by suit (hearts/diamonds/clubs/spades), stacked in order from A to K |
+| moveCount   | number               | Yes      | Current move count                                                                               |
+| gameStatus  | string               | Yes      | Game status: `"playing"` or `"won"`                                                              |
+| gameId      | string               | Yes      | Unique game identifier                                                                           |
 
 #### Card Structure
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| suit | string | Yes | Suit: `"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
-| rank | number | Yes | Rank: 1=A, 2-10, 11=J, 12=Q, 13=K |
+| Field | Type   | Required | Description                                              |
+| ----- | ------ | -------- | -------------------------------------------------------- |
+| suit  | string | Yes      | Suit: `"hearts"` / `"diamonds"` / `"clubs"` / `"spades"` |
+| rank  | number | Yes      | Rank: 1=A, 2-10, 11=J, 12=Q, 13=K                        |
 
 Example:
 
@@ -56,16 +57,22 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent can directly write to `/state.json` to set any valid game state, then dispatch the following Actions to notify the frontend to sync:
+The Agent can directly write to `/state.json` to set any valid game state, then dispatch the
+following Actions to notify the frontend to sync:
 
-- **SYNC_STATE**: The Agent has modified state.json (e.g., making moves on behalf of the user). The frontend executes `initFromCloud()` to read the latest state and refresh the UI.
-- **NEW_GAME**: The Agent has written a new game's state.json. The frontend executes `initFromCloud()` to read and refresh the UI.
+- **SYNC_STATE**: The Agent has modified state.json (e.g., making moves on behalf of the user). The
+  frontend executes `initFromCloud()` to read the latest state and refresh the UI.
+- **NEW_GAME**: The Agent has written a new game's state.json. The frontend executes
+  `initFromCloud()` to read and refresh the UI.
 
 ### User Operations (Frontend → Agent)
 
-- **MOVE_CARD**: After the user moves one or more cards on the board, the frontend updates the local state, syncs to the cloud, and reports the `MOVE_CARD` Action (with gameId and moveCount).
-- **NEW_GAME**: After the user clicks the "New Game" button, the frontend generates a new game and syncs to the cloud, then reports the `NEW_GAME` Action (with gameId).
+- **MOVE_CARD**: After the user moves one or more cards on the board, the frontend updates the local
+  state, syncs to the cloud, and reports the `MOVE_CARD` Action (with gameId and moveCount).
+- **NEW_GAME**: After the user clicks the "New Game" button, the frontend generates a new game and
+  syncs to the cloud, then reports the `NEW_GAME` Action (with gameId).
 
 ### Startup Recovery
 
-On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file does not exist, a new game is automatically generated and written to the cloud.
+On startup, the frontend calls `initFromCloud()` to fetch `/state.json` from the cloud. If the file
+does not exist, a new game is automatically generated and written to the cloud.
diff --git a/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md b/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md
index 7856f7a..3ef1c50 100644
--- a/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md
+++ b/apps/webuiapps/src/pages/Gomoku/meta/meta_cn/guide.md
@@ -18,39 +18,39 @@ apps/gomoku/data/
 
 #### 对局记录文件 `{id}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 对局唯一标识 |
-| players | array | 是 | 两位玩家信息数组，每项包含 name、color、role |
-| moves | array | 是 | 落子记录数组，按时间顺序排列 |
-| result | object \| null | 否 | 对局结果，对局未结束时为 null |
-| startedAt | number | 是 | 对局开始时间戳（毫秒） |
-| endedAt | number \| null | 是 | 对局结束时间戳（毫秒），未结束时为 null |
+| 字段      | 类型           | 必填 | 说明                                         |
+| --------- | -------------- | ---- | -------------------------------------------- |
+| id        | string         | 是   | 对局唯一标识                                 |
+| players   | array          | 是   | 两位玩家信息数组，每项包含 name、color、role |
+| moves     | array          | 是   | 落子记录数组，按时间顺序排列                 |
+| result    | object \| null | 否   | 对局结果，对局未结束时为 null                |
+| startedAt | number         | 是   | 对局开始时间戳（毫秒）                       |
+| endedAt   | number \| null | 是   | 对局结束时间戳（毫秒），未结束时为 null      |
 
 #### Player 对象
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| name | string | 是 | 玩家名称，如 "You"、"Agent" |
-| color | string | 是 | 棋子颜色，`"black"` 或 `"white"` |
-| role | string | 是 | 角色类型，`"human"` 或 `"agent"` |
+| 字段  | 类型   | 必填 | 说明                             |
+| ----- | ------ | ---- | -------------------------------- |
+| name  | string | 是   | 玩家名称，如 "You"、"Agent"      |
+| color | string | 是   | 棋子颜色，`"black"` 或 `"white"` |
+| role  | string | 是   | 角色类型，`"human"` 或 `"agent"` |
 
 #### Move 对象
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| position | object | 是 | 落子位置，包含 `row`（0-14）和 `col`（0-14） |
-| color | string | 是 | 落子颜色，`"black"` 或 `"white"` |
-| moveNumber | number | 是 | 第几手（从 1 开始） |
-| timestamp | number | 是 | 落子时间戳（毫秒） |
+| 字段       | 类型   | 必填 | 说明                                         |
+| ---------- | ------ | ---- | -------------------------------------------- |
+| position   | object | 是   | 落子位置，包含 `row`（0-14）和 `col`（0-14） |
+| color      | string | 是   | 落子颜色，`"black"` 或 `"white"`             |
+| moveNumber | number | 是   | 第几手（从 1 开始）                          |
+| timestamp  | number | 是   | 落子时间戳（毫秒）                           |
 
 #### Result 对象
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| winner | string \| null | 是 | 获胜方颜色，平局时为 null |
-| winLine | object \| null | 是 | 五连珠位置信息，认输或平局时为 null |
-| reason | string | 是 | 结束原因：`"five-in-a-row"` \| `"surrender"` \| `"draw"` |
+| 字段    | 类型           | 必填 | 说明                                                     |
+| ------- | -------------- | ---- | -------------------------------------------------------- |
+| winner  | string \| null | 是   | 获胜方颜色，平局时为 null                                |
+| winLine | object \| null | 是   | 五连珠位置信息，认输或平局时为 null                      |
+| reason  | string         | 是   | 结束原因：`"five-in-a-row"` \| `"surrender"` \| `"draw"` |
 
 ```json
 {
@@ -60,15 +60,28 @@ apps/gomoku/data/
     { "name": "Agent", "color": "white", "role": "agent" }
   ],
   "moves": [
-    { "position": { "row": 7, "col": 7 }, "color": "black", "moveNumber": 1, "timestamp": 1707350400000 },
-    { "position": { "row": 7, "col": 8 }, "color": "white", "moveNumber": 2, "timestamp": 1707350401000 }
+    {
+      "position": { "row": 7, "col": 7 },
+      "color": "black",
+      "moveNumber": 1,
+      "timestamp": 1707350400000
+    },
+    {
+      "position": { "row": 7, "col": 8 },
+      "color": "white",
+      "moveNumber": 2,
+      "timestamp": 1707350401000
+    }
   ],
   "result": {
     "winner": "black",
     "winLine": {
       "positions": [
-        { "row": 7, "col": 3 }, { "row": 7, "col": 4 }, { "row": 7, "col": 5 },
-        { "row": 7, "col": 6 }, { "row": 7, "col": 7 }
+        { "row": 7, "col": 3 },
+        { "row": 7, "col": 4 },
+        { "row": 7, "col": 5 },
+        { "row": 7, "col": 6 },
+        { "row": 7, "col": 7 }
       ],
       "color": "black"
     },
@@ -83,19 +96,19 @@ apps/gomoku/data/
 
 应用统计数据文件，记录历史对局统计信息。
 
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| currentGameId | string \| null | null | 最近一局的 ID |
-| totalGames | number | 0 | 总对局数 |
-| stats | object | - | 统计数据（见下表） |
+| 字段          | 类型           | 默认值 | 说明               |
+| ------------- | -------------- | ------ | ------------------ |
+| currentGameId | string \| null | null   | 最近一局的 ID      |
+| totalGames    | number         | 0      | 总对局数           |
+| stats         | object         | -      | 统计数据（见下表） |
 
 #### Stats 对象
 
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| blackWins | number | 0 | 黑棋获胜次数 |
-| whiteWins | number | 0 | 白棋获胜次数 |
-| draws | number | 0 | 平局次数 |
+| 字段      | 类型   | 默认值 | 说明         |
+| --------- | ------ | ------ | ------------ |
+| blackWins | number | 0      | 黑棋获胜次数 |
+| whiteWins | number | 0      | 白棋获胜次数 |
+| draws     | number | 0      | 平局次数     |
 
 ```json
 {
diff --git a/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md b/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md
index d5a2db5..dd1eb20 100644
--- a/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md
+++ b/apps/webuiapps/src/pages/Gomoku/meta/meta_en/guide.md
@@ -14,43 +14,44 @@ apps/gomoku/data/
 
 ### Game Records `/history/`
 
-Collection of game history records, one JSON file per game. File name is `{id}.json`, automatically written by the App when a game ends.
+Collection of game history records, one JSON file per game. File name is `{id}.json`, automatically
+written by the App when a game ends.
 
 #### Game Record File `{id}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique game identifier |
-| players | array | Yes | Two-element array of player info, each with name, color, role |
-| moves | array | Yes | Array of move records in chronological order |
-| result | object \| null | No | Game result, null if game is not finished |
-| startedAt | number | Yes | Game start timestamp (milliseconds) |
-| endedAt | number \| null | Yes | Game end timestamp (milliseconds), null if not finished |
+| Field     | Type           | Required | Description                                                   |
+| --------- | -------------- | -------- | ------------------------------------------------------------- |
+| id        | string         | Yes      | Unique game identifier                                        |
+| players   | array          | Yes      | Two-element array of player info, each with name, color, role |
+| moves     | array          | Yes      | Array of move records in chronological order                  |
+| result    | object \| null | No       | Game result, null if game is not finished                     |
+| startedAt | number         | Yes      | Game start timestamp (milliseconds)                           |
+| endedAt   | number \| null | Yes      | Game end timestamp (milliseconds), null if not finished       |
 
 #### Player Object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| name | string | Yes | Player name, e.g. "You", "Agent" |
-| color | string | Yes | Stone color, `"black"` or `"white"` |
-| role | string | Yes | Role type, `"human"` or `"agent"` |
+| Field | Type   | Required | Description                         |
+| ----- | ------ | -------- | ----------------------------------- |
+| name  | string | Yes      | Player name, e.g. "You", "Agent"    |
+| color | string | Yes      | Stone color, `"black"` or `"white"` |
+| role  | string | Yes      | Role type, `"human"` or `"agent"`   |
 
 #### Move Object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| position | object | Yes | Placement position with `row` (0-14) and `col` (0-14) |
-| color | string | Yes | Stone color, `"black"` or `"white"` |
-| moveNumber | number | Yes | Move number (starting from 1) |
-| timestamp | number | Yes | Move timestamp (milliseconds) |
+| Field      | Type   | Required | Description                                           |
+| ---------- | ------ | -------- | ----------------------------------------------------- |
+| position   | object | Yes      | Placement position with `row` (0-14) and `col` (0-14) |
+| color      | string | Yes      | Stone color, `"black"` or `"white"`                   |
+| moveNumber | number | Yes      | Move number (starting from 1)                         |
+| timestamp  | number | Yes      | Move timestamp (milliseconds)                         |
 
 #### Result Object
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| winner | string \| null | Yes | Winning color, null for draws |
-| winLine | object \| null | Yes | Five-in-a-row position info, null for surrender or draw |
-| reason | string | Yes | End reason: `"five-in-a-row"` \| `"surrender"` \| `"draw"` |
+| Field   | Type           | Required | Description                                                |
+| ------- | -------------- | -------- | ---------------------------------------------------------- |
+| winner  | string \| null | Yes      | Winning color, null for draws                              |
+| winLine | object \| null | Yes      | Five-in-a-row position info, null for surrender or draw    |
+| reason  | string         | Yes      | End reason: `"five-in-a-row"` \| `"surrender"` \| `"draw"` |
 
 ```json
 {
@@ -60,15 +61,28 @@ Collection of game history records, one JSON file per game. File name is `{id}.j
     { "name": "Agent", "color": "white", "role": "agent" }
   ],
   "moves": [
-    { "position": { "row": 7, "col": 7 }, "color": "black", "moveNumber": 1, "timestamp": 1707350400000 },
-    { "position": { "row": 7, "col": 8 }, "color": "white", "moveNumber": 2, "timestamp": 1707350401000 }
+    {
+      "position": { "row": 7, "col": 7 },
+      "color": "black",
+      "moveNumber": 1,
+      "timestamp": 1707350400000
+    },
+    {
+      "position": { "row": 7, "col": 8 },
+      "color": "white",
+      "moveNumber": 2,
+      "timestamp": 1707350401000
+    }
   ],
   "result": {
     "winner": "black",
     "winLine": {
       "positions": [
-        { "row": 7, "col": 3 }, { "row": 7, "col": 4 }, { "row": 7, "col": 5 },
-        { "row": 7, "col": 6 }, { "row": 7, "col": 7 }
+        { "row": 7, "col": 3 },
+        { "row": 7, "col": 4 },
+        { "row": 7, "col": 5 },
+        { "row": 7, "col": 6 },
+        { "row": 7, "col": 7 }
       ],
       "color": "black"
     },
@@ -83,19 +97,19 @@ Collection of game history records, one JSON file per game. File name is `{id}.j
 
 Application statistics file, recording historical game statistics.
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| currentGameId | string \| null | null | ID of the most recent game |
-| totalGames | number | 0 | Total number of games played |
-| stats | object | - | Statistics data (see below) |
+| Field         | Type           | Default | Description                  |
+| ------------- | -------------- | ------- | ---------------------------- |
+| currentGameId | string \| null | null    | ID of the most recent game   |
+| totalGames    | number         | 0       | Total number of games played |
+| stats         | object         | -       | Statistics data (see below)  |
 
 #### Stats Object
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| blackWins | number | 0 | Number of black wins |
-| whiteWins | number | 0 | Number of white wins |
-| draws | number | 0 | Number of draws |
+| Field     | Type   | Default | Description          |
+| --------- | ------ | ------- | -------------------- |
+| blackWins | number | 0       | Number of black wins |
+| whiteWins | number | 0       | Number of white wins |
+| draws     | number | 0       | Number of draws      |
 
 ```json
 {
@@ -113,7 +127,8 @@ Application statistics file, recording historical game statistics.
 
 ### Auto-save on Game End
 
-1. When a game ends (five-in-a-row, surrender, or draw), App writes the game record to `/history/{id}.json`
+1. When a game ends (five-in-a-row, surrender, or draw), App writes the game record to
+   `/history/{id}.json`
 2. App updates statistics in `/state.json`
 3. App calls `reportAction` to report the game result
 
diff --git a/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md b/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md
index 42035bf..ad7fecd 100644
--- a/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md
+++ b/apps/webuiapps/src/pages/MusicApp/meta/meta_cn/guide.md
@@ -21,16 +21,16 @@ apps/musicPlayer/data/
 
 #### 歌曲文件 `{id}.json`
 
-| Field      | Type   | Required | Description                          |
-| ---------- | ------ | -------- | ------------------------------------ |
-| id         | string | 是       | 歌曲唯一标识，如 `song-001`          |
-| title      | string | 是       | 歌曲标题                             |
-| artist     | string | 是       | 艺术家名称                           |
-| album      | string | 是       | 专辑名称                             |
-| duration   | number | 是       | 时长（秒）                           |
-| coverColor | string | 是       | 封面颜色（hex，如 `#6366F1`）        |
-| createdAt  | number | 是       | 创建时间戳（毫秒）                   |
-| audioUrl   | string | 是       | 音频文件 URL                         |
+| Field      | Type   | Required | Description                   |
+| ---------- | ------ | -------- | ----------------------------- |
+| id         | string | 是       | 歌曲唯一标识，如 `song-001`   |
+| title      | string | 是       | 歌曲标题                      |
+| artist     | string | 是       | 艺术家名称                    |
+| album      | string | 是       | 专辑名称                      |
+| duration   | number | 是       | 时长（秒）                    |
+| coverColor | string | 是       | 封面颜色（hex，如 `#6366F1`） |
+| createdAt  | number | 是       | 创建时间戳（毫秒）            |
+| audioUrl   | string | 是       | 音频文件 URL                  |
 
 ```json
 {
@@ -51,12 +51,12 @@ apps/musicPlayer/data/
 
 #### 播放列表文件 `{id}.json`
 
-| Field     | Type     | Required | Description                              |
-| --------- | -------- | -------- | ---------------------------------------- |
-| id        | string   | 是       | 播放列表唯一标识，如 `playlist-001`      |
-| name      | string   | 是       | 播放列表名称                             |
-| songIds   | string[] | 是       | 歌曲 ID 列表                            |
-| createdAt | number   | 是       | 创建时间戳（毫秒）                       |
+| Field     | Type     | Required | Description                         |
+| --------- | -------- | -------- | ----------------------------------- |
+| id        | string   | 是       | 播放列表唯一标识，如 `playlist-001` |
+| name      | string   | 是       | 播放列表名称                        |
+| songIds   | string[] | 是       | 歌曲 ID 列表                        |
+| createdAt | number   | 是       | 创建时间戳（毫秒）                  |
 
 ```json
 {
@@ -71,23 +71,23 @@ apps/musicPlayer/data/
 
 应用运行时状态文件，用于现场恢复和跨端状态同步。App 启动时读取此文件恢复上次状态，运行中定期保存。
 
-| Field            | Type           | Default     | Description                                        |
-| ---------------- | -------------- | ----------- | -------------------------------------------------- |
-| currentView      | string         | "all-songs" | 当前视图（`"all-songs"` \| `"playlist"`）          |
-| activePlaylistId | string \| null | null        | 当前选中的播放列表 ID                              |
-| player           | object         | -           | 播放器状态对象（见下表）                           |
-| searchQuery      | string         | ""          | 当前搜索关键词                                     |
+| Field            | Type           | Default     | Description                               |
+| ---------------- | -------------- | ----------- | ----------------------------------------- |
+| currentView      | string         | "all-songs" | 当前视图（`"all-songs"` \| `"playlist"`） |
+| activePlaylistId | string \| null | null        | 当前选中的播放列表 ID                     |
+| player           | object         | -           | 播放器状态对象（见下表）                  |
+| searchQuery      | string         | ""          | 当前搜索关键词                            |
 
 #### Player State（嵌套在 `player` 中）
 
-| Field                  | Type           | Default      | Description                                                  |
-| ---------------------- | -------------- | ------------ | ------------------------------------------------------------ |
-| currentSongId          | string \| null | null         | 当前播放歌曲 ID                                              |
-| currentPlaylistContext | string \| null | null         | 当前播放上下文的播放列表 ID                                  |
-| isPlaying              | boolean        | false        | 是否正在播放                                                 |
-| currentTime            | number         | 0            | 当前播放进度（秒）                                           |
-| volume                 | number         | 0.7          | 音量（0.0 - 1.0）                                            |
-| playMode               | string         | "sequential" | 播放模式（`"sequential"` \| `"repeat-one"` \| `"shuffle"`）  |
+| Field                  | Type           | Default      | Description                                                 |
+| ---------------------- | -------------- | ------------ | ----------------------------------------------------------- |
+| currentSongId          | string \| null | null         | 当前播放歌曲 ID                                             |
+| currentPlaylistContext | string \| null | null         | 当前播放上下文的播放列表 ID                                 |
+| isPlaying              | boolean        | false        | 是否正在播放                                                |
+| currentTime            | number         | 0            | 当前播放进度（秒）                                          |
+| volume                 | number         | 0.7          | 音量（0.0 - 1.0）                                           |
+| playMode               | string         | "sequential" | 播放模式（`"sequential"` \| `"repeat-one"` \| `"shuffle"`） |
 
 ```json
 {
@@ -118,7 +118,8 @@ apps/musicPlayer/data/
 
 1. 用户在 App 中操作（如创建播放列表、添加歌曲到播放列表）
 2. App 将数据写入云端（`syncToCloud`）
-3. App 调用 `reportAction` 上报用户操作（如 `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`）
+3. App 调用 `reportAction` 上报用户操作（如
+   `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`）
 
 ### 启动恢复
 
diff --git a/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md b/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md
index 2a25059..63739c3 100644
--- a/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md
+++ b/apps/webuiapps/src/pages/MusicApp/meta/meta_en/guide.md
@@ -17,20 +17,21 @@ apps/musicPlayer/data/
 
 ### Songs `/songs/`
 
-Song data collection, one JSON file per song. File name is `{id}.json`, written by the App or Agent upon creation.
+Song data collection, one JSON file per song. File name is `{id}.json`, written by the App or Agent
+upon creation.
 
 #### Song File `{id}.json`
 
-| Field      | Type   | Required | Description                              |
-| ---------- | ------ | -------- | ---------------------------------------- |
-| id         | string | Yes      | Unique song identifier, e.g. `song-001`  |
-| title      | string | Yes      | Song title                               |
-| artist     | string | Yes      | Artist name                              |
-| album      | string | Yes      | Album name                               |
-| duration   | number | Yes      | Duration in seconds                      |
-| coverColor | string | Yes      | Cover color (hex, e.g. `#6366F1`)        |
-| createdAt  | number | Yes      | Creation timestamp (milliseconds)        |
-| audioUrl   | string | Yes      | Audio file URL                           |
+| Field      | Type   | Required | Description                             |
+| ---------- | ------ | -------- | --------------------------------------- |
+| id         | string | Yes      | Unique song identifier, e.g. `song-001` |
+| title      | string | Yes      | Song title                              |
+| artist     | string | Yes      | Artist name                             |
+| album      | string | Yes      | Album name                              |
+| duration   | number | Yes      | Duration in seconds                     |
+| coverColor | string | Yes      | Cover color (hex, e.g. `#6366F1`)       |
+| createdAt  | number | Yes      | Creation timestamp (milliseconds)       |
+| audioUrl   | string | Yes      | Audio file URL                          |
 
 ```json
 {
@@ -51,12 +52,12 @@ Playlist data collection, one JSON file per playlist. File name is `{id}.json`.
 
 #### Playlist File `{id}.json`
 
-| Field     | Type     | Required | Description                                  |
-| --------- | -------- | -------- | -------------------------------------------- |
+| Field     | Type     | Required | Description                                     |
+| --------- | -------- | -------- | ----------------------------------------------- |
 | id        | string   | Yes      | Unique playlist identifier, e.g. `playlist-001` |
-| name      | string   | Yes      | Playlist name                                |
-| songIds   | string[] | Yes      | List of song IDs                             |
-| createdAt | number   | Yes      | Creation timestamp (milliseconds)            |
+| name      | string   | Yes      | Playlist name                                   |
+| songIds   | string[] | Yes      | List of song IDs                                |
+| createdAt | number   | Yes      | Creation timestamp (milliseconds)               |
 
 ```json
 {
@@ -69,23 +70,24 @@ Playlist data collection, one JSON file per playlist. File name is `{id}.json`.
 
 ### State File `/state.json`
 
-Runtime state file for session recovery and cross-device state synchronization. The App reads this file on startup to restore the previous state, and periodically saves during runtime.
+Runtime state file for session recovery and cross-device state synchronization. The App reads this
+file on startup to restore the previous state, and periodically saves during runtime.
 
-| Field            | Type           | Default     | Description                                        |
-| ---------------- | -------------- | ----------- | -------------------------------------------------- |
-| currentView      | string         | "all-songs" | Current view (`"all-songs"` \| `"playlist"`)       |
-| activePlaylistId | string \| null | null        | Currently selected playlist ID                     |
-| player           | object         | -           | Player state object (see below)                    |
-| searchQuery      | string         | ""          | Current search keyword                             |
+| Field            | Type           | Default     | Description                                  |
+| ---------------- | -------------- | ----------- | -------------------------------------------- |
+| currentView      | string         | "all-songs" | Current view (`"all-songs"` \| `"playlist"`) |
+| activePlaylistId | string \| null | null        | Currently selected playlist ID               |
+| player           | object         | -           | Player state object (see below)              |
+| searchQuery      | string         | ""          | Current search keyword                       |
 
 #### Player State (nested in `player`)
 
-| Field                  | Type           | Default      | Description                                                  |
-| ---------------------- | -------------- | ------------ | ------------------------------------------------------------ |
-| currentSongId          | string \| null | null         | Currently playing song ID                                    |
-| currentPlaylistContext | string \| null | null         | Playlist ID of current playback context                      |
-| isPlaying              | boolean        | false        | Whether audio is currently playing                           |
-| currentTime            | number         | 0            | Current playback position in seconds                         |
+| Field                  | Type           | Default      | Description                                                 |
+| ---------------------- | -------------- | ------------ | ----------------------------------------------------------- |
+| currentSongId          | string \| null | null         | Currently playing song ID                                   |
+| currentPlaylistContext | string \| null | null         | Playlist ID of current playback context                     |
+| isPlaying              | boolean        | false        | Whether audio is currently playing                          |
+| currentTime            | number         | 0            | Current playback position in seconds                        |
 | volume                 | number         | 0.7          | Volume level (0.0 - 1.0)                                    |
 | playMode               | string         | "sequential" | Play mode (`"sequential"` \| `"repeat-one"` \| `"shuffle"`) |
 
@@ -109,21 +111,25 @@ Runtime state file for session recovery and cross-device state synchronization.
 
 ### Agent Creates Data
 
-1. Agent writes song/playlist JSON files to the corresponding NAS directory (`/songs/{id}.json` or `/playlists/{id}.json`)
+1. Agent writes song/playlist JSON files to the corresponding NAS directory (`/songs/{id}.json` or
+   `/playlists/{id}.json`)
 2. Agent sends a data mutation Action (e.g. `CREATE_SONG`, `CREATE_PLAYLIST`)
-3. App receives the Action and calls the corresponding Repo's `refresh()` method to pull latest data from cloud
+3. App receives the Action and calls the corresponding Repo's `refresh()` method to pull latest data
+   from cloud
 4. UI automatically updates to display new data
 
 ### User Creates Data
 
 1. User performs an operation in the App (e.g. create playlist, add song to playlist)
 2. App writes data to cloud (`syncToCloud`)
-3. App calls `reportAction` to report the user operation (e.g. `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`)
+3. App calls `reportAction` to report the user operation (e.g.
+   `reportAction('CREATE_PLAYLIST', { playlistId: '...' })`)
 
 ### Startup Recovery
 
 1. App starts, reports `DOM_READY` lifecycle event
 2. Calls `initFromCloud()` to pull all data from NAS (songs, playlists, state.json)
-3. Reads `state.json`, restores `currentView`, `activePlaylistId`, `player` and other state to memory
+3. Reads `state.json`, restores `currentView`, `activePlaylistId`, `player` and other state to
+   memory
 4. UI rendering completes, reports `READY` lifecycle event
 5. App enters ready state and begins accepting Agent Actions
diff --git a/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md b/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md
index 71fcfdd..20f6b5b 100644
--- a/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md
+++ b/apps/webuiapps/src/pages/Twitter/twitter_cn/guide.md
@@ -23,42 +23,42 @@
 
 #### 帖子文件 `{postId}.json`
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 帖子唯一标识，与文件名一致（不含 `.json` 后缀） |
-| author | object | 是 | 作者信息 |
-| author.name | string | 是 | 作者昵称 |
-| author.username | string | 是 | 作者用户名（`@xxx` 格式） |
-| author.avatar | string | 是 | 作者头像 URL，可为空字符串 |
-| content | string | 是 | 帖子内容，最长 280 字符 |
-| timestamp | integer | 是 | 发布时间戳（毫秒） |
-| likes | integer | 是 | 点赞数，最小值为 0 |
-| isLiked | boolean | 是 | 当前用户是否已点赞 |
-| comments | array | 是 | 评论列表，每项为 Comment 对象 |
+| 字段            | 类型    | 必填 | 说明                                            |
+| --------------- | ------- | ---- | ----------------------------------------------- |
+| id              | string  | 是   | 帖子唯一标识，与文件名一致（不含 `.json` 后缀） |
+| author          | object  | 是   | 作者信息                                        |
+| author.name     | string  | 是   | 作者昵称                                        |
+| author.username | string  | 是   | 作者用户名（`@xxx` 格式）                       |
+| author.avatar   | string  | 是   | 作者头像 URL，可为空字符串                      |
+| content         | string  | 是   | 帖子内容，最长 280 字符                         |
+| timestamp       | integer | 是   | 发布时间戳（毫秒）                              |
+| likes           | integer | 是   | 点赞数，最小值为 0                              |
+| isLiked         | boolean | 是   | 当前用户是否已点赞                              |
+| comments        | array   | 是   | 评论列表，每项为 Comment 对象                   |
 
 **Comment 对象结构：**
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | string | 是 | 评论唯一标识 |
-| author | object | 是 | 评论作者信息 |
-| author.name | string | 是 | 作者昵称 |
-| author.username | string | 是 | 作者用户名（`@xxx` 格式） |
-| author.avatar | string | 是 | 作者头像 URL，可为空字符串 |
-| content | string | 是 | 评论内容，最长 280 字符 |
-| timestamp | integer | 是 | 评论时间戳（毫秒） |
+| 字段            | 类型    | 必填 | 说明                       |
+| --------------- | ------- | ---- | -------------------------- |
+| id              | string  | 是   | 评论唯一标识               |
+| author          | object  | 是   | 评论作者信息               |
+| author.name     | string  | 是   | 作者昵称                   |
+| author.username | string  | 是   | 作者用户名（`@xxx` 格式）  |
+| author.avatar   | string  | 是   | 作者头像 URL，可为空字符串 |
+| content         | string  | 是   | 评论内容，最长 280 字符    |
+| timestamp       | integer | 是   | 评论时间戳（毫秒）         |
 
 ### 状态文件 `/state.json`
 
 存储应用运行时状态，用于启动时恢复现场。前端在状态变更时自动保存并同步到云端。
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| draftContent | string | 否 | 当前发帖输入框中的草稿内容 |
-| currentUser | object | 是 | 当前登录用户信息 |
-| currentUser.name | string | 是 | 用户昵称 |
-| currentUser.username | string | 是 | 用户名（`@xxx` 格式） |
-| currentUser.avatar | string | 是 | 头像 URL，可为空字符串 |
+| 字段                 | 类型   | 必填 | 说明                       |
+| -------------------- | ------ | ---- | -------------------------- |
+| draftContent         | string | 否   | 当前发帖输入框中的草稿内容 |
+| currentUser          | object | 是   | 当前登录用户信息           |
+| currentUser.name     | string | 是   | 用户昵称                   |
+| currentUser.username | string | 是   | 用户名（`@xxx` 格式）      |
+| currentUser.avatar   | string | 是   | 头像 URL，可为空字符串     |
 
 示例：
 
@@ -77,8 +77,7 @@
 
 ### Agent 操作（Agent → 前端）
 
-Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。
-前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
+Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发 Action 通知前端同步刷新。前端收到 Action 后仅从云端读取最新数据，不再进行本地文件创建。
 
 **Agent 创建帖子**:
 
@@ -89,7 +88,8 @@ Agent 负责在云端完成文件的写入/修改/删除，完成后通过下发
 **Agent 更新/点赞/评论帖子**:
 
 1. Agent 在云端修改帖子文件（更新内容、增加点赞、追加评论等）
-2. Agent 下发对应 Action（`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`），params 携带 `filePath` 或 `postId`
+2. Agent 下发对应 Action（`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`），params 携带
+   `filePath` 或 `postId`
 3. 前端收到 Action 后从云端重新读取该帖子文件，替换本地数据并刷新 UI
 
 **Agent 删除帖子**:
diff --git a/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md b/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md
index 0ff3dc1..169ca2d 100644
--- a/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md
+++ b/apps/webuiapps/src/pages/Twitter/twitter_en/guide.md
@@ -23,42 +23,43 @@ Stores all post data. Each post is saved as an independent JSON file, named by p
 
 #### Post File `{postId}.json`
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique post identifier, matches the filename (without `.json` extension) |
-| author | object | Yes | Author information |
-| author.name | string | Yes | Author display name |
-| author.username | string | Yes | Author username (`@xxx` format) |
-| author.avatar | string | Yes | Author avatar URL, can be an empty string |
-| content | string | Yes | Post content, max 280 characters |
-| timestamp | integer | Yes | Publication timestamp (milliseconds) |
-| likes | integer | Yes | Like count, minimum 0 |
-| isLiked | boolean | Yes | Whether the current user has liked this post |
-| comments | array | Yes | Comment list, each item is a Comment object |
+| Field           | Type    | Required | Description                                                              |
+| --------------- | ------- | -------- | ------------------------------------------------------------------------ |
+| id              | string  | Yes      | Unique post identifier, matches the filename (without `.json` extension) |
+| author          | object  | Yes      | Author information                                                       |
+| author.name     | string  | Yes      | Author display name                                                      |
+| author.username | string  | Yes      | Author username (`@xxx` format)                                          |
+| author.avatar   | string  | Yes      | Author avatar URL, can be an empty string                                |
+| content         | string  | Yes      | Post content, max 280 characters                                         |
+| timestamp       | integer | Yes      | Publication timestamp (milliseconds)                                     |
+| likes           | integer | Yes      | Like count, minimum 0                                                    |
+| isLiked         | boolean | Yes      | Whether the current user has liked this post                             |
+| comments        | array   | Yes      | Comment list, each item is a Comment object                              |
 
 **Comment Object Structure:**
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | string | Yes | Unique comment identifier |
-| author | object | Yes | Comment author information |
-| author.name | string | Yes | Author display name |
-| author.username | string | Yes | Author username (`@xxx` format) |
-| author.avatar | string | Yes | Author avatar URL, can be an empty string |
-| content | string | Yes | Comment content, max 280 characters |
-| timestamp | integer | Yes | Comment timestamp (milliseconds) |
+| Field           | Type    | Required | Description                               |
+| --------------- | ------- | -------- | ----------------------------------------- |
+| id              | string  | Yes      | Unique comment identifier                 |
+| author          | object  | Yes      | Comment author information                |
+| author.name     | string  | Yes      | Author display name                       |
+| author.username | string  | Yes      | Author username (`@xxx` format)           |
+| author.avatar   | string  | Yes      | Author avatar URL, can be an empty string |
+| content         | string  | Yes      | Comment content, max 280 characters       |
+| timestamp       | integer | Yes      | Comment timestamp (milliseconds)          |
 
 ### State File `/state.json`
 
-Stores the app's runtime state for restoring the session on startup. The frontend automatically saves and syncs to the cloud when state changes.
+Stores the app's runtime state for restoring the session on startup. The frontend automatically
+saves and syncs to the cloud when state changes.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| draftContent | string | No | Current draft content in the post input box |
-| currentUser | object | Yes | Current logged-in user information |
-| currentUser.name | string | Yes | User display name |
-| currentUser.username | string | Yes | Username (`@xxx` format) |
-| currentUser.avatar | string | Yes | Avatar URL, can be an empty string |
+| Field                | Type   | Required | Description                                 |
+| -------------------- | ------ | -------- | ------------------------------------------- |
+| draftContent         | string | No       | Current draft content in the post input box |
+| currentUser          | object | Yes      | Current logged-in user information          |
+| currentUser.name     | string | Yes      | User display name                           |
+| currentUser.username | string | Yes      | Username (`@xxx` format)                    |
+| currentUser.avatar   | string | Yes      | Avatar URL, can be an empty string          |
 
 Example:
 
@@ -77,19 +78,23 @@ Example:
 
 ### Agent Operations (Agent → Frontend)
 
-The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to notify the frontend to sync and refresh.
-After receiving an Action, the frontend only reads the latest data from the cloud — it does not create files locally.
+The Agent completes file writes/modifications/deletions on the cloud, then dispatches Actions to
+notify the frontend to sync and refresh. After receiving an Action, the frontend only reads the
+latest data from the cloud — it does not create files locally.
 
 **Agent Creates a Post**:
 
 1. The Agent writes the file `/posts/{id}.json` on the cloud (containing the complete post JSON)
-2. The Agent dispatches the `CREATE_POST` Action with `filePath` in params (e.g., `/posts/{id}.json`)
+2. The Agent dispatches the `CREATE_POST` Action with `filePath` in params (e.g.,
+   `/posts/{id}.json`)
 3. The frontend reads the file from the cloud, updates the local file tree and UI
 
 **Agent Updates/Likes/Comments on a Post**:
 
-1. The Agent modifies the post file on the cloud (updates content, adds likes, appends comments, etc.)
-2. The Agent dispatches the corresponding Action (`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`) with `filePath` or `postId` in params
+1. The Agent modifies the post file on the cloud (updates content, adds likes, appends comments,
+   etc.)
+2. The Agent dispatches the corresponding Action
+   (`UPDATE_POST`/`LIKE_POST`/`UNLIKE_POST`/`COMMENT_POST`) with `filePath` or `postId` in params
 3. The frontend re-reads the post file from the cloud, replaces local data, and refreshes the UI
 
 **Agent Deletes a Post**:
@@ -100,7 +105,8 @@ After receiving an Action, the frontend only reads the latest data from the clou
 
 ### User Operations (Frontend → Cloud)
 
-User operations on the frontend are handled by the frontend code. The flow is: local operation → sync to cloud → report Action.
+User operations on the frontend are handled by the frontend code. The flow is: local operation →
+sync to cloud → report Action.
 
 **User Creates a Post**:
 
diff --git a/apps/webuiapps/vite.config.ts b/apps/webuiapps/vite.config.ts
index d2635e4..6a16753 100644
--- a/apps/webuiapps/vite.config.ts
+++ b/apps/webuiapps/vite.config.ts
@@ -2,7 +2,7 @@ import { UserConfigExport, ConfigEnv, loadEnv } from 'vite';
 import type { PluginOption, Plugin } from 'vite';
 import legacy from '@vitejs/plugin-legacy';
 import react from '@vitejs/plugin-react-swc';
-import { resolve } from 'path';
+import { resolve, sep } from 'path';
 import { visualizer } from 'rollup-plugin-visualizer';
 import autoprefixer from 'autoprefixer';
 import { sentryVitePlugin } from '@sentry/vite-plugin';
@@ -17,6 +17,77 @@ const SESSIONS_DIR = resolve(os.homedir(), '.openroom', 'sessions');
 const CHARACTERS_FILE = resolve(os.homedir(), '.openroom', 'characters.json');
 const MODS_FILE = resolve(os.homedir(), '.openroom', 'mods.json');
 
+type ServerConfigSection = Record<string, unknown>;
+interface ServerPersistedConfig {
+  llm: ServerConfigSection;
+  imageGen?: ServerConfigSection;
+}
+type ProxyProvider = 'openai' | 'anthropic' | 'minimax' | 'gemini' | 'unknown';
+type ConfigScope = 'llm' | 'imageGen';
+
+let cachedServerConfig: {
+  mtimeMs: number;
+  value: ServerPersistedConfig | null;
+} | null = null;
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function normalizeServerConfig(raw: unknown): ServerPersistedConfig | null {
+  if (isObjectRecord(raw) && isObjectRecord(raw.llm)) {
+    const normalized: ServerPersistedConfig = { llm: { ...raw.llm } };
+    if (isObjectRecord(raw.imageGen)) {
+      normalized.imageGen = { ...raw.imageGen };
+    }
+    return normalized;
+  }
+
+  if (isObjectRecord(raw) && 'provider' in raw) {
+    return { llm: { ...raw } };
+  }
+
+  return null;
+}
+
+function getStoredApiKey(section?: ServerConfigSection): string | null {
+  return typeof section?.apiKey === 'string' && section.apiKey.trim() ? section.apiKey : null;
+}
+
+function redactConfigSection(section?: ServerConfigSection): ServerConfigSection | undefined {
+  if (!section) return undefined;
+  return {
+    ...section,
+    apiKey: '',
+    hasApiKey: !!getStoredApiKey(section),
+  };
+}
+
+export function redactServerConfig(config: ServerPersistedConfig | null): Record<string, unknown> {
+  if (!config) return {};
+
+  const redacted: Record<string, unknown> = {
+    llm: redactConfigSection(config.llm),
+  };
+  const imageGen = redactConfigSection(config.imageGen);
+  if (imageGen) {
+    redacted.imageGen = imageGen;
+  }
+  return redacted;
+}
+
+function mergeConfigSection(
+  existing: ServerConfigSection | undefined,
+  incoming: ServerConfigSection,
+): ServerConfigSection {
+  const merged: ServerConfigSection = { ...(existing || {}), ...incoming };
+  if (!Object.hasOwn(incoming, 'apiKey') && typeof existing?.apiKey === 'string') {
+    merged.apiKey = existing.apiKey;
+  }
+  delete merged.hasApiKey;
+  return merged;
+}
+
 /** LLM config persistence plugin — reads/writes config to ~/.openroom/config.json */
 function llmConfigPlugin(): Plugin {
   return {
@@ -27,14 +98,8 @@ function llmConfigPlugin(): Plugin {
 
         if (req.method === 'GET') {
           try {
-            if (fs.existsSync(LLM_CONFIG_FILE)) {
-              const content = fs.readFileSync(LLM_CONFIG_FILE, 'utf-8');
-              res.writeHead(200);
-              res.end(content);
-            } else {
-              res.writeHead(200);
-              res.end('{}');
-            }
+            res.writeHead(200);
+            res.end(JSON.stringify(redactServerConfig(loadServerConfig())));
           } catch (err) {
             res.writeHead(500);
             res.end(JSON.stringify({ error: String(err) }));
@@ -46,12 +111,52 @@ function llmConfigPlugin(): Plugin {
           const chunks: Buffer[] = [];
           req.on('data', (chunk: Buffer) => chunks.push(chunk));
           req.on('end', () => {
+            let parsed: unknown;
+            let nextConfig: ServerPersistedConfig | null;
+            let existingConfig: ServerPersistedConfig | null;
+            let mergedConfig: ServerPersistedConfig;
+
             try {
               const body = Buffer.concat(chunks).toString();
-              // Validate JSON before writing
-              JSON.parse(body);
-              fs.mkdirSync(resolve(os.homedir(), '.openroom'), { recursive: true });
-              fs.writeFileSync(LLM_CONFIG_FILE, body, 'utf-8');
+              parsed = JSON.parse(body);
+              nextConfig = normalizeServerConfig(parsed);
+              if (!nextConfig) {
+                throw new Error('Invalid config payload');
+              }
+
+              existingConfig = loadServerConfig();
+              mergedConfig = {
+                llm: mergeConfigSection(existingConfig?.llm, nextConfig.llm),
+              };
+
+              if (isObjectRecord(parsed) && Object.hasOwn(parsed, 'imageGen')) {
+                if (parsed.imageGen !== null) {
+                  if (!isObjectRecord(parsed.imageGen)) {
+                    throw new Error('Invalid imageGen config payload');
+                  }
+                  mergedConfig.imageGen = mergeConfigSection(
+                    existingConfig?.imageGen,
+                    parsed.imageGen,
+                  );
+                }
+              } else if (existingConfig?.imageGen) {
+                mergedConfig.imageGen = { ...existingConfig.imageGen };
+              }
+            } catch (err) {
+              res.writeHead(400);
+              res.end(JSON.stringify({ error: String(err) }));
+              return;
+            }
+
+            try {
+              const configDir = resolve(os.homedir(), '.openroom');
+              fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+              fs.writeFileSync(LLM_CONFIG_FILE, JSON.stringify(mergedConfig), {
+                encoding: 'utf-8',
+                mode: 0o600,
+              });
+              const stat = fs.statSync(LLM_CONFIG_FILE);
+              cachedServerConfig = { mtimeMs: stat.mtimeMs, value: mergedConfig };
               res.writeHead(200);
               res.end(JSON.stringify({ ok: true }));
             } catch (err) {
@@ -69,6 +174,27 @@ function llmConfigPlugin(): Plugin {
   };
 }
 
+/**
+ * Sanitize a relative path to prevent directory traversal.
+ * Resolves any ../ sequences and ensures the result stays within the expected base.
+ * Returns null if the path would escape the base directory.
+ */
+function sanitizeRelativePath(relPath: string, baseDir: string): string | null {
+  // Strip null bytes and normalize
+  const cleaned = relPath.replace(/\0/g, '');
+  // Only allow safe characters: alphanumeric, underscore, hyphen, dot, forward slash
+  const safe = cleaned.replace(/[^a-zA-Z0-9_\-./]/g, '_');
+  // Resolve to absolute and verify it stays within baseDir
+  const resolved = resolve(baseDir, safe);
+  // Normalize both paths for comparison (resolve handles .. sequences)
+  const normalizedBase = resolve(baseDir);
+  if (!resolved.startsWith(normalizedBase + sep) && resolved !== normalizedBase) {
+    return null;
+  }
+  // Return the relative portion (stripped of base) for use with join()
+  return resolved.slice(normalizedBase.length + 1) || '';
+}
+
 /**
  * Session data plugin — reads/writes files under ~/.openroom/sessions/
  * API: /api/session-data?path={charId}/{modId}/chat/history.json
@@ -91,8 +217,13 @@ function sessionDataPlugin(): Plugin {
           return;
         }
 
-        // Sanitize: only allow alphanumeric, underscore, hyphen, dot, forward slash
-        const safePath = relPath.replace(/[^a-zA-Z0-9_\-./]/g, '_').replace(/\.\./g, '');
+        // Sanitize: resolve path and ensure it stays within SESSIONS_DIR
+        const safePath = sanitizeRelativePath(relPath, SESSIONS_DIR);
+        if (safePath === null) {
+          res.writeHead(403);
+          res.end(JSON.stringify({ error: 'Invalid path' }));
+          return;
+        }
         const filePath = join(SESSIONS_DIR, safePath);
 
         // Directory listing: ?action=list&path=...
@@ -216,7 +347,12 @@ function sessionDataPlugin(): Plugin {
           return;
         }
 
-        const safePath = relPath.replace(/[^a-zA-Z0-9_\-./]/g, '_').replace(/\.\./g, '');
+        const safePath = sanitizeRelativePath(relPath, SESSIONS_DIR);
+        if (safePath === null) {
+          res.writeHead(403);
+          res.end(JSON.stringify({ error: 'Invalid path' }));
+          return;
+        }
         const targetDir = join(SESSIONS_DIR, safePath);
 
         try {
@@ -252,13 +388,180 @@ function logServerPlugin(): Plugin {
   };
 }
 
-/** LLM API proxy plugin — resolves browser CORS restrictions */
+/** Load server-side LLM config for API key injection */
+function loadServerConfig(): ServerPersistedConfig | null {
+  try {
+    if (!fs.existsSync(LLM_CONFIG_FILE)) {
+      cachedServerConfig = null;
+      return null;
+    }
+
+    const stat = fs.statSync(LLM_CONFIG_FILE);
+    if (cachedServerConfig && cachedServerConfig.mtimeMs === stat.mtimeMs) {
+      return cachedServerConfig.value;
+    }
+
+    const parsed = normalizeServerConfig(JSON.parse(fs.readFileSync(LLM_CONFIG_FILE, 'utf-8')));
+    cachedServerConfig = { mtimeMs: stat.mtimeMs, value: parsed };
+    return parsed;
+  } catch {
+    // Config file missing or malformed
+    cachedServerConfig = null;
+  }
+  return null;
+}
+
+/** Determine provider type from target URL or X-LLM-Provider hint header */
+export function inferProvider(targetUrl: URL | string, hint?: string): ProxyProvider {
+  const normalizedHint = hint?.trim().toLowerCase();
+  if (normalizedHint) {
+    if (
+      normalizedHint === 'openai' ||
+      normalizedHint === 'anthropic' ||
+      normalizedHint === 'minimax' ||
+      normalizedHint === 'gemini'
+    ) {
+      return normalizedHint;
+    }
+    return 'unknown';
+  }
+
+  try {
+    const parsed = targetUrl instanceof URL ? targetUrl : new URL(targetUrl);
+    const host = parsed.hostname.toLowerCase();
+    if (host.includes('anthropic')) return 'anthropic';
+    if (host.includes('minimax')) return 'minimax';
+    if (host.includes('google') || host.includes('generativelanguage')) return 'gemini';
+    return 'openai'; // default: OpenAI-compatible
+  } catch {
+    return 'unknown';
+  }
+}
+
+export function parseProxyTargetUrl(targetUrl: string): URL | null {
+  try {
+    const parsed = new URL(targetUrl);
+    if (!['https:', 'http:'].includes(parsed.protocol)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Known LLM/image-gen provider hostnames that the proxy may forward to. */
+const ALLOWED_PROVIDER_HOSTS = new Set([
+  'api.openai.com',
+  'api.anthropic.com',
+  'api.deepseek.com',
+  'api.minimax.io',
+  'api.z.ai',
+  'api.moonshot.cn',
+  'openrouter.ai',
+  'generativelanguage.googleapis.com',
+]);
+
+/** Local development hosts — only allowed when ALLOW_LOCAL_LLM=true. */
+const LOCAL_LLM_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1']);
+
+/** Validate that a parsed target URL points to an allowed provider host.
+ * Public provider hosts must use HTTPS. Local development hosts may use HTTP/HTTPS
+ * only when ALLOW_LOCAL_LLM=true. */
+export function isAllowedTarget(parsed: URL): boolean {
+  const host = parsed.hostname.toLowerCase();
+  if (ALLOWED_PROVIDER_HOSTS.has(host)) {
+    return parsed.protocol === 'https:';
+  }
+  if (LOCAL_LLM_HOSTS.has(host) && process.env.ALLOW_LOCAL_LLM === 'true') {
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  }
+  return false;
+}
+
+function normalizeConfigScope(scope?: string): ConfigScope | undefined {
+  return scope === 'imageGen' || scope === 'llm' ? scope : undefined;
+}
+
+export function selectServerApiKey(
+  config: ServerPersistedConfig | null,
+  scope: ConfigScope | undefined,
+  provider: ProxyProvider,
+): string | null {
+  if (!config) return null;
+
+  const llmApiKey = getStoredApiKey(config.llm);
+  const imageGenApiKey = getStoredApiKey(config.imageGen);
+
+  if (scope === 'llm') return llmApiKey;
+  if (scope === 'imageGen') return imageGenApiKey;
+  if (provider === 'gemini') return imageGenApiKey || llmApiKey;
+  return llmApiKey || imageGenApiKey;
+}
+
+function isBlockedPassthroughHeader(headerName: string): boolean {
+  return (
+    headerName.startsWith('x-llm-') ||
+    [
+      'authorization',
+      'cookie',
+      'host',
+      'connection',
+      'proxy-authorization',
+      'x-api-key',
+      'x-goog-api-key',
+      // Hop-by-hop headers per RFC 9110 — forwarding these can cause
+      // request smuggling or broken upstream responses
+      'content-length',
+      'transfer-encoding',
+      'content-encoding',
+      'accept-encoding',
+      'te',
+      'trailer',
+      'upgrade',
+      'keep-alive',
+    ].includes(headerName)
+  );
+}
+
+/** Inject API key from server-side config into proxy request headers */
+function injectServerApiKey(
+  headers: Record<string, string>,
+  targetUrl: URL,
+  providerHint?: string,
+  configScope?: string,
+): void {
+  const config = loadServerConfig();
+  const provider = inferProvider(targetUrl, providerHint);
+  const apiKey = selectServerApiKey(config, normalizeConfigScope(configScope), provider);
+
+  if (!apiKey) return;
+
+  if (provider === 'anthropic' || provider === 'minimax') {
+    headers['x-api-key'] = apiKey;
+  } else if (provider === 'gemini') {
+    headers['x-goog-api-key'] = apiKey;
+  } else {
+    headers['authorization'] = `Bearer ${apiKey}`;
+  }
+}
+
+/** LLM API proxy plugin — resolves browser CORS restrictions
+ *  API keys are now injected server-side from ~/.openroom/config.json.
+ *  The browser never sends or sees API keys. */
 function llmProxyPlugin(): Plugin {
   return {
     name: 'llm-proxy',
     configureServer(server) {
       server.middlewares.use('/api/llm-proxy', async (req, res) => {
-        const targetUrl = req.headers['x-llm-target-url'] as string;
+        // Normalize header values — Node http headers can be string[] for duplicates
+        const getHeader = (name: string): string | undefined => {
+          const val = req.headers[name];
+          if (Array.isArray(val)) return val[0];
+          return val;
+        };
+
+        const targetUrl = getHeader('x-llm-target-url');
         if (!targetUrl) {
           res.writeHead(400, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify({ error: 'Missing X-LLM-Target-URL header' }));
@@ -269,24 +572,78 @@ function llmProxyPlugin(): Plugin {
         req.on('end', async () => {
           try {
             const body = Buffer.concat(chunks).toString();
+            const parsedTargetUrl = parseProxyTargetUrl(targetUrl);
+            if (!parsedTargetUrl) {
+              res.writeHead(400, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ error: 'Invalid target URL' }));
+              return;
+            }
+
+            // Strict SSRF: validate target host BEFORE injecting keys
+            if (!isAllowedTarget(parsedTargetUrl)) {
+              res.writeHead(400, { 'Content-Type': 'application/json' });
+              res.end(
+                JSON.stringify({
+                  error: 'Target host not allowed',
+                  host: parsedTargetUrl.hostname,
+                }),
+              );
+              return;
+            }
             const headers: Record<string, string> = {};
-            // Forward all headers except host/connection/internal ones
-            const skipKeys = new Set(['host', 'connection', 'content-length', 'x-llm-target-url']);
+            // Only forward safe, non-sensitive headers from the browser.
+            // API keys are NO LONGER accepted from the client — they come from server config.
+            const allowKeys = new Set([
+              'content-type',
+              'anthropic-version', // Anthropic API version (not a secret)
+            ]);
             for (const [key, val] of Object.entries(req.headers)) {
               if (typeof val !== 'string') continue;
-              if (skipKeys.has(key)) continue;
-              if (key.startsWith('x-custom-')) {
-                headers[key.replace('x-custom-', '')] = val;
-              } else {
+              if (allowKeys.has(key)) {
                 headers[key] = val;
+              } else if (key.startsWith('x-custom-')) {
+                // Only forward x-custom- headers that map to safe, non-sensitive names
+                const strippedKey = key.slice('x-custom-'.length);
+                // Block headers that could inject auth or override internal routing
+                if (strippedKey && !isBlockedPassthroughHeader(strippedKey)) {
+                  headers[strippedKey] = val;
+                }
               }
+              // All other headers (including authorization and x-api-key) are dropped
             }
 
-            const fetchRes = await fetch(targetUrl, {
-              method: req.method || 'POST',
+            // Inject API key from server-side config
+            injectServerApiKey(
               headers,
-              body,
-            });
+              parsedTargetUrl,
+              getHeader('x-llm-provider'),
+              getHeader('x-llm-config-scope'),
+            );
+
+            const controller = new AbortController();
+            const timeoutMs = 90_000;
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+            let fetchRes: Response;
+            try {
+              fetchRes = await fetch(parsedTargetUrl.toString(), {
+                method: req.method || 'POST',
+                headers,
+                body,
+                signal: controller.signal,
+              });
+            } catch (err) {
+              if (err instanceof Error && err.name === 'AbortError') {
+                res.writeHead(504, { 'Content-Type': 'application/json' });
+                res.end(
+                  JSON.stringify({ error: `Upstream request timed out after ${timeoutMs}ms` }),
+                );
+                return;
+              }
+              throw err;
+            } finally {
+              clearTimeout(timeoutId);
+            }
 
             res.writeHead(fetchRes.status, {
               'Content-Type': fetchRes.headers.get('Content-Type') || 'application/json',
diff --git a/e2e/app.spec.ts b/e2e/app.spec.ts
index 059806c..f2ae429 100644
--- a/e2e/app.spec.ts
+++ b/e2e/app.spec.ts
@@ -101,19 +101,28 @@ test.describe('Chat panel – input interaction', () => {
     await expect(sendBtn).toBeDisabled();
   });
 
-  test('typing a message and clicking send adds it to the messages area', async ({ page }) => {
+  test('typing a message without LLM config opens settings instead of sending', async ({
+    page,
+  }) => {
+    // Stub the config API so the app sees no LLM config (unconfigured state)
+    await page.route('**/api/llm-config', async (route) => {
+      await route.fulfill({
+        contentType: 'application/json',
+        body: '{}',
+      }); // Empty JSON object → no config
+    });
     await page.goto('/');
     const input = page.locator('[data-testid="chat-input"]');
     const sendBtn = page.locator('[data-testid="send-btn"]');
     const messages = page.locator('[data-testid="chat-messages"]');
+    const settingsModal = page.locator('[data-testid="settings-modal"]');
 
     await input.fill('Test message from E2E');
     await sendBtn.click();
 
-    // The user message should appear in the messages area
-    await expect(messages).toContainText('Test message from E2E');
-    // Input should be cleared after sending
-    await expect(input).toHaveValue('');
+    await expect(settingsModal).toBeVisible();
+    await expect(messages).not.toContainText('Test message from E2E');
+    await expect(input).toHaveValue('Test message from E2E');
   });
 });