From 8d670b7713c6a297eb117869c8dd8aeac93384dc Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Wed, 29 Apr 2026 10:53:47 +0900
Subject: [PATCH 01/10] fix micgroup getting overwritten issue

---
 .../src/components/Chat/Chat.module.css       | 106 ++++++++-----
 .../frontend/src/components/Chat/Chat.tsx     |  25 ++-
 .../src/pages/Chat/ChatPage.module.css        | 146 ------------------
 3 files changed, 76 insertions(+), 201 deletions(-)

diff --git a/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css b/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
index ea188fd2..b59cebe0 100644
--- a/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
+++ b/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
@@ -271,31 +271,87 @@
   box-shadow: 0 0 0 2px var(--color-primary-subtle);
 }
 
-/* Mic button + language selector grouped together */
+/* Mic + language selector */
 .micGroup {
   display: flex;
   align-items: center;
-  gap: 2px;
   position: relative;
+  gap: 0;
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-lg);
 }
 
-.langBtn {
+.micCombo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
   background: transparent;
   border: none;
+  color: var(--text-secondary);
+  cursor: pointer;
+  padding: 6px;
+  border-radius: var(--radius-lg) 0 0 var(--radius-lg);
+  outline: none;
+  transition: color 0.15s, background 0.15s;
+}
+
+.micCombo:hover {
   color: var(--text-primary);
+  background: var(--bg-tertiary);
+}
+
+.micCombo.micComboActive {
+  color: var(--color-error, #ef4444);
+}
+
+.micIconWrap {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+}
+
+/* Pulsing ring around mic icon when recording */
+.micPulseRing {
+  position: absolute;
+  inset: -3px;
+  border-radius: 50%;
+  border: 2px solid var(--color-error, #ef4444);
+  animation: micRingPulse 1.4s ease-in-out infinite;
+  pointer-events: none;
+}
+
+@keyframes micRingPulse {
+  0%, 100% { transform: scale(1); opacity: 0.8; }
+  50% { transform: scale(1.25); opacity: 0; }
+}
+
+.langBtn {
+  display: flex;
+  align-items: center;
+  align-self: stretch;
+  background: transparent;
+  border: none;
+  border-left: 1px solid var(--border-primary);
+  color: var(--text-secondary);
   font-size: 10px;
   font-family: inherit;
   font-weight: 600;
   cursor: pointer;
-  padding: 2px 3px;
-  border-radius: var(--radius-sm);
+  padding: 0 8px;
+  border-radius: 0 var(--radius-lg) var(--radius-lg) 0;
   line-height: 1;
   outline: none;
   white-space: nowrap;
+  transition: color 0.15s, background 0.15s;
 }
 
 .langBtn:hover:not(:disabled) {
   background: var(--bg-tertiary);
+  color: var(--text-primary);
 }
 
 .langBtn:disabled {
@@ -303,6 +359,10 @@
   cursor: not-allowed;
 }
 
+.langBtn.langBtnActive {
+  color: var(--color-error, #ef4444);
+}
+
 .langDropdown {
   position: absolute;
   bottom: calc(100% + 6px);
@@ -352,42 +412,6 @@
   opacity: 0.8;
 }
 
-/* 3 bouncing dots shown while listening */
-.listeningDots {
-  display: flex;
-  align-items: center;
-  gap: 4px;
-  padding: 4px var(--space-3) 0;
-}
-
-.listeningDots span {
-  display: block;
-  width: 6px;
-  height: 6px;
-  border-radius: 50%;
-  background: var(--color-primary);
-  animation: dotBounce 1.2s ease-in-out infinite;
-}
-
-.listeningDots span:nth-child(1) { animation-delay: 0s; }
-.listeningDots span:nth-child(2) { animation-delay: 0.2s; }
-.listeningDots span:nth-child(3) { animation-delay: 0.4s; }
-
-@keyframes dotBounce {
-  0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
-  30% { transform: translateY(-5px); opacity: 1; }
-}
-
-/* Mic button pulse animation when recording */
-.micListening {
-  animation: micPulse 1.2s ease-in-out infinite;
-}
-
-@keyframes micPulse {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.4; }
-}
-
 /* Attachment preview modal */
 .previewOverlay {
   position: fixed;
diff --git a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
index 7dc810ab..51fc0480 100644
--- a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
+++ b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
@@ -546,16 +546,19 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
         <IconButton icon={<Paperclip size={18} />} variant="ghost" tooltip="Attach file" onClick={handleAttachClick} />
 
         <div className={styles.micGroup} ref={langDropdownRef}>
-          <IconButton
-            icon={isListening ? <MicOff size={18} /> : <Mic size={18} />}
-            variant="ghost"
-            active={isListening}
-            tooltip={isListening ? 'Stop listening' : 'Voice input'}
+          <button
+            type="button"
+            className={`${styles.micCombo}${isListening ? ` ${styles.micComboActive}` : ''}`}
+            title={isListening ? 'Stop listening' : 'Voice input'}
             onClick={toggleListening}
-            className={isListening ? styles.micListening : undefined}
-          />
+          >
+            <span className={styles.micIconWrap}>
+              {isListening ? <MicOff size={18} /> : <Mic size={18} />}
+              {isListening && <span className={styles.micPulseRing} />}
+            </span>
+          </button>
           <button
-            className={styles.langBtn}
+            className={`${styles.langBtn}${isListening ? ` ${styles.langBtnActive}` : ''}`}
             onClick={() => !isListening && setLangOpen(o => !o)}
             title="Speech language"
             disabled={isListening}
@@ -633,12 +636,6 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
             </div>
           )}
 
-          {isListening && (
-            <div className={styles.listeningDots}>
-              <span /><span /><span />
-            </div>
-          )}
-
           <textarea
             ref={inputRef}
             className={`${styles.input}${isListening ? ` ${styles.inputListening}` : ''}`}
diff --git a/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css b/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css
index 492ddb76..d9c2d34a 100644
--- a/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css
+++ b/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css
@@ -332,152 +332,6 @@
   color: var(--text-muted);
 }
 
-.inputListening {
-  border-color: var(--color-primary);
-  box-shadow: 0 0 0 2px var(--color-primary-subtle);
-}
-
-/* Mic + language selector */
-.micGroup {
-  display: flex;
-  align-items: center;
-  position: relative;
-  gap: 0;
-  border: 1px solid var(--border-primary);
-  border-radius: var(--radius-lg);
-}
-
-.micCombo {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  position: relative;
-  background: transparent;
-  border: none;
-  color: var(--text-secondary);
-  cursor: pointer;
-  padding: 6px;
-  border-radius: var(--radius-lg) 0 0 var(--radius-lg);
-  outline: none;
-  transition: color 0.15s, background 0.15s;
-}
-
-.micCombo:hover {
-  color: var(--text-primary);
-  background: var(--bg-tertiary);
-}
-
-.micCombo.micComboActive {
-  color: var(--color-error, #ef4444);
-}
-
-.micIconWrap {
-  position: relative;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 22px;
-  height: 22px;
-}
-
-/* Pulsing ring around mic icon when recording */
-.micPulseRing {
-  position: absolute;
-  inset: -3px;
-  border-radius: 50%;
-  border: 2px solid var(--color-error, #ef4444);
-  animation: micRingPulse 1.4s ease-in-out infinite;
-  pointer-events: none;
-}
-
-@keyframes micRingPulse {
-  0%, 100% { transform: scale(1); opacity: 0.8; }
-  50% { transform: scale(1.25); opacity: 0; }
-}
-
-.langBtn {
-  display: flex;
-  align-items: center;
-  align-self: stretch;
-  background: transparent;
-  border: none;
-  border-left: 1px solid var(--border-primary);
-  color: var(--text-secondary);
-  font-size: 10px;
-  font-family: inherit;
-  font-weight: 600;
-  cursor: pointer;
-  padding: 0 8px;
-  border-radius: 0 var(--radius-lg) var(--radius-lg) 0;
-  line-height: 1;
-  outline: none;
-  white-space: nowrap;
-  transition: color 0.15s, background 0.15s;
-}
-
-.langBtn:hover:not(:disabled) {
-  background: var(--bg-tertiary);
-  color: var(--text-primary);
-}
-
-.langBtn:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
-}
-
-.langBtn.langBtnActive {
-  color: var(--color-error, #ef4444);
-}
-
-.langDropdown {
-  position: absolute;
-  bottom: calc(100% + 6px);
-  left: 0;
-  background: var(--bg-secondary);
-  border: 1px solid var(--border-primary);
-  border-radius: var(--radius-md);
-  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
-  overflow: hidden;
-  z-index: 999;
-  min-width: 130px;
-}
-
-.langOption {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  width: 100%;
-  background: transparent;
-  border: none;
-  color: var(--text-secondary);
-  font-family: inherit;
-  font-size: var(--text-sm);
-  padding: 7px 12px;
-  cursor: pointer;
-  text-align: left;
-}
-
-.langOption:hover {
-  background: var(--bg-tertiary);
-  color: var(--text-primary);
-}
-
-.langOptionActive {
-  color: var(--color-primary);
-}
-
-.langCode {
-  font-weight: 600;
-  font-size: 11px;
-  width: 36px;
-  flex-shrink: 0;
-}
-
-.langFull {
-  font-size: 11px;
-  opacity: 0.8;
-}
-
 /* Action Panel - Right Side (resizable) */
 .actionPanel {
   display: flex;

From fc0ec80635c50f526e26387e0d2c214668a91ad7 Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Thu, 30 Apr 2026 08:14:02 +0900
Subject: [PATCH 02/10] feature/clear conversation and task function and
 buttons

---
 app/ui_layer/adapters/browser_adapter.py      |  98 +++++++++++++
 app/ui_layer/adapters/tui_adapter.py          |  39 ++++++
 .../src/pages/Settings/GeneralSettings.tsx    | 129 ++++++++++++++++++
 .../pages/Settings/SettingsPage.module.css    |  59 ++++++++
 app/ui_layer/commands/builtin/__init__.py     |   2 +
 app/ui_layer/commands/builtin/clear_tasks.py  |  58 ++++++++
 app/ui_layer/components/protocols.py          |  10 ++
 app/ui_layer/controller/ui_controller.py      |   2 +
 app/usage/action_storage.py                   |  46 +++++++
 9 files changed, 443 insertions(+)
 create mode 100644 app/ui_layer/commands/builtin/clear_tasks.py

diff --git a/app/ui_layer/adapters/browser_adapter.py b/app/ui_layer/adapters/browser_adapter.py
index 68014828..ec66b683 100644
--- a/app/ui_layer/adapters/browser_adapter.py
+++ b/app/ui_layer/adapters/browser_adapter.py
@@ -644,6 +644,57 @@ async def clear(self) -> None:
             "type": "action_clear",
         })
 
+    async def clear_terminal_tasks(self) -> int:
+        """
+        Remove tasks whose status is completed/error/cancelled, along with
+        their child actions. Running/waiting tasks remain visible.
+
+        Returns:
+            Number of tasks removed (does not count child actions).
+        """
+        terminal_statuses = {"completed", "error", "cancelled"}
+
+        # Find terminal task IDs in the in-memory list
+        terminal_task_ids = {
+            item.id
+            for item in self._items
+            if item.item_type == "task" and item.status in terminal_statuses
+        }
+
+        if not terminal_task_ids:
+            return 0
+
+        # Remove the tasks themselves and any actions that belong to them
+        removed_ids = [
+            item.id
+            for item in self._items
+            if item.id in terminal_task_ids or item.parent_id in terminal_task_ids
+        ]
+        self._items = [
+            item
+            for item in self._items
+            if item.id not in terminal_task_ids and item.parent_id not in terminal_task_ids
+        ]
+
+        # Mirror in storage so a refresh doesn't bring them back. We let
+        # storage compute its own ID set rather than pass our list, since
+        # storage may carry tasks not currently loaded in memory.
+        if self._storage:
+            try:
+                self._storage.clear_terminal_tasks()
+            except Exception:
+                pass
+
+        # Tell each connected client to drop the removed items individually,
+        # so any other (running) tasks they're watching stay in place.
+        for item_id in removed_ids:
+            await self._adapter._broadcast({
+                "type": "action_remove",
+                "data": {"id": item_id},
+            })
+
+        return len(terminal_task_ids)
+
     def select_task(self, task_id: Optional[str]) -> None:
         """Select task - handled by frontend."""
         pass
@@ -1314,6 +1365,12 @@ async def _handle_ws_message(self, data: Dict[str, Any], ws=None) -> None:
         elif msg_type == "reset":
             await self._handle_reset()
 
+        elif msg_type == "clear_conversation":
+            await self._handle_clear_conversation()
+
+        elif msg_type == "clear_tasks":
+            await self._handle_clear_tasks()
+
         # Scheduler/Proactive operations
         elif msg_type == "scheduler_config_get":
             await self._handle_scheduler_config_get()
@@ -2853,6 +2910,47 @@ async def _handle_reset(self) -> None:
                 },
             })
 
+    async def _handle_clear_conversation(self) -> None:
+        """
+        Clear the chat conversation log only.
+
+        Drops chat messages from the panel and from chat_storage. The
+        action panel (tasks/actions) is left alone so running tasks are
+        not disrupted. Dashboard usage/task metrics live in a separate
+        database and are not touched.
+        """
+        try:
+            await self._chat.clear()
+            await self._broadcast({
+                "type": "clear_conversation",
+                "data": {"success": True},
+            })
+        except Exception as e:
+            await self._broadcast({
+                "type": "clear_conversation",
+                "data": {"success": False, "error": str(e)},
+            })
+
+    async def _handle_clear_tasks(self) -> None:
+        """
+        Clear only finished tasks (completed/error/cancelled) and their
+        child actions from the panel. Running/waiting tasks are preserved.
+
+        Dashboard usage/task metrics are persisted in a separate database
+        and are not affected.
+        """
+        try:
+            removed = await self._action_panel.clear_terminal_tasks()
+            await self._broadcast({
+                "type": "clear_tasks",
+                "data": {"success": True, "removed": removed},
+            })
+        except Exception as e:
+            await self._broadcast({
+                "type": "clear_tasks",
+                "data": {"success": False, "error": str(e)},
+            })
+
     # ─────────────────────────────────────────────────────────────────────
     # Scheduler/Proactive Operation Handlers
     # ─────────────────────────────────────────────────────────────────────
diff --git a/app/ui_layer/adapters/tui_adapter.py b/app/ui_layer/adapters/tui_adapter.py
index 5cd5fd7a..6a11a7fd 100644
--- a/app/ui_layer/adapters/tui_adapter.py
+++ b/app/ui_layer/adapters/tui_adapter.py
@@ -216,6 +216,45 @@ async def clear(self) -> None:
         self._order.clear()
         await self._adapter.action_updates.put(ActionPanelUpdate("clear", None))
 
+    async def clear_terminal_tasks(self) -> int:
+        """
+        Remove tasks whose status is completed/error/cancelled, along with
+        their child actions. Running/waiting tasks remain visible.
+
+        Returns:
+            Number of tasks removed (does not count child actions).
+        """
+        terminal_statuses = {"completed", "error", "cancelled"}
+
+        terminal_task_ids = {
+            item_id
+            for item_id, item in self._items.items()
+            if item.item_type == "task" and item.status in terminal_statuses
+        }
+
+        if not terminal_task_ids:
+            return 0
+
+        removed_ids = [
+            item_id
+            for item_id, item in list(self._items.items())
+            if item_id in terminal_task_ids or item.task_id in terminal_task_ids
+        ]
+
+        for item_id in removed_ids:
+            self._items.pop(item_id, None)
+        self._order = [iid for iid in self._order if iid not in removed_ids]
+
+        for item_id in removed_ids:
+            await self._adapter.action_updates.put(
+                ActionPanelUpdate(
+                    "remove",
+                    TUIActionItem(id=item_id, display_name="", item_type="", status=""),
+                )
+            )
+
+        return len(terminal_task_ids)
+
     def select_task(self, task_id: Optional[str]) -> None:
         """Select a task for detail view."""
         self._adapter._selected_task_id = task_id
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx
index a5cca7ff..1c32551c 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx
@@ -11,6 +11,8 @@ import {
   RefreshCw,
   Upload,
   Trash2,
+  Eraser,
+  ListChecks,
 } from 'lucide-react'
 import { Button, Badge, ConfirmModal } from '../../components/ui'
 import { useTheme } from '../../contexts/ThemeContext'
@@ -58,6 +60,15 @@ export function GeneralSettings() {
   const [isSaving, setIsSaving] = useState(false)
   const [saveStatus, setSaveStatus] = useState<'idle' | 'success' | 'error'>('idle')
 
+  // Clear Conversation / Clear Tasks state
+  const [isClearingConversation, setIsClearingConversation] = useState(false)
+  const [clearConversationStatus, setClearConversationStatus] =
+    useState<'idle' | 'success' | 'error'>('idle')
+  const [isClearingTasks, setIsClearingTasks] = useState(false)
+  const [clearTasksStatus, setClearTasksStatus] =
+    useState<'idle' | 'success' | 'error'>('idle')
+  const [clearTasksRemoved, setClearTasksRemoved] = useState<number | null>(null)
+
   // Agent profile picture
   const [profilePictureUrl, setProfilePictureUrl] = useState<string>(agentProfilePictureUrl)
   const [hasCustomPicture, setHasCustomPicture] = useState<boolean>(agentProfilePictureHasCustom)
@@ -205,6 +216,22 @@ export function GeneralSettings() {
         setResetStatus(d.success ? 'success' : 'error')
         setTimeout(() => setResetStatus('idle'), 3000)
       }),
+      onMessage('clear_conversation', (data: unknown) => {
+        const d = data as { success: boolean }
+        setIsClearingConversation(false)
+        setClearConversationStatus(d.success ? 'success' : 'error')
+        setTimeout(() => setClearConversationStatus('idle'), 3000)
+      }),
+      onMessage('clear_tasks', (data: unknown) => {
+        const d = data as { success: boolean; removed?: number }
+        setIsClearingTasks(false)
+        setClearTasksStatus(d.success ? 'success' : 'error')
+        setClearTasksRemoved(typeof d.removed === 'number' ? d.removed : null)
+        setTimeout(() => {
+          setClearTasksStatus('idle')
+          setClearTasksRemoved(null)
+        }, 3000)
+      }),
       onMessage('agent_file_read', (data: unknown) => {
         const d = data as { filename: string; content: string; success: boolean }
         if (d.filename === 'USER.md') {
@@ -391,6 +418,30 @@ export function GeneralSettings() {
     })
   }
 
+  const handleClearConversation = () => {
+    confirm({
+      title: 'Clear Conversation',
+      message: 'Clear the chat history? Tasks (including running ones) and dashboard data are preserved.',
+      confirmText: 'Clear',
+      variant: 'danger',
+    }, () => {
+      setIsClearingConversation(true)
+      send('clear_conversation')
+    })
+  }
+
+  const handleClearTasks = () => {
+    confirm({
+      title: 'Clear Tasks',
+      message: 'Remove completed, failed, and aborted tasks from the panel? Running tasks remain visible. Dashboard usage data and task statistics will be preserved.',
+      confirmText: 'Clear',
+      variant: 'danger',
+    }, () => {
+      setIsClearingTasks(true)
+      send('clear_tasks')
+    })
+  }
+
   const handleSaveUserMd = () => {
     setIsSavingUserMd(true)
     send('agent_file_write', { filename: 'USER.md', content: userMdContent })
@@ -632,6 +683,84 @@ export function GeneralSettings() {
         )}
       </div>
 
+      {/* Clear Data Section — compact */}
+      <div className={styles.dangerZone}>
+        <div className={styles.dangerRowList}>
+          <div className={styles.dangerRow}>
+            <Eraser size={16} className={styles.dangerRowIcon} />
+            <div className={styles.dangerRowInfo}>
+              <h4 className={styles.dangerRowTitle}>Clear Conversation</h4>
+              <p className={styles.dangerRowHint}>
+                Remove chat messages. Tasks and dashboard data are preserved.
+              </p>
+            </div>
+            <div className={styles.dangerRowAction}>
+              {clearConversationStatus === 'success' && (
+                <span className={styles.statusSuccess}>
+                  <Check size={14} /> Cleared
+                </span>
+              )}
+              {clearConversationStatus === 'error' && (
+                <span className={styles.statusError}>
+                  <X size={14} /> Failed
+                </span>
+              )}
+              <Button
+                variant="danger"
+                size="sm"
+                onClick={handleClearConversation}
+                disabled={isClearingConversation}
+                icon={
+                  isClearingConversation
+                    ? <Loader2 size={14} className={styles.spinning} />
+                    : <Eraser size={14} />
+                }
+              >
+                {isClearingConversation ? 'Clearing...' : 'Clear'}
+              </Button>
+            </div>
+          </div>
+
+          <div className={styles.dangerRow}>
+            <ListChecks size={16} className={styles.dangerRowIcon} />
+            <div className={styles.dangerRowInfo}>
+              <h4 className={styles.dangerRowTitle}>Clear Tasks</h4>
+              <p className={styles.dangerRowHint}>
+                Remove completed, failed, and aborted tasks. Running tasks and dashboard data are preserved.
+              </p>
+            </div>
+            <div className={styles.dangerRowAction}>
+              {clearTasksStatus === 'success' && (
+                <span className={styles.statusSuccess}>
+                  <Check size={14} />
+                  {clearTasksRemoved !== null
+                    ? ` ${clearTasksRemoved} cleared`
+                    : ' Cleared'}
+                </span>
+              )}
+              {clearTasksStatus === 'error' && (
+                <span className={styles.statusError}>
+                  <X size={14} /> Failed
+                </span>
+              )}
+              <Button
+                variant="danger"
+                size="sm"
+                onClick={handleClearTasks}
+                disabled={isClearingTasks}
+                icon={
+                  isClearingTasks
+                    ? <Loader2 size={14} className={styles.spinning} />
+                    : <ListChecks size={14} />
+                }
+              >
+                {isClearingTasks ? 'Clearing...' : 'Clear'}
+              </Button>
+            </div>
+          </div>
+        </div>
+      </div>
+
       {/* Reset Section */}
       <div className={styles.dangerZone}>
         <div className={styles.dangerHeader}>
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css b/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
index 0666da24..35ba379f 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
@@ -603,6 +603,65 @@
   line-height: 1.5;
 }
 
+/* Compact danger row — for low-risk maintenance actions */
+.dangerRowList {
+  display: flex;
+  flex-direction: column;
+}
+
+.dangerRow {
+  display: grid;
+  grid-template-columns: 18px 1fr auto;
+  align-items: center;
+  column-gap: var(--space-3);
+  padding: var(--space-3) 0;
+}
+
+.dangerRow:first-child {
+  padding-top: var(--space-1);
+}
+
+.dangerRow:last-child {
+  padding-bottom: var(--space-1);
+}
+
+.dangerRow + .dangerRow {
+  border-top: 1px solid rgba(239, 68, 68, 0.15);
+}
+
+.dangerRowIcon {
+  align-self: start;
+  margin-top: 2px;
+  color: var(--color-red);
+}
+
+.dangerRowInfo {
+  min-width: 0;
+}
+
+.dangerRowTitle {
+  font-size: var(--text-sm);
+  font-weight: var(--font-semibold);
+  color: var(--color-red);
+  margin: 0 0 2px 0;
+  line-height: 1.2;
+}
+
+.dangerRowHint {
+  font-size: var(--text-xs);
+  color: var(--text-secondary);
+  margin: 0;
+  line-height: 1.4;
+}
+
+.dangerRowAction {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--space-2);
+  min-width: 96px;
+}
+
 /* Status Messages */
 .statusSuccess {
   display: inline-flex;
diff --git a/app/ui_layer/commands/builtin/__init__.py b/app/ui_layer/commands/builtin/__init__.py
index 75a79eed..08f7eb79 100644
--- a/app/ui_layer/commands/builtin/__init__.py
+++ b/app/ui_layer/commands/builtin/__init__.py
@@ -2,6 +2,7 @@
 
 from app.ui_layer.commands.builtin.help import HelpCommand
 from app.ui_layer.commands.builtin.clear import ClearCommand
+from app.ui_layer.commands.builtin.clear_tasks import ClearTasksCommand
 from app.ui_layer.commands.builtin.reset import ResetCommand
 from app.ui_layer.commands.builtin.exit import ExitCommand
 from app.ui_layer.commands.builtin.menu import MenuCommand
@@ -17,6 +18,7 @@
 __all__ = [
     "HelpCommand",
     "ClearCommand",
+    "ClearTasksCommand",
     "ResetCommand",
     "ExitCommand",
     "MenuCommand",
diff --git a/app/ui_layer/commands/builtin/clear_tasks.py b/app/ui_layer/commands/builtin/clear_tasks.py
new file mode 100644
index 00000000..1a49b51b
--- /dev/null
+++ b/app/ui_layer/commands/builtin/clear_tasks.py
@@ -0,0 +1,58 @@
+"""Clear-tasks command implementation."""
+
+from __future__ import annotations
+
+from typing import List
+
+from app.ui_layer.commands.base import Command, CommandResult
+
+
+class ClearTasksCommand(Command):
+    """Clear finished tasks (completed/failed/aborted) from the action panel."""
+
+    @property
+    def name(self) -> str:
+        return "/clear-tasks"
+
+    @property
+    def aliases(self) -> List[str]:
+        return ["/cleartasks"]
+
+    @property
+    def description(self) -> str:
+        return "Remove completed, failed, and aborted tasks from the panel"
+
+    @property
+    def help_text(self) -> str:
+        return (
+            "Remove tasks whose status is completed, error, or cancelled "
+            "(failed/aborted) from the action panel, along with their child "
+            "actions. Running and waiting tasks are preserved.\n\n"
+            "Dashboard usage data and task history are not affected."
+        )
+
+    async def execute(
+        self,
+        args: List[str],
+        adapter_id: str = "",
+    ) -> CommandResult:
+        """Execute the clear-tasks command."""
+        adapter = self._controller.active_adapter
+        if not adapter or not adapter.action_panel:
+            self.emit_message(
+                "No action panel is available in this interface.",
+                "error",
+            )
+            return CommandResult(success=False)
+
+        removed = await adapter.action_panel.clear_terminal_tasks()
+
+        if removed:
+            self.emit_message(
+                f"Cleared {removed} finished task{'s' if removed != 1 else ''} from the panel.",
+                "system",
+            )
+        else:
+            self.emit_message("No finished tasks to clear.", "system")
+
+        return CommandResult(success=True)
diff --git a/app/ui_layer/components/protocols.py b/app/ui_layer/components/protocols.py
index cb608fbd..3a297e38 100644
--- a/app/ui_layer/components/protocols.py
+++ b/app/ui_layer/components/protocols.py
@@ -125,6 +125,16 @@ async def clear(self) -> None:
         """Clear all items from the panel."""
         ...
 
+    async def clear_terminal_tasks(self) -> int:
+        """
+        Remove tasks whose status is completed/error/cancelled, along with
+        their child actions. Running/waiting tasks are preserved.
+
+        Returns:
+            Number of items removed.
+        """
+        ...
+
     def select_task(self, task_id: Optional[str]) -> None:
         """
         Select a task for detail view.
diff --git a/app/ui_layer/controller/ui_controller.py b/app/ui_layer/controller/ui_controller.py
index d06e9729..de7bc95e 100644
--- a/app/ui_layer/controller/ui_controller.py
+++ b/app/ui_layer/controller/ui_controller.py
@@ -540,6 +540,7 @@ def _register_builtin_commands(self) -> None:
         from app.ui_layer.commands.builtin import (
             HelpCommand,
             ClearCommand,
+            ClearTasksCommand,
             ResetCommand,
             ExitCommand,
             MenuCommand,
@@ -552,6 +553,7 @@ def _register_builtin_commands(self) -> None:
 
         self._command_registry.register(HelpCommand(self))
         self._command_registry.register(ClearCommand(self))
+        self._command_registry.register(ClearTasksCommand(self))
         self._command_registry.register(ResetCommand(self))
         self._command_registry.register(ExitCommand(self))
         self._command_registry.register(MenuCommand(self))
diff --git a/app/usage/action_storage.py b/app/usage/action_storage.py
index 1c41c154..5dd49e46 100644
--- a/app/usage/action_storage.py
+++ b/app/usage/action_storage.py
@@ -335,6 +335,52 @@ def clear_items(self) -> int:
             conn.commit()
             return count
 
+    def clear_terminal_tasks(self) -> List[str]:
+        """
+        Delete tasks whose status is completed/error/cancelled, plus all
+        their child actions. Running/waiting tasks are preserved so the
+        user can keep monitoring active work.
+
+        Returns:
+            List of removed item IDs (terminal tasks + their child actions).
+        """
+        terminal_statuses = ("completed", "error", "cancelled")
+        with sqlite3.connect(self._db_path) as conn:
+            cursor = conn.cursor()
+
+            placeholders = ",".join("?" for _ in terminal_statuses)
+            cursor.execute(
+                f"""
+                SELECT id FROM action_items
+                WHERE item_type = 'task' AND status IN ({placeholders})
+                """,
+                terminal_statuses,
+            )
+            terminal_task_ids = [row[0] for row in cursor.fetchall()]
+
+            if not terminal_task_ids:
+                return []
+
+            id_placeholders = ",".join("?" for _ in terminal_task_ids)
+            cursor.execute(
+                f"""
+                SELECT id FROM action_items
+                WHERE id IN ({id_placeholders}) OR parent_id IN ({id_placeholders})
+                """,
+                terminal_task_ids + terminal_task_ids,
+            )
+            removed_ids = [row[0] for row in cursor.fetchall()]
+
+            cursor.execute(
+                f"""
+                DELETE FROM action_items
+                WHERE id IN ({id_placeholders}) OR parent_id IN ({id_placeholders})
+                """,
+                terminal_task_ids + terminal_task_ids,
+            )
+            conn.commit()
+            return removed_ids
+
     def delete_item(self, item_id: str) -> bool:
         """
         Delete an item by ID.

From 0b9138ba70388209c149d561273050e4d07aa078 Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Wed, 6 May 2026 05:13:37 +0900
Subject: [PATCH 03/10] Update AGENT.md

---
 app/data/agent_file_system_template/AGENT.md | 4663 +++++++++++++++++-
 1 file changed, 4523 insertions(+), 140 deletions(-)

diff --git a/app/data/agent_file_system_template/AGENT.md b/app/data/agent_file_system_template/AGENT.md
index 910a24a6..ea03f0da 100644
--- a/app/data/agent_file_system_template/AGENT.md
+++ b/app/data/agent_file_system_template/AGENT.md
@@ -1,152 +1,4535 @@
-# Agent Identity
-
-You are a general-purpose personal assistant AI agent developed by CraftOS.
-Your primary role is to assist users with ANY computer-based tasks. You can execute commands, manipulate files, browse the web, interact with applications, and complete complex multi-step workflows autonomously.
-You are not a chatbot. You are an autonomous agent that takes actions to accomplish goals. When given a task, you plan, execute, validate, and iterate until the goal is achieved or you determine it cannot be completed.
-
-## Error Handling
-
-Errors are normal. How you handle them determines success.
-- When an action fails, first understand why. Check the error message and the event stream. Is it a temporary issue that might succeed on retry? Is it a fundamental problem with your approach? Is it something outside your control?
-- For temporary failures (network issues, timing problems), a retry may work. But do not retry blindly - wait a moment, or try with slightly different parameters.
-- For approach failures (wrong action, incorrect parameters, misunderstanding of the task), change your approach. Select a different action or reformulate your plan.
-- For impossible tasks (required access you do not have, physical actions needed, policy violations), stop and inform the user. Explain what you tried, why it cannot work, and suggest alternatives if any exist.
-- If you find yourself stuck in a loop - the same action failing repeatedly with the same error - recognize this pattern and break out. Either try a fundamentally different approach or inform the user that you are blocked.
-- Never continue executing actions indefinitely when they are not making progress. This wastes resources and frustrates users.
-
-## File Handling
-
-Efficient File Reading:
-- read_file returns content with line numbers (cat -n format)
-- Default limit is 2000 lines - check has_more in response to know if file continues
-- For large files (>500 lines), follow this strategy:
-  1. Read beginning first to understand structure
-  2. Use grep_files to find specific patterns/functions
-  3. Use read_file with offset/limit to read targeted sections based on grep results
-
-File Actions:
-- read_file: General reading with pagination (offset/limit)
-- grep_files: Search files/directories for regex patterns with three output modes: 'files_with_matches' (discover files), 'content' (matching lines with line numbers), 'count' (match counts). Supports glob/file_type filtering, before/after context lines, case_insensitive, and multiline.
-- stream_read + stream_edit: Use together for file modifications
-
-Avoid: Reading entire large files repeatedly - use grep + targeted offset/limit reads instead
-
-## Self-Improvement Protocol
-
-You are a self-improving agent. When you encounter a capability gap, proactively expand your abilities using the following mechanisms.
-
-### Self-Improvement Workflow
-When you CANNOT complete a task due to missing capabilities:
-1. IDENTIFY - What capability is missing?
-2. SEARCH - Use `web_search` to find MCP servers or skills that provide the capability
-3. INSTALL - Edit config files or clone repositories to install the solution
-4. WAIT - The system will automatically detect the file change and hot-reload the new capability
-5. CONTINUE - Proceed with the task using the new capability
-6. REMEMBER - Store the solution in memory for future reference
-
-IMPORTANT: Always inform the user when you install new capabilities. Ask for permission if the installation requires credentials or has security implications.
-
-### Automatic Hot-Reload
-All configuration files are monitored for changes. When you edit any config file, the system automatically detects the change and reloads the configuration within ~1 second. No manual reload actions or restart required.
-
-Monitored config files:
-- `app/config/settings.json` - Settings (API keys, model config, OAuth credentials)
-- `app/config/mcp_config.json` - MCP server connections
-- `app/config/skills_config.json` - Skill configurations
-- `app/config/external_comms_config.json` - Communication platform integrations
-
-### 1. MCP - Install New Tools
-Config file: `app/config/mcp_config.json`
-
-When you lack a capability (e.g., cannot access a service, need a specific tool):
-1. Use `read_file` to check existing MCP servers in `app/config/mcp_config.json`
-2. Use `web_search` to find MCP servers: search "<capability> MCP server" or "modelcontextprotocol <service>"
-3. Use `stream_edit` to add new server entry to the `mcp_servers` array in `app/config/mcp_config.json`
-4. Set `"enabled": true` to activate the server
-5. The system will automatically detect the change and connect to the new server
-
-MCP server entry format:
-```json
-{
-  "name": "server-name",
-  "description": "What this server does",
-  "transport": "stdio",
-  "command": "npx",
-  "args": ["-y", "@org/server-package"],
-  "env": {"API_KEY": ""},
-  "enabled": true
+---
+version: 3
+purpose: agent operations manual
+---
+
+# AGENT.md
+
+Your ops manual. Grep `## <topic>` to load what you need.
+
+## Index
+
+<!-- index -->
+```
+add MCP server          → ## MCP
+add skill               → ## Skills
+connect platform        → ## Integrations
+switch model            → ## Models
+set API key             → ## Models
+generate document       → ## Documents
+build Living UI         → ## Living UI
+schedule recurring task → ## Proactive
+edit config file        → ## Configs
+start a task            → ## Tasks
+handle an error         → ## Errors
+read / edit a file      → ## Files
+discover an action      → ## Actions
+persistent storage      → ## File System
+long-running work       → ## Workspace
+self-improve            → ## Self-Improvement
+edit AGENT/USER/SOUL.md → ## Self-Edit
+look up a term          → ## Glossary
+```
+<!-- /index -->
+
+---
+
+## Runtime
+
+You run inside `AgentBase.react(trigger)` at [app/agent_base.py](app/agent_base.py). Each turn: one trigger is consumed, the LLM picks one or more actions, the executor runs them, events are appended to streams, and (often) a new trigger is queued for the next turn.
+
+### Trigger anatomy
+
+Triggers live in a priority queue at [agent_core/core/impl/trigger/queue.py](agent_core/core/impl/trigger/queue.py), ordered by `fire_at` (Unix timestamp) then `priority` (lower number = higher priority). Each trigger carries:
+
+```
+fire_at:                  float    when it should fire
+priority:                 int      ordering within same fire_at
+next_action_description:  str      human-readable hint
+payload:                  dict     routing + context
+session_id:               str|None which session/task this belongs to
+waiting_for_reply:        bool     paused for user input
+```
+
+`payload.type` is the routing key:
+```
+"memory_processing"   → memory workflow      (creates a memory-processor task)
+"proactive_heartbeat" → proactive heartbeat  (creates a Heartbeat task)
+"proactive_planner"   → proactive planner    (creates a day/week/month planner task)
+<absent or other>     → falls through to task / conversation routing by session state
+```
+
+Trigger producers:
+- The scheduler ([app/config/scheduler_config.json](app/config/scheduler_config.json)) — fires `memory_processing`, `proactive_heartbeat`, `proactive_planner` on cron.
+- External-comms listeners and the UI — fire triggers carrying user messages in the payload.
+- Actions you invoke — `wait`, `task_end`, and others enqueue follow-up triggers via `triggers.put(...)`.
+
+### react() routing (in order)
+
+```
+1.  _is_memory_trigger(trigger)        → _handle_memory_workflow         → return
+2.  _is_proactive_trigger(trigger)     → _handle_proactive_workflow      → return
+3.  _extract_trigger_data(trigger)
+4.  _initialize_session(...)
+5.  record user_message in trigger payload (if any) into the event stream
+6.  if active task is waiting_for_user_reply AND no user_message arrived
+        → re-queue the trigger with a 3-hour delay → return
+7.  _is_complex_task_mode(session)     → _handle_complex_task_workflow
+8.  _is_simple_task_mode(session)      → _handle_simple_task_workflow
+9.  default                            → _handle_conversation_workflow
+```
+
+Steps 7-9 share the same shape: `_select_action` (LLM picks actions; session caching for cache hits) → `_retrieve_and_prepare_actions` → `_execute_actions` → `_finalize_action_execution`. The differences are session state, todo handling, and caching strategy.
+
+### Workflows
+
+**memory** — `_handle_memory_workflow`
+- Trigger source: scheduler `memory-processing` (daily 3am) or startup replay if EVENT_UNPROCESSED.md is non-empty.
+- Behavior: spawns a task that uses the `memory-processor` skill. The task reads EVENT_UNPROCESSED.md, scores events, distills important ones into MEMORY.md, clears the buffer. May also prune MEMORY.md if `max_items` is exceeded.
+- During this task, `event_stream_manager.set_skip_unprocessed_logging(True)` is on, so the task's own events do not loop back into EVENT_UNPROCESSED.md. Reset on `task_end`.
+- Skipped entirely if `is_memory_enabled()` is False.
+- See `## Memory`.
+
+**proactive heartbeat** — `_handle_proactive_heartbeat`
+- Trigger source: scheduler `heartbeat` (cron `0,30 * * * *`).
+- Behavior: `proactive_manager.get_all_due_tasks()` collects due recurring tasks across all frequencies. If none, returns silently. Otherwise creates one `Heartbeat` task: `mode=simple`, `action_sets=[file_operations, proactive, web_research]`, `skill=heartbeat-processor`.
+- Skipped entirely if `is_proactive_enabled()` is False.
+- See `## Proactive`.
+
+**proactive planner** — `_handle_proactive_planner`
+- Trigger source: scheduler `day-planner` (daily 7am), `week-planner` (Sun 5pm), `month-planner` (1st 8am).
+- Behavior: creates a task named `<Day|Week|Month> Planner`, mode=simple, action_sets=[file_operations, proactive], skill=`<scope>-planner`. Task instruction: review recent interactions and update the Goals/Plan/Status section of PROACTIVE.md.
+
+**complex task** — `_handle_complex_task_workflow`
+- Active when a task exists for the session and `task.is_simple_task() == False`.
+- Full todo state machine; user-approval gate at the end. Session caching enabled for multi-turn efficiency. Parallel action execution supported.
+- See `## Tasks` for the full lifecycle.
+
+**simple task** — `_handle_simple_task_workflow`
+- Active when a task exists for the session and `task.is_simple_task() == True`.
+- Same select→prepare→execute→finalize flow as complex; no todos; auto-ends. Session caching enabled.
+
+**conversation** — `_handle_conversation_workflow`
+- Active when no task is running for the session.
+- Same flow as simple/complex but uses prefix caching only (no session cache). Supports parallel `task_start` to launch multiple tasks at once.
+- If the executed actions return a `task_id`, the session adopts that task and subsequent triggers route to the task workflow.
+
+### Re-entry and waiting
+
+Calling `wait` or having a task in `waiting_for_user_reply` does not block the loop — it queues a trigger with `fire_at` in the future. When that trigger fires:
+- If the wait was for a user reply and one arrived → process normally.
+- If no user message arrived but the task is still flagged `waiting_for_user_reply` → react re-queues the trigger with a fresh 3-hour delay and returns. The agent silently waits without consuming context.
+
+### Components attached at construction
+
+You do not call these directly, but every action routes through them. Knowing what owns what helps you debug:
+
+```
+LLMInterface           text + vision generation gateway
+ActionLibrary          DB-backed action storage (atomic + divisible)
+ActionManager          action lifecycle
+ActionRouter           LLM-based action selection
+ActionExecutor         sandboxed (ephemeral venv) or internal execution
+TaskManager            task lifecycle, per-task event streams, session storage
+StateManager           session state, current_task_id, current_task
+ContextEngine          builds system + user prompt each turn (KV cache aware)
+MemoryManager          ChromaDB-backed RAG over agent_file_system
+EventStreamManager     appends to EVENT.md / EVENT_UNPROCESSED.md / per-task streams
+MCPClient              external MCP tool servers
+SkillManager           SKILL.md discovery + selection + reload
+Scheduler              cron-driven trigger fires from scheduler_config.json
+ProactiveManager       PROACTIVE.md registry + get_all_due_tasks()
+ExternalCommsManager   platform listeners + senders
+WorkflowLockManager    blocks concurrent memory / proactive runs
+```
+
+### Workflow locks
+
+[agent_core/core/impl/workflow_lock/manager.py](agent_core/core/impl/workflow_lock/manager.py) gates concurrent runs of background workflows. Lock names in use:
+
+```
+"memory_processing"        only one memory-processor task at a time
+"proactive_*"              one proactive workflow per scope at a time
+```
+
+If a trigger fires while its lock is held, the new trigger is dropped silently. The next scheduled fire will pick up the work. This is by design — do not work around it.
+
+### State and context every turn
+
+What the LLM sees on each `_select_action` call:
+- Static system prompt (your role, policy, file-system map, environment).
+- The relevant slice of the event stream (recent actions, results, user messages).
+- Memory pointers retrieved by the ContextEngine for relevance.
+- Current task state if a task is active (instruction, todos, action sets, skills selected).
+- The list of currently available actions (filtered by selected action sets and current mode).
+
+Knowing this shape helps you decide what context to enrich. Need history beyond what's in the stream? Use `memory_search` (`## Memory`) or read TASK_HISTORY.md / CONVERSATION_HISTORY.md directly (`## File System`).
+
+---
+
+## Tasks
+
+Three runtime modes route through this section: **conversation**, **simple**, **complex**. Each has a distinct purpose, action surface, and starting move.
+
+### Conversation mode
+
+Active when **no task is running** for the session. Default state when a user message arrives in a fresh session.
+
+Action surface in conversation mode is intentionally small ([agent_core/core/prompts/action.py](agent_core/core/prompts/action.py)):
+```
+task_start(...)        begin a task — THE way user requests become work
+send_message(...)      reply without starting a task
+ignore                 user input needs no reply (e.g. emoji-only ack)
+```
+
+You CANNOT call file ops, web search, MCP tools, integrations, or skills directly from conversation mode. To unlock them, start a task first.
+
+You MAY emit multiple `task_start` actions in parallel from a single conversation turn. Example: user says "research topic A and topic B" → two parallel `task_start` calls, one per topic.
+
+When to stay in conversation mode:
+- Greeting, small talk, clarifying question.
+- Acknowledging a user message that needs no work.
+- Routing decisions where the user must confirm before any task starts (e.g. "do you want me to delete X?").
+
+When to leave conversation mode (call `task_start`):
+- ANY request that needs file access, web, MCP, skills, integrations, or memory beyond what's in your current context.
+- Even if you "think" you know the answer — if the request is computer-based and could benefit from verification, start a task. Do not refuse a task by claiming a limitation without checking.
+
+### Starting a task: `task_start` vs `schedule_task`
+
+```
+From conversation (no active task)  →  task_start(task_name, task_description, task_mode)
+From inside a task (simple/complex) →  schedule_task(name, instruction, schedule="immediate", mode, ...)
+For later / recurring execution     →  schedule_task(name, instruction, schedule="<expr>", ...)
+```
+
+**`task_start` cannot be called from inside another task.** If you're mid-task and need to spawn a separate one, use `schedule_task` with `schedule="immediate"`. The two actions create equivalent task objects — the difference is the entry point.
+
+`schedule_task` schedule expressions (validated by [app/scheduler/parser.py](app/scheduler/parser.py)):
+```
+"immediate"               run right now (queues an immediate trigger)
+"at 3pm" / "at 3:30pm"    one-time today
+"tomorrow at 9am"         one-time tomorrow
+"in 2 hours" / "in 30 minutes"    one-time relative
+"every day at 7am"        recurring daily
+"every monday at 9am"     recurring weekly
+"every 3 hours"           recurring interval
+"0 7 * * *"               cron (5-field)
+```
+Times must include `am`/`pm`. Freeform like "daily at", "weekly", "every morning", "every weekday" are NOT accepted.
+
+One-time scheduled tasks are auto-removed after firing. Recurring schedules persist in [app/config/scheduler_config.json](app/config/scheduler_config.json).
+
+### Simple mode
+
+Use for work completable in 2-3 actions where no user approval is required at the end.
+
+Pick simple when:
+- Quick lookup (weather, time, exchange rate).
+- Single-answer question (calculation, conversion).
+- Search and summarize where the result is the response.
+- No file the user must review.
+- No irreversible external action (no sends, no payments, no destructive writes).
+
+Flow:
+```
+1. task_start(task_mode="simple", ...)            ← from conversation
+   OR schedule_task(mode="simple", schedule="immediate", ...)  ← from inside a task
+2. (optional) send_message — brief ack
+3. Execute the 1-3 actions
+4. send_message — deliver the result
+5. task_end                                       ← auto-completes, no approval gate
+```
+
+Simple-mode rules:
+- No `task_update_todos`. No phase prefixes. The work is small enough that planning would slow you down.
+- Session caching IS active during simple-mode multi-turn execution (cache hits across the 2-3 turns).
+- If during execution you discover the work is bigger than simple — STOP. End the simple task with the partial result via `send_message` + `task_end`. Then `schedule_task(schedule="immediate", mode="complex")` for the remainder. Do NOT silently chain more actions in simple mode.
+
+### Complex mode
+
+Use for multi-step work, file outputs, irreversible operations, anything the user calls a "project", or anything spanning multiple sessions.
+
+Pick complex when:
+- Plan has more than 3 actions.
+- Output is a file or artifact the user should review and approve.
+- Work touches external state (sends messages, makes purchases, modifies third-party data).
+- Work spans multiple sessions or days (mission-scale — see `## Workspace`).
+
+State machine:
+```
+task_start(task_mode="complex", ...)             ← from conversation
+   OR schedule_task(mode="complex", schedule="immediate", ...)  ← from inside a task
+       │
+       ▼
+send_message                                      ← acknowledge IMMEDIATELY
+       │
+       ▼
+task_update_todos(<full plan, all "pending", phase-prefixed>)
+       │
+       ▼
+loop {
+    mark ONE todo "in_progress"
+    execute relevant actions (parallel within the same todo is fine)
+    mark that todo "completed"
+    if you discover missing info → add a fresh "Collect:" todo, revert
 }
+       │
+       ▼
+send_message(<final result + explicit approval request>)
+       │
+       ▼
+wait for user reply  ← queues a future trigger; you do NOT block, see ## Runtime
+       │
+       ▼
+task_end                                          ← only after explicit approval
 ```
 
-Common patterns:
-- NPX packages: `"command": "npx", "args": ["-y", "@modelcontextprotocol/server-name"]`
-- Python servers: `"command": "uv", "args": ["run", "--directory", "/path/to/server", "main.py"]`
-- HTTP/SSE servers: `"transport": "sse", "url": "http://localhost:3000/mcp"`
-
-### 2. Skill - Install Workflows and Instructions
-Config file: `app/config/skills_config.json`
-Skills directory: `skills/`
-
-When you need specialized workflows or domain knowledge:
-1. Use `read_file` to check `app/config/skills_config.json` for existing skills
-2. Use `web_search` to find skills: search "SKILL.md <domain>" or "<capability> agent skill github"
-3. Use `run_shell` to clone the skill repository into the `skills/` directory:
-   `git clone https://github.com/user/skill-repo skills/skill-name`
-4. Use `stream_edit` to add the skill name to `enabled_skills` array in `app/config/skills_config.json`
-5. The system will automatically detect the change and load the new skill
-
-### 3. App - Configure Integrations
-Config file: `app/config/external_comms_config.json`
-
-When you need to connect to communication platforms:
-1. Use `read_file` to check current config in `app/config/external_comms_config.json`
-2. Use `stream_edit` to update the platform configuration:
-   - Set required credentials (bot_token, api_key, phone_number, etc.)
-   - Set `"enabled": true` to activate
-3. The system will automatically detect the change and start/stop platform connections
-
-Supported platforms:
-- Telegram: bot mode (bot_token) or user mode (api_id, api_hash, phone_number)
-- WhatsApp: web mode (session_id) or API mode (phone_number_id, access_token)
-
-### 4. Model & API Keys - Configure Providers
-Config file: `app/config/settings.json`
-
-When you need different model capabilities or need to set API keys:
-1. Use `read_file` to check current settings in `app/config/settings.json`
-2. If the target model has no API key, you MUST ask the user for one. Without a valid API key, all LLM requests will fail.
-3. Use `stream_edit` to update model configuration and/or API keys:
-```json
+### Todo phase prefixes (mandatory in complex mode)
+
+Every todo must begin with one of these prefixes:
+```
+Acknowledge:   Restate the user's goal in your own words
+Collect:       Gather inputs (read files, search, ask user, list integrations)
+Execute:       Do the work (generate, transform, send, write)
+Verify:        Check the output meets the goal (re-read files, run tests, smoke-test)
+Confirm:       Present the result to the user for approval
+Cleanup:       Remove temp files, restore state, close connections
+```
+
+Rules:
+- Exactly ONE todo `in_progress` at a time. Always.
+- Never skip Verify on todos that produce files or change external state.
+- Never reach Cleanup before Confirm has been signed off by the user.
+- If during Execute you discover missing info, add a new `Collect:` todo and revert. Do not guess.
+- Cleanup is also where you remove `workspace/tmp/{task_id}/` artifacts you do not want to persist (the directory is auto-cleaned anyway, but explicit cleanup catches files saved elsewhere).
+
+### Action sets and skills (locked at task start)
+
+When a task is created via `task_start` or `schedule_task`, action sets and skills are selected automatically by the LLM based on the task description ([app/internal_action_interface.py](app/internal_action_interface.py) `do_create_task`). If the task was started via a skill slash command (e.g. `/pdf`), the pre-selected skill bypasses LLM skill selection but action sets are still LLM-selected and merged with skill-recommended ones.
+
+Once the task starts, the selection is **locked**. Mid-task changes:
+- Action sets: `action_set_management` action can add/remove sets.
+- Skills: cannot be swapped mid-task. End the task and start a new one if you need a different skill.
+
+### Output destinations
+
+- Files the user should keep across sessions → `agent_file_system/workspace/`
+- Drafts, sketches, intermediate state → `agent_file_system/workspace/tmp/{task_id}/` (auto-cleaned on `task_end` and on agent start)
+- Mission-scale, multi-task initiatives → `agent_file_system/workspace/missions/<mission_name>/INDEX.md`
+
+See `## Workspace` for the mission template and scan-on-start protocol.
+
+### Common task-mode mistakes to avoid
+
+- Starting in **simple**, work grows mid-task → do NOT silently chain more actions. End simple, schedule complex.
+- Calling `task_start` **from inside a task** → it doesn't work that way. Use `schedule_task` instead.
+- Using `schedule_task("immediate")` **from conversation** → use `task_start`. Conversation is built around it; using `schedule_task` from conversation creates an extra trigger hop.
+- Calling `task_end` **without a final `send_message`** → simple tasks must deliver the result; complex tasks must summarize and request approval. Never end silently.
+- Marking todos `completed` **before the actions ran** → mark `in_progress`, run, then mark `completed`.
+- Adding planning todos like `Acknowledge: Plan the work` to simple tasks → simple tasks do not use todos at all.
+
+---
+
+## Communication Rules
+
+The user only sees what you send via `send_message` (or `send_message_with_attachment`). Everything else — actions, errors, internal reasoning — is invisible to them.
+
+Cadence:
+- **Acknowledge immediately** after `task_start`. One sentence is enough. Don't wait for the first action to complete.
+- **Update on milestones**, not on every action. A milestone is: phase transition (Collect → Execute), significant finding, blocker, request for input.
+- **Stay silent during tight Verify loops.** If you're re-reading a file three times to check formatting, do not narrate each read.
+- **Final message before `task_end`** must summarize what was done, list any artifacts (with paths), and explicitly request approval.
+
+Channel choice:
+- Default: in-context chat.
+- If the user has a `Preferred Messaging Platform` set in `USER.md` and the task is asynchronous (proactive task, scheduled completion), prefer that platform.
+- Use `send_message_with_attachment` when sending generated files; pass the workspace path.
+
+What NOT to send:
+- Internal reasoning ("I'm now thinking about...").
+- Tool-call narration ("Let me run grep_files...").
+- Repeated acknowledgements after the first.
+- Status pings during fast operations.
+
+Hard rules:
+- Never end a complex task without explicit approval.
+- Never end any task silently.
+- Never claim success when an action failed — see `## Errors`.
+
+---
+
+## Errors
+
+You operate inside a harness with multiple safety layers. Some failures are handled automatically; others require you to recover deliberately. Knowing which is which is the difference between a productive recovery and an infinite loop.
+
+### Action result schema (read this first)
+
+EVERY action — built-in, MCP-routed, or skill-spawned — returns a dict with at minimum:
+
+```
 {
-  "model": {
-    "llm_provider": "anthropic",
-    "vlm_provider": "anthropic",
-    "llm_model": "claude-sonnet-4-20250514",
-    "vlm_model": "claude-sonnet-4-20250514"
-  },
-  "api_keys": {
-    "openai": "sk-...",
-    "anthropic": "sk-ant-...",
-    "google": "...",
-    "byteplus": "..."
-  }
+  "status": "success" | "error",
+  "message": "<human-readable detail>",     # present on error, often present on success
+  ... action-specific output fields ...
 }
 ```
-4. The system will automatically detect the change and update settings (model changes take effect in new tasks)
 
-Available providers: openai, anthropic, gemini, byteplus, remote (Ollama)
+Before you treat an action's output as a result you can act on, **check `status`**. If `status == "error"`, the `message` field tells you what went wrong. Failing to check `status` and proceeding as if everything worked is the most common avoidable failure mode in this harness.
+
+### Error event kinds in the event stream
+
+The event stream ([agent_core/core/impl/event_stream/manager.py](agent_core/core/impl/event_stream/manager.py)) records errors in distinct event kinds. You will see these when reviewing your own past steps:
+
+```
+"error"          react-level errors. LLM failures, exceptions in workflow handlers.
+                 Display message comes from classify_llm_error() (see below).
+"action_error"   actions DROPPED before execution: parallel-constraint violations,
+                 missing actions, invalid decisions.
+                 (Distinct from an action that ran and returned status=error.)
+"warning"        soft warnings that you must heed:
+                 - Action limit at 80% / 100%
+                 - Token limit at 80% / 100%
+                 - Other harness alerts
+"internal"       limit-choice messages, system-side info.
+```
+
+When you see an `"error"` or `"action_error"` event in the stream, it has already been logged. You do NOT need to log it again. You DO need to react to it.
+
+### Harness-level safety nets (do not duplicate)
+
+The harness already handles certain failures so you do not have to. Recognizing them prevents you from stepping on the harness.
+
+**Per-action timeout** ([agent_core/core/impl/action/executor.py](agent_core/core/impl/action/executor.py))
+- Default `DEFAULT_ACTION_TIMEOUT = 6000` seconds (100 min). Individual actions may declare shorter timeouts.
+- On timeout, the action returns:
+  ```
+  {"status": "error", "message": "Execution timed out after Ns while running <internal|sandboxed> action."}
+  ```
+- Recovery: the timeout is final for that invocation. Either retry with smaller scope (fewer rows, narrower regex, smaller batch) or split the work into multiple actions.
+
+**LLM consecutive-failure circuit breaker** ([agent_core/core/impl/llm/errors.py](agent_core/core/impl/llm/errors.py), [agent_core/core/impl/llm/interface.py](agent_core/core/impl/llm/interface.py))
+- After repeated consecutive LLM failures (auth, network, etc.), the harness raises `LLMConsecutiveFailureError`.
+- `_handle_react_error` walks the exception chain (`__cause__`/`__context__`) to detect this and **automatically cancels the task** via `task_manager.mark_task_cancel(...)`. The agent's last instruction is cached in `_llm_retry_instructions[session_id]` for retry-after-fix.
+- A `LLM_FATAL_ERROR` UI event is emitted so the user sees a clear failure dialog.
+- **Implication:** if you see `MSG_CONSECUTIVE_FAILURE` ("LLM calls have failed N consecutive times. Task aborted to prevent infinite retries."), the task is already gone. Do NOT try to re-create it. The user must check their LLM configuration.
+
+**Action limit (`max_actions_per_task`, minimum 5)** ([agent_core/core/state/types.py](agent_core/core/state/types.py))
+- Tracked in `STATE.get_agent_property("action_count")` against `max_actions_per_task`.
+- At **80%** the harness logs a `"warning"` event:
+  > "Action limit nearing: 80% of the maximum actions (N actions) has been used. Consider wrapping up the task or informing the user that the task may be too complex. If necessary, mark the task as aborted to prevent premature termination."
+  - Your response: **wrap up**. Send the best result you have, or ask the user whether to abort. Do NOT ignore.
+- At **100%** the harness logs a `"warning"`, sends a Continue/Abort chat message to the user, and PAUSES the task. `_check_agent_limits` returns False; the next trigger does not get scheduled. The task resumes only when the user picks Continue (limits reset) or Abort.
+
+**Token limit (`max_tokens_per_task`, minimum 100000)** ([agent_core/core/state/types.py](agent_core/core/state/types.py))
+- Same 80% warning / 100% pause pattern as actions, but for cumulative token usage.
+- 80% warning text is identical except "tokens" instead of "actions".
+- 100% triggers the same Continue/Abort gate.
+- Your response at 80%: same as action warning — wrap up or summarize aggressively.
+
+**Parallel constraint violations**
+- The router may drop an action before it runs and surface a `"action_error"` event with `_error` describing the constraint (e.g., "ignore must run alone", "cannot run multiple send_message in parallel").
+- The action is not executed; subsequent actions in the same batch may still run.
+- Recovery: re-issue the action sequentially in the next turn, not in parallel.
+
+### LLM error classes (from `classify_llm_error`)
+
+When an LLM call fails non-fatally, `classify_llm_error()` returns one of these messages. Knowing the class tells you whether retrying makes sense and what to tell the user:
+
+```
+MSG_AUTH         (HTTP 401/403)   "Unable to connect to AI service. Check your API key in Settings."
+                                  → DO NOT retry. Tell user to set/fix API key. See ## Models.
+MSG_MODEL        (HTTP 404)       "The selected AI model is not available."
+                                  → DO NOT retry. Tell user model name is wrong/unavailable.
+MSG_CONFIG       (HTTP 400)       "AI service configuration error. The selected model may not support required features."
+                                  → DO NOT retry. May indicate a feature flag (vision, tool use) not supported by chosen model.
+MSG_RATE_LIMIT   (HTTP 429)       "AI service is rate-limited. Please wait a moment and try again."
+                                  → Retryable after delay. Consider enabling slow_mode in settings.
+MSG_SERVICE      (HTTP 5xx)       "AI service is temporarily unavailable. Please try again later."
+                                  → Retryable. Often transient.
+MSG_CONNECTION   (timeout, ConnectionError)  "Unable to reach AI service. Check your internet."
+                                  → Retryable if connectivity recovers.
+MSG_GENERIC      (unmatched)      "An error occurred with the AI service."
+                                  → Investigate before retrying.
+```
+
+These come back as user-friendly strings to display; the harness wraps them in `"error"` events. You see them via the event stream and `display_message`.
+
+### Failure taxonomy and recovery decision
+
+There are four failure types. Identify which one you are in, then follow the matching recovery.
+
+**TRANSIENT**
+- Symptoms: rate limit, transient 5xx, connection error, file lock, sandbox process hiccup.
+- Action: wait briefly, retry ONCE with the same params.
+- Budget: 1 retry per action invocation. No second retry on the same params.
+
+**APPROACH**
+- Symptoms: action returned `status=error` with a "bad params" / "not found" / "invalid format" message. Semantic mismatch (you grepped the wrong file, ran the wrong action).
+- Action: change the approach. Different action, different params, different plan. Do NOT retry the same call unchanged.
+- Examples:
+  - `read_file` on a non-existent path → `find_files` first.
+  - `schedule_task` with `"daily at 9am"` rejected → use `"every day at 9am"` (the validated format).
+
+**IMPOSSIBLE**
+- Symptoms: missing access (no API key, no integration), hardware action needed (physical printer), policy violation, user data the agent cannot access.
+- Action: stop. `send_message` explaining what was tried and why it cannot work. Offer alternatives if any. For complex tasks, mark the task aborted.
+- Examples:
+  - `/linkedin login` required → ask user to authenticate.
+  - "send a fax" → state limitation, suggest email.
+
+**LOOP**
+- Symptoms: same action + same params + same error TWICE.
+- Action: stop immediately. Escalate to user with a specific question. Do NOT try a third time.
+- Why: loops burn action/token budget and produce no progress. The harness's `max_actions_per_task` and `LLMConsecutiveFailureError` limits are backstops, not your primary safety.
+
+### Recovery patterns by error source
+
+**File / shell / Python action returns `status=error`**
+- Read the `message` field. It often points at the fix (file not found, permission, syntax error, missing dep).
+- If the message says missing dependency for `run_python` / `run_shell`, install it via `pip install`/`npm install` in a follow-up `run_shell` call (auto-installed in sandboxed mode for declared `requirements`, but ad-hoc imports require explicit install).
+- If it says path not found, `find_files` or `list_folder` to locate before retry.
+
+**Web / fetch action returns error**
+- HTTP 4xx → URL or auth wrong. Don't retry the same URL.
+- HTTP 5xx or timeout → transient. One retry, then fall back (different URL, cached source, or report unavailability).
+- Empty result on `web_search` → broaden query or try a different search term. Do NOT keep retrying the same query.
+
+**Schedule / proactive action returns error**
+- Schedule expression rejected by parser → see `## Tasks` for the validated format list. Re-issue with a supported expression.
+- Recurring task creation fails → check PROACTIVE.md for syntax errors near your edit; the file's HTML markers (`PROACTIVE_TASKS_START`/`END`) must remain intact.
+
+**MCP tool returns error**
+- Server-side error in the MCP tool → check EVENT.md for stderr from the MCP server process. Often missing API key in the server's `env` block.
+- Tool not found → server may be disabled in `mcp_config.json` or the `action_set_name` not loaded. See `## MCP`.
+
+**Action limit / token limit warning at 80%**
+- Wrap up. Send the partial result and ask the user whether to continue.
+- If the work genuinely needs more budget, ask the user explicitly — they can pick Continue at the 100% gate and the limits reset.
+- Marking the task as aborted (`task_end` with status=aborted/failed) is preferable to silently exceeding the limit and pausing the task.
+
+**Action limit / token limit reached (100%)**
+- The task is paused; you don't get a next trigger until the user chooses Continue or Abort.
+- Do NOT attempt to schedule anything or send messages — the harness has already sent the user a Continue/Abort dialog.
+- When the user picks Continue, your next trigger arrives with limits reset.
+
+**LLM call failed (non-fatal)**
+- The harness retries internally up to its consecutive-failure threshold.
+- If you see a `"error"` event with one of the `MSG_*` strings, treat it according to the class table above.
+- If it escalates to `LLMConsecutiveFailureError` (`MSG_CONSECUTIVE_FAILURE`), the task is already cancelled. Do not try to recreate it.
+
+### Self-troubleshooting via logs
+
+When the action's `status=error` message does not tell you enough to recover, drop down to the runtime logs. The agent harness writes everything it does to disk, and you can read it.
+
+**Three log surfaces. Know which to use for what.**
+
+```
+EVENT.md                       agent_file_system/EVENT.md
+                               your perspective: events you produced/observed
+                               (action_start, action_end, send_message, error,
+                               warning, action_error, internal). Already on disk
+                               and indexed by memory_search.
+
+logs/<timestamp>.log           project_root/logs/
+                               runtime perspective: harness internals, every
+                               subsystem's INFO/WARN/ERROR log line. Loguru
+                               format. Rotates at 50 MB, kept 14 days.
+                               This is where stderr from sandboxed actions,
+                               MCP server output, and Python tracebacks land.
+
+diagnostic/logs/actions/       diagnostic/logs/actions/<ts>_<slug>.log.json
+                               per-action diagnostic dump (when run via the
+                               diagnostic harness). Contains full input/output
+                               for individual actions. See diagnostic/README.md.
+```
+
+**Picking the right surface:**
+- "What did I do, and what did the harness say back?" → EVENT.md.
+- "Why did this action / MCP / hot-reload actually fail?" → `logs/<timestamp>.log`.
+- "I want to replay one specific action's full input/output" → `diagnostic/logs/actions/`.
+
+**Log line format (loguru):**
+```
+2026-05-03 16:00:12.066 | INFO     | agent_core.core.database_interface:__init__:60 - Action registry loaded. 195 actions...
+^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+timestamp                  level      module:function:line                          message
+```
+- Levels: `DEBUG` < `INFO` < `WARNING` < `ERROR`. Default file threshold is INFO; harness emits a lot at INFO, so most context is captured.
+- The `module:function:line` segment tells you exactly where in the codebase the message came from. You can `read_file <module path>` and jump to the line for full context.
+
+**Subsystem tags you will see in messages.** Most subsystems prefix their log lines with a bracketed tag — grep for these:
+
+```
+[REACT]            react loop main flow                       app/agent_base.py
+[REACT ERROR]      react-level exceptions caught              app/agent_base.py:_handle_react_error
+[ACTION]           action preparation and execution           app/agent_base.py:_execute_actions
+[TASK]             task lifecycle (create, update, end)       agent_core/core/impl/task/manager.py
+[MEMORY]           memory indexing and processing             agent_core/core/impl/memory/manager.py
+[MCP]              MCP server init, connect, tool calls       agent_core/core/impl/mcp/client.py
+[SETTINGS]         settings load and updates                  agent_core/core/impl/settings/manager.py
+[CONFIG_WATCHER]   hot-reload events                          agent_core/core/impl/config/watcher.py
+[LIMIT]            action/token limit choice messages         app/agent_base.py
+[SESSION]          session cache lifecycle                    agent_core/core/impl/llm/interface.py
+[STATE]            state-debug snapshots                      app/agent_base.py
+[ONBOARDING]       onboarding state                           agent_core/core/impl/onboarding/manager.py
+[PROACTIVE]        proactive workflow                         app/proactive/manager.py
+[RESTORE]          startup task restoration                   app/agent_base.py:_restore_sessions
+[AGENT]            agent init, mode toggles                   app/agent_base.py:__init__
+[LLM FACTORY]      LLM provider construction                  agent_core/core/impl/llm/interface.py
+```
+
+**Self-troubleshooting workflow.** When an action returns an error you cannot decode from `message` alone:
+
+```
+1. Identify the latest log file:
+     list_folder logs/                        ← logs are timestamped, latest is freshest
+2. Find the time window of the failure:
+     - From EVENT.md, note the timestamp of the failing event.
+     - That same timestamp will exist in logs/<latest>.log (within seconds).
+3. Grep around that time + the relevant subsystem tag:
+     grep_files "[MCP]"   logs/<latest>.log -A 5 -B 1   ← MCP server failure?
+     grep_files "[ACTION]" logs/<latest>.log -A 5 -B 1   ← action execution issue?
+     grep_files "ERROR"    logs/<latest>.log -B 2 -A 10  ← any error-level line + context
+4. If a Python traceback is present, read upward from the traceback to the
+   most recent INFO line in the same subsystem — that tells you the last
+   successful step before the failure.
+5. The "module:function:line" field on the failing log line points at the code
+   path. read_file <module path> with offset = line - 30 to inspect.
+6. Decide:
+     - The error is in your action params       → ## Errors / APPROACH
+     - The error is in a subsystem (MCP server crash, settings parse error,
+       hot-reload exception)                   → ## MCP / ## Configs / ## Hot Reload
+     - The error is in the LLM call             → see classify_llm_error classes above
+     - The error is environmental (no API key,
+       missing dep, port in use)               → tell the user, do not retry blindly
+```
+
+**Concrete grep recipes:**
+
+```
+# Did an MCP server crash on startup or fail to connect?
+grep_files "[MCP]" logs/<latest>.log -A 3
+# → look for "Failed to connect", "subprocess exited", non-zero return codes.
+
+# Did the config watcher fail to apply a hot reload?
+grep_files "[CONFIG_WATCHER]" logs/<latest>.log -A 3
+
+# Did settings.json fail to parse?
+grep_files "[SETTINGS]" logs/<latest>.log -A 3
+
+# Did an action time out, and which one?
+grep_files "Execution timed out" logs/<latest>.log -B 5
+
+# Did the LLM hit consecutive failures?
+grep_files "LLMConsecutiveFailureError\|MSG_CONSECUTIVE_FAILURE" logs/<latest>.log -A 5
+
+# Did a sandboxed action subprocess produce stderr?
+grep_files "venv\|requirements\|subprocess" logs/<latest>.log -A 3
+
+# What did the agent's _check_agent_limits last log?
+grep_files "[LIMIT]" logs/<latest>.log -A 2
+
+# When did the last task end, and how?
+grep_files "[TASK].*ended\|task_end\|mark_task_cancel" logs/<latest>.log -A 3
+
+# Find the last 100 ERROR-level lines across the whole log:
+grep_files "| ERROR " logs/<latest>.log -A 5
+```
+
+**Acting on what you find.** A log line is data, not a fix. The decision rules:
+
+```
+If the log shows                               then
+─────────────────────────────────────────────  ──────────────────────────────────────
+[MCP] subprocess exited with code N            MCP server crashed. Inspect its env in
+                                               mcp_config.json. Likely missing API
+                                               key or wrong command path. See ## MCP.
+
+[SETTINGS] JSONDecodeError                     settings.json is malformed. Read the
+                                               file, find the syntax error around the
+                                               reported line, fix via stream_edit.
+
+[CONFIG_WATCHER] reload failed                 the change was not picked up. Save
+                                               again, or check the file is tracked in
+                                               watcher.register() (see ## Hot Reload).
+
+[REACT ERROR] LLMConsecutiveFailureError       harness already cancelled the task.
+                                               Tell user to fix LLM config. Do NOT
+                                               retry. See ## Models.
+
+[LIMIT] ... 100% ... Waiting for user choice   task is paused. Do not issue actions
+                                               until next trigger. See ## Errors above.
+
+ModuleNotFoundError in run_python output       the script needs a dependency. Install
+                                               via run_shell "pip install <pkg>" or
+                                               declare in action requirements.
+
+PermissionError / OSError on file write        the path is wrong, locked, or outside
+                                               the allowed scope. Verify with
+                                               list_folder; prefer workspace/ for
+                                               outputs.
+
+Long gaps between INFO lines (no activity)     the loop may be waiting for a trigger
+                                               (waiting_for_user_reply, scheduled
+                                               fire). Check the next trigger fire_at
+                                               in ProactiveManager / Scheduler.
+```
+
+**When logs are the only honest source of truth.** Some failures do not surface as `status=error` in the action result — they manifest as the action *seeming to work* but the side effect not happening (e.g., `run_shell` returns 0 but a script printed "ok" while silently catching an exception; an MCP tool returns success but logged a warning that the operation was a no-op). When you suspect a silent failure, grep the logs for the timestamp of your action and look for `WARNING` or unexpected `ERROR` lines around it.
+
+**Rotation and freshness.** Log files rotate at 50 MB and old files are kept for 14 days. The latest file by mtime is the one with current activity. If your investigation needs older history (e.g., a crash from yesterday), `list_folder logs/` and pick by timestamp.
+
+**Do not ask the user for log content you can read yourself.** The user does not have a better view than you do. If they ask "what's the error?", read the log, summarize, and explain. They are not your support layer — you are theirs.
+
+### Surfacing failures to the user
+
+Mid-task (recoverable):
+- `send_message` with: what failed (one sentence), what you tried (1-3 bullets), what you'll try next (one sentence).
+- Do not surface every transient retry. The user does not need to know about a single rate-limit retry that succeeded.
+
+Terminal (cannot recover):
+- For complex tasks: `send_message` with the failure summary + any salvageable partial result, then `task_end` with a failed-status summary.
+- For simple tasks: `send_message` with the failure, then `task_end`.
+- Mark task aborted via `task_manager.mark_task_cancel(...)` semantics ONLY through the proper action paths (don't try to invoke internals directly).
+- Never fabricate success. If you couldn't read the file, do not paraphrase what you "would have" found.
+
+### When you're blocked but not failed
+
+You're blocked when you don't know what to do next AND retrying won't help. The recovery is information, not action.
+
+```
+1. State the blocker plainly: "I can't proceed because <X>."
+2. List what you tried: "- Tried <A>: <result>. - Tried <B>: <result>."
+3. Ask ONE specific question — not "what should I do".
+   Good:  "Should I use the Slack bot token from settings.oauth.slack, or do you want me to reuse the existing /slack login session?"
+   Bad:   "What do you want me to do?"
+```
+
+### Common error-handling anti-patterns
+
+- **Treating action output as success without checking `status`.** The #1 source of silent failures. Always read the `status` field before using output.
+- **Retrying the same action with the same params** after `status=error` and no change. The error will repeat. Either change a parameter, change the action, or stop.
+- **Ignoring `"warning"` events** about action/token limits. The harness will pause your task soon — get ahead of it. At 80%, wrap up or send the partial result.
+- **Continuing to issue actions while limit-paused (100%).** They will not fire. The user is being shown a Continue/Abort dialog. Wait for the next trigger.
+- **Trying to retry after `LLMConsecutiveFailureError`.** The task is already cancelled by `_handle_react_error`. Do NOT recreate it. Tell the user the LLM configuration needs attention.
+- **Catching exceptions in `run_python` / `run_shell` and printing "ok".** The harness sees `status=success` if your script swallows the error. Always propagate non-zero exit codes / raise on failure.
+- **Fabricating success messages on failure.** Forbidden. If you couldn't read the file or call the API, do not paraphrase what you "would have" produced.
+- **Asking open-ended "what should I do" questions.** Always one specific question with an implied default ("Use the bot token from settings.oauth.slack, or reuse the existing /slack login session?").
+- **Self-detected logical loops.** The consecutive-failure breaker only catches LLM-call failures. If you keep choosing slightly different params for the same action and getting the same business-logic error (e.g., "user not found" three times with three different IDs you guessed), that is a logical loop. Stop and ask the user.
+
+### Errors observed in past self-edits of this file (do not repeat)
+
+When you edit AGENT.md, USER.md, SOUL.md, FORMAT.md, or any other file an LLM (you, future-you) will consume, the consumer is a token-counting reader, not a human eye. These mistakes have happened before and are easy to repeat:
+
+- **Generating output formatted for human readers.** ASCII art (boxes with `┌─┐│└─┘`, arrow trees with `│ ▼`), decorative tables for prose content, em-dash flourishes, marketing intros ("This file is your instruction manual..."), and rhetorical paragraphs are noise to a token-counting reader. Use plain bulleted structure, code blocks for schemas/formats, and direct imperative rules.
+- **Numbered cross-references like `§4`, `§15`, `§22`.** They rot the moment a section is reordered or inserted. Use topic-anchored references: `see ## Tasks`, `see ## Configs`. The header becomes the stable anchor.
+- **Repeating the same warning across multiple sections.** Saying "DO NOT edit MEMORY.md" three times burns tokens without adding meaning. State it once where it belongs (`## File System` or `## Memory`) and reference it elsewhere.
+- **Documenting features that do not exist in the codebase.** Verify by reading source before describing behavior. Examples of fabrication that occurred: an "org chart" section, action parameters that the action did not accept, slash subcommands that were never registered.
+- **Decorative tables for non-tabular content.** Tables make sense for `key | value` mappings (config schemas, command lists). They make NO sense for "rules" or "guidelines" — those should be bullets the LLM can grep with `-A` context.
+- **Confusing length with comprehensiveness.** A 1300-line file the agent cannot navigate is less useful than a 700-line file with stable anchors and tight sections. Comprehensive means "covers what's needed", not "long".
+- **Confusing brevity with clarity.** Inverse of the above. A 10-line section that omits the actual mechanism (what triggers, what payloads, what error states, what the harness does for you) leaves the agent guessing. Detail every mechanism the agent will encounter.
+- **Writing prose where rules would do.** "Use this when X is true, but consider Y..." is harder to act on than "if X: do A. else: do B."
+
+The pattern under all of these: the consumer of this file is an LLM. Optimize for grep, structure, and unambiguous rules. Optimize against token waste and decorative noise.
+
+### What the harness does NOT do for you
+
+- It does NOT change your approach when an action fails. You must.
+- It does NOT pick a different action when one returns `status=error`. You must.
+- It does NOT detect a logical loop you've created (same action with slightly different params, same error). The consecutive-failure breaker only catches LLM-call failures, not action-result failures. You must detect logical loops.
+- It does NOT verify that an action's `status=success` result actually achieved your goal. Verify (re-read the file you wrote, re-query the data you updated). See `## Tasks` Verify phase.
+
+---
+
+## Files
+
+### read_file
+- Returns `cat -n` formatted lines plus a `has_more` flag.
+- Default limit is 2000 lines. Use `offset` and `limit` for targeted reads.
+- For files larger than 500 lines: read the head first to learn structure, then `grep_files` for the section you need, then `read_file` with the right offset and limit.
+- Full input schema: [app/data/action/read_file.py](app/data/action/read_file.py).
+
+### grep_files
+Three output modes:
+- `files_with_matches`: returns file paths only. Use for discovery ("which files contain X").
+- `content`: returns matching lines with line numbers. Use for investigation.
+- `count`: returns match counts per file. Use for frequency checks.
+
+Supported parameters: `glob`, `file_type`, `before_context` / `after_context`, `case_insensitive`, `multiline`.
+
+Full input schema: [app/data/action/grep_files.py](app/data/action/grep_files.py).
+
+### stream_read + stream_edit
+- Use as a pair when modifying an existing file.
+- `stream_read` returns the exact bytes.
+- `stream_edit` applies a precise diff.
+- Preferred over `write_file` for edits. Preserves unrelated content and avoids whole-file overwrites.
+
+### write_file
+Use only when:
+- Creating a brand new file, OR
+- Doing a deliberate full rewrite of a small file.
+
+Never use `write_file` to patch an existing large file. Use `stream_edit`.
+
+### find_files vs list_folder
+- `list_folder`: top-level listing of a single directory.
+- `find_files`: recursive name pattern search across a tree.
+
+### convert_to_markdown vs read_pdf
+- `read_pdf`: direct PDF reading with page support.
+- `convert_to_markdown`: for office formats (docx, xlsx, pptx) you intend to grep afterwards.
+
+### Anti-patterns
+- Repeated full reads of large files. Use `grep_files` plus offset reads instead.
+- Chaining four `read_file` calls when one `grep_files` would answer the question.
+- Reading binary files as text. Use the dedicated action (`read_pdf`, `describe_image`, `understand_video`, etc.).
+
+---
+
+## File System
+
+Your persistent file system is `agent_file_system/`. Every file has a defined writer, reader, format, and update rule. Files marked `DO NOT EDIT` are managed by harness subsystems. Touching them creates inconsistency you cannot recover from.
+
+```
+agent_file_system/
+├── AGENT.md                  Operational manual (this file)
+├── USER.md                   User profile
+├── SOUL.md                   Personality (injected to system prompt)
+├── FORMAT.md                 Document / design standards
+├── MEMORY.md                 Distilled facts                     DO NOT EDIT
+├── EVENT.md                  Full event log                      DO NOT EDIT
+├── EVENT_UNPROCESSED.md      Memory-pipeline staging buffer      DO NOT EDIT
+├── CONVERSATION_HISTORY.md   Rolling dialogue log                DO NOT EDIT
+├── TASK_HISTORY.md           Task summaries                      DO NOT EDIT
+├── PROACTIVE.md              Recurring tasks + Goals/Plan/Status
+├── GLOBAL_LIVING_UI.md       Global Living UI design rules
+├── MISSION_INDEX_TEMPLATE.md Template for mission INDEX.md files
+└── workspace/                Sandbox for task outputs (see ## Workspace)
+```
+
+### Indexed for memory_search
+
+The MemoryManager indexes a fixed set of files for semantic retrieval ([agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py), constant `INDEX_TARGET_FILES`):
+
+```
+AGENT.md
+PROACTIVE.md
+MEMORY.md
+USER.md
+EVENT_UNPROCESSED.md
+```
+
+Editing any of these triggers re-indexing via [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py). Other files in `agent_file_system/` are NOT indexed. To find content in non-indexed files, use `grep_files` directly.
+
+### AGENT.md
+- Purpose: operational manual for you.
+- Write access: user (manually); you (only for operational improvements you have learned, see `## Self-Edit`).
+- Read pattern: `read_file` / `grep_files` on demand. Always grep by `## <Topic>` header.
+- Format: structured markdown. Stable `## <Topic>` headers. HTML comment markers (`<!-- name -->` ... `<!-- /name -->`) around schema and command blocks.
+- Update rule: bump `version:` in front matter on material changes. Sync to `app/data/agent_file_system_template/AGENT.md` when the change should ship to new installs.
+
+### USER.md
+- Purpose: persona and preferences of the user. Read at the start of any user-facing task.
+- Write access: the agent (after confirming with the user); the onboarding wizard.
+- Read pattern: at session start, when personalizing responses, when picking communication channel.
+- Format: plain markdown sections. Standard sections: `## Identity`, `## Communication Preferences`, `## Agent Interaction`, `## Life Goals`, `## Personality`.
+- Update rule: confirm the preference is durable before writing. One-off requests do not belong here.
+
+### SOUL.md
+- Purpose: personality, tone, behavior. Injected directly into the system prompt every turn.
+- Write access: user (primarily); you only on explicit user request.
+- Read pattern: the system reads on every turn. You do NOT need to `read_file` it during normal operation.
+- Caution: edits affect every interaction immediately on next turn. Confirm with user before saving.
+
+### FORMAT.md
+- Purpose: design and formatting standards for documents you generate.
+- Write access: user (preferences); you when the user supplies a new rule (with confirmation).
+- Read pattern: `grep_files "## <filetype>" agent_file_system/FORMAT.md` before generating any document. See `## Documents`.
+- Sections: `## global` (universal rules), `## pptx`, `## docx`, `## xlsx`, `## pdf`. Type-specific sections override `## global`.
+
+### MEMORY.md
+- Purpose: distilled long-term memory. Survives across sessions.
+- Write access: ONLY the memory processor (daily 3am job, plus startup replay if EVENT_UNPROCESSED.md is non-empty).
+- Hard rule: you MUST NOT edit MEMORY.md directly. Use the memory pipeline. See `## Memory`.
+- Read pattern: `memory_search` action (RAG, returns relevance-ranked pointers). Do NOT grep MEMORY.md directly for retrieval.
+- Format: `[YYYY-MM-DD HH:MM:SS] [type] content` — one fact per line.
+- Types: `capability`, `project`, `workspace`, `focus`, `preference`, `analysis`, `user_complaint`, `system_warning`, `system_limit`.
+
+### EVENT.md
+- Purpose: complete chronological event log. Append-only.
+- Write access: EventStreamManager. Hard rule: DO NOT edit.
+- Read pattern: `read_file` / `grep_files` for self-troubleshooting. See `## Errors` for log workflow.
+- Format: `[YYYY/MM/DD HH:MM:SS] [event_type]: payload`. Multi-line payloads continue on subsequent lines.
+- Auto-rotated when size threshold is exceeded.
+
+### EVENT_UNPROCESSED.md
+- Purpose: staging buffer for events awaiting memory distillation.
+- Write access: EventStreamManager (filtered subset of EVENT.md events). Hard rule: DO NOT edit.
+- Read pattern: the memory processor reads it daily 3am. See `## Memory`.
+- Cleared: after each successful memory-processing run.
+- Filter: events of kind `action_start`, `action_end`, `todos`, `error`, `waiting_for_user` are NOT staged. The pipeline focuses on user-facing dialogue and important state changes.
+- Skip flag: during memory-processing tasks, `set_skip_unprocessed_logging(True)` prevents the task's own events from looping back. Reset automatically on `task_end`.
+
+### CONVERSATION_HISTORY.md
+- Purpose: rolling dialogue record across all sessions.
+- Write access: EventStreamManager (on every user/agent message). Hard rule: DO NOT edit.
+- Read pattern: when restoring context for a returning user or reviewing what was said.
+- Format: `[YYYY/MM/DD HH:MM:SS] [sender]: message`. Sender is `user` or `agent`. Multi-line messages continue under one header.
+- Lifespan: permanent. Never auto-cleared.
+
+### TASK_HISTORY.md
+- Purpose: summary of every completed (or cancelled) task.
+- Write access: appended on `task_end`. Hard rule: DO NOT edit.
+- Read pattern: when checking past outcomes for a similar task.
+- Format: one markdown section per task:
+  ```
+  ### Task: <task name>
+  - **Task ID:** <id>
+  - **Status:** completed | cancelled | failed
+  - **Created:** <ISO timestamp>
+  - **Ended:** <ISO timestamp>
+  - **Summary:** <one-paragraph outcome>
+  - **Instruction:** <original task instruction>
+  - **Skills:** <skill names used>
+  - **Action Sets:** <action set names used>
+  ```
+
+### PROACTIVE.md
+- Purpose: recurring proactive task definitions plus the planner-maintained Goals / Plan / Status section.
+- Write access: `recurring_add` / `recurring_update_task` / `recurring_remove` actions; planners (day, week, month).
+- Read pattern: every heartbeat (every 30 min); planners on their schedules; you when the user asks about scheduled work. See `## Proactive`.
+- Format: YAML blocks between `<!-- PROACTIVE_TASKS_START -->` and `<!-- PROACTIVE_TASKS_END -->` markers, followed by a Goals / Plan / Status section.
+- Authority: PROACTIVE.md is the source of truth for the Decision Rubric, Permission Tiers, and recurring-task YAML schema. Do NOT duplicate that content elsewhere.
+
+### GLOBAL_LIVING_UI.md
+- Purpose: global design rules applied to every Living UI project.
+- Write access: user (primarily). You only when the user supplies a new universal rule with confirmation.
+- Read pattern: before creating any Living UI project. See `## Living UI`.
+- Sections: Design Preferences (colors, theme, font, border radius, spacing), Always Enforced rules, Optional rules, Custom rules.
+
+### MISSION_INDEX_TEMPLATE.md
+- Purpose: template for `workspace/missions/<name>/INDEX.md`. See `## Workspace`.
+- Write access: static template. DO NOT edit.
+- Read pattern: when starting a mission, copy this template into the mission directory and fill it in.
+- Fields: Goal, Status, Key Findings, What's Been Tried, Next Steps, Resources & References, Constraints & Notes.
+
+### Living UI projects (workspace/living_ui/)
+
+Living UI projects live at `agent_file_system/workspace/living_ui/<project_name>_<hash>/`. Internal structure varies project to project depending on what the user asked for (different stacks, frameworks, file layouts). Do NOT assume any particular structure beyond the three required files below. To see what's actually in a specific project, `list_folder` it. For lifecycle (create, modify, restart, inspect), use `living_ui_actions`. See `## Living UI`.
+
+Required files (every project has these):
+
+```
+workspace/living_ui/<name>_<hash>/
+├── LIVING_UI.md          Per-project doc: purpose, decisions, project-specific rules
+├── config/
+│   └── manifest.json     Project metadata: name, hash, ports, capabilities
+└── logs/                 Project logs (timestamped). Format and filenames vary per project.
+```
+
+- `LIVING_UI.md`: read this first when working on an existing project. Records purpose, design decisions, and any project-specific overrides of `GLOBAL_LIVING_UI.md`.
+- `config/manifest.json`: read by the runtime to identify the project and its assigned ports. Do not rename a project directory by hand. Re-register via `living_ui_actions` instead.
+- `logs/`: where the project's runtime, build, and console output land. First place to grep when a project misbehaves.
+
+Everything else (backend, frontend, build output, dependency caches, databases) is project-specific. To learn what a fresh-from-template project would contain (one possible shape, not the only one), see [app/data/living_ui_template/](app/data/living_ui_template/).
+
+### Files outside agent_file_system/
+
+Some persistent state the agent interacts with lives outside this directory:
+
+```
+app/config/settings.json              model, API keys, OAuth, cache              (## Configs)
+app/config/mcp_config.json            MCP server registry                         (## MCP)
+app/config/skills_config.json         enabled / disabled skills                   (## Skills)
+app/config/external_comms_config.json platform listener configs                   (## Integrations)
+app/config/scheduler_config.json      cron schedules                              (## Proactive)
+app/config/onboarding_config.json     first-run state                             (## Onboarding)
+skills/<name>/SKILL.md                installed skills                            (## Skills)
+.credentials/<platform>.json          OAuth tokens, bot tokens, API keys
+                                      DO NOT print contents to chat or logs
+logs/<timestamp>.log                  runtime logs                                (## Errors)
+chroma_db_memory/                     ChromaDB index for memory_search
+                                      DO NOT edit
+```
+
+---
 
-### 5. Memory - Learn and Remember
-When you learn something useful (user preferences, project context, solutions to problems):
-- Use `memory_search` action to check if relevant memory already exists
-- Store important learnings in MEMORY.md via memory processing actions
-- Use `read_file` to read USER.md and AGENT.md to understand context before tasks
-- Use `stream_edit` to update USER.md with user preferences you discover
-- Use `stream_edit` to update AGENT.md with operational improvements
+## Workspace
 
-## Proactive Behavior
+`agent_file_system/workspace/` is your sandbox for task output. Three subdirectories with distinct lifecycles:
 
-You activate on schedules (hourly/daily/weekly/monthly).
+```
+agent_file_system/workspace/
+├── <files at root>           Persistent task outputs the user should keep across sessions
+├── tmp/
+│   └── {task_id}/            Per-task scratch directory. Auto-cleaned.
+├── missions/
+│   └── <mission_name>/       Multi-task initiative. Persists indefinitely.
+│       ├── INDEX.md          Required (template at MISSION_INDEX_TEMPLATE.md)
+│       └── <mission files>
+└── living_ui/
+    └── <name>_<hash>/        Living UI projects. See ## File System.
+```
 
-Read PROACTIVE.md for more instruction.
+### Where to put a file
+
+```
+Type of file                                      → Destination
+final document the user should keep               → workspace/<filename>
+draft, sketch, intermediate state, scratch        → workspace/tmp/{task_id}/<filename>
+mission deliverable (multi-task initiative)       → workspace/missions/<mission_name>/<filename>
+Living UI project file                            → workspace/living_ui/<name>_<hash>/...
+```
+
+### Lifecycle rules
+
+- `workspace/` (root): never auto-cleaned. Anything you save here persists until the user deletes it.
+- `workspace/tmp/{task_id}/`: created automatically by `task_manager._prepare_task_temp_dir(task_id)` when a task starts. Cleaned by `task_manager.cleanup_all_temp_dirs(...)` on `task_end` AND on agent startup (excluding currently-restored tasks). Use this for anything you don't need after the task ends.
+- `workspace/missions/<name>/`: never auto-cleaned. The mission's `INDEX.md` is what future-you reads to restore context.
+- `workspace/living_ui/<name>_<hash>/`: managed via `living_ui_actions`. Do not rename or delete by hand. See `## Living UI`.
+
+### Path discipline
+
+- Always use absolute paths when invoking actions: `agent_file_system/workspace/<...>`. Never relative paths.
+- Inside an action result you may receive a path; pass it through verbatim. Do not normalize.
+- Filenames: lowercase, snake_case or kebab-case, no spaces. Example: `tsla_analysis_2026_05_04.pdf`.
+- For task-scoped files use the actual `task_id`, not a guess. The harness sets `task.temp_dir` on task creation; the path is `agent_file_system/workspace/tmp/{task_id}/`.
+
+### Missions: when to create one
+
+Create `workspace/missions/<mission_name>/INDEX.md` when ANY of:
+- Work spans multiple sessions or days.
+- Plan has more than ~10 todos.
+- User uses words like "project", "initiative", "ongoing", "campaign", "phase".
+- Output of this task will feed into a future task.
+
+If the answer is "no" to all, do NOT create a mission. A single complex task is enough.
+
+### Missions: scan-on-start
+
+At the start of every complex task:
+```
+1. list_folder agent_file_system/workspace/missions/
+2. If any directory name looks relevant to the user's request:
+     read_file agent_file_system/workspace/missions/<name>/INDEX.md
+3. Decide:
+     - Resume an existing mission              → continue updating its INDEX.md
+     - Create a new mission                    → copy MISSION_INDEX_TEMPLATE.md
+     - One-off complex task, not a mission     → no mission directory
+```
+
+This is non-optional. Skipping the scan causes duplicate work and lost context.
+
+### Mission INDEX.md fields
+
+Template lives at [agent_file_system/MISSION_INDEX_TEMPLATE.md](agent_file_system/MISSION_INDEX_TEMPLATE.md). Required fields:
+
+- **Goal**: what "done" looks like, with concrete deliverables.
+- **Status**: one of `Not started | In progress | Blocked | Completed | Abandoned`. Plus last task summary, last updated date.
+- **Key Findings**: distilled discoveries. The most important section. This is what future-you reads to restore context. Keep it tight and current.
+- **What's Been Tried**: approaches plus outcomes. Prevents repeating failed attempts.
+- **Next Steps**: concrete actions a fresh task can pick up immediately. Be specific enough that no further investigation is needed to start.
+- **Resources & References**: links, file paths, tools, contacts.
+- **Constraints & Notes**: deadlines, user preferences, environmental limits.
+
+### Mission INDEX.md update cadence
+
+- At task start (resuming a mission): read INDEX.md fully. Add a `Status` line for the new task.
+- During the task: append to `Key Findings` whenever you learn something durable. Append to `What's Been Tried` after any completed approach (success or failure).
+- Before `task_end`: update `Status`, write `Next Steps` so a fresh task session can pick up immediately. If the mission is done, mark `Status: Completed`.
+
+A mission with stale `Next Steps` is worse than no mission. Always leave it actionable.
+
+### What does NOT belong in workspace/
+
+- Configuration files (use `app/config/`).
+- Skills (use `skills/`).
+- Credentials (use `.credentials/`).
+- Logs (auto-go to `logs/<timestamp>.log`).
+- Editing AGENT.md / USER.md / SOUL.md / FORMAT.md (these are in `agent_file_system/`, not `workspace/`).
+
+---
+
+## Documents
+
+[agent_file_system/FORMAT.md](agent_file_system/FORMAT.md) is the source of truth for every document you generate (PDF, pptx, docx, xlsx, and any other file-format output). Read it before generating; it carries the user's brand colors, fonts, writing style, and layout rules.
+
+### FORMAT.md structure
+
+```
+## global       universal rules: brand colors, fonts, writing style, layout
+## pptx         slide-deck specifics (aspect ratio, margins, slide types, typography)
+## docx         Word document standards
+## xlsx         spreadsheet standards
+## pdf          PDF generation standards
+```
+
+The user can add more file-type sections (e.g., `## md`, `## csv`). Type-specific sections OVERRIDE `## global` for that file type.
+
+### Protocol before generating any document
+
+```
+1. grep_files "## <filetype>" agent_file_system/FORMAT.md -A 50
+   Read the file-type section in full.
+
+2. grep_files "## global" agent_file_system/FORMAT.md -A 50
+   Read the global section in full.
+
+3. If the file-type section is missing, fall back to global only.
+
+4. Apply the combined rules to your output: colors, fonts, spacing,
+   layout, writing style, language conventions, brand assets.
+
+5. After generating, verify the output matches by re-reading the produced
+   file (or summary of it). Especially for visual artifacts (PDF, pptx).
+```
+
+This is non-optional. Generating documents without reading FORMAT.md produces inconsistent outputs the user has to redo.
+
+### Action support
+
+Document generation actions in the standard action set:
+```
+create_pdf              build a PDF from markdown / text
+                        (preferred over rendering via run_python)
+convert_to_markdown     normalize office formats before further processing
+read_pdf                read a PDF with page support
+```
+
+Skills that compose document workflows (sample):
+```
+pdf, docx, pptx, xlsx          per-format end-to-end generation skills
+file-format                    format normalization and conversion
+compile-report-advance         multi-source compilation
+```
+
+If a skill exists for the target format (e.g., `pdf`), prefer invoking it (`/pdf` slash or LLM-selected) over composing actions yourself. Skills already encode the FORMAT.md read step and the right action sequence.
+
+### Updating FORMAT.md
+
+Edit when the user gives a durable formatting preference:
+```
+"always use a serif font in reports"            → ## global, font rule
+"company logo is at /path/to/logo.png"          → ## global, brand asset
+"PDF reports should have 1-inch margins"        → ## pdf, margins
+"slide decks should be 16:9 with dark theme"   → ## pptx, layout / theme
+```
+
+Edit procedure:
+```
+1. Confirm scope: "global rule for all docs, or just for <filetype>?"
+2. stream_edit FORMAT.md, write to the right section.
+3. Send the user the exact lines you wrote so they can correct.
+```
+
+DO NOT silently change FORMAT.md. The user owns their style guide.
+
+### Pitfalls
+
+- Generating a document without reading FORMAT.md. Visible inconsistency cost.
+- Mixing global and per-type rules incorrectly: per-type wins for that type, global wins everywhere else.
+- Adding a new file-type section without user consent. Ask first.
+- Storing the user's brand assets (logo URLs, colors) in MEMORY.md or USER.md instead of FORMAT.md. They belong in FORMAT.md.
+
+---
+
+## Living UI
+
+"Living UI" = generated React / HTML / single-page-app projects that have persistent state and are served from CraftBot. Each project is a self-contained mini-app (kanban board, habit tracker, dashboard, etc.) the user can interact with through their browser. Lifecycle is managed via `living_ui_actions`.
+
+Code: [app/data/action/living_ui_actions.py](app/data/action/living_ui_actions.py). File system layout: see `## File System` "Living UI projects" subsection.
+
+### What you actually do for a Living UI request
+
+You do NOT hand-write the project scaffold. The Living UI generator handles file scaffolding via the `living_ui_actions` action set. Your job is:
+1. Capture the user's intent (what is the app for, what state does it persist, what views / interactions).
+2. Apply GLOBAL_LIVING_UI.md design rules and any project-specific overrides.
+3. Use the appropriate Living UI skill (`living-ui-creator`, `living-ui-modify`, `living-ui-manager`) to drive the generator.
+
+### Skills for Living UI lifecycle
+
+```
+living-ui-creator    start a new project. Walks scaffolding + initial state design.
+living-ui-modify     edit an existing project (add features, change layout, fix bugs).
+living-ui-manager    list, inspect, archive, restart projects.
+```
+
+Prefer invoking these via slash (`/living-ui-creator`) or via LLM selection. They encode the right read-rules-first protocol and the right action sequence.
+
+### Protocol BEFORE creating any Living UI project
+
+```
+1. Read GLOBAL_LIVING_UI.md (small file, ~80 lines). It defines:
+   - Primary / secondary / accent colors
+   - Theme behavior (system / dark / light)
+   - Component preferences (preset components, no inline styles,
+     react-toastify, async spinners, toast CRUD feedback,
+     confirmation dialogs, validation, mobile responsive, etc.)
+   - Optional rules (drag-and-drop, keyboard shortcuts, item count
+     badges, search/filter, bulk selection, dark-mode-only, animations)
+   - User-defined custom rules
+
+2. Apply global rules first; only override on explicit user instruction.
+
+3. After creation, the project should respect EVERY "Always Enforced" rule
+   in GLOBAL_LIVING_UI.md (no inline styles, preset components, async
+   spinners, etc.).
+```
+
+If the user wants project-specific design that conflicts with GLOBAL_LIVING_UI.md, confirm the override before applying.
+
+### Per-project structure (what's guaranteed)
+
+Each project lives at `agent_file_system/workspace/living_ui/<name>_<hash>/`. The internal structure varies per project (different stacks possible). Only three files are guaranteed:
+
+```
+LIVING_UI.md          per-project doc: purpose, decisions, project-specific rules
+config/manifest.json  project metadata: name, hash, ports, capabilities
+logs/                 project runtime / build / console logs (timestamped)
+```
+
+For full file-system details and the do-not-rename rule, see `## File System` "Living UI projects" subsection.
+
+### Editing an existing project
+
+```
+1. read LIVING_UI.md to understand purpose + project-specific rules.
+2. list_folder the project to see what's actually there.
+3. Use living-ui-modify skill (don't hand-edit unless the skill
+   isn't suitable).
+4. After changes, the project should still respect GLOBAL_LIVING_UI.md.
+```
+
+When the project misbehaves: grep `logs/` first (frontend console output is piped there via ConsoleCapture). See `## File System` "Living UI projects" subsection for log details.
+
+### Updating GLOBAL_LIVING_UI.md
+
+Edit only when the user gives a NEW universal rule that should apply to ALL Living UI projects (e.g., "never use animations", "always include dark mode toggle"). For project-specific overrides, edit the project's own `LIVING_UI.md` instead.
+
+Edit procedure: same pattern as FORMAT.md — confirm scope, stream_edit, confirm to user.
+
+### Pitfalls
+
+- Hand-writing the project scaffold instead of using `living_ui_actions` / Living UI skills. The generator does it correctly; manual scaffolds drift from the template.
+- Using inline styles. Forbidden by GLOBAL_LIVING_UI.md.
+- Skipping the GLOBAL_LIVING_UI.md read for "simple" projects. Even simple ones should respect global rules.
+- Renaming a project directory by hand. Re-register via `living_ui_actions` instead — the manifest.json is the source of truth for the project's name.
+- Putting project-wide design changes in GLOBAL_LIVING_UI.md when they should be in the per-project LIVING_UI.md.
+
+---
+
+## Actions
+
+Actions are the only way you do anything. The runtime presents the currently-available actions to you in your prompt each turn. If you need a capability that is not in the current list, you must either expand the active action sets (see `## Action Sets`) or read the source to learn what to call.
+
+### Where actions live
+
+Built-in actions are Python files under [app/data/action/](app/data/action/). The action name does NOT always match the filename:
+
+```
+app/data/action/<file>.py             one or more @action() registrations
+app/data/action/CUSTOM_ACTION_GUIDE.md guide for authoring new actions
+app/data/action/<platform>/...        platform-specific bundles (one file may register 10+ actions)
+```
+
+Examples of files with multiple registrations:
+- `action_set_management.py` registers `add_action_sets`, `remove_action_sets`, `list_action_sets`.
+- `skill_management.py` registers `list_skills`, `use_skill`.
+- `integration_management.py` registers `list_available_integrations`, `connect_integration`, `check_integration_status`, `disconnect_integration`.
+- `discord/discord_actions.py`, `slack/slack_actions.py`, `telegram/telegram_actions.py`, `notion/notion_actions.py`, `linkedin/linkedin_actions.py`, `jira/jira_actions.py`, `github/github_actions.py`, `outlook/outlook_actions.py`, `whatsapp/whatsapp_actions.py`, `twitter/twitter_actions.py`, `google_workspace/{gmail,google_calendar,google_drive}_actions.py` each register many actions.
+
+Total registered built-in actions: roughly 195 (varies by version). The exact number is logged at startup in `logs/<timestamp>.log` — search for `Action registry loaded`.
+
+### How to discover actions
+
+You have three discovery paths. Pick by purpose.
+
+**1. By name (when you already know it).** Read the source:
+```
+read_file app/data/action/<action_name>.py
+```
+
+**2. By capability (when you do NOT know the name).** Grep descriptions and names across the folder:
+```
+grep_files 'name="' app/data/action/ -A 1            # list all action names + first description line
+grep_files 'description=' app/data/action/ -A 0      # list all descriptions
+grep_files '<keyword>' app/data/action/ -A 2 -B 1    # find actions matching a concept
+```
+
+**3. By currently-loaded set (what you can call right now).** Two options:
+- The runtime puts the current action list in your prompt every turn. That list is authoritative.
+- Call the `list_action_sets` action to see which sets are loaded plus all actions in them. Useful when the prompt list is truncated or you suspect a set is missing.
+
+### `@action(...)` decorator schema
+
+Every action is registered via the `@action` decorator at [agent_core/core/action_framework/registry.py](agent_core/core/action_framework/registry.py). When you read an action's `.py` file, these are the fields you will see:
+
+```
+name             str   required. Unique identifier the LLM uses to call the action.
+description      str   shown to the LLM. This is how you decide whether to use the action.
+mode             str   "CLI" | "ALL". Visibility filter.
+default          bool  legacy. If True, action is always available. Prefer action_sets.
+execution_mode   str   "internal" (in-process) | "sandboxed" (ephemeral venv subprocess).
+platforms        str|list  "linux" | "windows" | "darwin" | "all". Default: ["all"].
+input_schema     dict  JSON-schema-like description of parameters. Read this for param names and types.
+output_schema    dict  JSON-schema-like description of return shape. Read this to know what to expect.
+requirement      list  pip packages auto-installed in sandbox before execution.
+test_payload     dict  test input for diagnostic harness. The "simulated_mode" key bypasses real execution.
+action_sets      list  set names this action belongs to. Determines when it's loaded.
+parallelizable   bool  default True. False = action runs alone in its turn (write ops, state changes).
+```
+
+Key implications when reading an action:
+- `mode="CLI"` actions exist (e.g. `read_file`, `task_start`). They are loaded by default.
+- `parallelizable=False` actions cannot be batched. The router will sequence them. Examples: `task_update_todos`, `add_action_sets`, `remove_action_sets`.
+- `execution_mode="sandboxed"` means the action runs in a fresh venv subprocess with `requirement` packages installed automatically. `run_python` is sandboxed; most other actions are internal.
+- `default=True` means the action is in the action list regardless of which sets are loaded. Common defaults: `task_start`, `send_message`, `ignore`. Prefer adding to an `action_sets` list over using `default=True`.
+
+### Built-in action categories (orientation only — read source for current state)
+
+```
+core                     send_message, task_start, task_end, task_update_todos, ignore, wait,
+                         add_action_sets, remove_action_sets, list_action_sets,
+                         list_skills, use_skill,
+                         list_available_integrations, connect_integration,
+                         check_integration_status, disconnect_integration
+
+file_operations          read_file, grep_files, find_files, list_folder, stream_edit, write_file,
+                         read_pdf, convert_to_markdown, create_pdf
+
+shell                    run_shell, run_python
+
+web_research             web_fetch, web_search, http_request
+
+memory                   memory_search
+
+proactive / scheduler    schedule_task, scheduled_task_list, schedule_task_toggle,
+                         remove_scheduled_task, recurring_add, recurring_read,
+                         recurring_update_task, recurring_remove
+
+image                    describe_image, generate_image, perform_ocr
+
+video                    understand_video
+
+clipboard                clipboard_read, clipboard_write
+
+comms                    send_message_with_attachment
+
+living_ui                living_ui_http, living_ui_import_external, living_ui_import_zip,
+                         living_ui_notify_ready, living_ui_report_progress, living_ui_restart
+
+per-platform integrations  Discord, Slack, Telegram, Notion, LinkedIn, Jira, GitHub,
+                           Outlook, WhatsApp, Twitter, Google Workspace
+                           (each has its own bundle file; loaded via integration action sets)
+```
+
+This grouping is informal. The authoritative grouping per action is the `action_sets=[...]` list in its decorator. When in doubt, grep the source.
+
+### Calling an action
+
+You do not call actions directly in code. You emit an action decision in your turn output. Format (illustrative):
+
+```
+{"action_name": "read_file", "parameters": {"file_path": "agent_file_system/AGENT.md", "limit": 200}}
+```
+
+The router validates the name and parameters against the action's `input_schema`, then the executor runs it. The result returns as a dict matching `output_schema`. See `## Errors` for the standard `{"status": "success" | "error", ...}` envelope.
+
+### Authoring a new action
+
+If you discover the harness is missing a capability you need repeatedly:
+1. Read [app/data/action/CUSTOM_ACTION_GUIDE.md](app/data/action/CUSTOM_ACTION_GUIDE.md).
+2. Pick a similar existing action as a template (e.g. for a file op, copy `read_file.py`).
+3. Create the new file under [app/data/action/](app/data/action/) with a single `@action(...)` decorator.
+4. Register it in the right `action_sets`.
+5. Restart is required for code changes (hot-reload covers configs, NOT new action files). See `## Hot Reload`.
+
+For everything routine (existing capabilities), prefer composing existing actions over authoring new ones.
+
+---
+
+## Action Sets
+
+An action set is a named bundle of actions you load together. Loading a set makes all its actions available in your prompt; the LLM can then call them. Sets exist to keep your prompt small (only the actions you need) without sacrificing capability.
+
+Code: [app/action/action_set.py](app/action/action_set.py) (`ActionSetManager`). Set descriptions: [app/action/action_set.py](app/action/action_set.py) `DEFAULT_SET_DESCRIPTIONS`.
+
+### How sets are discovered
+
+Sets are NOT hardcoded. They are discovered dynamically by scanning every registered action's `action_sets=[...]` declaration. Any name an action declares becomes a valid set. This means:
+- Adding a new action to a new set name silently creates that set.
+- MCP servers auto-register as `mcp_<server_name>` sets via `action_set_name` in `mcp_config.json`. See `## MCP`.
+- A set with no actions is invisible (the discovery scans actions, not a static list).
+
+To list every set currently visible to the runtime, call the `list_action_sets` action.
+
+### Built-in sets (with curated descriptions)
+
+`DEFAULT_SET_DESCRIPTIONS` has explicit descriptions for these eight sets:
+
+```
+core                  Essential actions, always available
+file_operations       File and folder manipulation
+web_research          Internet search and browsing
+document_processing   PDF and document handling
+image                 Image viewing, analysis, OCR
+video                 Video analysis
+clipboard             Clipboard read/write
+shell                 Command line and Python execution
+```
+
+Any set name not in `DEFAULT_SET_DESCRIPTIONS` is presented to the LLM as `Custom action set: <name>`.
+
+### Other sets actually used by built-in actions
+
+Beyond the eight curated sets, these sets exist because actions declare them:
+
+```
+proactive             schedule_task, scheduled_task_list, recurring_*, schedule_task_toggle, ...
+scheduler             schedule_task, schedule_task_toggle (alongside proactive)
+content_creation      generate_image, create_pdf, ...
+living_ui             living_ui_http, living_ui_restart, ...
+
+per-integration sets (loaded only when the user has the integration connected):
+discord, slack, telegram_bot, telegram_user, whatsapp, twitter,
+notion, linkedin, jira, github, outlook, google_workspace
+```
+
+This list is illustrative, not authoritative. Run `list_action_sets` for the live list. Read [app/action/action_set.py](app/action/action_set.py) for the source.
+
+### `core` is always loaded
+
+[app/action/action_set.py](app/action/action_set.py) `compile_action_list`:
+
+```
+required_sets = set(selected_sets) | {"core"}
+```
+
+You cannot opt out of `core`. Whatever else you pass to `task_start`, `core` is added. `core` includes (at minimum):
+
+```
+send_message, task_start, task_end, task_update_todos, ignore, wait,
+add_action_sets, remove_action_sets, list_action_sets,
+list_skills, use_skill,
+list_available_integrations, connect_integration,
+check_integration_status, disconnect_integration,
+clipboard_read, clipboard_write
+```
+
+(Note: `clipboard_read` and `clipboard_write` are in `core`, not in a separate `clipboard` set, despite the curated description suggesting otherwise.)
+
+### How sets are loaded
+
+Three mechanisms, in order of preference:
+
+1. **At `task_start`** — pass the names in the `action_sets` parameter. The LLM-driven creator (`do_create_task`) auto-selects sets based on the task description; you can also pre-select via skill slash commands like `/pdf`. `core` is added automatically.
+2. **Mid-task** — call `add_action_sets(action_sets=[...])` or `remove_action_sets(action_sets=[...])`. The action list is recompiled and the new actions appear in the next turn's prompt.
+3. **Via skill selection** — if a skill's `SKILL.md` frontmatter has `action-sets: [...]`, those sets are auto-loaded when the skill is selected. See `## Skills`.
+
+After loading, the new actions ARE in your prompt the next turn. You do not need to re-fetch or refresh anything.
+
+### Picking the right sets
+
+Match the task's actual needs. Loading every set bloats the prompt and slows action selection.
+
+```
+Lightweight task                  core + file_operations
+Web research / lookup             core + web_research
+Document generation               core + file_operations + document_processing
+Multimedia work                   core + image (and/or video)
+Shell / scripting                 core + shell + file_operations
+Living UI work                    core + living_ui + file_operations + shell
+Proactive task setup              core + proactive
+Per-platform integration          core + <integration_name>  (e.g. core + slack)
+```
+
+Defaults that almost always make sense: `core + file_operations`. Add others as the task requires.
+
+### Tracking what is loaded
+
+Two ways to know what set is currently active for a task:
+1. The current prompt's action list (always authoritative).
+2. The `list_action_sets` action returns `{ available_sets, current_sets, current_actions }`.
+
+If you suspect a set was supposed to be loaded but isn't (an action you expect to see is missing), call `list_action_sets` to confirm before assuming you have to manually add it with `add_action_sets`.
+
+### Set lifecycle relative to a task
+
+- Sets are LOCKED when the task is created. The task's `compiled_actions` list is built once.
+- `add_action_sets` / `remove_action_sets` are the only mid-task mutations. They re-run `compile_action_list` and update the task's available actions.
+- When the task ends, the set selection is gone. The next task starts fresh.
+- Skills do NOT swap mid-task. To use a different skill, end the task and start a new one.
+
+See `## Tasks` for task-level lifecycle and `## Runtime` for how the action list reaches your prompt each turn.
+
+---
+
+## Slash Commands
+
+Slash commands are USER-invoked at the chat input. The agent does NOT call slash commands; the agent uses actions (see `## Actions`). Slash commands are documented here so you understand what the user just typed when they invoke one, and so you can answer questions about them.
+
+Sources of truth (in order of authority):
+1. Built-in command files: [app/ui_layer/commands/builtin/](app/ui_layer/commands/builtin/). One file per top-level command.
+2. Integration commands: dynamically registered from `INTEGRATION_HANDLERS` in [app/credentials/handlers.py](app/credentials/handlers.py). One slash command per registered handler.
+3. Skill commands: every skill with `user-invocable: true` (default) in its `SKILL.md` frontmatter is auto-registered as `/<skill_name>`.
+
+Run `/help` for the live list. If you need to verify a specific command, read its file.
+
+### General commands
+
+```
+/help [command]      list all commands, or detail one. Always available.
+/menu                show the main menu
+/clear               clear the conversation
+/clear_tasks         clear finished tasks (completed, failed, aborted) from the action panel
+/reset               reset the agent to its initial state
+/exit                quit the application
+/update              check for updates and update CraftBot
+/provider <name>     switch LLM provider (openai, anthropic, google, byteplus, remote)
+```
+
+### Credential and integration overview
+
+```
+/cred list           list all stored credentials across integrations
+/cred status         show connection status for every integration
+/cred integrations   list available integration types
+```
+
+`/cred` does not connect or disconnect; use `/<integration>` for that.
+
+### MCP server management
+
+```
+/mcp list                          list configured MCP servers + enabled state
+/mcp add <name> <command> [args]   register a new MCP server (stdio)
+/mcp add-json <json>               register from a full JSON entry
+/mcp remove <name>                 remove a server
+/mcp enable <name>                 enable a server (next reload picks it up)
+/mcp disable <name>                disable a server
+/mcp env <name> <KEY> <value>      set an env variable on a server entry
+```
+
+Edits go to [app/config/mcp_config.json](app/config/mcp_config.json) and are hot-reloaded. See `## MCP` and `## Configs`.
+
+### Skill management
+
+```
+/skill list                                    list installed skills + enabled state
+/skill info <name>                             show metadata + body of a skill
+/skill enable <name>                           move a skill into enabled_skills
+/skill disable <name>                          move a skill into disabled_skills
+/skill install <source>                        install from a git URL or path
+/skill create [name] [description]             scaffold a new skill (uses craftbot-skill-creator)
+/skill remove <name>                           delete a skill from skills/ directory
+/skill reload                                  rediscover skills (manual hot-reload)
+```
+
+Edits go to [app/config/skills_config.json](app/config/skills_config.json) and the [skills/](skills/) directory. See `## Skills`.
+
+### Skill direct invocation
+
+Every skill with `user-invocable: true` in its frontmatter (default) is registered as a slash command:
+
+```
+/<skill_name> [args]    invoke the skill directly
+```
+
+When the user types this, the runtime starts a task with the skill pre-selected (bypassing LLM skill selection in `do_create_task`). Examples that exist in the current build: `/pdf`, `/docx`, `/pptx`, `/xlsx`, `/weather-check`, `/get-weather`, etc. The list depends on which skills are enabled in [app/config/skills_config.json](app/config/skills_config.json).
+
+### Integration commands (auth + lifecycle)
+
+For each registered integration in `INTEGRATION_HANDLERS`, a slash command `/{integration}` is auto-registered:
+
+```
+/<integration> status                    show connection state, accounts
+/<integration> connect [...credentials]  connect (token-based) — fields depend on integration
+/<integration> disconnect [account_id]   remove a connection
+/<integration> login-qr                  for whatsapp_web (QR scan flow)
+/<integration> invite                    for OAuth-capable integrations (browser flow)
+```
+
+Currently registered (per [app/credentials/handlers.py](app/credentials/handlers.py) `INTEGRATION_HANDLERS`):
+
+```
+google              OAuth flow.   /google invite | status | disconnect
+slack               OAuth + token. /slack invite | connect <bot_token> [workspace_name] | status | disconnect
+notion              OAuth + token. /notion invite | connect <token> | status | disconnect
+linkedin            OAuth flow.   /linkedin invite | status | disconnect
+discord             Token flow.   /discord connect <bot_token> | status | disconnect
+telegram            Bot + user.   /telegram connect <bot_token> | status | disconnect
+                                  (user-account flow has additional sub-commands; see /help telegram)
+whatsapp            Web (QR).     /whatsapp login-qr [phone] | status | disconnect
+whatsapp_business   API tokens.   /whatsapp_business connect <phone_number_id> <access_token> | status | disconnect
+outlook             OAuth flow.   /outlook invite | status | disconnect
+jira                Token flow.   /jira connect ... | status | disconnect
+github              Token flow.   /github connect <token> | status | disconnect
+twitter             Token flow.   /twitter connect ... | status | disconnect
+```
+
+The exact `connect` fields per integration are defined in `INTEGRATION_REGISTRY` at [app/external_comms/integration_settings.py](app/external_comms/integration_settings.py). Use `/help <integration>` to see what credentials it expects.
+
+### Agent-provided commands
+
+Skills can register commands at runtime via the agent command wrapper ([app/ui_layer/commands/builtin/agent_command.py](app/ui_layer/commands/builtin/agent_command.py)). These appear in `/help` alongside built-in commands. To audit what's currently registered, ask the user to run `/help` and paste the output, or read the live command registry from the running process.
+
+### When the user types a slash command
+
+If a user types a slash command and you receive the resulting task or message:
+- The runtime processes the command BEFORE you see it. Your role is to react to its outcome, not to re-execute.
+- For `/<skill_name>`, the runtime creates a task with the skill pre-selected. You take over from there.
+- For `/<integration> connect` or `/cred status`, the result lands in the chat as text. The user may then ask you to do something with the now-connected integration.
+- For `/clear`, `/clear_tasks`, `/reset`, `/exit`: state changes happen immediately. You may not have continuity with prior conversation/tasks after these.
+
+---
+
+## Configs
+
+The agent's behavior is shaped by JSON config files under [app/config/](app/config/). When you need to change settings about yourself (model, API keys, MCP servers, skills, schedules, integrations), you edit one of these files. The harness watches them and reloads automatically.
+
+This section is the source of truth for: every config file's full schema, what each key controls, the hot-reload mechanism, what does and does NOT take effect without restart, and the edit-and-verify workflow.
+
+### The six config files
+
+```
+app/config/settings.json              model, API keys, OAuth, cache, browser, memory          hot-reload
+app/config/mcp_config.json            MCP server registry                                     hot-reload
+app/config/skills_config.json         enabled / disabled skills                               hot-reload
+app/config/external_comms_config.json telegram + whatsapp listener configs                    hot-reload
+app/config/scheduler_config.json      cron schedules                                          hot-reload
+app/config/onboarding_config.json     first-run state                                         NOT watched
+```
+
+You may also encounter MCP server entries that point at standalone JSON files; those are imported at MCP load time and follow `mcp_config.json`'s lifecycle.
+
+### Editing protocol (memorize this)
+
+```
+1.  read_file <config_path>                       see current state
+2.  decide what to change
+3.  stream_edit <config_path> ...                 make the edit (preserves unrelated content)
+4.  wait ~0.5s for debounce                        the watcher coalesces rapid saves
+5.  verify the reload happened                    see "Verifying a reload" below
+6.  if no effect: check logs/<latest>.log for     [SETTINGS] / [MCP] / [CONFIG_WATCHER] errors
+    [CONFIG_WATCHER] / [MCP] / [SETTINGS] errors
+```
+
+Use `stream_edit`, never `write_file`, on configs. A whole-file rewrite risks losing unrelated keys the runtime relies on (e.g. `api_keys_configured` bookkeeping, your own `oauth` clients).
+
+If the file is malformed JSON after your edit, the reload fails and the previous in-memory config keeps running. Read the file back and fix the syntax. `[SETTINGS] JSONDecodeError` will appear in the log.
+
+### Hot-reload mechanism
+
+Source: [agent_core/core/impl/config/watcher.py](agent_core/core/impl/config/watcher.py) (`ConfigWatcher` singleton).
+
+```
+backend                  watchdog library if installed; polling (1s) fallback otherwise
+watch granularity        the watcher subscribes to each config file's PARENT DIRECTORY,
+                         then filters events by registered file path
+debounce                 0.5 seconds. Rapid saves within 500ms are coalesced into one reload.
+trigger                  on file modification:
+                           1. cancel any pending debounce timer for that path
+                           2. start a fresh 0.5s timer
+                           3. on timer fire, call the registered reload callback
+callback execution       sync callbacks run in the watcher thread. Async callbacks are
+                         scheduled on the main event loop via run_coroutine_threadsafe.
+log signature            "[CONFIG_WATCHER] Registered watch for <name>"  (at startup)
+                         "[CONFIG_WATCHER] Started watching config files"
+                         per-reload: "[SETTINGS] Reloaded ..." / "[MCP] Reloaded ..." etc.
+```
+
+### Per-config reload behavior
+
+Every watched config has a specific reload callback registered at startup ([app/agent_base.py](app/agent_base.py) `_initialize_config_watcher`):
+
+```
+settings.json
+  callback        settings_manager.reload + invalidate_settings_cache
+  effect          provider/model/API keys updated for the NEXT LLM call.
+                  An in-flight call uses the OLD config; the next turn uses the new one.
+  log signature   [SETTINGS] Reloaded ...
+
+mcp_config.json
+  callback        mcp_client.reload  (async)
+  effect          servers with enabled=true that are not connected get connected.
+                  servers that became enabled=false get disconnected.
+                  newly-added servers register their action set as mcp_<name>.
+                  tools appear in the next turn's action list (after action set is loaded).
+  log signature   [MCP] Loaded config with N server(s) ... [MCP] Connecting to '<name>' ...
+
+skills_config.json
+  callback        skill_manager.reload + ui_controller.sync_skill_commands
+  effect          skill discovery re-runs on skills/. Newly-enabled skills become
+                  selectable; disabled skills disappear. Slash commands for
+                  user-invocable skills are re-registered (/{skill_name} appears or vanishes).
+                  Effect on a running task: the active task keeps its locked skill list.
+                  New skills are only available to the NEXT task.
+  log signature   [SKILL] Reloaded skills_config ...
+
+external_comms_config.json
+  callback        registered after external_comms initialization
+  effect          telegram and whatsapp listeners start, stop, or reconfigure based on
+                  enabled / mode changes. Other platforms (discord, slack, etc.) are not
+                  in this file - they are managed by .credentials/ + /<integration> commands.
+  log signature   [EXT_COMMS] Reloaded ...
+
+scheduler_config.json
+  callback        scheduler.reload  (async)
+  effect          schedules re-parsed. New entries fire on their first matching window.
+                  Removed entries do not fire next cycle.
+                  Currently-firing tasks are not interrupted.
+  log signature   [SCHEDULER] Reloaded ...
+
+onboarding_config.json
+  callback        NONE (not watched).
+  effect          you do not edit this file. It is managed by the onboarding flow.
+                  If you change it manually, restart is required.
+```
+
+### What does NOT take effect on a config save
+
+- An action set already selected for an active task (locked at `task_start`).
+- An LLM call already in flight (uses the old config; next turn uses the new one).
+- A skill body / metadata change on a running task (skills are locked at task creation).
+- New built-in actions added by creating a new `.py` file under `app/data/action/` (code change, requires restart).
+- Changes to OS environment variables not stored in any config file (requires restart).
+- Code changes anywhere in `app/`, `agent_core/`, `agents/` (requires restart).
+
+If any of these apply, end the current task, restart only what's needed (often nothing - just start a new task), and the new config will be in force.
+
+### Verifying a reload
+
+By config:
+
+```
+settings.json
+  - check logs:  grep_files "[SETTINGS]" logs/<latest>.log -A 1
+  - or read back: read_file app/config/settings.json (confirm your edit landed)
+  - in next task: model/provider/api_key changes are observable when an LLM call fires
+
+mcp_config.json
+  - check logs:  grep_files "[MCP]" logs/<latest>.log -A 2
+  - look for:    "Connecting to '<server-name>'", "[StdioTransport] Starting subprocess"
+  - in next task: list_action_sets shows mcp_<server-name> as a registered set
+
+skills_config.json
+  - run /skill list (user-side) or
+  - call list_skills action  → confirms enabled/disabled state
+  - new /<skill_name> slash commands appear after sync_skill_commands fires
+
+external_comms_config.json
+  - check logs:  grep_files "[EXT_COMMS]" logs/<latest>.log -A 2
+  - if telegram/whatsapp enabled and started, expect connection success messages
+
+scheduler_config.json
+  - check logs:  grep_files "[SCHEDULER]" logs/<latest>.log -A 2
+  - call scheduled_task_list action  → confirms entries
+```
+
+If the log shows the reload fired but the change still isn't reflected: the change probably falls in "What does NOT take effect on a config save" above. End the current task or restart as appropriate.
+
+### Schemas
+
+The blocks below are dictionary-style: keys, valid values, and defaults. Read the actual JSON file (`read_file app/config/<name>.json`) when you need current values.
+
+<!-- schema:settings.json -->
+```
+File: app/config/settings.json
+
+version: string                  (CraftBot version this config was written for; do not edit)
+
+general:
+  agent_name: string             (the user-facing name of this agent, e.g. "CraftBot")
+  os_language: string            (BCP-47 / ISO code, e.g. "en")
+
+proactive:
+  enabled: bool                  (master switch for proactive workflow; if false,
+                                  proactive_heartbeat and planners are skipped)
+
+memory:
+  enabled: bool                  (master switch for memory_search and memory pipeline)
+  max_items: int                 (default 200; cap on MEMORY.md before pruning)
+  prune_target: int              (default 135; how many items remain after a prune)
+  item_word_limit: int           (default 150; words per stored memory item)
+
+model:
+  llm_provider: "openai" | "anthropic" | "google" | "byteplus" | "remote"
+  vlm_provider: same options
+  llm_model: string | null       (null = provider default; e.g. "claude-sonnet-4-5-20250929")
+  vlm_model: string | null
+  slow_mode: bool                (true throttles requests for rate-limited providers)
+  slow_mode_tpm_limit: int       (tokens per minute when slow_mode is true)
+
+api_keys:
+  openai: string                 (sk-...)
+  anthropic: string              (sk-ant-...)
+  google: string                 (Gemini API key)
+  byteplus: string
+
+endpoints:
+  remote_model_url: string       (for "remote" provider, e.g. Ollama base URL)
+  byteplus_base_url: string      (default https://ark.ap-southeast.bytepluses.com/api/v3)
+  google_api_base: string        (override for Gemini API base URL)
+  google_api_version: string     (override for Gemini API version)
+  remote: string                 (default http://localhost:11434; Ollama endpoint)
+
+oauth:
+  google:    { client_id, client_secret }     (used by /google invite OAuth flow)
+  linkedin:  { client_id, client_secret }     (used by /linkedin invite)
+  slack:     { client_id, client_secret }     (used by /slack invite)
+  notion:    { client_id, client_secret }     (used by /notion invite)
+  outlook:   { client_id }                    (used by /outlook invite)
+
+web_search:
+  google_cse_id: string          (Google Custom Search Engine ID for web_search action)
+
+cache:
+  prefix_ttl: int                (seconds; cache TTL for the system-prompt prefix)
+  session_ttl: int               (seconds; cache TTL for per-session state)
+  min_tokens: int                (skip caching prompts below this token count)
+
+browser:
+  port: int                      (default 7926; CraftBot browser frontend port)
+  startup_ui: bool               (auto-open browser at startup)
+
+api_keys_configured:             (BOOKKEEPING - reflects which keys are non-empty)
+  openai: bool
+  anthropic: bool
+  google: bool
+  byteplus: bool
+```
+<!-- /schema:settings.json -->
+
+<!-- schema:mcp_config.json -->
+```
+File: app/config/mcp_config.json
+
+mcp_servers: [
+  {
+    name: string                                   required, unique within file
+    description: string                            human-readable, shown to the LLM
+    transport: "stdio" | "sse" | "websocket"       default "stdio"
+    command: string                                required for stdio (e.g. "npx", "uv", "python")
+    args: [string]                                 stdio command arguments
+    url: string                                    required for sse / websocket
+    env: { KEY: VALUE }                            environment variables passed to the server process
+    enabled: bool                                  controls whether the server connects on load/reload
+    action_set_name: string                        default "mcp_<name>"; the action set tools register under
+  }
+]
+
+Patterns by transport:
+  NPX (Node):     transport="stdio"  command="npx"     args=["-y", "@org/server-name", ...optional-args]
+  Python (uv):    transport="stdio"  command="uv"      args=["run", "--directory", "<path>", "main.py"]
+  Python (pip):   transport="stdio"  command="python"  args=["-m", "<module>", ...args]
+  Remote SSE:     transport="sse"    url="http://localhost:3000/mcp"
+  Remote WS:      transport="websocket" url="ws://..."
+
+When a server is enabled and connects, all its tools become callable as actions
+under its action_set_name. To use them in a task, load that set via add_action_sets
+or via task_start's auto-selection.
+```
+<!-- /schema:mcp_config.json -->
+
+<!-- schema:skills_config.json -->
+```
+File: app/config/skills_config.json
+
+auto_load: bool                  default true; if false, no skills are loaded at startup
+enabled_skills: [skill_name]     skills available for selection / slash invocation
+disabled_skills: [skill_name]    explicitly turned off; loader sets enabled=false
+project_skills_dir: string       default "skills"; where SKILL.md directories are discovered
+
+Skills are discovered by scanning <project_skills_dir>/<name>/SKILL.md.
+A skill in disabled_skills is loaded but flagged disabled (the LLM does not see it).
+A skill not listed in either is loaded and enabled by default if auto_load is true.
+
+To enable a skill: move its name from disabled_skills to enabled_skills.
+To remove a skill entirely: also delete the directory under skills/.
+SKILL.md frontmatter fields: see ## Skills.
+```
+<!-- /schema:skills_config.json -->
+
+<!-- schema:external_comms_config.json -->
+```
+File: app/config/external_comms_config.json
+
+telegram:
+  enabled: bool                  master switch for the telegram listener
+  mode: "bot" | "mtproto"        bot = Bot API; mtproto = user-account API
+  bot_token: string              required for mode=bot (from @BotFather)
+  bot_username: string           the bot's @username (without the @)
+  api_id: string                 required for mode=mtproto (from my.telegram.org)
+  api_hash: string               required for mode=mtproto
+  phone_number: string           required for mode=mtproto (E.164 format)
+  auto_reply: bool               if true, incoming messages route to the agent
+
+whatsapp:
+  enabled: bool                  master switch for whatsapp listener
+  mode: "web" | "business"       web = WhatsApp Web (Playwright); business = Cloud API
+  session_id: string             web mode: cached browser session
+  phone_number_id: string        business mode (from Meta business)
+  access_token: string           business mode
+  auto_reply: bool
+
+NOTE: Other platforms (discord, slack, gmail, notion, linkedin, outlook,
+google, jira, github, twitter) do NOT live in this file.
+- Their credentials live under .credentials/<platform>.json.
+- OAuth client_id/secret for some live in settings.json's "oauth" section.
+- Connect/disconnect via /<platform> commands.
+See ## Integrations and ## Slash Commands.
+```
+<!-- /schema:external_comms_config.json -->
+
+<!-- schema:scheduler_config.json -->
+```
+File: app/config/scheduler_config.json
+
+enabled: bool                                master switch for the scheduler
+schedules: [
+  {
+    id: string                               unique identifier
+    name: string                             human-readable
+    instruction: string                      what the agent should do when fired
+    schedule: string                         natural language OR cron (see formats below)
+    enabled: bool                            individual schedule on/off
+    priority: int                            1-100, lower = higher priority
+    mode: "simple" | "complex"               task mode for the spawned task
+    recurring: bool                          true = stays after firing; false = one-shot
+    action_sets: [string]                    sets to load before the task fires
+    skills: [string]                         skills to inject before the task fires
+    payload: { type: string, ... }           passed to react()'s trigger.payload
+                                             type drives workflow routing (see ## Runtime):
+                                              "memory_processing", "proactive_heartbeat",
+                                              "proactive_planner", "scheduled", ...
+  }
+]
+
+Schedule formats (parser at app/scheduler/parser.py):
+  Natural:  "every day at 3am"
+            "every sunday at 5pm"
+            "every 30 minutes"
+            "every 3 hours"
+            "tomorrow at 9am"
+            "in 2 hours"
+            "in 30 minutes"
+            "at 3pm"
+            "immediate"
+  Cron:     "0,30 * * * *"
+            "0 7 * * *"
+            "0 8 1 * *"
+
+Built-in schedules (do NOT remove):
+  memory-processing  every day at 3am   payload.type="memory_processing"
+  heartbeat          0,30 * * *         payload.type="proactive_heartbeat"
+                                         skill: heartbeat-processor
+  day-planner        every day at 7am   payload.type="proactive_planner" scope=day
+  week-planner       every sunday at 5pm payload.type="proactive_planner" scope=week
+  month-planner      0 8 1 * *          payload.type="proactive_planner" scope=month
+```
+<!-- /schema:scheduler_config.json -->
+
+<!-- schema:onboarding_config.json -->
+```
+File: app/config/onboarding_config.json
+
+hard_completed: bool                  wizard finished (collected user_name, language, tone, etc.)
+soft_completed: bool                  conversational interview task finished
+hard_completed_at: ISO timestamp | null
+soft_completed_at: ISO timestamp | null
+user_name: string
+agent_name: string
+agent_profile_picture: string | null
+
+This file is NOT hot-reloaded. It is managed by the onboarding flow.
+Do NOT edit this file as part of normal operation.
+```
+<!-- /schema:onboarding_config.json -->
+
+### Common edits and recipes
+
+Switch LLM provider:
+```
+read_file app/config/settings.json
+stream_edit app/config/settings.json
+   model.llm_provider: "openai" → "anthropic"
+   model.llm_model: "<old>"     → "claude-sonnet-4-5-20250929"
+api_keys.anthropic must be set or the next LLM call fails (see ## Models).
+```
+
+Set an API key (when user provides one):
+```
+stream_edit app/config/settings.json
+   api_keys.<provider>: ""        → "<key>"
+   api_keys_configured.<provider>: false → true
+```
+
+Enable an MCP server already in the file:
+```
+stream_edit app/config/mcp_config.json
+   mcp_servers[i].enabled: false → true
+   if env requires a token, fill it
+```
+
+Add a new MCP server: see `## MCP` for the full recipe.
+
+Enable / disable a skill:
+```
+stream_edit app/config/skills_config.json
+   move <name> between enabled_skills and disabled_skills
+```
+
+Add a recurring schedule: prefer the `schedule_task` or `recurring_add` actions
+over editing scheduler_config.json directly. They validate the schedule expression.
+See `## Proactive`.
+
+### Pitfalls
+
+- JSON syntax errors silently keep the OLD config in memory. The reload fires, the
+  parser fails, the manager logs the error, and the previous state remains active.
+  Always verify after editing.
+- Editing `version` in settings.json does nothing useful and may confuse the next install.
+- `api_keys_configured` is bookkeeping. If you set a key, also flip the boolean.
+- `core` action set is hardcoded as always-included (see `## Action Sets`). You cannot
+  disable it via config.
+- The watcher subscribes to parent DIRECTORIES, so creating a new file in app/config/
+  is detected, but the file must be explicitly registered for any reload to fire.
+- Sandboxed actions (run_python with requirements) install their packages on first
+  call, NOT on config save. The config has no effect on action sandboxes.
+
+---
+
+## MCP
+
+MCP (Model Context Protocol) servers extend your tool inventory at runtime. Use MCP when you need a capability that no built-in action covers and no skill can compose. Each connected MCP server registers its tools as actions under a dedicated action set, callable through the same action interface as everything else.
+
+Code: [agent_core/core/impl/mcp/client.py](agent_core/core/impl/mcp/client.py) (`MCPClient`, singleton). Config: [app/config/mcp_config.json](app/config/mcp_config.json). Schema in `## Configs`.
+
+### How MCP fits in
+
+```
+mcp_config.json (your edit)
+        │
+        ▼
+MCPClient.initialize() at startup     OR    MCPClient.reload() on hot-reload
+        │
+        ▼
+for each enabled server:
+   spawn subprocess (stdio) OR open connection (sse/websocket)
+   discover its tools
+   register tools as actions in action set "mcp_<server_name>"
+        │
+        ▼
+to use: load the action set in a task (auto-selected, or via add_action_sets)
+        │
+        ▼
+LLM calls the tool just like any other action
+```
+
+The action set name is `mcp_<name>` by default, or whatever `action_set_name` is set to in the entry. After a successful connect, expect log lines like:
+
+```
+[MCP] Connecting to '<name>' (stdio): <command> <args>
+[MCP] Successfully connected to '<name>' with N tools
+[MCP] Registered N tools from server '<name>' into action set 'mcp_<name>'
+```
+
+### Pre-defined servers in this codebase
+
+The shipped `mcp_config.json` contains roughly 157 server entries (most `enabled: false`). Examples of always-shipped, commonly-enabled ones:
+
+```
+filesystem            @modelcontextprotocol/server-filesystem      file ops on cwd
+playwright-mcp        @playwright/mcp                              browser automation
+amadeus-hotels-mcp    travel API                                    hotels search
+github-mcp            @modelcontextprotocol/server-github           GitHub API
+```
+
+Categories present in the shipped config: filesystem, browser automation, calendar/email/notes, finance/markets/crypto, productivity, OS integrations, fitness, search, media, AI/image, e-commerce, dev tools, security, design, analytics, real estate. To enumerate: `grep_files '"name":' app/config/mcp_config.json` returns the full list.
+
+Before adding a NEW server, check the existing entries. The capability you need may already be there as `enabled: false` — flipping the flag is safer than adding a duplicate.
+
+### Add or enable a server (recipe)
+
+```
+1. read_file app/config/mcp_config.json
+2. Decide:
+     - The server already exists with enabled: false  → flip to true (skip to step 5)
+     - You need a new server                         → continue
+3. web_search "<capability> MCP server"
+   Common naming patterns:
+     @modelcontextprotocol/server-<name>      official servers
+     @<org>/<name>-mcp                        community servers
+     GitHub repos following the MCP spec
+4. stream_edit app/config/mcp_config.json
+   Append to mcp_servers array. Use the schema from ## Configs.
+   Set enabled: true. Set env keys (API tokens, etc.) if required.
+5. Wait ~0.5s for the watcher to debounce.
+6. Verify: see "Verifying a server is live" below.
+7. If verification fails, see "Failure modes and log signatures".
+```
+
+If the server's `env` requires a credential (API key, OAuth token, bot token), ASK THE USER for it. Do not invent values. Empty env strings are common defaults; the server will report missing-credential errors at first tool call.
+
+### Transport patterns
+
+```
+stdio (subprocess, most common)
+  transport: "stdio"
+  command:   "npx" | "uv" | "python" | "node" | <executable>
+  args:      [...]
+  env:       { KEY: VALUE }
+  url:       (omit)
+
+  Examples:
+    NPX:        command="npx",    args=["-y", "@modelcontextprotocol/server-filesystem", "."]
+    Python uv:  command="uv",     args=["run", "--directory", "C:/path/to/server", "main.py"]
+    Python pip: command="python", args=["-m", "<module_name>"]
+    Node:       command="node",   args=["<path-to-script.js>"]
+
+sse (server-sent events, remote)
+  transport: "sse"
+  url:       "http://localhost:3000/mcp"  or  "https://<host>/mcp"
+  command:   (omit)
+  env:       (often unused; the server handles its own auth)
+
+websocket (remote)
+  transport: "websocket"
+  url:       "ws://..."  or  "wss://..."
+```
+
+If the server author provides a `claude_desktop_config.json` snippet (common pattern), copy the `command`, `args`, and `env` directly. The schema is identical.
+
+### Verifying a server is live
+
+After enabling/adding, in order of cheapness:
+
+```
+1. grep the latest log for the server's name:
+     grep_files "[MCP].*<server_name>" logs/<latest>.log -A 1
+   Expect: "Successfully connected" + "Registered N tools".
+
+2. confirm the action set is registered:
+     call list_action_sets   → look for "mcp_<server_name>" in the result.
+
+3. load the set into your task:
+     call add_action_sets({"action_sets": ["mcp_<server_name>"]})
+     The new tools appear in the next turn's action list.
+
+4. call a tool from the set.
+   If it returns status=success, you're done. If status=error, the message
+   will usually point at credentials or remote-service issues.
+```
+
+If steps 1-2 fail, the server did not connect. Go to "Failure modes" below.
+If steps 3-4 fail, the server connected but tool execution is broken. Usually credentials.
+
+### Failure modes and log signatures
+
+```
+Symptom in log                                       Likely cause              Fix
+───────────────────────────────────────────────────  ────────────────────────  ──────────────────────────
+[MCP] Failed to load MCP config from <path>: ...     malformed JSON in         re-read mcp_config.json,
+                                                     mcp_config.json           fix syntax via stream_edit
+
+[MCP] Failed to connect to '<name>' - check          missing dep / wrong path  reproduce in run_shell:
+server configuration                                                            run the exact command +
+                                                                                args. Inspect stderr.
+
+[StdioTransport] Starting subprocess: <cmd>          subprocess started but    check the next few log
+followed by no "Successfully connected"              died early                lines for stderr from
+                                                                                the subprocess.
+
+[MCP] Exception connecting to '<name>': <type>: ...  any other connect-time    type tells you the class:
+                                                     error                     FileNotFoundError = command
+                                                                                missing; ConnectionError =
+                                                                                remote unreachable.
+
+server connected, tool calls return                  missing or wrong env      ask user for the key, set
+"unauthorized" / "missing API key" / "401"           variable                   it via /mcp env <name>
+                                                                                <KEY> <value>, or
+                                                                                stream_edit the env block.
+
+server connected, tool calls hang                    wrong transport (e.g.     fix transport in config.
+                                                     sse server marked stdio)
+
+server connected, tool calls succeed but always      remote rate limited       slow down or upgrade the
+return errors after first burst                                                remote-service plan.
+```
+
+Reproducing a stdio server outside the harness:
+
+```
+run_shell "<command> <args...>"   ← run literally what's in the config
+```
+
+If the subprocess fails standalone, the harness will fail too. Fix it standalone first.
+
+### Hot-reload behavior on save
+
+`MCPClient.reload(config_path)` does the following on each `mcp_config.json` save:
+
+```
+1. re-parse mcp_config.json
+2. for each currently-connected server:
+     if not in new config OR enabled=false in new config  →  disconnect
+3. for each enabled server in new config:
+     if not currently connected                            →  connect, register tools
+4. re-register all tools as actions
+5. return { success, disconnected[], connected[], failed[], total_tools }
+```
+
+Implications:
+- Toggling `enabled` cleanly connects or disconnects a single server.
+- Editing `env` for a connected server does NOT take effect until the server reconnects. Disable then re-enable, or call `mcp_client.reload()` after the file change.
+- Tasks already running keep their LOCKED action sets. New MCP tools become callable in the NEXT task or after `add_action_sets`.
+
+### Slash commands (user-side)
+
+```
+/mcp list                                  servers + connection state
+/mcp add <name> <command> [args...]        register a stdio server
+/mcp add-json <json>                       register from a full JSON entry
+/mcp remove <name>                         remove from config
+/mcp enable <name>                         flip enabled to true
+/mcp disable <name>                        flip enabled to false
+/mcp env <name> <KEY> <value>              set/update an env var
+```
+
+The agent does NOT call slash commands. If the user has not exposed an MCP server you need, edit the config directly via `stream_edit`.
+
+### When to choose MCP vs alternatives
+
+```
+Need a capability and...
+
+an existing built-in action covers it           →  use the action  (## Actions)
+a skill could compose existing actions          →  write/use a skill (## Skills)
+a third party already ships an MCP server       →  add MCP server (here)
+the user has a connected integration            →  use integration actions (## Integrations)
+nothing exists, you have to write code          →  author a new action (## Actions)
+```
+
+MCP is for capabilities you cannot get any other way without writing Python. The cost is process management, network, and an extra credential to maintain.
+
+### Permission and disclosure
+
+- Adding/enabling an MCP server modifies your runtime tool surface. Tell the user before doing it.
+- If `env` requires credentials, ASK first. Do not write empty placeholders to "test" — that just creates noise in logs and confuses the user.
+- After successful enable, summarize what tools the new server adds (count + a few names).
+
+---
+
+## Skills
+
+A skill is a markdown file with structured instructions that get injected into your prompt when selected. Skills exist for reusable workflows and codified domain knowledge that compose existing actions. Use a skill instead of an MCP server when no new tools are needed, just better instructions.
+
+Code: [agent_core/core/impl/skill/loader.py](agent_core/core/impl/skill/loader.py) (`SkillLoader`), [agent_core/core/impl/skill/config.py](agent_core/core/impl/skill/config.py) (`SkillMetadata`, `Skill`, `SkillsConfig`), [agent_core/core/impl/skill/manager.py](agent_core/core/impl/skill/manager.py) (`SkillManager` singleton).
+
+### What a skill is
+
+```
+A directory:                  skills/<name>/
+                              ├── SKILL.md         required
+                              └── <support files>  optional, referenced by SKILL.md
+
+A SKILL.md file:              YAML frontmatter (metadata)
+                              + markdown body (instructions injected into your prompt)
+
+When selected during a task:  body appended to your context until task_end.
+                              action-sets it declares are auto-loaded.
+                              /<name> slash command is registered (if user-invocable).
+```
+
+A skill is NOT a process, NOT a tool, NOT an action. It is text instructions plus a small bundle of action-set selections. The tools it uses are existing actions (built-in, MCP, integrations).
+
+### SKILL.md format
+
+```
+---
+name: <unique_id>                      required. Snake-case or kebab-case.
+description: <one paragraph>           required. The LLM reads this to decide
+                                        when to select. Be specific about WHEN
+                                        and WHAT triggers selection. Vague
+                                        descriptions never get selected.
+argument-hint: <hint>                  optional. Shown in /help when user types
+                                        /<name>. Example: "<city>" or "<file_path>".
+user-invocable: true                   optional, default true.
+                                        true = registers /<name> slash command.
+                                        false = only LLM-selectable mid-task.
+allowed-tools: [<action_name>, ...]    optional. If non-empty, ONLY these actions
+                                        are callable while the skill is active.
+                                        Empty / omitted = no restriction.
+action-sets: [<set_name>, ...]         optional. Auto-loaded when the skill is
+                                        selected. Use this to declare what tools
+                                        the skill needs (e.g. file_operations,
+                                        web_research, mcp_<server_name>).
+---
+
+# <Skill title>
+
+<Markdown body. Headings, lists, code blocks, examples - anything you'd put
+in a procedure document. This text is appended to your prompt for the
+duration of the task.>
+```
+
+Frontmatter parsing (regex `^---\s*\n(.*?)\n---\s*\n(.*)$`):
+- The file MUST start with `---` on the first line.
+- The frontmatter MUST be valid YAML.
+- Keys may use `kebab-case` OR `snake_case`. Both `argument-hint` and `argument_hint` work; same for the others.
+- If `name` is missing, the directory name is used.
+- If `description` is missing, the first non-heading paragraph of the body is used (truncated to 200 chars).
+
+### Variable substitution in the body
+
+When a skill is invoked with arguments (e.g. `/get-weather Tokyo`), the body's variables are substituted before injection ([SkillLoader.substitute_variables](agent_core/core/impl/skill/loader.py)):
+
+```
+$ARGUMENTS         the full argument string ("Tokyo")
+$ARGUMENTS[0]      first positional arg, 0-indexed
+$ARGUMENTS[1]      second positional arg
+$0, $1, $2 ...     shorthand for $ARGUMENTS[N]
+```
+
+If the skill is selected by the LLM mid-task (not via slash invocation), arguments are typically empty and these placeholders resolve to empty strings. Write skills to handle both invocation paths.
+
+### Discovery and enable flow
+
+```
+1. SkillLoader.discover_skills(search_dirs=[skills/], config=SkillsConfig)
+   scans <project_skills_dir>/<name>/SKILL.md files
+   parses frontmatter + body via FRONTMATTER_PATTERN
+2. for each parsed skill:
+     if name in disabled_skills (skills_config.json)  -> enabled=false
+     else                                             -> enabled=true
+3. enabled skills are presented to the LLM each task turn for selection
+4. user-invocable + enabled skills are registered as /<name> slash commands
+```
+
+Discovery runs at startup AND on every save of [app/config/skills_config.json](app/config/skills_config.json). The directory itself is NOT watched, so adding a brand-new skill directory requires either editing `skills_config.json` (any save triggers rediscovery) or running `/skill reload`.
+
+### How a skill gets selected for a task
+
+Two paths:
+
+**Path 1: User invocation via slash command.** When the user types `/<skill_name> [args]`:
+```
+1. The runtime calls do_create_task(...) with pre_selected_skills=[<skill_name>]
+2. LLM skill selection is BYPASSED (user already chose).
+3. LLM action-set selection still runs, then merges with skill's action-sets.
+4. Body is injected with $ARGUMENTS substituted.
+5. Task starts. Skill stays active for the entire task.
+```
+
+**Path 2: LLM selection.** When the user makes a request without slashing in:
+```
+1. do_create_task runs LLM skill+action-set selection (single LLM call).
+2. LLM picks zero, one, or more relevant skills based on their `description`.
+3. For each picked skill: body injected, action-sets merged, task starts.
+4. Skills picked stay active until task_end.
+```
+
+Skills CANNOT be swapped mid-task. To change skills, end the task and start a new one. Action sets CAN be swapped mid-task (see `## Action Sets`).
+
+### `allowed-tools` restriction
+
+When `allowed-tools` is non-empty in the frontmatter, the action filter narrows to ONLY those names while the skill is active. Use this for safety-critical skills where you want to prevent the LLM from straying. Leave empty (the default) for normal skills.
+
+### `action-sets` auto-loading
+
+When a skill is selected, every name in its `action-sets` is added to the task's action sets. The merger logic (in `do_create_task` at [app/internal_action_interface.py](app/internal_action_interface.py)):
+
+```
+final_action_sets = dedup(skill.action_sets + llm_selected_action_sets)
+```
+
+A skill that needs `web_research`, `file_operations`, and an MCP server should declare:
+```
+action-sets:
+  - web_research
+  - file_operations
+  - mcp_<server_name>
+```
+
+Don't rely on the LLM to pick the right sets. Declare them.
+
+### Adding a new skill
+
+Three paths, in order of preference:
+
+**1. Use the built-in `craftbot-skill-creator` skill.**
+```
+User runs:    /craftbot-skill-creator <name> <description>
+or LLM picks craftbot-skill-creator mid-task
+```
+This skill walks through the scaffold (writes the SKILL.md, sets up the directory, suggests action-sets). Most reliable path.
+
+**2. Install from a git repo.**
+```
+1. read_file app/config/skills_config.json       (avoid duplicates)
+2. web_search "<capability> SKILL.md github"     (or known skill repos)
+3. run_shell "git clone <url> skills/<name>"
+4. stream_edit app/config/skills_config.json
+     - move <name> from disabled_skills (if present) to enabled_skills
+     - or just add it to enabled_skills if new
+5. wait ~0.5s for hot-reload
+6. verify: /skill list (user-side) or call list_skills action
+```
+
+**3. Author by hand.**
+```
+1. mkdir skills/<name>
+2. write_file skills/<name>/SKILL.md
+   (use the format above; copy a similar existing skill as template)
+3. stream_edit app/config/skills_config.json to add to enabled_skills
+4. wait ~0.5s for hot-reload
+5. verify
+```
+
+After adding, the skill is available to the NEXT task. The currently-running task (if any) keeps its locked skill list.
+
+### Enable and disable
+
+A skill's enabled state is governed by its presence in `enabled_skills` vs `disabled_skills` in [app/config/skills_config.json](app/config/skills_config.json):
+
+```
+enabled_skills:    [<name>, ...]    skills available for LLM selection / slash invocation
+disabled_skills:   [<name>, ...]    explicitly OFF (loaded but invisible)
+not in either:                       loaded as enabled if auto_load=true (default)
+```
+
+Toggle via `stream_edit` on `skills_config.json`, OR via the user-side commands `/skill enable <name>` / `/skill disable <name>`. Both go through the same hot-reload path.
+
+### Verifying changes
+
+After enable / disable / install:
+
+```
+1. grep_files "[SKILL]" logs/<latest>.log -A 1     (confirm reload fired)
+2. action: list_skills                              (returns the live list)
+3. user-side: /skill list                           (same data, different UI)
+4. /<skill_name>                                    (only works if user-invocable=true
+                                                     AND enabled, else 404)
+```
+
+### Skill vs MCP vs action vs prompt - when to choose
+
+```
+Capability needs new code or external service                         -> MCP server (## MCP)
+Capability needs new code, isolated to the agent                      -> author an action (## Actions)
+Capability already exists, just needs orchestration / domain steps    -> skill (here)
+Just want to nudge the LLM with a one-off instruction                 -> put it in the user message,
+                                                                          NOT in a skill
+```
+
+Skills shine for: multi-step workflows ("first check X, then if Y, do Z"), domain expertise ("when generating slides, follow these design rules"), and codified procedures the LLM should follow exactly every time.
+
+### Pitfalls
+
+- A skill with a vague `description` will never get auto-selected. Be specific about triggers.
+- A skill that declares `action-sets` it doesn't actually need bloats the prompt.
+- A skill with `allowed-tools` that's too narrow will hit dead ends mid-task. Test before shipping.
+- Forgetting to add the skill to `enabled_skills` after a fresh install. It stays invisible. Always verify.
+- Editing a SKILL.md body of an installed skill: the change applies to the NEXT task. The currently-running task keeps the cached version.
+- Body too long: skill body is injected into every prompt for the task. Keep it tight.
+
+### Pre-shipped skills (sample)
+
+The shipped `skills/` directory contains around 100+ entries. Most are disabled by default; flip them via `enabled_skills` in `skills_config.json` to use. Examples currently enabled in this build:
+
+```
+get-weather                  weather lookup via Playwright + BBC Weather
+weather-check                similar pattern, alternative source
+craftbot-skill-creator       authoring new skills
+craftbot-skill-improve       refining an existing skill
+predict-stock-next-week      stock prediction workflow
+docx, pptx, xlsx, pdf        document generation per file format
+file-format                  format normalization
+playwright-mcp               browser automation steering
+living-ui-creator,
+living-ui-modify,
+living-ui-manager            Living UI project lifecycle
+compile-report-advance       multi-source report compilation
+```
+
+To enumerate the full installed set: `list_folder skills/` or `read_file app/config/skills_config.json`. To inspect a specific skill before enabling: `read_file skills/<name>/SKILL.md`.
+
+---
+
+## Integrations
+
+You can help the user connect external integrations directly through chat. Most token-based integrations can be fully driven by you: collect the credential from the user, call `connect_integration` with it, and the listener auto-starts. OAuth integrations require the user to run a slash command that opens a browser — your job is to walk them through it. Treat connecting an integration like helping a non-technical friend: tell them exactly where to go, what to copy, and what to paste back.
+
+Code: [app/external_comms/integration_settings.py](app/external_comms/integration_settings.py) (`INTEGRATION_REGISTRY`, `connect_integration_token`, `connect_integration_oauth`, `connect_integration_interactive`). Handlers: [app/credentials/handlers.py](app/credentials/handlers.py) (`INTEGRATION_HANDLERS`).
+
+### What's wired in
+
+11 integrations registered in `INTEGRATION_REGISTRY`. Each has an `auth_type` that determines how connection happens:
+
+```
+id                  display name        auth_type                description
+─────────────────   ─────────────────   ──────────────────────   ──────────────────────────────
+google              Google Workspace    oauth                    Gmail, Calendar, Drive
+slack               Slack               both (oauth + token)     Team messaging
+notion              Notion              both (oauth + token)     Notes and databases
+linkedin            LinkedIn            oauth                    Professional network
+discord             Discord             token                    Community chat
+telegram            Telegram            token_with_interactive   Messaging platform
+whatsapp            WhatsApp            interactive (QR scan)    Messaging via Web
+whatsapp_business   WhatsApp Business   token                    WhatsApp Cloud API
+jira                Jira                token                    Issue tracking
+github              GitHub              token                    Repos, issues, PRs
+twitter             Twitter/X           token                    Tweets, timeline
+```
+
+To enumerate at runtime: call the `list_available_integrations` action. To check what's already connected: `check_integration_status`.
+
+### The agent's connection toolkit (actions)
+
+```
+list_available_integrations()                  → returns full registry + connected state for each
+check_integration_status(integration_id)       → status of one integration
+connect_integration(integration_id, ...)       → token-based connect (requires credentials)
+disconnect_integration(integration_id)         → remove connection
+```
+
+`connect_integration` is the workhorse for token-based flows. The exact required fields depend on the integration. Read [app/data/action/integration_management.py](app/data/action/integration_management.py) for the action's input_schema.
+
+### Auth-type playbook
+
+The user just asked you to connect an integration. Here's what you do for each `auth_type`:
+
+```
+auth_type "token"
+  Driven entirely from chat by you. Steps:
+    1. Tell user where to obtain the credential (links + scopes below).
+    2. User pastes the credential in chat.
+    3. You call connect_integration(integration_id, credentials={...}).
+    4. Verify with check_integration_status.
+
+auth_type "oauth"
+  Cannot be fully driven from chat. The user must run a slash command that
+  opens a browser. Steps:
+    1. Confirm settings.json has the right oauth.<platform> client_id and
+       client_secret. If empty, tell the user to register an OAuth app at
+       the platform's developer console (links below) and paste the IDs.
+       You can stream_edit settings.json once they paste.
+    2. Tell user: "Run /<platform> login (or /<platform> invite). It will
+       open a browser. Authorize, then come back."
+    3. Wait for user to confirm. Do NOT poll.
+    4. Call check_integration_status to confirm connection.
+
+auth_type "both"
+  Two paths. Pick based on user preference:
+    - User has CraftOS bot/app available     → /<platform> invite (OAuth)
+    - User has their own bot token / app     → connect_integration with token
+  Default to whichever the user already mentioned. If unclear, ask.
+
+auth_type "interactive" (whatsapp)
+  Requires a QR scan from the user's phone. Steps:
+    1. Tell user: "Run /whatsapp login. A QR code will appear. Scan it with
+       WhatsApp on your phone (Settings → Linked Devices → Link a Device)."
+    2. Wait for user to confirm scan.
+    3. Verify with check_integration_status.
+
+auth_type "token_with_interactive" (telegram)
+  Token is the primary path; the same as "token". Telegram has additional
+  user-account flows (login-user) that are interactive — only invoke if the
+  user explicitly wants user-account access (not bot).
+```
+
+Never invent a credential. If the user has not provided one, ask. If the user pastes something that doesn't match the expected format, point out what was expected before calling `connect_integration`.
+
+### Required fields and where to obtain them
+
+The fields each token integration needs (from `INTEGRATION_REGISTRY`):
+
+```
+slack
+  bot_token         (required, "xoxb-..." — Bot User OAuth Token)
+  workspace_name    (optional, friendly label)
+  Where to get it:
+    1. Go to https://api.slack.com/apps → Create New App (from scratch).
+    2. OAuth & Permissions → add scopes (chat:write, channels:read,
+       channels:history, users:read, etc. depending on use).
+    3. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-...).
+
+notion
+  token             (required, "secret_..." — Internal Integration Secret)
+  Where to get it:
+    1. Go to https://www.notion.so/my-integrations → New integration.
+    2. Pick a workspace and a name. Submit.
+    3. Copy the "Internal Integration Secret".
+    4. In Notion, share the relevant pages/databases with the integration
+       (the "..." menu on each page → Add connections).
+
+discord
+  bot_token         (required — Bot Token from a Discord application)
+  Where to get it:
+    1. Go to https://discord.com/developers/applications → New Application.
+    2. Bot tab → Add Bot → "Reset Token" → copy.
+    3. Enable required intents (Message Content, Server Members, etc.).
+    4. OAuth2 → URL Generator → bot scope + permissions → invite bot to server.
+
+telegram (bot)
+  bot_token         (required — from @BotFather)
+  Where to get it:
+    1. On Telegram, message @BotFather.
+    2. /newbot → set name and username (must end in "bot").
+    3. @BotFather replies with the token. Copy and paste.
+
+whatsapp_business
+  access_token      (required — Meta Cloud API access token)
+  phone_number_id   (required — phone number ID from Meta Business)
+  Where to get it:
+    1. Go to https://developers.facebook.com → My Apps → Create App
+       (Business type) → Add Product → WhatsApp.
+    2. From the WhatsApp config: copy the temporary access token AND the
+       phone_number_id of the test number (or your own once verified).
+    3. For production, generate a permanent token via System User.
+
+jira
+  domain            (required — e.g. mycompany.atlassian.net, no https)
+  email             (required — your Atlassian account email)
+  api_token         (required — Atlassian API token)
+  Where to get it:
+    1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.
+    2. Create API token → label it → copy.
+
+github
+  access_token      (required — Personal Access Token, "ghp_..." or "github_pat_...")
+  Where to get it:
+    1. Go to https://github.com/settings/tokens → Generate new token.
+    2. For full repo access, classic token with repo, workflow, read:org scopes;
+       fine-grained tokens work for specific repos.
+    3. Copy the token (only shown once).
+
+twitter
+  api_key             (required — Consumer Key)
+  api_secret          (required — Consumer Secret)
+  access_token        (required)
+  access_token_secret (required)
+  Where to get it:
+    1. Go to https://developer.twitter.com → Projects & Apps → create an app.
+    2. Keys and tokens tab: regenerate Consumer Keys, then Access Token and Secret.
+    3. Apps need at least Read+Write user-context permissions for posting.
+```
+
+For OAuth integrations (no fields, but client_id/client_secret in `settings.json` `oauth.<platform>`):
+
+```
+google
+  client_id, client_secret in settings.json → oauth.google
+  Where to get it:
+    1. Go to https://console.cloud.google.com/apis/credentials.
+    2. Create OAuth 2.0 Client ID → Desktop app or Web application.
+    3. Copy client_id and client_secret.
+    4. Enable APIs you need: Gmail API, Google Calendar API, Google Drive API.
+    5. After saving keys to settings.json, user runs /google login.
+
+linkedin
+  client_id, client_secret in settings.json → oauth.linkedin
+  Where to get it:
+    1. Go to https://www.linkedin.com/developers/apps.
+    2. Create app → set redirect URL (the CraftBot OAuth callback).
+    3. Verify app, request access to required products.
+    4. Copy Client ID and Client Secret.
+    5. After saving keys to settings.json, user runs /linkedin login.
+
+slack OAuth (alternate to bot token)
+  client_id, client_secret in settings.json → oauth.slack
+  User runs /slack invite (uses CraftOS-hosted app) or set up your own.
+
+notion OAuth (alternate to integration token)
+  client_id, client_secret in settings.json → oauth.notion
+  Most users prefer the token path (simpler).
+```
+
+### End-to-end chat-driven connection example
+
+A canonical chat-driven flow for `github`:
+
+```
+User: "connect my github"
+
+Agent (in conversation mode):
+  task_start(task_mode="simple", task_description="Connect user's GitHub")
+
+Agent (inside the task):
+  send_message: "I can connect GitHub. I'll need a Personal Access Token.
+                 To create one:
+                 1. Go to https://github.com/settings/tokens
+                 2. Click 'Generate new token (classic)'
+                 3. Pick the scopes you need (repo, workflow, read:org for full access)
+                 4. Generate and copy the token (it's only shown once)
+                 Paste it here when ready."
+
+User: "ghp_abc123xyz..."
+
+Agent:
+  connect_integration(
+    integration_id="github",
+    credentials={"access_token": "ghp_abc123xyz..."}
+  )
+  → returns {status: "success", message: "..."}
+
+Agent:
+  check_integration_status(integration_id="github")
+  → confirms connected, lists account name
+
+  send_message: "Connected. You're authenticated as <username>. You can now
+                 ask me to read your repos, manage issues, or open PRs."
+  task_end
+```
+
+For `oauth` integrations the analogous flow:
+
+```
+User: "connect my google account"
+
+Agent:
+  Check settings.json oauth.google. If client_id/client_secret are empty,
+  walk the user through registering an OAuth app at console.cloud.google.com,
+  collect the IDs, stream_edit settings.json, then continue.
+
+  send_message: "Now run `/google login` in chat. A browser will open.
+                 Authorize CraftBot, then come back here and tell me when
+                 you're done."
+
+User: "done"
+
+Agent:
+  check_integration_status(integration_id="google")
+  → if connected: confirm + list scopes/account
+  → if not: ask user to retry, mention common issues (popup blocked,
+            wrong account picked, scopes denied)
+```
+
+### Listener auto-start
+
+After a successful `connect_integration` call, listeners auto-start for platforms that support push-style messaging. From `PLATFORM_MAP`:
+
+```
+whatsapp     → whatsapp_web listener
+telegram     → telegram_bot AND telegram_user listeners
+google       → google_workspace listener
+jira         → jira listener
+github       → github listener
+twitter      → twitter listener
+```
+
+For `slack`, `notion`, `discord`, `linkedin`, `outlook`, `whatsapp_business`: connection works but listener-style auto-reply is not configured at this layer (some are handled separately via `external_comms_config.json` for telegram/whatsapp specifically).
+
+### Verifying a connection
+
+After any connect attempt:
+
+```
+1. check_integration_status(integration_id)         → returns success + account display
+2. /cred status (user-side)                          → overview of all integrations
+3. grep_files "[<platform>]" logs/<latest>.log     → look for connect / auth errors
+```
+
+If `check_integration_status` returns "Not connected" right after a successful `connect_integration` call, something is wrong. Common: the credential validated but the listener failed to start (check logs for that platform's tag).
+
+### Disconnect
+
+```
+disconnect_integration(integration_id, account_id?)
+```
+
+`account_id` is optional. Pass it when there are multiple accounts on one platform (e.g. multiple Slack workspaces) and you want to keep the others. Omit to disconnect everything for that integration.
+
+The user can also `/<platform> disconnect [account_id]`.
+
+### Common failure modes
+
+```
+Symptom                                            Likely cause              Fix
+─────────────────────────────────────────────────  ────────────────────────  ──────────────────────────
+"Bot token is required" / "Token is required"      missing credential        ask user, retry
+                                                   in connect_integration
+
+connect succeeds, but tool calls return            scope insufficient        user re-creates token
+"Forbidden" / "Insufficient scope"                                            with proper scopes
+
+oauth connect: browser doesn't open                missing client_id/secret  walk user through
+                                                   in settings.json          registering OAuth app
+                                                                              and pasting IDs
+
+oauth connect: "redirect_uri_mismatch"             redirect URL wrong in     fix redirect URL in
+                                                   the developer console     developer console
+
+whatsapp QR: timeout                               user did not scan in time tell user to retry,
+                                                                              ensure phone has network
+
+jira: 401 / 403 on tool calls                      domain or email wrong     user re-checks domain
+                                                                              format and Atlassian email
+
+twitter: invalid signature                         API tier doesn't allow    user upgrades Twitter API
+                                                   the operation             tier (free is read-only)
+
+connection works once, fails next session          token expired (some       user regenerates and
+                                                   GitHub fine-grained       reconnects
+                                                   tokens have short TTL)
+```
+
+When in doubt: read the action's error message in full, then check `logs/<latest>.log` for the integration's tag.
+
+### When to use integration actions vs MCP
+
+Some integrations have BOTH built-in actions (via this section's connection flow) AND a corresponding MCP server (e.g. `github`, `notion`, `slack`). Pick:
+
+```
+You need basic CRUD via the user's account                    → built-in integration (here)
+You need rich tool surface, custom workflows, or a feature
+the built-in action doesn't expose                            → MCP server (## MCP)
+The user has both connected                                   → use the integration first;
+                                                                 fall back to MCP if missing a verb
+```
+
+The built-in integrations cover the common 80%; MCP covers the long tail.
+
+### Permission and disclosure
+
+- ALWAYS tell the user what credentials you need and where to get them. Never paste a vague "give me your token".
+- ALWAYS confirm the credential format roughly matches before submitting (e.g., GitHub PAT starts with `ghp_` or `github_pat_`). If it doesn't, ask the user to verify.
+- ALWAYS mask tokens in your replies. Don't echo back the full credential — use a prefix or a `...` truncation.
+- ALWAYS verify connection success before declaring victory.
+- NEVER write the token to memory, MEMORY.md, USER.md, or chat history beyond the immediate connect step. The handler stores it under `.credentials/<platform>.json` (see `## File System` for the do-not-print rule).
+
+---
+
+## Models
+
+You generate every response through an LLM. The user can ask you to change provider or model in chat, and you can drive that change. This section covers: providers, the model registry, LLM vs VLM vs embedding, the right way to switch (with a critical gotcha), per-provider caching strategy, and rate-limit handling.
+
+Code: [agent_core/core/impl/llm/interface.py](agent_core/core/impl/llm/interface.py) (`LLMInterface`), [agent_core/core/models/model_registry.py](agent_core/core/models/model_registry.py) (`MODEL_REGISTRY`), [app/models/factory.py](app/models/factory.py) (`ModelFactory.create`), [app/ui_layer/settings/model_settings.py](app/ui_layer/settings/model_settings.py) (`PROVIDER_INFO`).
+
+### Three interface types
+
+The same provider serves up to three "interfaces":
+
+```
+LLM         text generation. The main chat brain. Required.
+VLM         vision-language model. Used for image actions (describe_image, OCR).
+EMBEDDING   text embedding. Used for memory_search semantic indexing.
+```
+
+Each interface picks its model independently. `settings.json` `model.llm_provider` and `model.vlm_provider` can point at different providers if you want (e.g., `anthropic` for text, `gemini` for vision).
+
+### Providers and what they support
+
+From [MODEL_REGISTRY](agent_core/core/models/model_registry.py):
+
+```
+provider     LLM default model            VLM default model           EMBEDDING default        notes
+─────────    ──────────────────────       ──────────────────────      ──────────────────────   ─────────────────────────────
+openai       gpt-5.2-2025-12-11           gpt-5.2-2025-12-11          text-embedding-3-small   OpenAI-hosted
+anthropic    claude-sonnet-4-5-20250929   claude-sonnet-4-5-20250929  (none — no embedding)    Claude models
+gemini       gemini-2.5-pro               gemini-2.5-pro              text-embedding-004       Google Gemini
+byteplus     seed-1-6-250915              seed-1-6-250915             skylark-embedding-...    BytePlus-hosted
+remote       llama3.2:3b                  llava:7b                    nomic-embed-text         Ollama or OpenAI-compat
+deepseek     deepseek-chat                (none)                      (none)                   text only
+moonshot     moonshot-v1-8k               (none)                      (none)                   text only
+grok         grok-3                       grok-4-0709                 (none)                   xAI
+minimax      MiniMax-Text-01              (none)                      (none)                   text only
+```
+
+If you set `model.llm_model: null` in settings.json, the default from MODEL_REGISTRY is used. Set an explicit string to override.
+
+A provider with `(none)` for VLM cannot be used as `vlm_provider`. If the user asks for vision but only has a text-only provider configured, tell them to set a separate `vlm_provider` (or use `byteplus` / `anthropic` / `openai` / `gemini` for vision).
+
+### Provider-name vs settings-key mismatch (gotcha)
+
+The provider names used in code and in `model.llm_provider` are not always identical to the `api_keys.<key>` names:
+
+```
+provider name   settings.json api_keys field   /provider command alias
+─────────────   ─────────────────────────       ──────────────────────
+openai          api_keys.openai                 openai
+anthropic       api_keys.anthropic              anthropic
+gemini          api_keys.google                 gemini    (note: provider name is "gemini" but the key is stored under "google")
+byteplus        api_keys.byteplus               byteplus
+deepseek        api_keys.deepseek               deepseek
+grok            api_keys.grok                   grok
+remote          (none — uses endpoints.remote)  remote
+```
+
+When setting an API key for Gemini, edit `api_keys.google`, NOT `api_keys.gemini`. Same translation in the `api_keys_configured` block.
+
+### Model section schema (in settings.json)
+
+```
+model:
+  llm_provider:        string        e.g. "anthropic"
+  vlm_provider:        string        e.g. "anthropic"  (often same as llm_provider)
+  llm_model:           string|null   null = use MODEL_REGISTRY default for the provider
+  vlm_model:           string|null   null = use MODEL_REGISTRY default
+  slow_mode:           bool          true = throttle requests to avoid 429s
+  slow_mode_tpm_limit: int           tokens per minute when slow_mode is true (e.g. 25000)
+```
+
+Full settings.json schema is in `## Configs`.
+
+### How LLMInterface picks the model
+
+At construction (and on `reinitialize_llm`), `ModelFactory.create(provider, interface, model_override, ...)`:
+
+```
+1. Looks up the provider in MODEL_REGISTRY[provider][interface].
+2. If model_override is set, uses it. Otherwise uses the registry default.
+3. Wires up the right client: OpenAI SDK, Anthropic SDK, Gemini client, BytePlus
+   wrapper, or Ollama HTTP for "remote".
+4. Returns ctx with provider, model, client/handles, base URL, etc.
+```
+
+The LLMInterface is constructed ONCE at startup (and reconstructed by `reinitialize_llm`). It is NOT recreated when settings.json is hot-reloaded. This is the most important gotcha in this section — see "Switching provider or model" below.
+
+### Switching provider or model — through chat
+
+The user asks: "switch to GPT-4" or "use Gemini" or "I'd like to try Claude".
+
+There are TWO mutation paths. Pick the right one based on what's changing:
+
+**Path A: Same-provider model swap (e.g. claude-sonnet-4 → claude-opus-4)**
+
+Edit `settings.json` and the change applies on the NEXT LLM call. The cache invalidates on save; the existing client uses the new model name from the next call onward.
+
+```
+1. read_file app/config/settings.json
+2. stream_edit:
+     model.llm_model: "<old>" → "<new>"
+     (also model.vlm_model if user wants vision swap)
+3. wait ~0.5s for hot-reload
+4. send_message confirming the swap took effect on next turn
+```
+
+**Path B: Provider switch (e.g. anthropic → openai)**
+
+`stream_edit` ALONE is not enough. The LLMInterface holds the old provider's client. You must trigger `reinitialize_llm`, which is exposed only via the `/provider` slash command.
+
+```
+1. Ensure api_keys.<settings_key> for the new provider is set.
+   Remember the gemini → "google" name translation.
+   If empty: ask the user for a key, then stream_edit api_keys + api_keys_configured.
+2. Tell the user to run:    /provider <name> [<api_key>]
+   Examples:    /provider openai sk-...
+                /provider anthropic
+                /provider gemini AIza...
+3. The slash command:
+     - saves to settings.json (settings, api_keys, env)
+     - calls agent.reinitialize_llm(<provider>) which rebuilds the LLMInterface
+4. Verify by waiting for the next LLM-driven response; mention the new provider
+   is in effect.
+```
+
+DO NOT just stream_edit `model.llm_provider` and call it done. The cache will say the new provider, but the LLMInterface will still use the old one until reinit. Symptoms of getting this wrong: replies still come from the old model, or LLMConsecutiveFailureError if the old client now lacks credentials.
+
+If the user cannot or will not run the slash command, the alternative is restarting CraftBot. State that explicitly.
+
+### Setting a missing API key (no provider switch)
+
+If the user just provides a new key for the CURRENT provider (e.g., they updated their Anthropic key):
+
+```
+1. stream_edit settings.json
+     api_keys.<settings_key>: "<old or empty>" → "<new>"
+     api_keys_configured.<settings_key>: false → true
+2. Hot-reload picks up the new key on next LLM call.
+3. If unsure whether the existing client cached the old key, recommend the user
+   run /provider <current> <new_key> to rebuild the client cleanly.
+```
+
+### Connection testing
+
+Before declaring the switch worked, verify. There's a built-in test using
+[app/config/connection_test_models.json](app/config/connection_test_models.json) (a tiny model + 1-token request per provider).
+
+```
+1. read_file app/config/connection_test_models.json   (see what model is used to test)
+2. test_provider_connection(provider, api_key)        helper at app/models
+                                                       (or wait for the user's first
+                                                        response to confirm)
+```
+
+The cheapest verification is just sending a `send_message` and waiting for the reply to come back without `LLMConsecutiveFailureError`.
+
+### Slow mode (rate-limit handling)
+
+If the user hits 429s (provider rate limit):
+
+```
+slow_mode: true                  pace requests
+slow_mode_tpm_limit: <N>         tokens per minute target. Common: 25000 for Anthropic free.
+```
+
+Set both. The throttle is internal to LLMInterface. After enabling, no further changes needed for the user — requests just take longer.
+
+### Per-provider caching (KV cache strategy)
+
+The harness applies different caching strategies per provider. You don't manage this directly, but knowing it helps explain cost/latency to the user:
+
+```
+provider      cache type                                managed by
+─────────     ───────────────────────────────────────   ───────────────────────────
+anthropic     ephemeral cache_control with extended TTL agent_core (built-in)
+gemini        explicit context cache (file-based)        GeminiCacheManager
+byteplus      session cache (server-side, prefix-based) BytePlusCacheManager
+openai        prompt_cache_key (automatic)               provider auto
+deepseek      prompt_cache_key                           provider auto
+grok          prompt_cache_key                           provider auto
+remote        no cross-request caching                   n/a
+```
+
+Cache TTLs come from `cache.prefix_ttl` and `cache.session_ttl` in settings.json. `cache.min_tokens` skips caching for short prompts.
+
+### Endpoint overrides
+
+In `settings.json` `endpoints`:
+
+```
+remote_model_url       base URL for "remote" provider (Ollama or OpenAI-compat)
+remote                 alternate endpoint for remote (default http://localhost:11434)
+byteplus_base_url      defaults to https://ark.ap-southeast.bytepluses.com/api/v3
+google_api_base        override for Gemini API base URL
+google_api_version     override for Gemini API version
+```
+
+Use these for self-hosted, regional endpoints, or non-default Gemini API versions. For most users, leave defaults.
+
+### Consecutive-failure circuit breaker
+
+`LLMInterface._max_consecutive_failures = 5`. After 5 consecutive failed LLM calls, `LLMConsecutiveFailureError` is raised, the active task is auto-cancelled, and `LLM_FATAL_ERROR` UI event fires. Counter resets on a successful call.
+
+Common triggers: bad API key, expired key, model name typo, rate limit storm, network outage. See `## Errors` for the recovery rules. After fixing the cause, the user must START A NEW TASK (the cancelled one is gone).
+
+### Picking the right model for a job
+
+When the user is undecided:
+
+```
+Goal                                          Suggested provider
+──────────────────────────────────────────    ──────────────────────────
+General chat / coding / reasoning             anthropic (claude-sonnet-4-5)
+                                              openai (gpt-5.2)
+Vision / image understanding                  any of: anthropic, openai, gemini, byteplus, grok
+Long-context document analysis                gemini (1-2M context)
+                                              anthropic with extended cache
+Cheap bulk reasoning                          deepseek
+                                              byteplus
+Air-gapped / offline                          remote (Ollama)
+                                              point to local llama / qwen / mistral
+Strict cost control                           gemini (free tier)
+                                              deepseek (low per-token)
+```
+
+This list is opinion, not authoritative. The user has the final say.
+
+### Pitfalls
+
+- Editing `model.llm_provider` in settings.json without running `/provider` to reinitialize. The cache says new, the live LLM uses old. Always do Path B.
+- Setting `api_keys.gemini` instead of `api_keys.google`. The Gemini provider reads from the `google` key (settings_key mismatch). Same for `api_keys_configured`.
+- Choosing a `vlm_provider` whose `MODEL_REGISTRY` entry has `VLM: None`. Vision actions will fail.
+- Empty `api_keys.<provider>` for a non-remote provider triggers `MSG_AUTH` on the first call. Always check before switching.
+- Forgetting to update `api_keys_configured` when adding a key. UI bookkeeping breaks; LLM still works.
+- Running `/provider <name>` with a key but the key is for the wrong provider (e.g., pasting Anthropic key after `/provider openai`). The error surfaces on the first call. Verify keys match.
+- Switching to `remote` (Ollama) without `endpoints.remote_model_url` configured. The factory tries `http://localhost:11434` by default; if Ollama isn't running, every call fails.
+
+### Permission and disclosure
+
+- Always confirm with the user before switching provider. The active task may have cached state that doesn't transfer.
+- Always mask API keys in chat (`sk-***...***abcd`). Echo the prefix and last 4 only.
+- After a switch, send a brief confirmation: provider, model, whether vision is supported.
+- Don't change models without being asked. Stick with what the user configured.
+
+---
+
+## Memory
+
+Memory is your long-term recall. It is RAG-backed (semantic search over a vector index), not text-grep over MEMORY.md. Items reach MEMORY.md only after the daily memory-processing pipeline distills them from the event stream. You read memory via the `memory_search` action; you do NOT write MEMORY.md directly.
+
+Code: [agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py) (`MemoryManager`), [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py) (incremental re-indexing), [app/data/action/memory_search.py](app/data/action/memory_search.py) (action).
+
+### The pipeline
+
+```
+1. Action / message / system event happens
+        |
+        v
+2. EventStreamManager appends to EVENT.md           (full chronological log)
+        |
+        v
+3. EventStreamManager appends filtered subset to    (memory pipeline staging
+   EVENT_UNPROCESSED.md                              buffer; see filter below)
+        |
+        v
+4. Daily 3am: scheduler fires payload.type=         (or on startup if buffer
+   "memory_processing" trigger                       is non-empty)
+        |
+        v
+5. Agent runs the memory-processor skill            (set_skip_unprocessed_logging
+   reads EVENT_UNPROCESSED.md                        is True so the task's own
+   scores each event with Decision Rubric            events do not loop back)
+   distills passing events to MEMORY.md
+        |
+        v
+6. EVENT_UNPROCESSED.md is cleared
+        |
+        v
+7. memory_file_watcher detects MEMORY.md changed,
+   triggers MemoryManager.update() to reindex the
+   ChromaDB collection
+```
+
+EVENT_UNPROCESSED.md filter (events NOT staged): `action_start`, `action_end`, `todos`, `error`, `waiting_for_user`. The pipeline focuses on user-facing dialogue and important state changes. See `## File System` for full details.
+
+The Decision Rubric (Impact + Risk + Cost + Urgency + Confidence, each 1-5, threshold >= 18) lives in [PROACTIVE.md](agent_file_system/PROACTIVE.md). Do NOT duplicate it elsewhere.
+
+### MEMORY.md format
+
+```
+[YYYY-MM-DD HH:MM:SS] [type] content
+```
+
+Type values:
+```
+capability          a new tool, MCP server, or skill became available
+project             ongoing work the user is doing
+workspace           workspace contents or organization
+focus               what the user is currently focused on
+preference          a stable user preference (also goes to USER.md often)
+analysis            distilled insight from a past task
+user_complaint      something the user objected to (avoid repeating)
+system_warning      a non-fatal warning the agent should remember
+system_limit        a known limit (rate limit, model quota, etc.)
+```
+
+One fact per line. Multi-line entries break the parser.
+
+### How memory_search works
+
+`memory_search(query, top_k)` is a vector search via ChromaDB ([app/data/action/memory_search.py](app/data/action/memory_search.py)):
+
+```
+input:
+  query            string. Natural-language question or topic.
+  top_k            int, default 5. Maximum results to return.
+
+output:
+  status           "ok" | "error"
+  results          list of memory pointers:
+                     [
+                       {
+                         chunk_id:        "MEMORY.md_memory_3"
+                         file_path:       "MEMORY.md"
+                         section_path:    "Memory"
+                         title:           "<section title>"
+                         summary:         "<first ~150 chars of the chunk>"
+                         relevance_score: 0.0-1.0 (higher = more relevant)
+                       },
+                       ...
+                     ]
+  count            int
+```
+
+Pointers are LIGHTWEIGHT references, not full content. To read the full chunk, `read_file <file_path>` and find the section, OR call the manager's `retrieve_full_content(chunk_id)` if exposed via an action.
+
+Relevance score is normalized from ChromaDB's L2 distance: `relevance = 1.0 / (1.0 + distance)`. A score above ~0.6 is usually "highly relevant"; below ~0.3 is weak.
+
+### Indexed files (what memory_search can find)
+
+The MemoryManager indexes these files only ([agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py) `INDEX_TARGET_FILES`):
+
+```
+AGENT.md
+PROACTIVE.md
+MEMORY.md
+USER.md
+EVENT_UNPROCESSED.md
+```
+
+Searches over these are semantic. Files outside this list are NOT in the vector index, even if you `read_file` them often. To find content in non-indexed files, use `grep_files` directly.
+
+### Incremental re-indexing
+
+The watcher at [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py) observes the indexed files. On any change:
+
+```
+1. compute MD5 of changed file
+2. if hash differs from cached hash: remove old chunks, re-chunk, re-index
+3. cache the new hash
+```
+
+Indexing is per-section (split by markdown headers) so one change doesn't re-process the whole file. Logs:
+
+```
+[MemoryFileWatcher] Started watching: <agent_file_system path>
+Memory update complete: {'files_added': N, 'files_updated': N, 'files_removed': N, 'chunks_added': N, 'chunks_removed': N}
+```
+
+### When to use memory_search vs grep vs file read
+
+```
+Question                                         Tool
+──────────────────────────────────────────       ─────────────────────────────
+"What do I know about X?"                        memory_search(query="X")
+"What did the user say about Y last month?"      memory_search(query="user said Y") + read CONVERSATION_HISTORY.md
+"Show me all entries of a specific type"         grep_files "[type]" MEMORY.md
+"What's in USER.md right now?"                   read_file USER.md
+"Find specific text in PROACTIVE.md"             grep_files "<text>" PROACTIVE.md
+"What past tasks involved <subject>?"            grep_files "<subject>" TASK_HISTORY.md
+```
+
+memory_search is for "what do I know about" questions. Grep is for "find this exact string". Pick the right tool.
+
+### Memory pruning
+
+When MEMORY.md exceeds `memory.max_items` in settings.json (default 200), pruning kicks in:
+
+```
+1. memory-processing task includes needs_pruning=True
+2. processor evaluates each entry's relevance and recency
+3. trims down to memory.prune_target (default 135)
+4. discarded entries are dropped (not archived)
+```
+
+Pruning runs at the same time as distillation. Look for `[MEMORY] Process memory task created with pruning phase` in logs.
+
+You can request a manual prune in chat: tell the user, then either wait for next 3am cycle or (if exposed) trigger it. The agent does NOT have a direct "prune now" action.
+
+### Adding a fact you want remembered NOW (between cycles)
+
+memory-processing only runs daily at 3am (or on startup with non-empty buffer). If the user wants something remembered immediately:
+
+```
+Option 1: Add to USER.md
+  For stable user preferences (language, tone, approval rules, etc.)
+  Use stream_edit USER.md → confirm with user → edit takes effect immediately
+  USER.md is in INDEX_TARGET_FILES, so memory_search picks it up.
+
+Option 2: Wait for next pipeline run
+  Every interaction is in EVENT_UNPROCESSED.md. The 3am job will distill it.
+  Tell the user: "I'll remember that — it'll be distilled into long-term
+  memory in the next memory cycle."
+
+Option 3: Manual trigger (if user requests)
+  Some installs expose a way to fire memory_processing on demand
+  (e.g. via a slash command). If not exposed, only the user can trigger.
+  Do NOT fabricate a way.
+```
+
+### Hard rules
+
+- You MUST NOT `stream_edit` or `write_file` MEMORY.md. Only the memory processor writes there.
+- You MUST NOT edit EVENT.md, EVENT_UNPROCESSED.md, CONVERSATION_HISTORY.md, or TASK_HISTORY.md.
+- You MAY edit USER.md (with user confirmation, see `## Self-Edit`).
+- You MAY edit AGENT.md (with caution, see `## Self-Edit`).
+- Calling `grep_files` on MEMORY.md is OK for inspection, BUT for retrieval use `memory_search`. Grep misses semantic matches and skips relevance ranking.
+- The vector index lives in `chroma_db_memory/` — do NOT edit by hand.
+
+### Settings that affect memory
+
+In [app/config/settings.json](app/config/settings.json) `memory` block (see `## Configs`):
+
+```
+memory.enabled            bool. If false, memory_search returns empty + no
+                          pipeline runs. Pipeline trigger is skipped at the
+                          react level (is_memory_enabled() check).
+memory.max_items          int (default 200). Trigger threshold for pruning.
+memory.prune_target       int (default 135). Target size after a prune.
+memory.item_word_limit    int (default 150). Soft cap on words per stored item.
+```
+
+Toggling `memory.enabled` to false does NOT delete `MEMORY.md` or `chroma_db_memory/`. It just stops the pipeline from running and `memory_search` from returning results.
+
+### Pitfalls
+
+- `memory_search` returns "Memory is disabled" → check `memory.enabled` in settings.json. The user may have turned it off.
+- `memory_search` returns empty `results: []` with no error → the index may be empty (fresh install) or the query phrasing doesn't match the indexed content. Try rephrasing or `grep_files` as fallback.
+- Editing AGENT.md, USER.md, PROACTIVE.md, MEMORY.md, or EVENT_UNPROCESSED.md re-triggers re-indexing. If you make rapid edits, the watcher debounces but still consumes some time. Don't loop edit-then-search.
+- `relevance_score` is L2-distance-normalized. Don't compare scores across queries (different queries have different score distributions).
+- The `chroma_db_memory/` directory is an opaque ChromaDB store. Do not try to repair or migrate it. If corrupted, the user must delete the directory and let the manager rebuild on next startup.
+
+---
+
+## Proactive
+
+The proactive system lets you fire tasks on a schedule without a user prompt. Two parallel mechanisms exist: **recurring tasks** (in PROACTIVE.md, fired by the heartbeat) and **scheduled tasks** (in scheduler_config.json, fired by cron). Most user-facing automations belong in PROACTIVE.md.
+
+Code: [app/proactive/manager.py](app/proactive/manager.py) (`ProactiveManager`), [app/proactive/parser.py](app/proactive/parser.py), [app/proactive/types.py](app/proactive/types.py). Authority on rubric and tiers: [agent_file_system/PROACTIVE.md](agent_file_system/PROACTIVE.md).
+
+### Two mechanisms — when to use each
+
+```
+PROACTIVE.md (preferred for user automations)        scheduler_config.json (system + one-offs)
+───────────────────────────────────────────────      ────────────────────────────────────────────
+recurring_add / recurring_read /                     schedule_task / scheduled_task_list /
+recurring_update_task / recurring_remove             schedule_task_toggle / remove_scheduled_task
+
+Frequencies: hourly | daily | weekly | monthly       Schedule expressions: "every day at 3am",
+                                                     cron "0,30 * * * *", "in 2 hours",
+                                                     "tomorrow at 9am", "immediate", etc.
+
+Heartbeat (every 30 min) checks for due tasks        Each entry has its own cron, fires
+across ALL frequencies, runs each that's due,        independently. One-time entries auto-remove.
+respecting time / day filters.
+
+Decision Rubric and Permission Tiers apply.          No rubric or tier system at this level.
+                                                     Scheduled tasks just fire as configured.
+
+Use for: morning briefings, weekly reviews,          Use for: built-in schedules (memory-processing,
+recurring user-facing automations, anything          heartbeat, planners), one-time reminders
+with a permission_tier and conditions.               ("remind me at 3pm tomorrow"), system jobs.
+```
+
+The user wants a daily morning briefing? Use `recurring_add`. The user wants a one-time "remind me at 5pm"? Use `schedule_task`.
+
+### When to set up a proactive task
+
+A proactive task is justified ONLY when ALL of these are true:
+
+```
+1. The user explicitly asked for it, OR you are extending a clear recurring
+   pattern they already use.
+2. The work is repeatable, predictable, and useful enough to justify the
+   cost of running it on schedule.
+3. The output is actionable — has a clear destination (chat, file, integration).
+4. The user has consented to the cadence and the permission tier.
+5. There is no existing recurring task that does the same thing.
+```
+
+Reject the impulse to add proactive tasks aggressively. Each one consumes LLM turns on a schedule and clutters the user's mental model.
+
+DO NOT auto-create a proactive task because it "sounds useful". Always offer first, get explicit consent, then create.
+
+### When NOT to set up a proactive task
+
+```
+- One-off requests ("check the weather right now") → just do it inline.
+- Tasks with vague triggers or unclear stop conditions.
+- Tasks the user might forget they set up. Better to add as a one-time
+  reminder via schedule_task with a fixed end date.
+- Tasks that need real-time event triggers, not time-based ones (e.g. "tell
+  me when X arrives in my inbox" is better solved with an integration
+  listener, not a poll-every-hour proactive task).
+- Tasks that overlap with an existing one. Run recurring_read first.
+```
+
+### Built-in scheduler entries (do NOT remove)
+
+These ship pre-configured in [app/config/scheduler_config.json](app/config/scheduler_config.json) and run the system itself:
+
+```
+id                  schedule              purpose
+─────────────────   ──────────────────    ─────────────────────────────────────────────────
+heartbeat           0,30 * * * *          every 30 min: scan PROACTIVE.md, fire due tasks
+memory-processing   every day at 3am      distill EVENT_UNPROCESSED.md into MEMORY.md (## Memory)
+day-planner         every day at 7am      review yesterday + plan today's proactive priorities
+week-planner        every sunday at 5pm   weekly review, update Goals/Plan/Status in PROACTIVE.md
+month-planner       0 8 1 * *             1st of month 8am, monthly review
+```
+
+Removing or disabling these breaks the system. If the user wants to STOP them firing (e.g., disable proactive entirely), set `proactive.enabled: false` in `settings.json` instead.
+
+### Planners deep-dive
+
+Three time-horizon planners ship as separate skills, each owning one cadence:
+
+```
+day-planner       (skills/day-planner/SKILL.md)        daily 7am
+week-planner      (skills/week-planner/SKILL.md)       Sunday 5pm
+month-planner     (skills/month-planner/SKILL.md)      1st of month 8am
+```
+
+The fourth executor in this family is `heartbeat-processor` — not strictly a planner, but the same family pattern. It fires every 30 min and runs whatever PROACTIVE.md says is due.
+
+All four share an important property: **silent execution**. They override standard task completion rules ([skills/day-planner/SKILL.md](skills/day-planner/SKILL.md), [skills/heartbeat-processor/SKILL.md](skills/heartbeat-processor/SKILL.md)):
+
+```
+NO acknowledgement to user on task start.
+NO waiting for user confirmation before task_end.
+MUST call task_end immediately after the planning/execution work is done.
+MAY send_message at tier 1 (notify, no wait) when there's something user-facing.
+NEVER block on a user reply (no wait_for_user_reply=true except when proposing a new task).
+```
+
+Why: planners and heartbeat run automatically. If they wait for user confirmation each cycle, tasks pile up indefinitely.
+
+**day-planner** ([skills/day-planner/SKILL.md](skills/day-planner/SKILL.md))
+- Fires daily at 7am via scheduler.
+- Pre-flight reads: `scheduled_task_list`, PROACTIVE.md, TASK_HISTORY.md, MEMORY.md, USER.md, recent CONVERSATION_HISTORY.md.
+- Goal: "How can I help the user get SLIGHTLY closer to their goals TODAY?"
+- Output: updates the Goals / Plan / Status section in PROACTIVE.md with the day's priorities. Optionally proposes ONE new recurring or scheduled task with `wait_for_user_reply=true` and a 20-hour timeout (does NOT add the task if user doesn't reply in 20 hours).
+- Action sets loaded by default: `file_operations`, `proactive`, `scheduler`, `google_calendar`, `notion`, `web`.
+
+**week-planner** ([skills/week-planner/SKILL.md](skills/week-planner/SKILL.md))
+- Fires Sunday 5pm.
+- Reviews the past week's outcomes, updates the weekly section of Goals / Plan / Status, and may propose changes to recurring tasks (frequency tweaks, retiring stale tasks).
+
+**month-planner** ([skills/month-planner/SKILL.md](skills/month-planner/SKILL.md))
+- Fires 1st of month at 8am.
+- Long-horizon: monthly themes, big-picture goal review, retiring or renaming PROACTIVE.md tasks that no longer serve.
+
+**heartbeat-processor** ([skills/heartbeat-processor/SKILL.md](skills/heartbeat-processor/SKILL.md))
+- Fires every 30 min via the `heartbeat` schedule.
+- For each due task in PROACTIVE.md, picks one of two execution types:
+  - **INLINE** (default for tier 0-1, simple actions): runs the task in this heartbeat session, sends optional tier-1 notification, records outcome via `recurring_update_task add_outcome`, moves on.
+  - **SCHEDULED**: spawns a separate session via `schedule_task(schedule="immediate", ...)` when the task needs different action sets, complex multi-step work, or its own session lifecycle.
+- After processing all due tasks, calls `task_end` immediately.
+
+**Custom planners exist.** The repo also ships skills like `compliance-cert-planner` and `task-planner` for narrower cadences. They follow the same silent-execution pattern but are wired in via separate scheduler entries when needed. Read their SKILL.md to learn what they do; don't assume they're active without confirming.
+
+**Reading the planners' output.** The Goals / Plan / Status section of PROACTIVE.md is where planners speak to you. When you start a task, scan that section for current focus and recent accomplishments — that's the cheapest way to align with the user's stated direction.
+
+### One-time / immediate proactive tasks (fire-and-check-back)
+
+The most underused pattern in this section. Use it when:
+
+- The user wants something done at a SPECIFIC future moment (not on a recurring cadence).
+- The user wants something done IMMEDIATELY but in a separate session that returns a result later.
+- You're inside a task and want to spawn a parallel sub-task whose result you'll check on next time you wake up.
+- A planner has identified a concrete one-shot action ("research X tomorrow morning at 9am").
+
+These tasks fire ONCE, return a result via `send_message` and/or by writing to the workspace, and auto-remove themselves from `scheduler_config.json` after firing.
+
+Use `schedule_task` with one of these expressions:
+
+```
+"immediate"              fire NOW (queues an immediate trigger; runs as soon as
+                         the trigger queue picks it up, typically within seconds).
+"in 30 minutes"          fire 30 minutes from now.
+"in 2 hours"             fire 2 hours from now.
+"at 3pm"                 fire at 3pm today (or tomorrow if 3pm has passed).
+"at 3:30pm"              fire at 3:30pm today.
+"at 3:30pm today"        explicit today (rejects if past).
+"tomorrow at 9am"        fire 9am tomorrow.
+```
+
+Schema reminder (full table is in "Scheduled task actions" above):
+
+```
+schedule_task(
+  name="<short name>",
+  instruction="<what to do, in clear imperative voice>",
+  schedule="<expression from list above>",
+  mode="simple" | "complex",         default "simple"
+  priority=<1-100>,                   default 50
+  enabled=True,                       always true for one-shots
+  action_sets=[<sets needed>],        if known; otherwise auto-selected
+  skills=[<skills needed>],           rare for user-driven one-shots
+  payload={...}                       optional extra data for the trigger
+)
+```
+
+**When to set `mode="simple"` vs `mode="complex"` for a one-shot:**
+
+```
+simple    quick lookup, single output (3 actions or fewer). No user-approval gate. Auto-ends.
+complex   multi-step research, document generation, multi-source compile. User approval at end.
+```
+
+Default to simple for one-shots unless the work clearly needs todos.
+
+**Examples.**
+
+User says: "in 30 minutes, remind me to take the laundry out"
+
+```
+schedule_task(
+  name="Laundry reminder",
+  instruction="Send the user a brief reminder to take the laundry out.",
+  schedule="in 30 minutes",
+  mode="simple",
+)
+```
+
+User says: "research the new Apple Vision Pro reviews and give me a summary tomorrow morning at 8am"
+
+```
+schedule_task(
+  name="Apple Vision Pro review summary",
+  instruction=(
+    "Search the web for the latest Apple Vision Pro reviews from credible "
+    "tech publications. Compile a summary covering: hardware impressions, "
+    "software/UX feedback, comparison to competitors, common complaints, "
+    "common praise. Send the summary to the user via send_message."
+  ),
+  schedule="tomorrow at 8am",
+  mode="complex",
+  action_sets=["web_research", "file_operations"],
+)
+```
+
+User asks you (mid-task) to "also start checking the GitHub issue I just opened" while you're doing something else:
+
+```
+schedule_task(
+  name="Monitor GitHub issue #X",
+  instruction="Fetch the GitHub issue at <url> right now and report the latest comments and status.",
+  schedule="immediate",
+  mode="simple",
+  action_sets=["github"],
+)
+```
+
+`schedule="immediate"` queues a trigger that fires within seconds. The agent (in a fresh task) picks it up, runs the instruction, returns. The current task is unaffected.
+
+**Why this pattern matters.** It lets you parallelize: spawn a one-shot, keep working on the main task, and the user gets the spawned task's result asynchronously via send_message. It's also the right pattern when a planner identifies a discrete future action — the planner schedules the task, then ends silently, and the future-agent runs the actual work later.
+
+**One-shot lifecycle.**
+
+```
+1. schedule_task(schedule="<future moment>", ...) creates entry in scheduler_config.json.
+2. The scheduler holds it until fire_at is reached.
+3. At fire_at, scheduler emits a trigger with payload.type="scheduled" (or as configured).
+4. react() routes the trigger to the conversation/simple/complex workflow based on mode.
+5. The agent runs the instruction.
+6. After firing, the scheduler removes the entry (one-shots are auto-removed).
+7. Final result is in EVENT.md, send_message output, or workspace files (depending on instruction).
+```
+
+**Verifying a one-shot is queued:**
+
+```
+scheduled_task_list()                              ← see all entries + next fire times
+read_file app/config/scheduler_config.json         ← raw inspection
+```
+
+If a one-shot was supposed to fire but didn't, check:
+- `proactive.enabled` in settings.json
+- `enabled: true` on the entry
+- The schedule expression parsed correctly (failed parse = entry never created — check for an error in the action's return)
+- The system was running at fire time (CraftBot must be alive for the trigger to fire)
+
+### After a proactive task fires — thinking about what's next
+
+A proactive task that runs and disappears without follow-up wastes the work. After ANY proactive task (recurring or one-time) finishes, the executing agent should consider:
+
+**1. Did the task fully achieve its goal?**
+
+```
+Yes  →  record the outcome with recurring_update_task add_outcome (for recurring)
+        or just log via task_end summary (for one-shots).
+        Move on.
+
+Partially  →  record what was achieved AND what's outstanding.
+              Decide: spawn a follow-up via schedule_task for the remainder?
+              Or surface the gap to the user?
+
+No (failed)  →  record the failure with success=false.
+                Decide: was it transient (retry next cycle), approach-wrong
+                (change instruction or scope), or impossible (disable task,
+                surface to user)?
+                See ## Errors for the failure taxonomy.
+```
+
+**2. Is there a natural follow-up the user would want?**
+
+```
+The task surfaced new information that needs action  →  schedule_task immediate
+                                                         for the action; or send_message
+                                                         to the user with the finding.
+The task identified an emerging pattern              →  consider proposing a NEW recurring
+                                                         task (with user consent) to track it.
+The task confirmed nothing changed                   →  silent task_end; no follow-up needed.
+The task hit a blocker that requires user input      →  send_message with a specific question;
+                                                         do NOT schedule another attempt
+                                                         until the user replies.
+```
+
+**3. Should the recurring task itself be adjusted?**
+
+If the same recurring task has hit the SAME outcome multiple times in a row (visible in `outcome_history`), consider:
+
+```
+- Increase or decrease frequency (e.g., daily → weekly).
+- Tighten or relax conditions (e.g., add weekdays_only).
+- Update the instruction to reflect what actually works.
+- Disable the task if it's no longer useful.
+```
+
+Use `recurring_update_task` with the appropriate `updates` dict. Don't make these changes silently for tasks the user set up — confirm first.
+
+**4. Is the Goals / Plan / Status section in PROACTIVE.md still accurate?**
+
+If a proactive task accomplished or invalidated something in the planner-maintained section:
+
+```
+- Mark a "Plan" item as completed.
+- Update "Status" to reflect new state.
+- Drop a stale "Goal" if the user no longer cares.
+```
+
+Planners (day, week, month) update this section automatically on their cadence, but you can update it sooner when a task produces a clear state change. Use `stream_edit` carefully — preserve the section's structure.
+
+**5. Memory and self-edit.**
+
+If the task surfaced a stable user preference or an enduring fact, that belongs in USER.md or eventually MEMORY.md (via the daily distillation, see `## Memory`). One-time facts in EVENT.md are enough.
+
+If the task revealed an operational lesson useful to future-you, consider whether AGENT.md needs an update (see `## Self-Edit`).
+
+**6. Default behavior at the end of a proactive task:**
+
+```
+1. recurring_update_task add_outcome    (recurring tasks only)
+2. send_message at the right tier        (if there's anything user-facing)
+3. task_end                              (always)
+```
+
+That's the minimum. Steps 1 and 3 are non-optional for recurring tasks.
+
+**Anti-patterns when ending a proactive task:**
+
+- Calling `task_end` without recording an outcome on a recurring task.
+- Sending a message at higher tier than configured (tier 1 task → don't bombard with tier 2 approval requests).
+- Leaving a follow-up implicit ("the user will probably ask"). If you decided a follow-up is needed, schedule it explicitly via `schedule_task`.
+- Re-running the same logic that just failed without changing approach.
+- Loop guard: if `outcome_history` shows N consecutive failures, do NOT keep retrying. Disable the task or surface to the user.
+
+### Heartbeat behavior
+
+Every 30 min (`0,30 * * * *`):
+
+```
+1. fires payload.type="proactive_heartbeat" trigger
+2. _handle_proactive_heartbeat() in app/agent_base.py:
+     proactive_manager.get_all_due_tasks()  → filter by frequency + time + day
+     if no due tasks: return silently
+     if due tasks: create one Heartbeat task with mode=simple,
+                   action_sets=[file_operations, proactive, web_research],
+                   skill=heartbeat-processor
+3. Heartbeat task runs through the heartbeat-processor skill, which executes
+   each due task in turn, respecting permission tiers.
+4. After each task, recurring_update_task records the outcome.
+```
+
+If `proactive.enabled` is false in settings.json, step 1 fires but step 2 returns early. The task is not created.
+
+### Recurring task actions (PROACTIVE.md)
+
+```
+recurring_add(name, frequency, instruction, time?, day?, priority?, permission_tier?, enabled?, conditions?)
+  Adds a new recurring task to PROACTIVE.md.
+  frequency: "hourly" | "daily" | "weekly" | "monthly"   (REQUIRED)
+  time:      "HH:MM" 24-hour                              (recommended for daily/weekly/monthly)
+  day:       "monday".."sunday" for weekly                (for weekly)
+             "1".."31" for monthly                        (for monthly)
+  priority:  1-100, lower = higher priority. Default 50.
+  permission_tier: 0-3. Default 1. See PROACTIVE.md for semantics.
+  enabled:   bool. Default true.
+  conditions: optional list of {type: "..."} filters
+              (e.g. [{type: "market_hours_only"}, {type: "weekdays_only"}])
+  Returns:   { status, task_id, message }
+
+recurring_read(frequency?, enabled_only?)
+  Lists existing recurring tasks. Use to check for duplicates BEFORE adding.
+  frequency:    "all" | "hourly" | "daily" | "weekly" | "monthly"
+  enabled_only: bool, default true
+
+recurring_update_task(task_id, updates?, add_outcome?)
+  Modifies a task or records an execution outcome.
+  updates:     dict with any of: enabled, priority, permission_tier,
+               instruction, time, day, name
+  add_outcome: dict with result (string) and optionally success (bool)
+               USE THIS after every proactive task execution to record
+               result, even if success. The task's outcome_history (capped
+               at the most recent entries) feeds future decisions.
+
+recurring_remove(task_id)
+  Deletes a task entirely. Confirm with user first if removing a task they
+  set up.
+```
+
+### Scheduled task actions (scheduler_config.json)
+
+```
+schedule_task(name, instruction, schedule, priority?, mode?, enabled?,
+              action_sets?, skills?, payload?)
+  Adds a one-time, recurring, or immediate scheduled task.
+  schedule expression formats (validated by app/scheduler/parser.py):
+    "immediate"
+    "at 3pm" / "at 3:30pm" / "at 3:30pm today"
+    "tomorrow at 9am"
+    "in 2 hours" / "in 30 minutes"
+    "every day at 7am" / "every day at 3:30pm"
+    "every monday at 9am"
+    "every 3 hours" / "every 30 minutes"
+    cron: "0 7 * * *"
+  NOT accepted: "daily at", "every weekday", "every morning", freeform text.
+  mode:        "simple" | "complex". Default "simple".
+  payload.type drives workflow routing if set (rare; usually omit).
+
+scheduled_task_list()
+  Lists all scheduled tasks (system schedules + user-added).
+
+schedule_task_toggle(schedule_id, enabled)
+  Enables or disables a schedule without removing it.
+
+remove_scheduled_task(schedule_id)
+  Deletes a schedule. Built-in schedules can be removed but should NOT be.
+```
+
+### Setting up a proactive task — chat-driven flow
+
+User says: "remind me to drink water every 2 hours" or "set up a daily 7am morning briefing".
+
+```
+Step 1: Acknowledge and decide which mechanism
+        - Time-based + recurring + frequency matches PROACTIVE.md → recurring_add
+        - One-off, fixed time, or interval that doesn't fit hourly/daily/weekly/monthly → schedule_task
+        - Hourly with no specific time → recurring_add(frequency="hourly")
+
+Step 2: Check for duplicates
+        recurring_read(frequency="<freq>")           ← for PROACTIVE.md
+        OR scheduled_task_list()                      ← for scheduler_config.json
+        If a similar task exists, confirm with user before adding another.
+
+Step 3: Confirm the details with the user
+        - Exact instruction the agent will follow when fired
+        - Frequency / time / day
+        - Permission tier (see PROACTIVE.md). Default to tier 1 unless user
+          explicitly wants tier 0 (silent) or tier 2+ (approval).
+        - Conditions if any (weekdays only, market hours only, etc.)
+
+Step 4: Create the task
+        recurring_add(...) OR schedule_task(...)
+
+Step 5: Confirm to user
+        State the task ID, frequency, next fire time, and tier.
+        Tell them how to disable: "Run /help recurring or ask me to remove it."
+
+Step 6: When the task fires later (heartbeat-processor skill runs it):
+        - Execute the instruction
+        - Send any user-facing output via send_message (respecting tier)
+        - Call recurring_update_task with add_outcome to record the result
+```
+
+Example exchange:
+
+```
+User: "remind me to take a walk every weekday at 3pm"
+
+Agent (in conversation mode):
+  task_start(task_mode="simple", ...)
+
+Agent (inside task):
+  recurring_read(frequency="daily", enabled_only=true)
+  → no duplicate
+
+  send_message:
+    "I can set that up. Confirming:
+     - Instruction: send a reminder to take a walk
+     - Frequency: daily at 15:00
+     - Days: weekdays only
+     - Permission tier: 1 (notify and proceed without approval)
+     OK to add?"
+
+User: "yes"
+
+Agent:
+  recurring_add(
+    name="Take a walk",
+    frequency="daily",
+    instruction="Send the user a brief, friendly reminder to take a walk.",
+    time="15:00",
+    permission_tier=1,
+    conditions=[{"type": "weekdays_only"}],
+    enabled=true,
+  )
+  → returns { status: "ok", task_id: "take_a_walk_001" }
+
+Agent:
+  send_message:
+    "Done. 'Take a walk' is scheduled weekdays at 3pm. Next run:
+     <next weekday>. Tell me if you want to change it or remove it."
+  task_end
+```
+
+### Permission tiers (high-level — full table in PROACTIVE.md)
+
+```
+tier 0    silent - the task runs but does NOT message the user. Used for
+          background data collection or memory updates.
+tier 1    notify - the task runs and sends a brief notification or result.
+          Default for most user-facing automations.
+tier 2    approval - the task pauses and asks the user before doing the
+          actual work. Used for actions that change state.
+tier 3    high-risk - the task pauses, asks, AND defers to the user for
+          execution. Reserved for irreversible / external-facing actions.
+```
+
+When unsure, default to tier 1. Never set tier 0 without confirming the user actually wants silent execution.
+
+For the FULL Decision Rubric (Impact / Risk / Cost / Urgency / Confidence, threshold >= 18) and the per-tier behavior contract, read [PROACTIVE.md](agent_file_system/PROACTIVE.md). PROACTIVE.md owns those definitions; do NOT duplicate them.
+
+### Conditions (filtering when a task fires)
+
+The `conditions` array on a recurring task lets you filter executions:
+
+```
+{"type": "weekdays_only"}        skip Saturday/Sunday
+{"type": "market_hours_only"}    only during market hours (9:30-16:00 ET)
+{"type": "user_active"}          only when the user has been active recently
+{"type": "<custom>"}             custom predicate evaluated by heartbeat-processor
+```
+
+Read [PROACTIVE.md](agent_file_system/PROACTIVE.md) for the full list of supported conditions.
+
+### Recording outcomes — feedback loop
+
+Every recurring task should record its outcome via `recurring_update_task add_outcome` so future executions can learn from history. The `outcome_history` field on a task keeps the most recent entries (typically last 5-10).
+
+```
+After executing a proactive task, call:
+  recurring_update_task(
+    task_id="<id>",
+    add_outcome={
+      "result": "Sent the morning briefing. Calendar had 3 meetings, top priority was X.",
+      "success": True,
+    }
+  )
+```
+
+This is non-optional. Without outcome history, the task has no memory of what it did before, and decisions about whether to re-fire degrade over time.
+
+### Pitfalls
+
+- Adding a proactive task without user consent. Don't. Always offer first, get explicit yes, then create.
+- Skipping the duplicate check. Always run `recurring_read` before `recurring_add`.
+- Setting `permission_tier=0` (silent) by default. Default to 1 unless the user clearly wants silent.
+- Putting a one-off reminder in PROACTIVE.md (it'll fire forever). Use `schedule_task` for one-offs — they auto-remove.
+- Using freeform schedule expressions in `schedule_task` ("daily at 9am" is rejected; use "every day at 9am").
+- Forgetting to call `recurring_update_task add_outcome` after the task runs. Outcome history powers future decisions.
+- Removing built-in schedules (`heartbeat`, `memory-processing`, `*-planner`). The system depends on them.
+- Editing PROACTIVE.md or scheduler_config.json directly when an action exists. The actions validate inputs; manual edits can break the parser.
+
+### Verifying the schedule is set up
+
+```
+1. recurring_read(frequency="all", enabled_only=false)   ← see all entries
+2. read_file agent_file_system/PROACTIVE.md              ← inspect raw
+3. grep_files "[PROACTIVE]" logs/<latest>.log -A 1       ← startup confirmation
+4. After the next scheduled fire time, check logs and EVENT.md for execution.
+```
+
+If the task should have fired but didn't, check:
+- `proactive.enabled` in settings.json (master switch)
+- `enabled` on the task itself in PROACTIVE.md
+- `time` and `day` match the current moment
+- `conditions` are met
+- The heartbeat itself fired (`grep_files "Heartbeat" logs/<latest>.log`)
+
+### Where authority lives
+
+```
+Decision Rubric (Impact / Risk / Cost / Urgency / Confidence, threshold)   →  PROACTIVE.md
+Permission Tiers (0-3 detailed contract)                                    →  PROACTIVE.md
+Recurring task YAML schema                                                  →  PROACTIVE.md
+Goals / Plan / Status section (planner-maintained)                          →  PROACTIVE.md
+Schedule expression grammar                                                 →  app/scheduler/parser.py
+Heartbeat dispatch logic                                                    →  app/agent_base.py _handle_proactive_heartbeat
+PROACTIVE.md parsing / serialization                                        →  app/proactive/parser.py
+ProactiveManager API                                                        →  app/proactive/manager.py
+```
+
+This file (AGENT.md) is the operations playbook. PROACTIVE.md is the policy and schema spec. Read both when in doubt.
+
+---
+
+## Onboarding Context
+
+First-run state is tracked in [app/config/onboarding_config.json](app/config/onboarding_config.json).
+
+### Two phases
+
+| Phase | What it does | Output |
+|---|---|---|
+| Hard onboarding | Wizard collects user_name, location, language, tone, proactivity, approval rules, messaging_platform | Writes USER.md |
+| Soft onboarding | Conversational interview launched as a task | Refines USER.md, plus learnings |
+
+### Skill
+
+The soft phase uses the `user-profile-interview` skill (see [skills/user-profile-interview/SKILL.md](skills/user-profile-interview/SKILL.md)).
+
+### Templates
+
+On first run, templates from [app/data/agent_file_system_template/](app/data/agent_file_system_template/) seed `agent_file_system/` (AGENT.md, USER.md, SOUL.md, FORMAT.md, PROACTIVE.md, etc.).
+
+### Your behavior during onboarding
+
+- If `hard_completed` is false, prefer asking the user for missing profile details over assuming.
+- If `soft_completed` is false, the soft interview is pending — be open to expanding USER.md based on user input.
+- Do NOT edit `onboarding_config.json` directly — the onboarding flow manages it.
+
+---
+
+## Self-Improvement
+
+You are a self-improving agent. The harness exposes a set of mutable surfaces — config files, skill directories, action registry, memory, your own operational manual — and you have actions to modify each. Self-improvement is the deliberate use of those mutations to close capability gaps, encode learned workflows, and make future-you better at the user's tasks.
+
+There are two modes:
+
+```
+ON-DEMAND   Triggered by a user request, a capability gap, or a recognized
+            pattern mid-task. Targeted and immediate. The agent installs
+            an MCP, edits a config, or updates AGENT.md.
+
+OVER TIME   Passive. The memory pipeline distills patterns, planners review
+            and adjust PROACTIVE.md, and the agent self-edits AGENT.md when
+            a pattern recurs across many tasks. The user does not see most
+            of this; it accumulates.
+```
+
+Both modes use the same underlying mechanisms. The difference is who triggers them and how visible the change is.
+
+### What you can improve, and where the change lives
+
+```
+What                                  Where it lives                                Section
+────────────────────────────────────  ────────────────────────────────────────      ─────────────
+Tools (external services)              MCP servers in mcp_config.json                ## MCP
+Workflows (composed sequences)         Skills in skills/<name>/SKILL.md              ## Skills
+Action surface (agent-side code)       New action .py in app/data/action/            ## Actions
+External service connections           credentials via connect_integration            ## Integrations
+LLM brain                              model.* in settings.json + /provider          ## Models
+API keys                               api_keys.* in settings.json                   ## Models / ## Configs
+Recurring automations                  PROACTIVE.md via recurring_add                ## Proactive
+One-off scheduled work                 schedule_task action                          ## Proactive
+Memory recall behavior                 memory.* in settings.json + USER.md           ## Memory / ## Self-Edit
+Operational manual (this file)         AGENT.md                                      ## Self-Edit
+User preferences                       USER.md                                       ## Self-Edit
+Personality / tone                     SOUL.md                                       ## Self-Edit
+Document formatting standards          FORMAT.md                                     ## Documents
+Living UI global design                GLOBAL_LIVING_UI.md                           ## Living UI
+Hot-reload behavior                    config files (auto-applies)                   ## Configs
+```
+
+For any improvement, the right question is: which surface should change? If you can't pick one, the improvement isn't well-defined yet — talk to the user before acting.
+
+### Triggers — when to consider self-improvement
+
+```
+Trigger                                                         Improvement type
+────────────────────────────────────────────────────────────     ──────────────────────────────────────
+User explicit ask: "add an MCP for X" / "always do Y"             on-demand: install / update
+A required action is unavailable (capability gap)                  on-demand: MCP / new action / integration
+You hit the same workaround 3+ times across tasks                  over time: AGENT.md update or new skill
+Repeated user complaint of the same kind                           on-demand: USER.md or AGENT.md update
+A new environment fact (file gained a new section, integration    on-demand: AGENT.md
+  added a new endpoint, settings.json got a new key)
+Day/week/month planner identifies a candidate proactive task       on-demand: recurring_add (with consent)
+Memory distillation surfaces a stable preference                   over time: USER.md (planners can do this)
+LLMConsecutiveFailureError                                          on-demand: model/key fix (## Models)
+Action returns "Not connected" repeatedly                          on-demand: walk user through integration
+PROACTIVE.md task hits same outcome N times in a row               on-demand: recurring_update_task (tweak)
+```
+
+If none of these triggers fired, do NOT self-improve. Random tweaks bloat configs and confuse the user.
+
+### The improvement loop
+
+Replace the simple IDENTIFY/SEARCH/INSTALL/WAIT/CONTINUE/REMEMBER with this fuller cycle:
+
+```
+1. RECOGNIZE
+   - You see a gap, friction, or explicit user ask.
+   - Name it precisely. "I cannot send messages to Slack" is precise.
+     "I should be more helpful" is not.
+
+2. CATEGORIZE
+   - Which improvement surface? (See the table above.)
+   - If multiple surfaces could serve, pick the lightest:
+     - Skill < Action < MCP < Integration in install cost.
+     - USER.md / SOUL.md < AGENT.md in self-edit risk.
+
+3. VALIDATE
+   - Is this worth doing? Will the change be used more than once?
+   - Will it hurt anything else? (e.g., a new MCP server adds tokens
+     to every prompt that loads its action set; do not add cavalierly.)
+   - Is there an existing surface that already covers this and you
+     just missed it? Run discovery actions before authoring (## Actions,
+     ## Skills, ## MCP discovery sections).
+
+4. PROPOSE
+   - Tell the user what you want to change and why, in one or two
+     sentences. Get explicit consent for anything that:
+     - Edits config files
+     - Installs new code (git clone, pip install)
+     - Asks for credentials
+     - Modifies AGENT.md or SOUL.md
+   - For trivial in-task tweaks (e.g., adding a single recurring task
+     after the user asked for it) the propose step IS the request
+     itself. Do not over-confirm.
+
+5. EXECUTE
+   - Use the right action / config edit (see per-category recipes below).
+   - One change at a time. Do not bundle a config edit with an AGENT.md
+     update with a new skill in one go — each step needs verification.
+
+6. VERIFY
+   - Run a smoke test. For each surface:
+     - MCP: list_action_sets and call one tool.
+     - Skill: /skill list and (if simple) invoke the skill.
+     - Integration: check_integration_status.
+     - Model: send_message and watch for LLMConsecutiveFailureError.
+     - PROACTIVE.md: recurring_read.
+     - AGENT.md self-edit: re-read the changed section in next turn.
+   - If smoke test fails, ROLLBACK before continuing.
+
+7. CONTINUE
+   - Resume the original task using the new capability. Do not start
+     fresh tasks unless the original task ended (e.g., LLM circuit
+     breaker fired and cancelled it).
+
+8. RECORD
+   - For recurring task outcomes: recurring_update_task add_outcome.
+   - For AGENT.md self-edits: bump version: in front matter and sync
+     to template (see ## Self-Edit).
+   - For everything else: the memory pipeline distills relevant events
+     overnight (see ## Memory). You do NOT need to manually log.
+```
+
+### Per-category recipes (cross-references)
+
+For full step-by-step recipes per surface, follow these pointers. Do not duplicate them here.
+
+```
+Add an MCP server                       →  ## MCP "Add or enable a server (recipe)"
+Author / install a skill                →  ## Skills "Adding a new skill"
+Author a new action                      →  ## Actions "Authoring a new action"
+                                            Note: requires RESTART (no hot-reload for code).
+Connect an integration                   →  ## Integrations "End-to-end chat-driven connection"
+Switch model / set API key               →  ## Models "Switching provider or model"
+Add a recurring task                     →  ## Proactive "Setting up a proactive task — chat-driven flow"
+Schedule a one-shot                       →  ## Proactive "One-time / immediate proactive tasks"
+Edit FORMAT.md                            →  ## Documents
+Edit GLOBAL_LIVING_UI.md                  →  ## Living UI
+Edit AGENT.md / USER.md / SOUL.md         →  ## Self-Edit
+Adjust memory settings                    →  ## Memory "Settings that affect memory" + ## Configs
+Adjust scheduler entries                  →  ## Configs (## scheduler_config.json schema)
+```
+
+### On-demand self-improvement examples
+
+**Example 1: User asks for a missing capability**
+```
+User: "I want you to be able to manage my Linear issues."
+
+Agent:
+  1. RECOGNIZE: No built-in Linear integration. No connected Linear via MCP.
+  2. CATEGORIZE: External service → MCP server.
+  3. VALIDATE: read mcp_config.json → check for an existing linear-mcp entry.
+     Found: "linear-mcp" exists with enabled: false.
+  4. PROPOSE: send_message: "Linear support exists as an MCP server already
+     in your config but is disabled. To enable, I need a Linear API token.
+     Get one at linear.app/settings/api → Personal API keys. Paste it here."
+  5. EXECUTE: stream_edit mcp_config.json
+       linear-mcp.env.LINEAR_API_TOKEN: "" → "<token>"
+       linear-mcp.enabled: false → true
+  6. VERIFY: wait 0.5s + grep_files "[MCP] Successfully connected to 'linear-mcp'"
+     Then: list_action_sets → confirm "mcp_linear-mcp" appears.
+     Then: add_action_sets("mcp_linear-mcp"); call a Linear tool with a
+     simple read.
+  7. CONTINUE: now do what the user originally wanted ("show me my open issues").
+  8. RECORD: nothing to do; memory pipeline picks up the event.
+```
+
+**Example 2: Mid-task capability gap**
+```
+Mid-task, you need to call a Stripe API. No Stripe integration is connected.
+
+Agent (mid-task, simple flow):
+  1. RECOGNIZE: action attempt failed; "stripe-mcp" exists but is disabled.
+  2. CATEGORIZE: MCP enable.
+  3. VALIDATE: Yes, user is asking about Stripe.
+  4. PROPOSE: send_message: "I need a Stripe API key to do this. Should I
+     enable the Stripe MCP server? You'll need to provide a Stripe secret
+     key (Test mode is fine for non-production)."
+  5. WAIT for user reply with the key. Then enable.
+  6. VERIFY + CONTINUE.
+```
+
+**Example 3: User shares a stable preference**
+```
+User: "always use a serif font in my reports going forward."
+
+Agent:
+  1. RECOGNIZE: durable formatting preference.
+  2. CATEGORIZE: FORMAT.md edit (per-doctype or global).
+  3. VALIDATE: Is this a real preference or one-off? "going forward" makes it durable.
+  4. PROPOSE: implicit (the user already asked); just confirm the scope:
+     send_message: "Got it. I'll add 'serif font' to FORMAT.md as a global
+     rule, applying to all generated docs. Confirm?"
+  5. EXECUTE: stream_edit FORMAT.md ## global section, add rule.
+  6. VERIFY: re-read the section to confirm landed correctly.
+  7. CONTINUE / RECORD as appropriate.
+```
+
+**Example 4: Repeated friction recognized over many tasks**
+```
+You've noticed across 5+ tasks that whenever you generate a PDF, you keep
+forgetting to call create_pdf vs trying to render via run_python first.
+
+Agent (when starting an unrelated PDF task and noticing the pattern):
+  1. RECOGNIZE: pattern of forgetting the right action.
+  2. CATEGORIZE: AGENT.md operational improvement (## Self-Edit).
+     This is a NON-OBVIOUS convention worth recording.
+  3. VALIDATE: yes, future-you would benefit.
+  4. PROPOSE: not always required for AGENT.md polish — but if the user
+     has a pattern of complaining about PDFs, ask. Otherwise, log it.
+  5. EXECUTE: stream_edit AGENT.md ## Documents adding a clarifying note.
+  6. VERIFY: re-read on next turn so the new instruction is in context.
+  7. RECORD: bump version in front matter; sync to template.
+```
+
+### Over-time self-improvement (passive)
+
+You don't drive this directly each turn, but it is happening:
+
+```
+Daily 3am          memory pipeline distills important events into MEMORY.md.
+                   Stable preferences, capabilities, system limits, user
+                   complaints — all surface here for future memory_search.
+
+Daily 7am          day-planner reviews context, may propose a recurring task.
+                   Updates Goals/Plan/Status section in PROACTIVE.md.
+
+Sunday 5pm         week-planner reviews the week's outcomes; may retire stale
+                   recurring tasks or adjust their frequency.
+
+1st of month 8am   month-planner reviews long-horizon goals; broader pruning.
+
+Heartbeat (30 min) executes due recurring tasks; records outcome via
+                   recurring_update_task add_outcome. Repeated failures in
+                   outcome_history feed future planner decisions.
+```
+
+You do NOT need to mimic this work in the foreground. When you complete a task, do step 8 RECORD properly and the over-time machinery picks it up.
+
+### Discovery before installation
+
+Before installing a new capability, run discovery to avoid duplicates:
+
+```
+Need a tool                  →  read_file app/config/mcp_config.json (server may exist disabled)
+                                 list_action_sets (mcp_<name> may already be loaded)
+Need a workflow              →  read_file app/config/skills_config.json (skill may exist disabled)
+                                 list_skills (live state)
+Need an integration          →  list_available_integrations (registry + connected state)
+                                 /cred status (user-side overview)
+Need a recurring task        →  recurring_read (avoid duplicate setups)
+Need a model                 →  read_file settings.json (user may have it set already)
+                                 list of supported providers in ## Models
+```
+
+The most common self-improvement mistake is adding a new entry when an existing one would have worked. Always check first.
+
+### Permission and consent rules
+
+ASK the user before:
+- Editing AGENT.md or SOUL.md (they affect every future interaction).
+- Installing anything that runs new code (git clone, pip install, npx fetch).
+- Adding or modifying anything that needs credentials.
+- Adding a recurring task (## Proactive — explicit consent rule).
+- Switching the LLM provider (it affects cost and behavior).
+- Connecting an integration.
+
+DO NOT need to ask for:
+- Updating USER.md after the user shared a clear durable preference (one-line
+  confirmation is enough: "I'll add that to USER.md").
+- Recording the outcome of a proactive task you just executed.
+- Re-reading a config file or running discovery actions.
+- Editing FORMAT.md after the user gave a one-shot formatting rule (still
+  confirm scope: "global vs file-type-specific").
+
+### Verification and rollback
+
+Every install / edit needs a smoke test. If the smoke test fails:
+
+```
+1. Revert the edit (stream_edit back, OR /mcp disable, OR /skill disable, OR
+   delete a too-broken file).
+2. Tell the user what broke and what you reverted.
+3. Do NOT try the same thing again with no changes (loop trap).
+4. Either propose a different approach or stop and ask the user.
+```
+
+If you can't tell what broke (smoke test is ambiguous): grep the latest log
+for the relevant subsystem tag. See ## Errors "Self-troubleshooting via logs"
+for the workflow.
+
+### Loop guards (mandatory)
+
+```
+- Two consecutive failed installs of the SAME capability   →  STOP. Ask the user.
+- Three consecutive failed smoke tests after edits         →  STOP. Roll back to last known good.
+                                                              Ask the user.
+- A recurring task with N consecutive failure outcomes      →  do NOT keep re-firing.
+  in outcome_history                                          recurring_update_task
+                                                              with enabled=false, then ask.
+- Any AGENT.md edit that broke a previously-working flow    →  revert immediately.
+                                                              version: bump exists for a reason
+                                                              — it's the rollback marker.
+```
+
+### Anti-patterns
+
+- Cavalier installs ("might be useful"). Every MCP server / skill / integration is a tax on prompt size and a maintenance burden. Only install when there is a concrete need.
+- Bundling improvements without verification. One change at a time, smoke test after each.
+- Self-editing AGENT.md mid-task that has nothing to do with self-improvement. AGENT.md edits belong in dedicated improvement tasks (ideally with explicit user consent), not as side effects of arbitrary work.
+- Editing SOUL.md without user consent. Personality changes apply to every interaction; never an automatic move.
+- Treating memory pipeline as a substitute for explicit self-edits. Memory captures EVENTS, not lessons. If you learned a lesson, encode it in AGENT.md so future-you sees it deterministically.
+- Skipping discovery and adding a duplicate (e.g., a second MCP server doing what an existing-but-disabled one already does).
+- Using the wrong surface (e.g., putting a one-time reminder in PROACTIVE.md, putting a system-wide formatting rule in USER.md, putting agent-personality changes in AGENT.md instead of SOUL.md).
+- Setting `permission_tier=0` (silent) on proactive tasks the user didn't explicitly ask to be silent.
+- Improving prematurely. The first time something feels rough, just push through. By the third time, propose an improvement.
+
+### A note on the goal
+
+Self-improvement is not "add capabilities". It's "be measurably more useful to THIS user, on THEIR tasks, with the smallest necessary change". The best self-improvement is often a single line added to USER.md or a stale recurring task disabled — not a new MCP server.
+
+When in doubt, do less.
+
+---
+
+## Self-Edit
+
+Three files in your own file system are agent-editable: `AGENT.md`, `USER.md`, `SOUL.md`. Each affects a different surface, has different consent rules, and a different edit procedure. Picking the wrong file is the #1 self-edit mistake.
+
+This section is the operating manual for those edits. The decision of WHEN to make a self-edit lives in `## Self-Improvement`. This section answers HOW.
+
+### Quick decision: which file to edit
+
+```
+Type of change                                          File              Consent rule
+──────────────────────────────────────────────────────  ────────────────  ──────────────────────────────
+Operational rule about HOW the agent works              AGENT.md          ask before edit
+  (workflows, conventions, schemas, recipes,
+   non-obvious gotchas)
+
+User profile fact (identity, language, time zone,       USER.md           one-line confirm
+  preferred channel, approval rules, life goals)         
+
+Personality / tone / behavior style                     SOUL.md           explicit user request only;
+  (how the agent talks, sense of humor, formality,                         ALWAYS quote back and confirm
+   emoji use, brevity vs verbosity)
+
+Document / file generation standards                    FORMAT.md         confirm scope (global vs
+  (colors, fonts, layouts per file type)                                   per-doctype)
+
+Living UI design rules                                  GLOBAL_LIVING_UI  ask if non-trivial
+  (palette, components, responsive rules)               .md
+
+Per-mission state, multi-task continuity                workspace/        no consent needed
+                                                        missions/<n>/     (it's mission-internal)
+                                                        INDEX.md
+
+Recurring or scheduled task definitions                 PROACTIVE.md      via recurring_* / schedule_*
+                                                        (or scheduler_    actions, NOT manual edit
+                                                        config.json)
+
+A one-off fact you want recalled later                  (do nothing)      memory pipeline picks it up
+                                                                          from EVENT_UNPROCESSED.md
+```
+
+If you can't pick one cleanly, the change isn't well-scoped yet. Ask the user before editing anything.
+
+### AGENT.md (this file)
+
+**Purpose.** Operational manual. Stable rules, schemas, recipes, gotchas. Read by future-you on every relevant task.
+
+**When to edit:**
+- The user explicitly asks for an operational improvement: "from now on, always X", "add a new rule about Y", "update the manual to say Z".
+- You discover a non-obvious convention through repeated experience that future-you would benefit from. Examples:
+  - A config file gained a new section after the user installed something.
+  - A workflow has a gotcha that costs a turn to rediscover each time.
+  - An action has a non-obvious parameter that the LLM keeps missing.
+
+**When NOT to edit:**
+- During a task that isn't about self-improvement. Side-quest edits get lost in unrelated tasks and bloat the manual.
+- To record one-off facts about the current user. Those go in USER.md.
+- To record project-specific findings. Those go in `workspace/missions/<name>/INDEX.md`.
+- To document something the user might change tomorrow. Stable rules only.
+- After your first encounter with a friction. Wait for the second or third. Premature additions are noise.
+
+**Edit procedure:**
+```
+1. Read the section you want to change (and its neighbors) so your edit
+   matches the surrounding tone and structure.
+2. stream_edit AGENT.md (NEVER write_file; you'd lose the rest of the file).
+3. Bump the `version:` line in the front matter when the change is material.
+4. Sync to template: also stream_edit app/data/agent_file_system_template/AGENT.md
+   so new installs get the upgrade. Both files must stay byte-identical.
+5. Re-read the changed section in your next turn so the new content lands
+   in your in-context manual.
+6. For high-impact edits, send_message to the user describing what changed
+   and where (so they can review).
+```
+
+**Style rules** (from observed errors in past edits — see `## Errors`):
+- Optimize for grep. Stable `## <Topic>` headers, HTML markers `<!-- name -->` ... `<!-- /name -->` around schemas and command blocks.
+- No ASCII art, no decorative tables for non-tabular content, no em-dash flourishes, no marketing prose.
+- Topic-anchored cross-references (`see ## Configs`), never `§N` numbers.
+- One change at a time. Don't bundle a structural reorganization with content additions.
+
+**Hard rules:**
+- Never delete a section without user consent.
+- Never demote a section header without user consent (changes grep targets).
+- Never edit AGENT.md on behalf of the agent's preferences. AGENT.md describes the harness, not what the agent personally wants.
+
+### USER.md
+
+**Purpose.** User profile. Identity, communication preferences, agent-interaction rules, life goals, personality. Indexed by `memory_search` (see `## Memory`).
+
+**Standard sections** (do NOT rename):
+```
+## Identity
+   Full Name, Preferred Name, Email, Location, Timezone, Job, etc.
+
+## Communication Preferences
+   Language, Preferred Tone, Response Style, Preferred Messaging Platform.
+
+## Agent Interaction
+   Prefer Proactive Assistance, Approval Required For, working hours, etc.
+
+## Life Goals
+   Long-term goals worth aligning to.
+
+## Personality
+   The user's personality traits the agent should adapt to.
+```
+
+**When to edit:**
+- The user shares a stable preference: "I'm in Tokyo timezone now", "I prefer terse replies", "always confirm before sending email".
+- The onboarding interview produces a fact (handled by the soft-onboarding flow, but you may add to it later).
+- A preference becomes clear from repeated user feedback (3+ instances of the same correction).
+
+**Edit procedure:**
+```
+1. Confirm the preference is durable, not one-off.
+   Quick check: "Want me to remember that for future tasks too?"
+   If yes → durable, edit USER.md.
+   If no → don't edit; let the memory pipeline catch it as a one-off.
+2. stream_edit USER.md.
+3. Write to the RIGHT section (Identity / Communication / Agent Interaction
+   / Life Goals / Personality). If it doesn't fit any, ask the user where
+   they want it.
+4. After saving, send_message confirming the exact line you wrote so the
+   user can correct it.
+```
+
+**Hard rules:**
+- ONE-LINE CONFIRM is the default. Don't over-confirm; the user already told you the preference.
+- Never silently change USER.md. The user must see the diff or your description.
+- Don't put project-specific details here. Those go in `workspace/missions/<name>/INDEX.md`.
+- Don't put SECRETS here (passwords, tokens, credentials). USER.md is indexed by memory_search and surfaces in many contexts.
+- Don't put one-off facts here. "I'm working on X today" is one-off. "I always work on X-class problems" is durable.
+
+### SOUL.md
+
+**Purpose.** Personality, tone, voice, behavior style. **Injected directly into the system prompt every turn.** This is not a reference file — it shapes every word the agent produces.
+
+**When to edit:**
+- ONLY when the user explicitly asks for a personality change: "be more formal", "stop being so cheerful", "use more emojis", "be more concise".
+
+**When NOT to edit:**
+- ANY OTHER REASON. SOUL.md is the highest-stakes file. A wrong edit changes the agent's voice for every future interaction.
+- Inferring a personality preference from indirect signals. If the user complained about tone, ASK what they want changed before editing.
+- "Improving" the soul because you think it could be better. The user owns their agent's personality.
+
+**Edit procedure:**
+```
+1. Read the current SOUL.md fully. Understand the existing voice.
+2. Quote back the exact change you propose to make:
+     "I'll change <quote of current line> to <quote of new line>. Confirm?"
+3. WAIT for the user's reply. Do NOT edit on assumption.
+4. Once confirmed: stream_edit SOUL.md.
+5. Send a short follow-up: "Done. The new voice will start in your next
+   message." (Reminds the user that the change applies immediately.)
+```
+
+**Hard rules:**
+- Always quote-back-and-confirm. No exceptions.
+- Never ADD a new section without the user explicitly asking for one.
+- Never DELETE a section without explicit confirmation.
+- Don't put operational rules here. Operational rules go in AGENT.md. SOUL.md is voice and behavior style only.
+- If the user says "stop doing X" repeatedly and X feels personality-driven, ASK before editing SOUL.md. They might just want a one-task fix, not a permanent voice change.
+
+### FORMAT.md and GLOBAL_LIVING_UI.md
+
+These are not strictly "self" files (they're for output design, not agent behavior), but the agent edits them under similar discipline. See `## Documents` and `## Living UI` for the per-file procedures.
+
+Quick rules:
+- FORMAT.md: edit when the user gives a durable formatting preference. Confirm scope (global vs file-type-specific) before writing.
+- GLOBAL_LIVING_UI.md: edit when the user supplies a new universal UI rule. For project-specific overrides, edit the per-project `LIVING_UI.md` instead.
+
+### AGENT.md ↔ template sync
+
+`agent_file_system/AGENT.md` is the LIVE file the running agent reads.
+`app/data/agent_file_system_template/AGENT.md` is the TEMPLATE that seeds new installs (see `## Onboarding Context`).
+
+```
+When you edit AGENT.md for a durable improvement, the live file and the
+template MUST stay byte-identical:
+
+1. Make the edit on whichever file you started with.
+2. Copy the change to the other file (read the section, stream_edit the same
+   change in the other file).
+3. Verify with: diff agent_file_system/AGENT.md app/data/agent_file_system_template/AGENT.md
+   (or just grep both for the new content; should appear in both).
+```
+
+If a sync drift exists (template diverges from live), the next install for a new user will ship the OLD content. That's a silent failure mode worth fixing immediately.
+
+### Verifying a self-edit
+
+After ANY edit:
+
+```
+For AGENT.md:
+  1. re-read the changed section in your next turn (it's now in your context).
+  2. confirm the front-matter version: bumped (if material change).
+  3. confirm the template was synced.
+
+For USER.md:
+  1. read the section back, paste the relevant lines to the user as
+     confirmation: "I added: <new lines>. Look right?"
+  2. memory_search will pick it up on next index pass (see ## Memory).
+
+For SOUL.md:
+  1. send a short message; the new voice should be visible in YOUR own
+     wording.
+  2. if the user immediately says "that's not what I wanted",
+     ROLL BACK to the previous SOUL.md content (you should have read it
+     before editing — keep the previous version mentally for one turn).
+```
+
+### Rollback procedure
+
+If a self-edit broke something or the user objects:
+
+```
+1. AGENT.md: stream_edit back to the previous content. Bump version: again
+   (every change deserves a version bump, even reversions).
+2. USER.md: stream_edit the offending lines back to old or remove.
+3. SOUL.md: stream_edit back. Apologize briefly. Don't re-edit until the
+   user is explicit about what they want.
+```
+
+If you don't remember the previous content (e.g., it's been many turns), grep TASK_HISTORY.md or EVENT.md for the change event and reconstruct, OR ask the user to describe what they want restored.
+
+### What ENT.md, USER.md, and SOUL.md are NOT
+
+```
+- A scratch pad. Use workspace/tmp/{task_id}/ for that.
+- A todo list. Use task_update_todos.
+- A mission record. Use workspace/missions/<name>/INDEX.md.
+- A diary. Use EVENT.md (the system writes it; you don't).
+- A memory store. Use the memory pipeline + memory_search.
+- A knowledge base for arbitrary user data. Anything that isn't profile,
+  tone, or operational rule does not belong in these files.
+```
+
+### Anti-patterns
+
+- Editing AGENT.md for things that aren't operational rules (project state, one-off opinions, user-specific facts).
+- Editing USER.md for things that aren't user profile (mission state, one-off requests).
+- Editing SOUL.md without quote-back-and-confirm.
+- Forgetting the AGENT.md template sync. The template should never drift.
+- Adding a new section to USER.md without user consent. Stick to the standard sections.
+- Putting credentials, tokens, or secrets in any of these files. They are indexed by memory and visible in chat / logs.
+- Multiple self-edits in one turn without verification between each.
+- Editing AGENT.md silently as part of an unrelated task. Self-edits deserve their own task.
+
+### One-line summary for each file
+
+```
+AGENT.md   "How the harness works, and how to operate within it." (this file)
+USER.md    "Who the user is and what they prefer."
+SOUL.md    "How the agent sounds and behaves."
+```
+
+If a proposed edit doesn't fit cleanly into one of those three sentences, it probably belongs somewhere else.
+
+---
+
+## Glossary
+
+Quick lookup of the terms used throughout this manual. Each entry points to the section that owns the full definition. Grep this section first when an unfamiliar term shows up.
+
+```
+action                    atomic unit the LLM picks each turn                              ## Actions
+action set                named bundle of actions loaded together at task_start            ## Action Sets
+add_action_sets           action that loads additional action sets mid-task                ## Action Sets
+add_outcome               recurring_update_task field for recording execution result       ## Proactive
+agent file system         the persistent agent_file_system/ directory                      ## File System
+AGENT.md                  this file - operational manual                                    ## Self-Edit
+api_keys                  settings.json block holding provider API keys                    ## Configs / ## Models
+auth_type                 integration auth flow shape: oauth/token/both/interactive/...    ## Integrations
+ChromaDB                  vector store under chroma_db_memory/ powering memory_search      ## Memory
+complex task              multi-step task with todos + user-approval gate                  ## Tasks
+ConfigWatcher             0.5s-debounced file watcher for app/config/ files                ## Configs
+connect_integration       action that connects an external service via credentials         ## Integrations
+CONVERSATION_HISTORY.md   rolling dialogue record (do not edit)                            ## File System
+conversation mode         workflow when no task is active; only task_start/send/ignore    ## Tasks / ## Runtime
+core (action set)         always-loaded set; cannot be opted out                            ## Action Sets
+Decision Rubric           proactive task scoring (Impact/Risk/Cost/Urgency/Confidence)     PROACTIVE.md, ## Proactive
+EVENT.md                  complete chronological event log (do not edit)                   ## File System
+EVENT_UNPROCESSED.md      memory pipeline staging buffer (do not edit)                     ## File System / ## Memory
+event pipeline            flow from event -> EVENT_UNPROCESSED -> MEMORY.md                ## Memory
+FORMAT.md                 document/design standards file                                   ## Documents
+GLOBAL_LIVING_UI.md       global Living UI design rules                                    ## Living UI
+heartbeat                 scheduler entry firing every 30 min to run due proactive tasks   ## Proactive
+heartbeat-processor       skill that executes due tasks during a heartbeat                 ## Proactive
+hot-reload                config-watcher debounced 0.5s reload of /app/config/             ## Configs
+INDEX_TARGET_FILES        five files indexed by memory_search                              ## Memory
+integration               external-service connection (Slack, GitHub, Jira, ...)           ## Integrations
+INTEGRATION_HANDLERS      registry of available integration handlers                       ## Integrations
+LIVING_UI.md              per-project doc inside a Living UI project                       ## Living UI / ## File System
+Living UI                 generated React/HTML projects with persistent state              ## Living UI
+LLM                       large language model used for text generation                    ## Models
+LLMConsecutiveFailureError  circuit-breaker after 5 consecutive LLM failures               ## Errors / ## Models
+MCP                       Model Context Protocol; external tool servers                    ## MCP
+mcp_<server_name>         action set name registered when an MCP server connects           ## MCP / ## Action Sets
+memory_search             RAG action over indexed agent_file_system/ files                 ## Memory
+MemoryManager             ChromaDB-backed singleton for memory indexing + retrieval        ## Memory
+MEMORY.md                 distilled long-term memory; read via memory_search only          ## Memory / ## File System
+MISSION_INDEX_TEMPLATE.md template for workspace/missions/<name>/INDEX.md                  ## File System / ## Workspace
+mission                   multi-task initiative in workspace/missions/                     ## Workspace
+MODEL_REGISTRY            agent_core registry mapping providers to default models          ## Models
+onboarding                first-run setup flow (hard wizard + soft interview)              ## Onboarding Context
+outcome_history           per-task list of recent execution outcomes in PROACTIVE.md       ## Proactive
+parallelizable            decorator flag controlling whether action can run in parallel    ## Actions
+permission_tier           0-3 user-interaction level for proactive tasks                   PROACTIVE.md, ## Proactive
+PROACTIVE.md              recurring task definitions + Goals/Plan/Status                   ## Proactive / ## File System
+proactive task            task fired by a schedule, not a user prompt                      ## Proactive
+provider                  LLM provider name (openai, anthropic, gemini, ...)                ## Models
+react()                   the agent's main loop entry point                                 ## Runtime
+recurring_add             action to register a new recurring task in PROACTIVE.md          ## Proactive
+recurring_update_task     action to modify a task or record an outcome                     ## Proactive
+reinitialize_llm          internal call that rebuilds LLMInterface for a provider switch   ## Models
+schedule_task             action to add immediate / one-shot / recurring scheduled task    ## Proactive
+scheduler_config.json     cron schedules for system + user one-shot tasks                  ## Configs / ## Proactive
+simple task               <=3-action auto-ending task with no approval gate                 ## Tasks
+SKILL.md                  skill definition file with YAML frontmatter + body               ## Skills
+slow_mode                 settings.json flag throttling LLM requests                        ## Models
+SOUL.md                   personality file injected directly into system prompt            ## Self-Edit
+stream_edit               preferred action for editing existing files                      ## Files
+task_id                   unique identifier for a task; equals session_id                  ## Tasks / ## Runtime
+task_start                action to begin a task from conversation mode                    ## Tasks
+TASK_HISTORY.md           summaries of completed tasks (do not edit)                       ## File System
+task mode                 simple | complex; locked at task_start                            ## Tasks
+todo phase                Acknowledge / Collect / Execute / Verify / Confirm / Cleanup     ## Tasks
+trigger                   dispatch unit consumed by react()                                 ## Runtime
+USER.md                   user profile file (preferences, identity, goals)                  ## Self-Edit / ## File System
+VLM                       vision-language model used for image actions                      ## Models
+waiting_for_user_reply    task flag; trigger re-queues with 3-hour delay if no reply       ## Runtime / ## Tasks
+workflow                  one of 5 paths react() routes to                                  ## Runtime
+workflow lock             prevents concurrent memory / proactive runs                      ## Runtime
+workspace/                per-agent sandbox under agent_file_system/                        ## Workspace
+```
 
+If a term is missing, search the relevant section header (`grep_files "## <topic>" agent_file_system/AGENT.md`). If you encounter a new term that should be in this glossary, add it via the `## Self-Edit` AGENT.md flow.

From bdb6e3fc7face30a1eabd8482d52ad4fd71364d1 Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Thu, 7 May 2026 11:55:05 +0900
Subject: [PATCH 04/10] Open router initiate implementation

---
 agent_core/core/impl/llm/interface.py         |  57 ++-
 agent_core/core/models/connection_tester.py   |  75 +++
 agent_core/core/models/factory.py             |   2 +-
 agent_core/core/models/model_registry.py      |   7 +
 agent_core/core/models/provider_config.py     |   5 +
 app/config.py                                 |   6 +
 app/config/settings.json                      |  19 +-
 app/config/skills_config.json                 |   4 +-
 app/data/agent_file_system_template/AGENT.md  |  15 -
 app/tui/settings.py                           |   1 +
 app/ui_layer/adapters/browser_adapter.py      |  51 ++
 .../src/pages/Settings/ModelSettings.tsx      |  95 +++-
 .../pages/Settings/OpenRouterModelPicker.tsx  | 468 ++++++++++++++++++
 .../pages/Settings/SettingsPage.module.css    | 307 ++++++++++++
 app/ui_layer/commands/builtin/provider.py     |   7 +-
 app/ui_layer/settings/model_settings.py       |  23 +-
 app/ui_layer/settings/openrouter_catalog.py   | 225 +++++++++
 17 files changed, 1306 insertions(+), 61 deletions(-)
 create mode 100644 app/ui_layer/browser/frontend/src/pages/Settings/OpenRouterModelPicker.tsx
 create mode 100644 app/ui_layer/settings/openrouter_catalog.py

diff --git a/agent_core/core/impl/llm/interface.py b/agent_core/core/impl/llm/interface.py
index 913453ca..8b01bf83 100644
--- a/agent_core/core/impl/llm/interface.py
+++ b/agent_core/core/impl/llm/interface.py
@@ -367,7 +367,7 @@ def _generate_response_sync(
             logger.info(f"[LLM SEND] system={system_prompt} | user={user_prompt}")
 
         try:
-            if self.provider in ("openai", "minimax", "deepseek", "moonshot", "grok"):
+            if self.provider in ("openai", "minimax", "deepseek", "moonshot", "grok", "openrouter"):
                 response = self._generate_openai(system_prompt, user_prompt)
             elif self.provider == "remote":
                 response = self._generate_ollama(system_prompt, user_prompt)
@@ -502,7 +502,7 @@ def create_session_cache(
         supports_caching = (
             (self.provider == "byteplus" and self._byteplus_cache_manager) or
             (self.provider == "gemini" and self._gemini_cache_manager) or
-            (self.provider in ("openai", "deepseek", "grok") and self.client) or  # OpenAI/DeepSeek/Grok use automatic caching with prompt_cache_key
+            (self.provider in ("openai", "deepseek", "grok", "openrouter") and self.client) or  # OpenAI/DeepSeek/Grok/OpenRouter use automatic caching with prompt_cache_key (and cache_control for Anthropic-routed OpenRouter models)
             (self.provider == "anthropic" and self._anthropic_client)  # Anthropic uses ephemeral caching with extended TTL
         )
 
@@ -605,7 +605,7 @@ def has_session_cache(self, task_id: str, call_type: str) -> bool:
                 return True
             if self.provider == "gemini" and self._gemini_cache_manager:
                 return True
-            if self.provider in ("openai", "deepseek", "grok") and self.client:
+            if self.provider in ("openai", "deepseek", "grok", "openrouter") and self.client:
                 return True
             if self.provider == "anthropic" and self._anthropic_client:
                 return True
@@ -687,8 +687,8 @@ def _generate_response_with_session_sync(
                 logger.info(f"[LLM RECV] {cleaned}")
             return cleaned
 
-        # Handle OpenAI/DeepSeek/Grok with call_type-based cache routing
-        if self.provider in ("openai", "deepseek", "grok"):
+        # Handle OpenAI/DeepSeek/Grok/OpenRouter with call_type-based cache routing
+        if self.provider in ("openai", "deepseek", "grok", "openrouter"):
             # Get stored system prompt or use provided one
             session_key = f"{task_id}:{call_type}"
             stored_system_prompt = self._session_system_prompts.get(session_key)
@@ -1184,15 +1184,46 @@ def _generate_openai(
             # Always enforce JSON output format
             request_kwargs["response_format"] = {"type": "json_object"}
 
-            # Add prompt_cache_key for OpenAI/DeepSeek cache routing.
-            # Grok (xAI) does not support prompt_cache_key — it uses automatic
-            # prefix caching and ignores this parameter, so skip it for Grok.
-            if self.provider != "grok" and call_type and system_prompt and len(system_prompt) >= config.min_cache_tokens:
+            # Build provider-specific cache hints in extra_body.
+            # - prompt_cache_key (OpenAI/DeepSeek/OpenRouter): improves prefix-cache routing
+            #   stickiness across alternating call types. Grok ignores it; we skip there
+            #   to avoid noise.
+            # - cache_control (OpenRouter routing to Anthropic Claude only): Anthropic
+            #   prompt caching is opt-in. OpenRouter accepts a top-level cache_control
+            #   field and applies it to the last cacheable block automatically. For
+            #   OpenAI/DeepSeek/Gemini upstreams via OpenRouter, caching is automatic
+            #   on the upstream side, so cache_control would be ignored — we only set
+            #   it when the slug is Anthropic-routed.
+            extra_body: Dict[str, Any] = {}
+
+            long_enough = system_prompt and len(system_prompt) >= config.min_cache_tokens
+
+            if self.provider != "grok" and call_type and long_enough:
                 prompt_hash = hashlib.sha256(system_prompt.encode()).hexdigest()[:16]
                 cache_key = f"{call_type}_{prompt_hash}"
-                request_kwargs["extra_body"] = {"prompt_cache_key": cache_key}
+                extra_body["prompt_cache_key"] = cache_key
                 logger.debug(f"[OPENAI] Using prompt_cache_key: {cache_key}")
 
+            if self.provider == "openrouter" and long_enough:
+                model_lower_for_cache = (self.model or "").lower()
+                # OpenRouter slugs are "<provider>/<model>". Anthropic Claude routes
+                # are the only ones requiring opt-in cache_control. Detect by either
+                # the slug prefix or the "claude" substring (some aliases like
+                # "anthropic/claude-3.5-sonnet:beta" still match).
+                if model_lower_for_cache.startswith("anthropic/") or "claude" in model_lower_for_cache:
+                    cache_control: Dict[str, Any] = {"type": "ephemeral"}
+                    if call_type:
+                        # 1-hour TTL keeps caches alive across alternating call types
+                        # (mirrors the Anthropic-direct path).
+                        cache_control["ttl"] = "1h"
+                    extra_body["cache_control"] = cache_control
+                    logger.debug(
+                        f"[OPENROUTER] Anthropic cache_control: {cache_control} (model={self.model})"
+                    )
+
+            if extra_body:
+                request_kwargs["extra_body"] = extra_body
+
             response = self.client.chat.completions.create(**request_kwargs)
             content = response.choices[0].message.content.strip()
             token_count_input = response.usage.prompt_tokens
@@ -1235,9 +1266,11 @@ def _generate_openai(
             token_count_output,
         )
 
-        # Report usage
+        # Report usage. service_type stays "llm_openai" (the request shape) but
+        # provider attributes to the actual upstream so dashboards split out
+        # OpenRouter / DeepSeek / Grok separately.
         self._report_usage_async(
-            "llm_openai", "openai", self.model,
+            "llm_openai", self.provider, self.model,
             token_count_input, token_count_output, cached_tokens
         )
 
diff --git a/agent_core/core/models/connection_tester.py b/agent_core/core/models/connection_tester.py
index 77925b51..761727a2 100644
--- a/agent_core/core/models/connection_tester.py
+++ b/agent_core/core/models/connection_tester.py
@@ -54,6 +54,9 @@ def test_provider_connection(
         elif provider == "grok":
             url = cfg.default_base_url
             return _test_grok(api_key, url, timeout)
+        elif provider == "openrouter":
+            url = base_url or cfg.default_base_url
+            return _test_openrouter(api_key, url, timeout)
         elif provider in ("minimax", "deepseek", "moonshot"):
             url = cfg.default_base_url
             return _test_openai_compat(provider, api_key, url, timeout)
@@ -399,6 +402,78 @@ def _test_openai_compat(
         return {"success": False, "message": "Network error", "provider": provider, "error": str(e)}
 
 
+def _test_openrouter(
+    api_key: Optional[str], base_url: str, timeout: float
+) -> Dict[str, Any]:
+    """Test OpenRouter API connection.
+
+    Uses /api/v1/auth/key (auth-required) so we both validate the key and
+    surface the user's credit balance in the success message — that's the
+    information OpenRouter users care about most.
+    """
+    if not api_key:
+        return {
+            "success": False,
+            "message": "API key is required for OpenRouter",
+            "provider": "openrouter",
+            "error": "Missing API key",
+        }
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(
+                f"{base_url.rstrip('/')}/auth/key",
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+
+        if response.status_code == 200:
+            data = response.json().get("data", {}) or {}
+            limit = data.get("limit")
+            usage = data.get("usage")
+            label = data.get("label") or "OpenRouter key"
+            if limit is None:
+                msg = f"Connected to OpenRouter ({label}) — unlimited credits"
+            else:
+                remaining = max(0.0, float(limit) - float(usage or 0.0))
+                msg = (
+                    f"Connected to OpenRouter ({label}) — "
+                    f"${remaining:.2f} of ${float(limit):.2f} remaining"
+                )
+            return {
+                "success": True,
+                "message": msg,
+                "provider": "openrouter",
+            }
+        elif response.status_code in (401, 403):
+            return {
+                "success": False,
+                "message": "Invalid API key",
+                "provider": "openrouter",
+                "error": "Authentication failed - check your OpenRouter API key",
+            }
+        else:
+            return {
+                "success": False,
+                "message": f"API returned status {response.status_code}",
+                "provider": "openrouter",
+                "error": response.text[:300] if response.text else "Unknown error",
+            }
+    except httpx.TimeoutException:
+        return {
+            "success": False,
+            "message": "Connection timed out",
+            "provider": "openrouter",
+            "error": "Request timed out - check your network connection",
+        }
+    except httpx.RequestError as e:
+        return {
+            "success": False,
+            "message": "Network error",
+            "provider": "openrouter",
+            "error": str(e),
+        }
+
+
 def _test_grok(api_key: Optional[str], base_url: str, timeout: float) -> Dict[str, Any]:
     """Test xAI Grok API connection using a minimal chat completion request.
 
diff --git a/agent_core/core/models/factory.py b/agent_core/core/models/factory.py
index 7c654c58..a36b4302 100644
--- a/agent_core/core/models/factory.py
+++ b/agent_core/core/models/factory.py
@@ -65,7 +65,7 @@ def create(
             Dictionary with provider context including client instances
         """
         # OpenAI-compatible providers that use OpenAI client with a custom base_url
-        _OPENAI_COMPAT = {"minimax", "deepseek", "moonshot", "grok"}
+        _OPENAI_COMPAT = {"minimax", "deepseek", "moonshot", "grok", "openrouter"}
 
         if provider not in PROVIDER_CONFIG:
             raise ValueError(f"Unsupported provider: {provider}")
diff --git a/agent_core/core/models/model_registry.py b/agent_core/core/models/model_registry.py
index f63c365c..f3178bfd 100644
--- a/agent_core/core/models/model_registry.py
+++ b/agent_core/core/models/model_registry.py
@@ -49,4 +49,11 @@
         InterfaceType.VLM: "grok-4-0709",
         InterfaceType.EMBEDDING: None,
     },
+    "openrouter": {
+        # OpenRouter slugs follow `<provider>/<model>` format. Default to a Claude
+        # model so KV caching exercises the cache_control path on first use.
+        InterfaceType.LLM: "anthropic/claude-sonnet-4.5",
+        InterfaceType.VLM: "anthropic/claude-sonnet-4.5",
+        InterfaceType.EMBEDDING: None,
+    },
 }
diff --git a/agent_core/core/models/provider_config.py b/agent_core/core/models/provider_config.py
index c948ded1..2c8de6bd 100644
--- a/agent_core/core/models/provider_config.py
+++ b/agent_core/core/models/provider_config.py
@@ -41,4 +41,9 @@ class ProviderConfig:
         api_key_env="XAI_API_KEY",
         default_base_url="https://api.x.ai/v1",
     ),
+    "openrouter": ProviderConfig(
+        api_key_env="OPENROUTER_API_KEY",
+        base_url_env="OPENROUTER_BASE_URL",
+        default_base_url="https://openrouter.ai/api/v1",
+    ),
 }
diff --git a/app/config.py b/app/config.py
index e8290284..e28fbaa6 100644
--- a/app/config.py
+++ b/app/config.py
@@ -100,12 +100,14 @@ def _get_default_settings() -> Dict[str, Any]:
             "anthropic": "",
             "google": "",
             "byteplus": "",
+            "openrouter": "",
         },
         "endpoints": {
             "remote_model_url": "",
             "byteplus_base_url": "https://ark.ap-southeast.bytepluses.com/api/v3",
             "google_api_base": "",
             "google_api_version": "",
+            "openrouter_base_url": "",
         },
         "web_search": {
             "google_cse_id": "",
@@ -221,6 +223,7 @@ def get_api_key(provider: str) -> str:
         "gemini": "google",
         "google": "google",
         "byteplus": "byteplus",
+        "openrouter": "openrouter",
     }
 
     settings_key = key_map.get(provider, provider)
@@ -247,6 +250,9 @@ def get_base_url(provider: str) -> Optional[str]:
         return url if url else "http://localhost:11434"
     elif provider == "gemini" or provider == "google":
         return endpoints.get("google_api_base") or None
+    elif provider == "openrouter":
+        url = endpoints.get("openrouter_base_url", "")
+        return url if url else "https://openrouter.ai/api/v1"
 
     return None
 
diff --git a/app/config/settings.json b/app/config/settings.json
index 12c00359..9be5089a 100644
--- a/app/config/settings.json
+++ b/app/config/settings.json
@@ -1,5 +1,5 @@
 {
-  "version": "1.3.0",
+  "version": "1.3.1",
   "general": {
     "agent_name": "CraftBot",
     "os_language": "en"
@@ -14,10 +14,10 @@
     "item_word_limit": 150
   },
   "model": {
-    "llm_provider": "byteplus",
-    "vlm_provider": "byteplus",
-    "llm_model": "kimi-k2-250905",
-    "vlm_model": "seed-1-6-250915",
+    "llm_provider": "anthropic",
+    "vlm_provider": "anthropic",
+    "llm_model": "claude-sonnet-4-5-20250929",
+    "vlm_model": "claude-sonnet-4-5-20250929",
     "slow_mode": true,
     "slow_mode_tpm_limit": 25000
   },
@@ -25,14 +25,16 @@
     "openai": "",
     "anthropic": "",
     "google": "",
-    "byteplus": ""
+    "byteplus": "",
+    "openrouter": ""
   },
   "endpoints": {
     "remote_model_url": "",
     "byteplus_base_url": "https://ark.ap-southeast.bytepluses.com/api/v3",
     "google_api_base": "",
     "google_api_version": "",
-    "remote": "http://localhost:11434"
+    "remote": "http://localhost:11434",
+    "openrouter_base_url": ""
   },
   "gui": {
     "enabled": true,
@@ -76,6 +78,7 @@
     "openai": false,
     "anthropic": false,
     "google": true,
-    "byteplus": true
+    "byteplus": true,
+    "openrouter": false
   }
 }
\ No newline at end of file
diff --git a/app/config/skills_config.json b/app/config/skills_config.json
index 5f963ad8..203b0611 100644
--- a/app/config/skills_config.json
+++ b/app/config/skills_config.json
@@ -9,7 +9,9 @@
     "xlsx",
     "living-ui-creator",
     "living-ui-manager",
-    "living-ui-modify"
+    "living-ui-modify",
+    "craftbot-skill-creator",
+    "craftbot-skill-improve"
   ],
   "disabled_skills": [
     "cli-anything",
diff --git a/app/data/agent_file_system_template/AGENT.md b/app/data/agent_file_system_template/AGENT.md
index ea03f0da..5c0d6634 100644
--- a/app/data/agent_file_system_template/AGENT.md
+++ b/app/data/agent_file_system_template/AGENT.md
@@ -718,21 +718,6 @@ You're blocked when you don't know what to do next AND retrying won't help. The
 - **Asking open-ended "what should I do" questions.** Always one specific question with an implied default ("Use the bot token from settings.oauth.slack, or reuse the existing /slack login session?").
 - **Self-detected logical loops.** The consecutive-failure breaker only catches LLM-call failures. If you keep choosing slightly different params for the same action and getting the same business-logic error (e.g., "user not found" three times with three different IDs you guessed), that is a logical loop. Stop and ask the user.
 
-### Errors observed in past self-edits of this file (do not repeat)
-
-When you edit AGENT.md, USER.md, SOUL.md, FORMAT.md, or any other file an LLM (you, future-you) will consume, the consumer is a token-counting reader, not a human eye. These mistakes have happened before and are easy to repeat:
-
-- **Generating output formatted for human readers.** ASCII art (boxes with `┌─┐│└─┘`, arrow trees with `│ ▼`), decorative tables for prose content, em-dash flourishes, marketing intros ("This file is your instruction manual..."), and rhetorical paragraphs are noise to a token-counting reader. Use plain bulleted structure, code blocks for schemas/formats, and direct imperative rules.
-- **Numbered cross-references like `§4`, `§15`, `§22`.** They rot the moment a section is reordered or inserted. Use topic-anchored references: `see ## Tasks`, `see ## Configs`. The header becomes the stable anchor.
-- **Repeating the same warning across multiple sections.** Saying "DO NOT edit MEMORY.md" three times burns tokens without adding meaning. State it once where it belongs (`## File System` or `## Memory`) and reference it elsewhere.
-- **Documenting features that do not exist in the codebase.** Verify by reading source before describing behavior. Examples of fabrication that occurred: an "org chart" section, action parameters that the action did not accept, slash subcommands that were never registered.
-- **Decorative tables for non-tabular content.** Tables make sense for `key | value` mappings (config schemas, command lists). They make NO sense for "rules" or "guidelines" — those should be bullets the LLM can grep with `-A` context.
-- **Confusing length with comprehensiveness.** A 1300-line file the agent cannot navigate is less useful than a 700-line file with stable anchors and tight sections. Comprehensive means "covers what's needed", not "long".
-- **Confusing brevity with clarity.** Inverse of the above. A 10-line section that omits the actual mechanism (what triggers, what payloads, what error states, what the harness does for you) leaves the agent guessing. Detail every mechanism the agent will encounter.
-- **Writing prose where rules would do.** "Use this when X is true, but consider Y..." is harder to act on than "if X: do A. else: do B."
-
-The pattern under all of these: the consumer of this file is an LLM. Optimize for grep, structure, and unambiguous rules. Optimize against token waste and decorative noise.
-
 ### What the harness does NOT do for you
 
 - It does NOT change your approach when an action fails. You must.
diff --git a/app/tui/settings.py b/app/tui/settings.py
index dc45304c..47f63036 100644
--- a/app/tui/settings.py
+++ b/app/tui/settings.py
@@ -20,6 +20,7 @@
     "anthropic": "anthropic",
     "deepseek": "deepseek",
     "grok": "grok",
+    "openrouter": "openrouter",
 }
 
 
diff --git a/app/ui_layer/adapters/browser_adapter.py b/app/ui_layer/adapters/browser_adapter.py
index ec66b683..a2dbc872 100644
--- a/app/ui_layer/adapters/browser_adapter.py
+++ b/app/ui_layer/adapters/browser_adapter.py
@@ -1467,6 +1467,18 @@ async def _handle_ws_message(self, data: Dict[str, Any], ws=None) -> None:
             base_url = data.get("baseUrl")
             await self._handle_ollama_models_get(base_url)
 
+        elif msg_type == "openrouter_models_get":
+            await self._handle_openrouter_models_get(
+                base_url=data.get("baseUrl"),
+                force_refresh=bool(data.get("forceRefresh", False)),
+            )
+
+        elif msg_type == "openrouter_credits_get":
+            await self._handle_openrouter_credits_get(
+                api_key=data.get("apiKey"),
+                base_url=data.get("baseUrl"),
+            )
+
         elif msg_type == "slow_mode_get":
             await self._handle_slow_mode_get()
 
@@ -3721,6 +3733,45 @@ async def _handle_ollama_models_get(self, base_url: Optional[str] = None) -> Non
                 "data": {"success": False, "models": [], "error": str(e)},
             })
 
+    async def _handle_openrouter_models_get(
+        self,
+        base_url: Optional[str] = None,
+        force_refresh: bool = False,
+    ) -> None:
+        """Fetch the OpenRouter model catalog and broadcast it.
+
+        The catalog is public (no auth) and large (~300 entries). The helper
+        caches it in-process for 5 min; pass forceRefresh=True from the UI
+        to bypass the cache.
+        """
+        try:
+            from app.ui_layer.settings.openrouter_catalog import fetch_models
+            result = await asyncio.to_thread(
+                fetch_models, base_url, force_refresh=force_refresh
+            )
+            await self._broadcast({"type": "openrouter_models_get", "data": result})
+        except Exception as e:
+            await self._broadcast({
+                "type": "openrouter_models_get",
+                "data": {"success": False, "models": [], "error": str(e)},
+            })
+
+    async def _handle_openrouter_credits_get(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> None:
+        """Fetch the OpenRouter account credit balance for the configured key."""
+        try:
+            from app.ui_layer.settings.openrouter_catalog import fetch_credits
+            result = await asyncio.to_thread(fetch_credits, api_key, base_url)
+            await self._broadcast({"type": "openrouter_credits_get", "data": result})
+        except Exception as e:
+            await self._broadcast({
+                "type": "openrouter_credits_get",
+                "data": {"success": False, "error": str(e)},
+            })
+
     # ─────────────────────────────────────────────────────────────────────
     # Slow Mode Handlers
     # ─────────────────────────────────────────────────────────────────────
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
index 984015ec..c74e41c3 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
@@ -9,6 +9,11 @@ import { useToast } from '../../contexts/ToastContext'
 import styles from './SettingsPage.module.css'
 import { useSettingsWebSocket } from './useSettingsWebSocket'
 import { getOllamaInstallPercent } from '../../utils/ollamaInstall'
+import {
+  OpenRouterModelPicker,
+  OpenRouterCreditsBanner,
+  useOpenRouterCatalog,
+} from './OpenRouterModelPicker'
 
 // Types
 interface ProviderInfo {
@@ -20,6 +25,7 @@ interface ProviderInfo {
   llm_model: string | null
   vlm_model: string | null
   has_vlm: boolean
+  supports_catalog?: boolean
 }
 
 interface ApiKeyStatus {
@@ -93,6 +99,16 @@ export function ModelSettings() {
   const [pullBytes, setPullBytes] = useState<{ completed: number; total: number; percent: number } | null>(null)
   const [pullStatus, setPullStatus] = useState('')
 
+  // OpenRouter catalog — fetched once on first OpenRouter selection,
+  // shared between the LLM and VLM pickers below.
+  const orCatalog = useOpenRouterCatalog(
+    send,
+    onMessage,
+    isConnected,
+    provider === 'openrouter',
+    baseUrls['openrouter'] || newBaseUrl || undefined,
+  )
+
   const fmtBytes = (n: number) => {
     if (n >= 1_073_741_824) return `${(n / 1_073_741_824).toFixed(1)} GB`
     if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(0)} MB`
@@ -420,28 +436,40 @@ export function ModelSettings() {
           {/* Model Configuration */}
           {currentProvider && (
             <>
-              <div className={styles.formGroup}>
-                <label>LLM Model</label>
-                {provider === 'remote' && ollamaModels.length > 0 ? (
-                  <select
-                    value={newLlmModel || currentLlmModel || ''}
-                    onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
-                  >
-                    {ollamaModels.map(m => <option key={m} value={m}>{m}</option>)}
-                  </select>
-                ) : (
-                  <input
-                    type="text"
-                    value={newLlmModel || currentLlmModel || ''}
-                    onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
-                    placeholder={
-                      provider === 'remote' && ollamaModelsLoading
-                        ? 'Loading models...'
-                        : currentLlmModel || 'Enter LLM model name...'
-                    }
-                  />
-                )}
-              </div>
+              {provider === 'openrouter' && currentProvider.supports_catalog ? (
+                <OpenRouterModelPicker
+                  models={orCatalog.models}
+                  loading={orCatalog.loading}
+                  error={orCatalog.error}
+                  onRefresh={orCatalog.refresh}
+                  label="LLM Model"
+                  value={newLlmModel || currentLlmModel || ''}
+                  onChange={(v) => { setNewLlmModel(v); setHasChanges(true) }}
+                />
+              ) : (
+                <div className={styles.formGroup}>
+                  <label>LLM Model</label>
+                  {provider === 'remote' && ollamaModels.length > 0 ? (
+                    <select
+                      value={newLlmModel || currentLlmModel || ''}
+                      onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
+                    >
+                      {ollamaModels.map(m => <option key={m} value={m}>{m}</option>)}
+                    </select>
+                  ) : (
+                    <input
+                      type="text"
+                      value={newLlmModel || currentLlmModel || ''}
+                      onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
+                      placeholder={
+                        provider === 'remote' && ollamaModelsLoading
+                          ? 'Loading models...'
+                          : currentLlmModel || 'Enter LLM model name...'
+                      }
+                    />
+                  )}
+                </div>
+              )}
 
               {/* Download new Ollama model / Install Ollama */}
               {provider === 'remote' && (
@@ -605,6 +633,18 @@ export function ModelSettings() {
               )}
 
               {currentProvider.has_vlm && (
+                provider === 'openrouter' && currentProvider.supports_catalog ? (
+                  <OpenRouterModelPicker
+                    models={orCatalog.models}
+                    loading={orCatalog.loading}
+                    error={orCatalog.error}
+                    onRefresh={orCatalog.refresh}
+                    label="VLM Model"
+                    requireVision
+                    value={newVlmModel || currentVlmModel || ''}
+                    onChange={(v) => { setNewVlmModel(v); setHasChanges(true) }}
+                  />
+                ) : (
                 <div className={styles.formGroup}>
                   <label>VLM Model</label>
                   {(() => {
@@ -636,6 +676,7 @@ export function ModelSettings() {
                     )
                   })()}
                 </div>
+                )
               )}
             </>
           )}
@@ -663,6 +704,16 @@ export function ModelSettings() {
             </div>
           )}
 
+          {/* OpenRouter credits */}
+          {provider === 'openrouter' && currentProvider?.supports_catalog && (
+            <OpenRouterCreditsBanner
+              send={send}
+              onMessage={onMessage}
+              isConnected={isConnected}
+              hasApiKey={!!apiKeys[provider]?.has_key}
+            />
+          )}
+
           {/* Base URL */}
           {currentProvider?.base_url_env && (
             <div className={styles.formGroup}>
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/OpenRouterModelPicker.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/OpenRouterModelPicker.tsx
new file mode 100644
index 00000000..b3b86df2
--- /dev/null
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/OpenRouterModelPicker.tsx
@@ -0,0 +1,468 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Loader2, RefreshCw, Eye, Wrench, Database, ExternalLink } from 'lucide-react'
+import styles from './SettingsPage.module.css'
+
+export interface OpenRouterModel {
+  id: string
+  canonical_slug: string | null
+  name: string
+  description: string
+  context_length: number | null
+  input_modalities: string[]
+  output_modalities: string[]
+  pricing: {
+    prompt: string | null
+    completion: string | null
+    image: string | null
+    input_cache_read: string | null
+    input_cache_write: string | null
+  }
+  supported_parameters: string[]
+  is_moderated: boolean | null
+}
+
+export interface OpenRouterCredits {
+  balance: number | null
+  usage: number
+  limit: number | null
+  label: string | null
+  is_free_tier: boolean | null
+}
+
+type WsSend = (type: string, data?: Record<string, unknown>) => void
+type WsOnMessage = (type: string, handler: (data: unknown) => void) => () => void
+
+// ─────────────────────────────────────────────────────────────────────
+// Hooks: catalog and credits
+// ─────────────────────────────────────────────────────────────────────
+
+export function useOpenRouterCatalog(
+  send: WsSend,
+  onMessage: WsOnMessage,
+  isConnected: boolean,
+  enabled: boolean,
+  baseUrl?: string,
+) {
+  const [models, setModels] = useState<OpenRouterModel[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [fetchedAt, setFetchedAt] = useState<number | null>(null)
+  const requestedRef = useRef(false)
+
+  useEffect(() => {
+    const cleanup = onMessage('openrouter_models_get', (data: unknown) => {
+      const d = data as { success: boolean; models?: OpenRouterModel[]; error?: string; fetched_at?: number }
+      setLoading(false)
+      if (d.success && d.models) {
+        setModels(d.models)
+        setError(null)
+        if (d.fetched_at) setFetchedAt(d.fetched_at)
+      } else {
+        setError(d.error || 'Failed to load models')
+      }
+    })
+    return cleanup
+  }, [onMessage])
+
+  // Fetch once after we go enabled+connected. Re-fetch when baseUrl changes.
+  useEffect(() => {
+    if (!isConnected || !enabled || requestedRef.current) return
+    requestedRef.current = true
+    setLoading(true)
+    setError(null)
+    send('openrouter_models_get', baseUrl ? { baseUrl } : {})
+  }, [isConnected, enabled, baseUrl, send])
+
+  const refresh = () => {
+    setLoading(true)
+    setError(null)
+    send('openrouter_models_get', { ...(baseUrl ? { baseUrl } : {}), forceRefresh: true })
+  }
+
+  return { models, loading, error, fetchedAt, refresh }
+}
+
+export function useOpenRouterCredits(
+  send: WsSend,
+  onMessage: WsOnMessage,
+  isConnected: boolean,
+  hasApiKey: boolean,
+) {
+  const [credits, setCredits] = useState<OpenRouterCredits | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const cleanup = onMessage('openrouter_credits_get', (data: unknown) => {
+      const d = data as {
+        success: boolean
+        balance?: number | null
+        usage?: number
+        limit?: number | null
+        label?: string | null
+        is_free_tier?: boolean | null
+        error?: string
+      }
+      setLoading(false)
+      if (d.success) {
+        setCredits({
+          balance: d.balance ?? null,
+          usage: d.usage ?? 0,
+          limit: d.limit ?? null,
+          label: d.label ?? null,
+          is_free_tier: d.is_free_tier ?? null,
+        })
+        setError(null)
+      } else {
+        setCredits(null)
+        setError(d.error || 'Failed to load credits')
+      }
+    })
+    return cleanup
+  }, [onMessage])
+
+  useEffect(() => {
+    if (!isConnected || !hasApiKey) {
+      setCredits(null)
+      return
+    }
+    setLoading(true)
+    send('openrouter_credits_get')
+  }, [isConnected, hasApiKey, send])
+
+  return { credits, loading, error }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────
+
+function formatPricePerMillion(p: string | null | undefined): string | null {
+  if (p == null) return null
+  const n = parseFloat(p)
+  if (isNaN(n)) return null
+  if (n === 0) return null
+  const perM = n * 1_000_000
+  if (perM >= 100) return `$${perM.toFixed(0)}`
+  if (perM >= 1) return `$${perM.toFixed(2)}`
+  if (perM >= 0.01) return `$${perM.toFixed(3)}`
+  return `$${perM.toFixed(4)}`
+}
+
+function isFreeModel(m: OpenRouterModel): boolean {
+  if (m.id.endsWith(':free')) return true
+  const p = parseFloat(m.pricing.prompt || '0')
+  const c = parseFloat(m.pricing.completion || '0')
+  return (isNaN(p) || p === 0) && (isNaN(c) || c === 0)
+}
+
+function supportsVision(m: OpenRouterModel): boolean {
+  return m.input_modalities.includes('image')
+}
+
+function supportsTools(m: OpenRouterModel): boolean {
+  return m.supported_parameters.includes('tools') || m.supported_parameters.includes('tool_choice')
+}
+
+function supportsCache(m: OpenRouterModel): boolean {
+  return Boolean(m.pricing.input_cache_read)
+}
+
+function upstreamOf(id: string): string {
+  const slash = id.indexOf('/')
+  return slash > 0 ? id.slice(0, slash) : id
+}
+
+function formatContext(n: number | null | undefined): string {
+  if (n == null) return ''
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`
+  if (n >= 1_000) return `${Math.round(n / 1_000)}K`
+  return `${n}`
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Credits banner
+// ─────────────────────────────────────────────────────────────────────
+
+interface CreditsBannerProps {
+  send: WsSend
+  onMessage: WsOnMessage
+  isConnected: boolean
+  hasApiKey: boolean
+}
+
+export function OpenRouterCreditsBanner({ send, onMessage, isConnected, hasApiKey }: CreditsBannerProps) {
+  const { credits, loading, error } = useOpenRouterCredits(send, onMessage, isConnected, hasApiKey)
+
+  if (!hasApiKey) {
+    return (
+      <div className={styles.orCreditsRow}>
+        <span className={styles.orCreditsLabel}>
+          Save an API key to see credit balance.
+        </span>
+        <a
+          className={styles.orCreditsLink}
+          href="https://openrouter.ai/keys"
+          target="_blank"
+          rel="noreferrer"
+        >
+          Get a key <ExternalLink size={12} />
+        </a>
+      </div>
+    )
+  }
+
+  if (loading) {
+    return (
+      <div className={styles.orCreditsRow}>
+        <span className={styles.orCreditsLabel}>
+          <Loader2 size={12} className={styles.spinning} /> Loading credits…
+        </span>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className={styles.orCreditsRow}>
+        <span className={styles.orCreditsLabel}>Credits: {error}</span>
+      </div>
+    )
+  }
+
+  if (!credits) return null
+
+  const balanceText = credits.balance != null
+    ? `$${credits.balance.toFixed(2)} remaining`
+    : 'Pay-as-you-go (no preset limit)'
+
+  return (
+    <div className={styles.orCreditsRow}>
+      <span className={styles.orCreditsLabel}>
+        Credits: <strong>{balanceText}</strong>
+        {credits.label ? <span className={styles.orCreditsKey}> · {credits.label}</span> : null}
+      </span>
+      <a
+        className={styles.orCreditsLink}
+        href="https://openrouter.ai/credits"
+        target="_blank"
+        rel="noreferrer"
+      >
+        Top up <ExternalLink size={12} />
+      </a>
+    </div>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Model picker
+// ─────────────────────────────────────────────────────────────────────
+
+interface PickerProps {
+  models: OpenRouterModel[]
+  loading: boolean
+  error: string | null
+  value: string
+  onChange: (v: string) => void
+  onRefresh: () => void
+  requireVision?: boolean
+  label: string
+}
+
+export function OpenRouterModelPicker({
+  models,
+  loading,
+  error,
+  value,
+  onChange,
+  onRefresh,
+  requireVision = false,
+  label,
+}: PickerProps) {
+  const [search, setSearch] = useState('')
+  const [filterFree, setFilterFree] = useState(false)
+  const [filterVision, setFilterVision] = useState(requireVision)
+  const [filterTools, setFilterTools] = useState(false)
+  const [filterCache, setFilterCache] = useState(false)
+  const [upstream, setUpstream] = useState<string>('')
+
+  // VLM picker should keep the vision filter pinned on
+  useEffect(() => {
+    if (requireVision) setFilterVision(true)
+  }, [requireVision])
+
+  const upstreams = useMemo(() => {
+    const set = new Set<string>()
+    for (const m of models) set.add(upstreamOf(m.id))
+    return Array.from(set).sort()
+  }, [models])
+
+  const filtered = useMemo(() => {
+    const q = search.trim().toLowerCase()
+    return models.filter(m => {
+      if (filterFree && !isFreeModel(m)) return false
+      if (filterVision && !supportsVision(m)) return false
+      if (filterTools && !supportsTools(m)) return false
+      if (filterCache && !supportsCache(m)) return false
+      if (upstream && upstreamOf(m.id) !== upstream) return false
+      if (!q) return true
+      return (
+        m.id.toLowerCase().includes(q) ||
+        m.name.toLowerCase().includes(q) ||
+        (m.description || '').toLowerCase().includes(q)
+      )
+    })
+  }, [models, search, filterFree, filterVision, filterTools, filterCache, upstream])
+
+  return (
+    <div className={styles.formGroup}>
+      <label>{label}</label>
+
+      <div className={styles.orPicker}>
+        <div className={styles.orPickerHeader}>
+          <input
+            type="text"
+            className={styles.searchInput}
+            placeholder={`Search ${models.length || ''} models...`}
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+          />
+          <button
+            type="button"
+            className={styles.orPickerRefreshBtn}
+            onClick={onRefresh}
+            title="Refresh catalog"
+            disabled={loading}
+          >
+            {loading ? <Loader2 size={14} className={styles.spinning} /> : <RefreshCw size={14} />}
+          </button>
+        </div>
+
+        <div className={styles.orPickerFilters}>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterFree ? styles.orPickerChipActive : ''}`}
+            onClick={() => setFilterFree(v => !v)}
+            aria-pressed={filterFree}
+          >
+            Free only
+          </button>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterVision ? styles.orPickerChipActive : ''}`}
+            onClick={() => !requireVision && setFilterVision(v => !v)}
+            aria-pressed={filterVision}
+            disabled={requireVision}
+            title={requireVision ? 'Vision required for VLM models' : undefined}
+          >
+            Vision
+          </button>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterTools ? styles.orPickerChipActive : ''}`}
+            onClick={() => setFilterTools(v => !v)}
+            aria-pressed={filterTools}
+          >
+            Tools
+          </button>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterCache ? styles.orPickerChipActive : ''}`}
+            onClick={() => setFilterCache(v => !v)}
+            aria-pressed={filterCache}
+          >
+            Caching
+          </button>
+          <select
+            className={styles.orPickerUpstream}
+            value={upstream}
+            onChange={(e) => setUpstream(e.target.value)}
+          >
+            <option value="">Any upstream</option>
+            {upstreams.map(u => (
+              <option key={u} value={u}>{u}</option>
+            ))}
+          </select>
+        </div>
+
+        <div className={styles.orPickerList}>
+          {loading && models.length === 0 && (
+            <div className={styles.orPickerStatus}>
+              <Loader2 size={14} className={styles.spinning} /> Loading catalog…
+            </div>
+          )}
+          {error && (
+            <div className={styles.orPickerError}>
+              {error}
+              <button type="button" onClick={onRefresh}>Retry</button>
+            </div>
+          )}
+          {!loading && !error && filtered.length === 0 && (
+            <div className={styles.orPickerStatus}>
+              No models match your filters.
+            </div>
+          )}
+          {filtered.map(m => {
+            const free = isFreeModel(m)
+            const promptPrice = formatPricePerMillion(m.pricing.prompt)
+            const completionPrice = formatPricePerMillion(m.pricing.completion)
+            const ctxStr = formatContext(m.context_length)
+            const selected = value === m.id
+            return (
+              <button
+                key={m.id}
+                type="button"
+                className={`${styles.orPickerRow} ${selected ? styles.orPickerRowSelected : ''}`}
+                onClick={() => onChange(m.id)}
+              >
+                <div className={styles.orPickerRowLeft}>
+                  <div className={styles.orPickerRowName}>{m.name}</div>
+                  <div className={styles.orPickerRowSlug}>{m.id}</div>
+                </div>
+                <div className={styles.orPickerRowRight}>
+                  <div className={styles.orPickerRowMeta}>
+                    {ctxStr && <span className={styles.orPickerCtx}>{ctxStr} ctx</span>}
+                    {supportsVision(m) && (
+                      <span className={styles.orPickerCap} title="Vision capable">
+                        <Eye size={12} />
+                      </span>
+                    )}
+                    {supportsTools(m) && (
+                      <span className={styles.orPickerCap} title="Tool calling">
+                        <Wrench size={12} />
+                      </span>
+                    )}
+                    {supportsCache(m) && (
+                      <span className={styles.orPickerCap} title="Prompt caching">
+                        <Database size={12} />
+                      </span>
+                    )}
+                  </div>
+                  <div className={styles.orPickerRowPrice}>
+                    {free ? (
+                      <span className={styles.orPickerFreeBadge}>FREE</span>
+                    ) : promptPrice && completionPrice ? (
+                      <span>In {promptPrice} · Out {completionPrice} <span className={styles.orPickerPriceUnit}>/M</span></span>
+                    ) : (
+                      <span className={styles.orPickerPriceUnit}>see openrouter.ai</span>
+                    )}
+                  </div>
+                </div>
+              </button>
+            )
+          })}
+        </div>
+
+        <div className={styles.orPickerSlug}>
+          <label>Or paste a slug:</label>
+          <input
+            type="text"
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+            placeholder="anthropic/claude-sonnet-4.5"
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css b/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
index 35ba379f..68e5c57c 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
@@ -2220,3 +2220,310 @@
   margin: 0;
   background: transparent;
 }
+
+/* ─────────────────────────────────────────────────────────────────────
+   OpenRouter model picker + credits banner
+   Used only when provider === 'openrouter'.
+   ───────────────────────────────────────────────────────────────────── */
+
+/* Credits row — label-style, not an input. Mirrors the muted-text look
+   used elsewhere in settings (see .hint at line 183). No background, no
+   border — just a row of text with a trailing link. */
+.orCreditsRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+  padding: 0 var(--space-1);
+  font-size: var(--text-xs);
+  color: var(--text-secondary);
+  margin: calc(-1 * var(--space-2)) 0 var(--space-1);
+}
+
+.orCreditsLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.orCreditsLabel strong {
+  color: var(--text-primary);
+  font-weight: 500;
+}
+
+.orCreditsKey {
+  color: var(--text-muted);
+}
+
+.orCreditsLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--color-primary);
+  text-decoration: none;
+}
+
+.orCreditsLink:hover {
+  text-decoration: underline;
+}
+
+.orPicker {
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  background: var(--bg-secondary);
+  display: flex;
+  flex-direction: column;
+}
+
+/* Header reuses the shared .searchInput control (see line 1543) so the
+   style is consistent with Skills/MCP/Integrations search bars. */
+.orPickerHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-3);
+  border-bottom: 1px solid var(--border-primary);
+}
+
+.orPickerHeader .searchInput {
+  flex: 1;
+}
+
+.orPickerRefreshBtn {
+  background: transparent;
+  border: 1px solid var(--border-primary);
+  color: var(--text-secondary);
+  border-radius: var(--radius-sm);
+  width: 32px;
+  height: 32px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+
+.orPickerRefreshBtn:hover {
+  background: var(--bg-tertiary);
+}
+
+.orPickerRefreshBtn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.orPickerFilters {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--border-primary);
+  font-size: 12px;
+  color: var(--text-secondary);
+}
+
+/* Filter chips behave as toggle-buttons. Visual language mirrors the
+   shared .toggle switch (line 245): gray surface when off, primary
+   when on — so the on/off semantics match the rest of settings. */
+.orPickerChip {
+  display: inline-flex;
+  align-items: center;
+  padding: 4px 10px;
+  border-radius: var(--radius-full);
+  border: 1px solid var(--border-primary);
+  background: transparent;
+  color: var(--text-secondary);
+  font-size: var(--text-xs);
+  cursor: pointer;
+  user-select: none;
+  transition: background var(--transition-fast), color var(--transition-fast), border-color var(--transition-fast);
+}
+
+.orPickerChip:hover:not(:disabled) {
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.orPickerChip:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.orPickerChipActive {
+  background: var(--color-primary);
+  border-color: var(--color-primary);
+  color: var(--color-white);
+}
+
+.orPickerChipActive:hover:not(:disabled) {
+  background: var(--color-primary);
+  color: var(--color-white);
+}
+
+.orPickerUpstream {
+  margin-left: auto;
+  padding: 3px 6px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-primary);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 12px;
+}
+
+.orPickerList {
+  max-height: 360px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.orPickerStatus {
+  padding: 16px;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--text-secondary);
+  font-size: 13px;
+}
+
+.orPickerError {
+  padding: 12px 14px;
+  color: var(--color-warning);
+  font-size: 13px;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.orPickerError button {
+  background: transparent;
+  color: var(--color-primary);
+  border: 1px solid var(--border-primary);
+  padding: 3px 10px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+}
+
+.orPickerRow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 12px;
+  border: none;
+  border-bottom: 1px solid var(--border-primary);
+  background: transparent;
+  text-align: left;
+  cursor: pointer;
+  color: var(--text-primary);
+  width: 100%;
+}
+
+.orPickerRow:last-child {
+  border-bottom: none;
+}
+
+.orPickerRow:hover {
+  background: var(--bg-tertiary);
+}
+
+.orPickerRowSelected {
+  background: var(--color-primary-light);
+  border-left: 3px solid var(--color-primary);
+  padding-left: 9px;
+}
+
+.orPickerRowLeft {
+  flex: 1;
+  min-width: 0;
+}
+
+.orPickerRowName {
+  font-size: 13px;
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.orPickerRowSlug {
+  font-size: 11px;
+  color: var(--text-tertiary);
+  font-family: var(--font-mono);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.orPickerRowRight {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 4px;
+  flex-shrink: 0;
+  min-width: 160px;
+  text-align: right;
+}
+
+.orPickerRowMeta {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--text-tertiary);
+  font-size: 11px;
+}
+
+.orPickerCtx {
+  font-variant-numeric: tabular-nums;
+}
+
+.orPickerCap {
+  display: inline-flex;
+  align-items: center;
+  color: var(--text-secondary);
+}
+
+.orPickerRowPrice {
+  font-size: 11px;
+  color: var(--text-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+.orPickerPriceUnit {
+  color: var(--text-tertiary);
+}
+
+.orPickerFreeBadge {
+  background: var(--color-success-light);
+  color: var(--color-success);
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+}
+
+.orPickerSlug {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 12px;
+  border-top: 1px solid var(--border-primary);
+}
+
+.orPickerSlug label {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  margin: 0;
+  white-space: nowrap;
+}
+
+.orPickerSlug input {
+  flex: 1;
+  padding: 6px 10px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-primary);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 12px;
+  font-family: var(--font-mono);
+}
diff --git a/app/ui_layer/commands/builtin/provider.py b/app/ui_layer/commands/builtin/provider.py
index e9c1d9b7..4008b660 100644
--- a/app/ui_layer/commands/builtin/provider.py
+++ b/app/ui_layer/commands/builtin/provider.py
@@ -19,6 +19,7 @@ class ProviderCommand(Command):
         "byteplus": ("BYTEPLUS_API_KEY", "BytePlus"),
         "deepseek": ("DEEPSEEK_API_KEY", "DeepSeek"),
         "grok": ("XAI_API_KEY", "Grok (xAI)"),
+        "openrouter": ("OPENROUTER_API_KEY", "OpenRouter"),
         "remote": (None, "Ollama (Local)"),
     }
 
@@ -48,12 +49,16 @@ def help_text(self) -> str:
   gemini     - Google Gemini models
   anthropic  - Anthropic Claude models
   byteplus   - BytePlus Kimi models
+  deepseek   - DeepSeek models
+  grok       - Grok (xAI) models
+  openrouter - OpenRouter (300+ models, one key)
   remote     - Ollama (local models)
 
 Examples:
   /provider
   /provider openai
-  /provider openai sk-xxx"""
+  /provider openai sk-xxx
+  /provider openrouter sk-or-v1-xxx"""
 
     async def execute(
         self,
diff --git a/app/ui_layer/settings/model_settings.py b/app/ui_layer/settings/model_settings.py
index 9e3b7c52..6554b4bb 100644
--- a/app/ui_layer/settings/model_settings.py
+++ b/app/ui_layer/settings/model_settings.py
@@ -75,6 +75,19 @@
         "settings_key": "grok",
         "requires_api_key": True,
     },
+    "openrouter": {
+        "name": "OpenRouter",
+        "api_key_env": "OPENROUTER_API_KEY",
+        # Intentionally no base_url_env — the OpenRouter endpoint is fixed for
+        # almost everyone, and exposing the field confused users into thinking
+        # they had to fill it in. Power users who need a custom gateway can
+        # still set endpoints.openrouter_base_url in settings.json by hand;
+        # the backend still reads it (see app/config.py get_base_url).
+        "settings_key": "openrouter",
+        "requires_api_key": True,
+        # Frontend opts in to a catalog-aware picker for this provider.
+        "supports_catalog": True,
+    },
     "remote": {
         "name": "Local (Ollama)",
         "base_url_env": "REMOTE_MODEL_URL",
@@ -162,6 +175,7 @@ def get_available_providers() -> Dict[str, Any]:
                 "llm_model": llm_model,
                 "vlm_model": vlm_model,
                 "has_vlm": vlm_model is not None,
+                "supports_catalog": info.get("supports_catalog", False),
             })
 
         return {
@@ -229,6 +243,9 @@ def get_model_settings() -> Dict[str, Any]:
         if remote_url:
             base_urls["remote"] = remote_url
 
+        if endpoints_settings.get("openrouter_base_url"):
+            base_urls["openrouter"] = endpoints_settings["openrouter_base_url"]
+
         return {
             "success": True,
             "llm_provider": llm_provider,
@@ -323,6 +340,8 @@ def update_model_settings(
                 settings["endpoints"]["byteplus_base_url"] = base_url
             elif provider_for_url == "remote":
                 settings["endpoints"]["remote_model_url"] = base_url
+            elif provider_for_url == "openrouter":
+                settings["endpoints"]["openrouter_base_url"] = base_url
 
         # Clear remote URL when switching away from remote so stale values don't persist
         if llm_provider and llm_provider != "remote" and old_llm_provider == "remote" and not provider_for_url:
@@ -378,11 +397,13 @@ def test_connection(
                 api_key = api_keys_settings.get(settings_key)
 
         # If no base URL provided, try to get it from settings.json
-        if base_url is None and provider in ["byteplus", "remote"]:
+        if base_url is None and provider in ["byteplus", "remote", "openrouter"]:
             if provider == "byteplus":
                 base_url = endpoints_settings.get("byteplus_base_url")
             elif provider == "remote":
                 base_url = endpoints_settings.get("remote_model_url")
+            elif provider == "openrouter":
+                base_url = endpoints_settings.get("openrouter_base_url")
 
         # Run connection test
         result = test_provider_connection(
diff --git a/app/ui_layer/settings/openrouter_catalog.py b/app/ui_layer/settings/openrouter_catalog.py
new file mode 100644
index 00000000..18724a9f
--- /dev/null
+++ b/app/ui_layer/settings/openrouter_catalog.py
@@ -0,0 +1,225 @@
+"""OpenRouter catalog + credits helpers for the settings UI.
+
+OpenRouter exposes a public model catalog at GET /api/v1/models (no auth)
+and a credits endpoint at GET /api/v1/credits / GET /api/v1/auth/key
+(auth required). The model picker renders the catalog and the balance.
+
+The catalog is cached in-process for 5 minutes — OpenRouter publishes new
+models periodically, but ~300 entries is enough payload that we don't
+want to re-fetch on every settings page open.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from app.config import get_api_key, get_base_url
+
+
+_DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+_CATALOG_TTL_SECONDS = 300  # 5 min — matches OR's own cache windows
+_CATALOG_TIMEOUT = 15.0
+_CREDITS_TIMEOUT = 10.0
+
+# In-process cache: { base_url: (timestamp, models) }
+_catalog_cache: Dict[str, tuple] = {}
+
+
+def _resolve_base_url(base_url: Optional[str] = None) -> str:
+    if base_url:
+        return base_url
+    configured = get_base_url("openrouter")
+    return configured or _DEFAULT_BASE_URL
+
+
+def _normalize_model(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """Project the OpenRouter model record to the fields the UI needs.
+
+    OpenRouter's payload is large per-model (descriptions, hugging-face links,
+    etc.). We only ship what the picker actually renders — keeps WS frames
+    small and makes the frontend types narrower.
+    """
+    pricing = raw.get("pricing") or {}
+    architecture = raw.get("architecture") or {}
+    top_provider = raw.get("top_provider") or {}
+    return {
+        "id": raw.get("id"),
+        "canonical_slug": raw.get("canonical_slug"),
+        "name": raw.get("name") or raw.get("id"),
+        "description": (raw.get("description") or "")[:500],
+        "context_length": raw.get("context_length") or top_provider.get("context_length"),
+        "input_modalities": architecture.get("input_modalities") or [],
+        "output_modalities": architecture.get("output_modalities") or [],
+        "pricing": {
+            "prompt": pricing.get("prompt"),
+            "completion": pricing.get("completion"),
+            "image": pricing.get("image"),
+            "input_cache_read": pricing.get("input_cache_read"),
+            "input_cache_write": pricing.get("input_cache_write"),
+        },
+        "supported_parameters": raw.get("supported_parameters") or [],
+        "is_moderated": top_provider.get("is_moderated"),
+    }
+
+
+def fetch_models(
+    base_url: Optional[str] = None,
+    *,
+    force_refresh: bool = False,
+) -> Dict[str, Any]:
+    """Return the OpenRouter model catalog (cached).
+
+    Returns:
+        {"success": bool, "models": [...], "fetched_at": int, "error": str?}
+    """
+    url = _resolve_base_url(base_url)
+    cache_key = url
+
+    if not force_refresh:
+        entry = _catalog_cache.get(cache_key)
+        if entry is not None:
+            ts, models = entry
+            if (time.time() - ts) < _CATALOG_TTL_SECONDS:
+                return {
+                    "success": True,
+                    "models": models,
+                    "fetched_at": int(ts),
+                    "cached": True,
+                }
+
+    try:
+        with httpx.Client(timeout=_CATALOG_TIMEOUT) as client:
+            response = client.get(f"{url.rstrip('/')}/models")
+        if response.status_code != 200:
+            return {
+                "success": False,
+                "models": [],
+                "error": f"OpenRouter /models returned status {response.status_code}",
+            }
+        raw_models = response.json().get("data") or []
+        models = [_normalize_model(m) for m in raw_models if m.get("id")]
+        _catalog_cache[cache_key] = (time.time(), models)
+        return {
+            "success": True,
+            "models": models,
+            "fetched_at": int(time.time()),
+            "cached": False,
+        }
+    except httpx.TimeoutException:
+        return {
+            "success": False,
+            "models": [],
+            "error": "Timed out fetching OpenRouter model catalog",
+        }
+    except httpx.RequestError as exc:
+        return {
+            "success": False,
+            "models": [],
+            "error": f"Network error fetching OpenRouter models: {exc}",
+        }
+    except Exception as exc:  # pragma: no cover — defensive
+        return {
+            "success": False,
+            "models": [],
+            "error": f"Unexpected error fetching OpenRouter models: {exc}",
+        }
+
+
+def fetch_credits(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Return account credit info for the configured OpenRouter key.
+
+    Hits /api/v1/credits (preferred — newer endpoint with `total_credits` /
+    `total_usage`). Falls back to /api/v1/auth/key on 404 since older keys /
+    routes still expose the legacy shape.
+
+    Returns:
+        {"success": bool, "balance": float, "usage": float, "limit": float?,
+         "label": str?, "error": str?}
+    """
+    if not api_key:
+        api_key = get_api_key("openrouter")
+    if not api_key:
+        return {
+            "success": False,
+            "error": "No OpenRouter API key configured",
+        }
+
+    url = _resolve_base_url(base_url)
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    try:
+        with httpx.Client(timeout=_CREDITS_TIMEOUT) as client:
+            response = client.get(f"{url.rstrip('/')}/credits", headers=headers)
+            if response.status_code == 404:
+                # Legacy fallback
+                response = client.get(f"{url.rstrip('/')}/auth/key", headers=headers)
+
+        if response.status_code in (401, 403):
+            return {
+                "success": False,
+                "error": "Invalid API key",
+            }
+        if response.status_code != 200:
+            return {
+                "success": False,
+                "error": f"Credits endpoint returned status {response.status_code}",
+            }
+
+        data = response.json().get("data") or {}
+
+        # /credits shape: { total_credits, total_usage }
+        # /auth/key shape: { label, usage, limit, is_free_tier, ... }
+        total_credits = data.get("total_credits")
+        total_usage = data.get("total_usage")
+        if total_credits is not None or total_usage is not None:
+            credits = float(total_credits) if total_credits is not None else 0.0
+            usage = float(total_usage) if total_usage is not None else 0.0
+            return {
+                "success": True,
+                "balance": max(0.0, credits - usage),
+                "usage": usage,
+                "limit": credits if total_credits is not None else None,
+                "label": data.get("label"),
+                "is_free_tier": data.get("is_free_tier"),
+            }
+
+        # Legacy /auth/key
+        usage = float(data.get("usage") or 0.0)
+        limit = data.get("limit")
+        balance = None
+        if limit is not None:
+            balance = max(0.0, float(limit) - usage)
+        return {
+            "success": True,
+            "balance": balance,
+            "usage": usage,
+            "limit": float(limit) if limit is not None else None,
+            "label": data.get("label"),
+            "is_free_tier": data.get("is_free_tier"),
+        }
+
+    except httpx.TimeoutException:
+        return {
+            "success": False,
+            "error": "Timed out fetching OpenRouter credits",
+        }
+    except httpx.RequestError as exc:
+        return {
+            "success": False,
+            "error": f"Network error fetching OpenRouter credits: {exc}",
+        }
+    except Exception as exc:  # pragma: no cover — defensive
+        return {
+            "success": False,
+            "error": f"Unexpected error fetching OpenRouter credits: {exc}",
+        }
+
+
+def invalidate_catalog_cache() -> None:
+    _catalog_cache.clear()

From 96a6b66969538a55bb57531fcc7373bfbad54fd2 Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Fri, 8 May 2026 14:57:28 +0900
Subject: [PATCH 05/10] Update LLM call error display and improve chat pannel
 UI

---
 agent_core/core/impl/llm/errors.py            | 934 +++++++++++++++---
 agent_core/core/impl/llm/interface.py         |  79 +-
 agent_core/core/models/connection_tester.py   | 695 +++++++------
 app/agent_base.py                             |  45 +-
 app/ui_layer/adapters/browser_adapter.py      |   5 +-
 .../src/components/Chat/Chat.module.css       |  76 ++
 .../frontend/src/components/Chat/Chat.tsx     | 189 ++--
 .../frontend/src/pages/Chat/ChatMessage.tsx   |   2 +-
 .../src/pages/Settings/ModelSettings.tsx      |   4 +
 app/ui_layer/settings/model_settings.py       |   6 +
 10 files changed, 1466 insertions(+), 569 deletions(-)

diff --git a/agent_core/core/impl/llm/errors.py b/agent_core/core/impl/llm/errors.py
index 052e2611..e63b5605 100644
--- a/agent_core/core/impl/llm/errors.py
+++ b/agent_core/core/impl/llm/errors.py
@@ -2,180 +2,864 @@
 """
 LLM Error Classification Module.
 
-Provides user-friendly error messages for LLM-related failures.
-Uses proper exception types and HTTP status codes - no string pattern matching.
+Turns provider-specific exceptions into a structured `LLMErrorInfo` so the UI
+can render category-aware error cards (auth vs credits vs rate-limit vs
+server, etc.) instead of a single generic string.
+
+Provider error shapes were captured from live SDK responses — see comments
+on each per-provider extractor. The classifier is intentionally defensive
+(every body lookup tolerates `None` / wrong type) because some providers
+return string bodies, partial JSON, or undocumented fields.
+
+External callers:
+- `classify_llm_error(exc) -> LLMErrorInfo` is the new structured API.
+- `classify_llm_error_message(exc) -> str` is the back-compat shim for any
+  caller that only wants the plain string. Equivalent to
+  `classify_llm_error(exc).message`.
 """
 
 from __future__ import annotations
 
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple
 
-from typing import Optional
 
-# Import provider exception types
+# Optional provider SDK imports — kept defensive so missing extras don't
+# break the classifier path.
 try:
     import openai
-except ImportError:
+except ImportError:  # pragma: no cover
     openai = None
 
 try:
     import anthropic
-except ImportError:
+except ImportError:  # pragma: no cover
     anthropic = None
 
+try:
+    import httpx
+except ImportError:  # pragma: no cover
+    httpx = None
+
 try:
     import requests
-except ImportError:
+except ImportError:  # pragma: no cover
     requests = None
 
 
-# User-friendly messages
-MSG_AUTH = "Unable to connect to AI service. Please check your API key in Settings."
+# ─── Public taxonomy ──────────────────────────────────────────────────
+
+
+class ErrorCategory(str, Enum):
+    AUTH = "auth"               # 401/403 — bad/missing key, key revoked
+    CREDIT = "credit"           # 402, "insufficient_quota", "credit_balance_too_low"
+    RATE_LIMIT = "rate_limit"   # 429 — transient
+    QUOTA = "quota"             # 429 + monthly/account scope (separable from per-min)
+    MODEL = "model"             # 404, "model_not_found"
+    BAD_REQUEST = "bad_request" # 400 — request malformed (context overflow, etc.)
+    BLOCKED = "blocked"         # safety filter (Gemini/Anthropic)
+    SERVER = "server"           # 5xx, "overloaded_error"
+    CONNECTION = "connection"   # network / timeout / DNS
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class ErrorAction:
+    """A clickable affordance attached to an error.
+
+    `url` opens in a new tab; `action` is a frontend-resolved verb such as
+    "open_settings_model" — handled by the chat component, not by URL nav.
+    Exactly one of url/action should be set.
+    """
+    label: str
+    url: Optional[str] = None
+    action: Optional[str] = None
+
+
+@dataclass
+class LLMErrorInfo:
+    category: ErrorCategory
+    title: str                          # e.g. "Rate limited"
+    message: str                        # e.g. "Free-tier limit on Google AI Studio. Wait ~30s or add your own key."
+    provider: str                       # "openrouter", "anthropic", ...
+    upstream: Optional[str] = None      # "Google AI Studio" — present when OR proxies
+    model: Optional[str] = None
+    http_status: Optional[int] = None
+    retry_after_seconds: Optional[int] = None
+    actions: List[ErrorAction] = field(default_factory=list)
+    raw_message: Optional[str] = None   # truncated raw upstream text for "Show details"
+    request_id: Optional[str] = None    # for support tickets
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        d["category"] = self.category.value
+        return d
+
+
+# ─── Provider display names + category fallbacks ─────────────────────
+
+
+_PROVIDER_DISPLAY: Dict[str, str] = {
+    "openai": "OpenAI",
+    "openrouter": "OpenRouter",
+    "anthropic": "Anthropic",
+    "gemini": "Gemini",
+    "google": "Gemini",
+    "byteplus": "BytePlus",
+    "deepseek": "DeepSeek",
+    "grok": "Grok",
+    "moonshot": "Moonshot",
+    "minimax": "MiniMax",
+    "remote": "Ollama",
+}
+
+
+# Used only when the provider gave us no message at all (rare). Most
+# real-world errors have an upstream message that's already informative;
+# we lead with that and only append a short action hint.
+_FALLBACK_BODY_BY_CATEGORY: Dict[ErrorCategory, str] = {
+    ErrorCategory.AUTH:        "the API key was rejected",
+    ErrorCategory.CREDIT:      "out of credits",
+    ErrorCategory.RATE_LIMIT:  "rate-limited",
+    ErrorCategory.QUOTA:       "quota exceeded",
+    ErrorCategory.MODEL:       "the selected model is not available",
+    ErrorCategory.BAD_REQUEST: "the request was rejected",
+    ErrorCategory.BLOCKED:     "blocked by the provider's safety filter",
+    ErrorCategory.SERVER:      "the provider is unavailable",
+    ErrorCategory.CONNECTION:  "unable to reach the provider",
+    ErrorCategory.UNKNOWN:     "something went wrong",
+}
+
+
+# Back-compat string constants — some callers still import these directly.
+# Kept thin (single phrase) since the rich text now flows through info.message.
+MSG_AUTH = "The API key was rejected. Check your key in Settings."
+MSG_RATE_LIMIT = "The provider rate-limited this request. Try again shortly."
+MSG_MODEL = "The selected model is not available. Pick a different model in Settings."
+MSG_CONFIG = "The request was rejected by the provider."
+MSG_SERVICE = "The provider service is unavailable. Try again later."
+MSG_CONNECTION = "Could not reach the provider. Check your network connection."
+MSG_GENERIC = "Something went wrong calling the AI service."
 MSG_CONSECUTIVE_FAILURE = (
-    "LLM calls have failed {count} consecutive times. "
-    "Task aborted to prevent infinite retries. Please check your LLM configuration."
+    "Aborted after {count} consecutive failures."
 )
 
 
+# ─── Consecutive-failure exception (preserves last classified info) ───
+
+
 class LLMConsecutiveFailureError(Exception):
     """Raised when LLM calls fail too many times consecutively.
 
-    This exception signals that the task should be aborted to prevent
-    infinite retry loops that flood logs and waste resources.
+    Carries the last classified `LLMErrorInfo` (when known) so the UI can
+    surface the *cause* of the failures, not just the count.
     """
 
-    def __init__(self, failure_count: int, last_error: Optional[Exception] = None):
+    def __init__(
+        self,
+        failure_count: int,
+        last_error: Optional[Exception] = None,
+        last_error_info: Optional[LLMErrorInfo] = None,
+    ):
         self.failure_count = failure_count
         self.last_error = last_error
+        self.last_error_info = last_error_info
         message = MSG_CONSECUTIVE_FAILURE.format(count=failure_count)
         if last_error:
             message += f" Last error: {last_error}"
         super().__init__(message)
-MSG_MODEL = "The selected AI model is not available. Please check your model settings."
-MSG_CONFIG = "AI service configuration error. The selected model may not support required features."
-MSG_RATE_LIMIT = "AI service is rate-limited. Please wait a moment and try again."
-MSG_SERVICE = "AI service is temporarily unavailable. Please try again later."
-MSG_CONNECTION = "Unable to reach AI service. Please check your internet connection."
-MSG_GENERIC = "An error occurred with the AI service. Please check your LLM configuration."
 
 
-def classify_llm_error(error: Exception) -> str:
-    """Classify an LLM error and return a user-friendly message.
+# ─── Public entry points ──────────────────────────────────────────────
+
 
-    Uses exception types and HTTP status codes for classification.
+def classify_llm_error(
+    error: Exception,
+    *,
+    provider: Optional[str] = None,
+    model: Optional[str] = None,
+) -> LLMErrorInfo:
+    """Classify an LLM error into structured info.
+
+    The user-visible string is `info.message` — fully self-contained, with
+    provider/upstream/raw/action hint composed inline. Other fields are
+    informational (logging, metrics) and not surfaced to the UI directly.
 
     Args:
-        error: The exception from the LLM call.
+        error: The exception raised by the provider call.
+        provider: Provider id (e.g. "openrouter", "anthropic"). Lets us
+            unwrap provider-specific error shapes (notably OpenRouter's
+            `metadata.provider_name`/`metadata.raw`).
+        model: Model id at call time. Stored on the info for logging.
 
     Returns:
-        A user-friendly error message.
+        `LLMErrorInfo` — never raises. For unrecognised shapes, falls back
+        to UNKNOWN with the raw exception text preserved as the message
+        (better than a generic stub — at least the user sees what blew up).
     """
-    # Check OpenAI exceptions
-    if openai is not None:
-        msg = _classify_openai_error(error)
-        if msg:
-            return msg
-
-    # Check Anthropic exceptions
-    if anthropic is not None:
-        msg = _classify_anthropic_error(error)
-        if msg:
-            return msg
-
-    # Check requests exceptions (BytePlus, remote/Ollama)
-    if requests is not None:
-        msg = _classify_requests_error(error)
-        if msg:
-            return msg
-
-    # Check for status_code attribute on any exception
-    status_code = _get_status_code(error)
-    if status_code:
-        return _message_from_status_code(status_code)
-
-    # Generic fallback
-    return MSG_GENERIC
-
-
-def _classify_openai_error(error: Exception) -> Optional[str]:
-    """Classify OpenAI SDK exceptions."""
-    if isinstance(error, openai.AuthenticationError):
-        return MSG_AUTH
-    if isinstance(error, openai.PermissionDeniedError):
-        return MSG_AUTH
-    if isinstance(error, openai.NotFoundError):
-        return MSG_MODEL
-    if isinstance(error, openai.BadRequestError):
-        return MSG_CONFIG
-    if isinstance(error, openai.RateLimitError):
-        return MSG_RATE_LIMIT
-    if isinstance(error, openai.InternalServerError):
-        return MSG_SERVICE
-    if isinstance(error, openai.APIConnectionError):
-        return MSG_CONNECTION
-    if isinstance(error, openai.APITimeoutError):
-        return MSG_CONNECTION
-    if isinstance(error, openai.APIStatusError):
-        return _message_from_status_code(error.status_code)
-    return None
+    info = _try_classify(error, provider=provider)
+    if info is None:
+        # Don't fabricate a generic message — the raw exception text is
+        # almost always more informative than any stub we could write.
+        raw = _truncate(str(error)) or "AI service error"
+        info = LLMErrorInfo(
+            category=ErrorCategory.UNKNOWN,
+            title="AI service error",
+            message=raw,
+            provider=provider or "unknown",
+            raw_message=raw,
+        )
+
+    if model and info.model is None:
+        info.model = model
+
+    return info
+
+
+def classify_llm_error_message(error: Exception) -> str:
+    """Back-compat shim — returns just the user-facing string.
+
+    Equivalent to `classify_llm_error(error).message`. Kept so existing
+    call sites that only need a string don't have to refactor in this PR.
+    """
+    return classify_llm_error(error).message
 
 
-def _classify_anthropic_error(error: Exception) -> Optional[str]:
-    """Classify Anthropic SDK exceptions."""
-    if isinstance(error, anthropic.AuthenticationError):
-        return MSG_AUTH
-    if isinstance(error, anthropic.PermissionDeniedError):
-        return MSG_AUTH
-    if isinstance(error, anthropic.NotFoundError):
-        return MSG_MODEL
-    if isinstance(error, anthropic.BadRequestError):
-        return MSG_CONFIG
-    if isinstance(error, anthropic.RateLimitError):
-        return MSG_RATE_LIMIT
-    if isinstance(error, anthropic.InternalServerError):
-        return MSG_SERVICE
-    if isinstance(error, anthropic.APIConnectionError):
-        return MSG_CONNECTION
-    if isinstance(error, anthropic.APITimeoutError):
-        return MSG_CONNECTION
-    if isinstance(error, anthropic.APIStatusError):
-        return _message_from_status_code(error.status_code)
-    return None
+# ─── Dispatcher ───────────────────────────────────────────────────────
+
+
+def _try_classify(
+    error: Exception,
+    *,
+    provider: Optional[str],
+) -> Optional[LLMErrorInfo]:
+    """Try each provider extractor in turn. Returns None if nothing matches."""
+    # OpenAI SDK exceptions cover openai/openrouter/grok/deepseek/moonshot/minimax
+    if openai is not None and isinstance(error, openai.OpenAIError):
+        return _classify_openai_compat(error, provider or "openai")
+
+    # Anthropic SDK exceptions
+    if anthropic is not None and isinstance(error, anthropic.AnthropicError):
+        return _classify_anthropic(error, provider or "anthropic")
 
+    # httpx errors are how the Gemini and BytePlus paths surface failures
+    if httpx is not None and isinstance(error, httpx.HTTPStatusError):
+        return _classify_httpx_status(error, provider)
+    if httpx is not None and isinstance(error, httpx.RequestError):
+        return _classify_httpx_connection(error, provider)
+
+    # `requests` library — older code paths still raise these
+    if requests is not None and isinstance(error, requests.exceptions.RequestException):
+        return _classify_requests(error, provider)
+
+    # Gemini's custom error type (raised by our REST client)
+    msg = str(error)
+    if "Gemini" in msg or "promptFeedback" in msg or "blocked" in msg.lower():
+        return _classify_gemini_runtime(error, provider or "gemini")
 
-def _classify_requests_error(error: Exception) -> Optional[str]:
-    """Classify requests library exceptions (for BytePlus/Ollama)."""
-    if isinstance(error, requests.exceptions.HTTPError):
-        if error.response is not None:
-            return _message_from_status_code(error.response.status_code)
-        return MSG_SERVICE
-    if isinstance(error, requests.exceptions.ConnectionError):
-        return MSG_CONNECTION
-    if isinstance(error, requests.exceptions.Timeout):
-        return MSG_CONNECTION
     return None
 
 
-def _get_status_code(error: Exception) -> Optional[int]:
-    """Extract HTTP status code from exception if available."""
-    # Check for status_code attribute
-    if hasattr(error, "status_code"):
-        return getattr(error, "status_code", None)
-    # Check for response.status_code (requests-style)
-    if hasattr(error, "response") and hasattr(error.response, "status_code"):
-        return error.response.status_code
+# ─── OpenAI / OpenAI-compatible (openai, openrouter, grok, deepseek, ...) ───
+
+
+def _classify_openai_compat(exc: Exception, provider: str) -> LLMErrorInfo:
+    """Handle openai SDK exception hierarchy.
+
+    Real shapes captured from live probes:
+    - OpenAI 401:    body.code = "invalid_api_key" (string), body.type = "invalid_request_error"
+    - OpenRouter 401: body = {"message": "User not found.", "code": 401}  ← flat, code is INT
+    - OpenRouter 429: body = {"message": ..., "code": 429,
+                              "metadata": {"raw": ..., "provider_name": "...", "is_byok": false}}
+    - Grok 400 (auth!): body is a STRING, status is 400 (NOT 401)
+    - DeepSeek 401:  body.type = "authentication_error", body.code = "invalid_request_error"
+    """
+    body = getattr(exc, "body", None)
+    status = getattr(exc, "status_code", None)
+    request_id = getattr(exc, "request_id", None)
+
+    body_dict: Dict[str, Any] = {}
+    if isinstance(body, dict):
+        body_dict = body
+    elif isinstance(body, str):
+        # Grok edge case — body is the raw string message
+        body_dict = {"message": body}
+
+    raw_message: str = (body_dict.get("message") if isinstance(body_dict.get("message"), str) else None) or str(exc)
+    code = body_dict.get("code")
+    error_type = body_dict.get("type")
+
+    upstream: Optional[str] = None
+    metadata = body_dict.get("metadata") if isinstance(body_dict.get("metadata"), dict) else None
+
+    # OpenRouter wraps upstream errors. The upstream's verbatim message is
+    # FAR more useful than OR's "Provider returned error" wrapper.
+    if provider == "openrouter" and metadata:
+        if isinstance(metadata.get("provider_name"), str):
+            upstream = metadata["provider_name"]
+        if isinstance(metadata.get("raw"), str) and metadata["raw"]:
+            raw_message = metadata["raw"]
+
+    # ── Category resolution ────────────────────────────────────────
+    category = _category_from_openai_exc(exc, status=status, body_dict=body_dict, raw=raw_message)
+
+    # OpenAI string codes are the gold standard signal where present
+    if isinstance(code, str):
+        if code == "insufficient_quota":
+            category = ErrorCategory.CREDIT
+        elif code == "rate_limit_exceeded":
+            category = ErrorCategory.RATE_LIMIT
+        elif code == "context_length_exceeded":
+            category = ErrorCategory.BAD_REQUEST
+        elif code in ("model_not_found", "invalid_model"):
+            category = ErrorCategory.MODEL
+        elif code == "invalid_api_key":
+            category = ErrorCategory.AUTH
+
+    # Anthropic-style nested error type can appear when OR proxies Anthropic
+    if isinstance(error_type, str):
+        if error_type == "credit_balance_too_low":
+            category = ErrorCategory.CREDIT
+        elif error_type == "overloaded_error":
+            category = ErrorCategory.SERVER
+
+    # OpenRouter uses 402 for empty wallet; the openai SDK doesn't have a
+    # dedicated 402 exception so we land in APIStatusError — adjust here.
+    if status == 402:
+        category = ErrorCategory.CREDIT
+
+    # ── Retry-After ────────────────────────────────────────────────
+    retry_after = _retry_after_seconds(exc)
+
+    # ── User-facing message ────────────────────────────────────────
+    message = _compose_message(category, raw_message, provider, upstream, retry_after_seconds=retry_after)
+    actions = _default_actions(category, provider, upstream, metadata)
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category, upstream=upstream),
+        message=message,
+        provider=provider,
+        upstream=upstream,
+        http_status=status if isinstance(status, int) else None,
+        retry_after_seconds=retry_after,
+        actions=actions,
+        raw_message=_truncate(raw_message),
+        request_id=request_id if isinstance(request_id, str) else None,
+    )
+
+
+def _category_from_openai_exc(
+    exc: Exception,
+    *,
+    status: Optional[int],
+    body_dict: Dict[str, Any],
+    raw: str,
+) -> ErrorCategory:
+    """Map openai SDK exception type → category. Defensive for missing SDK."""
+    if openai is None:  # pragma: no cover
+        return _category_from_status(status)
+
+    if isinstance(exc, openai.AuthenticationError):
+        return ErrorCategory.AUTH
+    if isinstance(exc, openai.PermissionDeniedError):
+        # Often "billing-blocked" or "country-not-supported" — surface as AUTH-ish.
+        return ErrorCategory.AUTH
+    if isinstance(exc, openai.NotFoundError):
+        return ErrorCategory.MODEL
+    if isinstance(exc, openai.RateLimitError):
+        return ErrorCategory.RATE_LIMIT
+    if isinstance(exc, openai.BadRequestError):
+        # Grok returns 400 for auth — sniff body
+        lower = raw.lower()
+        if "api key" in lower or "api_key" in lower or "invalid_api_key" in lower:
+            return ErrorCategory.AUTH
+        if "context" in lower and ("length" in lower or "too long" in lower or "exceeds" in lower):
+            return ErrorCategory.BAD_REQUEST
+        if "model" in lower and ("not found" in lower or "not available" in lower or "does not exist" in lower):
+            return ErrorCategory.MODEL
+        if "blocked" in lower or "safety" in lower or "policy" in lower:
+            return ErrorCategory.BLOCKED
+        return ErrorCategory.BAD_REQUEST
+    if isinstance(exc, openai.InternalServerError):
+        return ErrorCategory.SERVER
+    if isinstance(exc, (openai.APIConnectionError, openai.APITimeoutError)):
+        return ErrorCategory.CONNECTION
+    if isinstance(exc, openai.APIStatusError):
+        return _category_from_status(status)
+
+    return _category_from_status(status)
+
+
+# ─── Anthropic ────────────────────────────────────────────────────────
+
+
+def _classify_anthropic(exc: Exception, provider: str) -> LLMErrorInfo:
+    """Anthropic SDK shape:
+        body = {
+          "type": "error",
+          "error": {"type": "authentication_error" | ..., "message": "..."},
+          "request_id": "..."
+        }
+    """
+    if anthropic is None:  # pragma: no cover
+        return _fallback_unknown(exc, provider)
+
+    body = getattr(exc, "body", None)
+    status = getattr(exc, "status_code", None)
+    request_id = getattr(exc, "request_id", None)
+
+    error_block = {}
+    if isinstance(body, dict):
+        if isinstance(body.get("error"), dict):
+            error_block = body["error"]
+        elif isinstance(body.get("type"), str):
+            error_block = body
+
+    a_type = error_block.get("type") if isinstance(error_block, dict) else None
+    raw_message = (
+        error_block.get("message")
+        if isinstance(error_block, dict) and isinstance(error_block.get("message"), str)
+        else str(exc)
+    )
+
+    # Map Anthropic's typed error names. These are richer than HTTP codes.
+    type_to_category = {
+        "authentication_error": ErrorCategory.AUTH,
+        "permission_error": ErrorCategory.AUTH,
+        "credit_balance_too_low": ErrorCategory.CREDIT,
+        "billing_error": ErrorCategory.CREDIT,
+        "rate_limit_error": ErrorCategory.RATE_LIMIT,
+        "overloaded_error": ErrorCategory.SERVER,
+        "api_error": ErrorCategory.SERVER,
+        "invalid_request_error": ErrorCategory.BAD_REQUEST,
+        "not_found_error": ErrorCategory.MODEL,
+    }
+
+    category: Optional[ErrorCategory] = None
+    if isinstance(a_type, str) and a_type in type_to_category:
+        category = type_to_category[a_type]
+    else:
+        # Fall back to SDK exception class
+        if isinstance(exc, anthropic.AuthenticationError):
+            category = ErrorCategory.AUTH
+        elif isinstance(exc, anthropic.PermissionDeniedError):
+            category = ErrorCategory.AUTH
+        elif isinstance(exc, anthropic.NotFoundError):
+            category = ErrorCategory.MODEL
+        elif isinstance(exc, anthropic.RateLimitError):
+            category = ErrorCategory.RATE_LIMIT
+        elif isinstance(exc, anthropic.InternalServerError):
+            category = ErrorCategory.SERVER
+        elif isinstance(exc, (anthropic.APIConnectionError, anthropic.APITimeoutError)):
+            category = ErrorCategory.CONNECTION
+        elif isinstance(exc, anthropic.BadRequestError):
+            lower = raw_message.lower()
+            if "prompt is too long" in lower or "maximum context length" in lower:
+                category = ErrorCategory.BAD_REQUEST
+            else:
+                category = ErrorCategory.BAD_REQUEST
+        else:
+            category = _category_from_status(status)
+
+    retry_after = _retry_after_seconds(exc)
+
+    actions = _default_actions(category, provider, upstream=None, metadata=None)
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category),
+        message=_compose_message(category, raw_message, provider, upstream=None, retry_after_seconds=retry_after),
+        provider=provider,
+        upstream=None,
+        http_status=status if isinstance(status, int) else None,
+        retry_after_seconds=retry_after,
+        actions=actions,
+        raw_message=_truncate(raw_message),
+        request_id=request_id if isinstance(request_id, str) else None,
+    )
+
+
+# ─── Gemini ────────────────────────────────────────────────────────────
+
+
+def _classify_httpx_status(exc: Exception, provider: Optional[str]) -> LLMErrorInfo:
+    """httpx.HTTPStatusError — covers Gemini and BytePlus paths.
+
+    Gemini body: {"error":{"code":400,"message":"...","status":"INVALID_ARGUMENT",
+                  "details":[{"reason":"API_KEY_INVALID",...}]}}
+    BytePlus body: {"error":{"code":"AuthenticationError","message":"..."}}
+    """
+    if httpx is None:  # pragma: no cover
+        return _fallback_unknown(exc, provider or "unknown")
+
+    response = getattr(exc, "response", None)
+    status = response.status_code if response is not None else None
+    text = response.text if response is not None else ""
+    body_dict = _safe_json(text)
+
+    err = body_dict.get("error") if isinstance(body_dict.get("error"), dict) else {}
+    raw_message = err.get("message") if isinstance(err.get("message"), str) else str(exc)
+
+    # Detect Gemini specifically by reason field
+    reason: Optional[str] = None
+    details = err.get("details") if isinstance(err.get("details"), list) else []
+    for d in details:
+        if isinstance(d, dict) and isinstance(d.get("reason"), str):
+            reason = d["reason"]
+            break
+
+    inferred_provider = provider or ("gemini" if reason or "generativelanguage" in text else "unknown")
+
+    # Gemini's REST API returns 400 for invalid keys — map by reason field
+    if reason == "API_KEY_INVALID":
+        category = ErrorCategory.AUTH
+    elif reason == "RESOURCE_EXHAUSTED":
+        category = ErrorCategory.RATE_LIMIT
+    elif reason == "PERMISSION_DENIED":
+        category = ErrorCategory.AUTH
+    else:
+        category = _category_from_status(status)
+        # BytePlus encodes auth errors via err.code = "AuthenticationError"
+        if isinstance(err.get("code"), str) and "auth" in err["code"].lower():
+            category = ErrorCategory.AUTH
+
+    retry_after = None
+    if response is not None:
+        ra = response.headers.get("retry-after")
+        if ra is not None:
+            try:
+                retry_after = int(float(ra))
+            except (ValueError, TypeError):
+                retry_after = None
+
+    actions = _default_actions(category, inferred_provider, upstream=None, metadata=None)
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category),
+        message=_compose_message(category, raw_message, inferred_provider, upstream=None),
+        provider=inferred_provider,
+        upstream=None,
+        http_status=status,
+        retry_after_seconds=retry_after,
+        actions=actions,
+        raw_message=_truncate(raw_message),
+    )
+
+
+def _classify_httpx_connection(exc: Exception, provider: Optional[str]) -> LLMErrorInfo:
+    raw = _truncate(str(exc))
+    return LLMErrorInfo(
+        category=ErrorCategory.CONNECTION,
+        title=_title_for(ErrorCategory.CONNECTION),
+        message=_compose_message(ErrorCategory.CONNECTION, raw, provider or "unknown", upstream=None),
+        provider=provider or "unknown",
+        raw_message=raw,
+    )
+
+
+def _classify_gemini_runtime(exc: Exception, provider: str) -> LLMErrorInfo:
+    """Gemini's GeminiAPIError — raised when the response shape signals an issue
+    that isn't an HTTP failure (e.g. promptFeedback.blockReason)."""
+    raw = str(exc)
+    lower = raw.lower()
+
+    if "blocked" in lower or "promptfeedback" in lower or "safety" in lower:
+        category = ErrorCategory.BLOCKED
+    else:
+        category = ErrorCategory.UNKNOWN
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category),
+        message=_compose_message(category, raw, provider, upstream=None),
+        provider=provider,
+        raw_message=_truncate(raw),
+        actions=_default_actions(category, provider, upstream=None, metadata=None),
+    )
+
+
+# ─── requests library (legacy callers) ────────────────────────────────
+
+
+def _classify_requests(exc: Exception, provider: Optional[str]) -> Optional[LLMErrorInfo]:
+    if requests is None:  # pragma: no cover
+        return None
+    if isinstance(exc, requests.exceptions.HTTPError):
+        response = exc.response
+        if response is not None:
+            status = response.status_code
+            try:
+                body = response.json()
+            except Exception:
+                body = {}
+            err = body.get("error") if isinstance(body.get("error"), dict) else {}
+            raw_message = err.get("message") if isinstance(err.get("message"), str) else response.text
+            return LLMErrorInfo(
+                category=_category_from_status(status),
+                title=_title_for(_category_from_status(status)),
+                message=_compose_message(_category_from_status(status), raw_message, provider or "unknown", upstream=None),
+                provider=provider or "unknown",
+                http_status=status,
+                raw_message=_truncate(raw_message),
+            )
+    if isinstance(exc, (requests.exceptions.ConnectionError, requests.exceptions.Timeout)):
+        raw = _truncate(str(exc))
+        return LLMErrorInfo(
+            category=ErrorCategory.CONNECTION,
+            title=_title_for(ErrorCategory.CONNECTION),
+            message=_compose_message(ErrorCategory.CONNECTION, raw, provider or "unknown", upstream=None),
+            provider=provider or "unknown",
+            raw_message=raw,
+        )
     return None
 
 
-def _message_from_status_code(status_code: int) -> str:
-    """Map HTTP status code to user-friendly message."""
-    if status_code == 401 or status_code == 403:
-        return MSG_AUTH
-    if status_code == 404:
-        return MSG_MODEL
-    if status_code == 400:
-        return MSG_CONFIG
-    if status_code == 429:
-        return MSG_RATE_LIMIT
-    if 500 <= status_code < 600:
-        return MSG_SERVICE
-    return MSG_GENERIC
+# ─── Helpers ──────────────────────────────────────────────────────────
+
+
+def _category_from_status(status: Optional[int]) -> ErrorCategory:
+    if status is None:
+        return ErrorCategory.UNKNOWN
+    if status in (401, 403):
+        return ErrorCategory.AUTH
+    if status == 402:
+        return ErrorCategory.CREDIT
+    if status == 404:
+        return ErrorCategory.MODEL
+    if status == 400:
+        return ErrorCategory.BAD_REQUEST
+    if status == 429:
+        return ErrorCategory.RATE_LIMIT
+    if 500 <= status < 600:
+        return ErrorCategory.SERVER
+    return ErrorCategory.UNKNOWN
+
+
+def _retry_after_seconds(exc: Exception) -> Optional[int]:
+    response = getattr(exc, "response", None)
+    if response is None:
+        return None
+    ra = None
+    try:
+        ra = response.headers.get("retry-after")
+    except AttributeError:
+        return None
+    if not ra:
+        return None
+    try:
+        return int(float(ra))
+    except (ValueError, TypeError):
+        return None
+
+
+_CATEGORY_TITLES: Dict[ErrorCategory, str] = {
+    ErrorCategory.AUTH: "Invalid API key",
+    ErrorCategory.CREDIT: "Out of credits",
+    ErrorCategory.RATE_LIMIT: "Rate limited",
+    ErrorCategory.QUOTA: "Quota exceeded",
+    ErrorCategory.MODEL: "Incorrect model id",
+    ErrorCategory.BAD_REQUEST: "Bad request",
+    ErrorCategory.BLOCKED: "Blocked by safety filter",
+    ErrorCategory.SERVER: "Provider service unavailable",
+    ErrorCategory.CONNECTION: "Cannot reach provider",
+    ErrorCategory.UNKNOWN: "AI service error",
+}
+
+
+# Categories where we suppress the leading title sentence — the raw
+# provider message is already self-explanatory or the title would just
+# repeat the upstream's words.
+_SKIP_TITLE_CATEGORIES = {ErrorCategory.UNKNOWN, ErrorCategory.BAD_REQUEST}
+
+
+def _title_for(category: ErrorCategory, *, upstream: Optional[str] = None) -> str:
+    """Short title — used for logging/metrics and for the leading sentence
+    of the user-facing chat message (see `_compose_message`)."""
+    base = _CATEGORY_TITLES.get(category, "AI service error")
+    if upstream and category in (ErrorCategory.RATE_LIMIT, ErrorCategory.SERVER, ErrorCategory.BLOCKED):
+        return f"{base} ({upstream})"
+    return base
+
+
+def _compose_message(
+    category: ErrorCategory,
+    raw_message: str,
+    provider: str,
+    upstream: Optional[str],
+    *,
+    retry_after_seconds: Optional[int] = None,
+) -> str:
+    """Build the single user-facing string shown in the chat error bubble.
+
+    Format:  "<Category title>. <Provider> [via <Upstream>]: <raw>. <action hint>."
+
+    The category title leads so users instantly know *what kind* of error
+    happened — important when the provider's raw text is terse (Anthropic
+    returns just `"model: claude-sonnet-4-5-2025092945"` for a bad model
+    id, which is meaningless without context). The raw provider text
+    follows so users see the exact upstream message. The action hint
+    closes when it adds value beyond what the raw already says.
+    """
+    raw = (raw_message or "").strip()
+    if raw.lower() == "none":
+        raw = ""
+    raw = _truncate(raw.rstrip("."), limit=400)
+    if not raw:
+        raw = _FALLBACK_BODY_BY_CATEGORY.get(category, "an error occurred")
+
+    # Lead with category title (e.g. "Incorrect model id.") unless the
+    # category is too vague to title meaningfully.
+    if category in _SKIP_TITLE_CATEGORIES:
+        lead = ""
+    else:
+        lead = f"{_title_for(category, upstream=upstream)}."
+
+    name = _PROVIDER_DISPLAY.get(provider, "")
+    if name:
+        prefix = f"{name} (via {upstream})" if upstream else name
+        provider_part = f"{prefix}: {raw}"
+    else:
+        provider_part = raw
+
+    body = f"{lead} {provider_part}" if lead else provider_part
+    return _append_hint(body, category, provider, retry_after_seconds, raw.lower())
+
+
+def _append_hint(
+    body: str,
+    category: ErrorCategory,
+    provider: str,
+    retry_after: Optional[int],
+    raw_lower: str,
+) -> str:
+    """Append a short action hint, suppressed when the provider's own raw
+    text already covers it (avoids "...add your own key. Try again shortly.")."""
+    base = body.rstrip(".")
+
+    if category == ErrorCategory.AUTH:
+        if "key" in raw_lower or "settings" in raw_lower:
+            return f"{base}."
+        return f"{base}. Check your API key in Settings."
+
+    if category == ErrorCategory.CREDIT:
+        if any(s in raw_lower for s in ("billing", "credit", "top up", "topup")):
+            return f"{base}."
+        if provider == "openrouter":
+            return f"{base}. Top up at https://openrouter.ai/credits."
+        if provider == "openai":
+            return f"{base}. Manage billing at https://platform.openai.com/account/billing."
+        if provider == "anthropic":
+            return f"{base}. Manage billing at https://console.anthropic.com/settings/billing."
+        return f"{base}."
+
+    if category == ErrorCategory.RATE_LIMIT:
+        if retry_after:
+            return f"{base}. Try again in {retry_after}s."
+        if any(s in raw_lower for s in (
+            "byok", "your own key", "openrouter.ai/settings", "retry", "wait", "try again",
+        )):
+            return f"{base}."
+        return f"{base}. Try again shortly."
+
+    if category == ErrorCategory.QUOTA:
+        if "billing" in raw_lower or "usage" in raw_lower:
+            return f"{base}."
+        if provider == "openai":
+            return f"{base}. Manage usage at https://platform.openai.com/usage."
+        return f"{base}."
+
+    if category == ErrorCategory.MODEL:
+        if "settings" in raw_lower:
+            return f"{base}."
+        return f"{base}. Use a correct model in Settings."
+
+    if category == ErrorCategory.BLOCKED:
+        return f"{base}. Edit your prompt and retry."
+
+    if category == ErrorCategory.SERVER:
+        if "try again" in raw_lower or "retry" in raw_lower:
+            return f"{base}."
+        return f"{base}. Try again later."
+
+    if category == ErrorCategory.CONNECTION:
+        if provider == "remote":
+            return f"{base}. Check that Ollama is running."
+        if "network" in raw_lower or "connection" in raw_lower:
+            return f"{base}."
+        return f"{base}. Check your network connection."
+
+    # BAD_REQUEST / UNKNOWN — raw is the most informative thing we can show
+    return f"{base}."
+
+
+def _default_actions(
+    category: ErrorCategory,
+    provider: str,
+    upstream: Optional[str],
+    metadata: Optional[Dict[str, Any]],
+) -> List[ErrorAction]:
+    """Per-(category, provider) action affordances.
+
+    Keep this list short — each action is a click target the user is more
+    likely to actually want than just dismissing the error.
+    """
+    actions: List[ErrorAction] = []
+
+    if category == ErrorCategory.CREDIT:
+        if provider == "openrouter":
+            actions.append(ErrorAction(label="Top up credits", url="https://openrouter.ai/credits"))
+        elif provider == "openai":
+            actions.append(ErrorAction(label="Manage billing", url="https://platform.openai.com/account/billing"))
+        elif provider == "anthropic":
+            actions.append(ErrorAction(label="Manage billing", url="https://console.anthropic.com/settings/billing"))
+        actions.append(ErrorAction(label="Open settings", action="open_settings_model"))
+
+    elif category == ErrorCategory.RATE_LIMIT:
+        if provider == "openrouter" and metadata and metadata.get("is_byok") is False:
+            # Free-tier user — point at OR integrations page for BYOK
+            actions.append(ErrorAction(label="Add your own key", url="https://openrouter.ai/settings/integrations"))
+        actions.append(ErrorAction(label="Open settings", action="open_settings_model"))
+
+    elif category == ErrorCategory.QUOTA:
+        if provider == "openai":
+            actions.append(ErrorAction(label="Manage usage", url="https://platform.openai.com/usage"))
+
+    return actions
+
+
+def _has_action(info: LLMErrorInfo, action_value: str) -> bool:
+    return any(a.action == action_value for a in info.actions)
+
+
+def _safe_json(text: str) -> Dict[str, Any]:
+    if not text:
+        return {}
+    try:
+        import json
+        result = json.loads(text)
+        return result if isinstance(result, dict) else {}
+    except Exception:
+        return {}
+
+
+def _truncate(s: Optional[str], limit: int = 500) -> str:
+    if s is None:
+        return ""
+    s = str(s)
+    if len(s) <= limit:
+        return s
+    return s[:limit].rstrip() + "…"
+
+
+def _fallback_unknown(exc: Exception, provider: str) -> LLMErrorInfo:
+    raw = _truncate(str(exc)) or "AI service error"
+    return LLMErrorInfo(
+        category=ErrorCategory.UNKNOWN,
+        title="AI service error",
+        message=raw,
+        provider=provider,
+        raw_message=raw,
+    )
diff --git a/agent_core/core/impl/llm/interface.py b/agent_core/core/impl/llm/interface.py
index 8b01bf83..67d2cb54 100644
--- a/agent_core/core/impl/llm/interface.py
+++ b/agent_core/core/impl/llm/interface.py
@@ -29,7 +29,7 @@
     get_cache_config,
     get_cache_metrics,
 )
-from agent_core.core.impl.llm.errors import LLMConsecutiveFailureError
+from agent_core.core.impl.llm.errors import LLMConsecutiveFailureError, classify_llm_error
 from agent_core.core.hooks import (
     GetTokenCountHook,
     SetTokenCountHook,
@@ -384,8 +384,14 @@ def _generate_response_sync(
 
             # Check if response is empty and provide diagnostics
             if not content:
+                # Prefer the classified rich message (provider + upstream +
+                # raw + action hint inline) over the bare exception string.
+                # This is what the user actually sees in the chat bubble.
+                error_info = response.get("error_info_obj")
                 error_msg = response.get("error", "")
-                if error_msg:
+                if error_info is not None:
+                    error_detail = error_info.message
+                elif error_msg:
                     error_detail = f"LLM provider returned error: {error_msg}"
                 else:
                     error_detail = (
@@ -402,7 +408,14 @@ def _generate_response_sync(
                     f"[LLM CONSECUTIVE FAILURE] Count: {self._consecutive_failures}/{self._max_consecutive_failures}"
                 )
                 if self._consecutive_failures >= self._max_consecutive_failures:
-                    raise LLMConsecutiveFailureError(self._consecutive_failures)
+                    # Attach the underlying classified info so the agent_base
+                    # error handler can show the *cause* of the 5 failures
+                    # (e.g. "rate-limited on Google AI Studio") instead of a
+                    # meta-message about retry counts.
+                    raise LLMConsecutiveFailureError(
+                        self._consecutive_failures,
+                        last_error_info=error_info,
+                    )
                 raise RuntimeError(error_detail)
 
             # Success - reset consecutive failure counter
@@ -428,7 +441,17 @@ def _generate_response_sync(
                 f"[LLM CONSECUTIVE FAILURE] Count: {self._consecutive_failures}/{self._max_consecutive_failures} | Error: {e}"
             )
             if self._consecutive_failures >= self._max_consecutive_failures:
-                raise LLMConsecutiveFailureError(self._consecutive_failures, last_error=e) from e
+                # Classify on the way out so the fatal-failure handler can
+                # surface the cause, not just the count.
+                try:
+                    info = classify_llm_error(e, provider=self.provider, model=self.model)
+                except Exception:
+                    info = None
+                raise LLMConsecutiveFailureError(
+                    self._consecutive_failures,
+                    last_error=e,
+                    last_error_info=info,
+                ) from e
             raise
 
     @profile("llm_generate_response", OperationCategory.LLM)
@@ -1343,6 +1366,18 @@ def _generate_ollama(self, system_prompt: str | None, user_prompt: str) -> Dict[
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[OLLAMA_ERROR] {error_str}")
         else:
@@ -1464,6 +1499,18 @@ def _generate_gemini(
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[GEMINI_ERROR] {error_str}")
         else:
@@ -1701,6 +1748,18 @@ def _generate_byteplus_standard(
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[BYTEPLUS_ERROR] {error_str}")
         else:
@@ -1848,6 +1907,18 @@ def _generate_anthropic(
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[ANTHROPIC_ERROR] {error_str}")
         else:
diff --git a/agent_core/core/models/connection_tester.py b/agent_core/core/models/connection_tester.py
index 761727a2..e315215e 100644
--- a/agent_core/core/models/connection_tester.py
+++ b/agent_core/core/models/connection_tester.py
@@ -1,5 +1,14 @@
 # -*- coding: utf-8 -*-
-"""Connection tester for validating provider API keys."""
+"""Connection tester for validating provider API keys and model ids.
+
+When `model` is provided, each tester attempts a tiny chat-completion (or
+equivalent) against that exact model — so a typo in the model id is caught
+at test time, not at first real call. When `model` is omitted we fall back
+to a known-good default model from connection_test_models.json.
+
+On failure we run the underlying exception through `classify_llm_error` so
+the test result message reads exactly like a real LLM error in the chat.
+"""
 
 from typing import Dict, Any, Optional
 import httpx
@@ -11,22 +20,24 @@ def test_provider_connection(
     provider: str,
     api_key: Optional[str] = None,
     base_url: Optional[str] = None,
-    timeout: float = 10.0,
+    timeout: float = 15.0,
+    model: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Test if a provider's API key is valid by making a minimal API call.
+    """Test if a provider's API key (and optionally model id) is valid.
 
     Args:
-        provider: The LLM provider name (openai, gemini, anthropic, byteplus, remote)
-        api_key: The API key to test. If None, will check if connection is possible.
-        base_url: Optional base URL override (for byteplus/remote providers)
-        timeout: Request timeout in seconds
+        provider: The LLM provider name.
+        api_key: The API key to test.
+        base_url: Optional base URL override.
+        timeout: Request timeout in seconds.
+        model: When provided, the tester verifies this exact model is
+            reachable. Catches typos in the model id (e.g.
+            "claude-sonnet-4-5-2025092945" vs the real
+            "claude-sonnet-4-5-20250929") that would otherwise pass an
+            auth-only test and only fail at first real call.
 
     Returns:
-        Dictionary with:
-        - success: bool indicating if connection succeeded
-        - message: str with success/failure message
-        - provider: str provider name
-        - error: Optional[str] error details if failed
+        Dictionary with success/message/provider/error.
     """
     if provider not in PROVIDER_CONFIG:
         return {
@@ -40,26 +51,26 @@ def test_provider_connection(
 
     try:
         if provider == "openai":
-            return _test_openai(api_key, timeout)
+            return _test_openai(api_key, timeout, model)
         elif provider == "anthropic":
-            return _test_anthropic(api_key, timeout)
+            return _test_anthropic(api_key, timeout, model)
         elif provider == "gemini":
-            return _test_gemini(api_key, timeout)
+            return _test_gemini(api_key, timeout, model)
         elif provider == "byteplus":
             url = base_url or cfg.default_base_url
-            return _test_byteplus(api_key, url, timeout)
+            return _test_byteplus(api_key, url, timeout, model)
         elif provider == "remote":
             url = base_url or cfg.default_base_url
             return _test_remote(url, timeout)
         elif provider == "grok":
             url = cfg.default_base_url
-            return _test_grok(api_key, url, timeout)
+            return _test_grok(api_key, url, timeout, model)
         elif provider == "openrouter":
             url = base_url or cfg.default_base_url
-            return _test_openrouter(api_key, url, timeout)
+            return _test_openrouter(api_key, url, timeout, model)
         elif provider in ("minimax", "deepseek", "moonshot"):
             url = cfg.default_base_url
-            return _test_openai_compat(provider, api_key, url, timeout)
+            return _test_openai_compat(provider, api_key, url, timeout, model)
         else:
             return {
                 "success": False,
@@ -76,356 +87,346 @@ def test_provider_connection(
         }
 
 
-def _test_openai(api_key: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test OpenAI API connection."""
-    if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for OpenAI",
-            "provider": "openai",
-            "error": "Missing API key",
-        }
+# ─── Helpers ──────────────────────────────────────────────────────────
 
-    try:
-        # Use models endpoint - lightweight call to verify API key
-        with httpx.Client(timeout=timeout) as client:
-            response = client.get(
-                "https://api.openai.com/v1/models",
-                headers={"Authorization": f"Bearer {api_key}"},
-            )
 
-        if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to OpenAI API",
-                "provider": "openai",
-            }
-        elif response.status_code == 401:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "openai",
-                "error": "Authentication failed - check your API key",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "openai",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
+def _classified_error_result(exc: Exception, provider: str, model: Optional[str]) -> Dict[str, Any]:
+    """Run an exception through the classifier and return a failure result
+    with the rich message — same format the chat sees for real LLM errors."""
+    try:
+        from agent_core.core.impl.llm.errors import classify_llm_error
+        info = classify_llm_error(exc, provider=provider, model=model)
         return {
             "success": False,
-            "message": "Connection timed out",
-            "provider": "openai",
-            "error": "Request timed out - check your network connection",
+            "message": info.message,
+            "provider": provider,
+            "error": info.message,
         }
-    except httpx.RequestError as e:
+    except Exception:  # pragma: no cover — classifier must never break test
         return {
             "success": False,
-            "message": "Network error",
-            "provider": "openai",
-            "error": str(e),
+            "message": str(exc),
+            "provider": provider,
+            "error": str(exc),
         }
 
 
-def _test_anthropic(api_key: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test Anthropic API connection."""
+def _resolve_test_model(provider: str, model: Optional[str], fallback: str) -> str:
+    """Use the user's model when provided; otherwise pull the default test
+    model from connection_test_models.json (auth-only validation)."""
+    if model:
+        return model
+    try:
+        from app.config import get_connection_test_model
+        configured = get_connection_test_model(provider)
+        if configured:
+            return configured
+    except Exception:
+        pass
+    return fallback
+
+
+def _success(provider: str, model: Optional[str]) -> Dict[str, Any]:
+    detail = f" with model {model}" if model else ""
+    return {
+        "success": True,
+        "message": f"Successfully connected to {_DISPLAY.get(provider, provider)} API{detail}.",
+        "provider": provider,
+    }
+
+
+_DISPLAY = {
+    "openai": "OpenAI",
+    "anthropic": "Anthropic",
+    "gemini": "Google Gemini",
+    "byteplus": "BytePlus",
+    "deepseek": "DeepSeek",
+    "moonshot": "Moonshot",
+    "minimax": "MiniMax",
+    "grok": "Grok (xAI)",
+    "openrouter": "OpenRouter",
+    "remote": "Ollama",
+}
+
+
+# ─── OpenAI / OpenAI-compat ───────────────────────────────────────────
+
+
+def _openai_compat_chat_test(
+    *,
+    provider: str,
+    api_key: Optional[str],
+    base_url: Optional[str],
+    model: str,
+    timeout: float,
+) -> Dict[str, Any]:
+    """Hit /chat/completions with the user's model. The response tells us:
+        200/400/422 → key + model OK
+        401         → bad key
+        404         → bad model
+        402         → no credits (key valid)
+        429         → rate limited (key valid)
+    For all failure shapes, we surface the classifier's rich message.
+    """
     if not api_key:
         return {
             "success": False,
-            "message": "API key is required for Anthropic",
-            "provider": "anthropic",
+            "message": f"API key is required for {_DISPLAY.get(provider, provider)}",
+            "provider": provider,
             "error": "Missing API key",
         }
-
     try:
-        # Use a minimal messages request to verify API key
-        # We send an invalid request that will fail fast but verify auth
-        from app.config import get_connection_test_model, get_connection_test_config
-        test_model = get_connection_test_model("anthropic") or "claude-haiku-4-5-20251001"
-        test_config = get_connection_test_config("anthropic")
+        from openai import OpenAI
+        client = OpenAI(
+            api_key=api_key,
+            base_url=base_url or None,
+            timeout=timeout,
+            max_retries=0,
+        )
+        client.chat.completions.create(
+            model=model,
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=1,
+        )
+        return _success(provider, model)
+    except Exception as exc:
+        # 422 BadRequest with a "messages" issue still means auth+model worked.
+        # Classify, and if it's a BAD_REQUEST not about the model, treat as success.
+        from agent_core.core.impl.llm.errors import classify_llm_error, ErrorCategory
+        try:
+            info = classify_llm_error(exc, provider=provider, model=model)
+            if info.category in (ErrorCategory.AUTH, ErrorCategory.MODEL, ErrorCategory.CREDIT):
+                return {
+                    "success": False,
+                    "message": info.message,
+                    "provider": provider,
+                    "error": info.message,
+                }
+            # RATE_LIMIT, SERVER, BAD_REQUEST, etc. — auth+model are likely fine.
+            return _success(provider, model)
+        except Exception:
+            return _classified_error_result(exc, provider, model)
+
+
+def _test_openai(api_key: Optional[str], timeout: float, model: Optional[str]) -> Dict[str, Any]:
+    if model:
+        return _openai_compat_chat_test(
+            provider="openai", api_key=api_key, base_url=None, model=model, timeout=timeout,
+        )
+    # No model specified → just verify the key with /models list (cheaper).
+    if not api_key:
+        return {"success": False, "message": "API key is required for OpenAI",
+                "provider": "openai", "error": "Missing API key"}
+    try:
         with httpx.Client(timeout=timeout) as client:
-            response = client.post(
-                "https://api.anthropic.com/v1/messages",
-                headers={
-                    "x-api-key": api_key,
-                    "anthropic-version": "2023-06-01",
-                    "content-type": "application/json",
-                },
-                json={
-                    "model": test_model,
-                    "max_tokens": test_config.get("max_tokens", 1),
-                    "messages": [{"role": "user", "content": "hi"}],
-                },
+            response = client.get(
+                "https://api.openai.com/v1/models",
+                headers={"Authorization": f"Bearer {api_key}"},
             )
+        if response.status_code == 200:
+            return _success("openai", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "openai", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "openai", None)
+
 
-        # 200 means success (actual completion - shouldn't happen with max_tokens=1 but possible)
-        # 400 with specific error also indicates valid auth
+def _test_openai_compat(
+    provider: str, api_key: Optional[str], base_url: str, timeout: float, model: Optional[str],
+) -> Dict[str, Any]:
+    if model:
+        return _openai_compat_chat_test(
+            provider=provider, api_key=api_key, base_url=base_url, model=model, timeout=timeout,
+        )
+    # No model → /models list (auth-only).
+    display = _DISPLAY.get(provider, provider)
+    if not api_key:
+        return {"success": False, "message": f"API key is required for {display}",
+                "provider": provider, "error": "Missing API key"}
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(
+                f"{base_url.rstrip('/')}/models",
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
         if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to Anthropic API",
-                "provider": "anthropic",
-            }
-        elif response.status_code == 401:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "anthropic",
-                "error": "Authentication failed - check your API key",
-            }
-        elif response.status_code == 400:
-            # Bad request but auth succeeded
-            return {
-                "success": True,
-                "message": "Successfully connected to Anthropic API",
-                "provider": "anthropic",
-            }
-        elif response.status_code == 529:
-            # Overloaded but auth succeeded
-            return {
-                "success": True,
-                "message": "Connected to Anthropic API (service currently overloaded)",
-                "provider": "anthropic",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "anthropic",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "anthropic",
-            "error": "Request timed out - check your network connection",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "anthropic",
-            "error": str(e),
-        }
+            return _success(provider, None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": provider, "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, provider, None)
+
 
+# ─── Anthropic ────────────────────────────────────────────────────────
 
-def _test_gemini(api_key: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test Google Gemini API connection."""
+
+def _test_anthropic(api_key: Optional[str], timeout: float, model: Optional[str]) -> Dict[str, Any]:
     if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for Gemini",
-            "provider": "gemini",
-            "error": "Missing API key",
-        }
+        return {"success": False, "message": "API key is required for Anthropic",
+                "provider": "anthropic", "error": "Missing API key"}
 
+    test_model = _resolve_test_model("anthropic", model, fallback="claude-haiku-4-5-20251001")
+
+    try:
+        from anthropic import Anthropic
+        client = Anthropic(api_key=api_key, timeout=timeout, max_retries=0)
+        client.messages.create(
+            model=test_model,
+            max_tokens=1,
+            messages=[{"role": "user", "content": "hi"}],
+        )
+        return _success("anthropic", model)
+    except Exception as exc:
+        from agent_core.core.impl.llm.errors import classify_llm_error, ErrorCategory
+        try:
+            info = classify_llm_error(exc, provider="anthropic", model=test_model)
+            # Auth, missing model, or credit issues are real failures.
+            # 400 BadRequest about the prompt itself is fine (auth+model OK).
+            if info.category in (ErrorCategory.AUTH, ErrorCategory.MODEL, ErrorCategory.CREDIT):
+                return {
+                    "success": False,
+                    "message": info.message,
+                    "provider": "anthropic",
+                    "error": info.message,
+                }
+            return _success("anthropic", model)
+        except Exception:
+            return _classified_error_result(exc, "anthropic", model)
+
+
+# ─── Gemini ────────────────────────────────────────────────────────────
+
+
+def _test_gemini(api_key: Optional[str], timeout: float, model: Optional[str]) -> Dict[str, Any]:
+    if not api_key:
+        return {"success": False, "message": "API key is required for Gemini",
+                "provider": "gemini", "error": "Missing API key"}
+    if model:
+        # Verify the specific model via models/{name}.
+        url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}?key={api_key}"
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                response = client.get(url)
+            if response.status_code == 200:
+                return _success("gemini", model)
+            response.raise_for_status()
+            return {"success": False, "message": f"API returned status {response.status_code}",
+                    "provider": "gemini", "error": response.text[:300]}
+        except Exception as exc:
+            return _classified_error_result(exc, "gemini", model)
+    # No model → list endpoint (auth-only).
     try:
-        # Use models list endpoint to verify API key
         with httpx.Client(timeout=timeout) as client:
             response = client.get(
                 f"https://generativelanguage.googleapis.com/v1/models?key={api_key}",
             )
-
         if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to Google Gemini API",
-                "provider": "gemini",
-            }
-        elif response.status_code == 400 or response.status_code == 403:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "gemini",
-                "error": "Authentication failed - check your API key",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "gemini",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "gemini",
-            "error": "Request timed out - check your network connection",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "gemini",
-            "error": str(e),
-        }
+            return _success("gemini", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "gemini", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "gemini", None)
+
+
+# ─── BytePlus ─────────────────────────────────────────────────────────
 
 
 def _test_byteplus(
-    api_key: Optional[str], base_url: Optional[str], timeout: float
+    api_key: Optional[str], base_url: Optional[str], timeout: float, model: Optional[str],
 ) -> Dict[str, Any]:
-    """Test BytePlus API connection."""
     if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for BytePlus",
-            "provider": "byteplus",
-            "error": "Missing API key",
-        }
-
+        return {"success": False, "message": "API key is required for BytePlus",
+                "provider": "byteplus", "error": "Missing API key"}
     url = base_url or "https://ark.ap-southeast.bytepluses.com/api/v3"
-
+    if model:
+        # Verify via tiny chat completion.
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                response = client.post(
+                    f"{url.rstrip('/')}/chat/completions",
+                    headers={
+                        "Authorization": f"Bearer {api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json={
+                        "model": model,
+                        "messages": [{"role": "user", "content": "hi"}],
+                        "max_tokens": 1,
+                    },
+                )
+            if response.status_code in (200, 400, 422):
+                # 200 = both OK. 400/422 = auth+model OK, request quirk only.
+                return _success("byteplus", model)
+            response.raise_for_status()
+            return {"success": False, "message": f"API returned status {response.status_code}",
+                    "provider": "byteplus", "error": response.text[:300]}
+        except Exception as exc:
+            return _classified_error_result(exc, "byteplus", model)
+    # No model → /models list.
     try:
-        # BytePlus uses OpenAI-compatible API, test with models endpoint
         with httpx.Client(timeout=timeout) as client:
             response = client.get(
                 f"{url.rstrip('/')}/models",
                 headers={"Authorization": f"Bearer {api_key}"},
             )
-
         if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to BytePlus API",
-                "provider": "byteplus",
-            }
-        elif response.status_code == 401:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "byteplus",
-                "error": "Authentication failed - check your API key",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "byteplus",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "byteplus",
-            "error": "Request timed out - check your network connection",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "byteplus",
-            "error": str(e),
-        }
+            return _success("byteplus", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "byteplus", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "byteplus", None)
+
+
+# ─── Remote (Ollama) ──────────────────────────────────────────────────
 
 
 def _test_remote(base_url: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test remote/Ollama connection (no API key required)."""
+    """No API key required; the UI already validates Ollama models via
+    the /api/tags dropdown, so this stays auth-equivalent."""
     url = base_url or "http://localhost:11434"
-
     try:
-        # Ollama uses /api/tags to list models
         with httpx.Client(timeout=timeout) as client:
             response = client.get(f"{url.rstrip('/')}/api/tags")
-
         if response.status_code == 200:
             models = [m["name"] for m in response.json().get("models", [])]
             if models:
                 message = f"Connected! {len(models)} model(s) available: {', '.join(models)}"
             else:
                 message = "Connected to Ollama, but no models downloaded yet. Use '+ Download New Model' to get one."
-            return {
-                "success": True,
-                "message": message,
-                "provider": "remote",
-                "models": models,
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"Ollama returned status {response.status_code}",
-                "provider": "remote",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "remote",
-            "error": f"Could not connect to Ollama at {url}. Is it running?",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "remote",
-            "error": f"Could not connect to {url}: {str(e)}",
-        }
-
-
-def _test_openai_compat(
-    provider: str, api_key: Optional[str], base_url: str, timeout: float
-) -> Dict[str, Any]:
-    """Test an OpenAI-compatible API (MiniMax, DeepSeek, Moonshot)."""
-    names = {"minimax": "MiniMax", "deepseek": "DeepSeek", "moonshot": "Moonshot", "grok": "Grok (xAI)"}
-    display = names.get(provider, provider)
-
-    if not api_key:
-        return {
-            "success": False,
-            "message": f"API key is required for {display}",
-            "provider": provider,
-            "error": "Missing API key",
-        }
+            return {"success": True, "message": message, "provider": "remote", "models": models}
+        return {"success": False, "message": f"Ollama returned status {response.status_code}",
+                "provider": "remote", "error": response.text[:200] if response.text else "Unknown error"}
+    except Exception as exc:
+        return _classified_error_result(exc, "remote", None)
 
-    try:
-        with httpx.Client(timeout=timeout) as client:
-            response = client.get(
-                f"{base_url.rstrip('/')}/models",
-                headers={"Authorization": f"Bearer {api_key}"},
-            )
 
-        if response.status_code == 200:
-            return {"success": True, "message": f"Successfully connected to {display} API", "provider": provider}
-        elif response.status_code in (401, 403):
-            return {"success": False, "message": "Invalid API key", "provider": provider, "error": f"Authentication failed (HTTP {response.status_code}) - check your API key"}
-        else:
-            return {"success": False, "message": f"API returned status {response.status_code}", "provider": provider, "error": response.text[:300] if response.text else "Unknown error"}
-    except httpx.TimeoutException:
-        return {"success": False, "message": "Connection timed out", "provider": provider, "error": "Request timed out - check your network connection"}
-    except httpx.RequestError as e:
-        return {"success": False, "message": "Network error", "provider": provider, "error": str(e)}
+# ─── OpenRouter ───────────────────────────────────────────────────────
 
 
 def _test_openrouter(
-    api_key: Optional[str], base_url: str, timeout: float
+    api_key: Optional[str], base_url: str, timeout: float, model: Optional[str],
 ) -> Dict[str, Any]:
-    """Test OpenRouter API connection.
-
-    Uses /api/v1/auth/key (auth-required) so we both validate the key and
-    surface the user's credit balance in the success message — that's the
-    information OpenRouter users care about most.
-    """
     if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for OpenRouter",
-            "provider": "openrouter",
-            "error": "Missing API key",
-        }
-
+        return {"success": False, "message": "API key is required for OpenRouter",
+                "provider": "openrouter", "error": "Missing API key"}
+    if model:
+        # Verify auth + model + credits via tiny chat completion. OR returns
+        # 401 (bad key), 402 (no credits), 404 (bad model slug), or 200/4xx
+        # depending on upstream. Classifier handles them all.
+        return _openai_compat_chat_test(
+            provider="openrouter", api_key=api_key, base_url=base_url, model=model, timeout=timeout,
+        )
+    # No model → /auth/key (auth + balance only).
     try:
         with httpx.Client(timeout=timeout) as client:
             response = client.get(
                 f"{base_url.rstrip('/')}/auth/key",
                 headers={"Authorization": f"Bearer {api_key}"},
             )
-
         if response.status_code == 200:
             data = response.json().get("data", {}) or {}
             limit = data.get("limit")
@@ -435,59 +436,29 @@ def _test_openrouter(
                 msg = f"Connected to OpenRouter ({label}) — unlimited credits"
             else:
                 remaining = max(0.0, float(limit) - float(usage or 0.0))
-                msg = (
-                    f"Connected to OpenRouter ({label}) — "
-                    f"${remaining:.2f} of ${float(limit):.2f} remaining"
-                )
-            return {
-                "success": True,
-                "message": msg,
-                "provider": "openrouter",
-            }
-        elif response.status_code in (401, 403):
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "openrouter",
-                "error": "Authentication failed - check your OpenRouter API key",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "openrouter",
-                "error": response.text[:300] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "openrouter",
-            "error": "Request timed out - check your network connection",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "openrouter",
-            "error": str(e),
-        }
+                msg = (f"Connected to OpenRouter ({label}) — "
+                       f"${remaining:.2f} of ${float(limit):.2f} remaining")
+            return {"success": True, "message": msg, "provider": "openrouter"}
+        if response.status_code in (401, 403):
+            return {"success": False, "message": "Invalid API key",
+                    "provider": "openrouter",
+                    "error": "Authentication failed - check your OpenRouter API key"}
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "openrouter", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "openrouter", None)
 
 
-def _test_grok(api_key: Optional[str], base_url: str, timeout: float) -> Dict[str, Any]:
-    """Test xAI Grok API connection using a minimal chat completion request.
+# ─── Grok ─────────────────────────────────────────────────────────────
 
-    xAI returns 403 on the /models endpoint even for valid keys, so we use
-    a minimal chat completions call instead.
-    """
-    if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for Grok (xAI)",
-            "provider": "grok",
-            "error": "Missing API key",
-        }
 
+def _test_grok(
+    api_key: Optional[str], base_url: str, timeout: float, model: Optional[str],
+) -> Dict[str, Any]:
+    if not api_key:
+        return {"success": False, "message": "API key is required for Grok (xAI)",
+                "provider": "grok", "error": "Missing API key"}
+    test_model = _resolve_test_model("grok", model, fallback="grok-3")
     try:
         with httpx.Client(timeout=timeout) as client:
             response = client.post(
@@ -497,22 +468,18 @@ def _test_grok(api_key: Optional[str], base_url: str, timeout: float) -> Dict[st
                     "Content-Type": "application/json",
                 },
                 json={
-                    "model": "grok-3",
+                    "model": test_model,
                     "max_tokens": 1,
                     "messages": [{"role": "user", "content": "hi"}],
                 },
             )
-
-        if response.status_code in (200, 400, 403, 422):
-            # 200 = success
-            # 400/422 = bad request but auth passed
-            # 403 = model tier restriction but key is valid
-            return {"success": True, "message": "Successfully connected to Grok (xAI) API", "provider": "grok"}
-        elif response.status_code == 401:
-            return {"success": False, "message": "Invalid API key", "provider": "grok", "error": "Authentication failed - check your xAI API key"}
-        else:
-            return {"success": False, "message": f"API returned status {response.status_code}", "provider": "grok", "error": response.text[:300] if response.text else "Unknown error"}
-    except httpx.TimeoutException:
-        return {"success": False, "message": "Connection timed out", "provider": "grok", "error": "Request timed out - check your network connection"}
-    except httpx.RequestError as e:
-        return {"success": False, "message": "Network error", "provider": "grok", "error": str(e)}
+        if response.status_code == 200:
+            return _success("grok", model)
+        if response.status_code in (400, 422) and model is None:
+            # Hardcoded test model probably hit a tier restriction; auth still OK.
+            return _success("grok", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "grok", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "grok", model)
diff --git a/app/agent_base.py b/app/agent_base.py
index 3ffbfe4f..28500d6a 100644
--- a/app/agent_base.py
+++ b/app/agent_base.py
@@ -50,7 +50,11 @@
 
 from app.internal_action_interface import InternalActionInterface
 from app.llm import LLMInterface, LLMCallType
-from agent_core.core.impl.llm.errors import classify_llm_error, LLMConsecutiveFailureError
+from agent_core.core.impl.llm.errors import (
+    classify_llm_error,
+    classify_llm_error_message,
+    LLMConsecutiveFailureError,
+)
 from app.vlm_interface import VLMInterface
 from app.database_interface import DatabaseInterface
 from app.logger import logger
@@ -1297,20 +1301,43 @@ async def _handle_react_error(
         if not session_to_use or not self.event_stream_manager:
             return
 
-        # Get user-friendly error message
-        user_message = classify_llm_error(error)
-
-        # Fatal LLM errors must not re-queue the task - that causes infinite retry loops
-        # Walk the full exception chain (__cause__, __context__) to detect wrapped errors
+        # Walk the exception chain (__cause__, __context__) to detect the
+        # fatal-LLM case. We need the LLMConsecutiveFailureError to surface
+        # the *cause* of the 5 failures (e.g. "rate-limited on Google AI
+        # Studio"), not the meta-message about retry counts.
         is_fatal_llm_error = False
+        fatal_exc: LLMConsecutiveFailureError | None = None
+        seen: set[int] = set()
         exc: BaseException | None = error
-        while exc is not None:
+        while exc is not None and id(exc) not in seen:
+            seen.add(id(exc))
             if isinstance(exc, LLMConsecutiveFailureError):
                 is_fatal_llm_error = True
+                fatal_exc = exc
                 break
-            exc = exc.__cause__ or exc.__context__
-            if exc is error:  # prevent infinite loop on circular chains
+            cause = exc.__cause__ or exc.__context__
+            if cause is None or cause is exc:
                 break
+            exc = cause
+
+        # Compose the user-facing message. For the fatal case we lead with
+        # the cause (already a rich detailed string from the classifier)
+        # and prefix the abort context. For non-fatal cases the RuntimeError
+        # we receive was already constructed from `info.message` upstream
+        # in interface.py, so str(error) IS the rich text — classify is a
+        # no-op fallthrough that returns the same string back.
+        if is_fatal_llm_error and fatal_exc is not None and fatal_exc.last_error_info is not None:
+            cause_msg = fatal_exc.last_error_info.message
+            user_message = f"Aborted after {fatal_exc.failure_count} consecutive failures. {cause_msg}"
+        elif is_fatal_llm_error and fatal_exc is not None:
+            # Old code path that didn't attach last_error_info — fall back
+            # to the wrapper's str(). Better than empty.
+            user_message = str(fatal_exc)
+        else:
+            try:
+                user_message = classify_llm_error_message(error)
+            except Exception:
+                user_message = str(error) or "AI service error"
 
         try:
             logger.debug("[REACT ERROR] Logging to event stream")
diff --git a/app/ui_layer/adapters/browser_adapter.py b/app/ui_layer/adapters/browser_adapter.py
index a2dbc872..05bf3dea 100644
--- a/app/ui_layer/adapters/browser_adapter.py
+++ b/app/ui_layer/adapters/browser_adapter.py
@@ -1458,7 +1458,8 @@ async def _handle_ws_message(self, data: Dict[str, Any], ws=None) -> None:
             provider = data.get("provider", "")
             api_key = data.get("apiKey")
             base_url = data.get("baseUrl")
-            await self._handle_model_connection_test(provider, api_key, base_url)
+            model = data.get("model")
+            await self._handle_model_connection_test(provider, api_key, base_url, model)
 
         elif msg_type == "model_validate_save":
             await self._handle_model_validate_save(data)
@@ -3673,6 +3674,7 @@ async def _handle_model_connection_test(
         provider: str,
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
+        model: Optional[str] = None,
     ) -> None:
         """Test connection to a model provider."""
         try:
@@ -3680,6 +3682,7 @@ async def _handle_model_connection_test(
                 provider=provider,
                 api_key=api_key,
                 base_url=base_url,
+                model=model,
             )
             await self._broadcast({
                 "type": "model_connection_test",
diff --git a/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css b/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
index b59cebe0..09c04973 100644
--- a/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
+++ b/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
@@ -7,6 +7,16 @@
   min-width: 0;
 }
 
+/* Wraps the scrolling list so the scroll-to-bottom button can sit absolutely
+   over the chat without scrolling along with the messages. */
+.messagesArea {
+  position: relative;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
 .messagesContainer {
   flex: 1;
   overflow-y: auto;
@@ -16,6 +26,72 @@
   gap: var(--space-3);
 }
 
+/* Slack-style date divider: a thin rule with a centered pill label */
+.dateDivider {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-2) 0 var(--space-3);
+  user-select: none;
+}
+
+.dateDividerLine {
+  flex: 1;
+  height: 1px;
+  background: var(--border-primary);
+}
+
+.dateDividerLabel {
+  flex-shrink: 0;
+  padding: 2px 12px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: 999px;
+  font-size: var(--text-xs);
+  font-weight: var(--font-semibold);
+  color: var(--text-secondary);
+  letter-spacing: 0.01em;
+}
+
+/* Floating scroll-to-bottom affordance. Appears when the user has scrolled
+   away from the latest message; click to jump back to the bottom. */
+.scrollToBottomBtn {
+  position: absolute;
+  right: var(--space-4);
+  bottom: var(--space-3);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  border-radius: 999px;
+  color: var(--text-secondary);
+  cursor: pointer;
+  opacity: 0.85;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
+  transition: opacity var(--transition-fast), background var(--transition-fast),
+    color var(--transition-fast), transform var(--transition-fast);
+  z-index: 5;
+  animation: scrollBtnFadeIn 120ms ease-out;
+}
+
+.scrollToBottomBtn:hover {
+  opacity: 1;
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.scrollToBottomBtn:active {
+  transform: translateY(1px);
+}
+
+@keyframes scrollBtnFadeIn {
+  from { opacity: 0; transform: translateY(4px); }
+  to   { opacity: 0.85; transform: translateY(0); }
+}
+
 .emptyState {
   flex: 1;
   display: flex;
diff --git a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
index 51fc0480..778ffb92 100644
--- a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
+++ b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
@@ -1,6 +1,6 @@
 import React, { useState, useRef, useEffect, useLayoutEffect, KeyboardEvent, useCallback, ChangeEvent, useMemo } from 'react'
 import ReactDOM from 'react-dom'
-import { Send, Paperclip, X, Loader2, File, AlertCircle, Reply, Mic, MicOff } from 'lucide-react'
+import { Send, Paperclip, X, Loader2, File, AlertCircle, Reply, Mic, MicOff, ChevronDown } from 'lucide-react'
 import { useVirtualizer } from '@tanstack/react-virtual'
 import { useWebSocket } from '../../contexts/WebSocketContext'
 import { useToast } from '../../contexts/ToastContext'
@@ -54,6 +54,41 @@ const formatFileSize = (bytes: number): string => {
   return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i]
 }
 
+// Stable per-day key (local time) for grouping consecutive messages by date.
+const getDateKey = (timestamp: number): string => {
+  const d = new Date(timestamp * 1000)
+  return `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`
+}
+
+// Slack-style date divider label: "Today", "Yesterday", weekday for the
+// last week, otherwise a full localized date.
+const formatDateDivider = (timestamp: number): string => {
+  const date = new Date(timestamp * 1000)
+  const now = new Date()
+  const sameDay = (a: Date, b: Date) =>
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+
+  if (sameDay(date, now)) return 'Today'
+  const yesterday = new Date(now)
+  yesterday.setDate(yesterday.getDate() - 1)
+  if (sameDay(date, yesterday)) return 'Yesterday'
+
+  const msPerDay = 1000 * 60 * 60 * 24
+  const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+  const startOfDate = new Date(date.getFullYear(), date.getMonth(), date.getDate())
+  const daysDiff = Math.round((startOfToday.getTime() - startOfDate.getTime()) / msPerDay)
+
+  if (daysDiff > 0 && daysDiff < 7) {
+    return date.toLocaleDateString(undefined, { weekday: 'long', month: 'long', day: 'numeric' })
+  }
+  if (date.getFullYear() === now.getFullYear()) {
+    return date.toLocaleDateString(undefined, { weekday: 'long', month: 'long', day: 'numeric' })
+  }
+  return date.toLocaleDateString(undefined, { year: 'numeric', month: 'long', day: 'numeric' })
+}
+
 export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
   const {
     messages,
@@ -112,6 +147,7 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
   const wasNearBottomRef = useRef(true)
   const prevMessageCountRef = useRef(0)
   const hasInitialScrolled = useRef(false)
+  const [showScrollToBottom, setShowScrollToBottom] = useState(false)
 
   const attachmentValidation = useMemo(() => {
     const totalSize = pendingAttachments.reduce((sum, att) => sum + att.size, 0)
@@ -140,12 +176,6 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
     return lastSeenIdx + 1
   }, [orderedMessages, lastSeenMessageId])
 
-  const isNearBottom = useCallback(() => {
-    const container = parentRef.current
-    if (!container) return true
-    return container.scrollHeight - container.scrollTop - container.clientHeight < 100
-  }, [])
-
   // Close language dropdown when clicking outside
   useEffect(() => {
     if (!langOpen) return
@@ -171,14 +201,21 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
     const container = parentRef.current
     if (!container) return
     const handleScroll = () => {
-      wasNearBottomRef.current = isNearBottom()
+      const distFromBottom = container.scrollHeight - container.scrollTop - container.clientHeight
+      wasNearBottomRef.current = distFromBottom < 100
+      setShowScrollToBottom(distFromBottom > 100)
       if (container.scrollTop < 100 && hasMoreMessages && !loadingOlderMessages) {
         loadOlderMessages()
       }
     }
     container.addEventListener('scroll', handleScroll)
     return () => container.removeEventListener('scroll', handleScroll)
-  }, [isNearBottom, hasMoreMessages, loadingOlderMessages, loadOlderMessages])
+  }, [hasMoreMessages, loadingOlderMessages, loadOlderMessages])
+
+  const scrollToBottom = useCallback(() => {
+    if (orderedMessages.length === 0) return
+    virtualizer.scrollToIndex(orderedMessages.length - 1, { align: 'end', behavior: 'smooth' })
+  }, [virtualizer, orderedMessages.length])
 
   // Scroll to unread on mount, auto-scroll on new messages if near bottom
   useEffect(() => {
@@ -473,64 +510,86 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
 
   return (
     <div className={styles.chat}>
-      <div className={styles.messagesContainer} ref={parentRef}>
-        {orderedMessages.length === 0 ? (
-          <div className={styles.emptyState}>
-            <div className={styles.emptyIcon}>
-              <svg width="48" height="48" viewBox="0 0 32 32" fill="none">
-                <rect width="32" height="32" rx="6" fill="var(--color-primary-light)"/>
-                <path d="M8 12h16M8 16h12M8 20h8" stroke="var(--color-primary)" strokeWidth="2" strokeLinecap="round"/>
-              </svg>
-            </div>
-            <h3>{emptyMessage || 'Start a conversation'}</h3>
-            <p>{livingUIId ? 'Ask the agent about this UI' : 'Send a message to begin interacting with CraftBot'}</p>
-          </div>
-        ) : (
-          <div
-            style={{
-              height: `${virtualizer.getTotalSize()}px`,
-              width: '100%',
-              position: 'relative',
-            }}
-          >
-            {loadingOlderMessages && (
-              <div style={{ textAlign: 'center', padding: '8px 0', color: 'var(--text-tertiary)', fontSize: 'var(--text-xs)' }}>
-                <Loader2 size={14} style={{ display: 'inline', animation: 'spin 1s linear infinite' }} /> Loading older messages...
+      <div className={styles.messagesArea}>
+        <div className={styles.messagesContainer} ref={parentRef}>
+          {orderedMessages.length === 0 ? (
+            <div className={styles.emptyState}>
+              <div className={styles.emptyIcon}>
+                <svg width="48" height="48" viewBox="0 0 32 32" fill="none">
+                  <rect width="32" height="32" rx="6" fill="var(--color-primary-light)"/>
+                  <path d="M8 12h16M8 16h12M8 20h8" stroke="var(--color-primary)" strokeWidth="2" strokeLinecap="round"/>
+                </svg>
               </div>
-            )}
-            {virtualizer.getVirtualItems().map((virtualItem) => {
-              const message = orderedMessages[virtualItem.index]
-              // Prefer clientId as the React key so that when a pending optimistic
-              // message is reconciled with the server echo (messageId changes from
-              // `pending:<cid>` to the real id), React reuses the same DOM node —
-              // letting the CSS transform transition animate the slide into
-              // its server-canonical sorted position.
-              const rowKey = message.clientId || message.messageId || virtualItem.index
-              return (
-                <div
-                  key={rowKey}
-                  data-index={virtualItem.index}
-                  ref={virtualizer.measureElement}
-                  style={{
-                    position: 'absolute',
-                    top: 0,
-                    left: 0,
-                    width: '100%',
-                    transform: `translateY(${virtualItem.start}px)`,
-                    transition: 'transform 250ms ease',
-                  }}
-                >
-                  <ChatMessageItem
-                    message={message}
-                    onOpenFile={openFile}
-                    onOpenFolder={openFolder}
-                    onReply={handleChatReply}
-                    onOptionClick={sendOptionClick}
-                  />
+              <h3>{emptyMessage || 'Start a conversation'}</h3>
+              <p>{livingUIId ? 'Ask the agent about this UI' : 'Send a message to begin interacting with CraftBot'}</p>
+            </div>
+          ) : (
+            <div
+              style={{
+                height: `${virtualizer.getTotalSize()}px`,
+                width: '100%',
+                position: 'relative',
+              }}
+            >
+              {loadingOlderMessages && (
+                <div style={{ textAlign: 'center', padding: '8px 0', color: 'var(--text-tertiary)', fontSize: 'var(--text-xs)' }}>
+                  <Loader2 size={14} style={{ display: 'inline', animation: 'spin 1s linear infinite' }} /> Loading older messages...
                 </div>
-              )
-            })}
-          </div>
+              )}
+              {virtualizer.getVirtualItems().map((virtualItem) => {
+                const message = orderedMessages[virtualItem.index]
+                const prev = virtualItem.index > 0 ? orderedMessages[virtualItem.index - 1] : null
+                const showDateDivider = !prev || getDateKey(prev.timestamp) !== getDateKey(message.timestamp)
+                // Prefer clientId as the React key so that when a pending optimistic
+                // message is reconciled with the server echo (messageId changes from
+                // `pending:<cid>` to the real id), React reuses the same DOM node —
+                // letting the CSS transform transition animate the slide into
+                // its server-canonical sorted position.
+                const rowKey = message.clientId || message.messageId || virtualItem.index
+                return (
+                  <div
+                    key={rowKey}
+                    data-index={virtualItem.index}
+                    ref={virtualizer.measureElement}
+                    style={{
+                      position: 'absolute',
+                      top: 0,
+                      left: 0,
+                      width: '100%',
+                      transform: `translateY(${virtualItem.start}px)`,
+                      transition: 'transform 250ms ease',
+                    }}
+                  >
+                    {showDateDivider && (
+                      <div className={styles.dateDivider} role="separator" aria-label={formatDateDivider(message.timestamp)}>
+                        <span className={styles.dateDividerLine} />
+                        <span className={styles.dateDividerLabel}>{formatDateDivider(message.timestamp)}</span>
+                        <span className={styles.dateDividerLine} />
+                      </div>
+                    )}
+                    <ChatMessageItem
+                      message={message}
+                      onOpenFile={openFile}
+                      onOpenFolder={openFolder}
+                      onReply={handleChatReply}
+                      onOptionClick={sendOptionClick}
+                    />
+                  </div>
+                )
+              })}
+            </div>
+          )}
+        </div>
+        {showScrollToBottom && orderedMessages.length > 0 && (
+          <button
+            type="button"
+            className={styles.scrollToBottomBtn}
+            onClick={scrollToBottom}
+            aria-label="Scroll to latest message"
+            title="Scroll to latest message"
+          >
+            <ChevronDown size={18} />
+          </button>
         )}
       </div>
 
diff --git a/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx b/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx
index d8557a0c..44b06aca 100644
--- a/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx
@@ -81,7 +81,7 @@ export const ChatMessageItem = memo(function ChatMessageItem({
         <div className={styles.messageHeader}>
           <span className={styles.sender}>{message.sender}</span>
           <span className={styles.timestamp}>
-            {new Date(message.timestamp * 1000).toLocaleTimeString()}
+            {new Date(message.timestamp * 1000).toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' })}
           </span>
         </div>
         {/* Reply context callout - shown above user message when replying */}
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
index c74e41c3..ccd5d729 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
@@ -363,10 +363,13 @@ export function ModelSettings() {
 
   const handleTestConnection = () => {
     setIsTesting(true)
+    // Send the user's actual model so the test exercises it; otherwise a
+    // typo passes the test (auth-only) and only fails at first real call.
     send('model_connection_test', {
       provider,
       apiKey: newApiKey || undefined,
       baseUrl: newBaseUrl || baseUrls[provider],
+      model: newLlmModel || currentLlmModel || undefined,
     })
   }
 
@@ -381,6 +384,7 @@ export function ModelSettings() {
         provider,
         apiKey: newApiKey || undefined,
         baseUrl: newBaseUrl || baseUrls[provider],
+        model: newLlmModel || currentLlmModel || undefined,
       })
     } else {
       setIsSaving(true)
diff --git a/app/ui_layer/settings/model_settings.py b/app/ui_layer/settings/model_settings.py
index 6554b4bb..4b87e48c 100644
--- a/app/ui_layer/settings/model_settings.py
+++ b/app/ui_layer/settings/model_settings.py
@@ -372,6 +372,7 @@ def test_connection(
     provider: str,
     api_key: Optional[str] = None,
     base_url: Optional[str] = None,
+    model: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Test connection to a provider.
 
@@ -379,6 +380,10 @@ def test_connection(
         provider: Provider to test
         api_key: Optional API key to test with (if not provided, uses stored key)
         base_url: Optional base URL for byteplus/remote providers
+        model: Optional model id to verify. When provided the tester does a
+            tiny chat completion against this exact model so a typo in the
+            model id is caught at test time, not at first real call. When
+            omitted, falls back to a known-good test model (auth check only).
 
     Returns:
         Dict with test results
@@ -410,6 +415,7 @@ def test_connection(
             provider=provider,
             api_key=api_key,
             base_url=base_url,
+            model=model,
         )
 
         return result

From 07118dc53893ec550a02d40c4675c49d38c771c5 Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Fri, 8 May 2026 15:19:28 +0900
Subject: [PATCH 06/10] Fix chat panel scroll to botton button display logic

---
 app/agent_base.py                             | 24 +++++++++++++--
 .../frontend/src/components/Chat/Chat.tsx     | 30 +++++++++++++++----
 2 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/app/agent_base.py b/app/agent_base.py
index 28500d6a..e05d18a7 100644
--- a/app/agent_base.py
+++ b/app/agent_base.py
@@ -1341,10 +1341,30 @@ async def _handle_react_error(
 
         try:
             logger.debug("[REACT ERROR] Logging to event stream")
+            # Only fatal errors surface as a red chat bubble. Non-fatal cases
+            # (single parse failure, transient API hiccup, etc.) are still
+            # recorded into the event stream so the LLM sees the failure in
+            # its next-attempt context — but we use a non-error kind so the
+            # transformer does NOT emit a chat-visible ERROR_MESSAGE. The
+            # agent retries automatically via _create_new_trigger below, and
+            # the user shouldn't see a scary error bubble for something that
+            # is being silently recovered. If retries pile up past the
+            # consecutive-failure threshold, the fatal branch above kicks in
+            # and the rich classified message is surfaced then.
+            #
+            # NOTE: We must change the *kind* rather than just unsetting
+            # display_message — when kind is in ERROR_KINDS the transformer
+            # falls back to event.message (the full traceback) for the chat
+            # bubble, which would be even worse. Using kind="warning" follows
+            # the existing convention (see the limit-reached events earlier
+            # in this file) and the LLM still understands the entry from the
+            # message text.
+            log_kind = "error" if is_fatal_llm_error else "warning"
+            log_display_message = user_message if is_fatal_llm_error else None
             self.event_stream_manager.log(
-                "error",
+                log_kind,
                 f"[REACT] {type(error).__name__}: {error}\n{tb}",
-                display_message=user_message,
+                display_message=log_display_message,
                 task_id=session_to_use,
             )
             self.state_manager.bump_event_stream()
diff --git a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
index 778ffb92..e07b40ef 100644
--- a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
+++ b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
@@ -147,6 +147,7 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
   const wasNearBottomRef = useRef(true)
   const prevMessageCountRef = useRef(0)
   const hasInitialScrolled = useRef(false)
+  const prevScrollTopRef = useRef(0)
   const [showScrollToBottom, setShowScrollToBottom] = useState(false)
 
   const attachmentValidation = useMemo(() => {
@@ -196,15 +197,33 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
     return () => document.removeEventListener('keydown', handler)
   }, [previewAttachment])
 
-  // Track scroll position + load older messages on scroll-to-top
+  // Track scroll position + direction, and load older messages on scroll-to-top.
+  // The scroll-to-bottom button surfaces when the user is scrolling *toward*
+  // the bottom but hasn't arrived yet — scrolling up to read history hides it.
   useEffect(() => {
     const container = parentRef.current
     if (!container) return
+    prevScrollTopRef.current = container.scrollTop
     const handleScroll = () => {
-      const distFromBottom = container.scrollHeight - container.scrollTop - container.clientHeight
-      wasNearBottomRef.current = distFromBottom < 100
-      setShowScrollToBottom(distFromBottom > 100)
-      if (container.scrollTop < 100 && hasMoreMessages && !loadingOlderMessages) {
+      const scrollTop = container.scrollTop
+      const distFromBottom = container.scrollHeight - scrollTop - container.clientHeight
+      const nearBottom = distFromBottom < 100
+      wasNearBottomRef.current = nearBottom
+
+      const delta = scrollTop - prevScrollTopRef.current
+      prevScrollTopRef.current = scrollTop
+
+      if (nearBottom) {
+        setShowScrollToBottom(false)
+      } else if (delta > 0) {
+        // Scrolling down (toward latest) — offer a quick jump.
+        setShowScrollToBottom(true)
+      } else if (delta < 0) {
+        // Scrolling up (reading history) — get out of the way.
+        setShowScrollToBottom(false)
+      }
+
+      if (scrollTop < 100 && hasMoreMessages && !loadingOlderMessages) {
         loadOlderMessages()
       }
     }
@@ -215,6 +234,7 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
   const scrollToBottom = useCallback(() => {
     if (orderedMessages.length === 0) return
     virtualizer.scrollToIndex(orderedMessages.length - 1, { align: 'end', behavior: 'smooth' })
+    setShowScrollToBottom(false)
   }, [virtualizer, orderedMessages.length])
 
   // Scroll to unread on mount, auto-scroll on new messages if near bottom

From 0e5254f57c33cb8c9e4f82d3c7a05d165737f1a8 Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Sun, 10 May 2026 07:30:56 +0900
Subject: [PATCH 07/10] LLM call error handling and display

---
 agent_core/core/impl/llm/errors.py    | 17 +++++++++++++++--
 agent_core/core/impl/llm/interface.py | 13 +++++++++++++
 app/agent_base.py                     |  2 +-
 3 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/agent_core/core/impl/llm/errors.py b/agent_core/core/impl/llm/errors.py
index e63b5605..40efc555 100644
--- a/agent_core/core/impl/llm/errors.py
+++ b/agent_core/core/impl/llm/errors.py
@@ -142,7 +142,7 @@ def to_dict(self) -> Dict[str, Any]:
 MSG_CONNECTION = "Could not reach the provider. Check your network connection."
 MSG_GENERIC = "Something went wrong calling the AI service."
 MSG_CONSECUTIVE_FAILURE = (
-    "Aborted after {count} consecutive failures."
+    "Aborted after consecutive failures."
 )
 
 
@@ -286,7 +286,20 @@ def _classify_openai_compat(exc: Exception, provider: str) -> LLMErrorInfo:
         # Grok edge case — body is the raw string message
         body_dict = {"message": body}
 
-    raw_message: str = (body_dict.get("message") if isinstance(body_dict.get("message"), str) else None) or str(exc)
+    # Pick the cleanest user-facing string out of the body. Different
+    # OpenAI-compatible providers stash it under different keys:
+    #   - OpenAI / OpenRouter / DeepSeek: body["message"]
+    #   - Grok bad-model (400):           body["error"]   (a string)
+    #   - Grok bad-key (400, body=string):  handled above by string→dict shim
+    # Falling back to str(exc) produces "Error code: 400 - {full body dict}",
+    # which is too noisy for the chat — only use it when nothing else fits.
+    raw_message_candidate: Optional[str] = None
+    for key in ("message", "error"):
+        v = body_dict.get(key)
+        if isinstance(v, str) and v:
+            raw_message_candidate = v
+            break
+    raw_message: str = raw_message_candidate or str(exc)
     code = body_dict.get("code")
     error_type = body_dict.get("type")
 
diff --git a/agent_core/core/impl/llm/interface.py b/agent_core/core/impl/llm/interface.py
index 67d2cb54..2d684789 100644
--- a/agent_core/core/impl/llm/interface.py
+++ b/agent_core/core/impl/llm/interface.py
@@ -1306,6 +1306,19 @@ def _generate_openai(
             # Include error details for better diagnostics
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the outer
+            # `_generate_response_sync` can attach it to the consecutive-
+            # failure exception. Without this, providers that go through
+            # this path (OpenAI, OpenRouter, Grok, DeepSeek, MiniMax,
+            # Moonshot) would surface a bare "Aborted after N consecutive
+            # failures." with no cause when they fail. The classifier is
+            # wrapped in try/except so it can never break the error path.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[OPENAI_ERROR] {error_str}")
         else:
diff --git a/app/agent_base.py b/app/agent_base.py
index e05d18a7..cb43c409 100644
--- a/app/agent_base.py
+++ b/app/agent_base.py
@@ -1328,7 +1328,7 @@ async def _handle_react_error(
         # no-op fallthrough that returns the same string back.
         if is_fatal_llm_error and fatal_exc is not None and fatal_exc.last_error_info is not None:
             cause_msg = fatal_exc.last_error_info.message
-            user_message = f"Aborted after {fatal_exc.failure_count} consecutive failures. {cause_msg}"
+            user_message = f"Aborted after consecutive failures. {cause_msg}"
         elif is_fatal_llm_error and fatal_exc is not None:
             # Old code path that didn't attach last_error_info — fall back
             # to the wrapper's str(). Better than empty.

From 2ac9dc7ca3252b523b99880cff6ed0fee7b7c1db Mon Sep 17 00:00:00 2001
From: zfoong <tham_yikfoong@outlook.com>
Date: Sun, 10 May 2026 14:01:17 +0900
Subject: [PATCH 08/10] Fix token limit is global issue

---
 agent_core/core/impl/action/manager.py        | 20 +++++++++---
 agent_core/core/state/session.py              | 15 +++++++++
 app/agent_base.py                             | 13 +++-----
 app/gui/gui_module.py                         |  3 +-
 app/llm/interface.py                          | 10 +++---
 app/llm_interface.py                          | 29 +++++++----------
 app/state/agent_state.py                      | 21 +++++++++++++
 .../src/contexts/WebSocketContext.tsx         | 31 ++++++++++++-------
 app/vlm_interface.py                          | 10 +++---
 9 files changed, 98 insertions(+), 54 deletions(-)

diff --git a/agent_core/core/impl/action/manager.py b/agent_core/core/impl/action/manager.py
index d17ad889..b038c61c 100644
--- a/agent_core/core/impl/action/manager.py
+++ b/agent_core/core/impl/action/manager.py
@@ -387,13 +387,23 @@ async def execute_action(
 
         logger.debug(f"Persisting final state for action {action.name}...")
 
-        # Update action count in state
-        state = get_state_or_none()
-        if state:
-            state.set_agent_property(
+        # Update action count on the per-task StateSession (per-task counter).
+        # Falls back to the global state provider when no session is registered
+        # (e.g. transient/conversation-mode actions before any task is created).
+        from agent_core.core.state.session import StateSession
+        session = StateSession.get_or_none(session_id) if session_id else None
+        if session is not None:
+            session.agent_properties.set_property(
                 "action_count",
-                state.get_agent_property("action_count", 0) + 1
+                session.agent_properties.get_property("action_count", 0) + 1,
             )
+        else:
+            state = get_state_or_none()
+            if state:
+                state.set_agent_property(
+                    "action_count",
+                    state.get_agent_property("action_count", 0) + 1
+                )
 
         # Call on_action_end hook if provided
         if self._on_action_end:
diff --git a/agent_core/core/state/session.py b/agent_core/core/state/session.py
index 7aae45f3..79b29c49 100644
--- a/agent_core/core/state/session.py
+++ b/agent_core/core/state/session.py
@@ -72,6 +72,13 @@ def start(
     ) -> "StateSession":
         """Create or update a session for the given session_id.
 
+        If a session already exists for this session_id, its `agent_properties`
+        (which hold per-task counters like action_count and token_count) are
+        preserved across re-entries. Only the session context fields (task,
+        event_stream, gui_mode) are refreshed. Counters are reset only at task
+        end via StateSession.end(), or explicitly when the user resumes past a
+        limit.
+
         Args:
             session_id: Unique identifier for this session (typically task_id)
             current_task: The Task object for this session
@@ -81,6 +88,14 @@ def start(
         Returns:
             The created or updated StateSession instance
         """
+        existing = cls._instances.get(session_id)
+        if existing is not None:
+            existing.current_task = current_task
+            existing.event_stream = event_stream
+            existing.gui_mode = gui_mode
+            existing.agent_properties.set_property("current_task_id", session_id)
+            return existing
+
         inst = cls()
         inst.session_id = session_id
         inst.current_task = current_task
diff --git a/app/agent_base.py b/app/agent_base.py
index cb43c409..a787e5bc 100644
--- a/app/agent_base.py
+++ b/app/agent_base.py
@@ -1411,12 +1411,13 @@ def _cleanup_session(self) -> None:
     # ----- Agent Limits -----
 
     async def _check_agent_limits(self) -> bool:
-        agent_properties = STATE.get_agent_properties()
+        from app.state.agent_state import get_session_props
+        current_task_id: str = STATE.get_agent_property("current_task_id", "")
+        agent_properties = get_session_props(current_task_id).to_dict()
         action_count: int = agent_properties.get("action_count", 0)
         max_actions: int = agent_properties.get("max_actions_per_task", 0)
         token_count: int = agent_properties.get("token_count", 0)
         max_tokens: int = agent_properties.get("max_tokens_per_task", 0)
-        current_task_id: str = agent_properties.get("current_task_id", "")
 
         # Check action limits
         if (action_count / max_actions) >= 1.0:
@@ -1582,13 +1583,9 @@ async def handle_limit_continue(self, session_id: str) -> None:
             logger.warning(f"[LIMIT] Task {session_id} not found for limit continue")
             return
 
-        # Reset counters
-        STATE.set_agent_property("action_count", 0)
-        STATE.set_agent_property("token_count", 0)
-
-        # Also reset on the StateSession for this session
+        # Reset per-task counters on this session's StateSession.
         from agent_core.core.state.session import StateSession
-        session = StateSession.get(session_id)
+        session = StateSession.get_or_none(session_id)
         if session:
             session.agent_properties.set_property("action_count", 0)
             session.agent_properties.set_property("token_count", 0)
diff --git a/app/gui/gui_module.py b/app/gui/gui_module.py
index 37c5a6d2..6f9068ec 100644
--- a/app/gui/gui_module.py
+++ b/app/gui/gui_module.py
@@ -782,7 +782,8 @@ def _parse_reasoning_response(self, response: str) -> Tuple[ReasoningResult, int
         return reasoning_result, int(item_index)
 
     async def _check_agent_limits(self) -> bool:
-        agent_properties = STATE.get_agent_properties()
+        from app.state.agent_state import get_session_props
+        agent_properties = get_session_props().to_dict()
         action_count: int = agent_properties.get("action_count", 0)
         max_actions: int = agent_properties.get("max_actions_per_task", 0)
         token_count: int = agent_properties.get("token_count", 0)
diff --git a/app/llm/interface.py b/app/llm/interface.py
index b21fa5a8..52a48183 100644
--- a/app/llm/interface.py
+++ b/app/llm/interface.py
@@ -10,17 +10,17 @@
 
 from agent_core.core.impl.llm import LLMInterface as _LLMInterface
 from agent_core.core.hooks.types import UsageEventData
-from app.state.agent_state import STATE
+from app.state.agent_state import get_session_props
 
 
 def _get_token_count() -> int:
-    """Get token count from CraftBot's global STATE."""
-    return STATE.get_agent_property("token_count", 0)
+    """Get token count from the active task's StateSession (per-task counter)."""
+    return get_session_props().get_property("token_count", 0)
 
 
 def _set_token_count(count: int) -> None:
-    """Set token count in CraftBot's global STATE."""
-    STATE.set_agent_property("token_count", count)
+    """Set token count on the active task's StateSession (per-task counter)."""
+    get_session_props().set_property("token_count", count)
 
 
 async def _report_usage(event: UsageEventData) -> None:
diff --git a/app/llm_interface.py b/app/llm_interface.py
index 686ed9ab..d8299f19 100644
--- a/app/llm_interface.py
+++ b/app/llm_interface.py
@@ -37,7 +37,7 @@ class LLMCallType(str, Enum):
 from app.models.factory import ModelFactory
 from app.models.types import InterfaceType
 from app.google_gemini_client import GeminiAPIError, GeminiClient
-from app.state.agent_state import STATE
+from app.state.agent_state import STATE, get_session_props
 from agent_core import profile, OperationCategory
 
 # Logging setup — fall back to a basic logger if the project‑level logger
@@ -949,7 +949,8 @@ def _generate_response_sync(
         cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
 
         tokens_used = response.get("tokens_used", 0)
-        STATE.set_agent_property("token_count", STATE.get_agent_property("token_count", 0) + tokens_used)
+        _props = get_session_props()
+        _props.set_property("token_count", _props.get_property("token_count", 0) + tokens_used)
 
         if _slow_mode_active and tokens_used > 0:
             from app.rate_limiter import get_rate_limiter
@@ -1219,10 +1220,8 @@ def _generate_response_with_session_sync(
             response = self._generate_gemini(effective_system_prompt, user_prompt, call_type=call_type)
             cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
             _tokens_used = response.get("tokens_used", 0)
-            STATE.set_agent_property(
-                "token_count",
-                STATE.get_agent_property("token_count", 0) + _tokens_used
-            )
+            _props = get_session_props(task_id)
+            _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
             if _slow_mode_active and _tokens_used > 0:
                 from app.rate_limiter import get_rate_limiter
                 get_rate_limiter().record_usage(_tokens_used)
@@ -1246,10 +1245,8 @@ def _generate_response_with_session_sync(
             response = self._generate_openai(effective_system_prompt, user_prompt, call_type=call_type)
             cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
             _tokens_used = response.get("tokens_used", 0)
-            STATE.set_agent_property(
-                "token_count",
-                STATE.get_agent_property("token_count", 0) + _tokens_used
-            )
+            _props = get_session_props(task_id)
+            _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
             if _slow_mode_active and _tokens_used > 0:
                 from app.rate_limiter import get_rate_limiter
                 get_rate_limiter().record_usage(_tokens_used)
@@ -1334,10 +1331,8 @@ def _generate_response_with_session_sync(
 
             cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
             _tokens_used = response.get("tokens_used", 0)
-            STATE.set_agent_property(
-                "token_count",
-                STATE.get_agent_property("token_count", 0) + _tokens_used
-            )
+            _props = get_session_props(task_id)
+            _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
             if _slow_mode_active and _tokens_used > 0:
                 from app.rate_limiter import get_rate_limiter
                 get_rate_limiter().record_usage(_tokens_used)
@@ -1422,10 +1417,8 @@ def _generate_response_with_session_sync(
         cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
 
         _tokens_used = response.get("tokens_used", 0)
-        STATE.set_agent_property(
-            "token_count",
-            STATE.get_agent_property("token_count", 0) + _tokens_used
-        )
+        _props = get_session_props(task_id)
+        _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
         if _slow_mode_active and _tokens_used > 0:
             from app.rate_limiter import get_rate_limiter
             get_rate_limiter().record_usage(_tokens_used)
diff --git a/app/state/agent_state.py b/app/state/agent_state.py
index bb34686d..123509e9 100644
--- a/app/state/agent_state.py
+++ b/app/state/agent_state.py
@@ -7,6 +7,7 @@
 from typing import Any, Dict, Optional
 from app.state.types import AgentProperties
 from app.task import Task
+from agent_core.core.state.session import StateSession
 
 @dataclass
 class AgentState:
@@ -58,3 +59,23 @@ def get_agent_properties(self):
 
 # ---- Global runtime state ----
 STATE = AgentState()
+
+
+def get_session_props(session_id: Optional[str] = None) -> AgentProperties:
+    """Return the AgentProperties bag that owns per-task counters
+    (token_count, action_count) for the active task.
+
+    If `session_id` is given, returns that session's properties; otherwise
+    uses STATE.agent_properties.current_task_id to find the active session.
+    Falls back to the global STATE.agent_properties when no session exists
+    (e.g. conversation mode or before a task is created).
+
+    This is the single source of truth for per-task counters — the global
+    STATE counters must not be used for limit checks or token attribution.
+    """
+    sid = session_id or STATE.agent_properties.get_property("current_task_id", "")
+    if sid:
+        session = StateSession.get_or_none(sid)
+        if session is not None:
+            return session.agent_properties
+    return STATE.agent_properties
diff --git a/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx b/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx
index 5f27ae3b..53530798 100644
--- a/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx
+++ b/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx
@@ -1018,19 +1018,26 @@ export function WebSocketProvider({ children }: { children: ReactNode }) {
   ) => {
     const clientId = newClientId()
 
-    // Optimistic insert: show the user's bubble immediately at reduced opacity.
-    // The server echo (case 'chat_message') will replace this entry in place by
-    // matching on clientId, flipping `pending` -> false.
-    const optimistic: ChatMessage = {
-      sender: 'You',
-      content,
-      style: 'user',
-      timestamp: Date.now() / 1000,
-      messageId: `pending:${clientId}`,
-      clientId,
-      pending: true,
+    // Slash commands are handled by the controller's command executor and
+    // never produce a user chat bubble — skip the optimistic insert so a
+    // "pending" bubble doesn't linger when the server has nothing to echo.
+    const isSlashCommand = content.trimStart().startsWith('/')
+
+    if (!isSlashCommand) {
+      // Optimistic insert: show the user's bubble immediately at reduced opacity.
+      // The server echo (case 'chat_message') will replace this entry in place by
+      // matching on clientId, flipping `pending` -> false.
+      const optimistic: ChatMessage = {
+        sender: 'You',
+        content,
+        style: 'user',
+        timestamp: Date.now() / 1000,
+        messageId: `pending:${clientId}`,
+        clientId,
+        pending: true,
+      }
+      setState(prev => ({ ...prev, messages: [...prev.messages, optimistic] }))
     }
-    setState(prev => ({ ...prev, messages: [...prev.messages, optimistic] }))
 
     sendOrQueue(JSON.stringify({
       type: 'message',
diff --git a/app/vlm_interface.py b/app/vlm_interface.py
index 3c71e9e3..74781134 100644
--- a/app/vlm_interface.py
+++ b/app/vlm_interface.py
@@ -10,17 +10,17 @@
 
 from agent_core.core.impl.vlm import VLMInterface as _VLMInterface
 from agent_core.core.hooks.types import UsageEventData
-from app.state.agent_state import STATE
+from app.state.agent_state import get_session_props
 
 
 def _get_token_count() -> int:
-    """Get token count from CraftBot's global STATE."""
-    return STATE.get_agent_property("token_count", 0)
+    """Get token count from the active task's StateSession (per-task counter)."""
+    return get_session_props().get_property("token_count", 0)
 
 
 def _set_token_count(count: int) -> None:
-    """Set token count in CraftBot's global STATE."""
-    STATE.set_agent_property("token_count", count)
+    """Set token count on the active task's StateSession (per-task counter)."""
+    get_session_props().set_property("token_count", count)
 
 
 async def _report_usage(event: UsageEventData) -> None:

From c21d9e2d7a039c620d70755c0c7ecd61a1b8cd7c Mon Sep 17 00:00:00 2001
From: Vilius Vystartas <vilius.vystartas@gmail.com>
Date: Tue, 12 May 2026 20:36:00 +0100
Subject: [PATCH 09/10] fix: onboarding usability + platform-aware MCP paths

- Add Ctrl+S shortcut to skip optional wizard steps (MCP/Skills)
- Add 'focus_nav' action to reach nav bar from multi-select widgets
- Detect Windows-only paths in MCP servers and annotate as platform_blocked
- Surface platform warnings in onboarding MCP step descriptions
- Guard list_mcp_servers() against silent config-load failures
---
 app/onboarding/interfaces/steps.py | 47 +++++++++++++++++-------------
 app/tui/mcp_settings.py            | 40 +++++++++++++++++++++++--
 app/tui/onboarding/widgets.py      | 12 ++++++++
 3 files changed, 77 insertions(+), 22 deletions(-)

diff --git a/app/onboarding/interfaces/steps.py b/app/onboarding/interfaces/steps.py
index d87c02aa..a2c1ba67 100644
--- a/app/onboarding/interfaces/steps.py
+++ b/app/onboarding/interfaces/steps.py
@@ -498,28 +498,35 @@ def get_options(self) -> List[StepOption]:
         try:
             from app.tui.mcp_settings import list_mcp_servers
             servers = list_mcp_servers()
-
-            # Create a lookup by name
-            server_lookup = {s["name"]: s for s in servers}
-
-            # Return only recommended servers that exist in config
-            options = []
-            for name, (icon, requires_setup) in self.RECOMMENDED_SERVERS.items():
-                if name in server_lookup:
-                    server = server_lookup[name]
-                    label = server["name"].replace("-", " ").replace(" mcp", "").title()
-                    options.append(StepOption(
-                        value=server["name"],
-                        label=label,
-                        description=server.get("description", f"MCP server: {server['name']}"),
-                        default=server.get("enabled", False),
-                        icon=icon,
-                        requires_setup=requires_setup
-                    ))
-            return options
-        except ImportError:
+        except Exception:
+            # If MCP config is completely broken, show nothing rather than
+            # crashing the wizard — the user can configure later in Settings.
             return []
 
+        # Create a lookup by name
+        server_lookup = {s["name"]: s for s in servers}
+
+        # Return only recommended servers that exist in config
+        options = []
+        for name, (icon, requires_setup) in self.RECOMMENDED_SERVERS.items():
+            if name in server_lookup:
+                server = server_lookup[name]
+                label = server["name"].replace("-", " ").replace(" mcp", "").title()
+                # Append platform warning to description when server paths
+                # are incompatible with the current OS
+                desc = server.get("description", f"MCP server: {server['name']}")
+                if server.get("platform_blocked"):
+                    desc += " (Windows-only — requires setup on this OS)"
+                options.append(StepOption(
+                    value=server["name"],
+                    label=label,
+                    description=desc,
+                    default=server.get("enabled", False),
+                    icon=icon,
+                    requires_setup=requires_setup,
+                ))
+        return options
+
     def validate(self, value: Any) -> tuple[bool, Optional[str]]:
         # Value should be a list of server names
         if not isinstance(value, list):
diff --git a/app/tui/mcp_settings.py b/app/tui/mcp_settings.py
index 6696e5ff..e6236943 100644
--- a/app/tui/mcp_settings.py
+++ b/app/tui/mcp_settings.py
@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import json
+import sys
 from pathlib import Path
 from typing import Dict, List, Optional, Any
 
@@ -13,6 +14,23 @@
 MCP_CONFIG_PATH = APP_CONFIG_PATH / "mcp_config.json"
 
 
+def _is_windows_path(path: str) -> bool:
+    """Check if a path uses Windows drive-letter syntax (e.g. C:/...)."""
+    return bool(path) and len(path) >= 2 and path[0].isalpha() and path[1] == ":"
+
+
+def _path_usable_on_current_platform(command: str, args: list) -> bool:
+    """Return False if command/args reference paths not valid on this OS."""
+    if sys.platform == "win32":
+        return True
+    if _is_windows_path(command):
+        return False
+    for arg in args or []:
+        if _is_windows_path(arg):
+            return False
+    return True
+
+
 def load_mcp_config() -> MCPConfig:
     """Load MCP configuration from file."""
     try:
@@ -34,10 +52,27 @@ def save_mcp_config(config: MCPConfig) -> bool:
 
 
 def list_mcp_servers() -> List[Dict[str, Any]]:
-    """Get list of configured MCP servers with their status."""
-    config = load_mcp_config()
+    """Get list of configured MCP servers with their status.
+
+    Servers with platform-incompatible paths (e.g. Windows paths on macOS)
+    are annotated with a ``platform_blocked`` flag so the UI can explain why
+    they cannot be started.
+    """
+    try:
+        config = load_mcp_config()
+    except Exception as exc:
+        logger.error(f"Failed to load MCP config: {exc}")
+        return []
     servers = []
     for server in config.mcp_servers:
+        platform_blocked = not _path_usable_on_current_platform(
+            server.command or "", getattr(server, "args", []) or []
+        )
+        if platform_blocked:
+            logger.debug(
+                "MCP server %s has platform-specific paths — skipping on %s",
+                server.name, sys.platform,
+            )
         servers.append({
             "name": server.name,
             "description": server.description,
@@ -46,6 +81,7 @@ def list_mcp_servers() -> List[Dict[str, Any]]:
             "command": server.command,
             "action_set": server.resolved_action_set_name,
             "env": server.env,
+            "platform_blocked": platform_blocked,
         })
     return servers
 
diff --git a/app/tui/onboarding/widgets.py b/app/tui/onboarding/widgets.py
index 44116a68..e0621333 100644
--- a/app/tui/onboarding/widgets.py
+++ b/app/tui/onboarding/widgets.py
@@ -695,7 +695,19 @@ def _complete(self) -> None:
         self._handler.on_complete(cancelled=False)
         self.app.pop_screen()
 
+    def action_skip_step(self) -> None:
+        """Skip the current optional step (Ctrl+S)."""
+        step = self._handler.get_step(self._current_step)
+        if not step.required:
+            self._skip_step()
+
     def action_cancel(self) -> None:
         """Handle Escape key to cancel wizard."""
         self._handler.on_complete(cancelled=True)
         self.app.pop_screen()
+
+    def action_focus_nav(self) -> None:
+        """Focus the navigation bar (Tab)."""
+        nav = self.query_one("#nav-actions")
+        if hasattr(nav, 'focus'):
+            nav.focus()

From 75533eb15d16d758c894c9355c842efe51d34487 Mon Sep 17 00:00:00 2001
From: Vilius Vystartas <vilius.vystartas@gmail.com>
Date: Wed, 13 May 2026 12:36:32 +0100
Subject: [PATCH 10/10] =?UTF-8?q?fix:=20address=20review=20=E2=80=94=20BIN?=
 =?UTF-8?q?DINGS,=20platform=20warning=20visibility,=20browser=20Ctrl+S?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

1. Add BINDINGS to OnboardingWizardScreen so Ctrl+S/Escape route to
   action_skip_step/action_cancel (previously unreachable from keyboard).

2. Append platform-blocked warning to label instead of description
   so _build_multi_select renders it — it only shows opt.label, never
   opt.description.

3. Add useEffect keydown handler in OnboardingPage.tsx for Ctrl+S/Cmd+S
   to skip optional onboarding steps, matching TUI behavior. Prevents
   browser 'Save As' dialog interference.
---
 app/onboarding/interfaces/steps.py                |  2 +-
 app/tui/onboarding/widgets.py                     |  5 +++++
 .../src/pages/Onboarding/OnboardingPage.tsx       | 15 +++++++++++++++
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/app/onboarding/interfaces/steps.py b/app/onboarding/interfaces/steps.py
index a2c1ba67..212920de 100644
--- a/app/onboarding/interfaces/steps.py
+++ b/app/onboarding/interfaces/steps.py
@@ -516,7 +516,7 @@ def get_options(self) -> List[StepOption]:
                 # are incompatible with the current OS
                 desc = server.get("description", f"MCP server: {server['name']}")
                 if server.get("platform_blocked"):
-                    desc += " (Windows-only — requires setup on this OS)"
+                    label += " (⚠ Windows-only — requires setup on this OS)"
                 options.append(StepOption(
                     value=server["name"],
                     label=label,
diff --git a/app/tui/onboarding/widgets.py b/app/tui/onboarding/widgets.py
index e0621333..d2d5d9eb 100644
--- a/app/tui/onboarding/widgets.py
+++ b/app/tui/onboarding/widgets.py
@@ -286,6 +286,11 @@ class OnboardingWizardScreen(Screen):
 
     CSS = ONBOARDING_CSS
 
+    BINDINGS = [
+        ("ctrl+s", "skip_step", "Skip"),
+        ("escape", "cancel", "Cancel"),
+    ]
+
     def __init__(self, handler: "TUIHardOnboarding"):
         super().__init__()
         self._handler = handler
diff --git a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
index 88f3ff8c..e033cab1 100644
--- a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
@@ -490,6 +490,21 @@ export function OnboardingPage() {
   }, [onboardingStep, selectedValue, textValue, ollamaUrl, formValues, submitOnboardingStep])
 
   const handleSkip = useCallback(() => skipOnboardingStep(), [skipOnboardingStep])
+
+  // Ctrl+S to skip optional steps (matches TUI behavior)
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if ((e.ctrlKey || e.metaKey) && e.key === 's') {
+        if (onboardingStep && !onboardingStep.required) {
+          e.preventDefault()
+          skipOnboardingStep()
+        }
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [onboardingStep, skipOnboardingStep])
+
   const handleBack = useCallback(() => goBackOnboardingStep(), [goBackOnboardingStep])
 
   const isMultiSelect = onboardingStep?.name === 'mcp' || onboardingStep?.name === 'skills'